APE settings

Use this reference when adapting the EAM or MACE example. The tables summarize the settings most relevant to APE; they are not a complete list of SODA options.

Scientific settings belong in the run directory’s config.ini. Runtime options go after the SODA executable in the launch command. The force model is selected separately by pair_style and pair_coeff in potfiles/in.lammps.

Select and control exploration

Set [Main] job = ape explicitly.

The following entries belong in [APE]. Defaults are used when an entry is omitted; the repository examples may override them.

Option	Default	Purpose
max_cycle	0	Limits result-collection and registration cycles; 0 leaves them uncapped. A cycle can include several searches and is not a count of accepted processes.
sampling_strategy	energy	Selects the primary candidate-sampling strategy: energy favors lower-energy source structures, while random weights candidates by their remaining individual search quotas. Both work with environment clusters that still need searches.
soft_fix	true	Excludes environment clusters identified from SoftFixAtomIDs.dat from search-center selection on a fresh run. See Soft fixing for how the initial atoms define these clusters.
individual_search_sample	5	Sets the per-descriptor quota of scheduled searches in primary candidate selection, including searches still in progress. Fallback sampling can schedule further searches, so this is not a hard lifetime limit.
cluster_sample_batch	20	Controls the number of draws attempted per cluster in random and fallback sampling. It does not set the number of MPI workers.
cluster_search_sample	100	Sets the completed-search threshold summed over a cluster’s descriptor records. It counts completed attempts, not just unique processes found. This is a sampling criterion, not a guarantee that all physical processes have been found.

Soft fixing

Soft fixing controls which local environments APE targets for saddle searches. With [APE] soft_fix = true, APE reads SoftFixAtomIDs.dat from the run directory. This file lists zero-based atom IDs in the initial input structures; for multiple structures, group the IDs under the corresponding pos0, pos1, … headers, as in the EAM example.

On a fresh run, the file is required when soft_fix = true; when soft_fix = false, it must be absent. A restart restores the saved soft-fixed clusters from the database instead of reading this file again.

During initialization, APE identifies the environment clusters containing the listed atoms in their corresponding initial structures and marks those clusters as soft fixed. Atoms whose local environments belong to any of these clusters are excluded from search-center selection, including atoms that were not explicitly listed in the file.

Soft-fixed atoms remain free to move during saddle searches and during structure optimization, subject to any separate fixed-atom constraints in the input structures. Soft fixing restricts the choice of search centers; it does not constrain atomic positions.

Cluster membership depends on the local environment

The excluded cluster IDs are determined from the listed atoms in the initial structures. An atom’s environment can differ between structures, so the same atom can belong to a soft-fixed cluster in one structure and an unrestricted cluster in another. In the latter case, it can be selected as a search center, subject to the other sampling rules. Soft fixing therefore follows environment-cluster membership, rather than permanently excluding an atom ID throughout the exploration.

Descriptors and DECAF classification

These [Descriptors] entries control the local environments supplied to APE’s DECAF classifier. They do not select the potential used for forces.

For the classification method, cite:

Lai, K. C., Matera, S., Scheurer, C., and Reuter, K. “A fuzzy classification framework to identify equivalent atoms in complex materials and molecules.” The Journal of Chemical Physics 159(2), 024129 (2023). doi:10.1063/5.0160369.

The implementation is available in the DECAF repository.

Defaults apply when an entry is omitted from [Descriptors].

Option	Default	Purpose
descriptor	double_soap	Selects double_soap, soap, or mace as the local-environment representation.
mace_path	""	Path to the Python MACE model for descriptor generation; empty by default. The native LAMMPS force model has its own path in potfiles/in.lammps.
mace_device	gpu	Selects cpu or gpu for MACE descriptors; apu is accepted as an alias for gpu. Match this to the installed dependencies and worker allocation.
mace_num_layers	-1	Sets the number of MACE interaction layers used for descriptors; 0 or a negative value uses all model layers.
NNDistance	3.3	Sets the reference nearest-neighbor distance in Å, used to scale the SOAP cutoffs and Gaussian widths. Choose it for the material and structure being explored.
soap_nmax	4	Sets the radial basis size for soap.
soap_lmax	3	Sets the maximum angular order for soap.
soap_rcut	1.866	Sets the cutoff radius for soap, in units of NNDistance.
soap_sigma	0.233	Sets the Gaussian width for soap, in units of NNDistance.
soap_L_nmax	4	Sets the radial basis size for the long-range channel of double_soap.
soap_L_lmax	3	Sets the maximum angular order for the long-range channel of double_soap.
soap_L_rcut	1.866	Sets the cutoff radius for the long-range channel of double_soap, in units of NNDistance.
soap_L_sigma	0.233	Sets the Gaussian width for the long-range channel of double_soap, in units of NNDistance.
soap_S_nmax	8	Sets the radial basis size for the short-range channel of double_soap.
soap_S_lmax	4	Sets the maximum angular order for the short-range channel of double_soap.
soap_S_rcut	1.21	Sets the cutoff radius for the short-range channel of double_soap, in units of NNDistance.
soap_S_sigma	0.151	Sets the Gaussian width for the short-range channel of double_soap, in units of NNDistance.
embedding	MDS	Selects MDS or PCA for the descriptor embedding.
embedding_dim	0	Sets the descriptor embedding dimension; 0 selects it automatically using DECAF’s broken-stick criterion on the initial training data.
bandwidth_estimate	HaarWavelet	Selects HaarWavelet or Gaussian estimation when initial_bandwidth = 0.
initial_bandwidth	0.0	Sets the mean-shift clustering bandwidth directly when positive; it is not an initial guess. 0 estimates it from the initial embedded descriptors. The selected bandwidth is retained for subsequent updates.
cluster_minimum_sample	10	Sets the population threshold at which additional product descriptor candidates in an existing cluster can be discarded. Population counts assigned descriptor registry entries, including fixed entries but excluding alias-blocked duplicates; search eligibility is separate. It is not a minimum size for forming a cluster. [APE] cluster_search_sample separately counts completed searches.

The physical SOAP cutoff is soap_rcut × NNDistance, and the Gaussian width is soap_sigma × NNDistance, both in Å. The same scaling applies to the soap_L_* and soap_S_* cutoffs and widths. For example, soap_rcut = 1.866 with NNDistance = 3.3 gives a cutoff of 6.1578 Å.

Use Analyzing APE output to inspect the resulting clusters. Cluster labels belong to a particular descriptor model and run; their numbers need not match across calculations.

Search and structure settings

APE uses shared saddle-search, minimization, and structure-comparison settings. Begin with the complete example configuration and adjust settings for your potential and system.

APE selects search centers through descriptor sampling. Its displacement generator disables under-coordinated and least-coordinated center selection, so displace_max_coordination has no effect in APE, even if it is present in config.ini. The corresponding displace_under_coordinated_weight and displace_least_coordinated_weight settings are also ignored in APE.

Each entry below includes its config.ini section. Defaults apply when the option is omitted; example configurations may use different values.

Option	Default	Purpose
[Saddle Search] min_mode_method	dimer	Selects dimer or lanczos for the lowest-mode search.
[Saddle Search] displace_radius	4.0	Sets the radius in Å around the selected search-center atom within which free atoms receive initial random displacements. It does not restrict later motion during the search.
[Saddle Search] displace_magnitude	0.1	Sets the Gaussian standard deviation in Å for each Cartesian component of the initial random displacement, before any optional void bias. It is not a fixed total displacement length.
[Saddle Search] max_iterations	Inherited (1000)	Limits iterations in an individual saddle search, separately from the overall APE cycle limit. When omitted, uses [Optimizer] max_iterations.
[Saddle Search] max_energy	20.0	Rejects a search whose energy rises more than this many eV above its reactant. Also rejects a completed process if either its forward or reverse barrier exceeds this value.
[Saddle Search] nonlocal_count_abort	0	Aborts when at least this many atoms have moved by at least nonlocal_distance_abort from the saddle search’s starting, displaced geometry; 0 disables the check.
[Saddle Search] nonlocal_distance_abort	0.0	Sets that motion threshold in Å. Choose a positive distance when enabling nonlocal_count_abort: at the default 0, even unmoved atoms meet the distance test.
[Saddle Search] converged_force	Inherited (0.01)	Sets the saddle-search force tolerance in eV/Å, using [Optimizer] convergence_metric. When omitted, uses [Optimizer] converged_force. A positive final mode curvature also causes rejection.
[Process Search] minimization_offset	0.2	Sets the displacement length in Å along the normalized saddle eigenvector, in each direction, before relaxing the two endpoints. This is the length of the full configuration displacement, not a distance applied to every atom.
[Optimizer] opt_method	cg	Selects the optimizer for structural minimization and saddle-search translation: cg, qm, lbfgs, fire, or sd.
[Optimizer] converged_force	0.01	Sets the structural-minimization force tolerance in eV/Å. With the default convergence_metric = norm, this applies to the combined force-vector norm over free atoms, not a per-atom maximum.
[Optimizer] max_iterations	1000	Limits iterations in an individual structural minimization.
[Structure Comparison] energy_difference	0.01	Sets the energy tolerance in eV for matching states and comparing process barriers when identifying repeat processes. It is not an energy per atom.
[Structure Comparison] distance_difference	0.1	Sets the per-atom geometric mismatch tolerance in Å for structure and process comparisons.
[Structure Comparison] indistinguishable_atoms	true	Allows same-species atom permutations when matching product structures to states. Process-repeat checks and endpoint connectivity checks still preserve atom indices.
[Potential] lammps_threads	0	Requests OpenMP threads inside LAMMPS when positive; this requires its OPENMP package and a matching CPU allocation. Leave it unset or 0 for the plain EAM example and native MACE GPU builds.
[Potential] lammps_logging	false	Enables the LAMMPS-side log for diagnosing the force setup.

Command-line options

These are arguments to soda, after "$SODA_BIN". MPI and Slurm placement options such as --map-by, --bind-to, and --cpus-per-task belong to the launcher or scheduler; see Parallel execution.

Option	Purpose
--numranksperwgroup=1	Sets the number of MPI processes per worker group; the current implementation requires 1. Each worker’s LAMMPS instance can still use multiple CPU cores through OpenMP when the build supports it; match lammps_threads to the cores allocated per rank (see threaded workers).
--num-gpu-workers-per-node=N	Selects GPU-capable workers on each node. -1 selects all workers if the active setup requires a GPU, otherwise none; it does not select one worker per detected GPU. 0 requests CPU-only workers and a positive value requests that count. APE GPU process searches require every worker to be GPU-capable.
--allow_gpu_oversubscribe	Allows more GPU workers than visible GPUs. Shared devices must have enough memory for their workers’ models and calculations.
--numjobsperwgroup=N	Sets the per-worker-group contribution to the node’s shared job-queue capacity (W × N for W workers). Jobs are not reserved equally for each worker. This controls buffering, not CPU threads or worker count.
--numjobsdonetotriggerupdate=N	Sets the completed-result readiness threshold per node, not a total across all nodes. The master waits for all nodes to report readiness. Keep it within each node’s queue capacity; empty queues or buffer pressure can make a node ready earlier.
--storesummariesinfile=1	Saves additional process-search summaries in the HDF5 database for later inspection.
--flushafterjobsdone=N	Sets a flush condition: more than N completed-job summaries must have been collected since the previous flush. 0 removes this condition. When the time condition is also enabled, both must be met.
--flushafterminutes=N	Sets the elapsed-time flush condition in minutes; 0 removes it. When the job-count condition is also enabled, both must be met. This does not force workers to return unfinished results.
--outputdir=NAME	Chooses the output directory, normally output.
--loadrun=PATH	Restores exploration state from a saved database. Use a working copy and follow the restart instructions.

Suggested buffer sizes

Use the following as starting points for a small workstation run or a larger HPC allocation. The workstation column uses the code defaults; the HPC column is adapted from the larger APE example. Choose sizes according to memory available per node, atoms per state, and descriptor dimensions.

Buffer setting	Workstation	Larger HPC run
--envdescr_rows_per_block — descriptor allocation block	256 rows	20480 rows
--envdescr_rows_per_shm_buffer — shared-memory descriptor chunk	256 rows	16000 rows
--maxnumenvdescrinwb — descriptor working-buffer capacity	1024 rows	16000 rows
--maxnumactivestatespernode — active-state capacity	10 states per node	355 states per node
--soda_max_resident_states_per_node — resident state-payload capacity	100 states per node	3000 states per node
--numstatesallocatedperbatch — HDF5 state-allocation batch	5 states	200 states

Larger buffers can reduce allocation and data-transfer overhead, but require more memory. These values count rows or states, so the memory required also depends on the size of each record. They do not limit the total number of states or environments the exploration can discover.

Keep envdescr_rows_per_shm_buffer <= maxnumenvdescrinwb. The runtime also raises the resident-state capacity to at least 20 states per worker and the active-state capacity if necessary, so check the effective settings in the startup log.

Queue and output settings

These complement the buffers above. Here, W is the number of workers on one node, excluding its head rank; replace expressions with integer values in your launch options. The EAM and MACE walkthroughs set --flushafterminutes=0 for job-count-only flushing; the table below instead suggests combined job-count and elapsed-time conditions.

Setting	Small workstation run	Larger HPC run
--numjobsperwgroup	10	50
--numjobsdonetotriggerupdate	2	5 × W
--flushafterjobsdone	1	3000
--flushafterminutes	5	15

The update threshold is per node and must not exceed W × numjobsperwgroup. With 71 workers, the HPC values give 355 completed results per update-ready threshold and 3550 shared queue slots per node. Choose whether to save search summaries with --storesummariesinfile according to your analysis needs.

How the flush conditions combine

APE checks flushing in its workflow loop, using results already collected from the workers. With both options positive, regular flushing requires both thresholds to be exceeded. The workstation values above therefore require more than five minutes and more than one collected job summary since the previous flush. They do not write after each job.

Set --flushafterminutes=0 to use only the job-count condition, or --flushafterjobsdone=0 to use only elapsed time. With both set to 0, APE writes whenever it collects new results. Memory pressure can force an earlier write; APE also writes when ending at max_cycle or when no dispatchable candidates remain. These settings do not guarantee an exact write interval or save unfinished searches.

Tune for the cost of each search

These suggestions are starting points, not optimized settings for every system or potential.

• Fast searches, such as EAM: longer queues can help keep workers supplied with work. Collecting more completed searches per update and using larger buffers can reduce coordination overhead, provided memory is available.

• Slower searches, such as MACE: shorter queues may already keep workers busy. Collecting fewer completed searches per update lets APE incorporate new results sooner; smaller batches may also allow smaller buffers.

Increase --numjobsperwgroup if workers regularly run out of queued work. Once the queue is sufficient, making it longer adds memory use and schedules more work based on the current exploration state, without necessarily improving throughput. Queue depth and collection frequency are separate: a longer queue can still use a small --numjobsdonetotriggerupdate threshold.

Choose buffer sizes for the actual structures and descriptors. MACE can produce larger descriptor records, so slower searches do not automatically need less buffer memory. Here, more frequent collection means fewer completed jobs per update, not necessarily shorter wall-clock intervals. The --flushafter* options separately control writing results to disk.

See Parallel execution and the examples for MPI/Slurm launch commands, CPU-thread allocation, and GPU worker settings.

Full option lists

After activating the selected build, consult its own help for all supported options and defaults:

"$SODA_BIN" --help-config
"$SODA_BIN" --help

These commands initialize MPI, so use an environment where that build can start. The corresponding source references are the configuration schema and command-line definitions.