NEBScape settings¶

NEBScape defines surface-reaction exploration and pathway search. Its SODA integration exposes scientific controls in [NEBScape], with force-model settings in [ASE Calculator]. Start with the MACE surface-reaction example.

Keep [Main] job = nebscape. Use "$SODA_BIN" --help-config to inspect the INI schema and "$SODA_BIN" --help for runtime options after activating your build’s environment. The tables below list selected settings; the configuration schema gives the complete INI reference.

Reaction inputs and placement selection¶

These options belong to [NEBScape]. Scientific defaults match the reviewed native path; the example explicitly enables selection_prerelax_sample.

Option	Default	Purpose
`reaction_smiles_file`	`reactions_list.txt`	Reaction SMILES input file.
`prepare_settings_json`	`{}`	JSON preparation options, including `autoadsorbate`, `autoadsorbate_kwargs`, and `overwrite`.
`selection_prerelax_sample`	`false`	Enables placement pre-relaxation, intactness filtering, and K-means selection.
`selection_fmax`	`0.05`	Placement relaxation force threshold in eV/Å.
`selection_steps`	`500`	Maximum placement relaxation steps.
`selection_n_kmeans`	`20`	Maximum selected placements per preparation target, not per whole run.
`selection_energy_cutoff`	`1.5`	Placement energy window above the lowest energy, in eV.
`selection_distance_cutoff`	`6.0`	Dimer adsorbate center-of-mass separation cutoff in Å.
`selection_graph_mult`	`0.8`	Neighbor-cutoff multiplier for preparation and post-hopping intactness checks against the original prepared topology. Native MinHop `mult` converts to this setting.

The pre-relaxation and sampling controls apply when selection_prerelax_sample = true. As in native NEBScape, the sampler skips energy/distance filtering when at most selection_n_kmeans intact placements remain; otherwise dimer placements can pass either the energy or distance test.

Native difference: SODA performs pre-relaxation as a separate preparation phase and stores its results in HDF5. Native files such as initial_structures.xyz do not determine whether SODA skips this phase.

Minima hopping¶

minhop_settings_json contains a JSON object of supported native scientific settings. The MACE example uses:

minhop_settings_json = {"Ediff0": 1.0, "T0": 2000, "timestep": 0.5, "totalsteps": 10, "maxtemp": 10000, "optimizer": "FIRE"}

JSON key	Meaning
`Ediff0`	Initial energy acceptance threshold in eV.
`T0`	Initial MD search temperature in K; independent of `[Main] temperature`.
`timestep`	MD time step in fs.
`totalsteps`	Counter limit per start, including the initial relaxation; not MD steps or accepted minima.
`maxtemp`	Stops the search when its temperature reaches this value in K.
`optimizer`	Local relaxation optimizer: `FIRE` or `QuasiNewton`.

Native difference: minhop_share_minima_traj (default false) replaces native share_minima_traj. When enabled, starts in the same history group share SODA’s typed seed and accepted-minima records rather than a shared trajectory file. With pre-relaxation, every intact group seed is present before the first start, including unselected and unconverged seeds. Seeds count as prior minima and precede all proposals for duplicate handling.

After a group’s hopping history is settled, mandatory native finalization relaxes every retained search minimum and preparation seed with FIRE, fmax=0.05 eV/Å and at most 500 steps. It removes Hookean constraints, retains fixed atoms, and checks connectivity against the original prepared structure using selection_graph_mult. These fixed relaxation settings do not inherit the hopping optimizer or the configurable placement relaxation thresholds. Raw search geometries and constrained energies remain in the audit history; geometry preparation uses only intact, converged finalized endpoints after the whole dependency group completes. Independent groups may overlap.

With minhop_settings_json = {"optimize_only": true}, every prepared start goes directly to the same finalizer, using its original group reference. Each start is relaxed once; no hopping jobs or hopping-history rows are created. Non-intact and unconverged results remain recorded but ineligible. Native omissions produce completed zero-output outcomes; execution exceptions remain errors. Search finalization can add up to 500 FIRE steps per source. It restores the native scientific pipeline, with no promised speedup or Sella success rate.

Rebuild the C++ executable and deploy the matching Python adapters and analyzer from the same source version, then start a fresh run. Its schema-7 checkpoints include explicit run mode, reference, finalization-work and finalization-result counts, with finalization contract revision 2. Old databases are not upgraded or repaired by this change. Newly created databases use the ordinary checkpoint and --loadrun routines.

SODA-only limit: max_minima_per_job (default 20) caps staged MinHop proposals per job, including rejected proposals. At the limit, a continuing chain returns to the master for ordinary continuation scheduling. It is a buffer/batching bound, not a scientific stopping criterion; longer chains do not require raising it. An internal violation of the staging bound aborts.

Geometry pairs and interpolation¶

Option in `[NEBScape]`	Default	Purpose
`geometry_pair_reduce_method`	`decaf`	Endpoint reduction method: `decaf` or `kmeans`.
`geometry_pair_num_kmeans`	`10`	K-means centroid count and reduction threshold.
`geometry_pair_energy_cutoff`	`1.2`	Energy window above the lowest minimum, in eV, for ranged Pareto selection.
`geometry_pair_distance_cutoff`	`4.5`	Absolute distance cutoff in Å: donor–acceptor separation for transfer, or breaking-bond length for dissociation.
`geometry_pair_max_num_groups`	`10`	Maximum number of DECAF groups.
`geometry_pair_max_num_pairs`	`20`	Ranked-pair limit per reaction mapping; native early-return paths can retain more.
`geometry_pair_return_all`	`true`	Includes native slab-symmetry alignment variants.
`aligned_fs_relax_fmax`	`0.05`	Force threshold for aligned final-state relaxation in eV/Å.
`aligned_fs_energy_threshold`	`0.1`	Uses the converged aligned final state only if its absolute energy change is below this value in eV.
`final_interpolation_numimages`	`18`	Number of internal images, excluding both endpoints.
`final_interpolation_max_num_permutation`	`2`	Maximum index-permuted interpolations per geometry pair.
`final_interpolation_max_num_interpolations_per_mapping`	`5`	Maximum final interpolations retained per atom mapping.

Eighteen internal images make twenty with endpoints, matching native prepare_neb(numimages=18). Larger pair and permutation limits increase downstream work; they do not set NEB convergence.

NEB scientific controls¶

Set supported NEB options in neb_settings_json. An empty object {} uses the reviewed NEBScape 0.3.1 defaults below.

JSON key	Default	Purpose
`switch_climb`	`true`	Enables the native non-climbing then climbing sequence.
`no_climb_step`, `no_climb_fmax`	`200`, `0.05`	Non-climbing optimizer step limit and force threshold in eV/Å.
`climb_step`, `climb_fmax`	`2000`, `0.05`	Climbing optimizer step limit and force threshold in eV/Å.
`steps`, `fmax`	`1000`, `0.05`	Optimizer step limit and force threshold in eV/Å when climbing is disabled.
`method`, `k`	`aseneb`, `0.1`	ASE NEB method and spring constant in eV/Å².
`pre_relax_fmax`	`null`	Endpoint pre-relaxation force threshold in eV/Å; `null` skips it.
`refine_neb`	`false`	Checks chemical fidelity and can split/rerun a band before climbing.
`refine_with_sella`	`false`	Enables native Sella refinement and IRC validation when required.
`return_irc_traj`	`false`	Retains IRC frames from Sella refinement; does not enable refinement itself.
`sella_n_restarts`	`0`	Number of native Sella retries when that refinement is enabled.

For example, this explicitly retains the two-stage step limits:

neb_settings_json = {"switch_climb": true, "no_climb_step": 200, "no_climb_fmax": 0.05, "climb_step": 2000, "climb_fmax": 0.05}

As in native NEBScape, switch_climb: true uses the stage-specific limits; changing steps alone does not change the climbing stage. Use the [NEBScape] NEB settings rather than the example’s general [Optimizer] or [Saddle Search] entries to tune this calculation. The NEB settings reference lists all admitted scientific keys and their defaults.

Calculator and runtime controls¶

The MACE example sets [ASE Calculator] kind = mace_foundation, device = gpu, model = mh-1, and the oc20_usemppbe head in kwargs_json. These are example choices, not the schema defaults. See calculator preparation for the checkpoint and environment requirements.

MPI ranks and --num-gpu-workers-per-node determine worker capacity. Keep CPU workers available for geometry preparation and interpolation. --storesummariesinfile=1 enables stored search summaries, while --flushafterjobsdone controls result flushing. These are runtime controls, separate from scientific sampling and convergence settings.

Stop at a phase boundary¶

Use a SODA executable rebuilt from the updated sources. To save a reproducible starting point for NEB, add this to config.ini:

[Debug]
nebscape_stop_after_phase = final_interpolation

SODA completes all work through final interpolation, including band selection, and saves the ordinary completed-phase checkpoint. It then shuts down normally with exit code zero, without admitting any NEB jobs. Earlier permitted phases can still overlap. Collection, result registration, persistence, and shutdown use the ordinary workflow routines.

The accepted values are:

Value	Last phase allowed to compute
`none`	Unrestricted run; also the default when the option is omitted.
`placement_preparation`	Placement preparation and selection.
`minima_hopping`	Minima hopping, continuations, filtering, and mandatory native finalization; optimize-only completes its prepared-start finalization here.
`geometry_pair_preparation`	Endpoint selection, mapping, and geometry-pair candidate generation.
`aligned_fs_relaxation`	Relaxation and final-state choice for aligned candidates.
`final_interpolation`	Final interpolation and retained-band selection, before NEB.
`neb_calculation`	NEB and any enabled Sella/IRC work; this finishes the full workflow.

A completed phase means all its tasks reached their ordinary terminal outcomes. It does not mean every optimization converged or every band passed its scientific checks. Allowed phases with no work still complete normally; excluded phases remain unstarted. The option does not impose a timeout on a calculation that has yet to finish.

The target is read at startup and stays fixed for that invocation. Non-none values require [Main] job = nebscape. Despite its placement in [Debug], the option is available in normal builds and does not require runtime test probes. Mandatory NEBScape phase/result records are saved independently of the optional --storesummariesinfile setting.

Resume the saved run¶

Remove nebscape_stop_after_phase or set it to none, retain the same scientific configuration and required inputs, and use ordinary --loadrun:

mpirun -n 3 "$SODA_BIN" \
  --loadrun=/absolute/path/to/stopped/output/output.h5 \
  --num-gpu-workers-per-node=1

Run this example from a new working directory with the matching inputs and calculator environment; it assumes one head, one CPU worker, and one GPU worker. Set SODA_BIN to an absolute executable path. No analyzer extraction, database conversion, or special restart command is needed. Use an absolute checkpoint path: relative --loadrun paths are resolved inside outputdir. See Restarting a run for the general restart rules.

Keeping an already-reached target launches no new scientific work. Choosing an earlier target does not rewind the database or remove historical partial downstream results. Choosing a later target allows unfinished phases through that new boundary. The option and worker allocation do not change the scientific fingerprint; incompatible scientific settings or reaction catalogs still fail the normal restart checks.

Compare dedicated and shared GPUs¶

First finish a run with final_interpolation as its target. Prepare two fresh working directories with the same required inputs, calculator assets, and scientific configuration. Remove the stop option in both. Both runs can read the same closed HDF5 checkpoint, preserving the selected bands and image arrays without repeating upstream sampling. Separate working directories also isolate the workspace/ trees; changing only --outputdir does not do that.

For a local allocation with one visible GPU, these example layouts retain one CPU worker and one head, while changing the GPU workers from one to three:

export SODA_CHECKPOINT=/absolute/path/to/stopped/output/output.h5
(
  cd /absolute/path/to/replay-dedicated || exit 1
  mpirun -n 3 "$SODA_BIN" --loadrun="$SODA_CHECKPOINT" \
    --num-gpu-workers-per-node=1
)
(
  cd /absolute/path/to/replay-shared || exit 1
  mpirun -n 5 "$SODA_BIN" --loadrun="$SODA_CHECKPOINT" \
    --num-gpu-workers-per-node=3 --allow_gpu_oversubscribe
)

Keep calculator, NEB, and Sella settings unchanged, and apply your site’s normal MPI/thread allocation settings. Verify device assignments and each worker’s reported memory fraction in the logs. This controls the saved starting inputs; it does not guarantee equal NEB/Sella outcomes, measure GPU performance, or by itself establish the cause of a success-rate difference. CPU orchestration tests do not establish GPU convergence parity. See the GPU runtime notes and output analysis guide.

Unsupported and redirected settings¶

Native parameters cannot all be copied directly

Native difference marks replaced behavior; unsupported marks rejected choices. These notes apply to the SODA integration and conversion helpers.

Native parameter or input	Restriction or alternative when using SODA
`autopara_info`, `remote_info`, `num_python_subprocesses`, `n_jobs`	Native difference: MPI allocation and SODA worker options replace native scheduling; these keys are rejected in NEB JSON.
`calculator`, `logfile`, `outputs`, `workdir`, `trajectory` in NEB settings	Native difference: use `[ASE Calculator]` and HDF5 output; these native keys are rejected.
`autoadsorbate_kwargs.parallel`	Native difference: SODA schedules preparation; leave unset or `null`.
`prerelax_sample`, `n_kmeans`, `mult`, `share_minima_traj` in MinHop JSON	Renamed: use `selection_prerelax_sample`, `selection_n_kmeans`, `selection_graph_mult`, and `minhop_share_minima_traj` in `[NEBScape]`.
ASE `parallel`, `world`, `precon` in NEB JSON	Unsupported overrides. Each band runs serially within one task; SODA distributes tasks.
MinHop `check_minima` callback	Unsupported when non-null, including in directly written JSON.
Lambdas and instantiated calculator objects	Unsupported by static conversion. Use a calculator preset or importable custom calculator factory.
Native constructor `numimages`	Not converted: native `prepare_neb` does not use it. Set `prepare_params.numimages` or SODA `final_interpolation_numimages`.

Unknown keys in neb_settings_json are rejected. Conversion reports may instead list omitted native execution controls: review that report before running converted inputs. The native parameter conversion guide describes supported mappings and explicit omissions.