UniverseSequence¶

class pylimer_tools_cpp.UniverseSequence(self: pylimer_tools_cpp.UniverseSequence)¶

Bases: pybind11_object

This class represents a sequence of Universes, with the Universe’s data only being read on request. Dump files are read at once in order to know how many timesteps/universes are available in total (but the universes’ data is not read on first look through the file). This, while it can lead to two (or more) reads of the whole file, is a measure in order to enable low memory useage if needed (i.e. for large dump files). Use Python’s iterator to have this UniverseSequence only ever retain one universe in memory. Alternatively, use forget_at_index() to have the UniverseSequence forget about already read universes.

Construct an empty UniverseSequence.

Use initialization methods to populate it with data.

Methods Summary

`at_index`(self, index)	Get the Universe at the given index (as of in the sequence given by the dump file).
`compute_distance_autocorrelation_from_to`(...)	Compute the autocorrelation of the dot product of the distance vector from certain to other atoms.
`compute_distance_from_to_atoms`(self, ...[, ...])	Compute the root square norm of all the (unwrapped!) distances for the given pair of atoms.
`compute_msd_for_atom_properties`(self, ...[, ...])	Compute the mean square displacement for atoms using specified property names.
`compute_msd_for_atoms`(self, atom_ids[, ...])	Compute the mean square displacement for atoms with the specified IDs.
`compute_vector_from_to_atoms`(self, ...[, ...])	Compute the (unwrapped!) distances for the given pair of atoms.
`forget_at_index`(self, index)	Clear the memory of the Universe at the given index (as of in the sequence given by the dump file).
`get_all`(self)	Get all universes initialized back in a list.
`get_length`(self)	Get the number of universes in this sequence.
`initialize_from_data_sequence`(self, data_files)	Reset and initialize the Universes from an ordered list of Lammps data (`write_data`) files.
`initialize_from_dump_file`(self, ...)	Reset and initialize the Universes from a Lammps `dump` output.
`next`(self)	Get the Universe that's next in the sequence.
`reset_iterator`(self)	Reset the internal iterator, such that a subsequent call to `next()` returns the first one again.
`set_data_file_atom_style`(self, atom_styles)	Set the format of the data files to be read.

Methods Documentation

at_index(self: pylimer_tools_cpp.UniverseSequence, index: int) → pylimer_tools_cpp.Universe¶

Get the Universe at the given index (as of in the sequence given by the dump file).

Parameters:: index – The index of the universe to retrieve
Returns:: The Universe at the specified index

compute_distance_autocorrelation_from_to(self: pylimer_tools_cpp.UniverseSequence, atom_ids_from: list[int], atom_ids_to: list[int], nr_of_origins: int = 25, reduce_memory: bool = False) → dict[int, float]¶

Compute the autocorrelation of the dot product of the distance vector from certain to other atoms.

For example, this can be used to compute Eq. 4.51 from Masao Doi, Introduction to Polymer Physics, p. 74.

compute_distance_from_to_atoms(self: pylimer_tools_cpp.UniverseSequence, atom_ids_from: list[int], atom_ids_to: list[int], reduce_memory: bool = False) → list[float]¶

Compute the root square norm of all the (unwrapped!) distances for the given pair of atoms.

Can be used to somewhat faster compute e.g. all the end-to-end or bond distances. Pay attention that the image flags are correct, otherwise, this data may not be useable.

compute_msd_for_atom_properties(self: pylimer_tools_cpp.UniverseSequence, atom_ids: list[int], x_property: str, y_property: str, z_property: str, nr_of_origins: int = 25, reduce_memory: bool = False, max_tau: int = -1) → dict[int, float]¶

Compute the mean square displacement for atoms using specified property names.

Parameters:

atom_ids – List of atom IDs for which to compute the MSD
x_property – Name of the x-coordinate property in the dump file (e.g., “x”, “xu”, “xs”)
y_property – Name of the y-coordinate property in the dump file (e.g., “y”, “yu”, “ys”)
z_property – Name of the z-coordinate property in the dump file (e.g., “z”, “zu”, “zs”)
nr_of_origins – Number of time origins to use for averaging. Higher values provide better statistics but increase computation time (default: 25)
reduce_memory – If True, reduces memory usage by forgetting universes after processing them (default: False)
max_tau – Maximum time lag (tau) to compute. If -1, computes for all possible tau values. For better statistics, consider setting this to approximately half the sequence length (default: -1)

Returns:

Dictionary mapping time lag (tau) to mean square displacement values

compute_msd_for_atoms(self: pylimer_tools_cpp.UniverseSequence, atom_ids: list[int], nr_of_origins: int = 25, reduce_memory: bool = False, max_tau: int = -1) → dict[int, float]¶

Compute the mean square displacement for atoms with the specified IDs.

Parameters:

atom_ids – List of atom IDs for which to compute the MSD
nr_of_origins – Number of time origins to use for averaging. Higher values provide better statistics but increase computation time (default: 25)
reduce_memory – If True, reduces memory usage by forgetting universes after processing them (default: False)
max_tau – Maximum time lag (tau) to compute. If -1, computes for all possible tau values. For better statistics, consider setting this to approximately half the sequence length (default: -1)

Returns:

Dictionary mapping time lag (tau) to mean square displacement values

compute_vector_from_to_atoms(self: pylimer_tools_cpp.UniverseSequence, atom_ids_from: list[int], atom_ids_to: list[int], reduce_memory: bool = False) → list[numpy.ndarray[numpy.float64[3, 1]]]¶

Compute the (unwrapped!) distances for the given pair of atoms.

Can be used to somewhat faster compute e.g. all the end-to-end or bond vectors. Pay attention that the image flags are correct, otherwise, this data may not be useable.

forget_at_index(self: pylimer_tools_cpp.UniverseSequence, index: int) → None¶: Clear the memory of the Universe at the given index (as of in the sequence given by the dump file).

get_all(self: pylimer_tools_cpp.UniverseSequence) → list[pylimer_tools_cpp.Universe]¶

Get all universes initialized back in a list. For big dump files or lots of data files, this might lead to memory issues. Use __iter__() or at_index() and forget_at_index() to craft a more memory-efficient retrieval mechanism.

Returns:: A list of all Universe objects in the sequence

get_length(self: pylimer_tools_cpp.UniverseSequence) → int¶: Get the number of universes in this sequence.

initialize_from_data_sequence(self: pylimer_tools_cpp.UniverseSequence, data_files: list[str]) → None¶: Reset and initialize the Universes from an ordered list of Lammps data (write_data) files.

initialize_from_dump_file(self: pylimer_tools_cpp.UniverseSequence, initial_data_file: str, dump_file: str) → None¶: Reset and initialize the Universes from a Lammps dump output.

Note

If you have not output the id of the atoms in the dump file, they will be assigned sequentially. If you have not output the type of the atoms in the dump file, they will be set to -1 if they cannot be infered from the data file.

next(self: pylimer_tools_cpp.UniverseSequence) → pylimer_tools_cpp.Universe¶

Get the Universe that’s next in the sequence.

Returns:: The next Universe in the sequence

reset_iterator(self: pylimer_tools_cpp.UniverseSequence) → None¶: Reset the internal iterator, such that a subsequent call to next() returns the first one again.

set_data_file_atom_style(self: pylimer_tools_cpp.UniverseSequence, atom_styles: list[pylimer_tools_cpp.AtomStyle]) → None¶: Set the format of the data files to be read. See AtomStyle.