MATLAB / Octave
===============

MEX extension built with Octave's ``mkoctfile``, compatible with both
Octave and MATLAB.  Platform ZIPs (Linux x86\_64, macOS Intel, macOS ARM)
are attached to each GitHub release.

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

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

   **Process configuration**,
   —,                                            "``palioxis.set_root(path)``"
   —,                                            "``palioxis.root()``"
   **Construction / destruction**,
   ``Palioxis_ctor``,                            "``palioxis.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``,                        "``palioxis.MultipleDefectModel.get_boltzmann_const()``"
   ``getMinMobileConc``,                         "``palioxis.MultipleDefectModel.get_min_mobile_conc()``"
   ``self_consistent``,                          "—"
   ``getMaxOccupancy``,                          "used internally by ``retention_trapped_by_occupation``"
   **Diffusion**,
   ``getDiffusionConstant``,                     "``model.get_diffusion_constant(T)``"
   ``effectiveDiffusionCoefficientPrefactor``,   "``model.effective_diffusion_prefactor(mobile, defects, T)``"
   ``getDiffusionConstantStress``,               "—"
   ``effectiveDiffusionCoefficientPrefactorStress``, "—"
   ``getRelaxationVolume``,                      "—"
   ``getHeatOfTransport``,                       "—"
   **Time integration**,
   ``getTimeDerivative``,                        "``model.get_time_derivative(mobile, trapped, T)``"
   ``getMobileTimeDerivative``,                  "``model.get_mobile_time_derivative(mobile, defects, trapped, T)``"
   —,                                            "``[trapped_dy, mobile_dy] = model.get_time_derivatives(mobile, defects, trapped, T)``"
   ``getTimeDerivativesJacobian``,               "``model.get_time_derivatives_jacobian(defects, mobile, trapped, T)``"
   ``getMobileTimeDerivativeJacobianFromTrapped``, "``model.get_mobile_jacobian_from_trapped(defects, trapped, T, dyc, ddyc_dx, ddyc_dyc)``"
   ``getTimeDerivativeskBTJacobian``,            "``model.get_time_derivatives_temperature_sensitivity(defects, mobile, trapped, T)``"
   **Initialisation**,
   ``defect_density``,                           "``model.get_defect_concentrations(z1, z2)``"
   ``gas_fluence``,                              "``model.get_fluence_source_rate(z1, z2)``"
   ``setInitial_condition``,                     "``model.set_initial_conditions(mobile, T)``"
   ``gas_flux``,                                 "``model.get_gas_flux(z1, z2)``"
   —,                                            "``model.get_ic_from_xml(z1, z2, T)``  *(composite)*"
   **Bounds / validation**,
   ``ensureBounds``,                             "``[mobile, defects, trapped] = model.ensure_bounds(mobile, defects, trapped)``"
   ``inBounds``,                                 "``model.in_bounds(mobile, defects, trapped)``"
   **Surface**,
   ``surfaceRate``,                              "``model.get_surface_rate(location, mobile, T)``"
   ``surfaceVoxSetDirichlet``,                   "—"
   **Retention**,
   ``retention``,                                "``model.retention(mobile, defects, trapped, T, location, thickness)``"
   ``retention_noneq``,                          "``model.non_equilibrium_retention(defects, trapped, T)``"
   ``retention_trapped_by_occupation``,          "``model.retention_trapped_by_occupation(trap_index, mobile, defects, trapped, T)``"
   ``retention_trapped_by_trap``,                "``model.retention_trapped_by_trap(mobile, defects, trapped, T)``"
   ``probability_of_occupation``,                "—"
   ``calculate_mobile_steady_state``,            "``model.calculate_mobile_steady_state(mobile, defects, trapped, T)``"
   ``calculate_steady_state``,                   "``[mobile, trapped] = model.calculate_steady_state(mobile, defects, trapped, T)``"
   **Diagnostics**,
   ``report``,                                   "``model.report(verbose)``"
   ``Lib_Palioxis_init_MPI``,                    "—"
   ``echo_message``,                             "—"

Usage
-----

**Install** from a downloaded ZIP:

.. code-block:: matlab

   % Unzip the platform archive, then add the extracted folder to your path.
   unzip('palioxis-matlab-mexmaca64.zip', '~/palioxis-matlab')
   addpath('~/palioxis-matlab/palioxis-matlab')

**Example:**

.. code-block:: matlab

   % Set the Palioxis data root once per session.
   palioxis.set_root('/path/to/palioxis');

   % Construct a model from an XML configuration file.
   m = palioxis.MultipleDefectModel('input.xml');

   % Cached metadata available as read-only properties.
   disp(m.n_gas);
   disp(m.gas_names);
   disp(m.defect_names);

   % State vectors — sizes follow the cached dimensions.
   mobile  = zeros(m.n_gas, 1);
   defects = zeros(m.n_trap_types, 1);
   trapped = zeros(m.n_ne_traps, 1);
   T = 800;  % Kelvin

   % Effective diffusion coefficient prefactor matrix (n_gas × n_gas).
   D_eff = m.effective_diffusion_prefactor(mobile, defects, T);

   % Both mobile and trapped time derivatives in a single call.
   [trapped_dy, mobile_dy] = m.get_time_derivatives(mobile, defects, trapped, T);
   % trapped_dy — trapped rates  [n_ne_traps × 1]
   % mobile_dy  — mobile rates   [n_gas × 1]