Python
======

pybind11 extension module.  Wheels for Linux (x86\_64, aarch64) and macOS
(Intel, Apple Silicon) are attached to each GitHub release.

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

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

   **Module-level**,
   —,                                            "``palioxis.set_root(path)``"
   —,                                            "``palioxis.root()``"
   ``getPalioxisVersion``,                       "``palioxis.version()``"
   ``getMinMobileConc``,                         "``palioxis.get_min_mobile_conc()``"
   **Construction / destruction**,
   ``Palioxis_ctor``,                            "``MultipleDefectModel(xml_filename)``"
   ``Palioxis_delete``,                          "destructor"
   **Model metadata** *(read-only properties)*,
   ``getnGas``,                                  "``model.n_gas``"
   ``getnTrap``,                                 "``model.n_trap_types``"
   ``getnDofAfterConstraint``,                   "``model.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``"
   ``getBoltzmannConst``,                        "cached at construction"
   ``self_consistent``,                          "``model.self_consistent()``"
   ``getMaxOccupancy``,                          "``model.get_max_trap_occupancy(trap_index)``"
   **Diffusion**,
   ``getDiffusionConstant``,                     "``model.get_diffusion_constant(T)``  → ``list[float]``"
   ``getDiffusionConstantStress``,               "``model.get_diffusion_constant_stress(T, stress)``"
   ``effectiveDiffusionCoefficientPrefactor``,   "``model.effective_diffusion_prefactor(mobile, defects, T)``  → ``np.ndarray``"
   ``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)``  → ``(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
-----

**Install** from a downloaded wheel:

.. code-block:: bash

   pip install palioxis-<version>-<platform>.whl

**Example:**

.. code-block:: python

   import palioxis
   import numpy as np

   # Set the Palioxis data root once per process.
   palioxis.set_root("/path/to/palioxis")

   # Construct a model from an XML configuration file.
   m = palioxis.MultipleDefectModel("input.xml")

   # Cached metadata available as properties.
   print(m.n_gas, m.gas_names, m.defect_names)

   # State vectors — sizes follow the cached dimensions.
   mobile  = np.zeros(m.n_gas)
   defects = np.zeros(m.n_trap_types)
   trapped = np.zeros(m.n_ne_traps)
   T = 800.0  # Kelvin

   # Effective diffusion coefficient prefactor matrix (n_gas × n_gas numpy array).
   D_eff = m.effective_diffusion_prefactor(mobile, defects, T)

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