MDMC.trajectory_analysis package

Subpackages

• MDMC.trajectory_analysis.observables package
  • Submodules
  • MDMC.trajectory_analysis.observables.concurrency_tools module
    • core_batch()
    • create_executor()
  • MDMC.trajectory_analysis.observables.fqt module
    • AbstractFQt
      • AbstractFQt.FQt
      • AbstractFQt.apply_resolution()
      • AbstractFQt.calculate_SQw()
      • AbstractFQt.calculate_from_MD()
      • AbstractFQt.calculate_rho_config()
      • AbstractFQt.dependent_variables
      • AbstractFQt.dependent_variables_structure
      • AbstractFQt.errors
      • AbstractFQt.independent_variables
      • AbstractFQt.t
      • AbstractFQt.uniformity_requirements
    • FQt
      • FQt.name
    • calc_incoherent_scatt_length()
    • calculate_rho()
    • get_point_group()
    • wyckoff_symmetries()
  • MDMC.trajectory_analysis.observables.fqt_coh module
    • FQtCoherent
      • FQtCoherent.name
  • MDMC.trajectory_analysis.observables.fqt_incoh module
    • FQtIncoherent
      • FQtIncoherent.name
  • MDMC.trajectory_analysis.observables.obs module
    • Observable
      • Observable.reader
      • Observable.calculate_from_MD()
      • Observable.data
      • Observable.dependent_variables
      • Observable.dependent_variables_structure
      • Observable.errors
      • Observable.independent_variables
      • Observable.maximum_frames()
      • Observable.minimum_frames()
      • Observable.name
      • Observable.origin
      • Observable.read_from_file()
      • Observable.uniformity_requirements
      • Observable.use_FFT
  • MDMC.trajectory_analysis.observables.obs_factory module
    • ObservableFactory
      • ObservableFactory.create_observable()
      • ObservableFactory.get_observable()
      • ObservableFactory.register()
      • ObservableFactory.registry
  • MDMC.trajectory_analysis.observables.pdf module
    • PairDistributionFunction
      • PairDistributionFunction.PDF
      • PairDistributionFunction.PDF_err
      • PairDistributionFunction.calculate_from_MD()
      • PairDistributionFunction.dependent_variables
      • PairDistributionFunction.dependent_variables_structure
      • PairDistributionFunction.errors
      • PairDistributionFunction.independent_variables
      • PairDistributionFunction.maximum_frames()
      • PairDistributionFunction.minimum_frames()
      • PairDistributionFunction.name
      • PairDistributionFunction.r
      • PairDistributionFunction.uniformity_requirements
  • MDMC.trajectory_analysis.observables.sqw module
    • AbstractSQw
      • AbstractSQw.E
      • AbstractSQw.SQw
      • AbstractSQw.SQw_err
      • AbstractSQw.calculate_E()
      • AbstractSQw.calculate_dt()
      • AbstractSQw.calculate_from_MD()
      • AbstractSQw.calculate_resolution_functions()
      • AbstractSQw.dependent_variables
      • AbstractSQw.dependent_variables_structure
      • AbstractSQw.errors
      • AbstractSQw.independent_variables
      • AbstractSQw.recreated_Q
      • AbstractSQw.uniformity_requirements
      • AbstractSQw.validate_energy()
      • AbstractSQw.w
    • SQw
      • SQw.name
    • SQwCoherent
      • SQwCoherent.name
    • SQwIncoherent
      • SQwIncoherent.name
    • SQwMixins
      • SQwMixins.Q
      • SQwMixins.maximum_frames()
      • SQwMixins.minimum_frames()
  • Module contents
    • Observables (/ indicates alias)
    • CoherentDynamicStructureFactor
    • CoherentIntermediateScatteringFunction
    • DynamicStructureFactor
    • FQt
      • FQt.name
    • FQtCoh
    • FQtCoherent
      • FQtCoherent.name
    • FQtIncoherentFQtIncoh
    • FQt_coh
    • FQt_incoh
    • IncoherentDynamicStructureFactor
    • IncoherentIntermediateScatteringFunction
    • IntermediateScatteringFunction
    • PDF
    • PairDistributionFunction
      • PairDistributionFunction.PDF
      • PairDistributionFunction.PDF_err
      • PairDistributionFunction.calculate_from_MD()
      • PairDistributionFunction.dependent_variables
      • PairDistributionFunction.dependent_variables_structure
      • PairDistributionFunction.errors
      • PairDistributionFunction.independent_variables
      • PairDistributionFunction.maximum_frames()
      • PairDistributionFunction.minimum_frames()
      • PairDistributionFunction.name
      • PairDistributionFunction.r
      • PairDistributionFunction.uniformity_requirements
    • SQw
      • SQw.name
    • SQwCoh
    • SQwCoherent
      • SQwCoherent.name
    • SQwIncoherentSQwIncoh
    • SQw_coh
    • SQw_incoh

Submodules

MDMC.trajectory_analysis.compact_trajectory module

Module for memory-efficient MD trajectory handling. 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)

Bases: object

Stores an MD trajectory in numpy arrays. The units are system units.

The normal workflow for a CompactTrajectory is:

1. Create and allocate memory. traj = CompactTrajectory(n_step, n_atoms, useVelocity) or traj = CompactTrajectory() traj.preAllocate(n_step, n_atoms, useVelocity)

2. 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)

3. Add chemical element information traj.labelAtoms(atom_symbols, atom_masses) traj.setCharges(atom_charges)

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

property data

Returns the step numbers and time steps in a single array.

exportAtom(step_number: int = 0, atom_number: int = 0)

For compatibility with Trajectory, creates 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, for whatever purpose the user may need it.

Return type:

Atom

filter_by_element(elements: List[str])

Create a subtrajectory out of the original CompactTrajectory, containing only the chemical elements specified in the input element list.

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, end=None)

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 and error if start is not an element of the time array.

Parameters:

• start (float) – The start time for filtering the Trajectory

• end (, 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 CompactTrajectory with times in half open interval defined by start and end

Return type:

CompactTrajectory

filter_by_type(types: List[int])

Create a subtrajectory out of the original CompactTrajectory, containing only the atoms with the atom_type specified in the input types list.

Parameters:

types (List(int)) – A list of atom_type numbers.

Returns:

A CompactTrajectory containing only the atoms of the specified type.

Return type:

CompactTrajectory

labelAtoms(atom_symbols: dict = None, atom_masses: dict = None)

Creates a list of chemical elements of all the atoms in a trajectory frame, a set of all the chemical elements present in a trajectory, and 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) – a dictionary which returns a ‘str’ chemical element symbol for every ‘int’ atom_ID from the trajectory.

• atom_masses (dict) – a dictionary of ‘float’ atom masses, using as keys the ‘int’ atom_ID values.

property positions

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

postProcess()

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)

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:

• (int (n_atoms) – Number of simulation steps in the trajectory. Defaults to 1.

• optional) (If the trajectory contains) – Number of simulation steps in the trajectory. Defaults to 1.

• (int – Defaults to 1.

• optional) – Defaults to 1.

• (bool (useVelocity) – velocities, set to True to allocate an additional array for the velocity values. Defaults to False.

• optional) – velocities, set to True to allocate an additional array for the velocity values. Defaults to False.

setBytesPerNumber(bytes_per_number: int = 8)

Changes the number of bytes per number in the arrays 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 numbers.

Parameters:

• (int (bytes_per_number) – 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.

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

setCharge(charge_list: List[float] = None)

Sets the values of partial charge for each atom. It assumes that the charges are constant within the simulation.

Parameters:

charge_list (list[float]) – Fractional electrical charge of each atom, given in a list with one floating point number per atom.

setDimensions(frame_dimensions: array = None, step_num: int = -1)

Writes the simulation box dimensions into the object header. Additionally, if the simulation box dimensions change with time, it will keep track of the new dimensions at each step in the self.changing_dimensions object.

Parameters:

• frame_dimensions (np.array) – 3 float numbers defining the size of the simulation box along x, y and z.

• step_num (int) – The number of the simulation frame at which the frame_dimensions array was read.

subtrajectory(start: int = 0, stop: int = -1, step: int = 1, atom_filter: List = None)

Returns another CompactTrajectory instance, which contains the same header information, and a subset of the original trajectory steps. The arrays in the original trajectory will be sliced following the pattern: new = old[start:stop:step].

Optionally, atom_filter can be specified to choose only specific atoms from the trajectory. It is recommended not to use subtrajectory directly in this case, but to use the filter_by_element or filter_by_type methods, which will create the element_filter themselves.

Parameters:

• start (int) – number defining the beginning of the slicing range.

• stop (int) – number defining the end of the slicing range.

• step (int) – step size of the slicing operation

Returns:

• CompactTrajectory (a trajectory containing the same header)

• and the same or less steps than the original.

property times

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

validateTypes(raw_atom_types: array)

This function either sets the array of atom types (if it had not been set before), or checks if the array of atom types from the new frame is the same as the original array of atom types.

If the atom types have changed during the simulation, we cannot process the results using the CompactTrajectory object, and the validation will return False. It is up to the engine facade to decide what to do if valideTypes returns False.

Parameters:

atom_types (np.array) – an array of all the atom types, sorted by the atom ID. If these are numbers, like in a LAMMPS simulation, then they will be stored directly. If raw_atom_types are strings, an internal method called _create_types_from_elements will create numbers that correspond to the strings, so that every atom type has its own number.

Returns:

True if the atom types are the same as in the beginning, False otherwise.

Return type:

bool

property velocities

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

writeEmptyStep(step_num: int = -1, time: float = -1.0)

This function advances the iterators without writing any data. It is basically a reduced version of the writeOneStep method. This was added since the tests/trajectory_analysis/test_PDF.py use a trajectory made of 1000 _empty_ configurations.

Parameters:

• step_num (int, optional) – the index at which the numbers will be written. Defaults to -1.

• time (float, optional) – the time stamp of the simulation step, in the correct time units (femtoseconds). Defaults to -1.0.

writeOneStep(step_num: int = -1, time: float = -1.0, positions: array = None, velocities: array = None)

Writes the atom positions (and, optionally, velocities) of a single simulation frame into the trajectory arrays. This function assumes that we have allocated the memory already, and that we have sorted the atoms according to their IDs. It will then put the numbers into the arrays at the correct frame, given by the step_num parameter.

Parameters:

• step_num (int, optional) – the index at which the numbers will be written. Defaults to -1.

• time (float) – the time stamp of the simulation step, in the correct time units (femtoseconds). Defaults to -1.0.

• positions (np.array) – the array of the atom positions, shaped (n_atoms, 3). Defaults to None.

• velocities (np.array, optional) – the array of the atom velocities, shaped (n_atoms, 3). If we don’t use velocities, it can be skipped. Defaults to None.

MDMC.trajectory_analysis.compact_trajectory.configurations_as_compact_trajectory(*configs: List[TemporalConfiguration]) → CompactTrajectory

Populate the arrays of the CompactTrajectory using the input list of TemporalConfiguration objects.

Parameters:

objects (configs -- A list of TemporalConfiguration) – most likely containing atoms

:param : most likely containing atoms

Returns:

• A CompactTrajectory with atom types and positions matching those in the

• input configurations.

MDMC.trajectory_analysis.trajectory module

Module for Configuration and related classes

class MDMC.trajectory_analysis.trajectory.AtomCollection

Bases: object

Base class for Configurations

property dimensions: ndarray

Get the dimensions of the Universe in which the AtomCollection exists

Returns:

array – The dimensions of the Universe

Return type:

numpy.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)

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 –

  universe (Universe)

  The Universe of the Configuration

element_set

set of the elements in the Configuration

Type:

set

universe

Type:

Universe or None

data

Type:

*structures

add_structure(structures: Structure) → None

Adds the Atom objects from a Structure to the data

Parameters:

structures (Structure) – The Structure to add

property atom_positions: list

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

Returns:

A list of Atom.position

Return type:

list

property atom_velocities: list

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

Returns:

A list of ``Atom.velocity`

Return type:

list

property atoms: list[Atom]

Get the list of Atom which belong to the Configuration

Returns:

A list of Atom

Return type:

list

property data: ndarray

Get or set the Atom, Atom.position, and Atom.velocity which belong to the Configuration

Returns:

A structured NumPy array with 'atom', 'position', and 'velocity' fields

Return type:

numpy.ndarray

property element_list: list

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

Returns:

A list of str for the elements

Return type:

list

element_set

filter_atoms(predicate: function) → list[Atom]

Filters the list of Atom using the predicate

Parameters:

predicate (function) – 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]

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: function) → list[Structure]

Filters the list of Structures using the predicate

Parameters:

predicate (function) – 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

scale(factor: float, vectors: str = 'positions') → None

Scales either atom_positions or atom_velocities by a factor

Parameters:

• factor (float) – Factor by which the vector is scaled

• vectors (str, optional) – 'positions' (default) or 'velocities'

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

validate_structure(structure: Structure) → None

Validates the structure by testing that it belongs to the same Universe as the Configuration

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)

Bases: Configuration

A configuration which has a time associated with it

Parameters:

• time (float) – The time of the TemporalConfiguration in fs

• *structure_units – Zero or more Structures

time

Module contents

Modules relating to describing a molecular dynamics trajectory and calculating observables from them

Contents

observables trajectory