All Parameters¶

This page lists all parameters you can use in SCGO. For preset functions and their defaults, see Parameter Presets.

Parameter resolution¶

All high-level run_* functions share the same contract:

Safe defaults — pass params=None, go_params=None, or ts_params=None to use full preset defaults.
Partial overrides — pass a dict with only the keys you want to change; runners merge with defaults before execution.
Presets encouraged — start from a Parameter Presets builder, inspect/edit, then pass to run_*.

Merge rules

Dict	Merge behaviour
`params` / `go_params`	Deep-merge onto `get_default_params()` via `initialize_params()`. Nested dicts (e.g. `optimizer_params["ga"]`, `calculator_kwargs`) merge recursively; user keys win.
`ts_params`	Deep-merge onto `get_ts_search_params()` via `initialize_ts_params()`. Not merged with GO defaults. For `run_go_ts*`, calculator settings align with merged `go_params` unless overridden in `ts_params`.
Forbidden in dicts	Top-level `system_type` in `go_params` / `ts_params` (use the run `system_type=` argument). Factory-default `optimizer_params[*]["system_type"]` values are ignored when they match `get_default_params()`; explicit non-default values must match the run argument.
Run kwargs	`system_type`, `surface_config`, `adsorbates`, `seed`, `verbosity`, `output_` belong on the `run_` call, not inside preset dicts (except `surface_config` may also appear in presets when it must agree with the run argument).

Logging (verbosity >= 1): SCGO logs the defaults source and a flat list of user overrides, then the resolved GO optimizer settings or TS NEB configuration. See Utilities.

Verbosity levels (run_* verbosity= argument):

Level	Behaviour
0	Warnings and errors only; no progress bars
1	Normal operation: parameter merge logs, timing summaries, campaign progress, and GA phase summaries (initialization, per-generation crossover/mutation/relaxation)
2	Per-individual GA and initialization detail (offspring outcomes, placement failures, ineligible structures after relaxation); third-party loggers still suppressed in HPC mode
3	TRACE-level diagnostics (deepest SCGO logging)

Configure the root logger with configure_logging(). Set SCGO_LOCAL_DEV=1 for milder third-party log suppression during local development (see Installation).

Workflow

from scgo import run_go_ts
from scgo.param_presets import get_default_params, get_ts_search_params

go_params = get_default_params()
go_params["optimizer_params"]["ga"]["niter"] = 8

ts_params = get_ts_search_params(system_type="gas_cluster")
ts_params["max_pairs"] = 12

summary = run_go_ts(
    "Pt5",
    go_params=go_params,
    ts_params=ts_params,
    system_type="gas_cluster",
    seed=7,
)

GO Parameters¶

Passed as params or go_params to run_go, run_go_campaign, run_go_ts, etc.

Algorithm selection

Runners call select_scgo_minima_algorithm() automatically:

gas_cluster only, ≤2 mobile atoms → simple (simple_go.db)
3 atoms, no adsorbate → Basin Hopping (bh_go.db)
3 atoms, adsorbate system types → Genetic Algorithm (ga_go.db)
≥4 atoms → Genetic Algorithm (ga_go.db)

Top-Level:

`calculator`	`"MACE"`	Calculator: `"MACE"`, `"UMA"`, `"UPET"`, or `"EMT"`
`calculator_kwargs`	`{}`	Calculator options (e.g. `{"model_name": "mace_mp_small"}`). Unsupported `device` values raise `SCGOValidationError`.
`seed`	`None`	Random seed (function argument overrides)
`fitness_strategy`	`"low_energy"`	`"low_energy"`, `"high_energy"`, or `"diversity"`
`diversity_reference_db`	`None`	Glob pattern for reference DBs (for diversity mode)
`connectivity_factor`	`1.4`	Connectivity threshold (covalent radii multiplier) for initialization validation and post-operator GA checks; see Cluster initialization
`allow_cluster_fragmentation`	`False`	Allow cluster to split (surface only)
`allow_adsorbate_surface_detachment`	`False`	Allow adsorbates without cluster contact
`enforce_adsorbate_subgraph_integrity`	`True`	Keep adsorbate fragments connected
`freeze_adsorbate_internal_geometry`	`False`	Keep adsorbate fragments rigid
`surface_config`	`None`	Required for surface runs (prefer the run-function `surface_config=`; a top-level key in `go_params` is also allowed)
`cluster_adsorbate_config`	`None`	Adsorbate placement knobs (in `go_params` only)
`validation_n_jobs`	(optional)	Parallel workers for post-GO Hessian/force validation
`validate_with_hessian`	`False`	Run vibrational analysis
`tag_final_minima`	`True`	Mark final structures in database
`fmax_threshold`	`0.05`	Force threshold for validation (eV/\(\AA\))
`check_hessian`	`True`	Check Hessian during validation
`imag_freq_threshold`	`50.0`	Imaginary frequency cutoff (cm^-1)

Simple (``optimizer_params[“simple”]``) — used for 1–2 atom gas clusters only:

`optimizer`	`"FIRE"`	Local optimizer name
`fmax`	`0.05`	Force convergence (eV/\(\AA\))
`niter`	`1`	Relaxation steps
`niter_local_relaxation`	`"auto"`	Local relaxation budget

GA (``optimizer_params[“ga”]``):

`population_size`	`"auto"`	Number of structures in population
`niter`	`"auto"`	Number of generations
`mutation_probability`	`0.4`	Probability of mutating each structure
`offspring_fraction`	`0.5`	Fraction of population replaced each generation
`fmax`	`0.05`	Force convergence (eV/\(\AA\))
`vacuum`	`10.0`	Vacuum around clusters (\(\AA\))
`use_adaptive_mutations`	`True`	Auto-adjust mutation rate
`early_stopping_niter`	`10`	Stop if no improvement for N generations
`n_jobs_population_init`	`-2`	Parallel jobs for population init (-2 = all but 1)
`n_jobs_offspring`	`-2`	Parallel jobs for offspring
`write_timing_json`	`False`	Write `{run_dir}/timing.json`; enables `go_ts_timing.json` rollup in `run_go_ts`
`detailed_timing`	`False`	Include per-generation timing
`stagnation_trigger`	`4`	Generations without improvement before adaptive mutation boost
`stagnation_full_trigger`	`8`	Stronger stagnation threshold
`recovery_window`	`2`	Generations to watch after a mutation boost
`aggressive_burst_multiplier`	`1.8`	Mutation-rate multiplier on stagnation
`max_mutation_probability`	`0.65`	Cap on adaptive mutation probability
`batch_size`	`None`	TorchSim batch size (when using a relaxer)
`relaxer`	`None`	Optional TorchSim relaxer instance

BH (``optimizer_params[“bh”]``):

`temperature`	500K	Temperature for accepting moves
`dr`	`0.2`	Maximum step size (\(\AA\))
`move_fraction`	`0.3`	Fraction of atoms to move
`deduplicate`	`True`	Remove duplicates
`energy_tolerance`	`1e-5`	Energy tolerance for duplicates (eV)
`move_strategy`	`"random"`	Atom move strategy
`comparator_tol`	(default)	Structure comparator tolerance
`comparator_pair_cor_max`	(default)	Pair correlation cutoff for deduplication
`comparator_n_top`	`None`	Optional `n_top` for comparator
`write_timing_json`	`False`	Write `{run_dir}/timing.json`; enables `go_ts_timing.json` rollup in `run_go_ts`
`detailed_timing`	`False`	Include per-iteration timing breakdown

TS Parameters¶

Passed as ts_params to run_ts_search, run_ts_campaign, run_go_ts, etc. Sparse dicts are merged with get_ts_search_params() defaults at run time.

Core:

`calculator`	`"MACE"`	Calculator for TS search
`calculator_kwargs`	`{}`	Calculator options
`max_pairs`	`None`	Maximum minima pairs to check (None = all)
`energy_gap_threshold`	`2.0` / `0.75` (adsorbate)	Max energy gap to attempt TS (eV)
`use_torchsim`	`True`	Use TorchSim for NEB
`dedupe_minima`	`True`	Remove duplicate minima before pairing
`connectivity_factor`	`1.4`	Connectivity threshold
`similarity_tolerance`	(default)	Minima similarity tolerance for pairing
`similarity_pair_cor_max`	`0.1`	Pair-correlation cap for similarity
`minima_energy_tolerance`	`1e-5`	Energy tolerance when deduplicating minima
`write_timing_json`	`False`	Write `{ts_run_dir}/timing.json`; enables `go_ts_timing.json` rollup in `run_go_ts`

NEB:

`neb_n_images`	`5` / `7` (adsorbate)	Number of images
`neb_steps`	`"auto"` / `2000` (bare surface) / `4000` (adsorbate)	Maximum optimization steps
`neb_fmax`	`0.20`	Force convergence (eV/\(\AA\)); shared across all system types
`neb_spring_constant`	`0.1` / `0.5` (adsorbate)	Spring constant (eV/\(\AA\)²)
`neb_climb`	`False` / `True` (adsorbate)	Use climbing image
`use_parallel_neb`	`True`	Batch multiple NEB bands in one TorchSim force eval (all system types)
`parallel_neb_max_bands`	`None` / `1` (surface)	Cap concurrent bands in the parallel NEB runner; surface defaults to `1` (chunked one-at-a-time) to avoid GPU OOM on large slab cells
`max_endpoint_mismatch`	`None` / `1.25` (gas adsorbate) / `1.5` (surface adsorbate)	Å geometric gate on comparator `max_diff`; when set, also enables pre-NEB clash/IDPP energy checks
`neb_align_endpoints`	`True`	Align endpoints before interpolation
`neb_interpolation_mic`	`False` / `True`	Use minimum image convention
`neb_perturb_sigma`	`0.0`	Gaussian perturbation on band (Å)
`neb_interpolation_method`	`"idpp"`	Interpolation method
`neb_tangent_method`	(default)	NEB tangent method
`torchsim_fmax`	`0.20`	TorchSim force tolerance (mapped internally). Keep equal to `neb_fmax` unless you intentionally diverge them
`torchsim_max_steps`	`"auto"` / `2000` (bare surface) / `4000` (adsorbate)	TorchSim step budget (mapped internally)

Adsorbate NEB extras (beyond the table defaults above):

Fragment-wise adsorbate matching and core-anchored alignment
Pair selection prefers activated hops (moderate mismatch / core RMS), oversamples candidates (10× max_pairs), and re-ranks by IDPP profile so the NEB budget favors robust interior maxima when any exist
Pre-NEB rejection of clashing / high-residual IDPP paths, absurd barriers (> 8 eV), endpoint energy drift after alignment (> 0.5 eV), and one-sided interior maxima (prominence < 0.40 eV). Endpoint-max IDPP is used only when the oversampled pool has no robust-interior candidates
Climbing NEB: two-stage only when IDPP has a robust interior maximum (barrier ≥ 1.0 eV); endpoint-max and soft interior IDPP climb from step 0
Finalize also rejects barriers > 8 eV

Surface NEB (differences from gas):

neb_interpolation_mic=True (forced)
neb_surface_cell_remap=True
neb_surface_lattice_rotation=True for bare surface_cluster; False for surface_cluster_adsorbate (registry-safe)
neb_surface_max_lattice_shift=1
parallel_neb_max_bands=1 (parallel NEB path stays on; bands are chunked one-at-a-time for OOM safety on large slab cells)

Surface Config¶

`slab`	Required	ASE Atoms object
`adsorption_height_min`	`1.2` (class) / `2.0` (`make_surface_config`)	Minimum height above slab (\(\AA\)). Alias: `height_min`.
`adsorption_height_max`	`3.0` (class) / `3.5` (`make_surface_config`)	Maximum height above slab (\(\AA\)). Alias: `height_max`.
`surface_normal_axis`	`2`	Normal axis (0=x, 1=y, 2=z)
`fix_all_slab_atoms`	`True`	Keep entire slab frozen
`n_relax_top_slab_layers`	`None`	Top layers to relax
`n_fix_bottom_slab_layers`	`None`	Bottom layers to freeze
`comparator_use_mic`	`True`	Use MIC in structure comparator on surfaces
`cluster_init_vacuum`	(optional)	Extra vacuum for cluster init on slab
`init_mode`	`"smart"`	Surface cluster init mode: `smart`, `seed+growth`, `random_spherical`, or `template` (see Cluster initialization)
`max_placement_attempts`	(optional)	Max cluster placement attempts on slab
`structure_connectivity_factor`	(optional)	Connectivity factor for slab validation

Note

Use only one of the layer options, not both. See Surface workflows. Surface heights: adsorption_height_* (canonical) or height_* alias. Adsorbate heights: height_* (canonical) or adsorption_height_* alias. Conflicting values raise SCGOValidationError.

Adsorbate Config¶

`height_min`	`0.9`	Minimum placement height (\(\AA\)). Alias: `adsorption_height_min`.
`height_max`	`2.2`	Maximum placement height (\(\AA\)). Alias: `adsorption_height_max`.
`max_placement_attempts`	`80`	Maximum placement tries
`blmin_ratio`	`0.7`	Clash threshold