C ABI reference¶
The public C ABI (application binary interface) of libcpmdc is declared in
include/cpmdc.h and include/cpmdc_features.h.
Installed headers live under include/cpmdc/.
Every function has C linkage, and the header compiles as C and as C++.
The generated API pages carry the header comments; this page adds
the units, the return conventions, and the behaviour that the implementation
in src/cpmdc.c gives each call.
Conventions¶
Item |
Convention |
|---|---|
Parameter buffers |
unpacked flat Cap’n Proto messages: |
Positions in array calls |
Angstrom, |
Energy in |
Hartree |
Gradient and force arrays |
Hartree/Bohr; forces are the negative gradient |
|
energy in |
|
0 on success, -1 on failure |
|
|
Ownership |
the caller owns every buffer it passes; the library copies what it keeps |
Threads |
one process-wide CPMD state; serialize calls into one library instance |
ForceInput unit strings are matched without regard to case.
Length: angstrom, angstroms, a, aa, bohr, au, a.u., atomic,
nm, nanometer.
Energy: hartree, ha, au, a.u., ev, electronvolt, ry, rydberg,
kj/mol, kjmol, kcal/mol, kcalmol.
The schema defaults are angstrom and eV.
ForceInput.box is empty or nine values, a row-major 3 by 3 cell in
lengthUnit, one lattice vector per row.
The caller’s box is the cell.
A non-zero ForceInput.box replaces every CELL line of &SYSTEM and its
SYMMETRY: a cubic deck and a cubic box keep SYMMETRY 1, another
orthorhombic box gets SYMMETRY 8 and CELL a b/a c/a, and a box with
off-diagonal components gets CELL VECTORS without SYMMETRY, which CPMD
refuses beside it.
An isolated deck (SYMMETRY 0, the default deck) keeps SYMMETRY 0 and
takes only an orthorhombic box; another box fails the call.
Without ANGSTROM the box goes in as Bohr.
An all-zero box is a system without a cell: the deck’s CELL stays, or a
12 Angstrom cube when the deck has none.
The hasCharge, charge, hasMultiplicity, and multiplicity fields of
ForceInput are not read by cpmdc.
Types¶
CPMDCResult¶
Field |
Type |
Meaning |
|---|---|---|
|
|
non-zero when the calculation succeeded |
|
|
total energy in Hartree, 0 on failure |
|
|
null-terminated status or error text |
CPMDCSession¶
An opaque handle.
A session holds a copy of the CPMDParams bytes, the rendered deck, the
topology accepted on its first successful step, scratch arrays for step
geometry, and the results of its last evaluation.
Result snapshots¶
Each snapshot struct starts with int valid, set by a successful evaluation.
Struct |
Contents |
Units |
|---|---|---|
|
the 24 scalars of OpenCPMD’s |
Hartree |
|
|
electrons |
|
|
Hartree |
|
|
Hartree |
|
nuclear gradient in |
atomic units |
|
row-major |
Hartree/Bohr3 |
With OpenCPMD linked, CPMDCEnergyComponents fills etot, ekin,
epseu, enl, eht, and exc; the other fields stay zero.
The reference evaluator fills etot only.
EKINC, the fictitious electronic kinetic energy, is zero for a wavefunction
optimisation.
CPMDCFeatureEntry and CPMDCFeatureKind¶
Field |
Meaning |
|---|---|
|
stable ID such as |
|
|
|
non-zero when the stub build exposes the feature |
|
non-zero when an OpenCPMD build exposes the feature |
Library status¶
Function |
Returns |
|---|---|
|
|
|
the ABI generation, equal to |
|
1 when OpenCPMD is linked, ready, and not finalized; 0 on the reference build; 0 after finalize and from the link stub |
|
marks the runtime finalized; later evaluations fail with |
|
per-thread text of the last failing public call, empty after a success |
cpmdc_last_error() is written by cpmdc_set_params(), cpmdc_configure(),
cpmdc_bind_calculator(), cpmdc_adopt_calculator_comm(), cpmdc_session_create(),
cpmdc_session_set_params(), cpmdc_session_select_orbitals(),
cpmdc_session_create_from_config(),
cpmdc_session_configure(), cpmdc_potential_result_size_for_force_input(),
and every evaluation entry point.
When the call returns CPMDCResult, the text matches message, including a
missing pseudopotential directory.
Snapshot readers (cpmdc_last_stress() and the other cpmdc_last_* /
cpmdc_session_last_* getters) do not write it: -1 means the snapshot is
absent or the output pointer is null.
cpmdc_adopted_comm() and cpmdc_capabilities_result() do not write it
either.
A capabilities return of -1 is the size query.
MPI¶
Function |
Behaviour |
|---|---|
|
collective on |
|
collective on the caller’s communicator; reads rank and size from that communicator; does not call |
|
copies the stored calculator communicator into |
cpmdc_bind_calculator() runs once per process, before the first evaluation.
cpmdc_adopt_calculator_comm() may run again after every session has been destroyed.
See running under mpirun.
Configuration without a session¶
These calls configure the process-wide state that the global array calls use.
Function |
Behaviour |
|---|---|
|
decode |
|
resolve a |
cpmdc_configure() takes the cpmd arm when it is set.
With the arm unset, a common overlay (CommonMethodSpec) lowers into
synthesized CPMDParams.
The fields it lowers are the ones cpmdc_capabilities_result() lists:
xcFunctionals, basisSet, planewaveCutoffEv, charge,
spinMultiplicity, scfEnergyToleranceEv, scfMaxIterations, kMesh,
smearing, vanDerWaalsMethod, and vanDerWaalsS6.
scfEnergyToleranceEv fills both values of CONVERGENCE ORBITALS: the
orbital threshold and the total-energy change between steps, which ends a
smeared (free-energy) SCF once the energy settles.
Setting both the arm and the overlay is rejected, and so is an overlay field
without a CPMD lowering, relativityMethod.
Global array calls¶
Each call applies the message it is given and then evaluates, so every call starts from a cold SCF.
Function |
Output |
|---|---|
|
energy |
|
energy and gradient |
|
energy and forces |
The output array holds 3 * n_atoms doubles.
Sessions¶
Function |
Behaviour |
|---|---|
|
copy and render |
|
resolve a |
|
replace the parameters; -1 once the session has accepted a topology |
|
replace the configuration from a |
|
free the session; |
|
the next evaluations start from the orbitals stored under |
The first successful step fixes the atom count and the elemental composition.
A later step with a different count or composition fails with topology change requires a new session before CPMD runs.
A reordering of the same elements stays on the session.
Coordinates, the cell, and units may change between steps.
An evaluation with the same positions returns the stored energy and forces.
A session evaluated after another session in the same process reuses the
stored orbitals when the functional, deck, cutoff, cell, charge, multiplicity,
and elemental composition match.
A different method or composition runs setup on the next evaluation (see
wavefunction state).
Session array steps¶
Function |
Output |
|---|---|
|
energy |
|
energy and gradient |
|
energy and forces |
These calls pass no cell: the deck’s CELL applies, or a 12 Angstrom cube
when the deck has none.
Session message steps¶
Function |
Output |
|---|---|
|
energy in Hartree and forces in Hartree/Bohr; |
|
a serialized |
cpmdc_session_calculate_result() writes the required byte count to
\*out_size before it checks capacity.
When capacity is too small it returns ok == 0 with PotentialResult buffer too small and does not evaluate.
The written PotentialResult carries energy and forces in the requested
units, stress, gradient, dipole, polarizability, and the cpmdc
extension fields energyComponents, chargeIntegrals, multiStateEnergies,
and mdTrajectoryRow with their ...Valid flags.
One-shot message calls¶
Function |
Behaviour |
|---|---|
|
create a session, evaluate one step, destroy the session |
|
the same with a |
|
bytes needed for one |
A one-shot call reuses the stored orbitals when its basis matches the previous call in the process. The first call of the process is cold. Use a session for more than one step.
Results of the last evaluation¶
Each getter copies a snapshot into \*out and returns 0 when out->valid is
set, -1 otherwise.
The plain form reads the calculator that ran last: the active session, or the
global state after a global call.
The session form reads that session’s own last result, also after another
session has run.
Plain |
Per session |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
The stress snapshot is valid only when the tensor was computed for a periodic
cell: OpenCPMD ran totstr (cntl%tpres, which requires a periodic cell and
CPMDC_STRESS other than 0), or the reference evaluator filled the toy
tensor for a periodic deck with a positive cell volume.
An isolated cell (symmetry 0, CLUSTER, or an isolated-molecule keyword,
including Hockney) leaves valid unset even when the box volume is positive.
CPMDC_STRESS=0 leaves it unset on a periodic cell as well.
Function |
Behaviour |
|---|---|
|
copies the rank spread of the last evaluation in the process; 0 when it ran with |
CPMDCRankSpread holds ranks, the size of the calculator communicator,
energy_h, the largest |E_r - E_0| over its ranks in Hartree, and
gradient_h_bohr, the largest nuclear-gradient component difference from
rank 0 in Hartree/Bohr.
Both are taken before every rank receives rank 0’s values, and a NaN
difference is reported as infinity.
A repeat of the stored positions keeps the spread of the evaluation that
stored them.
See environment variables.
Discovery¶
Function |
Returns |
|---|---|
|
number of rows in the feature table |
|
the contiguous table, owned by the library |
|
the matching row or |
|
a serialized |
Call cpmdc_capabilities_result(NULL, 0, &size) to query the size.
The message names the backend, its version, the ABI generation, availability,
the operations energy, forces, gradient, and stress, the
CommonMethodSpec fields the overlay lowers, and the cpmd
PotentialConfig arm.
The feature inventory describes the table.
RESTART file library¶
include/cpmdc_restart.h declares a separate static library,
libcpmdc_restart, that reads and writes CPMD RESTART.n files without
OpenCPMD.
Group |
Functions |
|---|---|
open and close |
|
inspect |
|
read coordinates |
|
edit |
|
write |
|
Coordinates are Bohr in CPMD species order; CPMDC_RESTART_ANGSTROM_PER_BOHR
is 0.529177210859.
Editing coordinates rewrites only those records and copies the wavefunction
records unchanged.
The cpmdc-restart command exposes info, positions, velocities,
patch-positions, and patch-velocities, with --angstrom for Angstrom
input and output.