molsysmt.basic package#

Submodules#

molsysmt.basic.add module#

molsysmt.basic.add.add(to_molecular_system, from_molecular_system, selection='all', structure_indices='all', keep_ids=True, in_place=True, syntax='MolSysMT', skip_digestion=False)[source]#

Adding elements from one molecular system into another.

This function adds selected elements from a source molecular system (from_molecular_system) into a target molecular system (to_molecular_system). Both systems must be compatible in terms of structure count: if the target system contains structural information (e.g., coordinates), the source must either match this number of structures or the user must explicitly provide structure_indices to specify which structures to use during the addition.

Parameters:

to_molecular_system (molecular system) – The target molecular system, in any of the supported forms. Elements from the source system will be added to this system by default. If in_place=False, a copy will be returned instead of modifying this object directly.
from_molecular_system (molecular system) – The source molecular system, in any of the supported forms. Selected elements from this system will be added to the target system.
selection (str, list, tuple, or numpy.ndarray, default='all') – Atoms to be added, specified as a list/tuple/array of 0-based atom indices, or as a string following one of the supported selection syntaxes.
structure_indices (str, list, tuple, or numpy.ndarray, default='all') – Indices (0-based) of structures in the source system to use for copying structural attributes (e.g., coordinates) of the selected atoms.
keep_ids (bool, default=True) – Whether to preserve the unique IDs of elements from the source system when adding them to the target system.
in_place (bool, default=True) – If True, modifies to_molecular_system in place. If False, returns a new modified copy, leaving the original unchanged.
syntax (str, default='MolSysMT') – Selection syntax to interpret the selection string. See Selection syntaxes for options.
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.

Returns:

If in_place=True, returns None and modifies to_molecular_system directly. If in_place=False, returns a new molecular system (same form as the input) with the added structures.

Return type:

molecular system or None

Raises:

NotSupportedFormError – If any molecular system is provided in an unsupported form.
ArgumentError – If any argument has an invalid or inconsistent value.

Notes

All forms listed in Forms are accepted for both source and target systems.
Selection strings must follow one of the syntaxes described in Selection syntaxes.

See also

molsysmt.basic.select(): Select elements from a molecular system.
molsysmt.basic.merge(): Merge multiple molecular systems into one.
molsysmt.basic.append_structures(): Append structures from one system to another.
molsysmt.basic.concatenate_structures(): Concatenate multiple systems along the structural dimension.

Examples

>>> import molsysmt as msm
>>> from molsysmt import systems
>>> molsys_A = msm.convert(systems['alanine dipeptide']['alanine_dipeptide.h5msm'])
>>> molsys_B = msm.convert(systems['valine dipeptide']['valine_dipeptide.h5msm'])
>>> msm.get(molsys_A, n_molecules=True)
1
>>> msm.add(molsys_A, molsys_B)
>>> msm.get(molsys_A, n_molecules=True)
2

Tutorial with more examples

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

Added in version 1.0.0.

molsysmt.basic.append_structures module#

molsysmt.basic.append_structures.append_structures(to_molecular_system, from_molecular_system, selection='all', structure_indices='all', syntax='MolSysMT', in_place=True, skip_digestion=False)[source]#

Appending structures from one molecular system into another.

This function appends structural information (coordinates, box dimensions, velocities, etc.) from a source molecular system (from_molecular_system) into a target molecular system (to_molecular_system). The result is a molecular system with additional structures (frames or conformations).

The appended structures must correspond to the same number of atoms as the target system. If the number of atoms differs, a selection of atoms from the source system must be provided using the selection argument. Only the structural attributes of the selected atoms will be appended, and they must match the number of atoms in the target system.

By default, the operation modifies the input molecular system in place. This behavior can be changed by setting in_place=False, in which case a new molecular system is returned.

Parameters:

to_molecular_system (molecular system) – Molecular system that will receive the new structures. Must be in one of the supported forms.
from_molecular_system (molecular system) – Molecular system providing the structures to append. Must be in one of the supported forms.
selection (str, list, tuple or numpy.ndarray, default 'all') – Selection of atoms from the source system whose structural attributes will be appended. Can be a list/array of 0-based atom indices, or a string using any of the supported selection syntaxes (Selection syntaxes). Only needed when the number of atoms differs between systems.
structure_indices (int, list, tuple, numpy.ndarray or 'all', default 'all') – 0-based indices of the structures in the source system to append.
syntax (str, default 'MolSysMT') – Selection syntax used if selection is a string. Must be one of the supported syntaxes in Selection syntaxes.
in_place (bool, default True) – If True, modifies to_molecular_system directly. If False, returns a new molecular system with the appended structures, leaving the original unmodified.
skip_digestion (bool, default False) – Whether to skip MolSysMT’s internal argument digestion mechanism. Use with caution.

Returns:

If in_place=True, returns None and modifies to_molecular_system directly. If in_place=False, returns a new molecular system (same form as the input) with the appended structures.

Return type:

molecular system or None

Raises:

NotSupportedFormError – If either molecular system is not provided in a supported form.
ArgumentError – If arguments are inconsistent or conditions are not met, such as mismatched atom counts without a proper selection.
SyntaxError – If the selection syntax is not recognized.

Notes

All forms listed in Forms are accepted for both source and target systems.
Selection strings must follow one of the syntaxes described in Selection syntaxes.

See also

molsysmt.basic.select(): Select atoms from a molecular system.
molsysmt.basic.concatenate_structures(): Concatenate structures from multiple molecular systems into one.
molsysmt.basic.add(): Adding elements from one molecular system into another.
molsysmt.basic.merge(): Merge multiple molecular systems into one.

Examples

>>> import molsysmt as msm
>>> from molsysmt import systems
>>> molsys_A = msm.convert(systems['alanine dipeptide']['alanine_dipeptide.h5msm'])
>>> molsys_B = msm.structure.translate(molsys_A, translation='[0.1, 0.1, 0.1] nanometers')
>>> msm.get(molsys_A, n_structures=True)
1
>>> msm.append_structures(molsys_A, molsys_B)
>>> msm.get(molsys_A, n_structures=True)
2

Tutorial with more examples

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

Added in version 1.0.0.

molsysmt.basic.are_multiple_molecular_systems module#

molsysmt.basic.are_multiple_molecular_systems.are_multiple_molecular_systems(molecular_systems)[source]#

Checking whether a container holds only valid molecular systems.

This function verifies that every element in the given container is a valid molecular system in one of the supported forms recognized by MolSysMT.

Parameters:: molecular_systems (list or tuple of molecular systems) – Container to check. Each item must be in one of the supported forms.
Returns:: True if (i) the input is a list or tuple, (ii) it is not empty, and (iii) all items are valid molecular systems. False otherwise.
Return type:: bool

Notes

Supported molecular-system forms are summarized in Forms.
See molsysmt.basic.is_a_molecular_system() to validate single objects.

See also

molsysmt.basic.is_a_molecular_system(): Check whether a single object is a valid molecular system.

Examples

>>> import molsysmt as msm
>>> from molsysmt import systems
>>> A = '2LAO'  # PDB id (supported form)
>>> B = 'AVLYAWPA'  # one-letter peptide sequence (supported form)
>>> C = systems['Trp-Cage']['1l2y.h5msm']  # demo system (supported form)
>>> msm.are_multiple_molecular_systems([A, B, C])
True
>>> msm.are_multiple_molecular_systems([])  # empty container -> False
False
>>> msm.are_multiple_molecular_systems(A)  # not a list/tuple
False

Tutorial with more examples

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

Added in version 1.0.0.

molsysmt.basic.compare module#

molsysmt.basic.compare.compare(molecular_system, molecular_system_2, selection='all', structure_indices='all', selection_2='all', structure_indices_2='all', syntax='MolSysMT', rule='equal', output_type='boolean', attribute_type=None, include_none=False, skip_digestion=False, **kwargs)[source]#

Comparing two molecular systems or selected subsets of them.

This function compares attributes of two molecular systems (or their selected subsets) using either equality ('equal') or containment ('in') rules. The scope of the comparison can be restricted with selection/structure_indices for the first system, and selection_2/structure_indices_2 for the second.

If no explicit attributes are provided via keyword arguments, a default set of attributes (or those filtered by attribute_type) is considered.

Parameters:

molecular_system (molecular system) – First molecular system to compare. Accepted in any of the supported forms.
molecular_system_2 (molecular system) – Second molecular system to compare. Accepted in any of the supported forms.
selection (str, list, tuple or numpy.ndarray, default 'all') – Elements to include from the first system. Either a selection string following the supported syntaxes or a 0-based sequence of atom indices.
structure_indices (int, list, tuple, numpy.ndarray or 'all', default 'all') – 0-based indices of structures to include from the first system.
selection_2 (str, list, tuple or numpy.ndarray, default 'all') – Elements to include from the second system. Same semantics as selection.
structure_indices_2 (int, list, tuple, numpy.ndarray or 'all', default 'all') – 0-based indices of structures to include from the second system.
syntax (str, default 'MolSysMT') – Selection syntax used when selection/selection_2 are strings. See Selection syntaxes.
rule ({'equal', 'in'}, default 'equal') – Comparison rule: * 'equal' — checks that values are numerically or exactly identical (see Notes). * 'in' — checks that values from the first system are contained in the second
output_type ({'boolean', 'dictionary'}, default 'boolean') – Output format: * 'boolean' — a single True/False indicating overall success. * 'dictionary' — a per-attribute dictionary with individual results.
attribute_type ({'topological', 'structural', 'mechanical', 'all', None}, default None) – Attribute subset to compare. If None, attributes specified in **kwargs are used (if any). Otherwise, a default list for the given subset is applied.
include_none (bool, default False) – Whether to include attributes with None values when inferring comparable attributes.
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 – Attribute names to compare as keyword booleans indicating the expected outcome under rule: * True — the rule should hold (e.g., equality expected). * False — the negation should hold (e.g., inequality expected).

Returns:

True/False when output_type=’boolean’, or a dictionary mapping attribute names to booleans when output_type=’dictionary’.

Return type:

bool or dict

Raises:

NotSupportedFormError – If any molecular system is provided in an unsupported form.
ArgumentError – If arguments are inconsistent or invalid.

Notes

Supported forms are summarized in Forms.
Selection syntaxes are described in Selection syntaxes.

See also

molsysmt.basic.select(): Select elements of a molecular system.
molsysmt.get(): Retrieve attribute values.
molsysmt.info(): Display a concise system summary.

Examples

>>> import molsysmt as msm
>>> from molsysmt import systems
>>> A = msm.convert(systems['T4 lysozyme L99A']['181l.h5msm'])
>>> B = msm.convert(systems['T4 lysozyme L99A']['181l.h5msm'], selection='molecule_type=="protein"')
>>> msm.compare(A, B)
False
>>> msm.compare(A, B, box=True)
True
>>> msm.compare(A, B, n_groups=False)
True
>>> msm.compare(A, B, selection='molecule_type=="protein"', n_groups=True)
True

Tutorial with more examples

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

Added in version 1.0.0.

molsysmt.basic.concatenate_structures module#

molsysmt.basic.concatenate_structures.concatenate_structures(molecular_systems, selections='all', structure_indices='all', to_form=None, syntax='MolSysMT', skip_digestion=False)[source]#

Concatenate structures from a list of molecular systems into a single molecular system.

This function collects structures from several molecular systems and returns a new molecular system whose structural dimension is the concatenation of the selected structures. All participating systems must be aligned in atom count and ordering over the chosen selections; use selections to provide per-system matching subsets when needed. Optionally, select specific structures from each input with structure_indices.

Parameters:

molecular_systems (list of molecular systems) – List of input molecular systems in any of the supported forms. Structures will be taken from these systems.
selections (list of (str, tuple, list, numpy.ndarray) or 'all', default 'all') – Atom selections to extract structures from each molecular system. Provide a single value (applied to all systems) or a list of selections with the same length as molecular_systems. Each entry can be a 0-based index collection or a selection string parsed according to Selection syntaxes.
structure_indices (list of (int, tuple, list, numpy.ndarray) or 'all', default 'all') – Structure indices (0-based) per system to include. Provide a single value (applied to all systems) or a list matching molecular_systems in length.
to_form (str or None, default None) – Output form for the resulting molecular system. If None, the form is inherited from the first input system.
syntax (str, default 'MolSysMT') – Selection syntax used when entries of selections are strings. 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.

Returns:

New molecular system containing the concatenated structures. The topology is inherited from the first item in molecular_systems. The output form is controlled by to_form (or inherited if None).

Return type:

molecular system

Raises:

NotSupportedFormError – If any input system is provided in an unsupported form.
ArgumentError – If input values are invalid or inconsistent.

Notes

Supported molecular-system forms are summarized in Forms.
Selection strings must follow one of the syntaxes described in Selection syntaxes.
All systems must be consistent in number and ordering of atoms over the final selections. Use selections to align subsets when needed.
Structural attributes concatenated include coordinates, velocities, box, time (when available in the inputs).

See also

molsysmt.basic.select(): Select elements from a molecular system.
molsysmt.basic.append_structures(): Append structures from one molecular system to another.

Examples

>>> import molsysmt as msm
>>> from molsysmt import systems
>>> A = msm.convert(systems['alanine dipeptide']['alanine_dipeptide.h5msm'])
>>> B = msm.structure.translate(A, translation='[0.1, 0.1, 0.1] nanometers')
>>> C = msm.concatenate_structures([A, B])
>>> msm.get(C, n_structures=True)
2

Tutorial with more examples

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

Added in version 1.0.0.

molsysmt.basic.contains module#

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

Checking whether a molecular system contains specific elements or satisfies conditions.

This function returns a boolean indicating whether the molecular system, or a selected subset of it, satisfies a set of conditions expressed via keyword arguments. Each keyword corresponds to an attribute to check, and its value specifies the condition to apply.

Parameters:

molecular_system (molecular system) – Molecular system to analyze, in any of the supported forms.
selection (str, tuple, list or numpy.ndarray, default 'all') – Subset of atoms the conditions are applied to. Either a 0-based index collection or a selection string parsed according to Selection syntaxes. The default ‘all’ applies the conditions to the entire system.
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 –
Attribute conditions expressed as attribute=value pairs, where the value can be: - True: the attribute must be present and non-zero/non-empty on the selected subset. - False: the attribute must be absent or zero/empty on the selected subset. - int: the attribute (interpreted as a count/size) must be greater than or equal to

the given integer (threshold).

Returns:

True if all specified conditions are satisfied by the selected subset of the system; otherwise, False.

Return type:

bool

Raises:

NotSupportedFormError – If the molecular system is not in a supported form.
ArgumentError – If input arguments are 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 from a molecular system.
molsysmt.basic.is_composed_of(): Check if a molecular system is composed of specific types of elements.

Examples

>>> import molsysmt as msm
>>> molsys = msm.systems['T4 lysozyme L99A']['181l.h5msm']
>>> msm.contains(molsys, waters=True, ions=True)
True
>>> msm.contains(molsys, selection='atom_name=="CL"')
True
>>> msm.contains(molsys, selection='molecule_type!="water"', waters=True)
False

User guide

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

Added in version 1.0.0.

molsysmt.basic.convert module#

molsysmt.basic.convert.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.

molsysmt.basic.copy module#

molsysmt.basic.copy.copy(molecular_system, output_filename=None, skip_digestion=False)[source]#

Creating an independent copy of a molecular system.

This function returns a deep copy of the input molecular system, fully detached from the original. If the input is in a file-based form and output_filename is provided, the copy is written to a new file using the corresponding form handler.

Parameters:

molecular_system (molecular system) – Molecular system to duplicate, in any of the supported forms. A list/tuple of molecular systems is also accepted, in which case a list is returned.
output_filename (str, optional) – Path for the output file when copying a file-based form. If omitted, the copy is returned using a temporary filename.
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.

Returns:

A new molecular system (or list of systems if the input is a sequence), independent of the original and in the same form as the input. When output_filename is given for a file-based form, the returned object follows the form-specific handler’s semantics (typically the path or a file-form handle).

Return type:

molecular system or list of molecular systems

Raises:

NotSupportedFormError – If the input molecular system has an unsupported form.
ArgumentError – If input arguments are invalid or inconsistent.

Notes

Supported molecular-system forms are summarized in Forms.

See also

molsysmt.basic.convert(): Convert a molecular system into another form.

Examples

>>> import molsysmt as msm
>>> molsys_A = msm.convert(msm.systems['T4 lysozyme L99A']['181l.h5msm'])
>>> molsys_B = msm.copy(molsys_A)
>>> msm.compare(molsys_A, molsys_B, rule='equal')
True
>>> id(molsys_A) == id(molsys_B)
False

Tutorial with more examples

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

Added in version 1.0.0.

molsysmt.basic.extract module#

molsysmt.basic.extract.extract(molecular_system, selection='all', structure_indices='all', to_form=None, output_filename=None, copy_if_all=True, syntax='MolSysMT', skip_digestion=False)[source]#

Extracting a subset of atoms and/or structures from a molecular system.

This function creates a new molecular system containing only the elements and structures specified by selection and structure_indices. Optionally, the result can be returned in another form using to_form.

Parameters:

molecular_system (molecular system) – Molecular system to extract from, in any of the supported forms.
selection (str, tuple, list or numpy.ndarray, default 'all') – Subset of atoms to extract. Either a 0-based index collection or a selection string parsed according to Selection syntaxes. The default ‘all’ selects all atoms.
structure_indices (int, tuple, list, numpy.ndarray or 'all', default 'all') – 0-based indices of the structures to extract. The default ‘all’ includes all structures.
to_form (str or None, default None) – Target form of the output system. If None, the output form matches the input system. See Supported conversions.
output_filename (str or None, optional) – Optional output target used by certain form handlers. When applicable, the underlying conversion/extraction backend may write to this location.
copy_if_all (bool, default True) – If both selection and structure_indices equal ‘all’: * True: return an independent copy of the system. * False: return a view/reference to the original data, if the backend supports it.
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.

Returns:

A new molecular system containing only the selected atoms and structures, in to_form if provided, otherwise in the input form.

Return type:

molecular system

Raises:

NotSupportedFormError – If the input or requested output form is not supported.
ArgumentError – If input arguments are 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 from a molecular system without extracting them.
molsysmt.basic.copy(): Create an independent copy of a molecular system.
molsysmt.basic.convert(): Convert a molecular system into a different form.

Examples

>>> import molsysmt as msm
>>> from molsysmt import systems
>>> molsys_A = msm.convert(systems['T4 lysozyme L99A']['181l.h5msm'])
>>> molsys_B = msm.extract(molsys_A, selection='molecule_type=="protein"')
>>> msm.contains(molsys_A, waters=True)
True
>>> msm.contains(molsys_B, waters=True)
False

Tutorial with more examples

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

Added in version 1.0.0.

molsysmt.basic.get module#

molsysmt.basic.get.get(molecular_system, element='system', selection='all', structure_indices='all', mask=None, syntax='MolSysMT', get_missing_bonds=True, output_type='values', skip_digestion=False, **kwargs)[source]#

Retrieving attribute values from a molecular system.

This function retrieves values of one or more attributes from a molecular system (or from a selected subset of it), optionally specifying the hierarchical element level. Attributes to be returned are indicated via keyword flags in **kwargs (e.g., n_atoms=True, coordinates=True).

Parameters:

molecular_system (molecular system) – Molecular system to query, in any of the supported forms.
element ({'atom', 'group', 'component', 'molecule', 'chain', 'entity', 'bond', 'system'}, default 'system') – Element level at which attributes are retrieved.
selection (int, tuple, list, numpy.ndarray or str, default 'all') – Subset of elements (interpreted at the level set by element) to use when retrieving attributes. Either a 0-based index collection or a selection string parsed according to Selection syntaxes.
structure_indices (int, tuple, list, numpy.ndarray or 'all', default 'all') – 0-based indices of structures to include in the query. Required for structural attributes (e.g., coordinates, box, time).
mask (array-like of bool, optional) – Boolean mask to apply after selection and structure filtering. Must match the shape of the selected elements.
syntax (str, default 'MolSysMT') – Selection syntax used when selection is a string. See Selection syntaxes.
get_missing_bonds (bool, default False) – Whether to infer and return bond information on the fly when bond-related attributes are requested and the input form lacks explicit connectivity. The inference uses the form backend’s heuristics (distance/chemistry-aware thresholds).
output_type ({'values', 'dictionary'}, default 'values') –
Output format: - ``value` — convenience mode:
- if exactly one attribute is requested, return its value directly;
- if multiple attributes are requested, return a tuple of values following the order in which the attributes were provided in **kwargs.
- 'dictionary' — return a dictionary mapping attribute names to values.
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 – Attribute flags selecting which values to retrieve (e.g., n_atoms=True, coordinates=True, time=True, box=True, etc.). Only attributes flagged as True are returned.

Returns:

Depending on output_type: - If output_type == 'values' and a single attribute is requested: the attribute value. This value can be None if the attribute is not found in the system. - If output_type == 'values' and multiple attributes are requested: a tuple with values

in the order given by **kwargs.

If output_type == 'dictionary': a dictionary {attribute_name: value}.

Return type:

Any or tuple or dict or None

Raises:

NotSupportedFormError – If the molecular system has an unsupported form.
ArgumentError – If any input argument 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 from a molecular system.
molsysmt.basic.get_attributes(): Get the list of available attributes for a molecular system.

Examples

>>> import molsysmt as msm
>>> from molsysmt import systems
>>> molsys = systems['T4 lysozyme L99A']['181l.h5msm']
>>> msm.get(molsys, element='group', selection=[10,11,12], n_atoms=True)
[9, 4, 8]
>>> msm.get(molsys, element='molecule', selection='molecule_type=="water"', n_molecules=True)
136
>>> msm.get(molsys, element='bond', selection=[0,1,2,3,4], bonded_atoms=True)
[0, 1, 2, 3, 4, 8]

Tutorial with more examples

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

Added in version 1.0.0.

molsysmt.basic.get_attributes module#

molsysmt.basic.get_attributes.get_attributes(molecular_system, include_none=False, output_type='dictionary', skip_digestion=False)[source]#

Retrieving available attributes from a molecular system.

This function inspects the input molecular system and reports which attributes are available according to MolSysMT’s attribute registry. The result can be returned either as a dictionary mapping attribute names to booleans or as a list containing only the present attributes.

Parameters:

molecular_system (molecular system) – Molecular system to analyze, in any of the supported forms.
include_none (bool, default False) – Whether to consider attributes with value None as present when probing availability. If True, attributes that exist but currently hold None will be marked as present.
output_type ({'dictionary', 'list'}, default 'dictionary') – Format of the returned result. If 'dictionary', returns all supported attributes as keys with boolean values indicating presence. If 'list', returns only the names of attributes present in the molecular system.
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.

Returns:

If output_type == 'dictionary': dictionary with attribute names as keys and booleans as values indicating availability. If output_type == 'list': list with the names of attributes present.

Return type:

dict or list

Raises:

NotSupportedFormError – If the input molecular system has an unsupported form.
ArgumentError – If input arguments are 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.has_attribute(): Check whether a specific attribute exists in a molecular system.
molsysmt.basic.get_form(): Retrieve the form of a molecular system.
molsysmt.basic.get(): Retrieve attribute values from a molecular system.

Examples

>>> import molsysmt as msm
>>> molsys = msm.convert(msm.systems['T4 lysozyme L99A']['181l.h5msm'])
>>> attributes = msm.get_attributes(molsys)
>>> attributes['box']
True
>>> attributes['forcefield']
False
>>> output = msm.get_attributes(molsys, output_type='list')
>>> isinstance(output, list)
True
>>> 'molecule_id' in output
True
>>> 'forcefield' in output
False

Tutorial with more examples

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

Added in version 1.0.0.

molsysmt.basic.get_form module#

molsysmt.basic.get_form.get_form(molecular_system)[source]#

Retrieving the form of a molecular system.

This function returns a string that identifies the form of the input molecular system, such as 'file:pdb', 'openmm.Topology', 'string:pdb_id', or any other supported form.

Parameters:: molecular_system (molecular system) – Molecular system to analyze, in any of the supported forms.
Returns:: Name of the form of the input molecular system.
Return type:: str
Raises:: NotSupportedFormError – If the input molecular system has a form that is not supported.

Notes

See Forms for a full list of supported forms.

See also

molsysmt.convert(): Convert a molecular system into a different form.

Examples

>>> import molsysmt as msm
>>> from molsysmt import systems
>>> molsys_A = systems['T4 lysozyme L99A']['181l.h5msm']
>>> msm.get_form(molsys_A)
'file:h5msm'
>>> molsys_B = msm.convert(molsys_A, to_form='molsysmt.MolSys')
>>> msm.get_form(molsys_B)
'molsysmt.MolSys'
>>> molsys_C = msm.convert(molsys_B, to_form='openmm.Topology')
>>> msm.get_form(molsys_C)
'openmm.Topology'

Tutorial with more examples

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

Added in version 1.0.0.

molsysmt.basic.get_label module#

molsysmt.basic.get_label.get_label(molecular_system, element='atom', selection='all', string='{name}-{id}@{index}', syntax='MolSysMT', skip_digestion=False)[source]#

Generating label strings for selected elements of a molecular system.

This function builds one or more human-readable labels for elements of a molecular system, based on the requested element level and an f-string-like string pattern. Generic placeholders ({name}, {id}, {index}) are automatically mapped to the appropriate attribute names for the chosen element (e.g., atom_name, group_id). Explicit attribute names (e.g., molecule_name) are also allowed regardless of element.

Parameters:

molecular_system (molecular system) – Molecular system to analyze, in any of the supported forms.
element ({'atom', 'group', 'component', 'molecule', 'chain', 'entity', 'system'}, default 'atom') – Level of the molecular hierarchy for which labels are generated.
selection (int, tuple, list, numpy.ndarray or str, default 'all') – Selection of elements of the specified type. It can be a 0-based index collection or a selection string parsed according to Selection syntaxes. The selection is interpreted at the level given by element.
string (str, default ‘{name}-{id}@{index}’) – Pattern template used to construct the labels. It must be a valid str.format() template. Supported generic placeholders are {name}, {id}, {index} (mapped to the element’s attribute names). Additionally, explicit attribute names such as atom_name, group_id, molecule_id, etc., can be used directly.
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.

Returns:

A single label string if only one element is selected; otherwise, a list of label strings in the order of the selection.

Return type:

str or list of str

Raises:

NotSupportedFormError – If the input molecular system has an unsupported form.
ArgumentError – If input arguments are 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 from a molecular system.
molsysmt.basic.get(): Retrieve values of attributes for selected elements.

Examples

>>> import molsysmt as msm
>>> molsys = msm.convert(msm.systems['T4 lysozyme L99A']['181l.h5msm'])
>>> msm.get_label(molsys, element='group', selection=[10, 12, 14],
...               string='{group_name}{group_id}/{entity_name}')
['GLU11/T4 LYSOZYME', 'LEU13/T4 LYSOZYME', 'LEU15/T4 LYSOZYME']

Tutorial with more examples

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

Added in version 1.0.0.

molsysmt.basic.has_attribute module#

molsysmt.basic.has_attribute.has_attribute(molecular_system, attribute, include_none=False, skip_digestion=False)[source]#

Checking whether a molecular system has a specific attribute.

This function returns True if the given attribute is available for the input molecular system, and False otherwise. Availability depends on the form-specific backend and the global attribute registry.

Parameters:

molecular_system (molecular system) – Molecular system to analyze, in any of the supported forms.
attribute (str) – Name of the attribute to check.
include_none (bool, default False) – Whether to consider attributes currently holding None as available. If True, an attribute that exists but is None will return True.
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.

Returns:

True if the attribute is available in the molecular system, False otherwise.

Return type:

bool

Raises:

NotSupportedFormError – If the molecular system has a form that is not supported.
ArgumentError – If input arguments are 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.get_attributes(): Retrieve the list of available attributes in a molecular system.
molsysmt.basic.get(): Retrieve values of specific attributes from a molecular system.

Examples

>>> import molsysmt as msm
>>> from molsysmt import systems
>>> molsys = msm.convert(systems['T4 lysozyme L99A']['181l.h5msm'])
>>> msm.has_attribute(molsys, 'box')
True
>>> msm.has_attribute(molsys, 'forcefield')
False

Tutorial with more examples

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

Added in version 1.0.0.

molsysmt.basic.info module#

molsysmt.basic.info.info(molecular_system, element='system', selection='all', syntax='MolSysMT', skip_digestion=False)[source]#

Display a summary table of a molecular system or selected elements.

This function produces a formatted summary table (as a Pandas Styler) with key attributes of a molecular system, either for the whole system or for a given element level and selection. The columns returned depend on the chosen element and on the attributes available in the underlying form(s).

Parameters:

molecular_system (molecular system) – Molecular system to analyze, in any of the supported forms.
element ({'atom', 'group', 'component', 'molecule', 'chain', 'entity', 'system'}, default 'system') – Hierarchical level for which the summary is generated.
selection (int, tuple, list, numpy.ndarray or str, default 'all') – Selection of elements at the specified level. It can be a 0-based index collection or a selection string parsed according to Selection syntaxes.
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.

Returns:

A Pandas Styler wrapping a DataFrame with the summary. The exact columns depend on element and on the attributes exposed by the input form(s).

Return type:

pandas.io.formats.style.Styler

Raises:

NotSupportedFormError – If the molecular system has an unsupported form.
ArgumentError – If any input argument 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.
The function hides the row index for readability using Pandas’ Styler API; you can access the underlying DataFrame via the .data attribute (depending on your Pandas version) or by rebuilding it from the original values if needed.

See also

molsysmt.basic.select(): Select elements from a molecular system.
molsysmt.basic.get(): Retrieve values of attributes from a molecular system.
molsysmt.basic.get_form(): Retrieve the form of a molecular system.

Examples

>>> import molsysmt as msm
>>> from molsysmt import systems
>>> molsys = msm.convert(systems['T4 lysozyme L99A']['181l.h5msm'])
>>> print(msm.info(molsys, element='entity').to_string())
index  name                       type     n atoms  n groups  n components  n chains  n molecules
0      T4 LYSOZYME                protein  1289     162       1             1         1
1      CHLORIDE ION               unknown  2        2         2             2         2
2      2-HYDROXYETHYL DISULFIDE   unknown  8        1         1             1         1
3      BENZENE                    unknown  6        1         1             1         1
4      water                      water    136      136       136           1         136
>>> # If you are working in a Jupyter notebook, you can simply run:
>>> # msm.info(molsys, element='entity')
>>> # And the table will be displayed in a nicely formatted style by Pandas.

Tutorial with more examples

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

Added in version 1.0.0.

molsysmt.basic.is_a_molecular_system module#

molsysmt.basic.is_a_molecular_system.is_a_molecular_system(molecular_system)[source]#

Verifying whether the input is a single valid molecular system.

This function checks whether molecular_system represents one valid molecular system. The input may be a single item (any supported form) or a list/tuple combining compatible items (e.g., topology + coordinates files). For sequence inputs, validity requires internal consistency such as a matching number of atoms across all items.

Parameters:: molecular_system (molecular system) – Tentative molecular system, provided as a single item or a list/tuple of items in any of the supported forms.
Returns:: True if the input encodes a single valid molecular system, False otherwise.
Return type:: bool

Notes

Supported molecular-system forms are summarized in Forms.

See also

molsysmt.basic.are_multiple_molecular_systems(): Check whether each item in a container is a valid molecular system.
molsysmt.basic.get_form(): Retrieve the form of a molecular system.

Examples

>>> import molsysmt as msm
>>> from molsysmt import systems
>>> topology = systems['pentalanine']['pentalanine.prmtop']
>>> structures_A = systems['pentalanine']['pentalanine.inpcrd']
>>> structures_B = systems['chicken villin HP35']['traj_chicken_villin_HP35_solvated.dcd']
>>> msm.basic.is_a_molecular_system([topology, structures_A])
True
>>> msm.basic.is_a_molecular_system([topology, structures_B])
False

Tutorial with more examples

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

Added in version 1.0.0.

molsysmt.basic.is_composed_of module#

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

Checking whether a molecular system is composed exclusively of specific elements.

This function returns True if the selected portion of the molecular system is entirely composed of the requested element types and counts provided via keyword conditions in **kwargs; otherwise it returns False.

Parameters:

molecular_system (molecular system) – Molecular system to analyze, provided in any of the supported forms.
selection (int, tuple, list, numpy.ndarray or str, default 'all') – Subset of the molecular system to check. It can be a 0-based index collection or a selection string following Selection syntaxes. If ‘all’, the entire molecular system is considered.
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 – Composition conditions as name=value pairs. Accepted names include type counters (n_ions, n_waters, n_small_molecules, n_peptides, n_proteins, n_dnas, n_rnas, n_lipids, n_polysaccharides, n_saccharides, …) and element counters (n_atoms, n_groups, n_components, n_molecules, n_chains, n_entities, …). Values are interpreted as: - True → the count must be > 0 (presence required) - False → the count must be == 0 (absence required) - int → the count must be exactly that integer

Returns:

True if all provided conditions are satisfied by the selection; False otherwise.

Return type:

bool

Raises:

NotSupportedFormError – If the molecular system has an unsupported form.
ArgumentError – If any argument 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 specific elements from a molecular system.
molsysmt.basic.contains(): Check whether certain elements or attributes are present in a molecular system.

Examples

>>> import molsysmt as msm
>>> from molsysmt import systems
>>> molsys = systems['T4 lysozyme L99A']['181l.h5msm']
>>> msm.basic.is_composed_of(molsys, waters=True, ions=True)
False
>>> msm.basic.is_composed_of(molsys, waters=True, ions=True, small_molecules=2, proteins=1)
True
>>> msm.basic.is_composed_of(molsys, n_chains=6)
True

Tutorial with more examples

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

Added in version 1.0.0.

molsysmt.basic.iterator module#

class molsysmt.basic.iterator.Iterator(molecular_system, element='atom', selection='all', structure_indices=None, start=0, stop=None, step=1, chunk=1, syntax='MolSysMT', output_type='values', output_form='molsysmt.MolSys', skip_digestion=False, **kwargs)[source]#

Bases: object

Iterating over topological or structural attributes of a molecular system.

This class provides a unified interface to iterate over selected attributes of a molecular system — either topological (e.g., atom_name, group_index) or structural (e.g., coordinates, box, time). Iteration proceeds over elements (atoms, groups, molecules, etc.) or over structures depending on the requested attributes. When no attributes are requested, each iteration yields a molecular system with updated structural data (trajectory-like behavior).

Parameters:: __init__) ((see)

molecular_system#

Molecular system from which attribute values are extracted.

Type:: molecular system

element#

Hierarchical level over which iteration is performed.

Type:: {‘atom’, ‘group’, ‘component’, ‘molecule’, ‘chain’, ‘entity’, ‘system’}

indices#

Element indices used for iteration (as resolved from selection).

Type:: int, list, tuple or numpy.ndarray

structure_indices#

Structure indices used when iterating over structural attributes.

Type:: int, list, tuple or numpy.ndarray

start, stop, step, chunk

Control parameters defining the iteration window and stride.

Type:: int

iterator_index#

Current iteration position.

Type:: int

arguments#

Attribute names returned on each iteration.

Type:: list of str

Notes

Supported molecular-system forms are summarized in Forms.
Selection strings must follow one of the syntaxes described in Selection syntaxes.
This class implements the Python iterator protocol: __iter__() returns self, and __next__() returns the next item or raises StopIteration.
If no attributes are requested, the iterator returns a molecular system per iteration

with updated structural attributes.

See also

molsysmt.basic.select(): Select elements from a molecular system.
molsysmt.basic.get(): Retrieve values of attributes from a molecular system.

Examples

>>> import molsysmt as msm
>>> from molsysmt import systems
>>> molsys = systems['chicken villin HP35']['1vii.bcif.gz']
>>> it1 = msm.Iterator(molsys, element='group', selection='molecule_type=="peptide"',
...                    start=10, stop=20, step=2, group_index=True, group_name=True)
>>> for group_index, group_name in it1:
...     pass # replace with desired operations
>>> molsys = systems['pentalanine']['traj_pentalanine.h5']
>>> it2 = msm.Iterator(molsys, selection='group_index==3 and atom_name=="CA"',
...                    structure_indices=[100, 110, 120],
...                    time=True, coordinates=True)
>>> for time, coordinates in it2:
...     pass # replace with desired operations

Tutorial with more examples

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

Added in version 1.0.0.

__iter__()[source]#

Returning the iterator object.

This method returns self to enable usage in for loops and other iteration contexts.

Returns:: The iterator instance itself.
Return type:: molsysmt.basic.Iterator

__next__()[source]#

Producing the next item in the iteration.

If attributes were requested in **kwargs, this method returns either a tuple of values (output_type=’values’) or a dictionary of {attribute_name: value} (output_type=’dictionary’). If no attributes were requested, it returns a molecular system in output_form whose structural data (structure_id, time, coordinates, box) are updated to the current iteration.

Returns:: Tuple, single value, dictionary, or a molecular system depending on the initialization parameters (see above).
Return type:: Any
Raises:: StopIteration – When no further items are available.

molsysmt.basic.merge module#

molsysmt.basic.merge.merge(molecular_systems, selections='all', structure_indices='all', keep_ids=True, syntax='MolSysMT', to_form=None, skip_digestion=False)[source]#

Merging elements from multiple molecular systems into a new one.

This function builds a new molecular system by merging selected elements from several input systems. All inputs must be compatible in their number of structures; otherwise, structure_indices must be provided to align the frames that will be merged. You can also provide per-system atom selections via selections. The output form can be set with to_form (defaults to the first system’s form).

Parameters:

molecular_systems (list of molecular systems) – Input systems, each in one of the supported forms.
selections (list of (tuple, list, numpy.ndarray or str) or 'all', default 'all') – Atom selections for each input system. A single value applies to all systems; otherwise provide a list with the same length as molecular_systems. Selection strings follow Selection syntaxes. If ‘all’, all atoms from every system are included.
structure_indices (list of (int, tuple, list, numpy.ndarray) or 'all', default 'all') – 0-based indices of the structures to include from each system. A single value applies to all systems; otherwise provide a list matching molecular_systems.
keep_ids (bool, default True) – Whether to preserve original ids (atom, group, molecule) from the inputs. If False, ids are reassigned in the merged system.
syntax (str, default 'MolSysMT') – Selection syntax used when any entry in selections is a string. See Selection syntaxes.
to_form (str or None, default None) – Output form of the merged molecular system. If None, the output molecular system inherits the first input system’s form.
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.

Returns:

New molecular system composed of the selected elements from the inputs. Its form is controlled by to_form (or inherited from the first input when None).

Return type:

molecular system

Raises:

NotSupportedFormError – If any input molecular system has an unsupported form.
ArgumentError – If input arguments are invalid or inconsistent in length or compatibility.

Notes

Supported molecular-system forms are summarized in Forms.
Selection strings must follow one of the syntaxes described in Selection syntaxes.
All input systems must be aligned in number of structures or explicitly aligned via structure_indices. Internal conversions are performed when the input forms differ from the chosen to_form.

See also

molsysmt.basic.select(): Select elements from a molecular system.
molsysmt.basic.add(): Add elements from one system to another.
molsysmt.basic.append_structures(): Append structures from one system to another.
molsysmt.basic.concatenate_structures(): Concatenate structures across multiple molecular systems.

Examples

>>> import molsysmt as msm
>>> molsys = msm.systems['alanine dipeptide']['alanine_dipeptide.h5msm']
>>> molsys_A = msm.convert(molsys)
>>> molsys_B = msm.structure.translate(molsys_A, translation='[0.1, 0.1, 0.1] nanometers')
>>> molsys_merged = msm.basic.merge([molsys_A, molsys_B])
>>> msm.basic.get(molsys_merged, n_peptides=True)
2

Tutorial with more examples

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

Added in version 1.0.0.

molsysmt.basic.remove module#

molsysmt.basic.remove.remove(molecular_system, selection=None, structure_indices=None, to_form=None, syntax='MolSysMT', skip_digestion=False)[source]#

Removing atoms or structures from a molecular system.

This function returns a new molecular system after removing the atoms and/or structures specified via selection and structure_indices. If selection is None, no atoms are removed. If structure_indices is None, no structures are removed. Optionally, the resulting system can be returned in a different form with to_form.

Parameters:

molecular_system (molecular system) – Molecular system provided in any of the supported forms.
selection (str, tuple, list or numpy.ndarray, optional) – Atoms to remove, as a 0-based index collection or a selection string parsed according to Selection syntaxes. If ‘all’, all atoms are removed. If None, no atoms are removed.
structure_indices (int, tuple, list, numpy.ndarray or 'all', optional) – 0-based indices of structures to remove. If ‘all’, all frames are removed. If None, no structures are removed.
to_form (str, optional) – Output form of the resulting molecular system. If omitted, the output form matches the input system.
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.

Returns:

A new molecular system with the selected atoms and/or structures removed. The form of the returned system is either specified by to_form or inferred from the input.

Return type:

molecular system

Raises:

NotSupportedFormError – If the molecular system is provided in an unsupported form.
ArgumentError – If the selection or structure_indices are invalid or incompatible with the system.

Notes

Supported molecular-system forms are summarized in Forms.
Selection strings must follow one of the syntaxes described in Selection syntaxes.
Removal is implemented by selecting the complementary indices and delegating to molsysmt.basic.extract(), minimizing data copies when possible.

See also

molsysmt.select(): Select atoms or structures from a molecular system.
molsysmt.basic.extract(): Extract a subset of atoms/structures into a new molecular system.

Examples

>>> import molsysmt as msm
>>> system = msm.convert('1B3T')
>>> msm.get(system, n_chains=True)
8
>>> new_system = msm.remove(system, selection='chain_id=="A" or chain_id=="B"')
>>> msm.get(new_system, n_chains=True)
6

Tutorial with more examples

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

Added in version 1.0.0.

molsysmt.basic.select module#

molsysmt.basic.select.select(molecular_system, selection='all', structure_indices='all', element='atom', mask=None, syntax='MolSysMT', to_syntax=None, skip_digestion=False)[source]#

Selecting elements from a molecular system.

This function returns the indices of elements that match a selection query (unless to_syntax is used). The selection can be based on topological or structural attributes and applied at different hierarchical levels such as atoms, groups, components, molecules, chains or entities. If to_syntax is specified, the function returns a translated selection string instead of indices.

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

Parameters:

molecular_system (molecular system) – Molecular system to be queried. It can be in any of the supported forms.
selection (str, tuple, list or numpy.ndarray, default='all') – Selection query defining the elements to be selected. It can be: - A string with a selection expression (e.g. “group_name in [‘ALA’, ‘GLY’]”) - A list/array of 0-based indices - A nested list of multiple queries (for grouped selections)
structure_indices (str, tuple, list or numpy.ndarray, default='all') – 0-based indices of the structures over which the selection is applied.
element ({'atom', 'group', 'component', 'molecule', 'chain', 'entity'}, default='atom') – Structural level on which the selection is applied. Returned indices correspond to this level.
mask (str, tuple, list or numpy.ndarray, optional) – Optional subset of elements to restrict the selection. It is applied as an intersection filter.
syntax (str, default='MolSysMT') – Syntax used to interpret the selection string. See Selection syntaxes for available syntaxes.
to_syntax (str, optional) – If provided, returns the translated selection query string in the target syntax instead of indices.
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.

Returns:

If to_syntax is None, returns a list of selected element indices. Otherwise, returns a translated selection string in the specified syntax.

Return type:

list or str

Raises:

NotSupportedFormError – Raised if the molecular system is provided in an unsupported form.
ArgumentError – Raised if one or more input arguments are invalid.

Notes

Supported molecular-system forms are summarized in Forms.
Selection syntaxes and valid query expressions are described in Selection syntaxes.
The selection is always returned as indices corresponding to the specified element level,

unless a translation to another syntax is explicitly requested via to_syntax.

See also

molsysmt.basic.get(): Retrieving attributes of selected elements.

Examples

>>> import molsysmt as msm
>>> from molsysmt import systems
>>> molsys = systems['T4 lysozyme L99A']['181l.h5msm']
>>> msm.basic.select(molsys, element='group', selection='group_name in ["HIS", "THR"]')
[20, 25, 30, 33, 53, 58, 108, 114, 141, 150, 151, 154, 156]

Tutorial with more examples

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

Added in version 1.0.0.

molsysmt.basic.set module#

molsysmt.basic.set.set(molecular_system, element=None, selection='all', structure_indices='all', syntax='MolSysMT', skip_digestion=False, **kwargs)[source]#

Setting attribute values in a molecular system.

This function assigns new values to attributes of a molecular system. The change is applied to the selected elements and, if applicable, to specific structures, as specified by the selection and structure_indices arguments.

This function assigns new values to attributes in a molecular system. Values are set on specific elements (atoms, groups, etc.) and optionally for selected structures. The attributes to be modified are passed as keyword arguments.

Parameters:

molecular_system (molecular system) – Molecular system to be modified. It can be in any of the supported forms.
element ({'atom', 'group', 'component', 'molecule', 'chain', 'entity', 'system'}, optional) – Level of elements on which the attribute values will be set. If not provided, the function will infer it from the attribute definitions.
selection (str, tuple, list or numpy.ndarray, default='all') – Selection of elements whose attributes will be modified. It can be a list/array of 0-based indices or a query string using one of the supported selection syntaxes. The default ‘all’ includes the entire system.
structure_indices (str, tuple, list or numpy.ndarray, default='all') – 0-based indices of structures for which structural attributes will be modified. The default ‘all’ includes all structures.
syntax (str, default='MolSysMT') – Syntax used to interpret the selection string. See Selection syntaxes for details.
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 (dict) – Attributes to modify, passed as keyword arguments where the key is the attribute name and the value is the new value to be assigned.

Raises:

NotSupportedFormError – If the molecular system is provided in an unsupported form.
ArgumentError – If the input arguments do not meet the expected requirements.

Notes

Supported molecular-system forms are described in Forms.
Selection syntaxes and valid query expressions are described in Selection syntaxes.
If element is not specified, it is inferred from the attribute definition.
If the attribute runs over structures, structure_indices must be defined accordingly.

See also

molsysmt.basic.select(): Selecting elements of a molecular system.
molsysmt.basic.get(): Retrieving attribute values from a molecular system.

Examples

>>> import molsysmt as msm
>>> molsys = msm.convert('181L')
>>> msm.basic.get(molsys, element='group', selection='group_index==30', group_name=True)
['HIS']
>>> msm.basic.set(molsys, selection='group_index==30', group_name='HSD')
>>> msm.basic.get(molsys, element='group', selection='group_index==30', group_name=True)
['HSD']

Tutorial with more examples

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

Added in version 1.0.0.

molsysmt.basic.view module#

molsysmt.basic.view.view(molecular_system=None, selection='all', structure_indices='all', standard=True, with_water_as=None, with_ions_as=None, viewer='NGLView', syntax='MolSysMT', skip_digestion=False)[source]#

Visualizing a molecular system.

This function displays a molecular system using an external interactive 3D visualization library (viewer) inside a Jupyter notebook. The visualization can be customized by selecting specific atoms or structures, choosing representations for water and ions, and applying a standardized visual layout.

Parameters:

molecular_system (molecular system, optional) – Molecular system to be displayed. It can be in any of the supported forms. If None, an empty viewer is returned.
selection (str, tuple, list or numpy.ndarray, default='all') – Selection of atoms to be shown. It can be a list/array of 0-based indices, or a query string using one of the supported selection syntaxes. The default ‘all’ includes all atoms in the system.
structure_indices (int, tuple, list, numpy.ndarray or 'all', default='all') – 0-based indices of structures to be shown. The default ‘all’ includes all structures.
standard (bool, default=True) – Whether to apply a default standardized visual layout. This includes representations and color schemes for typical biomolecular systems.
with_water_as ({'licorice', 'surface', None}, default=None) – Representation used for water molecules. If None, water is not displayed.
with_ions_as ({'licorice', 'balls', 'balls and sticks', None}, default=None) – Representation used for ions. If None, ions are not displayed.
viewer ({'NGLView'}, default='NGLView') – Viewer backend to use for visualization. Currently, only ‘NGLView’ is supported.
syntax (str, default='MolSysMT') – Syntax used to interpret the selection string. See Selection syntaxes for details.
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.

Returns:

Visualization widget returned by the selected viewer. For ‘NGLView’, this is an nglview.NGLWidget instance.

Return type:

object

Raises:

NotSupportedFormError – If the molecular system is provided in an unsupported form.
ArgumentError – If one or more input arguments are invalid.

Notes

Supported molecular-system forms are described in Forms.
Selection syntaxes and valid query expressions are described in Selection syntaxes.
Currently, the only supported viewer is ‘NGLView’.
The standardized visual layout includes cartoon representations for proteins, licorice for

ligands, and appropriate color schemes. See View for details.

See also

molsysmt.basic.select(): Selecting atoms or elements from a molecular system.

Examples

The following example illustrates how to visualize only the protein component of a molecular system:

>>> import molsysmt as msm
>>> molecular_system = msm.systems['T4 lysozyme L99A']['181l.h5msm']
>>> msm.basic.view(molecular_system, selection='molecule_type=="protein"', viewer='NGLView')
NGLWidget()

Tutorial with more examples

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

Added in version 1.0.0.

molsysmt.basic.where_is_attribute module#

molsysmt.basic.where_is_attribute.where_is_attribute(molecular_system, attribute, include_none=False, skip_digestion=False)[source]#

Locating the item where a specific attribute is found.

A molecular system can be composed of multiple items in different forms. This function returns the item and its form where the given attribute is available. If include_none is False, items that have the attribute but with value None will be ignored.

Parameters:

molecular_system (molecular system) – Molecular system to be analyzed. It can be in any of the supported forms.
attribute (str) – Name of the attribute to search for within the molecular system.
include_none (bool, default=False) – Whether to ignore items that have the attribute defined but its value is None. With default value False, such items will be ignored.
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.

Returns:

item – The item in which the attribute was found.
str – The form of the item where the attribute was found.

Notes

Supported molecular-system forms are described in Forms.
If multiple items contain the same attribute, the last matching one is returned.
If no item contains the attribute both outputs will be None.

See also

molsysmt.basic.has_attribute(): Checking whether a molecular system contains a given attribute.
molsysmt.basic.get_attributes(): Retrieving the list of attributes present in a molecular system.

Examples

>>> import molsysmt as msm
>>> from molsysmt import systems
>>> structure = systems['pentalanine']['pentalanine.inpcrd']
>>> topology = systems['pentalanine']['pentalanine.prmtop']
>>> molecular_system = [topology, structure]
>>> item, form = msm.basic.where_is_attribute(molecular_system, 'box')
>>> form
'file:inpcrd'
>>> item, form = msm.basic.where_is_attribute(molecular_system, 'atom_id')
>>> form
'file:prmtop'

Tutorial with more examples

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

Added in version 1.0.0.

molsysmt.basic package#

Subpackages#

Submodules#

molsysmt.basic.add module#

molsysmt.basic.append_structures module#

molsysmt.basic.are_multiple_molecular_systems module#

molsysmt.basic.compare module#

molsysmt.basic.concatenate_structures module#

molsysmt.basic.contains module#

molsysmt.basic.convert module#

molsysmt.basic.copy module#

molsysmt.basic.extract module#

molsysmt.basic.get module#

molsysmt.basic.get_attributes module#

molsysmt.basic.get_form module#

molsysmt.basic.get_label module#

molsysmt.basic.has_attribute module#

molsysmt.basic.info module#

molsysmt.basic.is_a_molecular_system module#

molsysmt.basic.is_composed_of module#

molsysmt.basic.iterator module#

molsysmt.basic.merge module#

molsysmt.basic.remove module#

molsysmt.basic.select module#

molsysmt.basic.set module#

molsysmt.basic.view module#

molsysmt.basic.where_is_attribute module#

Module contents#