tmmc-lnpy 0.8.1.dev0
Analysis of lnPi results from TMMC simulation
Requires Python: >=3.10
Keywords: tmmc-lnpy

<!-- markdownlint-disable MD041 -->

<!-- prettier-ignore-start -->
[![Repo][repo-badge]][repo-link]
[![Docs][docs-badge]][docs-link]
[![PyPI license][license-badge]][license-link]
[![PyPI version][pypi-badge]][pypi-link]
[![Conda (channel only)][conda-badge]][conda-link]
[![Code style: ruff][ruff-badge]][ruff-link]
[![uv][uv-badge]][uv-link]

<!--
  For more badges, see
  https://shields.io/category/other
  https://naereen.github.io/badges/
  [pypi-badge]: https://badge.fury.io/py/tmmc-lnpy
-->

[ruff-badge]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
[ruff-link]: https://github.com/astral-sh/ruff
[uv-badge]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json
[uv-link]: https://github.com/astral-sh/uv
[pypi-badge]: https://img.shields.io/pypi/v/tmmc-lnpy
[pypi-link]: https://pypi.org/project/tmmc-lnpy
[docs-badge]: https://img.shields.io/badge/docs-sphinx-informational
[docs-link]: https://pages.nist.gov/tmmc-lnpy/
[repo-badge]: https://img.shields.io/badge/--181717?logo=github&logoColor=ffffff
[repo-link]: https://github.com/usnistgov/tmmc-lnpy
[conda-badge]: https://img.shields.io/conda/v/conda-forge/tmmc-lnpy
[conda-link]: https://anaconda.org/conda-forge/tmmc-lnpy
[license-badge]: https://img.shields.io/pypi/l/tmmc-lnpy?color=informational
[license-link]: https://github.com/usnistgov/tmmc-lnpy/blob/main/LICENSE
[changelog-link]: https://github.com/usnistgov/tmmc-lnpy/blob/main/CHANGELOG.md

<!-- other links -->

<!-- prettier-ignore-end -->

# `tmmc-lnpy`

## Overview

A package to analyze $\ln \Pi(N)$ data from Transition Matrix Monte Carlo
simulation. The main output from TMMC simulations, $\ln \Pi(N)$, provides a
means to calculate a host of thermodynamic properties. Moreover, if $\ln \Pi(N)$
is calculated at a specific chemical potential, it can be reweighted to provide
thermodynamic information at a different chemical potential

## Features

`tmmc-lnpy` provides a wide array of routines to analyze $\ln \Pi(N)$. These
include:

- Reweighting to arbitrary chemical potential
- Segmenting $\ln \Pi(N)$ (to identify unique phases)
- Containers for interacting with several values of $\ln \Pi(N)$ in a vectorized
  way.
- Calculating thermodynamic properties from these containers
- Calculating limits of stability, and phase equilibrium

## Status

This package is actively used by the author. Please feel free to create a pull
request for wanted features and suggestions!

## Example usage

Note that the distribution name `tmmc-lnpy` is different than the import name
`lnpy` due to name clashing on pypi.

```pycon
>>> import numpy as np
>>> import lnpy
>>> import lnpy.examples

>>> ref = lnpy.examples.load_example_lnpimasked("lj_sub")

>>> phase_creator = lnpy.PhaseCreator(nmax=1, ref=ref)
>>> build_phases = phase_creator.build_phases_mu([None])
>>> collection = lnpy.lnPiCollection.from_builder(
...     lnzs=np.linspace(-10, 3, 5), build_phases=build_phases
... )


# Collections are like pandas.Series
>>> collection
<class lnPiCollection>
lnz_0   phase
-10.00  0        [-10.0]
-6.75   0        [-6.75]
-3.50   0         [-3.5]
-0.25   0        [-0.25]
 3.00   0          [3.0]
dtype: object


# Access xarray backend for Grand Canonical properties with `xge` accessor
>>> collection.xge.betaOmega()
<xarray.DataArray 'betaOmega' (lnz_0: 5, phase: 1)> Size: 40B
array([[-2.3245e-02],
       [-6.0370e-01],
       [-1.8552e+02],
       [-1.5447e+03],
       [-2.9580e+03]])
Coordinates:
  * lnz_0    (lnz_0) float64 40B -10.0 -6.75 -3.5 -0.25 3.0
  * phase    (phase) int64 8B 0
    beta     float64 8B 1.372
    volume   float64 8B 512.0
Attributes:
    dims_n:         ['n_0']
    dims_lnz:       ['lnz_0']
    dims_comp:      ['component']
    dims_state:     ['lnz_0', 'beta', 'volume']
    dims_rec:       ['sample']
    standard_name:  grand_potential
    long_name:      $\beta \Omega(\mu,V,T)$


```

<!-- end-docs -->

## Installation

<!-- start-installation -->

Use one of the following

```bash
pip install tmmc-lnpy
```

or

```bash
conda install -c conda-forge tmmc-lnpy
```

<!-- end-installation -->

## Documentation

See the [documentation][docs-link] for a look at `tmmc-lnpy` in action.

## What's new?

See [changelog][changelog-link].

## License

This is free software. See [LICENSE][license-link].

## Related work

This package is used for with
[thermoextrap](https://github.com/usnistgov/thermo-extrap) to analyze
thermodynamically extrapolated macro state probability distributions.

## Contact

The author can be reached at <wpk@nist.gov>.

## Credits

This package was created using
[Cookiecutter](https://github.com/audreyr/cookiecutter) with the
[usnistgov/cookiecutter-nist-python](https://github.com/usnistgov/cookiecutter-nist-python)
template.