Metadata-Version: 2.4
Name: atooms-pp
Version: 4.4.0
Summary: Post-processing tools for particle simulations
Author-email: Daniele Coslovich <daniele.coslovich@umontpellier.fr>
License: GPLv3
Project-URL: repository, https://framagit.org/atooms/postprocessing
Project-URL: homepage, https://framagit.org/atooms/postprocessing
Project-URL: documentation, https://atooms.frama.io/postprocessing
Project-URL: changelog, https://framagit.org/atooms/postprocessing/-/blob/master/CHANGELOG.md
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: atooms>=3.27.0
Requires-Dist: argh
Requires-Dist: tqdm
Requires-Dist: f2py_jit
Dynamic: license-file

# Postprocessing

[![pypi](https://img.shields.io/pypi/v/atooms-pp.svg)](https://pypi.python.org/pypi/atooms-pp/)
[![version](https://img.shields.io/pypi/pyversions/atooms-pp.svg)](https://pypi.python.org/pypi/atooms-pp/)
[![license](https://img.shields.io/pypi/l/atooms-pp.svg)](https://en.wikipedia.org/wiki/GNU_General_Public_License)
[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/git/https%3A%2F%2Fframagit.org%2Fatooms%2Fpostprocessing/HEAD?labpath=docs%2Findex.ipynb)
[![pipeline](https://framagit.org/atooms/postprocessing/badges/master/pipeline.svg)](https://framagit.org/atooms/postprocessing/badges/master/pipeline.svg)
[![coverage report](https://framagit.org/atooms/postprocessing/badges/master/coverage.svg)](https://framagit.org/atooms/postprocessing/-/commits/master)

A Python package to compute static and dynamic correlation functions from simulations of interacting particles, such as molecular dynamics or Monte Carlo simulations. Based on [atooms](https://framagit.org/atooms/atooms).

## Quick start

Postprocessing works on trajectories. Any trajectory format recognized by
[atooms](https://framagit.org/atooms/atooms.git) can be processed, for instance most "xyz" files
should work fine. If you use a custom trajectory format, it is easy to [add it](https://atooms.frama.io/docs/trajectories.html#trajectory-formats). 

### From Python

As an example, we compute the structure factor S(k) from the file `data/trajectory.xyz`.

```python
from atooms.trajectory import Trajectory
import atooms.postprocessing as pp

with Trajectory('data/trajectory.xyz') as t:
     cf = pp.StructureFactor(t)
     cf.compute()
     cf.plot()
```
The wave-vectors and values of the correlation function are accessible as `cf.grid` and `cf.values`, respectively. If you also want to write the results of the calculation in a file, just use `do()` instead of `compute()`. You will find the results in `data/trajectory.xyz.pp.sk`. Check out the documentation section below for more information.

### From the command line

The same calculation can be done from the command line
```sh
pp.py sk data/trajectory.xyz
```

## Features

Available correlation and distribution functions

- *Real space*
  - [radial distribution function](https://atooms.frama.io/postprocessing/api/atooms/postprocessing/gr.html)
  - [pair distribution function](https://atooms.frama.io/postprocessing/api/atooms/postprocessing/pair.html)
  - [mean square displacement](https://atooms.frama.io/postprocessing/api/atooms/postprocessing/msd.html)
  - [velocity auto-correlation function](https://atooms.frama.io/postprocessing/api/atooms/postprocessing/vacf.html)
  - [self and collective overlap functions](https://atooms.frama.io/postprocessing/api/atooms/postprocessing/qt.html)
  - [four-point dynamic susceptibility of the self overlap](https://atooms.frama.io/postprocessing/api/atooms/postprocessing/chi4t.html)
  - [non-Gaussian parameter](https://atooms.frama.io/postprocessing/api/atooms/postprocessing/alpha2.html)
  - [bond-angle distribution](https://atooms.frama.io/postprocessing/api/atooms/postprocessing/gr.html)
  - [self and distinct van Hove correlation function](https://atooms.frama.io/postprocessing/api/atooms/postprocessing/vanhove.html)
- *Fourier space*
  - [structure factor](https://atooms.frama.io/postprocessing/api/atooms/postprocessing/sk.html)
  - [spectral density](https://atooms.frama.io/postprocessing/api/atooms/postprocessing/ik.html)
  - [self and collective intermediate scattering functions](https://atooms.frama.io/postprocessing/api/atooms/postprocessing/fkt.html)
  - [four-point dynamic structure factor of the self overlap](https://atooms.frama.io/postprocessing/api/atooms/postprocessing/s4kt.html)
  - [generic four point-point dynamic susceptibility](https://atooms.frama.io/postprocessing/api/atooms/postprocessing/susceptibility.html)
- *Molecular correlations*
  - [rotational correlation functions](https://atooms.frama.io/postprocessing/api/atooms/postprocessing/cl.html)
  - [orientational angle distribution function](https://atooms.frama.io/postprocessing/api/atooms/postprocessing/oad.html)
  - Most real and Fourier space correlation functions admit a [center-of-mass variant](https://atooms.frama.io/postprocessing/api/atooms/postprocessing/molecular.html) suitable for the molecules' centers of mass.

Most time-dependent single-particle correlation functions admit a cage-relative variant (through the ``cage_relative`` argument), useful to remove so-called Mermin-Wagner fluctuations in two-dimensional systems.

## Documentation

Check out the [tutorial](https://atooms.frama.io/docs/postprocessing/index.html) for more examples and the [public API](https://atooms.frama.io/postprocessing/) for full details.

Org-mode and jupyter notebooks are available under `docs/`. You can run the tutorial interactively on [Binder]( https://mybinder.org/v2/git/https%3A%2F%2Fframagit.org%2Fatooms%2Fpostprocessing/HEAD?labpath=docs%2Findex.ipynb).

## Installation

Install with `pip`
```
pip install atooms-pp
```

Or from source
```
git clone https://framagit.org/atooms/postprocessing.git
cd postprocessing
pip install .
```

## Contributing

Contributions to the project are welcome. If you wish to contribute, check out [these guidelines](https://framagit.org/atooms/atooms/-/blob/master/CONTRIBUTING.md).

## Authors

Daniele Coslovich: https://www.units.it/daniele.coslovich/

Thanks to Romain Simon and Giacomo Tonet for their contributions.
