Set#

Setting attribute values to a molecular system.

Some attributes of a molecular system can be changed without altering its identity — for example, modifying box dimensions, coordinates, stable isotope mass numbers, or force field parameters. In other cases, attribute corrections may be required, such as fixing a group name or atom type. MolSysMT provides the molsysmt.basic.set() function to assist with these tasks.

Hint

Visit the section Attributes for a detailed overview of attributes in MolSysMT.

Added in version 1.0.0.

API documentation

Follow this link for a detailed description of the input arguments, raised errors, and returned objects of this function: molsysmt.basic.set().

Basic usage#

Let’s show how this function works using a PDB structure (181L):

import molsysmt as msm

molsys = msm.convert('181L')

msm.info(molsys)

form	n_atoms	n_groups	n_components	n_chains	n_molecules	n_entities	n_waters	n_ions	n_small_molecules	n_proteins	n_structures
molsysmt.MolSys	1441	302	141	6	141	5	136	2	2	1	1

Suppose that the name of the group at index 30 is incorrect in our system:

msm.info(molsys, element='atom', selection='group_index==30')

index	id	name	type	group index	group id	group name	group type	molecule type	entity name
248	249	N	N	30	31	HIS	amino acid	protein	T4 LYSOZYME
249	250	CA	C	30	31	HIS	amino acid	protein	T4 LYSOZYME
250	251	C	C	30	31	HIS	amino acid	protein	T4 LYSOZYME
251	252	O	O	30	31	HIS	amino acid	protein	T4 LYSOZYME
252	253	CB	C	30	31	HIS	amino acid	protein	T4 LYSOZYME
253	254	CG	C	30	31	HIS	amino acid	protein	T4 LYSOZYME
254	255	ND1	N	30	31	HIS	amino acid	protein	T4 LYSOZYME
255	256	CD2	C	30	31	HIS	amino acid	protein	T4 LYSOZYME
256	257	CE1	C	30	31	HIS	amino acid	protein	T4 LYSOZYME
257	258	NE2	N	30	31	HIS	amino acid	protein	T4 LYSOZYME

Let’s now assume that the histidine residue should be labeled as “HSD” instead of “HIS”. This can be easily updated using the function molsysmt.basic.set():

msm.set(molsys, selection='group_index==30', group_name='HSD')

Tip

All methods defined in the molsysmt.basic module can also be invoked from the main level of the library. Hence, molsysmt.set() is the same function as molsysmt.basic.set().

Let’s check that the group name changed in deed:

msm.info(molsys, element='atom', selection='group_index==30')

index	id	name	type	group index	group id	group name	group type	molecule type	entity name
248	249	N	N	30	31	HSD	amino acid	protein	T4 LYSOZYME
249	250	CA	C	30	31	HSD	amino acid	protein	T4 LYSOZYME
250	251	C	C	30	31	HSD	amino acid	protein	T4 LYSOZYME
251	252	O	O	30	31	HSD	amino acid	protein	T4 LYSOZYME
252	253	CB	C	30	31	HSD	amino acid	protein	T4 LYSOZYME
253	254	CG	C	30	31	HSD	amino acid	protein	T4 LYSOZYME
254	255	ND1	N	30	31	HSD	amino acid	protein	T4 LYSOZYME
255	256	CD2	C	30	31	HSD	amino acid	protein	T4 LYSOZYME
256	257	CE1	C	30	31	HSD	amino acid	protein	T4 LYSOZYME
257	258	NE2	N	30	31	HSD	amino acid	protein	T4 LYSOZYME

Let’s explore another example, this time modifying a structural attribute. We will look at the coordinates of the “CA” atom in the “HSD” group:

msm.get(molsys, element='atom', selection='group_name=="HSD" and atom_name=="CA"', coordinates=True)

Magnitude	[[[3.7278 1.6327 1.7646999999999997]]]
Units	nanometer

There is only a single structure in the system, let’s change the coordinates of this former atom to a new value:

msm.set(molsys, selection='group_name=="HSD" and atom_name=="CA"', structure_indices=0, coordinates='[0,0,0] nm')

Finally, let’s verify that the coordinates of the “CA” atom in the “HSD” group were updated correctly:

msm.get(molsys, element='atom', selection='group_name=="HSD" and atom_name=="CA"', coordinates=True)

Magnitude	[[[0.0 0.0 0.0]]]
Units	nanometer

Initializing periodic boxes#

When a native system has coordinates but no box series, a full-axis msm.set(molsys, box=box_quantity) assignment initializes it. Supply matrices with shape (n_structures, 3, 3) and explicit length units. Internal storage uses nm; your input length units may differ. Partial updates require an existing series and raise an error before initialization. They do not invent boxes for unspecified structures. Periodic analyses use the assigned row lattice vectors; see the executed Get pi-pi interactions example.

Updating geometry with saved analyses#

For a native MolSys with named interactions, coordinate or box writes through msm.set(molsys, ...) remove old observations and mark the selected structures unevaluated in every analysis. Untouched structures remain available, and old query views remain historical snapshots. This includes evaluated-empty structures: their old zero count cannot describe new geometry. Recalculate and attach new results explicitly.

Empty atom/frame selections and identifier/time changes do not invalidate. Full geometry assignment preserves the frame axis when analyses are attached; change the axis with extraction or append operations. A failure after geometry delegation starts conservatively leaves selected frames unevaluated. Editing a separately accessed Structures object requires explicit owner invalidation. See the sparse interaction recipe.

Chemical-state atom and scientific bond edits with msm.set(molsys, ...) invalidate every covered structure in the named analyses. Replacing molsys.chemical_states does the same. Changing structure_chemical_state_index invalidates only the selected frames. Bond IDs and empty selections preserve results. No detector runs automatically. Separate Topology/ChemicalStates aliases, topology replacement, mechanics changes and raw data writes need explicit owner invalidation before new calculations.

Assigning mechanical charges#

For a native MolSys, msm.set(molsys, partial_charge=values) writes mechanical charges independently of formal charges. Supply a finite one-dimensional charge quantity or numerical values in elementary charge, aligned with the selected atom indices in their explicit order. Session charge units do not change native storage. Unknown unselected values stay missing; partial_charge=None clears the full column. An empty selection changes nothing. Explicit replacement clears original charge-model attribution. See Getting partial charges for a named calculation instead of manual values.

Setting mechanical labels#

Mechanical atom labels are parameter assignments, separate from element symbols. For a native MolecularMechanics object, msm.set(..., element='atom', atom_ff_type=...) accepts a one-dimensional string vector. Subset values follow the requested index order and require an existing atom axis. Invalid lengths fail before mutation. Manual labels are a caller declaration, and replacement clears their named typing provenance; it does not certify a chemical scheme. See Assigning AutoDock types for calculated assignments and export.