freud

DOI PyPI conda-forge ReadTheDocs Binder Codecov GitHub-Stars

Danger

freud v2.0 is currently in beta on the master branch. That’s right – freud just got a whole lot… beta. (Pun intended.) This major rewrite of the freud library brings new APIs, speedups, and many new features. Please report any issues you encounter while using the beta or learning the new API.

Overview

The freud Python library provides a simple, flexible, powerful set of tools for analyzing trajectories obtained from molecular dynamics or Monte Carlo simulations. High performance, parallelized C++ is used to compute standard tools such as radial distribution functions, correlation functions, and clusters, as well as original analysis methods including potentials of mean force and torque (PMFTs) and local environment matching. The freud library uses NumPy arrays for input and output, enabling integration with the scientific Python ecosystem for many typical materials science workflows.

When using freud to process data for publication, please use this citation.

Installation

The easiest ways to install freud are using pip:

pip install freud-analysis

or conda:

conda install -c conda-forge freud

freud is also available via containers for Docker or Singularity. If you need more detailed information or wish to install freud from source, please refer to the Installation Guide to compile freud from source.

Resources

Some other helpful links for working with freud:

Examples

The freud library is called using Python scripts. Many core features are demonstrated in the freud documentation. The examples come in the form of Jupyter notebooks, which can also be downloaded from the freud examples repository or launched interactively on Binder. Below is a script that computes the radial distribution function.

import freud

# Create a freud compute object (rdf is the canonical example)
rdf = freud.density.RDF(rmax=5, dr=0.1)

# Load in your data (freud does not provide a data reader)
box_data = np.load("path/to/box_data.npy")
pos_data = np.load("path/to/pos_data.npy")

# Create freud box
box = freud.box.Box(Lx=box_data[0]["Lx"], Ly=box_data[0]["Ly"], is2D=True)

# Compute RDF
rdf.compute(box, pos_data[0], pos_data[0])
# Get bin centers, RDF data
r = rdf.R
y = rdf.RDF

Support and Contribution

Please visit our repository on GitHub for the library source code. Any issues or bugs may be reported at our issue tracker, while questions and discussion can be directed to our forum. All contributions to freud are welcomed via pull requests!

Indices and tables