Metadata-Version: 2.4
Name: fastatomstruct
Version: 2.0.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Dist: numpy>=1.24
Requires-Dist: polars>=1.28
Requires-Dist: tomli ; python_full_version < '3.11'
Requires-Dist: ase>=3.22 ; extra == 'ase'
Requires-Dist: pytest ; extra == 'bench'
Requires-Dist: pytest-benchmark ; extra == 'bench'
Requires-Dist: requests ; extra == 'bench'
Requires-Dist: cp2k-rs ; extra == 'cp2k'
Requires-Dist: jax-cuda13-pjrt>=0.10.2,<=0.11.2 ; platform_machine == 'x86_64' and sys_platform == 'linux' and extra == 'cuda13'
Requires-Dist: nvidia-cublas>=13.0.0.19 ; platform_machine == 'x86_64' and sys_platform == 'linux' and extra == 'cuda13'
Requires-Dist: nvidia-cuda-cupti>=13.0.48 ; platform_machine == 'x86_64' and sys_platform == 'linux' and extra == 'cuda13'
Requires-Dist: nvidia-cuda-nvcc>=13.0.48 ; platform_machine == 'x86_64' and sys_platform == 'linux' and extra == 'cuda13'
Requires-Dist: nvidia-cuda-nvrtc>=13.0.48 ; platform_machine == 'x86_64' and sys_platform == 'linux' and extra == 'cuda13'
Requires-Dist: nvidia-cuda-runtime>=13.0.48 ; platform_machine == 'x86_64' and sys_platform == 'linux' and extra == 'cuda13'
Requires-Dist: nvidia-cudnn-cu13>=9.12.0.46,<10.0 ; platform_machine == 'x86_64' and sys_platform == 'linux' and extra == 'cuda13'
Requires-Dist: nvidia-cufft>=12.0.0.15 ; platform_machine == 'x86_64' and sys_platform == 'linux' and extra == 'cuda13'
Requires-Dist: nvidia-cusolver>=12.0.3.29 ; platform_machine == 'x86_64' and sys_platform == 'linux' and extra == 'cuda13'
Requires-Dist: nvidia-cusparse>=12.6.2.49 ; platform_machine == 'x86_64' and sys_platform == 'linux' and extra == 'cuda13'
Requires-Dist: nvidia-nccl-cu13>=2.27.7 ; platform_machine == 'x86_64' and sys_platform == 'linux' and extra == 'cuda13'
Requires-Dist: nvidia-nvjitlink>=13.0.39 ; platform_machine == 'x86_64' and sys_platform == 'linux' and extra == 'cuda13'
Requires-Dist: nvidia-nvshmem-cu13>=3.3.20 ; platform_machine == 'x86_64' and sys_platform == 'linux' and extra == 'cuda13'
Requires-Dist: nvidia-nvvm ; platform_machine == 'x86_64' and sys_platform == 'linux' and extra == 'cuda13'
Requires-Dist: mace-torch>=0.3.0 ; extra == 'mace-torch'
Requires-Dist: matplotlib>=3.6 ; extra == 'plot'
Requires-Dist: pyo3-stubgen==0.3.0 ; extra == 'stubs'
Requires-Dist: pyright==1.1.414 ; extra == 'stubs'
Requires-Dist: pytest ; extra == 'test'
Requires-Dist: fastavro ; extra == 'test'
Requires-Dist: ase>=3.22 ; extra == 'test'
Requires-Dist: matplotlib>=3.6 ; extra == 'test'
Requires-Dist: fastatomstruct-xla-cpu==2026.6.23 ; platform_machine == 'x86_64' and sys_platform == 'linux' and extra == 'xla'
Provides-Extra: ase
Provides-Extra: bench
Provides-Extra: cp2k
Provides-Extra: cuda13
Provides-Extra: mace-torch
Provides-Extra: plot
Provides-Extra: stubs
Provides-Extra: test
Provides-Extra: xla
License-File: LICENSE
License-File: ADDITIONAL-PERMISSIONS.md
License-File: THIRD-PARTY-NOTICES.md
Summary: Fast analysis, molecular dynamics and machine-learning potentials for atomistic simulations, written in Rust
Keywords: atomistic,molecular-dynamics,materials-science,machine-learning-potentials,dft
Home-Page: https://ag-salinga.zivgitlabpages.uni-muenster.de/fastatomstruct/
Author-email: Nils Cedric Holle <nils.holle@uni-muenster.de>
License-Expression: GPL-3.0-or-later
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://ag-salinga.zivgitlabpages.uni-muenster.de/fastatomstruct/changelog.html
Project-URL: Documentation, https://ag-salinga.zivgitlabpages.uni-muenster.de/fastatomstruct/
Project-URL: Issues, https://zivgitlab.uni-muenster.de/ag-salinga/fastatomstruct/-/issues
Project-URL: Repository, https://zivgitlab.uni-muenster.de/ag-salinga/fastatomstruct

# 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`](https://crates.io/crates/rayon) is used throughout to fully exploit multicore processors.

## Citation

If you use `fastatomstruct` in your research, please cite:

[![DOI](https://joss.theoj.org/papers/10.21105/joss.08106/status.svg)](https://doi.org/10.21105/joss.08106)

## Documentation

[Full documentation](https://ag-salinga.zivgitlabpages.uni-muenster.de/fastatomstruct)

## 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

```python
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](https://ag-salinga.zivgitlabpages.uni-muenster.de/fastatomstruct/examples.html).

## Rust API

`fastatomstruct` can also be used directly in Rust projects.
[Rust API documentation](https://ag-salinga.zivgitlabpages.uni-muenster.de/fastatomstruct/rustdoc/).

## 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](https://www.rust-lang.org/tools/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):

```bash
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

```bash
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](https://ag-salinga.zivgitlabpages.uni-muenster.de/fastatomstruct/telemetry.html).

## 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 issues page](https://zivgitlab.uni-muenster.de/ag-salinga/fastatomstruct/-/issues) to report bugs or ask for support.

