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; must agree across run argument and preset dicts when both are set

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

• verbosity: 0=quiet (warnings only), 1=normal (parameter merge and timing summaries), 2=debug (library detail), 3=trace (custom TRACE level for deep diagnostics). Progress bars are shown when verbosity >= 1 (see should_show_progress()).

See All Parameters (Parameter resolution) for merge rules and logging behaviour.

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 ("Pt5") or comma-separated symbols ("Pt,Pt,Au")
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

Configure timing in params / go_params only (optimizer_params['ga'] or bh):

• write_timing_json=True: write timing.json under each run directory (alongside metadata.json)

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

For TS, set write_timing_json in ts_params when needed.

See scgo.utils.timing_report for the JSON layout and scgo.utils.output_paths for campaign directory helpers.

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 only in params/go_params under optimizer_params['ga'] (or bh): write_timing_json and detailed_timing. See scgo.utils.timing_report.

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

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)

Supports two formats: - Comma-separated symbols: “Pt,Pt,Au” - Compact formula: “Pt3Au” or “AuPt2”

Return type:

list[str]

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.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, 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]]