cpmdc

_images/logo-light.svg _images/logo-dark.svg

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

First energy and forces

Drive the same step from ASE

Point CPMDCCalculator at a CPMDParams file

An energy and forces from ASE

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

Build OpenCPMD for more than one CPU

Use the PIC configure file, which passes -march=x86-64 or -march=armv8-a

OpenCPMD archive

See which instruction sets cpmdc compiles for

This library has no hot kernel and does not read CPMDC_SIMD

SIMD paths and dispatch

Edit these docs

Regenerate generated docs from docs/orgmode before building Sphinx

Contributing

Ask a question or report a bug

Open an issue with the version, the build options, and the failing deck

GitHub issue tracker

Cite cpmdc in a paper

Use the record in CITATION.cff, and cite OpenCPMD for its energies

CITATION.cff

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

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.

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.