spectral_galerkin_heat.io_utils.compute_L2_error
================================================

.. py:module:: spectral_galerkin_heat.io_utils.compute_L2_error

.. autoapi-nested-parse::

   compute_L2_error.py
   ===================
   Compute the L2 norm error between two XDMF solution files at their last
   time step, and optionally output an ``error.xdmf`` / ``error.h5`` file
   for ParaView visualisation.

   Supported grid combinations
   ----------------------------
   1. **Both structured** (``3DRectMesh`` / ``VXVYVZ``):
      If the grids match exactly (same dimensions AND same coordinate
      vectors up to tolerance), a **direct pointwise** comparison is done.
      Otherwise the finer grid is interpolated onto the coarser one using
      ``RegularGridInterpolator`` (trilinear).

   2. **One structured + one unstructured** (``Tetrahedron`` / ``XYZ``):
      The **structured** field is interpolated at the **unstructured mesh
      vertices** using ``RegularGridInterpolator`` (fast trilinear).
      This avoids the slow Delaunay triangulation entirely.
      L2 integration uses vertex volumes computed from the tetrahedral
      connectivity (lumped mass approach).

   3. **Both unstructured**: requires ``--resolution`` to create a common
      structured grid and uses ``LinearNDInterpolator`` for both fields.

   Numerical integration
   ---------------------
   - **Structured grids**: composite trapezoidal rule (second-order accurate)
   - **Unstructured evaluation**: lumped mass integration using vertex
     volumes computed from the tetrahedral mesh connectivity

   Usage
   -----
   ::

       python compute_L2_error.py file_A.xdmf file_B.xdmf [options]

       # Compare spectral output vs FE validation:
       python compute_L2_error.py \
           ../out/sim/fields/field_step000200.xmf \
           validation.xdmf \
           --attr-a temperature --attr-b Temperature

       # Fast convergence study (skip error output):
       python compute_L2_error.py spectral.xmf fe.xdmf --no-error-output



Functions
---------

.. autoapisummary::

   spectral_galerkin_heat.io_utils.compute_L2_error.compute_L2_structured
   spectral_galerkin_heat.io_utils.compute_L2_error.compute_L2_unstructured
   spectral_galerkin_heat.io_utils.compute_L2_error.compare


Module Contents
---------------

.. py:function:: compute_L2_structured(T_a, T_b, x, y, z)

   Compute error norms on a structured grid using trapezoidal rule.


.. py:function:: compute_L2_unstructured(T_a, T_b, vertex_volumes)

   Compute error norms on unstructured vertices using lumped mass.


.. py:function:: compare(path_a, path_b, attr_a = None, attr_b = None, output_base = Path('research/error'), resolution = None, write_error = True)

   Full comparison pipeline: load -> align/interpolate -> L2 -> write.

   :param path_a: Paths to XDMF files. File A is treated as the reference.
   :type path_a: str
   :param path_b: Paths to XDMF files. File A is treated as the reference.
   :type path_b: str
   :param attr_a: Attribute names to load from each file.
   :type attr_a: str, optional
   :param attr_b: Attribute names to load from each file.
   :type attr_b: str, optional
   :param output_base: Base name for error output files.
   :type output_base: str
   :param resolution: Grid resolution for both-unstructured case.
   :type resolution: tuple, optional
   :param write_error: If False, skip writing error XDMF/H5 files (faster).
   :type write_error: bool