pylj.trajectory

The configurations a simulation samples, kept in order for analysis after the run.

Sampled configurations, in order.

class pylj.trajectory.Trajectory(frames: Iterable[Configuration] = (), times: Iterable[float] | None = None)

Bases: object

The configurations a simulation has sampled, in order.

A simulation appends its current configuration each time sample is called. Every frame has the same box and the same number of atoms. Indexing gives a Configuration; slicing gives a Trajectory.

A molecular dynamics trajectory carries the time of each frame. A Monte Carlo trajectory has no times.

Parameters:

• frames – Configurations to start with, in order.

• times – The time of each frame, in seconds, or None for an untimed trajectory.

Raises:

ValueError – If times is given and is not one per frame.

append(configuration: Configuration, time: float | None = None) → None

Adds a frame to the end.

Parameters:

• configuration – The frame to add.

• time – The time of the frame, in seconds. Required on a timed trajectory and not accepted on an untimed one.

Raises:

ValueError – If the frame’s box or number of atoms differs from the first frame’s, or time is given to an untimed trajectory or withheld from a timed one.

property times: NDArray[float64] | None

The time of each frame, in seconds, or None if untimed.

property positions: NDArray[float64]

The positions of every frame, shape (frames, N, 2), in metres.

rdf(bins: int = 100, r_max: float | None = None) → tuple[NDArray[float64], NDArray[float64]]

Averages g(r) over the frames.

Parameters:

• bins – The number of bins.

• r_max – The largest distance binned, in metres; by default half the box.

Returns:

The bin centres, in metres, and the mean g(r) in each bin.

Raises:

ValueError – If the trajectory has no frames.

structure_factor(q_max: float | None = None) → tuple[NDArray[float64], NDArray[float64]]

Averages the structure factor S(q) over the frames.

The wavevectors come from the first frame, and every frame is evaluated on that one set.

Parameters:

q_max – The largest wavevector magnitude, in 1/m; the default comes from default_q_max() for the first frame.

Returns:

The wavevector magnitudes, in 1/m, and the mean S(q) at each magnitude.

Raises:

ValueError – If the trajectory has no frames, or q_max is below 2 pi / L.

msd(max_lag: float | None = None) → tuple[NDArray[float64], NDArray[float64]]

Averages the mean squared displacement over time origins.

For each lag, the squared displacement of the unwrapped positions between every pair of frames that lag apart is averaged over those pairs and over atoms.

Parameters:

max_lag – The longest lag returned, in seconds. By default the whole run.

Returns:

The lag times, in seconds, from one frame interval up to max_lag, and the mean squared displacement at each, in metres squared.

Raises:

ValueError – If the trajectory has no times, fewer than two frames, frames that are not evenly spaced, or max_lag is below the frame spacing.