molsysmt.basic.Iterator#

class molsysmt.basic.Iterator(molecular_system, element='atom', selection='all', structure_indices=None, start=0, stop=None, step=1, chunk=1, syntax='MolSysMT', output_type='values', output_form='molsysmt.MolSys', skip_digestion=False, **kwargs)[source]#

Iterating over topological or structural attributes of a molecular system.

This class provides a unified interface to iterate over selected attributes of a molecular system — either topological (e.g., atom_name, group_index) or structural (e.g., coordinates, box, time). Iteration proceeds over elements (atoms, groups, molecules, etc.) or over structures depending on the requested attributes. When no attributes are requested, each iteration yields a molecular system with updated structural data (trajectory-like behavior).

Parameters:

__init__) ((see)

molecular_system#

Molecular system from which attribute values are extracted.

Type:

molecular system

element#

Hierarchical level over which iteration is performed.

Type:

{‘atom’, ‘group’, ‘component’, ‘molecule’, ‘chain’, ‘entity’, ‘system’}

indices#

Element indices used for iteration (as resolved from selection).

Type:

int, list, tuple or numpy.ndarray

structure_indices#

Structure indices used when iterating over structural attributes.

Type:

int, list, tuple or numpy.ndarray

start, stop, step, chunk

Control parameters defining the iteration window and stride.

Type:

int

iterator_index#

Current iteration position.

Type:

int

arguments#

Attribute names returned on each iteration.

Type:

list of str

Notes

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

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

  • This class implements the Python iterator protocol: __iter__() returns self, and __next__() returns the next item or raises StopIteration.

  • If no attributes are requested, the iterator returns a molecular system per iteration

with updated structural attributes.

See also

molsysmt.basic.select()

Select elements from a molecular system.

molsysmt.basic.get()

Retrieve values of attributes from a molecular system.

Examples

>>> import molsysmt as msm
>>> from molsysmt import systems
>>> molsys = systems['chicken villin HP35']['1vii.bcif.gz']
>>> it1 = msm.Iterator(molsys, element='group', selection='molecule_type=="peptide"',
...                    start=10, stop=20, step=2, group_index=True, group_name=True)
>>> for group_index, group_name in it1:
...     pass # replace with desired operations
>>> molsys = systems['pentalanine']['traj_pentalanine.h5']
>>> it2 = msm.Iterator(molsys, selection='group_index==3 and atom_name=="CA"',
...                    structure_indices=[100, 110, 120],
...                    time=True, coordinates=True)
>>> for time, coordinates in it2:
...     pass # replace with desired operations

Tutorial with more examples

See the following tutorial for a practical demonstration of how to use this class, along with additional examples: Iterator.

Added in version 1.0.0.

__init__(molecular_system, element='atom', selection='all', structure_indices=None, start=0, stop=None, step=1, chunk=1, syntax='MolSysMT', output_type='values', output_form='molsysmt.MolSys', skip_digestion=False, **kwargs)[source]#

Initializing an iterator over attributes of a molecular system.

Parameters:

  • molecular_system (molecular system) – Input system in any of the supported forms.

  • element ({'atom', 'group', 'component', 'molecule', 'chain', 'entity', 'system'}, default 'atom') – Hierarchical level guiding selection and topological iteration.

  • selection (int, index, tuple, list, numpy.ndarray or str, default 'all') – Elements to iterate over. Indices or a selection string (see Selection syntaxes).

  • structure_indices (int, list, tuple, numpy.ndarray or 'all', optional) – Structure indices (0-based) used if all requested attributes are structural.

  • start (int, default (0, None, 1, 1)) – Iteration control parameters: - start: starting position - stop: final exclusive position (None means until the end) - step: stride between positions - chunk: number of positions advanced per yielded item

  • stop (int, default (0, None, 1, 1)) – Iteration control parameters: - start: starting position - stop: final exclusive position (None means until the end) - step: stride between positions - chunk: number of positions advanced per yielded item

  • step (int, default (0, None, 1, 1)) – Iteration control parameters: - start: starting position - stop: final exclusive position (None means until the end) - step: stride between positions - chunk: number of positions advanced per yielded item

  • chunk (int, default (0, None, 1, 1)) – Iteration control parameters: - start: starting position - stop: final exclusive position (None means until the end) - step: stride between positions - chunk: number of positions advanced per yielded item

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

  • output_type ({'values', 'dictionary'}, default 'values') – Format of the returned item when attributes are requested: - ‘values’: tuple with atribute values in order (or a single value if only one attribute) - ‘dictionary’: mapping {attribute_names: keys}

  • output_form (str, default 'molsysmt.MolSys') – Form of the yielded molecular system when no attributes are requested.

  • **kwargs ({str: bool}) – Attributes to extract (e.g., time=True, coordinates=True). Keys must be valid attribute names; only those with True are included.

Raises:

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

  • ArgumentError – If any input argument is invalid or inconsistent, including an out-of-range structure index.

Methods

__init__(molecular_system[, element, ...])

Initializing an iterator over attributes of a molecular system.