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 in any supported MolSysMT format.

  • selection (str, list, tuple, or numpy.ndarray, default='all') – Selection string or boolean/integer array specifying elements.

  • structure_indices (int, list, tuple, or numpy.ndarray, default='all') – Structure indices (0-based) to include or process.

  • element (str, default='atom') – Structural element level to query (‘atom’, ‘group’, ‘component’, ‘molecule’, ‘chain’, ‘entity’).

  • mask (str, list, tuple, numpy.ndarray, or None, default=None) – Boolean mask combined with selection when choosing elements.

  • syntax (str, default='MolSysMT') – Selection syntax used to evaluate selection (e.g., ‘MolSysMT’, ‘MDTraj’).

  • to_syntax (str or None, default=None) – Selection syntax used to format the returned selection string.

  • chemical_state ({'reference', 'structure'}, int, or None, default='reference') – Chemical state used to resolve state-dependent attributes.

  • skip_digestion (bool, default=False) – Whether to skip MolSysMT’s internal argument digestion mechanism.

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

  • All-element selections obtain counts through a direct getter or the source form’s registered attribute pipe.

  • 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