molsysmt.basic.convert#

molsysmt.basic.convert(molecular_system, to_form='molsysmt.MolSys', selection='all', structure_indices='all', syntax='MolSysMT', skip_digestion=False, **kwargs)[source]#

Converting a molecular system into another form or set of forms.

This function converts a molecular system from its current form into one target form, or into multiple target forms. Optionally, a subset of atoms and/or structures can be selected using selection and structure_indices before the conversion takes place.

Parameters:

  • molecular_system (molecular system) – Molecular system provided in any of the supported forms.

  • to_form (str or list of str, default 'molsysmt.MolSys') – Target form (or list of forms) for the conversion output. When a list is given, the function returns a list with one converted output per requested form. See Supported conversions.

  • selection (str, tuple, list or numpy.ndarray, default 'all') – Atom selection to apply prior to conversion. Either a 0-based index collection or a selection string parsed according to Selection syntaxes. The default ‘all’ includes the entire system.

  • structure_indices (int, tuple, list, numpy.ndarray or 'all', default 'all') – 0-based indices of the structures to include in the conversion. The default ‘all’ includes all structures.

  • syntax (str, default 'MolSysMT') – Selection syntax used when selection is a string. See Selection syntaxes.

  • skip_digestion (bool, default False) –

    Whether to skip MolSysMT’s internal argument digestion mechanism.

    MolSysMT includes a built-in digestion system that validates and normalizes function arguments. This process checks types, shapes, and values, and automatically adjusts them when possible to meet expected formats.

    Setting skip_digestion=True disables this process, which may improve performance in workflows where inputs are already validated. Use with caution: only set this to True if you are certain all input arguments are correct and consistent.

  • **kwargs – Additional keyword arguments forwarded to specific conversion handlers when required by a particular input-output path (e.g., topology or box handling options).

Returns:

The converted molecular system in the requested to_form. If to_form is a list, a list of converted systems is returned (one per target form).

Return type:

molecular system or list of molecular systems

Raises:

  • NotSupportedFormError – If the input system or the requested target form is not supported.

  • ArgumentError – If any of the input arguments is invalid or inconsistent.

Notes

  • Supported molecular-system forms are summarized in Forms.

  • Selection strings must follow one of the syntaxes described in Selection syntaxes.

See also

molsysmt.basic.select()

Select elements of a molecular system.

molsysmt.basic.get_form()

Retrieve the form of a molecular system.

molsysmt.basic.extract()

Extract a subset of a molecular system.

Examples

>>> import molsysmt as msm
>>> molsys_A = '2LAO'
>>> msm.get_form(molsys_A)
'string:pdb_id'
>>> molsys_B = msm.convert(molsys_A, to_form='openmm.Topology')
>>> msm.get_form(molsys_B)
'openmm.Topology'

Tutorial with more examples

See the following tutorial for a practical demonstration of how to use this function, along with additional examples: Convert.

Added in version 1.0.0.

On this page