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: CPMDParams, PotentialConfig, or ForceInput from schema/Potentials.capnp

Positions in array calls

Angstrom, 3 * n_atoms doubles, atom-major (x0 y0 z0 x1 ...)

Energy in CPMDCResult

Hartree

Gradient and force arrays

Hartree/Bohr; forces are the negative gradient

PotentialResult values

energy in ForceInput.energyUnit, forces in energyUnit per lengthUnit, stress in energyUnit per lengthUnit cubed

int setup calls

0 on success, -1 on failure

CPMDCResult calls

ok non-zero on success; message holds "ok" or the reason

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

ok

int

non-zero when the calculation succeeded

energy_h

double

total energy in Hartree, 0 on failure

message

char[512]

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

CPMDCEnergyComponents

the 24 scalars of OpenCPMD’s ener_com, etot to eefield

Hartree

CPMDCChargeIntegrals

csumg, csumr, csums, csumsabs from chrg

electrons

CPMDCMultiStateEnergies

count doubles in values[64] from ener_c and ener_d

Hartree

CPMDCMDTrajectoryRow

count doubles in values[32]: etot ekin epseu enl eht exc ehep ehee ehii esr eself EKINC

Hartree

CPMDCPropertySnapshot

nuclear gradient in hessian[4096], dipole in dipole[3], polarizability in polarizability[9], each with a count

atomic units

CPMDCStressTensor

row-major values[9], paiu/omega

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

feature_id

stable ID such as abi.cpmdc_session_calculate_result

kind

CPMDC_FEATURE_SECTION (1), CPMDC_FEATURE_PARAMS (2), CPMDC_FEATURE_ABI (3), CPMDC_FEATURE_KEYWORD (4)

stub_applicable

non-zero when the stub build exposes the feature

embed_applicable

non-zero when an OpenCPMD build exposes the feature

Library status

Function

Returns

const char *cpmdc_version(void)

"cpmdc/" followed by the project version

int cpmdc_abi_version(void)

the ABI generation, equal to CPMDC_ABI_VERSION and the shared-library soversion, which are the first field of version.txt

int cpmdc_available(void)

1 when OpenCPMD is linked, ready, and not finalized; 0 on the reference build; 0 after finalize and from the link stub

void cpmdc_finalize(void)

marks the runtime finalized; later evaluations fail with CPMD embed not available; does not call MPI_Finalize

const char *cpmdc_last_error(void)

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

int cpmdc_bind_calculator(int ranks_per_calc)

collective on MPI_COMM_WORLD; initialises MPI when needed and splits the world into calculators of ranks_per_calc consecutive ranks; ranks_per_calc <= 0 keeps one calculator; returns this rank’s calculator index, or -1 when the world size is not a multiple or the library has no CPMD backend; a second call returns the same index

int cpmdc_adopt_calculator_comm(const void *comm, size_t nbytes, int ranks_per_calc)

collective on the caller’s communicator; reads rank and size from that communicator; does not call MPI_Init or MPI_Comm_split; when ranks_per_calc > 0 the adopted size must equal it, and a mismatch returns -1 with both numbers in cpmdc_last_error(); the group must be one aligned block of world ranks, and any other layout returns -1 on every rank; the calculator index is the lowest world rank of that block divided by the adopted size; indices are unique when every group has the same size, which the same ranks_per_calc > 0 on every rank enforces; an OpenCPMD build stores the communicator as mp_comm_world; a later call replaces it when no CPMDCSession exists, and if any rank has a live session every rank returns -1; also returns -1 when the pointer is null, MPI is not initialized, or the build has no MPI

int cpmdc_adopted_comm(void *out, size_t nbytes)

copies the stored calculator communicator into out (on an OpenCPMD build, mp_comm_world); returns 0, or -1 when no communicator is stored; does not write cpmdc_last_error()

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

int cpmdc_set_params(const void *params, size_t size)

decode CPMDParams, render the deck, apply it; 0 or -1

int cpmdc_configure(const void *config, size_t size)

resolve a PotentialConfig and apply the result like cpmdc_set_params(); 0 or -1

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

CPMDCResult cpmdc_energy(int n_atoms, const double *positions_ang, const int *atomic_numbers, const void *params, size_t size)

energy

CPMDCResult cpmdc_energy_gradient(..., double *grad_h_bohr)

energy and gradient

CPMDCResult cpmdc_energy_forces(..., double *forces_h_bohr)

energy and forces

The output array holds 3 * n_atoms doubles.

Sessions

Function

Behaviour

CPMDCSession *cpmdc_session_create(const void *params, size_t size)

copy and render CPMDParams; NULL on a decode or render failure

CPMDCSession *cpmdc_session_create_from_config(const void *config, size_t size)

resolve a PotentialConfig like cpmdc_configure(), then create a session

int cpmdc_session_set_params(CPMDCSession *s, const void *params, size_t size)

replace the parameters; -1 once the session has accepted a topology

int cpmdc_session_configure(CPMDCSession *s, const void *config, size_t size)

replace the configuration from a PotentialConfig; same rule

void cpmdc_session_destroy(CPMDCSession *s)

free the session; NULL is accepted

int cpmdc_session_select_orbitals(CPMDCSession *s, long long key)

the next evaluations start from the orbitals stored under key; -1 for a NULL session

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

CPMDCResult cpmdc_session_energy(CPMDCSession *s, int n_atoms, const double *positions_ang, const int *atomic_numbers)

energy

CPMDCResult cpmdc_session_energy_gradient(..., double *grad_h_bohr)

energy and gradient

CPMDCResult cpmdc_session_energy_forces(..., double *forces_h_bohr)

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

CPMDCResult cpmdc_session_calculate_forces(CPMDCSession *s, const void *force_input, size_t size, double *forces_h_bohr, size_t forces_len)

energy in Hartree and forces in Hartree/Bohr; forces_len >= 3 * n_atoms

CPMDCResult cpmdc_session_calculate_result(CPMDCSession *s, const void *force_input, size_t size, void *out, size_t capacity, size_t *out_size)

a serialized PotentialResult in out, its byte count in \*out_size

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

CPMDCResult cpmdc_calculate_result(const void *params, size_t params_size, const void *force_input, size_t force_size, void *out, size_t capacity, size_t *out_size)

create a session, evaluate one step, destroy the session

CPMDCResult cpmdc_calculate_result_from_config(const void *config, size_t config_size, ...)

the same with a PotentialConfig

size_t cpmdc_potential_result_size_for_force_input(const void *force_input, size_t size)

bytes needed for one PotentialResult; parses geometry only; 0 when the message is invalid or too large

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

int cpmdc_last_energy_components(CPMDCEnergyComponents *out)

int cpmdc_session_last_energy_components(const CPMDCSession *s, CPMDCEnergyComponents *out)

int cpmdc_last_charge_integrals(CPMDCChargeIntegrals *out)

cpmdc_session_last_charge_integrals

int cpmdc_last_multi_state_energies(CPMDCMultiStateEnergies *out)

cpmdc_session_last_multi_state_energies

int cpmdc_last_md_trajectory_row(CPMDCMDTrajectoryRow *out)

cpmdc_session_last_md_trajectory_row

int cpmdc_last_property_snapshot(CPMDCPropertySnapshot *out)

cpmdc_session_last_property_snapshot

int cpmdc_last_stress(CPMDCStressTensor *out)

cpmdc_session_last_stress

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

int cpmdc_last_rank_spread(CPMDCRankSpread *out)

copies the rank spread of the last evaluation in the process; 0 when it ran with CPMDC_RANK_CONSENSUS=1 under a running MPI, -1 otherwise; does not write cpmdc_last_error()

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

size_t cpmdc_feature_count(void)

number of rows in the feature table

const CPMDCFeatureEntry *cpmdc_feature_table(void)

the contiguous table, owned by the library

const CPMDCFeatureEntry *cpmdc_feature_find(const char *feature_id)

the matching row or NULL

int cpmdc_capabilities_result(void *out, size_t capacity, size_t *out_size)

a serialized Capabilities message; 0, or -1 with the required size in \*out_size

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

cpmdc_restart_read_mem, cpmdc_restart_read_path, cpmdc_restart_free

inspect

cpmdc_restart_is_stream, cpmdc_restart_header, cpmdc_restart_section, cpmdc_restart_cell, cpmdc_restart_species, cpmdc_restart_ncoords, cpmdc_restart_cutoff, cpmdc_restart_states

read coordinates

cpmdc_restart_coordinates, cpmdc_restart_velocities, cpmdc_restart_initial_coordinates

edit

cpmdc_restart_set_coordinates, cpmdc_restart_set_velocities, cpmdc_restart_set_cell

write

cpmdc_restart_write_mem, cpmdc_restart_write_path

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.