Reading Simulation Data for freud (2024)

The freud package is designed for maximum flexibility by making minimal assumptions about its data.However, users accustomed to the more restrictive patterns of most other tools may find this flexibility confusing.In particular, knowing how to provide data from specific simulation sources can be a significant source of confusion.This page is intended to describe how various types of data may be converted into a form suitable for freud.

To simplify the examples below, we will assume in all cases that the user wishes to compute a radial distribution function over all frames in the trajectory and that the following code has already been run:

import freudrdf = freud.density.RDF(bins=50, r_max=5)

Native Integrations¶

The freud library offers interoperability with several popular tools for particle simulations, analysis, and visualization.Below is a list of file formats and tools that are directly supported as “system-like” objects (see freud.locality.NeighborQuery.from_system).Such system-like objects are data containers that store information about a periodic box and particle positions.Other attributes, such as particle orientations, are not included automatically in the system representation and must be loaded as separate NumPy arrays.

GSD Trajectories¶

Using the GSD Python API, GSD files can be easily integrated with freud as shown in the Quickstart Guide.This format is natively supported by HOOMD-blue.Note: the GSD format can also be read by MDAnalysis and garnett.Here, we provide an example that reads data from a GSD file.

import gsd.hoomdtraj = gsd.hoomd.open('trajectory.gsd', 'rb')for frame in traj: rdf.compute(system=frame, reset=False)

MDAnalysis Readers¶

The MDAnalysis package can read many popular trajectory formats, including common output formats from CHARMM, NAMD, LAMMPS, Gromacs, Tinker, AMBER, GAMESS, HOOMD-blue, and more.

MDTraj Readers¶

The MDTraj package can read many popular trajectory formats, including common output formats from AMBER, MSMBuilder2, Protein Data Bank files, OpenMM, Tinker, Gromacs, LAMMPS, HOOMD-blue, and more.

To use data read with MDTraj in freud, a system-like object must be manually constructed because it does not have a “frame-like” object containing information about the periodic box and particle positions (both quantities are provided as arrays over the whole trajectory).Here, we provide an example of how to construct a system:

import mdtrajtraj = mdtraj.load_xtc('output/prd.xtc', top='output/prd.gro')for system in zip(np.asarray(traj.unitcell_vectors), traj.xyz): rdf.compute(system=system, reset=False)

garnett Trajectories¶

The garnett package can read several trajectory formats that have historically been supported by the HOOMD-blue simulation engine, as well as other common types such as DCD and CIF.The garnett package will auto-detect supported file formats by the file extension.Here, we provide an example that reads data from a POS file.

import garnettwith garnett.read('trajectory.pos') as traj: for frame in traj: rdf.compute(system=frame, reset=False)

OVITO Modifiers¶

The OVITO Open Visualization Tool supports user-written Python modifiers.The freud package can be installed alongside OVITO to enable user-written Python script modifiers that leverage analyses from freud.Below is an example modifier that creates a user particle property in the OVITO pipeline for Steinhardt bond order parameters.

import freuddef modify(frame, data): ql = freud.order.Steinhardt(l=6) ql.compute(system=data, neighbors={'num_neighbors': 6}) data.create_user_particle_property( name='ql', data_type=float, data=ql.ql) print('Created ql property for {} particles.'.format(data.particles.count))

HOOMD-blue Snapshots¶

HOOMD-blue supports analyzers, callback functions that can perform analysis.Below is an example demonstrating how to use an anlyzer to log the Steinhardt bond order parameter \(q_6\) during the simulation run.

import hoomdfrom hoomd import mdimport freudhoomd.context.initialize()# Create a 10x10x10 simple cubic lattice of particles with type name Asystem = hoomd.init.create_lattice( unitcell=hoomd.lattice.sc(a=2.0, type_name='A'), n=10)# Specify Lennard-Jones interactions between particle pairsnl = md.nlist.cell()lj = md.pair.lj(r_cut=3.0, nlist=nl)lj.pair_coeff.set('A', 'A', epsilon=1.0, sigma=1.0)# Integrate at constant temperaturemd.integrate.mode_standard(dt=0.005)hoomd.md.integrate.langevin(group=hoomd.group.all(), kT=1.2, seed=4)# Create a Steinhardt object to analyze snapshotsql = freud.order.Steinhardt(l=6)def compute_q6(timestep): snap = system.take_snapshot() ql.compute(system=snap, neighbors={'num_neighbors': 6}) return ql.order# Register a logger that computes q6 and saves to a fileql_logger = hoomd.analyze.log(filename='ql.dat', quantities=['q6'], period=100)ql_logger.register_callback('q6', compute_q6)# Run for 10,000 time stepshoomd.run(10e3)

Reading Text Files¶

Typically, it is best to use one of the natively supported data readers described above; however it is sometimes necessary to parse trajectory information directly from a text file.One example of a plain text format is the XYZ file format, which can be generated and used by many tools for particle simulation and analysis, including LAMMPS and VMD.Note that various readers do exist for XYZ files, including MDAnalysis, but in this example we read the file manually to demonstrate how to read these inputs as plain text.Though they are easy to parse, XYZ files usually contain no information about the system box, so this must already be known by the user.Assuming knowledge of the box used in the simulation, a LAMMPS XYZ file could be used as follows:

N = int(np.genfromtxt('trajectory.xyz', max_rows=1))traj = np.genfromtxt( 'trajectory.xyz', skip_header=2, invalid_raise=False)[:, 1:4].reshape(-1, N, 3)box = freud.box.Box.cube(L=20)for frame_positions in traj: rdf.compute(system=(box, frame_positions), reset=False)

The first line is the number of particles, so we read this line and use it to determine how to reshape the contents of the rest of the file into a NumPy array.