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', chemical_state='reference', 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 (str or array-like, optional) – Additional subset applied after selection. It can be a selection string, a collection of 0-based element indices, or a Boolean array with one entry per element.

  • syntax (str, default 'MolSysMT') – Selection syntax used when selection is a string. See Selection syntaxes.

  • get_missing_bonds (bool, default True) – 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 list of values following the order in which the attributes were provided in **kwargs.

    • 'dictionary' — return a dictionary mapping attribute names to values.

  • chemical_state ({'reference', 'structure'} or int, default 'reference') – Chemical state used to resolve state-dependent atom, component, and bond attributes. A non-negative integer selects a state by its 0-based index. 'structure' resolves the unique state associated with the requested structures of a native MolSys. State identifiers are not accepted because they need not be unique.

  • 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 list with values

in the order given by **kwargs.

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

Return type:

Any or list or dict or None

Raises:

  • NotSupportedFormError – If the molecular system has an unsupported form.

  • ArgumentError – If any input argument is invalid or inconsistent, including malformed selections and out-of-range element, mask, or structure indices.

  • NotWithThisFormError – If a form declares a requested attribute but provides neither a compatible direct getter, registered derivation, nor usable attribute pipe.

Notes

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

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

  • A request may combine attributes from different element levels when an incompatible attribute has exactly one catalog-supported level. MolSysMT evaluates that attribute at its supported level and preserves the input attribute order. For example, with element='atom', coordinates are evaluated on atoms while structure_id is evaluated on the system. The atom selection is not applied to system-level attributes.

  • Native Structures and MolSys objects expose stored temperature, potential energy, and kinetic energy series. Total energy is returned only when both energy components are present. OpenMM Context and Simulation objects expose temperature only when their integrator defines it.

  • Native Topology and MolSys objects resolve state-dependent atom chemistry, components, and bonds from chemical_state. The default uses the reference-state rules. Access is rejected when multiple states exist without a reference and no explicit index is supplied.

  • isotope is stable atom metadata. Rich bond attributes keep integral and fractional order, relationship type, aromaticity, conjugation, stereochemistry and reference atoms, direction, component participation, and evidence independent.

  • State inventory attributes such as chemical_state_index and chemical_state_id continue to describe every state even when chemical_state selects one state for other requested attributes.

  • Explicit integer state selection currently requires a native Topology or MolSys. Convert an external form before querying a non-reference state.

  • chemical_state='structure' requires a native MolSys and rejects missing associations or structure selections spanning multiple states.

  • Form-independent attributes such as box lengths, angles, shape, and volume are derived from the box matrix when the source form exposes that matrix but does not implement a dedicated getter.

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]
>>> from molsysmt.native import Topology
>>> topology = Topology(n_atoms=3)
>>> msm.set(topology, element='atom', formal_charge=[0, -1, 1])
>>> msm.get(topology, element='atom', chemical_state=0, formal_charge=True)
[0, -1, 1]
>>> msm.set(topology, element='atom', isotope=[13, None, 2])
>>> msm.get(topology, element='atom', isotope=True)[0]
13
>>> msm.get(topology, element='system', n_chemical_states=True,
...         reference_chemical_state_index=True)
[1, 0]
>>> import numpy as np
>>> from molsysmt.native import MolSys
>>> molsys = MolSys(n_atoms=1)
>>> molsys.structures.coordinates = msm.pyunitwizard.quantity(np.zeros((2, 1, 3)), 'nm')
>>> msm.get(molsys, structure_chemical_state_index=True)
[0, 0]

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