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. Covers gas-phase, surface, and adsorbate workflows.

Documentation: Read the Docs

Install

Exactly one MLIP extra per environment:

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.

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). 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, surface_cluster_adsorbate, surface, or surface_adsorbate. Surfaces need surface_config=; adsorbates need adsorbates=.

Output: run_go writes {path_key}_searches/; GO+TS/TS use a campaign root with sibling {path_key}_searches/ and {path_key}_ts_results/ (e.g. Pt5_OH_OH_graphite_searches). See quickstart.

Examples

examples/ — MACE + TorchSim smoke scripts for the supported system types (example_pt5_*.py, example_defected_graphite.py, example_n_doped_graphite.py).

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

Uploaded Aug 3, 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.5-py3-none-any.whl (762.6 kB view details)

Uploaded Aug 3, 2026 Python 3

File details

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

File metadata

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

File hashes

Hashes for scgo-0.6.5.tar.gz
Algorithm	Hash digest
SHA256	`fe0933bd982e4ebf099c6769b346e478258db05ae1bfc3d0dcfe7cc621d5e210`
MD5	`219bb4b1b7a6714ae2fe9492fe8c8d54`
BLAKE2b-256	`dd3e28d242123837e25f8cc0559021904aa7ca3e89fc205ad1d6bc7712ada046`

See more details on using hashes here.

Provenance

The following attestation bundles were made for scgo-0.6.5.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.5.tar.gz
- Subject digest: fe0933bd982e4ebf099c6769b346e478258db05ae1bfc3d0dcfe7cc621d5e210
- Sigstore transparency entry: 2337596735
- Sigstore integration time: Aug 3, 2026
Source repository:
- Permalink: rlaplaza-lab/scgo@a9d04dfd14f75f453fb369b7a40f0d6443221fa6
- 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@a9d04dfd14f75f453fb369b7a40f0d6443221fa6
- Trigger Event: workflow_dispatch