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 scgo.utils.run_helpers.

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
2	DEBUG-level library messages (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 → Basin Hopping (bh_go.db)
≥4 atoms, or any surface/adsorbate type → Genetic Algorithm (ga_go.db)

Top-Level:

`calculator`	`"MACE"`	Calculator: `"MACE"`, `"UMA"`, or `"EMT"`
`calculator_kwargs`	`{}`	Calculator options (e.g., `{"model_name": "mace_mp_small"}`)
`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
`cluster_adsorbate_config`	`None`	Tune adsorbate placement
`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 timing to JSON
`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

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`	Max energy gap to attempt TS (eV)
`use_torchsim`	`True`	Use TorchSim for NEB
`use_parallel_neb`	`False`	Run NEB in parallel
`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
`torchsim_batch_size`	`5`	TorchSim NEB batch size
`write_timing_json`	`False`	Write TS timing JSON sidecar

NEB:

`neb_n_images`	`5`	Number of images
`neb_steps`	`"auto"` / `500`	Maximum optimization steps
`neb_fmax`	`0.05` / `0.1`	Force convergence (eV/\(\AA\))
`neb_spring_constant`	`0.1`	Spring constant (eV/\(\AA\)²)
`neb_climb`	`False`	Use climbing image
`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.05` / `0.1`	TorchSim force tolerance (not a runner kwarg; mapped internally)
`torchsim_max_steps`	`"auto"` / `500`	TorchSim step budget (mapped internally)

Surface NEB (differences from gas):

neb_interpolation_mic=True (forced)
neb_surface_cell_remap=True
neb_surface_lattice_rotation=True
neb_surface_max_lattice_shift=1

Surface Config¶

`slab`	Required	ASE Atoms object
`adsorption_height_min`	`2.0`	Minimum height above slab (\(\AA\))
`adsorption_height_max`	`3.5`	Maximum height above slab (\(\AA\))
`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`	`False`	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 for the full SurfaceSystemConfig field list.

Adsorbate Config¶

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

All Parameters¶

Parameter resolution¶

GO Parameters¶

TS Parameters¶

Surface Config¶

Adsorbate Config¶

See Also¶