Fast calculation of structural and dynamical parameters

fastatomstruct is a Python package (mostly written in Rust) that provides fast, parallelised analysis of atomistic simulation data. Thread-based parallelisation via rayon is used throughout to fully exploit multicore processors.

Citation

If you use fastatomstruct in your research, please cite:

Documentation

Full documentation

What can this package do?

Structural analysis

• Atomic distances, coordination numbers, bond finding, nearest neighbours
• Lazy access to trajectories larger than memory (fs.io.open): frames are decoded on demand and analyses process them a few at a time
• Radial distribution function (RDF) and static structure factor
• Bond orientational order (Steinhardt q_l, Q_l) and bond order correlation
• Tetrahedral, octahedral, and trigonal order parameters
• Three-body correlation (TBC, ALTBC) — simple, angular-limited, and angular-resolved
• Bond angle distribution, dihedral angle distribution, bond length ratio, angular-resolved RDF
• Local environment characterisation (Cartesian and cylindrical coordinates)
• Ring size distribution (King's and Guttman's shortest-path algorithms)
• Peierls distortion analysis
• Voids, Steinhardt W_l, common neighbour analysis, Voronoi and polyhedral template matching, mobility clusters, non-affine D², percolation

Dynamical analysis

• Mean squared displacement, non-Gaussian parameter, overlap q
• Four-point correlation functions (χ₄)
• Current correlation functions, velocity autocorrelation
• Vibrational density of states, intermediate scattering functions
• Viscosity (Green–Kubo and NALD), participation ratio, phase quotient, mode-weighted quantities

Force calculators & molecular dynamics

• MACE machine-learning potentials with fastatomstruct's own engine (CPU and NVIDIA GPUs; no mace-torch or PyTorch needed), including foundation models, committees and training
• ACE/PACE potentials, CP2K DFT, built-in Lennard-Jones and EMT, and an adapter for any ASE calculator (VASP, GPAW, Quantum ESPRESSO, …)
• DFT-D2, DFT-D3 and DFT-D4 dispersion corrections
• Molecular dynamics: Velocity Verlet and Langevin integrators; Bussi, Berendsen, Andersen and Nosé-Hoover thermostats; isotropic and semi-isotropic Bussi barostats (NPT); temperature and pressure curves, constraints, checkpoint/resume, measurement hooks
• Structural and cell relaxation (BFGS, L-BFGS-B, FIRE, NAG)
• Active learning (MD, relaxation, random structure search, pool labelling) with MACE committees and a DFT queue
• Parallel computing: MPI worker for snapshot-parallel analyses and domain-decomposition MD for large systems

Phonons & electronic structure

• Finite-displacement phonons with automatic k-paths (band structures, DOS)
• Electronic band structures and DOS from CP2K, COHP/COOP bonding analysis
• Kubo–Greenwood optical spectra, electron–phonon coupling, NEGF transport

Physical units

• fs.units holds units as objects: every dimensional parameter accepts a quantity such as 2 * fs.units.fs or 0.35 * fs.units.nm, checks its dimension and converts it exactly; results in units other than the internal ASE units come back tagged with their unit

Visualisation & tooling

• 3D structure/trajectory rendering (view, view_image, view_interactive, GIF video) and publication plotting via the bundled plot module
• Separate fastatomstruct-ui application (own repository, one-line installer): 3D viewer / file browser, analysis charts, active-learning metrics panel and Avro run-log monitor in one command
• MCP server for LLM agents (fastatomstruct-mcp, separate package)

Example usage

import fastatomstruct as fs

# Lithium BCC supercell
atoms = fs.build.bulk(fs.Element.Li, "bcc", a=3.45, size=(10, 10, 10))

# All pairwise distances
dists = fs.analysis.distance.all_distances(atoms)

# Coordination numbers with a 3 Å cutoff
coordination = fs.analysis.neighbours.coordination_numbers(
    atoms, fs.analysis.distance.CutoffMode.Fixed(3.0)
)

More examples are in the documentation.

Rust API

fastatomstruct can also be used directly in Rust projects. Rust API documentation.

Installation

From PyPI

pip install fastatomstruct

Supported platforms: Windows (x86_64), Linux (x86_64, aarch64), macOS (x86_64, aarch64), Python ≥ 3.9. x86_64 builds require AVX2 support (available on most CPUs since ~2015).

Optional features:

pip install "fastatomstruct[ase]"      # ASE: Atoms.to_ase(), ASE calculator workflows, active learning
pip install "fastatomstruct[plot]"     # matplotlib: the fs.plot_* helpers and phonon plots
pip install "fastatomstruct[xla]"      # MACE on the CPU through XLA (faster)
pip install "fastatomstruct[cuda13]"   # MACE on NVIDIA GPUs (CUDA 13 runtime included)
pip install "fastatomstruct[mace-torch]"   # mace-torch, for MACECalculator(backend="torch") and the default trainer
pip install "fastatomstruct[cp2k]"     # the cp2k-rs package, for NEGF electron transport
pip install fastatomstruct-mcp      # MCP server (Model Context Protocol), separate package

From source

Requirements: Python ≥ 3.9, Rust ≥ 1.98 (install), maturin.

The authoritative build path is the workspace Justfile — the same recipes CI uses (bare maturin build picks the default feature set, which is not what the release wheels contain):

pip install just maturin
just develop          # release build into the current venv (maturin develop --release)
just wheel-linux-x86  # release wheel (manylinux) in target/wheels

Running tests

cargo test          # Rust unit tests
pytest python/test  # Python regression tests (requires pytest)

Telemetry

fastatomstruct sends anonymous performance telemetry (operation name, atom/frame count, CPU type, thread/process count, elapsed time; never coordinates, elements or structure data). Opt out with FASTATOMSTRUCT_NO_TELEMETRY=1 or fastatomstruct.disable_telemetry(); details in the documentation.

Contributing

1. Fork the repository on GitLab.
2. Create a descriptive branch for your feature or bugfix.
3. Commit with clear messages and open a merge request with a detailed description.

Reporting issues & support

Use the GitLab work items page to report bugs or ask for support.