:py:mod:`FELiCS.IO.Mapping`
===========================

.. py:module:: FELiCS.IO.Mapping


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

Classes
~~~~~~~

.. autoapisummary::

   FELiCS.IO.Mapping.Mapping




Attributes
~~~~~~~~~~

.. autoapisummary::

   FELiCS.IO.Mapping.logger


.. py:data:: logger

   

.. py:class:: Mapping


   Utility class for constructing index mappings between FEM spaces or DOF coordinates.

   This class contains static methods that compute permutation arrays used to transfer
   values between meshes or finite element spaces with identical layouts but differing
   internal DOF orderings.

   **Initialize the Mapping object**

   This class is not intended to be instantiated; all functionality is provided through
   static methods.

   .. admonition:: Notes

      - The mapping assumes that input and output meshes have identical geometric DOF locations, possibly in different order.
      - Coordinates are rounded to 11 decimal places before comparison to avoid small floating-point inconsistencies.

   .. py:method:: calculateMappingFromSpaces(inputSpace, outputSpace)
      :staticmethod:

      Compute a DOF index mapping between two finite element spaces.

      This method extracts the coordinates of DOFs from both spaces and delegates the
      mapping computation to :meth:`calculateMappingFromDofs`.

      :param inputSpace: Finite element space providing the input DOF coordinates. Must implement
                         ``tabulate_dof_coordinates()``.
      :type inputSpace: :py:class:`object`
      :param outputSpace: Finite element space providing the output DOF coordinates. Must implement
                          ``tabulate_dof_coordinates()``.
      :type outputSpace: :py:class:`object`

      :returns: One-dimensional array of indices such that ``output[index] = input[mapping[index]]``.
      :rtype: :py:class:`numpy.ndarray`

      :raises ValueError: If the DOF coordinate arrays from the two spaces are incompatible in dimension.


   .. py:method:: calculateMappingFromDofs(inputDofs, outputDofs)
      :staticmethod:

      Compute a DOF index mapping from coordinate arrays.

      The algorithm constructs a bijection between two sets of DOF coordinates by:
      1. Copying the coordinate arrays,
      2. Appending the original DOF indices,
      3. Sorting by spatial coordinates,
      4. Aligning sorted entries,
      5. Extracting the permutation that maps input DOFs to output DOFs.

      :param inputDofs: Array of shape ``(n_dofs, dim)`` containing input DOF coordinates.
      :type inputDofs: :py:class:`numpy.ndarray`
      :param outputDofs: Array of shape ``(n_dofs, dim)`` containing output DOF coordinates.
      :type outputDofs: :py:class:`numpy.ndarray`

      :returns: One-dimensional integer array representing the mapping from input DOF indices
                to output DOF indices.
      :rtype: :py:class:`numpy.ndarray`

      :raises ValueError: If the coordinate arrays have different lengths or incompatible shapes.

      .. admonition:: Notes

         - Coordinates are rounded to 11 decimal places before matching.
         - The mapping requires exact geometric correspondence of DOFs between input and
           output meshes.