Dynamics and trajectories

Mean squared displacement

MeanSquaredDisplacement

MeanSquaredDisplacement(*, window=True, unwrap=True)

Mean squared displacement of the atoms of a trajectory.

Parameters:

Name	Type	Description	Default
window	bool	Average over every time origin, by fast Fourier transforms (True, default), or measure from the first frame only (False).	True
unwrap	bool	Follow the atoms through the periodic boundaries (True, default), or take the positions as they are, already unwrapped (False).	True

compute

compute(frames)

The displacement of a sequence of frames, such as a Trajectory.

Parameters:

Name	Type	Description	Default
frames	sequence of System	The same atoms in every frame: matched by the id column where the first frame has one, else in the same order. With unwrap and without an image column, atoms must move less than half the box between frames.	required

Returns:

Type	Description
DisplacementResult	The mean squared displacement for each lag.

DisplacementResult dataclass

DisplacementResult(lag, msd, components)

Bases: Result

Mean squared displacement against the lag.

Attributes:

Name	Type	Description
lag	ndarray	(T,) int64 lag in frames.
msd	ndarray	(T,) float64 mean squared displacement in Ų, averaged over the atoms.
components	ndarray	(T, 3) float64, its x, y and z parts.

Lindemann index

LindemannIndex

LindemannIndex(*, unwrap=True)

Lindemann index: the fluctuation of the distances between atoms relative to their mean, which rises sharply at melting.

Parameters:

Name	Type	Description	Default
unwrap	bool	Follow the atoms through the periodic boundaries (True, default), or take the positions as they are, already unwrapped (False).	True

compute

compute(frames, *, progress=None, cancel=None)

The index of a sequence of frames.

Parameters:

Name	Type	Description	Default
frames	sequence of System	The same atoms in every frame: matched by the id column where the first frame has one, else in the same order. With unwrap and without an image column, atoms must move less than half the box between frames. Time grows as the square of the number of atoms.	required

Returns:

Type	Description
LindemannResult	The index over every pair, of each atom and of each prefix of the frames.

LindemannResult dataclass

LindemannResult(index, atomic, running)

Bases: Result

Lindemann index of a trajectory.

Attributes:

Name	Type	Description
index	float64	The index averaged over every pair of atoms.
atomic	ndarray	(N,) float64, the index of each atom, averaged over its pairs, the atoms in the order of the first frame.
running	ndarray	(T,) float64, the index of the frames up to each one.

Atomic temperature

AtomicTemperature

AtomicTemperature(cutoff)

The temperature of each atom and its neighbors, from their velocities relative to their center of mass.

Parameters:

Name	Type	Description	Default
cutoff	float64	The neighbors closer than cutoff, in Å, form the group of an atom.	required

compute

compute(system, *, neighbors=None, progress=None, cancel=None)

The temperature of each atom.

Parameters:

Name	Type	Description	Default
system	System	The atoms, with velocities and either mass or element.	required
neighbors	NeighborList	A neighbor list of this system reaching at least cutoff.	None

Returns:

Type	Description
TemperatureResult	The temperature of each atom.

TemperatureResult dataclass

TemperatureResult(temperature)

Bases: Result

The local temperature of each atom.

Attributes:

Name	Type	Description
temperature	ndarray	(N,) float64 temperature in K; NaN for atoms without neighbors.

Along a trajectory

TimeAverage

TimeAverage(quantity, *, unwrap=True)

The mean of a quantity over the frames of a trajectory, as OVITO's time averaging modifier.

Parameters:

Name	Type	Description	Default
quantity	str or callable	A column of numbers of the atoms, such as "positions" or "csp"; "box" for the lattice vectors; or a function of a frame that gives a number, or an array of the same shape in every frame, such as the g(r) of a radial distribution function.	required
unwrap	bool	For positions: follow the atoms through the periodic boundaries (True, default), or average the positions as they are.	True

compute

compute(frames)

The mean over frames, such as a Trajectory or a slice of one.

Parameters:

Name	Type	Description	Default
frames	iterable of System	For a column, the same atoms in every frame: matched by the id column where the first frame has one, else in the same order. With unwrap and without an image column, atoms must move less than half the box between frames.	required

Returns:

Type	Description
TimeAverageResult	The mean and the number of frames.

TimeAverageResult dataclass

TimeAverageResult(value, frames, name=None)

Bases: Result

Time average of a quantity.

Attributes:

Name	Type	Description
value	ndarray	The float64 mean over the frames: of each atom in the order of the first frame for a column, (3, 3) for the box, of the shape the function gives otherwise.
frames	int32	The number of frames.
name	str or None	The column averaged; None for the box or a function.

TimeSeries

TimeSeries(quantity, operation='mean')

A quantity in every frame of a trajectory, as OVITO's time series modifier: a column reduced to one number per frame, or any function of a frame.

Parameters:

Name	Type	Description	Default
quantity	str or callable	A column of numbers, a component such as "positions.z" or an expression over the columns, reduced by operation in each frame; or a function of a frame that gives a number, or an array of the same shape in every frame.	required
operation	str	For a column, one of OPERATIONS of reduce. Default mean.	'mean'

compute

compute(frames)

The quantity in each frame, such as of a Trajectory or a slice of one.

Parameters:

Name	Type	Description	Default
frames	iterable of System	The frames, in order.	required

Returns:

Type	Description
TimeSeriesResult	The values and the timesteps.

TimeSeriesResult dataclass

TimeSeriesResult(frame, values, timestep, name=None)

Bases: Result

A quantity in each frame.

Attributes:

Name	Type	Description
frame	ndarray	(F,) int64 the place of each frame among those given, from 0.
values	ndarray	(F,) float64, the quantity in each frame; (F, k) for one of k components or values.
timestep	ndarray or None	(F,) int64 the timestep of each frame, where every frame has one in its information.
name	str or None	The column; None for a function.

FrameDifference

FrameDifference(column)

The change of a column of each atom from a reference frame, as OVITO's difference between frames.

Parameters:

Name	Type	Description	Default
column	str	A column of numbers, a component such as "pe.1" or an expression over the columns. Positions change through the periodic boundaries as given: use AtomicDisplacement for displacements.	required

compute

compute(system, reference)

The change from the reference.

Parameters:

Name	Type	Description	Default
system	System	The frame.	required
reference	System	The reference frame, such as the first of the trajectory: its atoms matched by the id column where both have one, else in the same order.	required

Returns:

Type	Description
FrameDifferenceResult	The values of the system minus those of the reference.

FrameDifferenceResult dataclass

FrameDifferenceResult(difference, name)

Bases: Result

A column minus its values in a reference frame.

Attributes:

Name	Type	Description
difference	ndarray	(N,) or (N, k) float64, the change of each atom of the system; added by System.with_columns as the column, its dots as underscores, followed by _change.
name	str	The column.

trajectory_lines

trajectory_lines(frames, atoms=None, *, unwrap=True)

The paths of atoms over the frames of a trajectory, as OVITO's generate trajectory lines.

Parameters:

Name	Type	Description	Default
frames	iterable of System	The same atoms in every frame: matched by the id column where the first frame has one, else in the same order.	required
atoms	array_like	A boolean mask or indices of the atoms of the first frame whose paths are wanted. Default all.	None
unwrap	bool	Follow the atoms through the periodic boundaries (True, default), or take the positions as they are.	True

Returns:

Type	Description
ndarray	(M, T, 3) float64, the positions of each atom in each frame, the atoms in the order of the first frame.

Changing a trajectory

remove_drift

remove_drift(frames, reference=0, *, atoms=None, unwrap=True)

The frames of a trajectory moved so that the center of mass of the atoms stays where it is in a reference frame, as OVITO's center of mass correction.

Parameters:

Name	Type	Description	Default
frames	sequence of System	The same atoms in every frame, such as a Trajectory: matched by the id column where the first frame has one, else in the same order. The masses are the mass column of the first frame, else those of its elements, else all equal.	required
reference	int32	The frame whose center of mass is kept. Default 0.	0
atoms	array_like	A boolean mask or indices of the atoms of the first frame whose center of mass is kept. Default all.	None
unwrap	bool	Follow the atoms through the periodic boundaries to find the center of mass (True, default), or take the positions as they are.	True

Returns:

Type	Description
sequence of System	The frames, read when they are used, each with all its atoms moved by one translation; the boxes do not move. Its shifts are the (T, 3) translations in Å.

Raises:

Type	Description
InvalidParameter	If there are no frames, the reference frame is not one of them, no atoms are chosen or their masses add up to zero, or the frames do not hold the same atoms.

freeze

freeze(system, reference, column, name=None)

The values of a column in a reference frame given to the atoms of a system, as OVITO's freeze property.

Parameters:

Name	Type	Description	Default
system	System	The frame that takes the values.	required
reference	System	The frame of the values, such as the first of the trajectory: its atoms matched by the id column where both have one, else in the same order.	required
column	str	A column, a component such as "positions.z" or an expression over the columns.	required
name	str	The new column; by default the column, its dots as underscores, followed by _frozen.	None

Returns:

Type	Description
System	The system with the values of the reference in the new column.

Raises:

Type	Description
MissingProperty	If an atom of the system is not in the reference.
InvalidParameter	Without ids, if the frames have different numbers of atoms.

smooth_trajectory

smooth_trajectory(frames, window)

The positions and other real numbers of each frame averaged over a window of frames about it, the atoms followed through the periodic boundaries, as OVITO's smooth trajectory.

Parameters:

Name	Type	Description	Default
frames	sequence of System	The same atoms in every frame, such as a Trajectory: matched by the id column where the frames have one, else in the same order. Without an image column, atoms must move less than half the box between frames.	required
window	int32	The number of frames averaged: the frame, (window - 1) // 2 frames before it and window // 2 after it, the first and last frames repeated beyond the ends; 1 leaves the positions as they are.	required

Returns:

Type	Description
sequence of System	The frames, each computed when it is used: the mean positions about the atoms of that frame, the mean of every other column of real numbers (velocities, forces, values of analyses) matched by atom; columns of integers or text as they are.

Raises:

Type	Description
InvalidParameter	If the window is not a positive integer or there are no frames.