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 |
|
Cap’n Proto decode and deck rendering |
|
Session, topology, result sizing, and unit conversion |
|
Generated feature inventory |
|
Base |
|
Top-level |
|
Public C ABI inventory |
|
Stub ABI feature rows |
|
Shared library ABI exports |
|
|
|
Inline option token coverage |
|
Typed render field coverage |
|
Long-tail directive section coverage |
|
Escape-hatch carrier coverage |
|
Embedding docs coverage |
|
Public header docs coverage |
|
Public host example docs |
|
README and quickstart navigation |
|
OpenCPMD archive build |
|
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 |
|---|---|
|
Add catalog coverage and rendered-token checks |
|
Add |
|
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 |
|---|---|
|
Add the |
|
Render the exact |
|
Add catalog and parameter feature table rows |
|
Add matching inventory metadata |
|
Add a base |
|
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 |
|---|---|
|
shared RPC and direct-call wire contract |
|
public C ABI and session result entry points |
|
runtime feature discovery ABI |
|
Cap’n Proto decode, effective config, CPMD deck rendering |
|
session lifecycle, topology guard, unit conversion, result writing |
|
Fortran |
|
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).