Install & Compatibility
Where this runs
No compatibility data collected yet for this library.
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
simulate
✓ from jax_md import simulate
✗ import jax_md.simulate
jax_md is a package; submodules must be imported explicitly.
energy
✓ from jax_md import energy
✗ import jax_md.energy
Same as above.
space
✓ from jax_md import space
✗ import jax_md.space
Same pattern.
partition
✓ from jax_md import partition
✗ import jax_md.partition
Neighbor list partitioning.
A basic NVE (constant energy) simulation of soft spheres in 2D with a periodic box and neighbor lists.
import jax
import jax.numpy as jnp
from jax_md import simulate, energy, space, quantity
# Set up a simple cubic lattice of particles
dimension = 2
box_size = 5.0
displacement_fn, shift_fn = space.periodic(box_size)
# Create positions on a lattice
N = 9
lattice = space.initialize_canonical_lattice(N, box_size=box_size, dim=dimension, center=[0.0, 0.0])
positions = lattice['position']
# Define a soft sphere interaction
energy_fn = energy.soft_sphere(displacement_fn, sigma=1.0, epsilon=1.0)
# Initialize neighbor list
neighbor_fn = partition.neighbor_list(displacement_fn, box_size, r_cutoff=2.5, capacity_multiplier=1.2)
neighbor_list = neighbor_fn.allocate(positions)
# Wrap energy function with neighbor list
def total_energy(R, **kwargs):
return energy_fn(R, neighbor_list.idx)
# Run simulation with NVE
init, apply = simulate.nve(energy_fn, shift_fn, dt=0.001, T0=1.0)
state = init(jax.random.PRNGKey(0), positions, neighbor_list=neighbor_list)
# Simulate for 100 steps
for i in range(100):
state = apply(state, neighbor_list=neighbor_list)
if i % 10 == 0:
print(f'Step {i}, KE={quantity.kinetic_energy(state.velocity, state.mass):.3f}')
print('Quickstart complete.')
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'jax_md'
Package not installed.
fixRun `pip install jax-md`.
AttributeError: module 'jax_md' has no attribute 'simulate'
Incorrect import: using `import jax_md; jax_md.simulate` instead of explicit submodule import.
fixUse `from jax_md import simulate`.
TypeError: smooth_barrier() missing 1 required positional argument: 'displacement_fn'
Energy functions require displacement function as first argument.
fixPass the displacement function: `energy.smooth_barrier(displacement_fn, ...)`.
jax.errors.UnexpectedTracerError: Cannot differentiate with respect to argument 0
Attempting to differentiate through a function that uses a non-differentiable operation (e.g., neighbor list construction inside a loop).
fixConstruct neighbor lists outside the differentiated function, e.g., pre-allocate and pass as static argument.
Upgrade
Version history
0.2.28latest on PyPI · released Mar 22, 2026
Audit
Dependencies
jaxrequiredJAX-MD is built on JAX; must have compatible version (jax>=0.4).
jaxliboptionalProvides XLA backend; required for GPU support.
dm-haikuoptionalUsed for neural network potentials (optional).
optaxoptionalUsed for optimization routines (optional).