freud

3.5.0 verified Fri May 01 auth: no python

Freud is a Python library for powerful, efficient trajectory analysis in scientific Python, targeting molecular dynamics and particle-based simulations. Version 3.5.0 supports Python >=3.12, uses abi3 wheels, and is released on a regular cadence (quarterly or more).

pip install freud-analysis

Common errors

error ModuleNotFoundError: No module named 'freud' ↓

cause Package name is 'freud-analysis' on PyPI, not 'freud'.

fix

pip install freud-analysis

error AttributeError: module 'freud' has no attribute 'Box' ↓

cause Box is in freud.box submodule, not top-level.

fix

from freud.box import Box

error TypeError: RDF.compute() got an unexpected keyword argument 'normalize' ↓

cause In freud v3.0.0, 'normalize' was renamed to 'normalization_mode'.

fix

Replace normalize=True with normalization_mode='default' (or other valid mode).

error ValueError: Shape mismatch: quaternion array must have shape (N,4) ↓

cause freud.order.Nematic in v3.0.0+ expects orientation vectors (N,3) instead of quaternions.

fix

Pass orientation vectors (e.g., directors) of shape (N,3).

Warnings

breaking In freud v3.0.0, the 'normalize' argument to freud.density.RDF was renamed to 'normalization_mode'. ↓

fix Use 'normalization_mode' instead of 'normalize'.

breaking In freud v3.0.0, freud.order.Nematic uses orientation vectors instead of quaternions. Old code using quaternions will break. ↓

fix Pass orientation vectors (shape (N,3)) instead of quaternions (shape (N,4)).

breaking freud v3.0.0 removed freud.order.Translational. It was already deprecated. ↓

fix Use freud.order.Translational? (no direct replacement, check documentation).

deprecated Support for Python 3.8, 3.9, 3.10, 3.11 removed in freud v3.5.0 (requires >=3.12). ↓

fix Use Python 3.12+.

gotcha NeighborList from certain compute objects may become invalid if the compute object is garbage collected (fixed in v2.13.0). ↓

fix Upgrade to v2.13.0+ or keep a reference to the compute object.

Imports

freud
wrong
```
from freud import ...
```
correct
```
import freud
```
Top-level package. Use freud.box, freud.density, freud.order etc.
Box
wrong
```
import freud.box.Box
```
correct
```
from freud.box import Box
```
Box is a class in freud.box module.

RDF

wrong

from freud import RDF

correct

from freud.density import RDF

RDF is in freud.density, not top-level.

NeighborList

wrong

import freud.NeighborList

correct

from freud.locality import NeighborList

NeighborList is in freud.locality.

Quickstart

Create a box, random points, compute RDF and neighbor list.

import freud
import numpy as np

# Create a simulation box and random points
box = freud.box.Box.cube(10.0)
points = np.random.uniform(-5, 5, (100, 3))

# Compute radial distribution function
rdf = freud.density.RDF(bins=100, r_max=5.0)
rdf.compute(system=(box, points))
print(rdf.r, rdf.rdf)

# Compute neighbors
nlist = freud.locality.LinkCell().compute(system=(box, points), num_neighbors=6)
print(nlist.nlist.id_i, nlist.nlist.id_j)