API Reference

High-level functions for running global optimization and transition state searches.

Main Functions

Single composition:

run_go(...) → list[tuple[float, Atoms]]	Optimize one composition, return list of (energy, Atoms) tuples
run_ts_search(...) → list[dict[str, Any]]	Find transition states for one composition
run_go_ts(...) → dict[str, Any]	Run GO then TS for one composition

Multiple compositions (campaigns):

run_go_campaign(...) → dict[str, list[tuple[float, Atoms]]]	Optimize multiple compositions; failed compositions are logged and skipped (empty list for that formula). See Cluster initialization.
run_ts_campaign(...) → dict[str, list[dict[str, Any]]]	Find TS for multiple compositions
run_go_ts_campaign(...) → dict[str, dict[str, Any]]	Run GO+TS for multiple compositions

All functions accept:

• composition: formula string ("Pt5"), symbol list (["Pt"]*5), or ASE Atoms

• params / go_params: GO parameter dictionary (None or partial dict; merged with get_default_params() at run time)

• ts_params: TS parameter dictionary (None or partial dict; merged with get_ts_search_params() at run time)

• seed: random seed for reproducibility (must agree across seed=, go_params['seed'], and ts_params['seed'] when more than one is set)

• system_type: "gas_cluster", "surface_cluster", "gas_cluster_adsorbate", or "surface_cluster_adsorbate" (run argument only — not inside preset dicts)

• surface_config: required for surface system types (run argument preferred; may also appear in go_params / ts_params)

• adsorbates: ASE Atoms or list of Atoms, required for adsorbate system types

• verbosity: 0 quiet … 3 trace (progress bars when verbosity >= 1)

scgo.runner_api is the public facade (implementation split across runner_composition, runner_params, runner_go, runner_ts).

See All Parameters for merge rules.

Output directories

output_dir semantics differ by runner. Full table and directory-tree examples: Quick Start (Output directories).

Runner	output_dir is	Also accepts
run_go	{formula}_searches/ directory itself	—
run_go_campaign	Campaign parent → {parent}/{formula}_searches/	—
run_go_ts	Campaign root → {root}/{formula}_searches/ + {root}/{formula}_ts_results/	output_root, output_stem
run_go_ts_campaign	Campaign parent → {parent}/{formula}_campaign/…	output_root, output_stem
run_ts_search	Campaign root (or existing *_searches/ — parent inferred)	searches_dir
run_ts_campaign	Shared campaign root for all compositions	—

Complete Examples

from scgo import run_go
from scgo.param_presets import get_testing_params

results = run_go(
    "Pt5",
    params=get_testing_params(),
    seed=42,
    system_type="gas_cluster",
)

See Quick Start for surface, adsorbate, TS, campaign, and output-layout examples.

Utility Functions

build_one_element_compositions(element, min_atoms, max_atoms)	Symbol lists for mono-element size scans (e.g. [["Pt", "Pt"], ["Pt", "Pt", "Pt"]])
build_two_element_compositions(el1, el2, min_atoms, max_atoms)	Symbol lists for bimetallic size scans (all el1/el2 splits per atom count)
parse_composition_arg(comp_str)	Parse a compact formula with chemical capitalization ("Pt5", "HO2Ru9W2"), or comma-separated symbols ("Pt,Pt,Au"; unambiguous, case-insensitive)
resolve_workflow_seed(*, seed_kw, go_params, ts_params)	Ensure seed consistency across params
log_go_ts_summary(logger, summary, *, wall_time_s=None)	Print summary of a GO+TS run

Timing and Profiling

Per-run timing — set in params / go_params under optimizer_params['ga'] or bh:

• write_timing_json=True — write {run_dir}/timing.json (alongside metadata.json)

• detailed_timing=True — add per_generation rows (requires write_timing_json=True)

TS timing — set write_timing_json in ts_params for {ts_run_dir}/timing.json.

GO+TS pipeline rollup — when timing JSON is enabled in go_params and/or ts_params, run_go_ts also writes go_ts_timing.json at the campaign root.

See Utilities for timing JSON layout and output-path helpers. On-disk layout and provenance: Quick Start (On-disk layout).

Module Reference

High-level SCGO workflows: GO, TS, GO+TS, and campaigns.

go_params = global-optimization params; ts_params = flat TS preset (scgo.param_presets.get_ts_search_params()). The run seed and go_params['seed'] / ts_params['seed'] must agree when more than one is set (resolve_workflow_seed()). System mode is set only by the run function system_type=... argument together with explicit surface_config=... and, for *_adsorbate modes, core-only composition plus adsorbates=... (single or multiple ASE Atoms fragments). System-definition keys in go_params are partly restricted: system_type remains rejected, while top-level surface_config is allowed and fanned out into optimizer slots. Adsorbate placement tuning (cluster_adsorbate_config, connectivity_factor, freeze_adsorbate_internal_geometry) belongs in go_params only—not as separate run_* keywords. For ts_params, system_type remains rejected while surface_config is allowed and validated against the run argument.

GA/BH timing JSON is configured in params/go_params under optimizer_params['ga'] (or bh): write_timing_json and detailed_timing. TS uses write_timing_json in ts_params. run_go_ts may also write go_ts_timing.json at the campaign root. See scgo.utils.timing_report.

This module is intentionally thin: the actual implementations live in scgo.runner_composition (composition parsing), scgo.runner_params (param merging/allowlisting/coherence and context dataclasses), scgo.runner_go (GO trials/campaigns), and scgo.runner_ts (TS and GO+TS pipelines). Everything that was previously importable from scgo.runner_api remains importable from here, including private helpers used by tests via monkeypatch.setattr("scgo.runner_api.<name>", ...) (e.g. run_trials, get_calculator_class, _run_go_trials, _run_go_campaign_compositions, _ts_search, _ts_campaign, _run_go_ts_pipeline). scgo.runner_go and scgo.runner_ts call back into this module (via function-local imports, to avoid a top-level import cycle) specifically so that patching those attributes here is honored regardless of which module physically defines the calling code.

type scgo.runner_api.CompositionInput = str | list[str] | Atoms

scgo.runner_api.build_one_element_compositions(element, min_atoms, max_atoms)

Composition list for mono-element size scans (min_atoms..max_atoms).

Return type:

list[list[str]]

scgo.runner_api.build_two_element_compositions(element1, element2, min_atoms, max_atoms)

Composition list for bimetallic size scans (min_atoms..max_atoms).

Return type:

list[list[str]]

scgo.runner_api.log_go_ts_summary(logger, summary, *, wall_time_s=None)

Log NEB success counts from a run_go_ts* summary dict.

Return type:

None

scgo.runner_api.parse_composition_arg(comp_str)

Parse composition strings.

Supported formats:

• Comma-separated symbols such as "Pt,Pt,Au" (case-insensitive per symbol).

• Compact formula with chemical capitalization such as "Pt3Au" or "HO2Ru9W2". Uses ase.formula.Formula; HO2 is H + O2, not holmium.

All-lowercase compact formulas are accepted only for unambiguous single-element inputs such as pt3. Multi-element lowercase strings (pt3au) and ambiguous two-letter forms (ho2 as H+O2 vs holmium) are rejected.

Return type:

list[str]

scgo.runner_api.resolve_workflow_seed(*, seed_kw=None, go_params=None, ts_params=None)

Unify run seed=..., go_params['seed'], and ts_params['seed']; all non-null must agree.

Return type:

int | None

scgo.runner_api.run_go(composition, params=None, seed=None, verbosity=1, run_id=None, clean=False, output_dir=None, calculator_for_global_optimization=None, surface_config=None, system_type=None, adsorbates=None, log_summary=True)

Run global optimization trials for one composition.

Return type:

list[tuple[float, Atoms]]

scgo.runner_api.run_go_campaign(compositions, params=None, seed=None, verbosity=1, run_id=None, clean=False, output_dir=None, surface_config=None, system_type=None, adsorbates=None, log_summary=True)

Run global optimization for multiple compositions.

Each composition gets a reproducible sub-seed derived from seed / params['seed']. If a composition fails (ValueError, RuntimeError, SCGOValidationError, I/O, or database errors), the error is logged, that formula maps to an empty list, and remaining compositions continue.

Return type:

dict[str, list[tuple[float, Atoms]]]

scgo.runner_api.run_go_ts(composition, *, go_params=None, ts_params=None, seed=None, verbosity=1, output_dir=None, output_root=None, output_stem=None, surface_config=None, system_type=None, adsorbates=None, log_summary=True)

Run global optimization then transition-state search for one composition.

Return type:

dict[str, Any]

scgo.runner_api.run_go_ts_campaign(compositions, *, go_params=None, ts_params=None, seed=None, verbosity=1, output_dir=None, output_root=None, output_stem=None, surface_config=None, system_type=None, adsorbates=None, log_summary=True)

Run GO+TS for multiple compositions.

Return type:

dict[str, dict[str, Any]]

scgo.runner_api.run_ts_campaign(compositions, *, ts_params=None, output_dir=None, seed=None, verbosity=1, surface_config=None, system_type=None, adsorbates=None, log_summary=True)

Return type:

dict[str, list[dict[str, Any]]]

scgo.runner_api.run_ts_search(composition, *, ts_params=None, output_dir=None, searches_dir=None, seed=None, verbosity=1, surface_config=None, system_type=None, adsorbates=None, log_summary=True)

Run transition-state search for one composition.

output_dir is the campaign root. Minima are loaded from {formula}_searches/ (or from searches_dir when provided). TS artifacts are written to sibling {formula}_ts_results/ with run_*/pair_*/ subdirectories. If output_dir points at an existing *_searches directory, its parent is treated as the campaign root.

Return type:

list[dict[str, Any]]

scgo.runner_api.select_scgo_minima_algorithm(n_atoms, system_type)

Select global optimizer for composition size and system type.

Uses the mobile-atom count (core + adsorbate symbols for adsorbate modes). Plain gas_cluster alone may use simple for 1-2 atoms; adsorbate and surface modes never select simple.

Return type:

Literal['simple', 'bh', 'ga']