molsysmt.basic.where_is_attribute#

molsysmt.basic.where_is_attribute(molecular_system, attribute, include_none=False, skip_digestion=False)[source]#

Locating the item where a specific attribute is found.

A molecular system can be composed of multiple items in different forms. This function returns the item and its form where the given attribute is available. If include_none is False, items that have the attribute but with value None will be ignored.

Parameters:

  • molecular_system (molecular system) – Molecular system to be analyzed. It can be in any of the supported forms.

  • attribute (str) – Name of the attribute to search for within the molecular system.

  • include_none (bool, default=False) – Whether to ignore items that have the attribute defined but its value is None. With default value False, such items will be ignored.

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

  • item – The item in which the attribute was found.

  • str – The form of the item where the attribute was found.

Notes

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

  • If multiple items contain the same attribute, the last matching one is returned.

  • A structural attribute is only looked for in items spanning the structure axis of the molecular system, which is the largest number of structures any of its items carries. An item holding a single reference conformation therefore does not supply a structural series for a trajectory held by another item, and the rule above applies only among the items that do span the axis. This makes the result independent of the order the items were listed in. When the attribute exists solely off the axis, both outputs are None and a StructuralAttributeOffAxisWarning is emitted.

  • If no item contains the attribute both outputs will be None.

See also

molsysmt.basic.has_attribute()

Checking whether a molecular system contains a given attribute.

molsysmt.basic.get_attributes()

Retrieving the list of attributes present in a molecular system.

Examples

>>> import molsysmt as msm
>>> from molsysmt import systems
>>> structure = systems['pentalanine']['pentalanine.inpcrd']
>>> topology = systems['pentalanine']['pentalanine.prmtop']
>>> molecular_system = [topology, structure]
>>> item, form = msm.basic.where_is_attribute(molecular_system, 'box')
>>> form
'file:inpcrd'
>>> item, form = msm.basic.where_is_attribute(molecular_system, 'atom_id')
>>> form
'file:prmtop'

Tutorial with more examples

See the following tutorial for a practical demonstration of how to use this function, along with additional examples: Where is attribute

Added in version 1.0.0.

On this page