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 ='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.

DCD files are among the most familiar simulation outputs due to their longevity.Here, we provide an example that reads data from a DCD file.

import MDAnalysisreader = MDAnalysis.coordinates.DCD.DCDReader('trajectory.dcd')for frame in reader: rdf.compute(system=frame, reset=False)

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), 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'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(, 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), 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

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('', max_rows=1))traj = np.genfromtxt( '', skip_header=2, invalid_raise=False)[:, 1:4].reshape(-1, N, 3)box = 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.

Other External Readers

For many trajectory formats, high-quality readers already exist.However sometimes these readers’ data structures must be converted into a format understood by freud.Below, we show an example that converts the MDAnalysis box dimensions from a matrix into a that MDAnalysis inputs are natively supported by freud without this extra step.For other formats not supported by a reader listed above, a similar process can be followed.

import MDAnalysisreader = MDAnalysis.coordinates.DCD.DCDReader('trajectory.dcd')for frame in reader: box = rdf.compute(system=(box, frame.positions), reset=False)
Reading Simulation Data for freud (2024)


Top Articles
Latest Posts
Article information

Author: Kelle Weber

Last Updated:

Views: 5760

Rating: 4.2 / 5 (73 voted)

Reviews: 80% of readers found this page helpful

Author information

Name: Kelle Weber

Birthday: 2000-08-05

Address: 6796 Juan Square, Markfort, MN 58988

Phone: +8215934114615

Job: Hospitality Director

Hobby: tabletop games, Foreign language learning, Leather crafting, Horseback riding, Swimming, Knapping, Handball

Introduction: My name is Kelle Weber, I am a magnificent, enchanting, fair, joyous, light, determined, joyous person who loves writing and wants to share my knowledge and understanding with you.