Metadata-Version: 2.4
Name: asaf
Version: 0.0.1
Summary: Library to facilitate the processing and analysis of data from the grand canonical transition matrix Monte Carlo adsorption simulations.
Author-email: Bartosz Mazur <bartosz.mazur@pwr.edu.pl>
License-Expression: MIT
Project-URL: Documentation, https://bartoszmazurwro.github.io/asaf/
Project-URL: Homepage, https://github.com/bartoszmazurwro/asaf
Project-URL: Issues, https://github.com/bartoszmazurwro/asaf/issues
Project-URL: Repository, https://github.com/bartoszmazurwro/asaf
Keywords: adsorption,isotherm,molecular simulation,monte carlo,transition matrix monte carlo
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: pandas
Requires-Dist: gemmi
Requires-Dist: pymatgen
Requires-Dist: plotly
Dynamic: license-file

# Quick and easy analysis of the data from the flat histogram simulations

[![Tests](https://github.com/bartoszmazurwro/asaf/actions/workflows/tests.yml/badge.svg)](https://github.com/bartoszmazurwro/asaf/actions/workflows/tests.yml)
[![Ruff](https://github.com/bartoszmazurwro/asaf/actions/workflows/ruff.yml/badge.svg)](https://github.com/bartoszmazurwro/asaf/actions/workflows/ruff.yml)
[![Docs](https://github.com/bartoszmazurwro/asaf/actions/workflows/docs.yml/badge.svg)](https://github.com/bartoszmazurwro/asaf/actions/workflows/docs.yml)
[![Codecov](https://codecov.io/gh/bartoszmazurwro/asaf/branch/main/graph/badge.svg)](https://codecov.io/gh/bartoszmazurwro/asaf)
[![PyPI](https://img.shields.io/pypi/v/asaf.svg)](https://pypi.org/project/asaf/)
[![Python versions](https://img.shields.io/pypi/pyversions/asaf.svg)](https://pypi.org/project/asaf/)
[![License](https://img.shields.io/github/license/bartoszmazurwro/asaf.svg)](LICENSE)
[![Paper DOI](https://img.shields.io/badge/DOI-10.1021%2Facsami.4c02616-blue)](https://doi.org/10.1021/acsami.4c02616)

***ASAF** (Adsorption Simulation Analysis Facilitator)* is a python library created to facilitate the processing and
analysis of data from grand canonical transition matrix Monte Carlo adsorption simulations.

> [!WARNING]
> ASAF is under active development. Backward compatibility with older versions is not currently guaranteed.

### Features:

- calculation of the macrostate probability distribution (MPC) from the transition probabilities
- interpolation of the transition probabilities
- calculation of the adsorption isotherm from the MPD
- calculation of the free energy from the MPD
- temperature extrapolation of the macrostate probability distribution
- saving the isotherms to an AIF file

### Installation

For the latest PyPI release:

```bash
pip install asaf
```

For the development version:

```bash
pip install "asaf @ git+https://github.com/bartoszmazurwro/asaf.git"
```

### Development

ASAF uses `uv` for local development. To set up the repository:

```bash
git clone https://github.com/bartoszmazurwro/asaf.git
cd asaf
uv sync --locked --all-extras --dev
uv run pytest
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development, testing, and release workflow.

### Citing

If you use ASAF in your work, please consider citing the following paper:

> Efficient Modeling of Water Adsorption in MOFs Using Interpolated Transition Matrix Monte Carlo, B. Mazur, L. Firlej,
> and B. Kuchta, **2024**, ACS Appl. Mater. Interfaces,
> DOI: [10.1021/acsami.4c02616](https://doi.org/10.1021/acsami.4c02616).

### FAQ

**In my prob files I see `current_cycle` column instead of `macrostate`.**

That's because you're looking at a prob file for a simulation in a particular macrostate. To calculate the macrostate
probability distribution you need at least several simulations in different macrostates. The diagram below explains the
scheme for creating the prob file used by ASAF from prob files generated by RASPA.

<img src="https://github.com/bartoszmazurwro/asaf/blob/main/docs/prob_files_workflow.png" width="1000" class="center">

**I don't have `.metadata.json` file.**

Currently, the only options are to create this file manually (for example, by copying one of the
[example files](https://github.com/bartoszmazurwro/asaf/blob/main/example/data/prob_MOF-303-E4D4_3.2.3_298.000000_1700.metadata.json)
and modifying it) or to add a function to your workflow that generates such a file based on RASPA input files. In the
future,
ASAF will be able to do this.

**Prob files are not generated.**

Make sure that you are using modified version of RASPA.

**My prob files are huge**

In general, you can play with `PrintGhostProbabilitesEvery` parameter. A more frequent print will be useful when you
want
to use energy fluctuations to extrapolate MPD, otherwise a value similar to that used in `PrintEvery` will be sufficient
to monitor the simulation. 
