molsysmt.basic.get#

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

On this page