SCGO: Simple Cluster Global Optimization

SCGO Logo

Global optimization of atomic clusters with ASE: Basin Hopping, Genetic Algorithms, NEB transition-state search, and MLIPs (MACE, UMA, UPET) via TorchSim. Supports six system types: gas_cluster, surface_cluster, gas_cluster_adsorbate, surface_cluster_adsorbate, surface, and surface_adsorbate.

Documentation: Read the Docs

Install

Exactly one MLIP extra per environment:

pip install "scgo[mace]"   # or [uma] / [upet]

UPET note: After pip install "scgo[upet]", manually install vesin==0.6.0:

pip install 'vesin==0.6.0' --force-reinstall --no-deps

Python 3.12+, SQLite JSON1. Details: installation guide.

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 (energy-sorted).

Algorithms: SCGO auto-selects based on system size:

≤2 mobile atoms: Simple relaxation
3 atoms, no adsorbate: Basin Hopping
3+ atoms with adsorbate: Genetic Algorithm
≥4 atoms: Genetic Algorithm

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. Surfaces need surface_config=, adsorbates need adsorbates=.

Output: run_go writes {path_key}_searches/ with datetime-tagged run_*/ subdirectories. GO+TS creates sibling {path_key}_ts_results/. The path_key combines nanoparticle formula, adsorbate fragments, and surface name (e.g., Pt5, Pt5_OH_OH_graphite). See quickstart.

Examples

examples/ — MACE + TorchSim smoke scripts for all six system types. See examples/README.md for details.

Development

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

Long MLIP sweeps: benchmark/.

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.7.0.tar.gz (687.9 kB view details)

Uploaded Aug 10, 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.7.0-py3-none-any.whl (838.9 kB view details)

Uploaded Aug 10, 2026 Python 3

File details

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

File metadata

Download URL: scgo-0.7.0.tar.gz
Upload date: Aug 10, 2026
Size: 687.9 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for scgo-0.7.0.tar.gz
Algorithm	Hash digest
SHA256	`1e0965625be384e30e6ed8ffb18587e40bea8fba283f8ff8746627db03f42896`
MD5	`5ec18700e5d34cbbbc8b620935d4116b`
BLAKE2b-256	`e9274034344e8b4a6f0a381db0747dbfd3bb8bbc4ec5c0159062c752fdde82bc`

See more details on using hashes here.

Provenance

The following attestation bundles were made for scgo-0.7.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.7.0.tar.gz
- Subject digest: 1e0965625be384e30e6ed8ffb18587e40bea8fba283f8ff8746627db03f42896
- Sigstore transparency entry: 2402648377
- Sigstore integration time: Aug 10, 2026
Source repository:
- Permalink: rlaplaza-lab/scgo@bda5d7f739a409aa5a43b5bdbe1563ef1189bd41
- 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@bda5d7f739a409aa5a43b5bdbe1563ef1189bd41
- Trigger Event: workflow_dispatch