Structures#

A molecular system in MolSysMT has two complementary parts:

  • Topology: what the system is — atoms, groups, chains, molecules, entities…

  • Structures: where those atoms are in space — coordinates, optional box, optional time…

This page focuses on structures.

A molecular system can contain one structure (a single set of coordinates) or many structures. And “many structures” can mean different things:

  • a molecular dynamics trajectory: frames ordered in time,

  • an ensemble: multiple models that are not necessarily time-ordered (for example, an NMR PDB entry),

  • or simply multiple coordinate sets attached to the same topology.

import molsysviewer as viewer

view = viewer.demo["pentalanine"]
view.show()

As explained in Loading and inspection, the molecular system is stored in view as view.molsys. Inside it, you will find the structures object at view.molsys.structures:

type(view.molsys.structures)

molsysmt.native.structures.Structures

What is a structure?#

A structure is a bundle of per-structure data. At minimum, it includes:

  • coordinates (the atomic positions)

Depending on the source dataset, it may also include optional per-structure attributes such as:

  • structure_id

  • box (if periodic boundary conditions exist)

  • time (if the structure comes from a molecular dynamics trajectory)

  • velocities (if the structure comes from a molecular dynamics trajectory)

  • b_factors (if the structure comes from an X-ray structure)

Structures are indexed by a 0-based structure index. In MolSysViewer and MolSysMT, you usually refer to them through the structure_indices argument.

If the structures come from a molecular dynamics trajectory, many tools would call each structure a frame. In MolSysMT/MolSysViewer we prefer the more general term structure, because not all multi-structure datasets are time-ordered.

You can also inspect view.molsys.structures directly (it is a lightweight container that stores arrays for the structural attributes that are present):

view.molsys.structures.box
Magnitude
[[[2.0 0.0 0.0]  [0.0 2.0 0.0]  [0.0 0.0 2.0]] [[2.0 0.0 0.0]  [0.0 2.0 0.0]  [0.0 0.0 2.0]] [[2.0 0.0 0.0]  [0.0 2.0 0.0]  [0.0 0.0 2.0]] ... [[2.0 0.0 0.0]  [0.0 2.0 0.0]  [0.0 0.0 2.0]] [[2.0 0.0 0.0]  [0.0 2.0 0.0]  [0.0 0.0 2.0]] [[2.0 0.0 0.0]  [0.0 2.0 0.0]  [0.0 0.0 2.0]]]
Unitsnanometer

You can also retrieve structural attributes with view.get(...).

For example, you can retrieve coordinates for a selection across a few structure indices:

view.get(element="system", n_structures=True)

200

Discovering what structural attributes are available#

Sometimes you do not know which structural attribute names exist for your current system.

MolSysMT provides a discovery function for that: molsysmt.basic.get_attributes(). In the next cell we request only attributes of type "structural".

You will typically use this when you are working with a new dataset and you are not sure whether it includes attributes such as box, time, velocities, or b_factors.

import molsysmt as msm

attrs = msm.get_attributes(view.molsys, attribute_type='structural', output_type='list')
attrs

['box',
 'box_shape',
 'box_angles',
 'box_lengths',
 'box_volume',
 'coordinates',
 'n_structures',
 'bioassembly',
 'n_bioassemblies']

Structural queries use structure_indices#

Requesting coordinates is a structural query, so you pass structure_indices.

You can use:

  • an integer (0),

  • a list of indices ([0, 10, 20]),

  • or 'all'.

view.get(element="atom", selection="atom_name=='C' and group_name=='ACE'", structure_indices=[10, 20, 30], coordinates=True)
Magnitude
[[[0.9115739464759827 1.1495733261108398 0.3834869861602783]] [[1.4904042482376099 1.3557647466659546 0.19293922185897827]] [[1.3005061149597168 0.7329973578453064 -0.5156993865966797]]]
Unitsnanometer