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() or load().
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() or load().
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() or load().
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() or load().
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() or load().
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() or load().
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
loaded()[source]

Returns True if all frames are loaded into memory.

See also: load()

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() or load().
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() or load().
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() or load().
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() or load().
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() or load().
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() or load().
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() or load().

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.

box

Instance of Box

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.

load()[source]

Load the frame into memory.

loaded()[source]

Returns True if the frame is loaded into memory.

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_hoomd_snapshot(snapshot=None)[source]

Copy this frame to a HOOMD-blue snapshot.

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).

get_box_array()[source]

Returns the box parameters as a 6-element list.

get_box_matrix()[source]

Returns the box matrix (3x3).

The dimensions (Lx,Ly,Lz) are the diagonal.

round(decimals=0)[source]

Return box instance with all values rounded up to the given precision.

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.