Default Build

The default build is the first check for this repository. The build compiles the parser, generated Cap’n Proto readers, shared libcpmdc, feature table, session runtime, and deterministic reference evaluator. No OpenCPMD checkout is needed.

Install Meson, Ninja, Cap’n Proto, cmocka, C and Fortran compilers, and pkg-config with your system package manager, or use the checked-in Pixi environment:

pixi run test-stub

The equivalent explicit commands are:

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

The pass condition is a successful Meson run covering parser, ABI, feature inventory, session lifecycle, result sizing, unit conversion, and reference-evaluator E2E tests.

Common Paths

Path	Commands	Expected coverage
Full default suite	meson setup build -Dwith_tests=true; meson compile -C build; meson test -C build --print-errorlogs	parser, ABI, feature inventory, sessions, E2E reference evaluator
cmocka/parser focus	meson test -C build --suite cmocka --print-errorlogs	Cap’n Proto decode, deck rendering, feature table checks
session E2E focus	meson test -C build --suite e2e --print-errorlogs	one-shot calls, session calls, topology rejection, unit conversion
docs	pixi run -e docs docbld	Org export, generated C API pages, Sphinx HTML

Work Loop

Build once, then iterate with focused tests. Use the table above to pick the smallest command that exercises the layer you changed, then run the default suite when the focused command passes.

Step	Command	Use it when
Configure or reconfigure	meson setup build -Dwith_tests=true or meson setup --reconfigure build	Reconfigure only when build definitions change, dependencies change, or the build directory does not exist
Compile after C, Fortran, or schema edits	meson compile -C build	The changed code affects compiled targets or generated Cap’n Proto readers
Run a focused guard	meson test -C build <test-name> --print-errorlogs	One inventory, ABI, parser, session, or docs contract names the changed behavior
Run the default suite	meson test -C build --print-errorlogs	Run the full suite before publishing a change
Build docs	pixi run -e docs sphinxbld	Public prose, org sources, API headers, or generated RST changed

meson test rebuilds stale targets before running tests, so most source edits do not need a separate configure step.

This configuration compiles the vendored capnp-c runtime, generates C readers for schema/Potentials.capnp, and runs cmocka suites:

stub

tests/test_stub_abi.c

abi

exported header and feature-discovery surface

cmocka / capnp

structured CPMDParams deck rendering

params / inventory

schema field coverage and CPMD catalog feature IDs

socket

ForceInput sizing and session PotentialResult buffer contract

e2e

one-shot and session calls through the deterministic reference evaluator

cmocka is resolved through pkg-config. The parser tests use Cap’n Proto text fixtures encoded by the capnp CLI (tests/encode_capnp.py).

The standalone stub target is different from the default shared engine: libcpmdc_stub.a only provides linkable symbols and reports cpmdc_available() == 0. The default shared libcpmdc reports availability through the reference evaluator and can run the session tests.

What To Read After The First Run

Need	Page
Compute an energy and forces from your own C program	First energy and forces
Call the C ABI from a host process	Embedding cpmdc and C ABI reference
Choose structured CPMDParams fields	Write a CPMDParams message and CPMD option mapping
Understand sessions, units, and topology	Architecture
Link against a real OpenCPMD archive	OpenCPMD archive and OpenCPMD Archive Build below

Run The Host Example

examples/host_step.c is a minimal C host for the public ABI. It reads one serialized CPMDParams file and one serialized ForceInput file, creates a CPMDCSession, sizes the PotentialResult output, evaluates one step, and prints the result summary.

meson test -C build example-host-step --print-errorlogs

The example output has this shape:

energy_h=...
potential_result_size_bytes=...
message=...

The Meson test feeds the example from the same generated fixture binaries used by the E2E suites. Those fixture binaries are produced from tests/cpmd_params_parser.capnp.txt or tests/water_blyp_params.capnp.txt and tests/force_input_step_a.capnp.txt, depending on whether the build links OpenCPMD archives.

Test Selection

Use the smallest suite that exercises the layer you changed:

Change	Command	Pass condition
Parser, feature inventory, or C ABI	meson test -C build --print-errorlogs	all configured tests pass
Deck rendering or Cap’n Proto fixtures	meson test -C build --suite cmocka --print-errorlogs	cmocka render suites pass
Session lifecycle, topology, or units	meson test -C build --suite e2e --print-errorlogs	single-point and optimizer-session tests pass
Public documentation	pixi run -e docs sphinxbld	Sphinx build succeeds
Org-to-RST refresh	pixi run -e docs mkrst	checked-in docs/source/*.rst matches the org sources
OpenCPMD archive link	CPMDC_PSEUDO_DIR=/path/to/PP_LIBRARY meson test -C build-cpmd --print-errorlogs	default tests plus live water parity pass

meson test --print-errorlogs is preferred because cmocka assertion output and OpenCPMD diagnostics stay attached to the failed test.

Session Suites

The embed shell includes a deterministic harmonic evaluator so single-point and multi-step session paths work without linking OpenCPMD archives. Real PW-DFT evaluation replaces that evaluator when archives are wired.

meson test -C build --suite e2e --print-errorlogs
# or
pixi run test-e2e

e2e-single-point

cpmdc_calculate_result + cpmdc_energy_forces on one ForceInput (HO-like geometry).

e2e-optimizer-session

one CPMDCSession, three geometry steps (A, B, then A again), forces on B, topology rejection, then a second session for species change.

OpenCPMD Archive Build

The default build emits libcpmdc.so for dlopen consumers such as rgpot. Passing a tree path links that same C ABI surface against libcpmd.a.

export CPMD_ROOT=/path/to/OpenCPMD/CPMD
export CPMDC_PSEUDO_DIR=/path/to/Regtests/tests/PP_LIBRARY
meson setup build-cpmd \
  -Dwith_cpmd=true \
  -Dcpmd_root="$CPMD_ROOT" \
  -Dwith_tests=true
meson compile -C build-cpmd
meson test -C build-cpmd --print-errorlogs

The OpenCPMD tree must contain lib/libcpmd.a and obj/timetag.o from a completed executable build, patched and compiled with -fPIC as the archive how-to describes. If the params use pseudopotential library tokens such as O_MT_BLYP.psp, set CPMDC_PSEUDO_DIR to the directory containing those files before running real backend tests or embedding the library.

The live build runs the same public C ABI as the default build. When with_cpmd=true is enabled, water Cap’n Proto parity tests are added and the long E2E tests exercise the linked OpenCPMD archive.

Common Failures

These checks usually identify environment problems before code changes are needed:

Symptom	Check
with_cpmd requires ... lib/libcpmd.a	CPMD_ROOT points at a completed OpenCPMD build tree with lib/libcpmd.a
OpenCPMD cannot find O_MT_BLYP.psp or H_CVB_BLYP.psp	CPMDC_PSEUDO_DIR points at the regtest PP_LIBRARY or the params use absolute pseudopotential paths
A session reports a topology change	the same CPMDCSession received a different atom count or ordered atomic-number list; create a new session
PotentialResult buffer too small	call cpmdc_potential_result_size_for_force_input() and allocate at least that many bytes
Unit parsing fails	use supported length/energy strings such as angstrom, bohr, eV, and hartree
capnp encode fails on a fixture	re-run the command against schema/Potentials.capnp and the intended root type, either CPMDParams or ForceInput

Cap’n Proto Fixtures

Encode a CPMDParams or ForceInput text message the same way tests do:

capnp encode schema/Potentials.capnp CPMDParams \
  < tests/cpmd_params_parser.capnp.txt > /tmp/cpmd_params.bin
capnp encode schema/Potentials.capnp ForceInput \
  < tests/force_input_step_a.capnp.txt > /tmp/force_input.bin

Pass those buffers to cpmdc_session_create() and cpmdc_session_calculate_result() from C, Python (pycapnp), or rgpot.