C++
===

Header-only wrapper in ``include/palioxis.hpp``.  No build step required —
add ``include/`` to your include path and link against the Palioxis static
library.

API coverage
------------

.. csv-table::
   :header: "C API (``Lib_Palioxis_c.h``)", "C++ wrapper"
   :widths: 42, 58

   **Process configuration**,
   —,                                            "``palioxis::set_root(path)``"
   —,                                            "``palioxis::root()``"
   **Construction / destruction**,
   ``Palioxis_ctor``,                            "``MultipleDefectModel(xml_filename)``"
   ``Palioxis_delete``,                          "destructor"
   **Model metadata**,
   ``getnGas``,                                  "``model.get_n_gas()``  / cached ``_n_gas``"
   ``getnTrap``,                                 "``model.get_n_trap_types()``"
   ``getnDofAfterConstraint``,                   "``model.get_n_ne_traps()``"
   ``getGas_name`` / ``gas_name_len``,           "``model.gas_names()``"
   ``getTrap_name`` / ``trap_name_len``,         "``model.defect_names()``"
   ``getDof_name`` / ``dof_name_len``,           "``model.trap_names()``"
   ``getPalioxisVersion``,                       "``MultipleDefectModel::version()``"
   ``getBoltzmannConst``,                        "cached at construction"
   ``getMinMobileConc``,                         "``MultipleDefectModel::get_min_mobile_conc()``"
   ``self_consistent``,                          "``model.self_consistent()``"
   ``getMaxOccupancy``,                          "``model.get_max_trap_occupancy(trap_index)``"
   **Diffusion**,
   ``getDiffusionConstant``,                     "``model.get_diffusion_constant(T)``"
   ``getDiffusionConstantStress``,               "``model.get_diffusion_constant_stress(T, stress)``"
   ``effectiveDiffusionCoefficientPrefactor``,   "``model.effective_diffusion_prefactor(mobile, defects, T)``"
   ``effectiveDiffusionCoefficientPrefactorStress``, "``model.effective_diffusion_prefactor_stress(mobile, defects, T, stress)``"
   ``getRelaxationVolume``,                      "``model.get_relaxation_volume()``"
   ``getHeatOfTransport``,                       "—"
   ``getHeatOfTransportStress``,                 "—"
   **Time integration**,
   ``getTimeDerivative``,                        "``model.get_time_derivative(mobile, trapped, T)``"
   ``getMobileTimeDerivative``,                  "``model.get_mobile_time_derivative(mobile, defects, trapped, T)``"
   —,                                            "``model.get_time_derivatives(mobile, defects, trapped, T)``  *(both)*"
   ``getTimeDerivativesJacobian``,              "``model.get_time_derivatives_jacobian(defects, mobile, trapped, T)``  → ``TimeDerivativesJacobian``"
   ``getMobileTimeDerivativeJacobianFromTrapped``, "``model.get_mobile_time_derivative_jacobian_from_trapped(defects, trapped, T, dyc, ddyc_dx, ddyc_dyc)``  → ``MobileTimeDerivativeJacobian``"
   ``getTimeDerivativeskBTJacobian``,           "``model.get_time_derivatives_temperature_sensitivity(defects, mobile, trapped, T)``  → ``TimeDerivativesTemperatureSensitivity``"
   **Initialisation**,
   ``defect_density``,                           "``model.get_defect_concentrations(z1, z2)``"
   ``gas_fluence``,                              "``model.set_fluence_source_rate(z1, z2)``"
   ``setInitial_condition``,                     "``model.set_initial_conditions(mobile, T)``"
   ``gas_flux``,                                 "``model.apply_gas_flux(z1, z2)``"
   —,                                            "``model.get_ic_from_xml(location, z1, z2, T)``  *(composite)*"
   **Bounds / validation**,
   ``ensureBounds``,                             "``model.ensure_bounds(mobile, defects, trapped)``"
   ``inBounds``,                                 "``model.in_bounds(mobile, defects, trapped)``"
   **Surface**,
   ``surfaceRate``,                              "``model.get_surface_rate(location, mobile, T)``"
   ``surfaceVoxSetDirichlet``,                   "``model.set_surface_dirichlet(location, mobile, T)``"
   **Retention**,
   ``retention``,                                "``model.retention(mobile, defects, trapped, T, location, thickness)``"
   ``retention_noneq``,                          "``model.non_equilibrium_retention(defects, trapped, T)``"
   ``retention_trapped_by_occupation``,          "``model.trapped_retention_by_occupation(trap_index, mobile, defects, trapped, T)``"
   ``retention_trapped_by_trap``,                "``model.trapped_retention_by_trap(mobile, defects, trapped, T)``"
   ``probability_of_occupation``,                "``model.probability_of_occupation(trap_index, mobile, trapped, T)``"
   ``calculate_mobile_steady_state``,            "``model.calculate_mobile_steady_state(mobile, defects, T, trapped)``"
   ``calculate_steady_state``,                   "``model.calculate_steady_state(mobile, T, trapped, defects)``"
   **Diagnostics**,
   ``report``,                                   "``model.report(verbose=false)``"
   ``Lib_Palioxis_init_MPI``,                    "—"
   ``echo_message``,                             "—"

Usage
-----

.. code-block:: cpp

   #include "palioxis.hpp"

   // Set the Palioxis data root once per process.
   // XML input files cross-reference each other relative to this path.
   palioxis::set_root("/path/to/palioxis");

   // Construct a model from an XML configuration file.
   palioxis::MultipleDefectModel m("input.xml");

   // Inspect cached metadata.
   std::cout << "n_gas = " << m.get_n_gas() << "\n";
   for (const auto& name : m.gas_names())
       std::cout << "  gas: " << name << "\n";

   // State vectors — sizes: mobile[n_gas], defects[n_trap_types], trapped[n_ne_traps]
   palioxis::MobileConcentrations  mobile  = { /* ... */ };
   palioxis::DefectConcentrations  defects = { /* ... */ };
   palioxis::TrappedConcentrations trapped = { /* ... */ };
   double T = 800.0;  // Kelvin

   // Effective diffusion coefficient prefactor matrix (n_gas × n_gas).
   palioxis::ShapedDoubleData D_eff = m.effective_diffusion_prefactor(mobile, defects, T);

   // Both mobile and trapped time derivatives in a single call.
   palioxis::TimeDerivatives dy = m.get_time_derivatives(mobile, defects, trapped, T);
   // dy.mobile  — mobile rates  [n_gas]
   // dy.trapped — trapped rates [n_ne_traps]