molsysmt.basic.select#

molsysmt.basic.select(molecular_system, selection='all', structure_indices='all', element='atom', mask=None, syntax='MolSysMT', to_syntax=None, chemical_state='reference', 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 can be a selection string, a collection of 0-based indices, or a Boolean array with one entry per element. It is applied as an intersection filter.

  • syntax (str, default='MolSysMT') – Syntax used to interpret the selection string. MolSysMT and MDTraj are available from any convertible molecular-system form. MDAnalysis is available when the input can be converted to an MDAnalysis.Universe.

  • to_syntax (str, optional) – If provided, returns the translated selection query string instead of indices. MDTraj and NGLView output syntaxes are supported.

  • chemical_state ({'reference', 'structure'} or int, default 'reference') – Chemical state used by state-dependent predicates and hierarchy resolution. Integer values are 0-based state indices. 'structure' resolves the unique state associated with structure_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 a selection cannot be parsed or if an element, mask, or structure index is outside the valid range.

Notes

  • Supported molecular-system forms are summarized in Items and Forms.

  • Selection syntaxes and valid query expressions are described in Selection syntaxes.

  • Syntax support is directional. molsysmt.supported.syntaxes() reports the accepted input and output directions and their scope.

  • 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.

  • Explicit element and structure indices are non-negative and range checked. Supported parser failures are exposed as molsysmt.ArgumentError while retaining the original exception as their cause.

  • When using the MolSysMT syntax, numeric comparisons on *_id fields (for example, atom_id<10) are allowed as a convenience: if the underlying IDs are integer-like strings, they are temporarily converted to integers inside this function; otherwise a warning is issued and the comparison uses string semantics.

  • Native chemical-state atom attributes, components, and connectivity are resolved through chemical_state. Missing values and ambiguous multi-state systems raise explicit diagnostics instead of producing an empty selection.

  • With element='bond', MolSysMT predicates over canonical bond attributes are evaluated directly and return bond indices.

  • Explicit integer state selection currently requires a native Topology or MolSys and the MolSysMT selection syntax.

  • A structure selection spanning multiple associated states cannot return one ordinary atom-index selection and is rejected.

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]

Chemical-state attributes, such as formal_charge, are also selectable when available in the resolved native state.

>>> from molsysmt.native import Topology
>>> topology = Topology(n_atoms=3)
>>> msm.set(topology, element='atom', formal_charge=[0, 1, -1])
>>> msm.select(topology, 'formal_charge!=0', chemical_state=0)
[1, 2]
>>> topology._append_chemical_state_bonds([[0, 1]], is_aromatic=[True])
>>> msm.select(topology, 'bond_is_aromatic==True', element='bond')
[0]

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