MDMC.trajectory_analysis package

Subpackages

MDMC.trajectory_analysis.observables package

Submodules

MDMC.trajectory_analysis.compact_trajectory module

Module for memory-efficient MD trajectory handling.

Notes

Seeing how the current (as of August 2022) trajectory implementation consumes a lot of memory, an attempt is being made to build an object that will contain the bare minimum of functionality, to show the limits of performance that we can achieve within Python.

class MDMC.trajectory_analysis.compact_trajectory.CompactTrajectory(n_steps: int = 0, n_atoms: int = 1, useVelocity: bool = False, bits_per_number: int = 8, **settings: dict)[source]

Bases: object

Store an MD trajectory in numpy arrays.

The units are system units.

The normal workflow for a CompactTrajectory is:

Create and allocate memory.

traj = CompactTrajectory(n_step, n_atoms, useVelocity)
or
traj = CompactTrajectory()
traj.preAllocate(n_step, n_atoms, useVelocity)

Write values into arrays.

for n in frame_numbers:
    if not traj.validateTypes(atom_types):
        traj.WriteOneStep(step_number = n, time = time_value, positions = pos_values)
        traj.setDimensions(box_dimensions, step_number = n)

Add chemical element information.

traj.labelAtoms(atom_symbols, atom_masses)
traj.setCharges(atom_charges)

Check internal consistency, trim arrays.
```
traj.postProcess()
```

Parameters:

n_steps (int, optional) –
Number of simulation steps in the trajectory. Defaults to 0.

n_steps = 0 means that preAllocate will have to be run separately after the CompactTrajectory has been created.

n_steps > 0 means that preAllocate will be run immediately in the __init__ function.
n_atoms (int, optional) – Number of atoms in the system. Defaults to 1.
useVelocity (bool, optional) – If the trajectory contains velocities, set to True to allocate an additional array for the velocity values. Defaults to False.
bits_per_number (int, optional) – Set number of bytes in floating point numbers.
**settings (dict) – Extra options.

static create_from_h5md(file_name: str)[source]

Create a CompactTrajectory from an H5MD file.

Parameters:: file_name (str) – Path to the H5MD file containing the desired trajectory.
Returns:: The trajectory described by the file.
Return type:: CompactTrajectory

property data: ndarray

The step numbers and time steps in a single array.

Returns:: Concatenation of separate data arrays.
Return type:: ndarray

exportAtom(step_number: int = 0, atom_number: int = 0)[source]

Create an Atom object for a chosen time step of the simulation and atom number.

Parameters:

step_number (int) – Number of the simulation step at which the atom position should be read.
atom_number (int) – Number of the atom in the trajectory that will be created as an Atom object.

Returns:

A single Atom object.

Return type:

Atom

Notes

For compatibility with Trajectory.

filter_by_element(elements: list[str]) → CompactTrajectory[source]

Filter subtrajectory by chemical symbol.

Parameters:: elements (list[str]) – List of chemical elements given as string.
Returns:: A CompactTrajectory containing only the atoms of the specified chemical elements.
Return type:: CompactTrajectory

filter_by_time(start: float, end: float = None) → CompactTrajectory[source]

Filter to within time defined by start and end.

Create another CompactTrajectory, containing only the frames with the time values equal to or larger than the start parameter, and smaller than the end parameter.

If only one time value is given, the function will create a CompactTrajectory with a single time step equal to start, or raise an error if start is not an element of the time array.

Parameters:

start (float) – The start time for filtering the Trajectory.
end (float, optional) – The end time for filtering the Trajectory. The default is None, which means the new returned Trajectory has a single time, defined by the start.

Returns:

A copy with times in half open interval defined by start and end.

Return type:

CompactTrajectory

Raises:

ValueError – No valid MD frames found.

filter_by_type(types: list[int]) → CompactTrajectory[source]

Filter subtrajectory by atom ID.

Parameters:: types (list[int]) – A list of atom IDs.
Returns:: A CompactTrajectory containing only the atoms of the specified type.
Return type:: CompactTrajectory

labelAtoms(atom_symbols: dict[int, str] = None, atom_masses: dict[int, float] = None) → bool[source]

Create internal atom references.

A list of chemical elements of all the atoms in a trajectory frame,
a set of all the chemical elements present in a trajectory,
a list of atom masses of all the atoms in a trajectory frame.

It is up to the engine facade to construct the input dictionaries containing the correct information about the chemical elements and masses.

Parameters:

atom_symbols (dict[int, str]) – Mapping from trajectory atom_ID to chemical symbol.
atom_masses (dict[int, float]) – Mapping from trajectory atom_ID to chemical mass.

Returns:

References created successfully.

Return type:

bool

property positions: ndarray

The position array.

Added for those parts of code that use the plural form instead of singular.

Returns:: Time samples array.
Return type:: ndarray

postProcess()[source]

Finalise trajectory analysis.

Notes

This function should be called after the all the trajectory steps have been read. It will discard the unnecessary rows of the arrays, in case we had allocated too many due to some rounding error.

preAllocate(n_steps: int = 1, n_atoms: int = 1, useVelocity: bool = False)[source]

Allocate array space for data.

Creates empty arrays for storing atom positions, velocities, time values of the simulation frames, and the simulation box dimensions.

The numpy empty object do not initialise elements until they have been accessed by a read or write operation. This means that allocating too many steps is generally safe and harmless, as the unused steps will be removed when the postProcess method is called.

Parameters:

n_steps (int, optional) – Number of simulation steps in the trajectory. Defaults to 1.
n_atoms (int, optional) – Number of atoms in the system. Defaults to 1.
useVelocity (bool, optional) – If the trajectory contains velocities, set to True to allocate an additional array for the velocity values. Defaults to False.

setBytesPerNumber(bytes_per_number: int = 8)[source]

Change the number of bytes per number in the arrays.

This is used for storing atom positions, velocities, the frame timestamps and simulation box dimensions.

The best approach is to set the correct value before populating the arrays, but it is still possible to change the data type using this function when the CompactTrajectory already contains some values.

Parameters:: bytes_per_number (int, optional) – If 8, the arrays will use np.float64 to store the positions, velocities and time at each step. Will always be rounded up to the nearest multiple of 2.

MDMC.trajectory_analysis.trajectory module

Module for Configuration and related classes.

class MDMC.trajectory_analysis.trajectory.AtomCollection[source]

Bases: object

Base class for Configurations.

property dimensions: ndarray

Get the dimensions of the Universe in which the AtomCollection exists.

Returns:: The dimensions of the Universe.
Return type:: snumpy.ndarray

property universe: Universe | None

Get or set the Universe in which the AtomCollection exists.

Returns:: The Universe in which the AtomCollection exists, or None if it has not been set.
Return type:: Universe

class MDMC.trajectory_analysis.trajectory.Configuration(*structures: Structure, **settings: dict)[source]

Bases: AtomCollection

A Configuration stores Atom objects and their positions and velocities.

Parameters:

*structures – Zero or more Structure objects to be added to the Configuration.
**settings (dict) – Extra options.

element_set

set of the elements in the Configuration

Type:: set

data

Tuple of all contained structures.

Type:: tuple[Structure, …]

Parameters:: universe (Universe) – The Universe of the Configuration.

add_structure(structures: Structure) → None[source]

Add the Atom objects from a Structure to the data.

Parameters:: structures (Structure) – The Structure to add.

property atom_positions: list[ndarray]

Get the list of Atom.position which belong to the Configuration.

Returns:: A list of Atom.position s in Configuration.
Return type:: list[numpy.ndarray]

property atom_velocities: list[ndarray]

Get the list of Atom.velocity which belong to the Configuration.

Returns:: A list of Atom.velocity` s in ``Configuration.
Return type:: list[numpy.ndarray]

property atoms: list[Atom]

Get the list of Atom which belong to the Configuration.

Returns:: A list of all Atom s in Configuration.
Return type:: list[Atom]

property data: ndarray

Get or set the Atom properties of the Configuration.

Returns:: A structured NumPy array with 'atom', 'position', and 'velocity' fields.
Return type:: numpy.ndarray

property element_list: list[str]

Get the list of Atom.element.symbol which belong to the Configuration.

Returns:: A list of str of element abbreviations.
Return type:: list[str]

element_set

filter_atoms(predicate: Callable[[Atom], bool]) → list[Atom][source]

Filter the list of Atom using the predicate.

Parameters:: predicate (Callable[[Atom], bool]) – A function which returns a bool when passed an Atom.
Returns:: A list of Atom which are True for the given predicate.
Return type:: list

filter_by_element(element: str) → list[Atom][source]

Filter the Configuration using an element.

Parameters:: element (str) – An elemental symbol of the same format as is used for creating Atom objects.
Returns:: A list of Atom of the specified element.
Return type:: list

filter_structures(predicate: Callable[[Structure], bool]) → list[Structure][source]

Filter the list of Structures using the predicate.

Parameters:: predicate (Callable[[Structure], bool]) – A function which returns a bool when passed a Structure.
Returns:: A list of Structures which are True for the given predicate.
Return type:: list

property molecule_list: list[Molecule]

Get the list of Molecule which belong to the Configuration.

Returns:: A list of Molecule.
Return type:: list[Molecule]

scale(factor: float, vectors: Literal['positions', 'velocities'] = 'positions') → None[source]

Scale either atom_positions or atom_velocities by a factor.

Parameters:

factor (float) – Factor by which the vector is scaled.
vectors ({'positions', 'velocities'}) – Vectors to rescale.

Raises:

NotImplementedError – THIS IS NOT IMPEMENTED.

property structure_list: list[Structure]

Get the list of Structure which belong to the Configuration.

Returns:: A list of Structure.
Return type:: list[Structure]

validate_structure(structure: Structure) → None[source]

Validate the structure by testing that it belongs to the same Universe.

Parameters:: structure (Structure) – The Structure to validate.
Raises:: AssertionError – If the Structure does not belong to the same Universe as the Configuration.

class MDMC.trajectory_analysis.trajectory.TemporalConfiguration(time: float, *structures: Structure, **settings: dict)[source]

Bases: Configuration

A configuration which has a time associated with it.

Parameters:

time (float) – The time of the TemporalConfiguration in fs.
*structures (Structure) – Zero or more Structures.
**settings (dict) – Extra options to pass to superclass.

time

Module contents

Modules relating to describing an MD trajectory and calculating observables.

Contents

observables
trajectory