Trajectory handling#

class dynasor.Trajectory(filename, trajectory_format=None, atomic_indices=None, length_unit=None, time_unit=None, frame_start=0, frame_stop=None, frame_step=1, force_unit=None, properties=None)[source]#

Instances of this class hold trajectories in a format suitable for the computation of correlation functions. They behave as iterators, where each step returns the next frame as a TrajectoryFrame object. The latter hold information regarding atomic positions, types, velocities, and forces.

Parameters:

  • filename (str) – Name of input file.

  • trajectory_format (Optional[str]) – Type of trajectory. Possible values are: 'lammps_internal', 'extxyz', 'ase' or one of the formats supported by MDAnalysis (except for 'lammpsdump', which can be called by specifying 'lammps_mdanalysis' to avoid ambiguity). A format handled by MDAnalysis must be a name MDAnalysis knows, for example 'nc' or 'NCDF' for an AMBER netCDF trajectory. Case does not matter. If None, MDAnalysis picks a reader based on the file extension. Name the format for an extended xyz file, since the xyz reader of MDAnalysis ignores the Lattice field that dynasor needs.

  • atomic_indices (Union[str, dict[str, list[int]], None]) – Specify which indices belong to which atom type. Can be (1) a dictionary where the keys specify the species and the values are a list of atomic indices, (2) 'read_from_trajectory', in which case the species are read from the trajectory or (3) the path to a gromacs index file.

  • length_unit (Optional[str]) – Length unit of trajectory ('Angstrom', 'nm', 'pm', 'fm'). Necessary for correct conversion to internal dynasor units if the trajectory file does not contain unit information. If no length unit is specified and the reader cannot read units from the trajectory, Angstrom is assumed.

  • time_unit (Optional[str]) – Time unit of trajectory ('fs', 'ps', 'ns'). Necessary for correct conversion to internal dynasor units if the trajectory file does not contain unit information. If no time unit is specified and the reader cannot read units from the trajectory, fs is assumed.

  • frame_start (Optional[int]) – First frame to read; must be larger or equal 0.

  • frame_stop (Optional[int]) – Exclusive upper bound on the frame indices to read. For example, frame_stop=3 reads frames 0, 1, and 2 when using the default frame_start and frame_step. By default (None), the entire trajectory is read.

  • frame_step (Optional[int]) – Read every frame_step-th step of the input trajectory. By default (1) every frame is read. Must be larger than 0.

  • force_unit (Optional[str]) – Force unit of trajectory ('eV/Angstrom', 'eV/nm', 'kJ/mol/Angstrom', 'kJ/mol/nm', 'kcal/mol/Angstrom', 'kcal/mol/nm', 'Hartree/Bohr'). Necessary for correct conversion to internal dynasor units if the trajectory file does not contain unit information. If no force unit is specified and the reader cannot read units from the trajectory, eV/Angstrom is assumed. A unit dynasor cannot convert leaves the forces unconverted, with a warning.

  • properties (Union[str, Sequence[str], None]) – Names of the per-atom properties to read, any of 'positions', 'velocities', and 'forces', given as a sequence or, for a single one, as a string. A property that is not read is never split by atom type and hence costs no memory, which is worth doing for a large system, since a window of a dynamic structure factor calculation holds window_size + 1 frames at a time. Note what the analysis functions require: the structure factors need positions, currents need velocities in addition, and the spectral energy density needs velocities alone. The first frame of the trajectory decides what is read, so it provides the default and it is what a request is checked against.

property atomic_indices: dict[str, list[int]]#

Return copy of index arrays

property cell: NDArray[float]#

Simulation cell

property filename: str#

The trajectory filename

property frame_step: int#

Frame to access, trajectory will return every frame_step-th snapshot.

property has_forces: bool#

Whether the trajectory provides forces

property has_positions: bool#

Whether the trajectory provides positions

property has_velocities: bool#

Whether the trajectory provides velocities

property n_atoms: int#

Number of atoms

property properties: tuple[str, ...]#

Per-atom properties that are read from the trajectory

class dynasor.trajectory.trajectory_frame.TrajectoryFrame(atomic_indices, frame_index, positions=None, velocities=None, forces=None, properties=None)[source]#

Class holding positions and optionally velocities and forces, split by atom type, for one snapshot (frame) in a trajectory.

Each quantity is provided as a dictionary keyed by atom type, such that positions_by_type['Cs'] is a numpy array with shape (n_atoms_Cs, 3) and positions_by_type['Pb'] is a numpy array with shape (n_atoms_Pb, 3). The get_*_as_array methods return a quantity for all atoms in a single array ordered by atom index.

A quantity that the frame does not carry is reported as None.

Parameters:

  • atomic_indices (dict[str, list[int]]) – Dictionary specifying which indices (values) belong to which atom type (keys).

  • frame_index (int) – Trajectory index of the snapshot (frame).

  • positions (Optional[GenericAlias[float]]) – Positions as an array with shape (n_atoms, 3).

  • velocities (Optional[GenericAlias[float]]) – Velocities as an array with shape (n_atoms, 3); defaults to None.

  • forces (Optional[GenericAlias[float]]) – Forces as an array with shape (n_atoms, 3); defaults to None.

  • properties (Optional[Sequence[str]]) – Names of the per-atom properties to keep, a subset of per_atom_properties; defaults to None, which keeps every quantity that is provided.

property forces_by_type: dict[str, NDArray[float]] | None#

Forces split by atom type; None if the frame carries no forces.

property frame_index: int#

Index of the frame.

get_forces_as_array(atomic_indices)[source]#

Return the full forces array with shape (n_atoms, 3).

Parameters:

atomic_indices (dict[str, list[int]]) – Dictionary specifying which indices (values) belong to which atom type (keys).

Return type:

GenericAlias[float]

get_positions_as_array(atomic_indices)[source]#

Return the full positions array with shape (n_atoms, 3).

Parameters:

atomic_indices (dict[str, list[int]]) – Dictionary specifying which indices (values) belong to which atom type (keys).

Return type:

GenericAlias[float]

get_velocities_as_array(atomic_indices)[source]#

Return the full velocities array with shape (n_atoms, 3).

Parameters:

atomic_indices (dict[str, list[int]]) – Dictionary specifying which indices (values) belong to which atom type (keys).

Return type:

GenericAlias[float]

property positions_by_type: dict[str, NDArray[float]] | None#

Positions split by atom type; None if the frame carries no positions.

property velocities_by_type: dict[str, NDArray[float]] | None#

Velocities split by atom type; None if the frame carries no velocities.