artist.core.core_utils
======================

.. py:module:: artist.core.core_utils


Functions
---------

.. autoapisummary::

   artist.core.core_utils.per_heliostat_reduction
   artist.core.core_utils.scale_loss


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

.. py:function:: per_heliostat_reduction(per_sample_values: torch.Tensor, active_heliostats_mask: torch.Tensor, device: torch.device | None = None) -> torch.Tensor

   Compute mean losses for each heliostat with multiple samples.

   If the active heliostats of one group have different amounts of samples to train on, i.e.,
   one heliostat is trained with more samples than another, this function makes sure that
   each heliostat still contributes equally to the overall loss of the group. This function
   computes the mean loss for each heliostat.

   Parameters
   ----------
   per_sample_values : torch.Tensor
       The per sample values to be reduced.
       Tensor of shape [number_of_samples].
   active_heliostats_mask : torch.Tensor
       A mask defining which heliostats are activated.
       Tensor of shape [number_of_heliostats].
   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 mean loss per heliostat.
       Tensor of shape [number_of_heliostats].


.. py:function:: scale_loss(loss: torch.Tensor, reference: torch.Tensor, weight: float) -> torch.Tensor

   Scale one loss so that its weighted contribution is a ratio of the reference loss.

   Parameters
   ----------
   loss : torch.Tensor
       The loss to be scaled.
       Tensor of shape [1].
   reference : torch.Tensor
       The reference loss.
       Tensor of shape [1].
   weight : float
       The weight or ratio used for the scaling.

   Returns
   -------
   torch.Tensor
       The scaled loss.
       Tensor of shape [1].