artist.optim.surface_reconstructor
==================================

.. py:module:: artist.optim.surface_reconstructor


Attributes
----------

.. autoapisummary::

   artist.optim.surface_reconstructor.log


Classes
-------

.. autoapisummary::

   artist.optim.surface_reconstructor.SurfaceReconstructor


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

.. py:data:: log

   A logger for the surface reconstructor.


.. py:class:: SurfaceReconstructor(ddp_setup: artist.util.env.DdpSetup, scenario: artist.scenario.scenario.Scenario, data: dict[str, artist.io.calibration_parser.CalibrationDataParser | list[tuple[str, list[pathlib.Path], list[pathlib.Path]]]], optimization_configuration: dict[str, Any], dni: float | None = None, number_of_surface_points: torch.Tensor = torch.tensor([50, 50]), bitmap_resolution: torch.Tensor = torch.tensor([256, 256]), epsilon: float | None = 1e-12, device: torch.device | None = None)

   Initialize the surface reconstructor.

   Parameters
   ----------
   ddp_setup : DdpSetup
       Information about the distributed environment, process groups, devices, ranks, world size,
       and heliostat-group-to-ranks mapping.
   scenario : Scenario
       The scenario.
   data : dict[str, CalibrationDataParser | list[tuple[str, list[pathlib.Path], list[pathlib.Path]]]]
       The data parser and the mapping of heliostat name and calibration data.
   optimization_configuration : dict[str, Any]
       The parameters for the optimizer, learning rate scheduler, early stopping, and constraints.
   dni : float | None
       Direct normal irradiance in W/m² used to scale the ray-traced flux (default is None).
       If None, the ``HeliostatRayTracer`` uses its own default.
   number_of_surface_points : torch.Tensor
       The number of surface points of the reconstructed surfaces (default is ``torch.tensor([50, 50])``).
       Shape is ``[2]``.
   bitmap_resolution : torch.Tensor
       The resolution of all bitmaps during reconstruction (default is ``torch.tensor([256, 256])``).
       Shape is ``[2]``.
   epsilon : float | None
       Small numerical offset used to avoid division by zero in the energy constraint (default is 1e-12).
   device : torch.device | None
       The device on which to perform computations or load tensors and models (default is None).
       If None, ``ARTIST`` will automatically select the most appropriate
       device (CUDA or CPU) based on availability and OS.


   .. py:attribute:: ddp_setup


   .. py:attribute:: scenario


   .. py:attribute:: data


   .. py:attribute:: optimizer_dict


   .. py:attribute:: scheduler_dict


   .. py:attribute:: constraint_dict


   .. py:attribute:: number_of_surface_points


   .. py:attribute:: dni
      :value: None



   .. py:attribute:: bitmap_resolution


   .. py:attribute:: epsilon
      :value: 1e-12



   .. py:method:: reconstruct_surfaces(loss_definition: artist.optim.loss.Loss, device: torch.device | None = None) -> tuple[torch.Tensor, list[list[dict[str, list[float]]]]]

      Reconstruct NURBS surfaces from bitmaps.

      Parameters
      ----------
      loss_definition : Loss
          The definition of the loss function and pre-processing of the prediction.
      device : torch.device | None
          The device on which to perform computations or load tensors and models (default is None).
          If None, ``ARTIST`` will automatically select the most appropriate
          device (CUDA or CPU) based on availability and OS.

      Returns
      -------
      torch.Tensor
          The final reconstruction loss per heliostat, one entry per heliostat in the scenario.
          Shape is ``[total_number_of_heliostats_in_scenario]``.
      list[list[dict[str, list[float]]]]
          Loss histories over epochs grouped by rank.

          - Outer list: one entry per rank.
          - Inner list: one entry per heliostat group processed on that rank.
          - Each group entry is a dict with keys:
            ``"total_loss"``, ``"flux_loss"``, ``"smoothness_regularizer"``,
            ``"ideal_regularizer"``, ``"flux_integral"``, and
            ``"flux_integral_constraint"``.
            Each value is a list of per-epoch scalar floats.

            In non-distributed mode, this is a single-rank container: ``[local_group_histories]``.



   .. py:method:: lock_control_points_on_outer_edges(gradients: torch.Tensor, device: torch.device | None = None) -> torch.Tensor
      :staticmethod:


      Lock the u and v values of the control points on the outer edges of each facet.

      As the knots of the first and last knots on each facet have full multiplicity, the
      NURBS surfaces all start and end in control points. If the outer control points
      are not fixed in their u and v values, the reconstructed surfaces may not be
      rectangular anymore. To keep them rectangular, this function zeros the gradients
      of the u and v coordinates of all outer control points.

      Parameters
      ----------
      gradients : torch.Tensor
          The full control point gradient tensor for all active heliostats. Gradients on the
          outer edges will be zeroed; interior gradients are returned unchanged.
          Shape is ``[number_of_active_heliostats, number_of_facets_per_surface, number_of_control_points_u_direction, number_of_control_points_v_direction, 3]``.
      device : torch.device | None
          The device on which to perform computations or load tensors and models (default is None).
          If None, ``ARTIST`` will automatically select the most appropriate
          device (CUDA or CPU) based on availability and OS.

      Returns
      -------
      torch.Tensor
          The updated gradients.
          Shape is ``[number_of_active_heliostats, number_of_facets_per_surface, number_of_control_points_u_direction, number_of_control_points_v_direction, 3]``.