molsysmt.basic.select#

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

On this page