AKMC settings

Use this reference when adapting the EAM, GAP, or MACE example. The tables cover the settings most relevant to these tutorials, rather than every SODA option.

Scientific settings belong in config.ini. SODA runtime options go after the executable in the launch command. The force model is selected separately in potfiles/in.lammps. Defaults below apply when an entry is omitted; the example files often override them.

Select and control AKMC

[Main] job = akmc selects AKMC and is also the default. The bundled AKMC examples therefore work without adding this entry.

Option	Default	Purpose
[Main] temperature	300.0	Temperature in K used for rates and thermal windows. The examples use 600 K.
[Main] random_seed	-1	Seeds random-number generation when nonnegative; negative values request nondeterministic seeding. A fixed seed does not guarantee identical trajectories across parallel layouts or result-arrival orders.
[AKMC] max_kmc_steps	0	Limits KMC transitions performed during this invocation, including after a restart. 0 means unlimited; a positive value stops after that many transitions. This does not count saddle searches or collection cycles.
[AKMC] confidence	0.99	Target search confidence before leaving a state. Choose a value between 0 and 1; a higher target generally needs more searches. This estimator is not a guarantee of complete physical sampling.
[AKMC] confidence_scheme	old	old uses consecutive relevant rediscoveries; new uses the number of relevant processes and their random-search discovery counts. All bundled AKMC examples select new.
[AKMC] confidence_correction	false	Adjusts the confidence estimator using the minimum-to-maximum discovery-count ratio among relevant processes. Leave it disabled for the tutorial settings.
[AKMC] thermally_accessible_window	20	Includes processes in the rate table and confidence calculation when their forward barrier is within this many kT above the lowest barrier. It is not an energy in eV.
[AKMC] thermally_accessible_buffer	0	Adds a margin in kT to the search-retention window. It does not expand the window used by the KMC rate table.
[Recycling] use_recycling	true	Seeds searches using processes from the predecessor state, skipping the process used to enter the current state. Recycled proposals still undergo process searches.
[Debug] use_mean_time	false	When true, advances each KMC step by the mean residence time, 1 / total_escape_rate, instead of drawing an exponentially distributed waiting time. Keep false for the ordinary stochastic timing.

At 600 K, thermally_accessible_window = 20 is approximately 1.03 eV above the lowest barrier; it is not a 1.03 eV absolute barrier cutoff. The separate [Saddle Search] max_energy setting is in eV.

Step limit and native EON differences

max_kmc_steps = 0 leaves the run uncapped by KMC step count, matching native EON. Regular output flushing remains active. A positive limit forces a final write and normal shutdown when reached. The EAM adatom example uses 20000; the GAP and MACE setup checks use 1.

The native EON guide describes the method and upstream options. This integration is based on EON revision r2545; it does not implement the full current EON configuration surface. In particular, basining/superbasin handling is unavailable. SODA supplies its own MPI launch, job queues, HDF5 output, and --loadrun restart mechanism, so native EON server/client launch commands and restart files do not apply here.

The step-limit behavior above is checked against the current AKMC loop. The configuration schema lists the parsed options; the descriptions here account for the runtime behavior where inherited help differs.

Search centers and structure comparison

AKMC uses displacement-based search-center selection. Unlike APE, it honors under-coordinated and least-coordinated displacement weights and does not use descriptor clusters or soft-fixed environment labels.

Option	Default	Purpose
[Saddle Search] displace_random_weight	0.0	Relative weight of random search-center selection. When all three displacement weights are zero, the generator falls back to random selection.
[Saddle Search] displace_under_coordinated_weight	0.0	Relative weight of selecting free atoms whose coordination is at most displace_max_coordination. The examples set this to 1.0.
[Saddle Search] displace_least_coordinated_weight	0.0	Relative weight of choosing free atoms with the lowest coordination.
[Saddle Search] displace_max_coordination	11	Maximum coordination allowed for an under-coordinated search center. The adatom EAM example uses 8.
[Saddle Search] displace_radius	4.0	Radius in Å around the selected center within which free atoms receive initial displacements. It does not constrain later search motion.
[Saddle Search] displace_magnitude	0.1	Gaussian standard deviation in Å per Cartesian displacement component, before optional biasing. It is not a fixed displacement length.
[Saddle Search] min_mode_method	dimer	Chooses dimer or lanczos for the lowest-mode search.
[Saddle Search] max_energy	20.0	Rejects a search that rises this many eV above its reactant, or a completed process whose forward or reverse barrier exceeds this value.
[Saddle Search] nonlocal_count_abort	0	Aborts when at least this many atoms move by at least nonlocal_distance_abort from the starting displaced geometry; 0 disables the check.
[Saddle Search] nonlocal_distance_abort	0.0	Motion threshold in Å for that check. Set a positive distance when enabling the count threshold.
[Process Search] minimization_offset	0.2	Full-configuration displacement length in Å along each direction of the normalized saddle mode before endpoint minimization.
[Optimizer] opt_method	cg	Structural optimizer: cg, qm, lbfgs, fire, or sd. The GAP and MACE examples use fire.
[Optimizer] converged_force	0.01	Force tolerance in eV/Å, evaluated with convergence_metric.
[Optimizer] convergence_metric	norm	norm uses the combined force-vector norm over free atoms; max_atom uses the largest atomic force norm; max_component uses the largest absolute component.
[Optimizer] max_iterations	1000	Iteration limit for one minimization. Saddle-search max_iterations and converged_force inherit optimizer values when omitted.
[Structure Comparison] energy_difference	0.01	Energy tolerance in eV for matching states and comparing process barriers; it is not an energy per atom.
[Structure Comparison] distance_difference	0.1	Per-atom geometric mismatch tolerance in Å when comparing structures and processes.
[Structure Comparison] indistinguishable_atoms	true	Allows same-species atom permutations when matching product structures to states. Process-repeat and endpoint-connectivity checks still preserve atom indices.

Fixed atoms in pos.con or supported constraints in pos.xyz remain a separate structural constraint. If no eligible free search-center atoms remain, revisit the geometry and displacement settings.

Prefactors and force evaluation

The tutorials use harmonic transition-state-theory rates. A forward rate combines the forward prefactor with the Boltzmann factor for its barrier at [Main] temperature.

Option	Default	Purpose
[Prefactor] default_value	0	0 calculates prefactors; a positive value in s⁻¹ skips that calculation and uses the same constant in both directions. It is not a fallback used only after failure.
[Prefactor] filter_scheme	fraction	Chooses atoms for prefactor evaluation: fraction selects by cumulative displacement, while cutoff uses min_displacement; both add nearby free atoms. Examples use cutoff.
[Prefactor] filter_fraction	0.9	Cumulative fraction of displacement used to select atoms in the fraction scheme, not a fraction of the atom count.
[Prefactor] min_displacement	0.25	Endpoint-to-saddle displacement threshold in Å used by the cutoff scheme.
[Prefactor] within_radius	3.3	Radius in Å for adding free neighbors around the selected atoms in the saddle structure.
[Prefactor] min_value, max_value	1e9, 1e21	Accepted range of calculated prefactors in s⁻¹. Out-of-range values reject the process; they are not clamped to these bounds.
[Potential] lammps_threads	0	Positive values request LAMMPS OpenMP threads and require its OPENMP package. Match the allocated cores; leave unset or 0 for plain EAM and native MACE GPU builds.
[Potential] lammps_logging	false	Enables the LAMMPS-side log for diagnosing the force setup.

Using a constant prefactor changes the rate model. Keep the same prefactor policy, force tolerances, and temperature when comparing execution layouts.

Command-line options

These arguments belong after "$SODA_BIN". MPI placement flags and Slurm resource requests belong to the launcher or scheduler; see Parallel execution.

Option	Purpose
--numranksperwgroup=1	Sets MPI ranks per worker group; the current implementation requires 1. A worker can still use several CPU cores through a supported threaded calculator.
--num-gpu-workers-per-node=N	Selects GPU-capable workers per node: 0 for CPU workers, positive for that count, or -1 for all workers when the active setup requires a GPU. It does not mean one worker per GPU.
--allow_gpu_oversubscribe	Allows multiple workers to share a GPU. Check model and calculation memory requirements first.
--numjobsperwgroup=N	Sets the per-worker contribution to the node’s shared queue capacity: W × N slots for W workers. It does not create more workers.
--numjobsdonetotriggerupdate=N	Sets the completed-result readiness threshold per node. Keep it within that node’s queue capacity; empty queues or buffer pressure can trigger earlier collection.
--storesummariesinfile=1	Retains additional search-summary records for analysis. State/process records and KMC history are separate from these optional summaries.
--flushafterjobsdone=N	Enables a write condition after more than N job summaries have been collected since the previous flush; 0 disables this condition.
--flushafterminutes=N	Enables an elapsed-time write condition in minutes; 0 disables it. With both thresholds positive, both must be exceeded.
--outputdir=NAME	Selects the output directory, normally output.
--loadrun=PATH	Restores a saved SODA database. Use a working copy and follow Restarting a run.

The tutorials use a two-slot contribution per worker, a two-result readiness threshold, and only the job-count flush condition. Both flush options set to 0 request a write whenever new results are collected. Memory pressure can force a write, and the positive KMC step limit forces a final write. Flush settings do not save unfinished searches or specify a KMC step count.

Larger queues can keep fast EAM searches supplied with work, but may schedule more searches than are needed before confidence is reached. Smaller queues can be useful for expensive MACE or GAP searches. Tune queue depth and collection frequency separately, using progress and memory measurements.

State-buffer options such as --soda_max_resident_states_per_node and --maxnumactivestatespernode control per-node memory capacity, not the total number of states the trajectory can visit. Start with the defaults for the small examples; check effective capacities in the startup log before adopting the larger batch templates.