artist.optim.kinematics_reconstructor
=====================================

.. py:module:: artist.optim.kinematics_reconstructor


Attributes
----------

.. autoapisummary::

   artist.optim.kinematics_reconstructor.log


Classes
-------

.. autoapisummary::

   artist.optim.kinematics_reconstructor.KinematicsReconstructor


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

.. py:data:: log

   A logger for the kinematic reconstructor.


.. py:class:: KinematicsReconstructor(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, reconstruction_method: str = constants.kinematics_reconstruction_raytracing, bitmap_resolution: torch.Tensor = torch.tensor([256, 256]))

   Initialize the kinematics optimizer.

   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]
       Parameters for the optimizer, learning rate scheduler, regularizers, and early stopping.
   dni : float | None
       Direct normal irradiance in W/m^2 (default is None which leads to a ray magnitude of 1.0).
   reconstruction_method : str
       The reconstruction method. Currently, only reconstruction via ray tracing is implemented.
   bitmap_resolution : torch.Tensor
       The resolution of all bitmaps during reconstruction (default is ``torch.tensor([256, 256])``).
       Shape is ``[2]``.


   .. py:attribute:: ddp_setup


   .. py:attribute:: scenario


   .. py:attribute:: data


   .. py:attribute:: optimizer_dict


   .. py:attribute:: scheduler_dict


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



   .. py:attribute:: bitmap_resolution


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

      Reconstruct the kinematic parameters.

      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 kinematics reconstruction for each heliostat in each group.
          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 key ``"total_loss"`` mapping to a list
          of per-epoch scalar loss values.
          In non-distributed mode, this is a single-rank container: ``[local_group_histories]``.



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

      Reconstruct the kinematics parameters using ray tracing.

      This reconstruction method optimizes the kinematics parameters by extracting the focal points
      of calibration images and using heliostat-tracing.

      Parameters
      ----------
      loss_definition : Loss
          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 kinematics reconstruction for each heliostat in each group.
          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 key ``"total_loss"`` mapping to a list
          of per-epoch scalar loss values.
          In non-distributed mode, this is a single-rank container: ``[local_group_histories]``.