Global Namespace

Overview

// typedefs

typedef struct CPMDCResult CPMDCResult;
typedef struct CPMDCEnergyComponents CPMDCEnergyComponents;
typedef struct CPMDCChargeIntegrals CPMDCChargeIntegrals;
typedef struct CPMDCMultiStateEnergies CPMDCMultiStateEnergies;
typedef struct CPMDCMDTrajectoryRow CPMDCMDTrajectoryRow;
typedef struct CPMDCPropertySnapshot CPMDCPropertySnapshot;
typedef struct CPMDCStressTensor CPMDCStressTensor;
typedef struct CPMDCRankSpread CPMDCRankSpread;
typedef struct CPMDCSession CPMDCSession;
typedef enum CPMDCFeatureKind CPMDCFeatureKind;
typedef struct CPMDCFeatureEntry CPMDCFeatureEntry;
typedef struct cpmdc_pwscale_problem cpmdc_pwscale_problem;
typedef struct cpmdc_pwscale_stats cpmdc_pwscale_stats;
typedef struct cpmdc_pwscale_mpi_bind cpmdc_pwscale_mpi_bind;
typedef struct cpmdc_restart cpmdc_restart;

// enums

enum CPMDCFeatureKind;

// structs

struct CPMDCChargeIntegrals;
struct CPMDCEnergyComponents;
struct CPMDCFeatureEntry;
struct CPMDCMDTrajectoryRow;
struct CPMDCMultiStateEnergies;
struct CPMDCPropertySnapshot;
struct CPMDCRankSpread;
struct CPMDCResult;
struct CPMDCStressTensor;
struct cpmdc_pwscale_problem;
struct cpmdc_pwscale_stats;

// global functions

int cpmdc_set_params(const void* params_capnp, size_t params_capnp_size_bytes);
int cpmdc_configure(const void* config_capnp, size_t config_capnp_size_bytes);
CPMDCResult cpmdc_energy_gradient(int n_atoms, const double* positions_ang, const int* atomic_numbers, const void* params_capnp, size_t params_capnp_size_bytes, double* grad_h_bohr);
CPMDCResult cpmdc_energy(int n_atoms, const double* positions_ang, const int* atomic_numbers, const void* params_capnp, size_t params_capnp_size_bytes);
CPMDCResult cpmdc_energy_forces(int n_atoms, const double* positions_ang, const int* atomic_numbers, const void* params_capnp, size_t params_capnp_size_bytes, double* forces_h_bohr);
int cpmdc_bind_calculator(int ranks_per_calc);
int cpmdc_adopt_calculator_comm(const void* comm, size_t comm_bytes, int ranks_per_calc);
int cpmdc_adopted_comm(void* out, size_t nbytes);
CPMDCSession* cpmdc_session_create(const void* params_capnp, size_t params_capnp_size_bytes);
int cpmdc_session_set_params(CPMDCSession* session, const void* params_capnp, size_t params_capnp_size_bytes);
CPMDCSession* cpmdc_session_create_from_config(const void* config_capnp, size_t config_capnp_size_bytes);
int cpmdc_session_configure(CPMDCSession* session, const void* config_capnp, size_t config_capnp_size_bytes);
void cpmdc_session_destroy(CPMDCSession* session);
int cpmdc_session_select_orbitals(CPMDCSession* session, long long key);
CPMDCResult cpmdc_session_energy_gradient(CPMDCSession* session, int n_atoms, const double* positions_ang, const int* atomic_numbers, double* grad_h_bohr);
CPMDCResult cpmdc_session_energy(CPMDCSession* session, int n_atoms, const double* positions_ang, const int* atomic_numbers);
CPMDCResult cpmdc_session_energy_forces(CPMDCSession* session, int n_atoms, const double* positions_ang, const int* atomic_numbers, double* forces_h_bohr);
CPMDCResult cpmdc_session_calculate_forces(CPMDCSession* session, const void* force_input_capnp, size_t force_input_capnp_size_bytes, double* forces_h_bohr, size_t forces_len);
CPMDCResult cpmdc_session_calculate_result(CPMDCSession* session, const void* force_input_capnp, size_t force_input_capnp_size_bytes, void* potential_result_capnp, size_t potential_result_capnp_capacity_bytes, size_t* potential_result_capnp_size_bytes);
CPMDCResult cpmdc_calculate_result(const void* params_capnp, size_t params_capnp_size_bytes, const void* force_input_capnp, size_t force_input_capnp_size_bytes, void* potential_result_capnp, size_t potential_result_capnp_capacity_bytes, size_t* potential_result_capnp_size_bytes);
CPMDCResult cpmdc_calculate_result_from_config(const void* config_capnp, size_t config_capnp_size_bytes, const void* force_input_capnp, size_t force_input_capnp_size_bytes, void* potential_result_capnp, size_t potential_result_capnp_capacity_bytes, size_t* potential_result_capnp_size_bytes);
size_t cpmdc_potential_result_size_for_force_input(const void* force_input_capnp, size_t force_input_capnp_size_bytes);
int cpmdc_capabilities_result(void* capabilities_capnp, size_t capabilities_capnp_capacity_bytes, size_t* capabilities_capnp_size_bytes);
const char* cpmdc_version(void);
const char* cpmdc_last_error(void);
int cpmdc_abi_version(void);
int cpmdc_available(void);
void cpmdc_finalize(void);
int cpmdc_last_energy_components(CPMDCEnergyComponents* out);
int cpmdc_session_last_energy_components(const CPMDCSession* session, CPMDCEnergyComponents* out);
int cpmdc_last_charge_integrals(CPMDCChargeIntegrals* out);
int cpmdc_session_last_charge_integrals(const CPMDCSession* session, CPMDCChargeIntegrals* out);
int cpmdc_last_multi_state_energies(CPMDCMultiStateEnergies* out);
int cpmdc_session_last_multi_state_energies(const CPMDCSession* session, CPMDCMultiStateEnergies* out);
int cpmdc_last_md_trajectory_row(CPMDCMDTrajectoryRow* out);
int cpmdc_session_last_md_trajectory_row(const CPMDCSession* session, CPMDCMDTrajectoryRow* out);
int cpmdc_last_property_snapshot(CPMDCPropertySnapshot* out);
int cpmdc_session_last_property_snapshot(const CPMDCSession* session, CPMDCPropertySnapshot* out);
int cpmdc_last_stress(CPMDCStressTensor* out);
int cpmdc_session_last_stress(const CPMDCSession* session, CPMDCStressTensor* out);
int cpmdc_last_rank_spread(CPMDCRankSpread* out);
size_t cpmdc_feature_count(void);
const CPMDCFeatureEntry* cpmdc_feature_table(void);
const CPMDCFeatureEntry* cpmdc_feature_find(const char* feature_id);
void cpmdc_pwscale_fill_geometry(const cpmdc_pwscale_problem* prob, double* positions_bohr, int* atomic_numbers);
int cpmdc_pwscale_within(double got, double ref);
int cpmdc_pwscale_sample_check(double got_energy, const double* got_forces, double ref_energy, const double* ref_forces, int n3, long long g_got, long long g_ref, long long a_got, long long a_ref, double* max_abs_dE, double* max_abs_dF, int* counts_match);
int cpmdc_pwscale_eval(const cpmdc_pwscale_problem* prob, const double* positions_bohr, const int* atomic_numbers, double* forces_h_bohr, int nthreads, int dist, cpmdc_pwscale_stats* stats);
int cpmdc_pwscale_eval_mpi(const cpmdc_pwscale_problem* prob, const double* positions_bohr, const int* atomic_numbers, double* forces_h_bohr, int nthreads, int dist, cpmdc_pwscale_stats* stats, const void* comm, size_t comm_bytes);
int cpmdc_pwscale_mpi_bind_create(const cpmdc_pwscale_problem* prob, int dist, const void* comm, size_t comm_bytes, cpmdc_pwscale_mpi_bind** out);
int cpmdc_pwscale_eval_mpi_bound(cpmdc_pwscale_mpi_bind* bind, const double* positions_bohr, const int* atomic_numbers, double* forces_h_bohr, int nthreads, cpmdc_pwscale_stats* stats);
void cpmdc_pwscale_mpi_bind_free(cpmdc_pwscale_mpi_bind* bind);
int cpmdc_pwscale_cuda_compiled(void);
int cpmdc_pwscale_cuda_device(char* name, int namelen);
int cpmdc_pwscale_eval_cuda(const cpmdc_pwscale_problem* prob, const double* positions_bohr, const int* atomic_numbers, double* forces_h_bohr, cpmdc_pwscale_stats* stats);
cpmdc_restart* cpmdc_restart_read_mem(const void* bytes, size_t nbytes, char* err, size_t err_cap);
cpmdc_restart* cpmdc_restart_read_path(const char* path, char* err, size_t err_cap);
void cpmdc_restart_free(cpmdc_restart* file);
int cpmdc_restart_is_stream(const cpmdc_restart* file);
const char* cpmdc_restart_header(const cpmdc_restart* file);
int cpmdc_restart_section(const cpmdc_restart* file, int section, int* count);
int cpmdc_restart_cell(const cpmdc_restart* file, int* ibrav, int* indpg, double celldm[6]);
int cpmdc_restart_species(const cpmdc_restart* file, int* nsp, const int** na_per_species);
int cpmdc_restart_expand_species_symbols(const cpmdc_restart* file, const char*const* species_symbols, int nspecies, const char** atom_symbols, int n_atoms);
int cpmdc_restart_ncoords(const cpmdc_restart* file);
int cpmdc_restart_coordinates(const cpmdc_restart* file, double* xyz, int n3);
int cpmdc_restart_velocities(const cpmdc_restart* file, double* xyz, int n3);
int cpmdc_restart_initial_coordinates(const cpmdc_restart* file, double* xyz, int n3);
int cpmdc_restart_set_coordinates(cpmdc_restart* file, const double* xyz, int n3);
int cpmdc_restart_set_velocities(cpmdc_restart* file, const double* xyz, int n3);
int cpmdc_restart_set_cell(cpmdc_restart* file, const double celldm[6]);
int cpmdc_restart_cutoff(const cpmdc_restart* file, double* ecut, double* cdual, int* dual_flag, int* nel, int* nr1s, int* nr2s, int* nr3s);
int cpmdc_restart_states(const cpmdc_restart* file, int* n, int* nkpts, int* ngw, int* ngwl, int* nhg, int* nhgl);
int cpmdc_restart_write_mem(const cpmdc_restart* file, void** bytes, size_t* nbytes, char* err, size_t err_cap);
int cpmdc_restart_write_path(const cpmdc_restart* file, const char* path, char* err, size_t err_cap);

// macros

#define CPMDC_ABI_VERSION
#define CPMDC_PWSCALE_DIST_ATOMS
#define CPMDC_PWSCALE_DIST_PW
#define CPMDC_PWSCALE_ERR_ARG
#define CPMDC_PWSCALE_ERR_CUDA
#define CPMDC_PWSCALE_ERR_NOCUDA
#define CPMDC_PWSCALE_ERR_NOFFTW
#define CPMDC_PWSCALE_ERR_NOMPI
#define CPMDC_PWSCALE_OK
#define CPMDC_PWSCALE_RTOL
#define CPMDC_RESTART_ANGSTROM_PER_BOHR

Detailed Documentation

Typedefs

typedef struct CPMDCResult CPMDCResult

Result returned by energy / gradient / forces entry points.

typedef struct CPMDCEnergyComponents CPMDCEnergyComponents

In-process snapshot of OpenCPMD ener_com scalars (Hartree a.u.).

Filled after a successful embed SCF (wfopts) or reference PEF evaluation. Hosts read this via cpmdc_last_energy_components() without parsing CLI ENERGY files or opening a network socket. Field names mirror ener_com_t in OpenCPMD ener.mod.F90. Zero fields are valid (not set for that run).

typedef struct CPMDCChargeIntegrals CPMDCChargeIntegrals

OpenCPMD chrg_t density integrals (post-SCF module state).

typedef struct CPMDCMultiStateEnergies CPMDCMultiStateEnergies

Flattened CAS22-class multi-state catalog (ener_c + ener_d).

Layout is backend-defined; count is the number of doubles copied into values (caller provides capacity). Returns -1 when no snapshot.

typedef struct CPMDCMDTrajectoryRow CPMDCMDTrajectoryRow

One ENERGY-file-equivalent trajectory row (Hartree).

Layout (count >= 12 after a successful eval): [0] etot [1] ekin [2] epseu [3] enl [4] eht [5] exc [6] ehep [7] ehee [8] ehii [9] esr [10] eself [11] EKINC (fictitious electronic KE; 0 for BO/SCF-only wfopt, filled in MD)

typedef struct CPMDCPropertySnapshot CPMDCPropertySnapshot

PROP-style property snapshot after a successful evaluation.

  • dipole[3]: OpenCPMD ddippdipole (a.u.) when linked; PEF zeros

  • polarizability[9]: filled when PROP/aoresponse available; else zeros with count 9

  • hessian[]: nuclear gradient dE/dR packed as [natoms*3] (full Hessian needs dedicated PROP/Hessian run; gradient is always available after force eval)

typedef struct CPMDCStressTensor CPMDCStressTensor

Cartesian stress tensor after a successful PEF evaluation.

Layout is row-major [xx, xy, xz, yx, yy, yz, zx, zy, zz] in Hartree/Bohr^3 (OpenCPMD paiu/omega after totstr when cntltpres). valid is set only when that tensor was computed for a periodic cell. A positive cell volume is not enough: an isolated (cluster/Hockney) box leaves valid unset. Returns 0 when out->valid is set; -1 when stress was not computed.

typedef struct CPMDCRankSpread CPMDCRankSpread

How far the ranks of one calculator were from its rank 0.

Written by an evaluation that ran with CPMDC_RANK_CONSENSUS=1 under a running MPI. The differences are taken before every rank receives rank 0’s energy and gradient. A NaN difference is reported as infinity. Both are 0 when every rank held the same values.

typedef struct CPMDCSession CPMDCSession

Opaque handle for repeated evaluations with one Cap’n Proto parameter set.

typedef enum CPMDCFeatureKind CPMDCFeatureKind

Feature namespace represented by a CPMDCFeatureEntry.

typedef struct CPMDCFeatureEntry CPMDCFeatureEntry

One discoverable ABI, parameter, section, or keyword capability.

typedef struct cpmdc_pwscale_problem cpmdc_pwscale_problem

One scaffold problem: atom count, plane waves, and the Gaussian width.

typedef struct cpmdc_pwscale_stats cpmdc_pwscale_stats

Timers and visit counts from one scaffold evaluation.

typedef struct cpmdc_pwscale_mpi_bind cpmdc_pwscale_mpi_bind

A problem bound to a communicator for repeated rank force calls.

cpmdc_pwscale_eval_mpi binds, evaluates once, and frees on every call.

typedef struct cpmdc_restart cpmdc_restart

Opaque RESTART image.

Global Functions

int cpmdc_set_params(const void* params_capnp, size_t params_capnp_size_bytes)

Apply CPMD method parameters from a Cap’n Proto message.

Callers do not need C setter functions for individual CPMD keywords. Build one CPMDParams message with top-level fields, structured inputSections, and literal inputBlocks, then pass its bytes to this function or to cpmdc_session_create().

Feature discovery mirrors the schema carriers: typed fields such as params.inputSections.cpmd.maxIter, params.inputSections.system.cell, params.inputSections.dft.hfxScreening, and params.inputSections.atoms.pseudopotentials; catalog sections such as catalog.section.VDW; and escape hatches such as params.inputSections.raw. The same serialized params buffer is accepted by cpmdc_calculate_result() for one-shot calls.

Parameters:

params_capnp

Pointer to an unpacked flat CPMDParams message.

params_capnp_size_bytes

Size of params_capnp in bytes.

Returns:

0 on success, -1 on parse or configuration failure. Failure text is cpmdc_last_error().

int cpmdc_configure(const void* config_capnp, size_t config_capnp_size_bytes)

Apply configuration from a PotentialConfig message.

The cpmd union arm carries CPMDParams and wins wholesale when present. With the arm unset, a set common overlay (CommonMethodSpec) lowers to synthesized CPMDParams : functional, plane-wave cutoff, charge, multiplicity, MAXITER, and the Monkhorst-Pack kMesh. Setting both the cpmd arm and the overlay is rejected (capnp cannot distinguish unset arm fields from defaults). Overlay fields without a CPMD lowering are rejected and reported through cpmdc_last_error().

Returns:

0 on success, -1 on parse, lowering, or apply failure.

CPMDCResult cpmdc_energy_gradient(int n_atoms, const double* positions_ang, const int* atomic_numbers, const void* params_capnp, size_t params_capnp_size_bytes, double* grad_h_bohr)

Compute energy and nuclear gradient for an atomic configuration.

Positions are Angstrom; gradient is Hartree/Bohr (CPMD ionic forces are negated into a nuclear gradient for API symmetry with nwchemc).

CPMDCResult cpmdc_energy(int n_atoms, const double* positions_ang, const int* atomic_numbers, const void* params_capnp, size_t params_capnp_size_bytes)

Compute total energy only (no gradient allocation).

CPMDCResult cpmdc_energy_forces(int n_atoms, const double* positions_ang, const int* atomic_numbers, const void* params_capnp, size_t params_capnp_size_bytes, double* forces_h_bohr)

Compute energy and nuclear forces (negative gradient, Hartree/Bohr).

int cpmdc_bind_calculator(int ranks_per_calc)

Bind this rank to one CPMD calculator of ranks_per_calc ranks.

Collective on MPI_COMM_WORLD, once, before the first energy call. World size must divide into groups of ranks_per_calc. Each group is one CPMD calculator: its own communicator, its own wavefunction, the same deck. A value of zero or less takes the whole world as one group. Returns the group index, or -1 when the split is refused or the library carries no CPMD backend. Failure text is cpmdc_last_error(). A second call returns the same index and does not split again.

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

Install a communicator the caller already split.

comm points at an MPI_Comm of comm_bytes bytes. Collective on that communicator. Does not call MPI_Init or MPI_Comm_split. Rank and size come from comm. When ranks_per_calc is greater than zero, that size must equal it. A mismatch returns -1 and cpmdc_last_error() names both numbers. Zero or less skips the size check. The group must be one aligned block of world ranks, starting at a multiple of the adopted size. Any other layout returns -1 on every rank of the group. The calculator index is the lowest world rank in that block divided by the size. Indices are unique when every group has the same size, which the same ranks_per_calc > 0 on every rank enforces. The handle is borrowed: the call does not use MPI_Comm_dup. It stores the caller’s communicator, and an OpenCPMD build also stores it as mp_comm_world. The caller keeps ownership and must not free the communicator until the last session is destroyed or a later adopt replaces it. An adopt after cpmdc_bind_calculator replaces the communicator that call split, and the caller of bind cannot free that one. A later call replaces the communicator when no CPMDCSession exists. If any rank of the group has a live session, every rank returns -1 and the stored communicator stays as it was. Returns -1 when comm is null, comm_bytes is not the size of an MPI_Comm, MPI is not initialized, or this build has no MPI. Failure text is cpmdc_last_error(). Call adopt, cpmdc_session_create, and cpmdc_session_destroy from one thread: g_live_sessions and g_active_session are process globals, and OpenCPMD state is process-global too.

int cpmdc_adopted_comm(void* out, size_t nbytes)

Copy the stored calculator communicator into out.

out receives an MPI_Comm of nbytes bytes. On an OpenCPMD build that handle is mp_comm_world. Returns 0 when a calculator communicator is stored, and -1 when out is null, nbytes is not that size, or no communicator has been adopted. Does not write cpmdc_last_error().

CPMDCSession* cpmdc_session_create(const void* params_capnp, size_t params_capnp_size_bytes)

Create a persistent evaluation session from a Cap’n Proto message.

The session owns a copy of the serialized message so callers may release the input buffer after this call returns. Returns NULL on failure; the reason is cpmdc_last_error().

int cpmdc_session_set_params(CPMDCSession* session, const void* params_capnp, size_t params_capnp_size_bytes)

Replace Cap’n Proto parameters before the session accepts topology.

CPMDCSession* cpmdc_session_create_from_config(const void* config_capnp, size_t config_capnp_size_bytes)

Create a persistent session from a PotentialConfig message.

Resolves the config exactly like cpmdc_configure() and installs the effective CPMDParams on a new session.

int cpmdc_session_configure(CPMDCSession* session, const void* config_capnp, size_t config_capnp_size_bytes)

Configure an existing session from a PotentialConfig message.

Accepted only before the session evaluates; resolution matches cpmdc_configure().

void cpmdc_session_destroy(CPMDCSession* session)

Release a persistent evaluation session.

int cpmdc_session_select_orbitals(CPMDCSession* session, long long key)

Name the calculation the next evaluations of this session belong to.

The process stores the converged orbitals of one SCF. With a key named, those orbitals are kept per key: an evaluation under a key starts from the orbitals the last converged evaluation under the same key left, and a key that has none yet starts from the orbitals already stored. Of the stored orbitals of every key, the ones that converged nearest to the new geometry start the SCF, and only within CPMDC_WARM_RMSD (root-mean- square distance per atom, default 0.15 Angstrom); farther, the deck’s guess starts it. A host that runs several calculations on one calculator, the images of a band or the beads of a ring polymer, names each by a stable key, so each starts from its own previous geometry instead of from its neighbour’s. Every rank of a calculator names the same key before the same evaluation. A basis change clears every key’s orbitals. A session that never names a key keeps one stored copy.

Returns:

0, or -1 when session is NULL.

CPMDCResult cpmdc_session_energy_gradient(CPMDCSession* session, int n_atoms, const double* positions_ang, const int* atomic_numbers, double* grad_h_bohr)

Compute energy and nuclear gradient with session-owned parameters.

Positions are Angstrom. The gradient buffer must have n_atoms * 3 doubles and is filled in Hartree/Bohr.

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

Compute total energy with session-owned parameters.

Positions are Angstrom and the returned energy is Hartree.

CPMDCResult cpmdc_session_energy_forces(CPMDCSession* session, int n_atoms, const double* positions_ang, const int* atomic_numbers, double* forces_h_bohr)

Compute energy and nuclear forces with session-owned parameters.

Positions are Angstrom. The forces buffer must have n_atoms * 3 doubles and is filled in Hartree/Bohr.

CPMDCResult cpmdc_session_calculate_forces(CPMDCSession* session, const void* force_input_capnp, size_t force_input_capnp_size_bytes, double* forces_h_bohr, size_t forces_len)

Compute energy and forces for one Cap’n Proto ForceInput step.

Session keeps persistent CPMDParams; each call supplies geometry. Returned energy/forces use CPMD native units: Hartree and Hartree/Bohr.

CPMDCResult cpmdc_session_calculate_result(CPMDCSession* session, const void* force_input_capnp, size_t force_input_capnp_size_bytes, void* potential_result_capnp, size_t potential_result_capnp_capacity_bytes, size_t* potential_result_capnp_size_bytes)

Compute forces for one ForceInput step and write PotentialResult.

Direct-call socket entry point: method state in the session, geometry in ForceInput, output energy/forces converted to ForceInput.energyUnit and energyUnit / lengthUnit.

When potential_result_capnp_capacity_bytes is too small, returns ok == 0, writes the required byte count to potential_result_capnp_size_bytes, and does not evaluate CPMD.

CPMDCResult cpmdc_calculate_result(const void* params_capnp, size_t params_capnp_size_bytes, const void* force_input_capnp, size_t force_input_capnp_size_bytes, void* potential_result_capnp, size_t potential_result_capnp_capacity_bytes, size_t* potential_result_capnp_size_bytes)

One-shot Cap’n Proto entry point (params + ForceInput -> PotentialResult).

Multi-step callers should create one session and call cpmdc_session_calculate_result() per step.

CPMDCResult cpmdc_calculate_result_from_config(const void* config_capnp, size_t config_capnp_size_bytes, const void* force_input_capnp, size_t force_input_capnp_size_bytes, void* potential_result_capnp, size_t potential_result_capnp_capacity_bytes, size_t* potential_result_capnp_size_bytes)

One-shot Cap’n Proto entry point resolving a full PotentialConfig (native arm plus common overlay, exactly like cpmdc_configure()).

Multi-step callers should create one session via cpmdc_session_create_from_config() and call cpmdc_session_calculate_result() per step.

size_t cpmdc_potential_result_size_for_force_input(const void* force_input_capnp, size_t force_input_capnp_size_bytes)

Byte count needed for a PotentialResult for the given ForceInput.

Parses geometry only; does not initialize or evaluate CPMD. Returns 0 when the message is invalid or too large for the C ABI. That failure is reported through cpmdc_last_error().

int cpmdc_capabilities_result(void* capabilities_capnp, size_t capabilities_capnp_capacity_bytes, size_t* capabilities_capnp_size_bytes)

Write a Cap’n Proto Capabilities message describing this backend.

Loaders negotiate against the message before dispatch: backend name and version, ABI generation, availability, the calculate operations the ABI serves, the CommonMethodSpec fields the overlay lowers, and the PotentialConfig arms accepted. A stub build reports the same operation surface with available = false.

Returns 0 on success. On a too-small buffer (including the pure size query capabilities_capnp == NULL, capabilities_capnp_capacity_bytes == 0) returns -1 with *capabilities_capnp_size_bytes set to the required size. That -1 does not write cpmdc_last_error().

const char* cpmdc_version(void)

Compiled library version string.

const char* cpmdc_last_error(void)

Diagnostic for the most recent public call on this thread that reports failure through this string.

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 (cpmdc_energy(), cpmdc_energy_gradient(), cpmdc_energy_forces(), the session variants, and the calculate-result calls). When the call returns CPMDCResult, the text matches message, including a missing pseudopotential directory. Empty after a successful call.

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.

int cpmdc_abi_version(void)

Numeric ABI generation of the compiled library.

Compare against the CPMDC_ABI_VERSION the consumer compiled with.

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)

Finalize an owned embedded CPMD runtime.

int cpmdc_last_energy_components(CPMDCEnergyComponents* out)

Copy the last in-process ener_com energy decomposition.

The no-session entry points read the active calculator. A session entry point reads that session, including after another session has run. Returns 0 when out->valid is set. Values are Hartree.

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

Copy the last energy decomposition stored on session.

int cpmdc_last_charge_integrals(CPMDCChargeIntegrals* out)

Copy the last in-process density integrals.

Returns 0 when out->valid is set. Does not write cpmdc_last_error().

int cpmdc_session_last_charge_integrals(const CPMDCSession* session, CPMDCChargeIntegrals* out)

Copy the last density integrals stored on session.

int cpmdc_last_multi_state_energies(CPMDCMultiStateEnergies* out)

Copy the last multi-state energy catalog.

Returns 0 when out->valid is set. Does not write cpmdc_last_error().

int cpmdc_session_last_multi_state_energies(const CPMDCSession* session, CPMDCMultiStateEnergies* out)

Copy the last multi-state energy catalog stored on session.

int cpmdc_last_md_trajectory_row(CPMDCMDTrajectoryRow* out)

Copy the last trajectory row.

Values are Hartree. Returns 0 when out->valid is set. Does not write cpmdc_last_error().

int cpmdc_session_last_md_trajectory_row(const CPMDCSession* session, CPMDCMDTrajectoryRow* out)

Copy the last trajectory row stored on session.

int cpmdc_last_property_snapshot(CPMDCPropertySnapshot* out)

Copy the last property snapshot.

Returns 0 when out->valid is set. Does not write cpmdc_last_error().

int cpmdc_session_last_property_snapshot(const CPMDCSession* session, CPMDCPropertySnapshot* out)

Copy the last property snapshot stored on session.

int cpmdc_last_stress(CPMDCStressTensor* out)

Copy the last stress tensor.

Returns 0 when out->valid is set, which is only after stress was computed for a periodic cell. Does not write cpmdc_last_error().

int cpmdc_session_last_stress(const CPMDCSession* session, CPMDCStressTensor* out)

Copy the last stress tensor stored on session.

int cpmdc_last_rank_spread(CPMDCRankSpread* out)

Copy the rank spread of the last evaluation in this process.

Returns 0 when out->valid is set: the last evaluation ran with CPMDC_RANK_CONSENSUS=1 under a running MPI. A repeat of the stored positions keeps the spread of the evaluation that stored them. Does not write cpmdc_last_error().

size_t cpmdc_feature_count(void)

Number of entries returned by cpmdc_feature_table().

const CPMDCFeatureEntry* cpmdc_feature_table(void)

Return the contiguous feature table.

The returned pointer has cpmdc_feature_count() entries and remains owned by the library.

const CPMDCFeatureEntry* cpmdc_feature_find(const char* feature_id)

Find one feature by stable ID.

Returns:

Pointer to the matching table entry, or NULL when the feature ID is not present.

void cpmdc_pwscale_fill_geometry(const cpmdc_pwscale_problem* prob, double* positions_bohr, int* atomic_numbers)

Fill a deterministic geometry for prob.

A null pointer returns without writing. Positions are Bohr.

int cpmdc_pwscale_within(double got, double ref)

Return 1 when got agrees with ref under CPMDC_PWSCALE_RTOL.

int cpmdc_pwscale_sample_check(double got_energy, const double* got_forces, double ref_energy, const double* ref_forces, int n3, long long g_got, long long g_ref, long long a_got, long long a_ref, double* max_abs_dE, double* max_abs_dF, int* counts_match)

Compare one finished sample with the serial reference.

Writes this sample’s gaps and whether the visit counts match. Returns 1 only when the energy, every force, and both counts agree. A null buffer or a non-positive n3 returns 0 and writes nothing.

int cpmdc_pwscale_eval(const cpmdc_pwscale_problem* prob, const double* positions_bohr, const int* atomic_numbers, double* forces_h_bohr, int nthreads, int dist, cpmdc_pwscale_stats* stats)

Evaluate the scaffold on one rank.

dist selects the split: plane waves, or atoms. nthreads is the OpenMP team size. One thread is the serial loop. Wall time covers scratch allocation, the arithmetic, and the ordered sum. A null buffer or an unknown dist returns CPMDC_PWSCALE_ERR_ARG.

int cpmdc_pwscale_eval_mpi(const cpmdc_pwscale_problem* prob, const double* positions_bohr, const int* atomic_numbers, double* forces_h_bohr, int nthreads, int dist, cpmdc_pwscale_stats* stats, const void* comm, size_t comm_bytes)

Evaluate the scaffold on every rank of one communicator.

Every rank passes the same problem. Every rank receives every rank’s partial and sums them in rank order. nthreads is the team inside a rank. comm NULL selects MPI_COMM_WORLD. A build without MPI returns CPMDC_PWSCALE_ERR_NOMPI. seconds runs from this rank’s entry to the arrival of every partial. Each rank holds (ranks + 1) * (3 * natoms + 4) doubles for the sum.

int cpmdc_pwscale_mpi_bind_create(const cpmdc_pwscale_problem* prob, int dist, const void* comm, size_t comm_bytes, cpmdc_pwscale_mpi_bind** out)

Bind a problem to a communicator.

Collective over comm. Every rank passes the same problem and dist. One collective checks that agreement and every rank’s buffers, so the bound calls repeat neither check. comm NULL selects MPI_COMM_WORLD, and the communicator must outlive the binding. On failure every rank returns the same code and out is NULL. A build without MPI returns CPMDC_PWSCALE_ERR_NOMPI.

int cpmdc_pwscale_eval_mpi_bound(cpmdc_pwscale_mpi_bind* bind, const double* positions_bohr, const int* atomic_numbers, double* forces_h_bohr, int nthreads, cpmdc_pwscale_stats* stats)

One bound force call.

Collective over the bound communicator, with the result of cpmdc_pwscale_eval_mpi for the same arguments. The call runs one collective, an Allgather of each rank’s energy, forces, visit counts, and return code. A failure on one rank, including a missing array, returns an error on every rank.

void cpmdc_pwscale_mpi_bind_free(cpmdc_pwscale_mpi_bind* bind)

Release a binding.

Local. Leaves the communicator alone.

int cpmdc_pwscale_cuda_compiled(void)

Return 1 when this build compiled the CUDA scaffold.

int cpmdc_pwscale_cuda_device(char* name, int namelen)

Write a device name when one is present.

Returns 1 when a device exists.

int cpmdc_pwscale_eval_cuda(const cpmdc_pwscale_problem* prob, const double* positions_bohr, const int* atomic_numbers, double* forces_h_bohr, cpmdc_pwscale_stats* stats)

Evaluate the scaffold on the CUDA device.

Total seconds include host-to-device, device-to-host, and synchronization. A missing build or a missing device is an error and writes no timing.

cpmdc_restart* cpmdc_restart_read_mem(const void* bytes, size_t nbytes, char* err, size_t err_cap)

Read a RESTART image from a memory buffer.

Parameters:

bytes

RESTART image bytes.

nbytes

Number of bytes in bytes.

err

Diagnostic buffer. May be NULL.

err_cap

Capacity of err, including the terminating NUL.

Returns:

The image, or NULL on failure.

cpmdc_restart* cpmdc_restart_read_path(const char* path, char* err, size_t err_cap)

Read a RESTART image from a filesystem path.

Parameters:

path

Filesystem path of the RESTART file.

err

Diagnostic buffer. May be NULL.

err_cap

Capacity of err, including the terminating NUL.

Returns:

The image, or NULL on failure.

void cpmdc_restart_free(cpmdc_restart* file)

Release an image returned by the readers.

Parameters:

file

Image to free. May be NULL.

int cpmdc_restart_is_stream(const cpmdc_restart* file)

Report whether the image uses the continuing-record stream layout.

Parameters:

file

Image to query.

Returns:

1 when file uses that layout, 0 otherwise.

const char* cpmdc_restart_header(const cpmdc_restart* file)

Section 1 header text.

Parameters:

file

Image to query.

Returns:

The header, or NULL when the image has none.

int cpmdc_restart_section(const cpmdc_restart* file, int section, int* count)

Report one section’s record count.

Parameters:

file

Image to query.

section

1-based section index.

count

Receives the integer in the section header, or 0 when the section is empty.

Returns:

0 when the section is present.

int cpmdc_restart_cell(const cpmdc_restart* file, int* ibrav, int* indpg, double celldm[6])

Read the cell description.

Parameters:

file

Image to query.

ibrav

Receives the stored ibrav. May be NULL.

indpg

Receives the stored indpg. May be NULL.

celldm

Receives the six lattice parameters. Required.

Returns:

0 when the cell section is present.

int cpmdc_restart_species(const cpmdc_restart* file, int* nsp, const int** na_per_species)

Read the species counts.

Parameters:

file

Image to query.

nsp

Receives the stored species count. May be NULL.

na_per_species

Points at the image’s own array. May be NULL. Valid until the image is freed or rewritten.

Returns:

0 when the species section is present.

int cpmdc_restart_expand_species_symbols(const cpmdc_restart* file, const char*const* species_symbols, int nspecies, const char** atom_symbols, int n_atoms)

Expand one symbol per species into CPMD coordinate order.

atom_symbols[i] aliases species_symbols[s] for the species that owns coordinate i. The caller keeps species_symbols alive.

Parameters:

file

Image whose species counts select the expansion.

species_symbols

One symbol per species, length nspecies.

nspecies

Must equal the stored species count.

atom_symbols

Receives n_atoms pointers. Required.

n_atoms

Must equal the coordinate count.

Returns:

0 on success.

int cpmdc_restart_ncoords(const cpmdc_restart* file)

Number of coordinate triples in section 4.

Parameters:

file

Image to query.

Returns:

The triple count, or 0 when that section is empty.

int cpmdc_restart_coordinates(const cpmdc_restart* file, double* xyz, int n3)

Copy coordinates in Bohr.

Parameters:

file

Image to query.

xyz

Receives ncoords * 3 doubles.

n3

Capacity of xyz in doubles.

Returns:

0 on success.

int cpmdc_restart_velocities(const cpmdc_restart* file, double* xyz, int n3)

Copy velocities in Bohr.

Parameters:

file

Image to query.

xyz

Receives ncoords * 3 doubles.

n3

Capacity of xyz in doubles.

Returns:

0 on success.

int cpmdc_restart_initial_coordinates(const cpmdc_restart* file, double* xyz, int n3)

Copy the initial geometry in Bohr.

Parameters:

file

Image to query.

xyz

Receives ncoords * 3 doubles.

n3

Capacity of xyz in doubles.

Returns:

0 on success.

int cpmdc_restart_set_coordinates(cpmdc_restart* file, const double* xyz, int n3)

Replace coordinates, leaving every other record unchanged.

Parameters:

file

Image to modify.

xyz

n3 doubles, ncoords * 3, in Bohr.

n3

Number of doubles in xyz.

Returns:

0 on success.

int cpmdc_restart_set_velocities(cpmdc_restart* file, const double* xyz, int n3)

Replace velocities, leaving every other record unchanged.

Parameters:

file

Image to modify.

xyz

n3 doubles, in Bohr.

n3

Number of doubles in xyz.

Returns:

0 on success.

int cpmdc_restart_set_cell(cpmdc_restart* file, const double celldm[6])

Replace the cell lattice parameters.

Parameters:

file

Image to modify.

celldm

Six lattice parameters.

Returns:

0 on success.

int cpmdc_restart_cutoff(const cpmdc_restart* file, double* ecut, double* cdual, int* dual_flag, int* nel, int* nr1s, int* nr2s, int* nr3s)

Read the cutoff section.

dual_flag is the logical dual stored in section 7 (0 or 1), not the real dual factor. That factor is cdual.

Parameters:

file

Image to query.

ecut

Receives the stored cutoff. May be NULL.

cdual

Receives the stored real dual factor. May be NULL.

dual_flag

Receives the stored logical dual, 0 or 1. May be NULL.

nel

Receives the stored nel. May be NULL.

nr1s

Receives the stored nr1s. May be NULL.

nr2s

Receives the stored nr2s. May be NULL.

nr3s

Receives the stored nr3s. May be NULL.

Returns:

0 when the section is present.

int cpmdc_restart_states(const cpmdc_restart* file, int* n, int* nkpts, int* ngw, int* ngwl, int* nhg, int* nhgl)

Read the electronic-state counts.

Parameters:

file

Image to query.

n

Receives the stored state count. May be NULL.

nkpts

Receives the stored k-point count. May be NULL.

ngw

Receives the stored ngw. May be NULL.

ngwl

Receives the stored ngwl. May be NULL.

nhg

Receives the stored nhg. May be NULL.

nhgl

Receives the stored nhgl. May be NULL.

Returns:

0 when the section is present.

int cpmdc_restart_write_mem(const cpmdc_restart* file, void** bytes, size_t* nbytes, char* err, size_t err_cap)

Write the image to a newly allocated buffer.

Parameters:

file

Image to write.

bytes

Receives a buffer the caller frees.

nbytes

Receives the number of bytes written.

err

Diagnostic buffer. May be NULL.

err_cap

Capacity of err, including the terminating NUL.

Returns:

0 on success.

int cpmdc_restart_write_path(const cpmdc_restart* file, const char* path, char* err, size_t err_cap)

Write the image to a filesystem path.

Parameters:

file

Image to write.

path

Destination path.

err

Diagnostic buffer. May be NULL.

err_cap

Capacity of err, including the terminating NUL.

Returns:

0 on success.

Macros

#define CPMDC_ABI_VERSION

Numeric ABI generation of this header.

Matches the shared-library soversion and cpmdc_abi_version(); bumps only on an incompatible ABI change.

#define CPMDC_PWSCALE_DIST_ATOMS

Split the atom loop across workers.

#define CPMDC_PWSCALE_DIST_PW

Split the plane-wave loop across workers.

#define CPMDC_PWSCALE_ERR_ARG

Argument or collective failure.

#define CPMDC_PWSCALE_ERR_CUDA

A CUDA call failed.

#define CPMDC_PWSCALE_ERR_NOCUDA

This build has no CUDA.

#define CPMDC_PWSCALE_ERR_NOFFTW

This build has no FFTW.

#define CPMDC_PWSCALE_ERR_NOMPI

This build has no MPI.

#define CPMDC_PWSCALE_OK

Status and distribution codes for the scaffold.

#define CPMDC_PWSCALE_RTOL

Relative tolerance for energy and force agreement.

A gap is accepted when it is at most this times max(1, |got|, |reference|).

#define CPMDC_RESTART_ANGSTROM_PER_BOHR

Angstroms per Bohr.

Multiply a Bohr coordinate by this macro.