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.position # MxNx3 traj.orientation # MxNx4 traj.typeid # MxN
or by individual frames:
first_frame = traj[0] last_frame = traj[-1] n_th_frame = traj[n] first_frame.position # Nx3 first_frame.orientation # Nx4 first_frame.types # Nx1
You can iterate through individual frames:
for frame in trajectory: print(frame.position)
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.position[i][0:traj.N[i]]
Returns: frame sizes as array with length M Return type: numpy.ndarray
(dtype=numpy.int_
)Raises: RuntimeError – When accessed before calling load_arrays()
orload()
.
-
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()
-
box
¶ Access the frame boxes as a NumPy array.
Returns: frame boxes as an (M) element array Return type: numpy.ndarray
(dtype=numpy.object_
)Raises: RuntimeError – When accessed before calling load_arrays()
orload()
.
-
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 all available trajectory properties into memory.
After calling this function, trajectory properties can be accessed as coherent NumPy arrays:
traj.load_arrays() traj.N # M -- frame sizes traj.position # MxNx3 traj.orientation # MxNx4 traj.typeid # 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.position
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.position
-
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()
.
-
orientation
¶ 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()
.
-
orientations
¶ Deprecated alias for orientation.
Deprecated since version 0.7.0: This will be removed in 0.8.0. This property is deprecated, use orientation instead.
-
position
¶ 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()
.
-
positions
¶ Deprecated alias for position.
Deprecated since version 0.7.0: This will be removed in 0.8.0. This property is deprecated, use position instead.
-
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.
-
typeid
¶ 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
¶ List of type names ordered by type_id.
Returns: particles type names as (MxT) array Return type: numpy.ndarray
(dtype=numpy.str_
)Raises: RuntimeError – When accessed before calling load_arrays()
orload()
.
-
velocities
¶ Deprecated alias for velocity.
Deprecated since version 0.7.0: This will be removed in 0.8.0. This property is deprecated, use velocity instead.
-
velocity
¶ 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. -
N
¶ Number of particles.
-
angmom
¶ Nx4 array of angular momenta for N particles represented as quaternions.
-
charge
¶ Nx1 array of charges for N particles.
-
copyto_snapshot
(snapshot)[source]¶ Copy this frame to a HOOMD-blue snapshot.
Deprecated since version 0.7.0: This will be removed in 0.8.0. Use to_hoomd_snapshot.
-
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.
-
classmethod
from_hoomd_snapshot
(snapshot)[source]¶ Constructs a Frame object from a HOOMD-blue snapshot.
Parameters: snapshot – A HOOMD snapshot.
-
image
¶ Nx3 array of periodic images for N particles in 3 dimensions.
-
make_snapshot
()[source]¶ Create a HOOMD-blue snapshot object from this frame.
Deprecated since version 0.7.0: This will be removed in 0.8.0. Use to_hoomd_snapshot with no argument.
-
mass
¶ Nx1 array of masses for N particles.
-
moment_inertia
¶ Nx3 array of principal moments of inertia for N particles in 3 dimensions.
-
orientation
¶ Nx4 array of rotational coordinates for N particles represented as quaternions.
-
orientations
¶ Nx4 array of rotational coordinates for N particles represented as quaternions. Deprecated alias for orientation.
Deprecated since version 0.7.0: This will be removed in 0.8.0. This property is deprecated, use orientation instead.
-
position
¶ Nx3 array of coordinates for N particles in 3 dimensions.
-
positions
¶ Nx3 array of coordinates for N particles in 3 dimensions. Deprecated alias for position.
Deprecated since version 0.7.0: This will be removed in 0.8.0. This property is deprecated, use position instead.
-
shapedef
¶ An ordered dictionary of instances of
Shape
.Deprecated since version 0.7.0: This will be removed in 0.8.0. This property is deprecated, use type_shapes instead. Until its removal, shapedef keys should not be individually set, only the entire dictionary at once.
-
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.
-
type_shapes
¶ T list of shape definitions.
-
typeid
¶ N array of type indices for N particles.
-
types
¶ T array of type names 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. Deprecated alias for velocity.
Deprecated since version 0.7.0: This will be removed in 0.8.0. This property is deprecated, use velocity instead.
-
velocity
¶ 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 triclinic 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.
-