TrajectoryObserver¶

relax() and run() construct and attach a TrajectoryObserver internally. It is not meant to be constructed or attached directly. See the usage guide for how to read trajectory data back from their results.

TrajectoryObserver ¶

TrajectoryObserver(
    atoms: Atoms,
    include_temperature: bool = False,
    include_magmoms: bool = False,
    include_dipoles: bool = False,
    include_velocities: bool = False,
)

TrajectoryObserver is a class that observes and records the states of atomic structures.

Acts as a hook during the relaxation process in ASE, saving intermediate structures and their associated properties like energies, forces, stresses, and optionally, temperatures, magnetic moments, and dipoles.

Attributes:

Name	Type	Description
`atoms`	`Atoms`	The ASE Atoms object representing the structure to observe.
`include_temperature`	`bool`	Whether to save the temperature values. Defaults to False.
`include_magmoms`	`bool`	Whether to save the magnetic moments. Defaults to False.
`include_dipoles`	`bool`	Whether to save the dipoles. Defaults to False.
`include_velocities`	`bool`	Whether to save the velocities. Defaults to False.

Note

This class was adapted from the matgl code and extended to include the ability to save additional property values.

Initializes the TrajectoryObserver with the ASE Atoms object and optional flags.

Parameters:

Name	Type	Description	Default
`atoms`	`Atoms`	The ASE Atoms object representing the atomic structure to observe and record.	required
`include_temperature`	`bool`	If True, the observer will record the temperature at each step. Defaults to False.	`False`
`include_magmoms`	`bool`	If True, the observer will record the magnetic moments at each step. Defaults to False.	`False`
`include_dipoles`	`bool`	If True, the observer will record the dipoles at each step. Defaults to False.	`False`
`include_velocities`	`bool`	If True, the observer will record the velocities at each step. Defaults to False.	`False`

call ¶

__call__() -> None

Records the current state of the atoms, including energies, forces, and stresses.

Optionally records temperatures, magnetic moments, dipoles, and velocities.

getitem ¶

__getitem__(item) -> tuple[Any, ...]

Returns a tuple of recorded properties at the specified index.

Parameters:

Name	Type	Description	Default
`item`	`int`	The index of the step to retrieve properties for.	required

Returns:

Name	Type	Description
`tuple`	`tuple[Any, ...]`	A tuple containing the total energies, potential energies, kinetic energies, forces, stresses, cell parameters, atomic positions, atomic numbers, chemical symbols, and, if applicable, temperatures, magnetic moments, dipoles, and velocities at the specified step.

len ¶

__len__()

Returns the number of recorded steps in the observer.

as_pandas ¶

as_pandas() -> pd.DataFrame

Converts the recorded trajectory into a pandas DataFrame.

The DataFrame will contain columns for total energies, potential energies, kinetic energies, forces, stresses, cell parameters, atomic positions, atomic numbers, chemical symbols, and, if applicable, temperatures, magnetic moments, dipoles, and velocities.

Returns:

Type	Description
`DataFrame`	pd.DataFrame: A DataFrame where each row corresponds to a step in the trajectory,
`DataFrame`	and each column corresponds to a recorded property.

save ¶

save(filename: str) -> None

Saves the recorded trajectory to a file in binary format using pickle.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The name of the file where the trajectory will be saved.	required

TrajectoryObserver¶