PotentialConfig arms

This page lists the arms of the Cap’n Proto PotentialConfig union and what potserv does with each.

rgpot user parameters (PotentialConfig) over RPC

Backend options for a live Potential go in PotentialConfig (CppCore/rgpot/rpc/Potentials.capnp, a copy of the pinned potentials-schema). It is a union whose arms and ordinals are none @0, nwchem @1, cpmd @2, metatomic @4, lammps @5, xtb @6, tblite @7, uma @8, lj @9, morse @10, zbl @11, d3 @12, d4 @13, mopac @14, skala @15, expr @16 and cp2k @17. Outside the union, common @3 is a CommonMethodSpec overlay. Geometry stays on ForceInput; configure(config) applies method and backend setup only. potserv applies nwchem, cpmd and morse on the matching backend, and cp2k on a build with CP2K. none is a no-op on every backend. Every other arm gets ok=false with a message that names the arm. An arm from a newer schema is named by its discriminant. D3Pot and D4Pot stay in-process Potential summands; potserv refuses the d3 and d4 arms.

NWChem arm (PotentialConfig.nwchem / NWChemParams)

With potserv <port> NWChem, pass configure with the nwchem arm set. The payload fields (basis, theory, scfType, charge, multiplicity, enginePath, nwchemRoot, task, title, memoryMb, scratchDir, permanentDir, inputBlocks, inputStanzas) are NWChem-specific.

Python: tests/nwchem_params.py builds PotentialConfig with the nwchem arm. The helper uses RGPOT_NWCHEM_ENGINE for enginePath and NWCHEM_TOP for nwchemRoot when explicit values are not supplied. For BLYP, set theory="dft" and scfType="blyp". calculate still needs a loadable libnwchemc engine.

Morse arm (PotentialConfig.morse / MorseParams)

With potserv <port> Morse, pass configure with the morse arm set. MorseParams carries de, a, re and cutoff, with the platinum defaults of MorseConfig (0.7102 eV, 1.6047 1/Angstrom, 2.897 Angstrom, 9.5 Angstrom). The server rebuilds its MorsePot from those values and keeps its switch width, so the next calculate uses them. A non-finite value, a cutoff that is not positive, or a cutoff below the switch width gets ok=false and leaves the pot as it was. tests/rpc_integ.py doubles de and checks that the energy at re doubles.

CPMD arm (PotentialConfig.cpmd / CPMDParams)

With potserv <port> CPMD, pass configure with the cpmd arm set. CPMDParams is method and backend setup only; each calculate() call still carries geometry in ForceInput.

The rgpot frontend loads libcpmdc at run time and forwards serialized CPMDParams to that C ABI. Engine lookup tries CPMDParams.enginePath, then CPMDC_LIBRARY, RGPOT_CPMDC_ENGINE, RGPOT_CPMD_ENGINE, and the default shared-library names. A non-empty CPMDParams.cpmdRoot is exported as CPMD_ROOT before the engine loads (not on Windows).

The payload fields are method-level defaults (functional, cutOffRy, charge, multiplicity, task, title, memoryMb), frontend hints (enginePath, cpmdRoot), file placement (scratchDir, permanentDir), raw inputBlocks, and structured inputSections. CPMDInputSection has typed arms for system, cpmd, dft, atoms and set, a generic arm, a raw arm, directive-only arms for the other CPMD sections, and typed arms for &VDW, &PROP, &LINRES, &PIMD, &PATH, &TDDFT, &RESP, &EXTE and &VECTORS. The typed cpmd section includes wavefunction and geometry optimization, molecular dynamics, orbital and geometry convergence thresholds, iteration limits, timestep, electron mass, CP/BO/EH/PT/classical MD variants, MD file, Nose/Berendsen/Langevin/annealing/quench thermostat controls, RATTLE/SHAKE, constraints, Trotter factor, restart, print/store, center molecule, DIIS/ODIIS/PCG/diagonalization, free-energy, interface, QMMM, bicanonical, CDFT, properties, and trajectory controls. The typed dft section includes functional, LSD, GC cutoff, XC driver, LIBXC, LR kernel, refunct, MTS high/low functionals, HFX, HFX screening, Hubbard, alpha, beta, old/new code selection, correlation, exchange, and Becke88 controls.

Python: tests/cpmd_params.py builds PotentialConfig with the cpmd arm. The helper uses CPMD_ROOT for cpmdRoot and CPMDC_LIBRARY, RGPOT_CPMDC_ENGINE or RGPOT_CPMD_ENGINE for enginePath when explicit values are not supplied. Its input_sections argument builds the generic, system, cpmd, dft, atoms, set and raw arms without raw Cap’n Proto builder code in clients.

Typed atoms sections carry pseudopotential entries and structured directives for ATOMS keywords that are not pseudopotential entries. Per CppCore/rgpot/CPMDPot/README.md, the engine groups ForceInput coordinates into &ATOMS, requires entries for every atomic number present in a step, and without an atoms section has built-in BLYP defaults for H and O only.

The cpmd configure result is ok=false when no usable libcpmdc engine can be loaded or when the engine rejects the params. The integration script exercises RPC configure() with the cpmd arm:

pixi run -e rpctest python tests/rpc_integ.py \
  --server-bin build/CppCore/potserv \
  --cpmd-smoke