mcpy-gcmc 1.5.0__tar.gz

mcpy_gcmc-1.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Riccardo Farris, Emanuele Telari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcpy_gcmc-1.5.0/PKG-INFO

@@ -0,0 +1,157 @@
+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).

mcpy_gcmc-1.5.0/README.md

@@ -0,0 +1,118 @@
+[![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).

mcpy_gcmc-1.5.0/mcpy/__init__.py

@@ -0,0 +1,12 @@
+import logging
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version('mcpy-gcmc')
+except PackageNotFoundError:  # not installed, e.g. run from a source checkout
+    __version__ = '0.0.0.unknown'
+
+# Library convention: attach a NullHandler to the top-level package logger so
+# importing mcpy has no side effects on the host application's logging config.
+# Users opt in to logging via mcpy.utils.logging.configure(...).
+logging.getLogger(__name__).addHandler(logging.NullHandler())

mcpy_gcmc-1.5.0/mcpy/calculators/__init__.py

@@ -0,0 +1,24 @@
+from .base_calculator import BaseCalculator
+
+# The backend calculators import lazily (PEP 562): mace-torch and nvalchemi
+# pull in torch, which costs seconds and, in a misconfigured env, kills the
+# process with SIGBUS. Accessing one without its backend raises the real
+# ImportError (install with: pip install -e .[mace] or .[alchemi]).
+_LAZY = {
+    'MACE_F_Calculator': 'mace_f_calculator',
+    'AlchemiCalculator': 'alchemi',
+    'AlchemiFCalculator': 'alchemi',
+}
+
+__all__ = ['BaseCalculator', *_LAZY]
+
+
+def __getattr__(name):
+    if name in _LAZY:
+        from importlib import import_module
+        return getattr(import_module(f'.{_LAZY[name]}', __name__), name)
+    raise AttributeError(f'module {__name__!r} has no attribute {name!r}')
+
+
+def __dir__():
+    return sorted({*globals(), *__all__})