Trajectory API¶
Instances of Trajectory
give access to trajectory data stored in files and file-like objects.
In the simplest case, trajectories are just a sequence of Frame
instances.
Trajectories¶
-
class
garnett.trajectory.
Trajectory
(frames=None, dtype=None)[source]¶ Manages a particle trajectory data resource.
A trajectory is basically a sequence of
Frame
instances.Trajectory data can either be accessed as coherent numpy arrays:
traj.load_arrays() M = len(traj) traj.N # M traj.positions # MxNx3 traj.orientations # MxNx4 traj.types # MxN traj.type_ids # MxN
or by individual frames:
first_frame = traj[0] last_frame = traj[-1] n_th_frame = traj[n] first_frame.positions # Nx3 first_frame.orientations # Nx4 first_frame.types # Nx1
You can iterate through individual frames:
for frame in trajectory: print(frame.positions)
and create a sub-trajectory from the i’th to the (j-1)’th frame:
sub_trajectory = traj[i:j]
Parameters: - frames (
Frame
) – The individual frames of this trajectory. - dtype – The default data type for trajectory data.
-
N
¶ Access the frame sizes as a numpy array.
Mostly important when the trajectory has varying size.
pos_i = traj.positions[i][0:traj.N[i]]
Returns: frame size as array with length M Return type: numpy.ndarray
(dtype=numpy.int_
)Raises: RuntimeError – When accessed before calling load_arrays()
orload()
.
-
TRAJ_ATTRIBUTES
= ['N', 'type', 'types', 'type_ids', 'positions', 'orientations', 'velocities', 'mass', 'charge', 'diameter', 'moment_inertia', 'angmom', 'image']¶
-
angmom
¶ Access the particle angular momenta as a numpy array.
Returns: particle angular momenta quaternions as (Nx4) element array Return type: numpy.ndarray
Raises: RuntimeError – When accessed before calling load_arrays()
orload()
.
-
arrays_loaded
()[source]¶ Returns true if arrays are loaded into memory.
See also:
load_arrays()
-
charge
¶ Access the particle charge as a numpy array.
Returns: particle charge as (N) element array Return type: numpy.ndarray
Raises: RuntimeError – When accessed before calling load_arrays()
orload()
.
-
diameter
¶ Access the particle diameter as a numpy array.
Returns: particle diameter as (N) element array Return type: numpy.ndarray
Raises: RuntimeError – When accessed before calling load_arrays()
orload()
.
-
image
¶ Access the particle periodic images as a numpy array.
Returns: particle periodic images as (Nx3) element array Return type: numpy.ndarray
Raises: RuntimeError – When accessed before calling load_arrays()
orload()
.
-
load
()[source]¶ Load all frames into memory.
By default, only frames which are accessed are loaded into memory. Using this function, all frames are loaded at once.
This can be useful, e.g., if the trajectory resource cannot remain open, however in all other cases this should be avoided.
See also:
load_arrays()
-
load_arrays
()[source]¶ Load positions, orientations and types into memory.
After calling this function, positions, orientations and types can be accessed as coherent numpy arrays:
traj.load_arrays() traj.N # M -- frame sizes traj.positions # MxNx3 traj.orientations # MxNx4 traj.types # MxN traj.type_ids # MxN
Note
It is not necessary to call this function again when accessing sub trajectories:
traj.load_arrays() sub_traj = traj[m:n] sub_traj.positions
However, it may be more efficient to call
load_arrays()
only for the sub trajectory if other data is not of interest:sub_traj = traj[m:n] sub_traj.load_arrays() sub_traj.positions
-
mass
¶ Access the particle mass as a numpy array.
Returns: particle mass as (N) element array Return type: numpy.ndarray
Raises: RuntimeError – When accessed before calling load_arrays()
orload()
.
-
moment_inertia
¶ Access the particle principal moment of inertia components as a numpy array.
Returns: particle principal moment of inertia components as (Nx3) element array Return type: numpy.ndarray
Raises: RuntimeError – When accessed before calling load_arrays()
orload()
.
-
orientations
¶ Access the particle orientations as a numpy array.
Orientations are stored as quaternions.
Returns: particle orientations as (Nx4) array Return type: numpy.ndarray
Raises: RuntimeError – When accessed before calling load_arrays()
orload()
.
-
positions
¶ Access the particle positions as a numpy array.
Returns: particle positions as (Nx3) array Return type: numpy.ndarray
Raises: RuntimeError – When accessed before calling load_arrays()
orload()
.
-
set_dtype
(value)[source]¶ Change the data type of this trajectory.
This function cannot be called if any frame is already loaded.
Parameters: value – The new data type value.
-
type
¶ List of type names ordered by type_id.
Use the type list to map between type_ids and type names:
type_name = traj.type[type_id]
See also:
type_ids
Returns: particle types in order of type id. Return type: list Raises: RuntimeError – When accessed before calling load_arrays()
orload()
.
-
type_ids
¶ Access the particle type ids as a numpy array.
See also:
type
Returns: particle type ids as (MxN) array. Return type: numpy.ndarray
(dtype=numpy.int_
)Raises: RuntimeError – When accessed before calling load_arrays()
orload()
.
-
types
¶ Access the particle types as a numpy array.
Returns: particles types as (MxN) array Return type: numpy.ndarray
(dtype=numpy.str_
)Raises: RuntimeError – When accessed before calling load_arrays()
orload()
.
-
velocities
¶ Access the particle velocities as a numpy array.
Returns: particle velocities as (Nx3) array Return type: numpy.ndarray
Raises: RuntimeError – When accessed before calling load_arrays()
orload()
.
- frames (
Frames¶
Trajectory data can be accessed via individual frames.
-
class
garnett.trajectory.
Frame
(dtype=None)[source]¶ A frame is a container object for the actual frame data.
The frame data is read from the origin stream whenever accessed.
Parameters: dtype – The data type for frame data. -
angmom
¶ Nx4 array of angular momenta for N particles represented as quaternions.
-
charge
¶ Nx1 array of charges for N particles.
-
data
¶ A dictionary of lists for each attribute.
-
data_keys
¶ A list of strings, where each string represents one attribute.
-
diameter
¶ Nx1 array of diameters for N particles.
-
dtype
¶ Return the data type for frame data.
-
image
¶ Nx3 array of periodic images for N particles in 3 dimensions.
-
mass
¶ Nx1 array of masses for N particles.
-
moment_inertia
¶ Nx3 array of principal moments of inertia for N particles in 3 dimensions.
-
orientations
¶ Nx4 array of rotational coordinates for N particles represented as quaternions.
-
positions
¶ Nx3 array of coordinates for N particles in 3 dimensions.
-
to_plato_scene
(backend, scene=None)[source]¶ Create a plato scene from this frame.
Parameters: - backend (str) – Backend name to use with plato. The backend must support all primitives corresponding to shapes defined in this frame.
- scene (
plato.draw.Scene
) – Scene object to render into. By default, a new scene is created.
-
types
¶ Nx1 array of types represented as strings.
-
unload
()[source]¶ Unload the frame from memory.
Use this method carefully. This method removes the frame reference to the frame data, however any other references that may still exist, will prevent a removal of said data from memory.
-
velocities
¶ Nx3 array of velocities for N particles in 3 dimensions.
-
view_rotation
¶ A quaternion specifying a rotation that should be applied for visualization.
-
Box¶
The box instance gives access to the box of individual frames.
-
class
garnett.trajectory.
Box
(Lx, Ly, Lz, xy=0.0, xz=0.0, yz=0.0, dimensions=3)[source]¶ A triclinical box class.
You can access the box size and tilt factors via attributes:
# Reading length_x = box.Lx tilt_xy = box.xy # etc. # Setting box.Lx = 10.0 box.Ly = box.Lz = 5.0 box.xy = box.xz = box.yz = 0.01 # etc.
-
Lx
= None¶ The box length in x-direction.
-
Ly
= None¶ The box length in y-direction.
-
Lz
= None¶ The box length in z-direction.
-
dimensions
= None¶ The number of box dimensions (2 or 3).
-
xy
= None¶ The box tilt factor in the xy-plane.
-
xz
= None¶ The box tilt factor in the xz-plane.
-
yz
= None¶ The box tilt factor in the yz-plane.
-