Overview

cpmdc is the C ABI layer for embedding OpenCPMD in OmniPotentRPC tools. It keeps the public boundary small and language-neutral. Hosts pass method setup once, pass geometry for each calculation step, and get native C results or a serialized result message back.

Message	Owns	Typical lifetime
CPMDParams	method setup, CPMD sections, pseudopotentials, backend hints	one session
ForceInput	positions, atomic numbers, optional cell, requested units	one calculation step
PotentialResult	energy, forces, status, message	one calculation result

The ABI does not expose C++ types, Rust types, or a second JSON/TOML options language. All portable configuration lives in schema/Potentials.capnp; the C library decodes those bytes with generated capnp-c readers and renders the CPMD INPUT deck internally.

Long-running drivers create one CPMDCSession from CPMDParams, then pass ForceInput per step. The result-carrier call, cpmdc_session_calculate_result(), writes the same PotentialResult message used by rgpot RPC clients.

The first accepted session evaluation fixes atom count and ordered atomic numbers. Later steps may change coordinates, units, and the 3 by 3 cell; topology changes require a new session.

Start Here

You want to	Start with	Page
See an energy and forces come out of the C API	Build the default library, then link OpenCPMD	First energy and forces
Relax a structure from eOn	Pass a CPMDParams file through [RgpotPot] params_path	eOn through rgpot
Build and test the project	Run the default Meson suite and learn what it covers	Quickstart and Install and build
Link a real OpenCPMD archive	Apply the patches in tools/ and build with -fPIC	OpenCPMD archive
Turn a CPMD deck into a message	Pick typed section fields before raw deck text	Write a CPMDParams message
Call cpmdc from a host process	Choose the API path first; new hosts usually want cpmdc_session_calculate_result	Embedding cpmdc and C ABI reference
Run on many ranks	Bind calculator groups and share the parent rank’s result	Run under mpirun
Find out why a call failed or an energy is off	Write the deck with CPMDC_DECK_OUT	Troubleshooting
Understand what happens inside a call	Layers, the in-process route, orbitals between calls	Architecture
Edit these docs	Regenerate generated docs from docs/orgmode before building Sphinx	Contributing

Build and Test

meson setup build -Dwith_tests=true
meson compile -C build
meson test -C build --print-errorlogs

The default build does not need an OpenCPMD checkout. It uses a deterministic reference evaluator to test the public ABI, parser, feature table, sessions, result sizing, and unit conversion.

Map A CPMD Input Line

The main rule is to separate writable schema fields from capability/discovery rows.

Manual line	Writable carrier	Discovery row
OPTIMIZE GEOMETRY CLASSICAL XYZ SAMPLE	params.inputSections.cpmd.optimizeGeometryOptions plus optimizeGeometrySample	catalog.cpmd.OPTIMIZE_GEOMETRY_CLASSICAL, catalog.cpmd.OPTIMIZE_GEOMETRY_XYZ, catalog.cpmd.OPTIMIZE_GEOMETRY_SAMPLE_OPTION
NOSE IONS ULTRA MASSIVE T0	params.inputSections.cpmd.noseIonsOptions	catalog.cpmd.NOSE_IONS_ULTRA, catalog.cpmd.NOSE_IONS_MASSIVE, catalog.cpmd.NOSE_IONS_T0
BOX WALLS in &SYSTEM	params.inputSections.system.boxWalls	params.inputSections.system.boxWalls
&VDW with nested EMPIRICAL CORRECTION	inputSections.vdw.directives and subsections	catalog.section.VDW

Use params.* IDs when a typed schema field owns the value. Use catalog.cpmd.* rows for recognized &CPMD keywords and inline option spellings that render through an existing text field. Use catalog.section.* rows to check whole-section support. The complete table lives in CPMD option mapping.

Runtime Contracts

Concern	Carrier	Public entry points
Method setup	serialized CPMDParams	cpmdc_session_create, cpmdc_session_set_params, cpmdc_set_params
Geometry step	serialized ForceInput or C arrays	cpmdc_session_calculate_result, cpmdc_session_calculate_forces, cpmdc_session_energy_forces
Result carrier	serialized PotentialResult or native C values	cpmdc_session_calculate_result, cpmdc_calculate_result, CPMDCResult
Runtime discovery	stable feature IDs	cpmdc_feature_count, cpmdc_feature_table, cpmdc_feature_find

An OpenCPMD archive build links the same C ABI surface against libcpmd.a.

Tutorials

• Build the default library
• Describe the method and the geometry
• Run the example host
• Write your own host
• Switch to OpenCPMD
• What you built
• What connects to what
• Prepare the run directory
• Run the minimisation
• Change the method
• Run on several ranks
• Default Build
• Common Paths
• Work Loop
• What To Read After The First Run
• Run The Host Example
• Test Selection
• Session Suites
• OpenCPMD Archive Build
• Common Failures
• Cap’n Proto Fixtures

How-To Guides

• What gets built
• Requirements
• Build the default library
• Meson options
• Build against OpenCPMD
• Install
• Pixi tasks
• Goal
• Patches and what each one is for
• Build a patched tree
• Patch a tree that is already built
• Link and check
• Goal
• Write the message as Cap’n Proto text
• Map deck lines to fields
• Defaults that change the physics
• Check the rendered deck
• Where the geometry-dependent lines go
• Pick The Entry Point
• C ABI
• Message Flow
• Feature Discovery
• Session Step Calls (direct-call socket)
• Result Buffer Contract
• Session Lifetime
• CPMD Input Ownership
• RESTART files
• Units
• OpenCPMD Runtime Inputs
• Nuclear forces from repeated SCF calls
• Goal
• The rules
• One calculator over all ranks
• Several calculators in one job
• Share the parent’s result
• One session per calculator
• Finalize MPI
• Threads
• Goal
• Measured on the Si3N4 cluster
• Set ODIIS in the message
• When to keep PCG
• Always set MAXITER
• Goal
• Write the deck to a file
• What the OpenCPMD path changes
• Checks worth making on the file
• Compare with a deck that works
• Energies
• Failed calls
• Forces
• Build and link

Reference

• Conventions
• Types
• Library status
• MPI
• Configuration without a session
• Global array calls
• Sessions
• One-shot message calls
• Results of the last evaluation
• Discovery
• RESTART file library
• Read by libcpmdc at run time
• Read by the tests and tools
• Read by hosts that load libcpmdc
• CPMDParams
• CPMDInputSection
• CPMDDirective
• CPMDCpmdSection, the fields a force call uses
• CPMDSystemSection, the fields that set the cell
• CPMDDftSection
• CPMDAtomsSection and CPMDAtomsPseudopotential
• ForceInput
• PotentialConfig
• Contract
• Top-level CPMDParams fields
• Feature ID namespaces
• Mapping a CPMD manual line
• Inventory guardrails
• CPMDInputSection kinds
• Escape hatches
• Choosing an input carrier
• Catalog section exposure
• Other structured parameter features
• Typed &CPMD controls
• Typed &DFT controls
• PotentialConfig
• Two copies of one list
• Feature IDs
• Query it from C
• The inventory file
• The checks
• Add a row
• Sources checked
• Symbols
• Parser sections
• A
• C
• D
• E
• F
• G
• H
• K
• M
• N
• O
• P
• R
• S
• T
• W
• API Reference

Explanation

• Why a C ABI around CPMD
• Layers
• Two messages, two lifetimes
• What one evaluation does
• Where the deck comes from
• Sessions, topology, and state
• Three builds, one ABI
• The file route it replaces
• What one call costs
• How the wavefunction travels
• What each route has to guard against
• Both routes give the same answers
• Cold and warm calls
• Where the orbitals are kept
• What clears the orbitals
• The RESTART file
• The optimiser on a warm start
• Every rank is a copy of the host
• The communicator CPMD uses
• Why the parent rank’s result counts
• One session per calculator
• Who ends MPI
• Threads inside ranks

Contributing

• Development Checks
• Add a typed CPMD keyword
• Source Layout
• Documentation
• Release Process
  • Versioning
  • Checklist

Project

• Changelog