Metadata-Version: 2.4
Name: npl
Version: 3.1.0
Requires-Dist: ase>=3.23
Requires-Dist: numpy>=1.26
Requires-Dist: scipy>=1.11
Requires-Dist: scikit-learn>=1.5
Requires-Dist: sortedcontainers>=2.4
Requires-Dist: pytest>=7.0 ; extra == 'test'
Provides-Extra: test
License-File: LICENSE
Summary: NanoParticleLibrary: structural and chemical-ordering analysis and optimization of nanoparticles
Author: Konstantin M. Neyman, Albert Bruix
Author-email: Riccardo Farris <rfarris@ub.edu>
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://nplib.readthedocs.io
Project-URL: Homepage, https://github.com/farrisric/npl
Project-URL: Issues, https://github.com/farrisric/npl/issues

<!-- [![GitHub release](https://img.shields.io/github/release/yourusername/npl.svg)](https://GitHub.com/yourusername/npl/releases/) -->

[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/mit)
[![GitHub issues](https://img.shields.io/github/issues/farrisric/npl.svg)](https://GitHub.com/farrisric/npl/issues)
[![Documentation Status](https://readthedocs.org/projects/nplib/badge/)](https://nplib.readthedocs.io/en/latest/index.html)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20445317.svg)](https://doi.org/10.5281/zenodo.20445317)

# <span style="font-size:larger;">NanoParticleLibrary (NPL)</span>

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/farrisric/npl/main/docs/images/logo_dark.png">
  <img src="https://raw.githubusercontent.com/farrisric/npl/main/docs/images/logo.png?v=2" alt="NPL Logo" width="206">
</picture>

## Table of contents

- [NanoParticleLibrary (NPL)](#nanoparticlelibrary-npl)
  - [About NPL](#about-npl)
  - [Documentation](#documentation)
  - [Installation](#installation)
    - [Requirements](#requirements)
    - [Installation from PyPI](#installation-from-pypi)
    - [Installation from source](#installation-from-source)
  - [Examples](#examples)
  - [References](#references)
  - [Contact](#contact)
  - [License](#license)

## About NPL

NPL is a Python library for the simulation and structural optimization of nanoparticles, specifically tailored for bimetallic nanoparticles. Built on the robust ASE (Atomic Simulation Environment), it enables users to easily set up and analyze complex nanoparticle structures across a range of chemical compositions and structures. NPL provides high-level abstractions, making it accessible for both beginners and experienced researchers aiming to perform detailed nanoparticle simulations.

## Documentation

A partial documentation is available at: https://nplib.readthedocs.io/en/latest/

## Installation

### Requirements

- Python 3.10+
- Atomic Simulation Environment (ASE) >= 3.23
- numpy, scipy, scikit-learn, sortedcontainers

### Installation from PyPI

You can install NPL with pip:

```sh
pip install npl
```

The wheels include a compiled Rust extension that makes ACT basin hopping and the ACT genetic algorithm 24-42x faster.

### Installation from source

Building from source compiles that extension, so it needs a Rust toolchain (https://rustup.rs):

```sh
git clone https://github.com/farrisric/npl
pip install ./npl
```

## Examples

### TOP Energy Evaluation Example

This example demonstrates how to evaluate the topological (TOP) energy of a bimetallic nanoparticle using pretrained coefficients shipped with NPL. A 201-atom truncated-octahedral Pt151Cu50 particle is constructed, its extended topological feature vector is computed, and the energy is evaluated using a `TOPCalculator` loaded from pretrained linear-model coefficients. The result is a fast relative energy, in the units of the pretrained coefficients, without requiring an external calculator.

```python
from npl.core import Nanoparticle
from npl.calculators import TOPCalculator
from npl.descriptors import ExtendedTopologicalFeaturesClassifier

calculator = TOPCalculator(
    "ETOP",
    stoichiometry="Pt151Cu50",
    feature_classifier=ExtendedTopologicalFeaturesClassifier,
)
feature_classifier = calculator.get_feature_classifier()

particle = Nanoparticle()
particle.truncated_octahedron(7, 2, {"Pt": 151, "Cu": 50})

feature_classifier.compute_feature_vector(particle)
energy = calculator.compute_energy(particle)

print(f"TOP energy of Pt151Cu50: {float(energy):.4f}")
```

NPL optimizes the chemical ordering of a particle with guided local optimization, basin hopping and a genetic algorithm (`model="TOP"` or `"ACT"` for two metals, `model="ETOP"` for three or more), or with Metropolis Monte Carlo over a fitted energy model (`npl.monte_carlo.run_monte_carlo`).
See `examples/basin_hopping_act.py` for a two-metal search and `examples/multimet_go.ipynb` for a trimetallic (Pd/Au/Cu) workflow that compares ETOP basin hopping with Monte Carlo.

> **Note:** `npl`'s Monte Carlo samples chemical ordering at fixed composition (canonical). For *grand-canonical* Monte Carlo with machine-learning interatomic potentials (variable particle number, MACE/alchemi), see the companion package [mcpy](https://github.com/farrisric/mcpy).

## References

If you use this code, please cite our papers:

```bibtex
@article{neumann2021,
  author  = {Neumann, Felix and Margraf, Johannes T. and Reuter, Karsten and Bruix, Albert},
  title   = {Interplay between shape and composition in bimetallic nanoparticles revealed by an efficient optimal-exchange optimization algorithm},
  journal = {ChemRxiv},
  year    = {2021},
  doi     = {10.26434/chemrxiv-2021-26ztp}
}

@article{farris2024zr,
  author  = {Farris, Riccardo and Merinov, Boris V. and Bruix, Albert and Neyman, Konstantin M.},
  title   = {Effects of {Zr} dopants on properties of {PtNi} nanoparticles for {ORR} catalysis: A {DFT} modeling},
  journal = {The Journal of Chemical Physics},
  volume  = {160},
  number  = {12},
  pages   = {124706},
  year    = {2024},
  doi     = {10.1063/5.0193848}
}

@article{farris2024ordering,
  author  = {Farris, Riccardo and Neyman, Konstantin M. and Bruix, Albert},
  title   = {Determining the chemical ordering in nanoalloys by considering atomic coordination types},
  journal = {The Journal of Chemical Physics},
  volume  = {161},
  number  = {13},
  pages   = {134114},
  year    = {2024},
  doi     = {10.1063/5.0214377}
}
```

## Contact

For any questions or issues, please contact:

- Riccardo Farris: [rfarris@ub.edu](mailto:rfarris@ub.edu)
- GitHub Issues: [npl Issues](https://github.com/farrisric/npl/issues)

## License

This project is licensed under the MIT License - see the [LICENSE](https://opensource.org/licenses/MIT) file for details.

