cpmdc¶
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 |
|---|---|---|
|
method setup, CPMD sections, pseudopotentials, backend hints |
one session |
|
positions, atomic numbers, optional cell, requested units |
one calculation step |
|
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 the atom count and the elemental composition. A reordering of those elements stays on the session. Later steps may change coordinates, units, and the 3 by 3 cell; a different composition requires 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 |
|
Drive the same step from ASE |
Point |
|
Relax a structure from eOn |
Pass a |
|
Build and test the project |
Run the default Meson suite and learn what it covers |
|
Link a real OpenCPMD archive |
Apply the patches in |
|
Turn a CPMD deck into a message |
Pick typed section fields before raw deck text |
|
Call cpmdc from a host process |
Choose the API path first; new hosts usually want |
|
Run on many ranks |
Bind calculator groups and share the parent rank’s result |
|
Find out why a call failed or an energy is off |
Write the deck with |
|
Understand what happens inside a call |
Layers, the in-process route, orbitals between calls |
|
Build OpenCPMD for more than one CPU |
Use the PIC configure file, which passes |
|
See which instruction sets cpmdc compiles for |
This library has no hot kernel and does not read |
|
Edit these docs |
Regenerate generated docs from |
|
Ask a question or report a bug |
Open an issue with the version, the build options, and the failing deck |
|
Cite cpmdc in a paper |
Use the record in |
Questions and bug reports¶
Ask questions and report bugs on the GitHub issue tracker. Check Troubleshooting first, because it lists known failures with their fixes. Its last section lists what to put in a new report.
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 |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
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 |
|
Geometry step |
serialized |
|
Result carrier |
serialized |
|
Runtime discovery |
stable feature IDs |
|
An OpenCPMD archive build links the same C ABI surface against libcpmd.a.
Tutorials
How-To Guides
- Install and build
- Build the OpenCPMD archive for embedding
- Write a CPMDParams message
- Embedding cpmdc
- Call cpmdc from Python
- Run under mpirun
- Choose the wavefunction optimiser
- Extrapolate the orbitals along a trajectory
- Debug an input with CPMDCDECKOUT
- Check forces and stress by finite differences
- Time the plane-wave scaffold on ranks
- Troubleshooting
Reference
Explanation
Contributing
Project
Citation¶
Cite cpmdc with the record in CITATION.cff at the root of the repository. It gives the author, the version, the license, and the repository in the Citation File Format. GitHub reads that file and offers the record as “Cite this repository” on the repository page, as the GitHub documentation on citation files describes. The record carries no digital object identifier (DOI).
An OpenCPMD archive build computes its energies and forces with OpenCPMD, so a paper that reports them cites OpenCPMD as well. OpenCPMD ships no citation file; name it with its repository, github.com/OpenCPMD/CPMD, and the version or commit that the archive was built from.
License¶
cpmdc is released under the MIT License.
The full terms are in
LICENSE at
the root of the repository.