Metadata-Version: 2.4
Name: scgo
Version: 0.6.3
Summary: Global optimization of atomic clusters using ASE with Basin Hopping and Genetic Algorithms, MLIP calculators (MACE, UMA, UPET), surface/adsorbate workflows, and NEB transition-state search.
Author-email: "R. Laplaza" <ruben.laplaza@iiq.csic.es>
License: MIT
Project-URL: Homepage, https://github.com/rlaplaza-lab/scgo
Project-URL: Documentation, https://scgo.readthedocs.io/
Project-URL: Repository, https://github.com/rlaplaza-lab/scgo
Project-URL: Issues, https://github.com/rlaplaza-lab/scgo/issues
Keywords: computational-chemistry,structure-optimization,atomic-clusters,basin-hopping,genetic-algorithm,ase,mace,uma,upet,fairchem,metatomic
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ase>=3.22.0
Requires-Dist: ase-ga>=0.1.0
Requires-Dist: numpy<2.5,>=2.2
Requires-Dist: scipy<3,>=1.14
Requires-Dist: tqdm>=4.60.0
Provides-Extra: mace
Requires-Dist: e3nn==0.4.4; extra == "mace"
Requires-Dist: mace-torch==0.3.16; extra == "mace"
Requires-Dist: nvalchemi-toolkit-ops==0.3.1; extra == "mace"
Requires-Dist: nvidia-nccl-cu12>=2.28; extra == "mace"
Requires-Dist: torch<2.13,>=2.12.0; extra == "mace"
Requires-Dist: torch-sim-atomistic[mace]==0.6.0; extra == "mace"
Provides-Extra: uma
Requires-Dist: fairchem-core>=2.19.0; extra == "uma"
Requires-Dist: torch-sim-atomistic[fairchem]==0.6.0; extra == "uma"
Provides-Extra: upet
Requires-Dist: upet>=0.2.6; extra == "upet"
Requires-Dist: metatomic-torchsim>=0.1.3; extra == "upet"
Requires-Dist: torch-sim-atomistic==0.6.0; extra == "upet"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: psutil>=7.0.0; extra == "dev"
Requires-Dist: ruff==0.14.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Dynamic: license-file

# SCGO: Simple Cluster Global Optimization

[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/) [![PyPI](https://img.shields.io/pypi/v/scgo.svg)](https://pypi.org/project/scgo/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

![SCGO Logo](docs/source/_static/scgo_logo.svg)

Global optimization of atomic clusters with ASE: Basin Hopping, Genetic Algorithms, NEB transition-state search, and MLIPs (MACE, UMA, UPET) via TorchSim. Covers gas-phase, surface, and adsorbate workflows.

**Documentation:** [Read the Docs](https://scgo.readthedocs.io/)

## Install

Exactly one MLIP extra per environment:

```bash
pip install "scgo[mace]"   # or [uma] / [upet]
# UPET only: pip install 'vesin==0.6.0' --force-reinstall --no-deps
```

Python 3.12+, SQLite JSON1. Details: [installation guide](https://scgo.readthedocs.io/en/latest/installation.html).

## Quick start

```python
from scgo import run_go
from scgo.param_presets import get_testing_params

results = run_go(
    ["Pt"] * 4,
    params=get_testing_params(),
    seed=42,
    system_type="gas_cluster",
)
```

`results` is a list of `(energy, Atoms)` unique minima (energy-sorted). Use `run_go_campaign` for multi-composition runs.

## Workflows

| Goal | Entry point |
|------|-------------|
| Single composition GO | `run_go` |
| Multi-composition GO | `run_go_campaign` |
| TS from existing minima | `run_ts_search` |
| GO then TS | `run_go_ts` |
| Multi-composition TS / GO+TS | `run_ts_campaign` / `run_go_ts_campaign` |

`system_type` is always a run argument: `gas_cluster`, `surface_cluster`, `gas_cluster_adsorbate`, or `surface_cluster_adsorbate`. Surfaces need `surface_config=`; adsorbates need `adsorbates=`.

Output: `run_go` writes `{formula}_searches/`; GO+TS/TS use a campaign root with sibling `{formula}_searches/` and `{formula}_ts_results/`. See [quickstart](https://scgo.readthedocs.io/en/latest/quickstart.html).

## Examples

[`examples/`](examples/) — MACE + TorchSim smoke scripts for all four system types (`example_pt5_*.py`).

## Development

```bash
pip install -e ".[mace,dev]"   # or [uma,dev] / [upet,dev]
pre-commit install
pytest tests/ -m "not slow"
```

Long MLIP sweeps: [`benchmark/`](benchmark/).

---

MIT License — see [`LICENSE`](LICENSE).
