scgo 0.5.1

Global optimization of atomic clusters using ASE with Basin Hopping and Genetic Algorithms, MLIP calculators (MACE, UMA), surface/adsorbate workflows, and NEB transition-state search.

SCGO: Simple Cluster Global Optimization

A compact toolkit for global optimization of atomic clusters using ASE. SCGO provides a focused API for Basin Hopping (BH) and Genetic Algorithm (GA) workflows with practical defaults.

Documentation: Read the Docs

Features

• Basin Hopping and Genetic Algorithm global optimization with automatic algorithm selection by cluster size
• MLIP support — MACE and UMA (fairchem) for GPU-accelerated optimization via TorchSim
• Surface workflows — slab-supported clusters and adsorbates with hull-site placement and tag-aware GA operators
• Transition state search — NEB-based TS search with automated pair selection and PBC-aware endpoint alignment
• Flexible API — high-level runners (run_go, run_go_ts, …) and low-level control for custom workflows
• Reproducible initialization — composition-canonical atom ordering for multi-element GA runs; mass-biased placement with per-structure RNG threading

Install

Install with exactly one MLIP extra per environment ([mace] or [uma]):

pip install "scgo[mace]"   # or: pip install "scgo[uma]"

Requires Python 3.12+ and SQLite with the JSON1 extension. See the installation guide for conda, editable installs, development extras, and HPC notes.

Quick start

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, sorted by energy. For sequential multi-composition runs, use run_go_campaign.

Workflows

Goal	Entry point	Documentation
Single composition GO	run_go	Quick start
Multi-composition GO	run_go_campaign	Quick start — Campaigns
TS from existing minima	run_ts_search	Quick start — Transition States
GO then TS	run_go_ts	Quick start — Transition States
Multi-composition TS	run_ts_campaign	Quick start — Campaigns
Multi-composition GO+TS	run_go_ts_campaign	Quick start — Campaigns

Pass one of four system_type values on every run: gas_cluster, surface_cluster, gas_cluster_adsorbate, or surface_cluster_adsorbate. See system types for when to use each.

Output layout depends on the runner: run_go writes directly to {formula}_searches/ (default in the current directory); combined and TS workflows use a campaign root with sibling {formula}_searches/ and {formula}_ts_results/ subdirectories. See output directories and on-disk layout (run IDs, provenance, timing).

Examples

Runnable scripts in examples/ (MACE + TorchSim by default):

Script	system_type	Notes
examples/example_pt5_gas.py	gas_cluster	Gas-phase Pt5
examples/example_pt5_graphite.py	surface_cluster	Pt5 on preset graphite
examples/example_pt5_oh_gas.py	gas_cluster_adsorbate	Pt5 + OH in gas phase
examples/example_pt5_2oh_graphite.py	surface_cluster_adsorbate	Pt5 + 2 OH on graphite

Development

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

Long-running MLIP regression sweeps live in benchmark/ (see benchmark/README.md).

---

MIT License — see LICENSE.