Parameter Presets¶

This page explains the parameter presets available in SCGO and what each parameter controls.

Overview¶

SCGO has two parameter dict types: GO (params / go_params) and TS (ts_params). Merge rules, logging, and override behaviour are in All Parameters (Parameter resolution).

Preset Functions¶

Use these preset functions to get started quickly.

Global Optimization:

GO Presets¶
`get_testing_params()`	Fast EMT-based parameters for testing (small populations, few iterations)
`get_default_params()`	Default MACE-based parameters for production
`get_minimal_ga_params(seed, model_name)`	Compact GA parameters that run sequentially (easier to debug)
`get_torchsim_ga_params(*, system_type, surface_config, seed, model_name)`	MACE + TorchSim for GPU acceleration. Requires `scgo[mace]`.
`get_default_uma_params()`	Default UMA (fairchem) parameters
`get_uma_ga_benchmark_params(seed, *, model_name, uma_task)`	UMA parameters for benchmarking campaigns
`get_diversity_params(reference_db_glob, max_references, update_interval)`	Bias exploration toward diverse structures
`get_high_energy_params()`	Bias exploration toward high-energy structures

Transition State Search:

TS Presets¶
`get_ts_search_params(calculator, calculator_kwargs, *, system_type, surface_config, seed)`	TS-only settings (NEB, calculator, pairing). Requires `system_type`. For surfaces, also requires `surface_config`. Default calculator is `"MACE"`.
`get_ts_defaults(system_type)`	NEB knob defaults for one system type (used internally by `get_ts_search_params()`; prefer `get_ts_search_params` in user code)

Preset effects (vs defaults)¶

Preset	Main differences from `get_default_params()` / `get_ts_search_params()`
`get_testing_params()`	`calculator="EMT"`; small `niter` / `population_size` in all optimizer slots
`get_default_params()`	Canonical MACE production defaults (baseline for GO merge)
`get_minimal_ga_params()`	Sequential GA jobs (`n_jobs_* = 1`); optional `seed` / `model_name`
`get_torchsim_ga_params()`	MACE benchmark GA stack + TorchSim relaxer; sets `surface_config` for surface types
`get_default_uma_params()`	`calculator="UMA"` + FairChem TorchSim relaxer with auto local-step budget
`get_uma_ga_benchmark_params()`	UMA + fixed 200 local steps, autobatcher, `expected_max_atoms=600` (benchmark parity with TorchSim GA preset)
`get_diversity_params()`	`fitness_strategy="diversity"` + reference DB glob and update interval
`get_high_energy_params()`	`fitness_strategy="high_energy"`; BH temperature raised to 1000 K
`get_ts_search_params()`	Full flat TS dict for one `system_type` (NEB knobs from `get_ts_defaults()`); baseline for TS merge

Parameter reference¶

See All Parameters for the full GO, TS, surface, and adsorbate parameter tables.

Available Models¶

MACE models: "mace_matpes_0", "mace_mp_small", "mace_mpa_medium", "mace_off_small"

UMA models: "uma-s-1p2", "uma-s-1p1", "uma-m-1p1"

Usage Examples¶

Start from a preset:

from scgo.param_presets import get_default_params

params = get_default_params()
params["calculator_kwargs"]["model_name"] = "mace_mp_small"
params["optimizer_params"]["ga"]["population_size"] = 100

Build TS params:

from scgo import make_graphite_surface_config
from scgo.param_presets import get_ts_search_params

surface_config = make_graphite_surface_config(slab_layers=3)

ts_params = get_ts_search_params(
    system_type="surface_cluster",
    surface_config=surface_config,
    seed=42,
)
ts_params["max_pairs"] = 20
ts_params["neb_n_images"] = 7

Combined GO + TS:

from scgo import make_graphite_surface_config
from scgo.param_presets import get_torchsim_ga_params, get_ts_search_params

surface_config = make_graphite_surface_config(slab_layers=3)

go_params = get_torchsim_ga_params(
    system_type="surface_cluster",
    surface_config=surface_config,
    seed=42,
)

ts_params = get_ts_search_params(
    system_type="surface_cluster",
    surface_config=surface_config,
    seed=42,
)

See Quick Start for complete workflow examples and All Parameters for the full parameter list.

Module Reference¶

Parameter presets for SCGO campaigns.

scgo.param_presets.get_default_params()[source]¶

Return the default SCGO parameter dictionary for global optimization.

Suitable for run_go / run_go_ts as params / go_params; pass as-is or override keys (omitted keys are filled via scgo.utils.run_helpers.initialize_params()).

Return type:: dict[str, Any]

scgo.param_presets.get_minimal_ga_params(seed=None, model_name=None)[source]¶

Return compact GA-focused parameters derived from defaults.

Uses sequential population init and offspring work (n_jobs_* set to 1) so runners stay easy to reason about. Pass as-is to run_* or override keys; omitted keys are filled via scgo.utils.run_helpers.initialize_params().

Return type:: dict[str, Any]

scgo.param_presets.get_testing_params()[source]¶

Return fast, low-cost parameters for tests (EMT, fewer iterations).

Complete preset based on get_default_params(); pass as-is to run_* or override keys (omitted keys are filled via scgo.utils.run_helpers.initialize_params()).

Return type:: dict[str, Any]

scgo.param_presets.get_torchsim_ga_params(*, system_type, surface_config=None, seed=None, model_name=None)[source]¶

Return GO params using TorchSim relaxer (requires scgo[mace]).

Mirrors get_ts_search_params() call style by requiring system_type and accepting surface_config / seed explicitly. Pass as-is to run_* or override keys. When model_name is set, it is written to calculator_kwargs and the TorchSimBatchRelaxer uses the same MACE model name as the ASE calculator.

Return type:: dict[str, Any]

scgo.param_presets.get_diversity_params(reference_db_glob='**/*.db', max_references=100, update_interval=5)[source]¶

Return params for diversity-based optimization (reference DB, intervals).

Pass as-is to run_* or override keys. reference_db_glob must match at least one database with reference structures when you run; there is no runtime check that the glob is non-empty.

Return type:: dict[str, Any]

scgo.param_presets.get_high_energy_params()[source]¶

Return params that bias exploration toward high-energy structures.

Pass as-is to run_* or override keys. Sets top-level fitness_strategy to high_energy (used by BH and GA). Basin hopping additionally uses a higher temperature. GA hyperparameters are otherwise unchanged—override optimizer_params['ga'] if you need stronger exploration there.

Return type:: dict[str, Any]

scgo.param_presets.get_ts_defaults(system_type)[source]¶

Return a fresh copy of NEB knob defaults for one system type.

Single source of truth read by get_ts_search_params() and scgo.utils.ts_runner_kwargs.coerce_ts_params_to_runner_kwargs().

Return type:: dict[str, Any]

scgo.param_presets.get_ts_search_params(calculator='MACE', calculator_kwargs=None, *, system_type, surface_config=None, seed=None)[source]¶

TS-only settings (NEB, calculator, pairing). Not merged with GO defaults.

Suitable for run_ts_search / run_go_ts as ts_params; pass as-is or override keys (omitted keys are filled via scgo.utils.run_helpers.initialize_ts_params()).

For EMT or other non-TorchSim calculators, set use_torchsim=False on the returned dict before running. system_type is used to shape technical defaults. For surface system types, surface_config is required and stored in the returned dictionary so TS loading/validation always receives explicit slab context (no guessing). If seed is set, it is stored in the returned dict; run_go_ts() / run_ts_* require it to be consistent with go_params['seed'] and the seed= run argument. The connectivity_factor key sets the global connectivity threshold for cluster validation (default 1.4).

NEB endpoint alignment is on by default (neb_align_endpoints=True). Surface system types also enable neb_interpolation_mic, neb_surface_cell_remap, neb_surface_lattice_rotation, and neb_surface_max_lattice_shift (default 1) so path interpolation starts from lattice-compatible aligned endpoints.

Return type:: dict[str, Any]

scgo.param_presets.get_default_uma_params()[source]¶

Default SCGO parameters using the UMA calculator (fairchem-core).

Pass as-is to run_* or override keys. For typical campaigns with default GA settings: niter_local_relaxation is "auto" and the TorchSim relaxer uses 250 max steps in that case. Autobatcher and memory-probe defaults follow TorchSimBatchRelaxer (autobatcher None: CUDA on, CPU off). Use get_uma_ga_benchmark_params() when you need the same structure as the MACE benchmark preset (fixed local steps, explicit autobatcher/expected_max_atoms).

Return type:: dict[str, Any]

scgo.param_presets.get_uma_ga_benchmark_params(seed, *, model_name='uma-s-1p2', uma_task='oc25')[source]¶

GA benchmark parameters matching _get_base_ga_benchmark_params() but with UMA.

Tuned for regression and profiling alongside the MACE TorchSim benchmark preset (get_torchsim_ga_params()): fixed local relaxation budget from the base preset (200 steps, not "auto"), with autobatching and expected_max_atoms=600 for stable GPU memory behaviour. Pass as-is to run_* or override keys. For general UMA runs with default GA "auto" local steps, use get_default_uma_params() instead.

Return type:: dict[str, Any]