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

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

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

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

  • get_missing_bonds (bool, default=True) – Whether to infer missing covalent bonds before resolving derived attributes.

  • output_type (str, default='values') – Representation used for the returned result.

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

With output_type=’values’, a single requested attribute returns its value (including None when absent). Multiple attributes return a list of values in their requested order. With output_type=’dictionary’, the result maps each requested attribute name to its 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.

  • FormatError – If a legacy H5MSM file has missing, invalid, or contradictory units, or structures YAML has an unsupported schema or invalid quantity record.

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

Notes

Native atom-level group identities preserve missing parent membership as None per selected atom when the hierarchy is partially populated. The same missing-parent mapping applies to group-based molecule/entity identities. A wholly absent group table retains its group-identity None result.

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

  • A partial native MolSys without topology can still expose its atom count, chemical-state inventory, and stored structural series. Attributes that require an absent domain return None. Explicit chemical-state selection on such an object is not supported yet.

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

  • A native topology with zero groups returns None for atom-level group_id, group_name, and group_type queries. No group or ligand label is invented.

  • Empty native connectivity is valid. With element='atom', n_bonds returns a zero count and bond_index an empty list for each selected atom. With element='system' (the default), the total bond count is zero. This does not establish that chemical connectivity is complete.

  • With element='group', n_bonds counts distinct bonds incident on each selected group in the selected chemical state. An internal bond contributes once; a bond between groups contributes once to each group.

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

  • Sparse alternate_location mappings are keyed by integer atom indices in the source system. Atom selections filter these keys without renumbering them. The outer list follows structure_indices, including repeated indices and structures with no alternate sites (empty dictionaries). Each entry’s atom_id values remain string labels. An absent alternate-location attribute returns None.

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]

>>> molsys = Topology(n_atoms=2)
>>> msm.get(molsys, element='atom', n_bonds=True)
[0, 0]
>>> msm.get(molsys, element='atom', bond_index=True)
[[], []]
>>> msm.get(molsys, n_groups=True)
0
>>> msm.get(molsys, element='atom', group_name=True) is None
True

>>> from molsysmt.native import Structures
>>> molsys = Structures(
...     coordinates=msm.pyunitwizard.quantity(np.zeros((1, 3, 3)), 'nm'),
...     alternate_location=[{2: {
...         'location_id': np.array(['A', 'B']), 'atom_id': [10, 11],
...         'occupancy': np.array([0.6, 0.4]),
...         'b_factor': msm.pyunitwizard.quantity(np.zeros(2), 'nm**2'),
...         'coordinates': msm.pyunitwizard.quantity(np.zeros((2, 3)), 'nm'),
...     }}])
>>> sites = msm.get(molsys, selection=[2], alternate_location=True)
>>> list(sites[0])
[2]
>>> sites[0][2]['atom_id']
['10', '11']

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