artist.core.surface_reconstructor
=================================

.. py:module:: artist.core.surface_reconstructor


Attributes
----------

.. autoapisummary::

   artist.core.surface_reconstructor.log


Classes
-------

.. autoapisummary::

   artist.core.surface_reconstructor.SurfaceReconstructor


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

.. py:data:: log

   A logger for the surface reconstructor.


.. py:class:: SurfaceReconstructor(ddp_setup: dict[str, Any], scenario: artist.scenario.scenario.Scenario, data: dict[str, artist.data_parser.calibration_data_parser.CalibrationDataParser | list[tuple[str, list[pathlib.Path], list[pathlib.Path]]]], optimization_configuration: dict[str, Any], number_of_surface_points: torch.Tensor = torch.tensor([50, 50]), bitmap_resolution: torch.Tensor = torch.tensor([256, 256]), device: torch.device | None = None)

   Initialize the surface reconstructor.

   Parameters
   ----------
   ddp_setup : dict[str, Any]
      Information about the distributed environment, process_groups, devices, ranks, world_Size, 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 and early stopping.
   number_of_surface_points : torch.Tensor
       The number of surface points of the reconstructed surfaces (default is torch.tensor([50,50])).
       Tensor of shape [2].
   bitmap_resolution : torch.Tensor
       The resolution of all bitmaps during reconstruction (default is torch.tensor([256,256])).
       Tensor of shape [2].
   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:: optimization_configuration


   .. py:attribute:: number_of_surface_points


   .. py:attribute:: bitmap_resolution


   .. py:method:: reconstruct_surfaces(loss_definition: artist.core.loss_functions.Loss, device: torch.device | None = None) -> torch.Tensor

      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 loss of the surface reconstruction for each heliostat in each group.
          Tensor of shape [total_number_of_heliostats_in_scenario].



   .. 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 gradients of the outer control points.
          Tensor of shape [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.
          Tensor of shape [number_of_active_heliostats, number_of_facets_per_surface, number_of_control_points_u_direction, number_of_control_points_v_direction, 3].