# 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](nebscape-mace.md).

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
{repo}`configuration schema <src/python/config.yaml>` 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:

```ini
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:

```ini
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 {repo}`NEB settings reference <src/python/nebscape_neb_settings.py>` 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](nebscape-mace.md#2-prepare-the-calculator)
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`:

```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`:

```bash
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](restart.md) 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:

```bash
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](nebscape-mace.md) and
[output analysis guide](nebscape-analysis.md#check-workflow-progress).

## Unsupported and redirected settings

:::{admonition} Native parameters cannot all be copied directly
:class: tip

**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
{repo}`native parameter conversion guide <docs/soda_analyzer_nebscape.md#native-nebscape-parameter-categories-for-conversion>`
describes supported mappings and explicit omissions.
:::