particletools package

particletools.analyze

Functions to analyze a particle based trajectory.

particletools.analyze module

Functions to analyze a particle based trajectory.

particletools.analyze.calc_S(q_arr, r_arr, rdf, rho0)

Calculate the structure factor from the radial distribution function. See page 73 of Allen and Tildesley (2nd edition) for more.

Parameters:

• q_arr – A 1D numpy array of scattering length values to use in calculating the structure factor.

• r_arr – A 1D numpy array of radius values used in calculating the rdf.

• rdf – The radial distribution function for a frame of a simulation stored as a 1D numpy array with dimension radius (matches r_arr).

• rho0 – The bulk density for the particles used in calculating the rdf stored as a float.

Returns:

The structure factor stored as a 1D numpy array with dimension scattering length (matches q_arr).

particletools.analyze.calc_msd(traj_unwrap)

Count the number of particles separated by a vector rij for each frame. rij is equal to the position vector of particle j minus the position vector of particle i.

Parameters:

traj_unwrap – The unwrapped trajectory of each particle stored as a 3D numpy array with dimensions ‘frame (ascending order) by particle ID (ascending order) by particle position (x, y, z)’.

Returns:

The mean-squared displacement of an unwrapped trajectory stored as a 1D numpy array with dimension frame (ascending order).

particletools.analyze.calc_rdf(pos, box_config, r_arr)

Calculate the radial distribution function for a frame of a simulation.

Parameters:

• pos – The position of each particle stored as a 2D numpy array with dimensions ‘particle ID (ascending order) by particle position (x, y, z)’.

• box_config – The simulation box configuration stored as a 1D numpy array of length 6 with the first three elements being box length (lx, ly, lz) and the last three being tilt factors (xy, xz, yz)’.

• r_arr – A 1D numpy array of radius values to use in calculating the rdf.

Returns:

The radial distribution function for a frame of a simulation stored as a 1D numpy array with dimension radius (matches r_arr).

particletools.analyze.calc_rg(pos, mass)

Calculate the radius of gyration for a molecule. The radius of gyration is the mass-averaged distance between the particles of a molecule and the molecule’s center of mass.

Parameters:

• pos – The position of each particle stored as a 2D numpy array with dimensions ‘particle ID (ascending order) by particle position (x, y, z)’.

• mass – The mass of each particle stored as a 1D numpy array with dimension ‘particle ID (ascending order)’.

Returns:

The radius of gyration of the molecule stored as a float.

particletools.analyze.calc_rgt(pos, mass)

Calculate the radius of gyration tensor for a molecule. The radius of gyration tensor is a 3 by 3 matrix that describes the shape of a molecule. Each element is effectively a squared radius of gyration calculation in 1 dimension or a convolution of 2 dimensions. When diagonlized, the radius of gyration tensor returns the squared radius of gyration through a sum of the diagonal elements.

Parameters:

• pos – The position of each particle stored as a 2D numpy array with dimensions ‘particle ID (ascending order) by particle position (x, y, z)’.

• mass – The mass of each particle stored as a 1D numpy array with dimension ‘particle ID (ascending order)’.

Returns:

The radius of gyration tensor of a molecule stored as a 2D numpy array with dimensions 1st axis (x, y, z) by 2nd axis (x, y, z).

particletools.analyze.center_traj(traj, molid, mass, box_config, axis, method='SYSTEM', ccut=350)

Center a trajectory along a given axis using the given method.

Parameters:

• traj – The trajectory of each particle stored as a 3D numpy array with dimensions ‘frame (ascending order) by particle ID (ascending order) by particle position (x, y, z)’.

• molid – The molecule ID of each particle stored as a 1D numpy array with dimension ‘particle ID (ascending order)’.

• mass – The mass of each particle stored as a 1D numpy array with dimension ‘particle ID (ascending order)’.

• box_config – The simulation box configuration stored as a 1D numpy array of length 6 with the first three elements being box length (lx, ly, lz) and the last three being tilt factors (xy, xz, yz)’.

• axis – The axis along which to center the trajectory.

• method – The centering method used when calculating the density profile. Method can have values of ‘SYSTEM’ (all particle positions are shifted so that the entire system’s center of mass is at the center of the chosen axis) or ‘SLAB’ (all particle positions are shifted so that the largest cluster of particles’ center of mass is at the center of the chosen axis).

• ccut – The cluster cutoff used for determining clusters in the ‘SLAB’ centering method. For computational tractability, molecules are clustered together instead of particles, and ccut is the maximum distance a molecule can be from the closest molecule in the same cluster.

Returns:

The centered trajectory of each particle stored as a 3D numpy array with dimensions ‘frame (ascending order) by particle ID (ascending order) by particle position (x, y, z)’.

particletools.analyze.density_from_frame(pos, molid, mass, box_config, selection, bin_axis, nbins, centering='NONE', ccut=350)

Calculate the density profile of the selected particles along a given axis for a single frame.

Parameters:

• pos – The position of each particle stored as a 2D numpy array with dimensions ‘particle ID (ascending order) by particle position (x, y, z)’.

• molid – The molecule ID of each particle stored as a 1D numpy array with dimension ‘particle ID (ascending order)’.

• mass – The mass of each particle stored as a 1D numpy array with dimension ‘particle ID (ascending order)’.

• box_config – The simulation box configuration stored as a 1D numpy array of length 6 with the first three elements being box length (lx, ly, lz) and the last three being tilt factors (xy, xz, yz)’.

• selection – The selected particles chosen for this calculation stored as a 1D numpy array with dimension ‘particle ID’ (ascending order). For example, for density_from_frame, the particles making up the density returned are just the selected particles.

• bin_axis – The axis along which bins are generated for counting particles. In most cases, the bin_axis can have a value of 0 (x-axis), 1 (y-axis), or 2 (z-axis).

• nbins – The number of bins to generate for counting particles.

• centering – The centering method used when calculating the density profile. Centering can have values of ‘NONE’ (no centering is performed), ‘SYSTEM’ (all particle positions are shifted so that the system’s center of mass is at the center of the profile), or ‘SLAB’ (all particle positions are shifted so that the largest cluster of particles is at the center of the profile).

• ccut – The cluster cutoff used for determining clusters in the ‘SLAB’ centering method. For efficiency, molecules are clustered together instead of particles, and ccut is the maximum distance a molecule can be from the closest molecule in the same cluster.

Returns:

The density profile of the selected particles along a given axis stored as a 2D numpy array with dimensions ‘bin index by bin properties (position along the axis, density at that position).

particletools.analyze.density_from_traj(traj, molid, mass, box_config, selection, bin_axis, nbins, centering='NONE', ccut=350)

Calculate the average density profile of the selected particles along a given axis for every frame.

Parameters:

• traj – The trajectory of each particle stored as a 3D numpy array with dimensions ‘frame (ascending order) by particle ID (ascending order) by particle position (x, y, z)’.

• molid – The molecule ID of each particle stored as a 1D numpy array with dimension ‘particle ID (ascending order)’.

• mass – The mass of each particle stored as a 1D numpy array with dimension ‘particle ID (ascending order)’.

• box_config – The simulation box configuration stored as a 1D numpy array of length 6 with the first three elements being box length (lx, ly, lz) and the last three being tilt factors (xy, xz, yz)’.

• selection – The selected particles chosen for this calculation stored as a 1D numpy array with dimension ‘particle ID’ (ascending order). For example, for density_from_frame, the particles making up the density returned are just the selected particles.

• bin_axis – The axis along which bins are generated for counting particles. In most cases, the bin_axis can have a value of 0 (x-axis), 1 (y-axis), or 2 (z-axis).

• nbins – The number of bins to generate for counting particles.

• centering – The centering method used when calculating the density profile. Centering can have values of ‘NONE’ (no centering is performed), ‘SYSTEM’ (all particle positions are shifted so that the system’s center of mass is at the center of the profile), or ‘SLAB’ (all particle positions are shifted so that the largest cluster of particles is at the center of the profile).

• ccut – The cluster cutoff used for determining clusters in the ‘SLAB’ centering method. For efficiency, molecules are clustered together instead of particles, and ccut is the maximum distance a molecule can be from the closest molecule in the same cluster.

Returns:

The density profile of the selected particles along a given axis per frame stored as a 3D numpy array with dimensions ‘frame (ascending order) by bin index by bin properties (position along the axis, density at that position)’.

particletools.analyze.img_flags_from_traj(traj_wrap, box_config)

Estimate image flags from a trajectory.

Calculate the image flags of a wrapped particle-based trajectory. This assumes that the dump frequency is sufficiently high such that particles never travel more than half the length of a box dimension, otherwise image flags may be incorrect. Molecules that are spread across a periodic boundary will have incorrect image flags, potentially introducing errors in other calculations. Assumes that the box dimensions are constant in time.

Parameters:

• traj_wrap – The wrapped trajectory of each particle stored as a 3D numpy array with dimensions ‘frame (ascending order) by particle ID (ascending order) by particle position (x, y, z)’.

• box_config – The simulation box configuration stored as a 1D numpy array of length 6 with the first three elements being box length (lx, ly, lz) and the last three being tilt factors (xy, xz, yz).

Returns:

The image flags of the particles across the trajectory stored as a 3D numpy array with dimensions ‘frame (ascending order) by particle ID (ascending order) by particle image flag (ix, iy, iz)’.

particletools.analyze.meshgrid3D(x, y, z)

Create a 3D mesh and return the gridpoints of that mesh for the x, y, and z axes. Analagous to np.meshgrid(x, y, z, indexing=’ij’), except meshgrid3D is compatible with Numba’s jit compilation in nopython mode.

Parameters:

• x – The x-axis values of the 3D mesh stored as a 1D numpy array with dimension ‘x-index’.

• y – The y-axis values of the 3D mesh stored as a 1D numpy array with dimension ‘y-index’.

• z – The z-axis values of the 3D mesh stored as a 1D numpy array with dimension ‘z-index’.

Returns:

The gridpoint values of each axis in the 3D mesh stored as a 4D numpy array with dimension ‘axis (x, y, z) by x-index by y-index by z-index’.

particletools.analyze.mol_com_from_frame(pos, molid, mass)

Calculate the center of mass and mass of each molecule for a single frame of their trajectory.

Parameters:

• pos – The position of each particle stored as a 2D numpy array with dimensions ‘particle ID (ascending order) by particle position (x, y, z)’.

• molid – The molecule ID of each particle stored as a 1D numpy array with dimension ‘particle ID (ascending order)’.

• mass – The mass of each particle stored as a 1D numpy array with dimension ‘particle ID (ascending order)’.

Returns:

A tuple where the first element is the center of mass of each molecule stored as a 2D numpy array with dimensions ‘molecule ID (ascending order) by molecule center of mass (x, y, z)’. The second element is the mass of each molecule stored as a 1D numpy array with dimension ‘molecule ID (asecnding order)’.

particletools.analyze.mol_com_from_traj(traj, molid, mass)

Calculate the center of mass and mass of each molecule for every frame.

Parameters:

• traj – The trajectory of each particle stored as a 3D numpy array with dimensions ‘frame (ascending order) by particle ID (ascending order) by particle position (x, y, z)’.

• molid – The molecule ID of each particle stored as a 1D numpy array with dimension ‘particle ID (ascending order)’.

• mass – The mass of each particle stored as a 1D numpy array with dimension ‘particle ID (ascending order)’.

Returns:

A tuple where the first element is the center of mass of each molecule for every frame stored as a 2D numpy array with dimensions ‘frame (ascending order) by molecule ID (ascending order) by molecule center of mass (x, y, z)’. The second element is the mass of each molecule stored as a 1D numpy array with dimension ‘molecule ID (asecnding order)’.

particletools.analyze.rijcnt_from_frame(pos, box_config, rijgrid, rcut)

Count the number of particles separated by a vector rij for a single frame. rij is equal to the position vector of particle j minus the position vector of particle i.

Parameters:

• pos – The position of each particle stored as a 2D numpy array with dimensions ‘particle ID (ascending order) by particle position (x, y, z)’.

• box_config – The simulation box configuration stored as a 1D numpy array of length 6 with the first three elements being box length (lx, ly, lz) and the last three being tilt factors (xy, xz, yz)’.

• rijgrid – The gridpoint values of each axis in the 3D mesh, that the rij vector is placed on, stored as a 4D numpy array with dimension ‘axis (x, y, z) by x-index by y-index by z-index’.

• rcut – The rij vector cutoff used to determine the maximum length the rij vector can be along a single axis. Due to the minimum image convention, rcut cannot be greater than the shortest simulation box length.

Returns:

The number of particles separated by a vector rij stored as a 3D numpy array with dimensions ‘x-index by y-index by z-index’, where these indices are the indices of the rij vector placed on the 3D mesh defined by rijgrid.

particletools.analyze.rijcnt_from_traj(traj, box_config, rijgrid, rcut)

Count the number of particles separated by a vector rij for each frame. rij is equal to the position vector of particle j minus the position vector of particle i.

Parameters:

• traj – The trajectory of each particle stored as a 3D numpy array with dimensions ‘frame (ascending order) by particle ID (ascending order) by particle position (x, y, z)’.

• box_config – The simulation box configuration stored as a 1D numpy array of length 6 with the first three elements being box length (lx, ly, lz) and the last three being tilt factors (xy, xz, yz)’.

• rijgrid – The gridpoint values of each axis in the 3D mesh, that the rij vector is placed on, stored as a 4D numpy array with dimension ‘axis (x, y, z) by x-index by y-index by z-index’.

• rcut – The rij vector cutoff used to determine the maximum length the rij vector can be along a single axis. Due to the minimum image convention, rcut cannot be greater than the shortest simulation box length.

Returns:

The number of particles separated by a vector rij per frame stored as a 4D numpy array with dimensions ‘frame (ascending order) by x-index by y-index by z-index’, where these indices are the indices of the rij vector placed on the 3D mesh defined by rijgrid.

particletools.analyze.unwrap_traj(traj_wrap, box_config, img_flags)

Calculate the unwrapped trajectory of a particle-based trajectory using the trajectory’s image flags and the simluation box configuration. Assumes that the box dimensions are constant in time.

Parameters:

• traj_wrap – The wrapped trajectory of each particle stored as a 3D numpy array with dimensions ‘frame (ascending order) by particle ID (ascending order) by particle position (x, y, z)’.

• box_config – The simulation box configuration stored as a 1D numpy array of length 6 with the first three elements being box length (lx, ly, lz) and the last three being tilt factors (xy, xz, yz)’.

• img_flags – The image flags of the particles across the trajectory stored as a 3D numpy array with dimensions ‘frame (ascending order) by particle ID (ascending order) by particle image flag (ix, iy, iz)’.

Returns:

The unwrapped trajectory of each particle stored as a 3D numpy array with dimensions ‘frame (ascending order) by particle ID (ascending order) by particle position (x, y, z)’.