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

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.

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.

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.

shapedef

An ordered dictionary of instances of Shape.

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

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.