artist.optim.motor_position_optimizer
=====================================

.. py:module:: artist.optim.motor_position_optimizer


Attributes
----------

.. autoapisummary::

   artist.optim.motor_position_optimizer.log


Classes
-------

.. autoapisummary::

   artist.optim.motor_position_optimizer.MotorPositionsOptimizer


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

.. py:data:: log

   A logger for the motor positions optimizer.


.. py:class:: MotorPositionsOptimizer(ddp_setup: artist.util.env.DdpSetup, scenario: artist.scenario.scenario.Scenario, optimization_configuration: dict[str, Any], incident_ray_direction: torch.Tensor, target_area_index: int, ground_truth: torch.Tensor, dni: float, bitmap_resolution: torch.Tensor = torch.tensor([256, 256]), epsilon: float = 1e-12, device: torch.device | None = None)

   Initialize the motor-positions 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.
   optimization_configuration : dict[str, Any]
       Parameters for the optimizer, learning rate scheduler, regularizers, and early stopping.
   incident_ray_direction : torch.Tensor
       Incident ray direction during the optimization.
       Shape is ``[4]``.
   target_area_index : int
       Index of the target used for the optimization.
   ground_truth : torch.Tensor
       Desired focal spot or distribution.
       Shape is ``[4]`` or ``[bitmap_resolution_e, bitmap_resolution_u]``.
   dni : float
       Direct normal irradiance in W/m^2.
   bitmap_resolution : torch.Tensor
       Resolution of all bitmaps during optimization (default is ``torch.tensor([256,256])``).
       Shape is ``[2]``.
   epsilon : float
       A small value to avoid division by zero (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:: optimizer_dict


   .. py:attribute:: scheduler_dict


   .. py:attribute:: constraint_dict


   .. py:attribute:: incident_ray_direction


   .. py:attribute:: target_area_index


   .. py:attribute:: ground_truth


   .. py:attribute:: dni


   .. py:attribute:: bitmap_resolution


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



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

      Optimize the motor positions.

      The motor positions are optimized through a reparameterization to ensure stable training
      across different heliostats with widely varying initial motor positions and ranges. Motor
      positions can range from 0 to up to ~80000. Instead of directly optimizing the absolute
      motor positions, which can differ in magnitudes, an unconstrained parameter is optimized.
      Directly optimizing the absolute motor positions would have very different effects depending
      on the scale of the motors. For small initial motor positions (e.g. ~100), a gradient update
      of size 10 may cause a ~10% relative change, drastically altering the motor positions of this
      heliostat. For large initial motor positions (e.g. ~50000), the same optimizer step would
      correspond to only a 0.02% relative change in motor positions, effectively freezing the
      optimization of this heliostat. This mismatch makes it impossible to choose a single learning
      rate that works robustly across all heliostats.
      Reparameterizing the motor positions to be optimized defines the optimizable parameter as:

      .. math::

          \text{motor\_positions\_optimized} = \tanh(
              \text{torch.nn.Parameter(optimizable\_parameter)}
          )

      The true motor positions can be reconstructed by:

      .. math::

          \text{motor\_positions} = \text{initial\_motor\_positions} +
          \text{motor\_positions\_normalized} \cdot \text{scale}

      where scale defines the range (e.g. up to ~80000) for adjustments.
      By optimizing reparameterized instead of raw motor positions, every heliostat sees updates
      of comparable relative magnitude, regardless of the absolute size of its motors positions.

      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
          Final loss of the motor position optimization.
      dict[str, list]
          Loss history over epochs, with keys ``"total_loss"``, ``"flux_loss"``,
          ``"local_flux_constraint"``, ``"intercept_constraint"``, ``"flux_integral_constraint"``,
          and ``"flux_integral"``. Each value is a list of per-epoch scalar floats.
      torch.Tensor
          Final intercept factors for each heliostat.
      torch.Tensor
          Final fraction of rays hitting the target, neglecting blocking effects, for each heliostat.
      torch.Tensor
          Final fraction of rays not being blocked, for each heliostat.