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 CPMDCSession CPMDCSession;
typedef enum CPMDCFeatureKind CPMDCFeatureKind;
typedef struct CPMDCFeatureEntry CPMDCFeatureEntry;
typedef struct cpmdc_restart cpmdc_restart;

// enums

enum CPMDCFeatureKind;

// structs

struct CPMDCChargeIntegrals;
struct CPMDCEnergyComponents;
struct CPMDCFeatureEntry;
struct CPMDCMDTrajectoryRow;
struct CPMDCMultiStateEnergies;
struct CPMDCPropertySnapshot;
struct CPMDCResult;
struct CPMDCStressTensor;

// 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);
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);
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);
size_t cpmdc_feature_count(void);
const CPMDCFeatureEntry* cpmdc_feature_table(void);
const CPMDCFeatureEntry* cpmdc_feature_find(const char* feature_id);
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_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_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 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_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.

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.

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_session_create(), cpmdc_session_set_params(), 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_capabilities_result() does not write it either; its -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 the embedded OpenCPMD runtime is available.

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.

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.

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_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_RESTART_ANGSTROM_PER_BOHR

Angstroms per Bohr, matching OpenCPMD cnstfbohr.