Julia
=====

Pure Julia package using ``ccall`` into the native library.  Distributed
via a private registry.

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

Note: Julia uses free functions dispatched on ``MultipleDefectModel`` rather
than methods.  The naming convention differs from C++/Python:
``getTimeDerivative`` → ``trapped_rates``, ``getMobileTimeDerivative`` →
``mobile_rates``, both together → ``rates``.

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

   **Process configuration**,
   —,                                            "``Palioxis.init(path)``  /  ``palioxis_root(path)``"
   **Construction**,
   ``Palioxis_ctor``,                            "``MultipleDefectModel(xml_filename)``  /  ``try_model(xml_filename)``"
   ``Palioxis_delete``,                          "``close(model)``  *(finaliser)*"
   **Model metadata** *(struct fields)*,
   ``getnGas``,                                  "``model.n_gas``"
   ``getnTrap``,                                 "``model.n_traps``"
   ``getnDofAfterConstraint``,                   "``model.n_ne_species``"
   ``getGas_name`` / ``gas_name_len``,           "``gas_names(model)``"
   ``getTrap_name`` / ``trap_name_len``,         "``defect_names(model)``"
   ``getDof_name`` / ``dof_name_len``,           "``trap_names(model)``"
   ``getBoltzmannConst``,                        "``model.kb``  *(cached)*"
   ``self_consistent``,                          "``self_consistent(model)``"
   ``getMaxOccupancy``,                          "``get_max_trap_occupancy(model, trap_index)``"
   **Diffusion**,
   ``getDiffusionConstant``,                     "``diffusion_constants(model, T)``"
   ``effectiveDiffusionCoefficientPrefactor``,   "``effective_diffusion_prefactor(model, mobile, defects, T)``"
   ``getDiffusionConstantStress``,               "``diffusion_constants_stress(model, T, stress)``"
   ``effectiveDiffusionCoefficientPrefactorStress``, "``effective_diffusion_prefactor_stress(model, mobile, defects, T, stress)``"
   ``getRelaxationVolume``,                      "``get_relaxation_volume(model)``"
   ``getHeatOfTransport``,                       "—"
   **Time integration**,
   ``getTimeDerivative``,                        "``trapped_rates(model, mobile, trapped, T)``  /  ``trapped_rates!(out, ...)``"
   ``getMobileTimeDerivative``,                  "``mobile_rates(model, mobile, defects, trapped, T)``  /  ``mobile_rates!(out, ...)``"
   —,                                            "``rates(model, mobile, defects, trapped, T)``  *(both)*  /  ``rates!(...)``"
   ``getTimeDerivativesJacobian``,                   "``time_derivatives_jacobian(model, defects, mobile, trapped, T)``  → ``TimeDerivativesJacobian``"
   ``getMobileTimeDerivativeJacobianFromTrapped``,    "``mobile_time_derivative_jacobian_from_trapped(model, defects, trapped, T, dyc, ddyc_dx, ddyc_dyc)``  → ``MobileTimeDerivativeJacobian``"
   ``getTimeDerivativeskBTJacobian``,                 "``time_derivatives_temperature_sensitivity(model, defects, mobile, trapped, T)``  → ``TimeDerivativesTemperatureSensitivity``"
   **Initialisation**,
   ``defect_density``,                           "``get_defect_concentrations(model, z1, z2)``"
   ``gas_fluence``,                              "``set_fluence_source_rate(model, z1, z2)``"
   ``setInitial_condition``,                     "``set_initial_conditions(model, mobile, T)``"
   ``gas_flux``,                                 "``gas_flux(model, z1, z2)``"
   —,                                            "``get_ic_from_xml(model, location, z1, z2, T)``  *(composite)*"
   **Bounds / validation**,
   ``ensureBounds``,                             "``ensure_bounds!(model, mobile, defects, trapped)``"
   ``inBounds``,                                 "``in_bounds(model, mobile, defects, trapped)``"
   **Surface**,
   ``surfaceRate``,                              "``surface_rates(model, location, mobile, T)``  /  ``surface_rates!(out, ...)``"
   ``surfaceVoxSetDirichlet``,                   "``set_surface_dirichlet!(model, location, mobile, T)``"
   **Retention**,
   ``retention``,                                "``retention(model, mobile, defects, trapped, T, location, thickness)``"
   ``retention_noneq``,                          "``noneq_retention(model, defects, trapped, T)``"
   ``retention_trapped_by_occupation``,          "``trapped_retention_by_occupation(model, trap_index, mobile, defects, trapped, T)``"
   ``retention_trapped_by_trap``,                "``trapped_retention_by_trap(model, mobile, defects, trapped, T)``"
   ``probability_of_occupation``,                "``probability_of_occupation(model, trap_index, mobile, trapped, T)``"
   ``calculate_mobile_steady_state``,            "``calculate_mobile_steady_state(model, mobile, defects, T, trapped)``"
   ``calculate_steady_state``,                   "``calculate_steady_state!(model, mobile, defects, trapped, T)``  *(in-place)*"
   **Diagnostics**,
   ``report``,                                   "``report(model; verbose=false)``"
   ``Lib_Palioxis_init_MPI``,                    "—"
   ``echo_message``,                             "—"

Usage
-----

**Install** from the private registry:

.. code-block:: julia

   using Pkg
   Pkg.activate(temp=true)

   Pkg.Registry.add("General")
   Pkg.Registry.add(url="https://github.com/stephen-dixon/julia-registry.git")

   Pkg.add("Palioxis")

**Example:**

.. code-block:: julia

   using Palioxis

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

   # Construct a model — try_model returns nothing on failure rather than throwing.
   m = Palioxis.try_model("input.xml")

   # Cached metadata available as struct fields.
   println(m.n_gas, " ", m.gas_names, " ", m.defect_names)

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

   # Effective diffusion coefficient prefactor (ShapedDoubleData with .shape and .data).
   D_eff = effective_diffusion_prefactor(m, mobile, defects, T)

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