Skip to main content

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:

DOI

Documentation

Full documentation

What can this package do?

Structural analysis

  • Atomic distances, coordination numbers, bond finding, nearest neighbours
  • 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

  • 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
  • MACE machine-learning potentials with fastatomstruct's own engine (CPU and NVIDIA GPUs), 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
  • 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

  • IO (read and write xyz, traj, taco, cif, ...)
  • Lazy access to trajectories larger than memory (fs.io.open): frames decoded on demand, analyses process a few at a time
  • 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.

Metadata

Release files for fastatomstruct 2.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for fastatomstruct 2.3.0
File Actions
fastatomstruct-2.3.0-cp39-abi3-win_amd64.whl CPython 3.9 abi3 Windows x86-64 Details for fastatomstruct-2.3.0-cp39-abi3-win_amd64.whl
fastatomstruct-2.3.0-cp39-abi3-manylinux_2_27_x86_64.whl CPython 3.9 abi3 Linux glibc 2.27+ x86-64 Details for fastatomstruct-2.3.0-cp39-abi3-manylinux_2_27_x86_64.whl
fastatomstruct-2.3.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl CPython 3.9 abi3 Linux glibc 2.17+ ARM64 Details for fastatomstruct-2.3.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
fastatomstruct-2.3.0-cp39-abi3-macosx_13_0_x86_64.whl CPython 3.9 abi3 macOS 13.0+ x86-64 Details for fastatomstruct-2.3.0-cp39-abi3-macosx_13_0_x86_64.whl
fastatomstruct-2.3.0-cp39-abi3-macosx_13_0_arm64.whl CPython 3.9 abi3 macOS 13.0+ ARM64 Details for fastatomstruct-2.3.0-cp39-abi3-macosx_13_0_arm64.whl

Total release size: 169.9 MB

Release files / fastatomstruct-2.3.0-cp39-abi3-win_amd64.whl

Download URL fastatomstruct-2.3.0-cp39-abi3-win_amd64.whl
Size 32.2 MB
Tags CPython 3.9 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
9506a3d06a2d8555ee3b246ad44cc6235a0207a5da0b4d688776de956cda6748
BLAKE2b-256 checksum
How to use checksums
c568ff04932e61284079af81a24e6eecf4a509a25a6d8720b6e4c63bbea6e3e4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.13

Release files / fastatomstruct-2.3.0-cp39-abi3-manylinux_2_27_x86_64.whl

Download URL fastatomstruct-2.3.0-cp39-abi3-manylinux_2_27_x86_64.whl
Size 50.4 MB
Tags CPython 3.9 Linux glibc 2.27+ x86-64 abi3
SHA-256 checksum
How to use checksums
8c75b5f33a840b47a65b60ba3dad9553f3ddce9547ed626cbc919554063fc959
BLAKE2b-256 checksum
How to use checksums
92785a0793da839424a4c367104a86bcb81475c4d38a710a6a80e84426c71a85
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.13

Release files / fastatomstruct-2.3.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

Download URL fastatomstruct-2.3.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Size 27.6 MB
Tags CPython 3.9 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
f813d761cf5e15a7a070fb6bd28aaeb67cd58a85a6ffd8bc350421ea17dc3e67
BLAKE2b-256 checksum
How to use checksums
e05432873afff7b233086cd8ac580bbf294b70733aac23d0ee04bcab86c070de
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.13

Release files / fastatomstruct-2.3.0-cp39-abi3-macosx_13_0_x86_64.whl

Download URL fastatomstruct-2.3.0-cp39-abi3-macosx_13_0_x86_64.whl
Size 31.3 MB
Tags CPython 3.9 abi3 macOS 13.0+ x86-64
SHA-256 checksum
How to use checksums
b5796d6f229bdea1e28358f1dfc6bd182a531083f89fd654938dde164ea321bc
BLAKE2b-256 checksum
How to use checksums
ededf51326b6badc1e015284fabe744d680955ba752895a5f8849cb4a396b2e2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.13

Release files / fastatomstruct-2.3.0-cp39-abi3-macosx_13_0_arm64.whl

Download URL fastatomstruct-2.3.0-cp39-abi3-macosx_13_0_arm64.whl
Size 28.4 MB
Tags CPython 3.9 abi3 macOS 13.0+ ARM64
SHA-256 checksum
How to use checksums
ad53133d7d63636b7e3a3e0b158fc7ec5aa914361d0ea6dbb5ad0d658244d9a0
BLAKE2b-256 checksum
How to use checksums
2e0e4fad98e8a877820843703b69096ec3a28f400fb6bf5eba4b044454102b3f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.13

Security for fastatomstruct 2.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.3.0 This release

5 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page