trajectory_reader

A module containing classes for reading a trajectory from a file.

Summary

Classes:

TrajectoryReader

A class for reading a trajectory from a file.

Reference

class TrajectoryReader(
filename: str | list[str],
traj_format: TrajectoryFormat | str = TrajectoryFormat.AUTO,
md_format: MDEngineFormat | str = MDEngineFormat.PQ,
topology: Topology | None = None,
constant_topology: bool = True,
)[source]

Bases: BaseReader

A class for reading a trajectory from a file.

Inherited from BaseReader.

Parameters:

  • filename (str or list of str) – The name of the file to read from or a list of filenames to read from.

  • traj_format (TrajectoryFormat | str, optional) – The format of the trajectory. Default is TrajectoryFormat.AUTO. The format is inferred from the file extension.

  • md_format (MDEngineFormat | str, optional) – The format of the trajectory. Default is MDEngineFormat.PQ.

  • topology (Topology, optional) – The topology of the trajectory. Default is None.

  • constant_topology (bool, optional) – Whether the topology is constant over the trajectory or does change. Default is True.

calculate_frame_size(
filename: str = None,
) → int[source]

Calculates the size of the frame in the trajectory file.

Returns:

The size of the frame in the trajectory file.

Return type:

int

Raises:

TrajectoryReaderError – If the number of atoms in the first line of the file is invalid.

calculate_number_of_frames_per_file() → list[int][source]

Calculates the number of frames for each trajectory file.

Returns:

The number of frames in the trajectory files.

Return type:

List[int]

Raises:

TrajectoryReaderError – If the number of lines in the file is not divisible by the number of atoms.

frame_generator(
trajectory_start: int = 0,
trajectory_stop: int | None = None,
) → Generator[AtomicSystem][source]

A generator that yields the frames of the trajectory.

The difference to the read method is that the read method returns the whole trajectory at once, while the frame_generator yields the frames one after another. This is useful if the trajectory is very large and cannot be stored in memory.

This method is used to read the trajectory from the file. It reads the trajectory from the file and concatenates the lines of the same frame. The frame information is then read from the concatenated string with the FrameReader class and a Frame object is created.

Parameters:

  • trajectory_start (int, optional) – The start index of the trajectory, by default 0.

  • trajectory_stop (int | None, optional) – The last index of the trajectory, by default None, which then set to the length of the trajectory.

  • Exceptions

  • ----------

  • PQIndexError – If trajectory_start is less than 0 or greater than the length of the trajectory. If trajectory_stop is less than 0 or greater than the length of the trajectory.

Yields:

Generator[AtomicSystem] – The frames of the trajectory.

read(
topology: Topology | None = None,
) → Trajectory[source]

Reads the trajectory from the file.

It reads the trajectory from the file and concatenates the lines of the same frame. The frame information is then read from the concatenated string with the FrameReader class and a Frame object is created.

In order to read the cell information given in the file, the cell information of the last frame is used for all following frames that do not have cell information.

If the trajectory is split into multiple files, the files are read one after another and the frames are concatenated into a single trajectory.

Parameters:

topology (Topology, optional) – The topology of the trajectory. Default is None.

Returns:

The trajectory read from the file.

Return type:

Trajectory

window_generator(
window_size: int,
window_gap: int = 1,
trajectory_start: int = 0,
trajectory_stop: int | None = None,
) → Generator[Trajectory][source]

A generator that yields the windows of the trajectory using the specified window size and gap. The windows are generated by sliding a window of the specified size over the trajectory with the specified gap. It uses the frame_generator method to read the frames of the trajectory.

Parameters:

  • window_size (int) – The size of the window.

  • window_gap (int, optional) – The gap size between two windows, by default 1

  • trajectory_start (int, optional) – The start index of the first window, by default 0

  • trajectory_stop (int | None, optional) – Stop index of the window generator, by default None, which then set to the length of the trajectory.

Raises:

IndexError – If trajectory_start is less than 0 or greater than the length of the trajectory. If trajectory_stop is less than 0 or greater than the length of the trajectory. If window_size is less than 1 or greater than the length of the trajectory. If window_gap is less than 1 or greater than the length of the trajectory. If window_size is greater than trajectory_stop - trajectory_start.

Warning

If not all frames are included in the windows, a warning is issued.

Yields:

Generator[Trajectory] – A generator over the windows of the trajectory with the specified window size and gap.

property cells: list[Cell]

Returns the cells of the trajectory.

Returns:

The list of cells of the trajectory.

Return type:

list of Cell

logger = <CustomLogger PQAnalysis.TrajectoryReader (INFO)>