molsysmt.basic.set#

molsysmt.basic.set(molecular_system, element=None, selection='all', structure_indices='all', syntax='MolSysMT', chemical_state='reference', skip_digestion=False, **kwargs)[source]#

Setting attribute values in a molecular system.

This function assigns new values to attributes of a molecular system. The change is applied to the selected elements and, if applicable, to specific structures, as specified by the selection and structure_indices arguments.

This function assigns new values to attributes in a molecular system. Values are set on specific elements (atoms, groups, etc.) and optionally for selected structures. The attributes to be modified are passed as keyword arguments.

Parameters:

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

  • element ({'atom', 'group', 'component', 'molecule', 'chain', 'entity', 'system'}, optional) – Level of elements on which the attribute values will be set. If not provided, the function will infer it from the attribute definitions.

  • selection (str, tuple, list or numpy.ndarray, default='all') – Selection of elements whose attributes will be modified. It can be a list/array of 0-based indices or a query string using one of the supported selection syntaxes. The default ‘all’ includes the entire system.

  • structure_indices (str, tuple, list or numpy.ndarray, default='all') – 0-based indices of structures for which structural attributes will be modified. The default ‘all’ includes all structures.

  • syntax (str, default='MolSysMT') – Syntax used to interpret the selection string. See Selection syntaxes for details.

  • chemical_state ({'reference', 'structure'} or int, default 'reference') – Chemical state on which state-dependent atom, component, and bond attributes are modified. Integer values are 0-based state indices; 'structure' resolves a unique state from structure_indices.

  • 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 (dict) – Attributes to modify, passed as keyword arguments where the key is the attribute name and the value is the new value to be assigned.

Raises:

  • NotSupportedFormError – If the molecular system is provided in an unsupported form.

  • ArgumentError – If the input arguments do not meet the expected requirements, including an out-of-range structure index for a structural attribute.

Notes

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

  • Selection syntaxes and valid query expressions are described in Selection syntaxes.

  • If element is not specified, it is inferred from the attribute definition.

  • If the attribute runs over structures, structure_indices must be defined accordingly.

  • Setting formal_charge, atom aromaticity, radical state, implicit-hydrogen semantics, atom stereochemistry, components, or bonds on a native Topology or MolSys writes the state selected by chemical_state. Formal charge accepts integer counts or quantities compatible with elementary charge.

  • isotope sets the stable nullable isotope mass number. It does not set atomic mass and is independent of chemical_state.

  • Rich bond order, fractional order, type, aromaticity, conjugation, stereochemistry and reference atoms, direction, component participation, and evidence are independent attributes; setting one does not infer the others.

  • Explicit integer state selection currently requires a native Topology or MolSys. Convert external forms before editing a non-reference state.

  • structure_chemical_state_index sets the nullable MolSys association aligned to structure_indices; it does not change the topology reference.

See also

molsysmt.basic.select()

Selecting elements of a molecular system.

molsysmt.basic.get()

Retrieving attribute values from a molecular system.

Examples

>>> import molsysmt as msm
>>> molsys = msm.convert('181L')
>>> msm.basic.get(molsys, element='group', selection='group_index==30', group_name=True)
['HIS']
>>> msm.basic.set(molsys, selection='group_index==30', group_name='HSD')
>>> msm.basic.get(molsys, element='group', selection='group_index==30', group_name=True)
['HSD']
>>> from molsysmt.native import Topology
>>> topology = Topology(n_atoms=2)
>>> msm.set(topology, element='atom', chemical_state=0, formal_charge=[1, -1])
>>> msm.get(topology, element='atom', chemical_state=0, formal_charge=True)
[1, -1]
>>> msm.set(topology, element='atom', isotope=[13, 2])
>>> msm.get(topology, element='atom', isotope=True)
[13, 2]

Tutorial with more examples

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

Added in version 1.0.0.

On this page