Quickstart¶
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 |
|
parser, ABI, feature inventory, sessions, E2E reference evaluator |
cmocka/parser focus |
|
Cap’n Proto decode, deck rendering, feature table checks |
session E2E focus |
|
one-shot calls, session calls, topology rejection, unit conversion |
docs |
|
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 |
|
Reconfigure only when build definitions change, dependencies change, or the build directory does not exist |
Compile after C, Fortran, or schema edits |
|
The changed code affects compiled targets or generated Cap’n Proto readers |
Run a focused guard |
|
One inventory, ABI, parser, session, or docs contract names the changed behavior |
Run the default suite |
|
Run the full suite before publishing a change |
Build docs |
|
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:
stubtests/test_stub_abi.cabiexported header and feature-discovery surface
cmocka/capnpstructured
CPMDParamsdeck renderingparams/inventoryschema field coverage and CPMD catalog feature IDs
socketForceInputsizing and sessionPotentialResultbuffer contracte2eone-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 also returns cpmdc_available() == 0, because that call means OpenCPMD is linked.
Session tests still run on the reference evaluator.
What To Read After The First Run¶
Need |
Page |
|---|---|
Compute an energy and forces from your own C program |
|
Call the C ABI from a host process |
|
Choose structured |
|
Understand sessions, units, and topology |
|
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 |
|
all configured tests pass |
Deck rendering or Cap’n Proto fixtures |
|
cmocka render suites pass |
Session lifecycle, topology, or units |
|
single-point and optimizer-session tests pass |
Public documentation |
|
Sphinx build succeeds |
Org-to-RST refresh |
|
|
OpenCPMD archive link |
|
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-pointcpmdc_calculate_result+cpmdc_energy_forceson oneForceInput(HO-like geometry).e2e-optimizer-sessionone
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 |
|---|---|
|
|
OpenCPMD cannot find |
|
A session reports a topology change |
the same |
|
call |
Unit parsing fails |
use supported length/energy strings such as |
|
re-run the command against |
Cap’n Proto Fixtures¶
Encode a CPMDParams or ForceInput text message the same way tests do:
mkdir -p tutorial-work
capnp encode schema/Potentials.capnp CPMDParams \
< tests/cpmd_params_parser.capnp.txt > tutorial-work/cpmd_params.bin
capnp encode schema/Potentials.capnp ForceInput \
< tests/force_input_step_a.capnp.txt > tutorial-work/force_input.bin
Pass those buffers to cpmdc_session_create() and
cpmdc_session_calculate_result() from C, Python (pycapnp), or rgpot.