pymatgen.core.trajectory module

This module provides classes used to define a MD trajectory.

class Trajectory(lattice: Sequence[float] | Sequence[Sequence[float]] | np.ndarray | Lattice, species: list[str | Element | Species | DummySpecies | Composition], frac_coords: list[Sequence[Sequence[float]]] | np.ndarray, time_step: float = 2, site_properties: dict = None, frame_properties: dict = None, constant_lattice: bool = True, coords_are_displacement: bool = False, base_positions: Sequence[Sequence[float]] = None)[source]

Bases: monty.json.MSONable

Trajectory object that stores structural information related to a MD simulation. Provides basic functions such as slicing trajectory or obtaining displacements.

Create a trajectory object :param lattice: The lattice as any 2D array. Each row should correspond to a lattice

vector. E.g., [[10,0,0], [20,10,0], [0,0,30]] specifies a lattice with lattice vectors [10,0,0], [20,10,0] and [0,0,30].

  • species

    List of species on each site. Can take in flexible input, including: i. A sequence of element / species specified either as string

    symbols, e.g. [“Li”, “Fe2+”, “P”, …] or atomic numbers, e.g., (3, 56, …) or actual Element or Species objects.

    1. List of dict of elements/species and occupancies, e.g., [{“Fe” : 0.5, “Mn”:0.5}, …]. This allows the setup of disordered structures.

  • frac_coords (MxNx3 array) – list of fractional coordinates of each species

  • time_step (int, float) – Timestep of simulation in femtoseconds. Defaults to 2fs.

  • site_properties (list) – Properties associated with the sites as a list of dicts of sequences, e.g., [{“magmom”:[5,5,5,5]}, {“magmom”:[5,5,5,5]}]. The sequences have to be the same length as the atomic species and fractional_coords. Number of supplied dicts should match number of frames in trajectory Defaults to None for no properties.

  • frame_properties (dict) – Properties of the trajectory such as energy, pressure, etc. each property should have a length equal to the trajectory length. eg: {‘energy’: [#, #, #, #], ‘pressure’: [0, 0.1, 0 0.02]}

  • constant_lattice (bool) – Whether the lattice changes during the simulation, such as in an NPT MD simulation.

  • coords_are_displacement (bool) – Whether supplied coordinates are given in displacements (True) or positions (False)

  • base_positions (Nx3 array) – The starting positions of all atoms in trajectory. Used to reconstruct positions when converting from displacements to positions. Only needs to be specified if coords_are_displacement=True. Defaults to first index of frac_coords if coords_are_displacement=False.


MSONAble dict.


Copy of Trajectory.


Concatenate another trajectory :param trajectory: Trajectory to add :type trajectory: Trajectory

classmethod from_file(filename, constant_lattice=True, **kwargs)[source]

Convenience constructor to obtain trajectory from XDATCAR or vasprun.xml file :param filename: The filename to read from. :type filename: str :param constant_lattice: Whether the lattice changes during the simulation, such as in an NPT MD

simulation. True results in



classmethod from_structures(structures, constant_lattice=True, **kwargs)[source]

Convenience constructor to obtain trajectory from a list of structures. Note: Assumes no atoms removed during simulation

  • structures (list) – list of pymatgen Structure objects.

  • constant_lattice (bool) – Whether the lattice changes during the simulation, such as in an NPT MD simulation. True results in




Returns structure at specified index :param i: Index of structure :type i: int


(Structure) pymatgen structure object


Converts position coordinates of trajectory into displacements between consecutive frames


Converts fractional coordinates of trajectory into positions

write_Xdatcar(filename='XDATCAR', system=None, significant_figures=6)[source]

Writes Xdatcar to a file. The supported kwargs are the same as those for the Xdatcar_from_structs.get_string method and are passed through directly.

  • filename (str) – name of file (It’s prudent to end the filename with ‘XDATCAR’, as most visualization and analysis software require this for autodetection)

  • system (str) – Description of system

  • significant_figures (int) – Significant figures in the output file