artist.scene.sun
================

.. py:module:: artist.scene.sun


Attributes
----------

.. autoapisummary::

   artist.scene.sun.log


Classes
-------

.. autoapisummary::

   artist.scene.sun.Sun


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

.. py:data:: log

   A logger for the sun.


.. py:class:: Sun(number_of_rays: int, distribution_parameters: dict[str, Any] = dict(distribution_type='normal', mean=0.0, covariance=4.3681e-06), device: torch.device | None = None)

   Bases: :py:obj:`artist.scene.light_source.LightSource`


   Initialize the sun as a light source.

   The sun is one type of light source that can be implemented in ``ARTIST``. The number of rays sent out by the
   light source per heliostat surface point must be specified. If more rays are sent out, the resulting flux
   density distribution on the receiver is higher. Furthermore, each light source also implements the
   ``get_distortions`` function required to scatter the light.

   Parameters
   ----------
   number_of_rays : int
       The number of sent-out rays sampled from the sun distribution.
   distribution_parameters
       Parameters of the distribution used to model the sun.
   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.

   Raises
   ------
   ValueError
       If the specified distribution type is unknown.


   .. py:attribute:: distribution_parameters


   .. py:attribute:: number_of_rays


   .. py:method:: from_hdf5(config_file: h5py.File, light_source_name: str | None = None, device: torch.device | None = None) -> typing_extensions.Self
      :classmethod:


      Class method that initializes a sun from an HDF5 file.

      Parameters
      ----------
      config_file : h5py.File
          The HDF5 file containing the information about the sun.
      light_source_name : str | None
          The name of the light source - used for logging.
      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
      -------
      Sun
          A sun initialized from an HDF5 file.



   .. py:method:: get_distortions(number_of_points: int, number_of_heliostats: int, random_seed: int = 7) -> tuple[torch.Tensor, torch.Tensor]

      Get distortions given the selected model of the sun.

      Parameters
      ----------
      number_of_points : int
          The number of points on the heliostat from which rays are reflected.
      number_of_facets : int
          The number of facets for each heliostat (default: 4).
      number_of_heliostats : int
          The number of heliostats in the scenario (default: 1).
      random_seed : int
          The random seed to enable result replication (default: 7).

      Returns
      -------
      tuple[torch.Tensor, torch.Tensor]
          The distortion in north and up direction.