.. image:: /_static/logo-light.svg :class: light-only :width: 460 :align: center .. image:: /_static/logo-dark.svg :class: dark-only :width: 460 :align: center 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 | one session | | | sections, | | | | pseudopotentials, | | | | backend hints | | +---------------------+-----------------------+-----------------------+ | ``ForceInput`` | positions, atomic | one calculation step | | | numbers, optional | | | | cell, requested units | | +---------------------+-----------------------+-----------------------+ | ``PotentialResult`` | energy, forces, | one calculation | | | status, message | 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 atom count and ordered atomic numbers. Later steps may change coordinates, units, and the 3 by 3 cell; topology changes require a new session. Start Here ========== .. list-table:: :header-rows: 1 * - You want to - Start with - Page * - See an energy and forces come out of the C API - Build the default library, then link OpenCPMD - :doc:`First energy and forces ` * - Relax a structure from eOn - Pass a ``CPMDParams`` file through ``[RgpotPot] params_path`` - :doc:`eOn through rgpot ` * - Build and test the project - Run the default Meson suite and learn what it covers - :doc:`Quickstart ` and :doc:`Install and build ` * - Link a real OpenCPMD archive - Apply the patches in ``tools/`` and build with ``-fPIC`` - :doc:`OpenCPMD archive ` * - Turn a CPMD deck into a message - Pick typed section fields before raw deck text - :doc:`Write a CPMDParams message ` * - Call cpmdc from a host process - Choose the API path first; new hosts usually want ``cpmdc_session_calculate_result`` - :doc:`Embedding cpmdc ` and :doc:`C ABI reference ` * - Run on many ranks - Bind calculator groups and share the parent rank's result - :doc:`Run under mpirun ` * - Find out why a call failed or an energy is off - Write the deck with ``CPMDC_DECK_OUT`` - :doc:`Troubleshooting ` * - Understand what happens inside a call - Layers, the in-process route, orbitals between calls - :doc:`Architecture ` * - Edit these docs - Regenerate generated docs from ``docs/orgmode`` before building Sphinx - :doc:`Contributing ` Build and Test ============== .. code:: bash 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`` | ``catalog.cpmd.OPTIMIZE_GEOMETRY_CLASSICAL``, | | | plus ``optimizeGeometrySample`` | ``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 | ``inputSections.vdw.directives`` and ``subsections`` | ``catalog.section.VDW`` | | ``EMPIRICAL CORRECTION`` | | | +--------------------------------------------+-------------------------------------------------------+--------------------------------------------------+ 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 :doc:`CPMD option mapping `. Runtime Contracts ================= +-------------------+------------------------+-------------------------------------+ | Concern | Carrier | Public entry points | +===================+========================+=====================================+ | Method setup | serialized | ``cpmdc_session_create``, | | | ``CPMDParams`` | ``cpmdc_session_set_params``, | | | | ``cpmdc_set_params`` | +-------------------+------------------------+-------------------------------------+ | Geometry step | serialized | ``cpmdc_session_calculate_result``, | | | ``ForceInput`` or C | ``cpmdc_session_calculate_forces``, | | | arrays | ``cpmdc_session_energy_forces`` | +-------------------+------------------------+-------------------------------------+ | Result carrier | serialized | ``cpmdc_session_calculate_result``, | | | ``PotentialResult`` or | ``cpmdc_calculate_result``, | | | native C values | ``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``. .. toctree:: :maxdepth: 2 :caption: Tutorials tutorials/first-energy tutorials/eon-rgpot tutorials/quickstart .. toctree:: :maxdepth: 2 :caption: How-To Guides howto/install howto/opencpmd-archive howto/write-cpmdparams howto/embedding howto/mpi howto/wavefunction-optimiser howto/debug-deck howto/troubleshooting .. toctree:: :maxdepth: 2 :caption: Reference reference/c-abi reference/environment reference/cpmdparams-schema reference/cpmd-options reference/feature-inventory reference/surface-map reference/glossary api/index .. toctree:: :maxdepth: 2 :caption: Explanation explanation/architecture explanation/routes explanation/wavefunction-state explanation/mpi-model .. toctree:: :maxdepth: 2 :caption: Contributing contributing/index .. toctree:: :maxdepth: 1 :caption: Project changelog