SCGO: Simple Cluster Global Optimization

SCGO Logo

SCGO finds low-energy atomic structures with global optimization. It uses Basin Hopping, Genetic Algorithms, NEB transition-state search, and machine learning potentials (MACE, UMA, UPET) through ASE and TorchSim.

A cluster (also called the core when molecules are present) is the metal nanoparticle whose shape you are searching. An adsorbate is a small molecule or fragment (for example OH or CO) attached to the cluster or the surface. A slab is a periodic surface the cluster or adsorbate sits on. You can also search the top layers of the slab itself, with the bottom layers held still.

Six system types combine these pieces: 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 (never inside go_params / optimizer_params slots). Surfaces prefer surface_config= as a run argument; a top-level surface_config in go_params / ts_params is enough when the run argument is omitted (both must agree when set). 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 (for example Pt5, Pt5_OH_OH_graphite). See quickstart.

Examples

examples/ holds 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 and not integration and not requires_cuda and not requires_upet and not requires_uma"

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

Uploaded Aug 20, 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.8.0-py3-none-any.whl (967.6 kB view details)

Uploaded Aug 20, 2026 Python 3

File details

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

File metadata

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

File hashes

Hashes for scgo-0.8.0.tar.gz
Algorithm	Hash digest
SHA256	`237e6a34410451810568067027cad48d1897820371e47b843f42ea7e1dbd1f8f`
MD5	`b60766dfb8c0bedf46128267b45d3713`
BLAKE2b-256	`5631fce71a4f4e3c237c4d4c44d19ed7b69ae21712331fcdda54d3616ddff331`

See more details on using hashes here.

Provenance

The following attestation bundles were made for scgo-0.8.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.8.0.tar.gz
- Subject digest: 237e6a34410451810568067027cad48d1897820371e47b843f42ea7e1dbd1f8f
- Sigstore transparency entry: 2540209961
- Sigstore integration time: Aug 20, 2026
Source repository:
- Permalink: rlaplaza-lab/scgo@1a55b7e781e8b0b3f08a2add46895a388e487b8b
- 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@1a55b7e781e8b0b3f08a2add46895a388e487b8b
- Trigger Event: workflow_dispatch