Contributing

Bug reports, fixes, tests, documentation, and new typed keywords for the input deck are welcome. Report a problem or propose a change on the GitHub issue tracker. Send the change itself as a pull request to the cpmdc repository on GitHub. The sections below list the checks to run first and the files that each kind of change touches.

Development Checks

Run the default parser, socket, and stub checks before changing the ABI, schema, renderer, or session runtime:

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

Use focused suites while iterating, then run the default suite before pushing a public change:

Contract

Command

Full default ABI and parser suite

meson test -C build --print-errorlogs

Cap’n Proto decode and deck rendering

meson test -C build --suite cmocka --print-errorlogs

Session, topology, result sizing, and unit conversion

meson test -C build --suite e2e --print-errorlogs

Generated feature inventory

meson test -C build feature-inventory --print-errorlogs

Base &CPMD keyword inventory

meson test -C build cpmd-base-keyword-inventory --print-errorlogs

Top-level CPMDParams feature rows and duplicate inventory lists

meson test -C build cpmd-params-field-inventory --print-errorlogs

Public C ABI inventory

meson test -C build cpmd-public-abi-inventory --print-errorlogs

Stub ABI feature rows

meson test -C build stub-abi-symbol-coverage stub-abi --print-errorlogs

Shared library ABI exports

meson test -C build shared-dlopen-symbol-coverage shared-dlopen-abi --print-errorlogs

CPMDCpmdSection render mappings

meson test -C build cpmd-schema-render-coverage --print-errorlogs

Inline option token coverage

meson test -C build cpmd-option-token-coverage --print-errorlogs

Typed render field coverage

meson test -C build cpmd-typed-render-field-coverage --print-errorlogs

Long-tail directive section coverage

meson test -C build cpmd-long-tail-section-coverage --print-errorlogs

Escape-hatch carrier coverage

meson test -C build cpmd-escape-hatch-coverage --print-errorlogs

Embedding docs coverage

meson test -C build cpmd-embedding-docs-coverage --print-errorlogs

Public header docs coverage

meson test -C build cpmd-public-header-docs-coverage --print-errorlogs

Public host example docs

meson test -C build examples-documented --print-errorlogs

README and quickstart navigation

meson test -C build readme-navigation --print-errorlogs

OpenCPMD archive build

CPMDC_PSEUDO_DIR=/path/to/PP_LIBRARY meson test -C build-cpmd --print-errorlogs

Params render coverage lives under tests/cmocka/ and uses cmocka assertions on generated Cap’n Proto types (read_CPMDParams, deck substrings) only. Session tests use encoded CPMDParams and ForceInput fixtures from tests/*.capnp.txt. feature-inventory ties the generated JSON inventory to the schema, public feature table, docs, public headers, ABI symbol list, and optional CPMD_ROOT parser section probe. cpmd-base-keyword-inventory requires every base &CPMD keyword in schema/inventory/cpmd_cp_keywords.txt to resolve to a catalog.cpmd.* row. cpmd-params-field-inventory requires every top-level CPMDParams schema field to resolve to a params.* feature row and rejects duplicate inventory IDs/lists and C feature table duplicates before set comparisons can hide them. cpmd-public-abi-inventory requires every public cpmdc_* header function to resolve through abi_symbols and the feature table, then verifies the native src/cpmdc.c, stub src/cpmdc_stub.c, or shared src/cpmdc_features.c implementation that exports it. stub-abi-symbol-coverage requires the standalone stub test to assert every abi_symbols feature row is present and stub-applicable. shared-dlopen-symbol-coverage requires the shared-library dlopen test to load every abi_symbols entry from libcpmdc.so. cpmd-schema-render-coverage and cpmd-option-token-coverage keep typed CPMDCpmdSection fields and fixture inline tokens tied to render coverage. cpmd-typed-render-field-coverage requires typed cpmd, system, dft, and atoms fields to appear in render fixtures or render assertions. cpmd-long-tail-section-coverage requires every CPMDDirectiveSection union arm to appear in the long-tail fixture, render assertions, and option reference. cpmd-escape-hatch-coverage requires inputBlocks, generic, set, and raw carriers to stay covered by schema, fixtures, render tests, and option docs. cpmd-embedding-docs-coverage requires the embedding how-to to name the public ABI feature IDs plus the typed, long-tail, and escape-hatch CPMDParams carrier IDs used by host authors. cpmd-public-header-docs-coverage requires the public header and generated C API docs to describe the serialized CPMDParams input surface. examples-documented requires public docs to point at the runnable examples/host_step.c host program. readme-navigation keeps the README and quickstart docs focused on entry paths, work-loop labels, and current wording.

Add a typed CPMD keyword

Use a typed field when a CPMD control has stable structure, affects ordinary host inputs, or should be discoverable through cpmdc_feature_find(). Use directives, set, generic, raw, or inputBlocks for rare literal deck fragments that should stay text.

Start from the test surface:

File

Required change

tests/test_params_cp_dft_render.c

Add catalog coverage and rendered-token checks

tests/test_features_cmocka.c

Add catalog.cpmd.* and params.inputSections.cpmd.* expectations

tests/params_*.capnp.txt

Add a fixture value that exercises the new field

Run the focused failure before adding production code:

CPMD_ROOT=OpenCPMD-cpmdc meson test -C build \
  params-cp-dft-render features-cmocka feature-inventory \
  cpmd-base-keyword-inventory cpmd-params-field-inventory \
  cpmd-public-abi-inventory cpmd-schema-render-coverage \
  stub-abi-symbol-coverage \
  shared-dlopen-symbol-coverage \
  cpmd-option-token-coverage cpmd-typed-render-field-coverage \
  cpmd-long-tail-section-coverage \
  cpmd-escape-hatch-coverage \
  --print-errorlogs

Then update the production and docs surface in one change:

File

Required change

schema/Potentials.capnp

Add the CPMDCpmdSection field with the next field number

src/cpmdc_params.c

Render the exact &CPMD deck spelling accepted by OpenCPMD

src/cpmdc_features.c

Add catalog and parameter feature table rows

schema/inventory/cpmd_features.json

Add matching inventory metadata

schema/inventory/cpmd_cp_keywords.txt

Add a base &CPMD keyword when the parser accepts it as a top-level control

docs/orgmode/reference/cpmd-options.org

Document every writable field ID

Re-run the focused command, then run:

meson test -C build --print-errorlogs
pixi run -e docs sphinxbld

For parser coverage audits, compare OpenCPMD control_utils.mod.F90 keyword_contains(line, ...) branches against catalog.cpmd.* rows. Treat context-specific branch tokens as covered by their structured parent when the schema field renders the accepted deck form, such as LBFGS_NTRUST for LBFGS NTRUST or NOSE_IONS_LOCAL for NOSE IONS LOCAL.

Source Layout

Path

Ownership

schema/Potentials.capnp

shared RPC and direct-call wire contract

include/cpmdc.h

public C ABI and session result entry points

include/cpmdc_features.h

runtime feature discovery ABI

src/cpmdc_params.c

Cap’n Proto decode, effective config, CPMD deck rendering

src/cpmdc.c

session lifecycle, topology guard, unit conversion, result writing

src/cpmd_embed_c_api.F90

Fortran iso_c_binding bridge and OpenCPMD archive path

tests/

encoded fixtures and C/cmocka contract tests

Documentation

Documentation source lives under docs/orgmode (authoritative prose), with light/dark logos in docs/source/_static/ and branding/logo/. Build docs (exports Org to RST, Doxygen XML, Sphinx HTML with Antics analytics):

pixi run -e docs docbld

Link between pages with Org file links, [[file:../howto/mpi.org][text]]. The default export is ox-rst. A file link whose target ends in .org becomes a Sphinx :doc: role, so the same link works on the forge and in the built site. Set CPMDC_ORG_EXPORT=pandoc to export with pandoc instead. That path applies docs/org-links.lua and makes the same :doc: rewrite. Generated docs/source/**/*.rst is not committed.

Regenerate RST after editing Org sources:

pixi run -e docs mkrst

Check the links in the README, the Org sources, and the newsfragments:

pixi run lychee

The task runs lychee with .lychee.toml, which also checks the anchor of a link such as README.md#citation. The Pixi environment does not provide lychee, so put it on the path first. A link to a file on the main branch fails until that file lands there.

The Sphinx theme injects antics-api.turtletech.us/antics.js via docs/source/_templates/partials/extra-head.html, and the footer credit lives in docs/source/_templates/partials/site-foot.html (same pattern as rgpot).

Release Process