Metadata-Version: 2.4
Name: mcpy-gcmc
Version: 1.5.0
Summary: A python package to run atomistic Monte Carlo simulations
Author: Riccardo Farris, Emanuele Telari, Konstantin M. Neyman, Albert Bruix
License-Expression: MIT
Project-URL: Homepage, https://github.com/farrisric/mcpy
Project-URL: Documentation, https://mc-py.readthedocs.io
Project-URL: Issues, https://github.com/farrisric/mcpy/issues
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ase>=3.23.0
Requires-Dist: numpy>=1.22
Requires-Dist: scipy>=1.8
Provides-Extra: mace
Requires-Dist: mace-torch>=0.3.9; extra == "mace"
Provides-Extra: alchemi
Requires-Dist: nvalchemi-toolkit[mace]<0.3,>=0.2.0; extra == "alchemi"
Provides-Extra: mpi
Requires-Dist: mpi4py>=4.0; extra == "mpi"
Provides-Extra: plot
Requires-Dist: matplotlib>=3.5; extra == "plot"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-cov>=4.0; extra == "test"
Requires-Dist: mcpy-gcmc[plot]; extra == "test"
Dynamic: license-file

[![Tests](https://github.com/farrisric/mcpy/actions/workflows/tests.yml/badge.svg)](https://github.com/farrisric/mcpy/actions/workflows/tests.yml)
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/mit)
[![GitHub issues](https://img.shields.io/github/issues/farrisric/mcpy.svg)](https://GitHub.com/farrisric/mcpy/issues)
[![Documentation Status](https://readthedocs.org/projects/mc-py/badge/)](https://mc-py.readthedocs.io/en/latest/index.html)

# mcpy

`mcpy` runs Grand Canonical Monte Carlo (GCMC) simulations of atomistic systems on top of the Atomic Simulation Environment (ASE).
It predicts the composition and structure of surfaces and nanoparticles in contact with a gas or metal reservoir, with any ASE calculator: classical potentials, DFT, or machine-learned interatomic potentials such as MACE.

Documentation: <https://mc-py.readthedocs.io>

## Features

- **Grand-canonical Monte Carlo**: atomic insertion and deletion at fixed chemical potential, with the free volume of the insertion region estimated from per-species exclusion radii.
- **Molecular adsorbates**: whole-molecule insertion, deletion and rigid translate+rotate moves (O2, H2O, CO, NH3, any ASE-buildable template), with per-atom `molecule_id` bookkeeping that survives rollback, trajectories and restarts.
  Atomic and molecular species can coexist in one run.
- **Insertion regions** for every common geometry: the periodic box, a window over a slab, a sphere around a nanoparticle, and a dome over a supported particle.
- **Replica exchange** along a temperature or chemical-potential ladder, over MPI or in one process on one GPU with batched energy evaluation.
- **Relaxed trial energies** (the hybrid GCMC scheme of Senftle et al.): each trial can be relaxed before the acceptance test, which makes GCMC workable on dense metal surfaces.
- **Canonical Monte Carlo and basin hopping**: permutation, displacement, shake and Brownian moves, and a running file of the lowest-energy configurations.
- **Optional GPU backend**: MACE evaluation and relaxation (FIRE by default, `optimizer=` for FIRE2 or LBFGS) through NVIDIA's `nvalchemi-toolkit`.
- **Phase diagrams**: post-processing of a chemical-potential sweep into surface and nanoparticle phase diagrams.

## Validation

mcpy's GCMC sampler reproduces LAMMPS `fix gcmc` for atomic and rigid-molecule Lennard-Jones systems, and the ideal gas against its analytic result.
The tables, the rerunnable scripts and a MACE comparison are in [`benchmark/README.md`](benchmark/README.md).

## Installation

mcpy needs Python 3.11 or later.
The distribution is named `mcpy-gcmc` (the `mcpy` name on PyPI belongs to an unrelated package).
You still write `import mcpy`.
Until the first PyPI release, install from the repository:

```sh
git clone https://github.com/farrisric/mcpy.git
cd mcpy
pip install -e .
```

The base install (ASE, NumPy, SciPy) runs the CPU examples `examples/00` to `examples/02`.
Optional extras:

| Extra | Adds | Needed for |
| --- | --- | --- |
| `.[mace]` | `mace-torch` | `MACE_F_Calculator` |
| `.[alchemi]` | `nvalchemi-toolkit[mace]` | `AlchemiCalculator`, `AlchemiFCalculator`, `examples/03` and `examples/04` (CUDA GPU) |
| `.[plot]` | `matplotlib` | the phase-diagram utilities |
| `.[mpi]` | `mpi4py` | `ReplicaExchange` over MPI |
| `.[test]` | `pytest` | the test suite |

A conda-installed `mpi4py` (`conda install mpi4py`) is often the safer choice, because it links the MPI library it was built for.
The [installation guide](https://mc-py.readthedocs.io/en/latest/installation.html) covers the GPU backend and the MPI launch.

## Quickstart (CPU, about three minutes)

```sh
python examples/00_hello_gcmc.py
```

The script fills an empty periodic box with Lennard-Jones particles from a reservoir and prints the average particle count next to the LAMMPS value for the same conditions.
Here is the core of it:

```python
from ase import Atoms
from ase.calculators.lj import LennardJones

from mcpy.cell import Cell
from mcpy.ensembles import GrandCanonicalEnsemble
from mcpy.moves import DeletionMove, DisplacementMove, InsertionMove, MoveSelector

atoms = Atoms(cell=[9.0, 9.0, 9.0], pbc=True)   # an empty periodic box
cell = Cell(atoms, seed=6)                      # insert and delete anywhere in it

move_selector = MoveSelector(
    [1, 1, 1],
    [InsertionMove(cell, species=['H'], seed=1),
     DeletionMove(cell, species=['H'], seed=2),
     DisplacementMove(species=['H'], max_displacement=0.3, seed=3)],
    seed=4,
)

gcmc = GrandCanonicalEnsemble(
    atoms=atoms,
    cells=[cell],
    calculator=LennardJones(sigma=1.0, epsilon=1.0, rc=3.0, smooth=False),
    mu={'H': -3.0},          # reduced chemical potential
    species=['H'],
    units_type='LJ',
    temperature=2.0,         # reduced temperature
    move_selector=move_selector,
    random_seed=5,           # every random stream is seeded: the run repeats exactly
    outfile='hello_gcmc.out',
    traj_file='hello_gcmc.xyz',
    outfile_write_interval=100,
    trajectory_write_interval=100,
)
gcmc.run(6000)
```

The [tutorial](https://mc-py.readthedocs.io/en/latest/getting_started.html) takes the same loop to an O/Ag(111) oxidation phase diagram with MACE.
[`examples/`](examples/README.md) has the other runnable scripts, and [`notebooks/`](notebooks/) has worked case studies with executed output.

## Citing mcpy

If you use mcpy in published work, please cite it with the metadata in [`CITATION.cff`](CITATION.cff) (GitHub shows a "Cite this repository" button for it).

## Contributing

Contributions are welcome.
See [CONTRIBUTING.md](CONTRIBUTING.md) for the development setup, the tests, and how to submit changes.
Bug reports and feature requests go to the [issue tracker](https://github.com/farrisric/mcpy/issues).

## License

mcpy is licensed under the MIT License; see [LICENSE](LICENSE).
