SCGO: Simple Cluster Global Optimization

SCGO Logo

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, UMA (fairchem), and UPET (metatomic) 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], [uma], or [upet]):

pip install "scgo[mace]"   # or: pip install "scgo[uma]" or pip install "scgo[upet]"
# UPET also needs vesin 0.6.0 at runtime (skin= for metatomic-torchsim):
# pip install 'vesin==0.6.0' --force-reinstall --no-deps

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.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

scgo-0.6.0.tar.gz (582.1 kB view details)

Uploaded Jul 22, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

scgo-0.6.0-py3-none-any.whl (715.7 kB view details)

Uploaded Jul 22, 2026 Python 3

File details

Details for the file scgo-0.6.0.tar.gz.

File metadata

Download URL: scgo-0.6.0.tar.gz
Upload date: Jul 22, 2026
Size: 582.1 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for scgo-0.6.0.tar.gz
Algorithm	Hash digest
SHA256	`2b3791b7d0888ec3484e02c0c00c1ed785ee97050b0763e497d6b97163d187ca`
MD5	`3b5489dda0244eefd55fc200e148ae32`
BLAKE2b-256	`5f5c3ab64ce6694e623f8f81b499fb4aa29592f1d67b62aedd79d41e45d29b98`

See more details on using hashes here.

Provenance

The following attestation bundles were made for scgo-0.6.0.tar.gz:

Publisher: publish-pypi.yml on rlaplaza-lab/scgo

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: scgo-0.6.0.tar.gz
- Subject digest: 2b3791b7d0888ec3484e02c0c00c1ed785ee97050b0763e497d6b97163d187ca
- Sigstore transparency entry: 2219310766
- Sigstore integration time: Jul 22, 2026
Source repository:
- Permalink: rlaplaza-lab/scgo@2465e307daf0d427514079c3c57aacdde6d7967b
- Branch / Tag: refs/heads/main
- Owner: https://github.com/rlaplaza-lab
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish-pypi.yml@2465e307daf0d427514079c3c57aacdde6d7967b
- Trigger Event: workflow_dispatch