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

  • element (str, default=None) – 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.

  • syntax (str, default='MolSysMT') – Selection syntax used to evaluate selection (e.g., ‘MolSysMT’, ‘MDTraj’).

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

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

Native MolecularMechanics atom assignments accept one-dimensional string atom_ff_type labels or explicit partial-charge vectors. Values follow the selected atom order. A subset requires an existing mechanical atom axis; invalid lengths fail before mutation. Manual replacement clears the named provenance of the replaced mechanical attribute.

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

  • partial_charge on a native MolSys writes MolecularMechanics, independently of formal charges. Supply a finite one-dimensional charge quantity or numerical values in elementary charge, aligned with the selected atoms. Unknown unselected values remain missing; None clears the full charge column.

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

  • Editing coordinates or box through a native MolSys invalidates every named interaction analysis on the selected structures. Their observations are removed and those structures become unevaluated. Other structures and existing result views are preserved; no scientific recalculation is performed. Empty selections and identifier/time edits do not invalidate. With attached analyses, full geometry assignment cannot resize the structure axis; use extraction or append operations instead.

  • Invalidation is staged before geometry delegation. If delegation fails after it starts, selected structures remain unevaluated because a partial write may have occurred. Allocation and validation failures before delegation preserve the existing system. Direct edits through a separate Structures object require explicit owner invalidation.

  • Editing native MolSys atom-state assignments or scientific bond-state attributes invalidates every evaluated structure in every named analysis. This includes charge, aromaticity, hydrogen and stereochemical assignments; bond_id remains a label. Chemical dependencies are not inferred, even when chemical_state names one state or structure_indices selects only some structures: the assignment changes that state’s chemical data. Editing structure_chemical_state_index invalidates only the selected structures. Direct Topology/ChemicalStates aliases and mechanics edits require explicit owner invalidation.

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 MolSys, 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]
>>> molsys = MolSys(n_atoms=1)
>>> molsys.structures.append(coordinates=msm.pyunitwizard.quantity(
...     [[[0, 0, 0]]], 'nm'))
>>> analysis = msm.Interactions.from_records([], n_atoms=1, n_structures=1,
...     evaluated_structure_indices=[0], method='example')
>>> molsys.interactions = {'example': analysis}
>>> msm.set(molsys, coordinates=msm.pyunitwizard.quantity(
...     [[[1, 0, 0]]], 'nm'))
>>> molsys.interactions['example'].evaluated_structure_indices.tolist()
[]
>>> molsys.interactions = {'example': analysis}
>>> msm.set(molsys, element='atom', formal_charge=[0])
>>> molsys.interactions['example'].evaluated_structure_indices.tolist()
[]

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