artist.scene ============ .. py:module:: artist.scene .. autoapi-nested-parse:: Bundle all classes that represent the scene in ``ARTIST``. Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/artist/scene/light_source/index /autoapi/artist/scene/light_source_array/index /autoapi/artist/scene/rays/index /autoapi/artist/scene/sun/index Classes ------- .. autoapisummary:: artist.scene.LightSource artist.scene.LightSourceArray artist.scene.Rays artist.scene.Sun Package Contents ---------------- .. py:class:: LightSource(number_of_rays: int) Initialize the light source. The abstract light source implements a template for the construction of light sources which can be of various types. The most noticeable light source is the sun, however, drones could carry artificial light sources and distribute this light on specific heliostats for calibration purposes. Currently, only the sun is implemented. Parameters ---------- number_of_rays : int The number of sent-out rays sampled from the sun distribution. .. 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: :abstractmethod: Load the light source from an HDF5 file. Parameters ---------- config_file : h5py.File The HDF5 file containing the information about the light sources. 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. Raises ------ NotImplementedError Whenever called (abstract base class method). .. py:method:: get_distortions(number_of_points: int, number_of_heliostats: int, random_seed: int = 7) -> tuple[torch.Tensor, torch.Tensor] :abstractmethod: Get distortions given the light source model. This function gets the distortions that are later used to model possible ray directions that are being generated from the light source. Depending on the model of the light source, the distortions are generated differently. 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). Raises ------ NotImplementedError Whenever called (abstract base class method). .. py:class:: LightSourceArray(light_source_list: collections.abc.Sequence[artist.scene.light_source.LightSource]) Initialize the light sources included in the considered scenario. The light source array bundles all light sources considered in the scenario. The light source sends out the rays that are then used for ray tracing. The position of the light sources can be dynamic throughout a time span. Parameters ---------- light_source_list : Sequence[LightSource] A list of light sources included in the scenario. .. py:attribute:: light_source_list .. py:method:: from_hdf5(config_file: h5py.File, device: torch.device | None = None) -> typing_extensions.Self :classmethod: Load a light source array from an HDF5 file. Parameters ---------- config_file : h5py.File The HDF5 file containing the configuration to be loaded. 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 ------- LightSourceArray The light source array loaded from the HDF5 file. .. py:class:: Rays(ray_directions: torch.Tensor, ray_magnitudes: torch.Tensor) Initialize the ``Rays`` class. The rays in ``ARTIST`` have a direction vector and a magnitude. They are used for ray tracing. The direction vector determines the direction of the rays, i.e., the path they are taking through space. The magnitude is important for considering atmospheric losses and cloud coverage. If a ray travels through a cloud, the magnitude changes. Parameters ---------- ray_directions : torch.Tensor The direction of the rays. Tensor of shape [number_of_active_heliostats, number_of_rays, number_of_combined_surface_normals_all_facets, 4]. ray_magnitudes : torch.Tensor The magnitudes of the rays. Tensor of shape [number_of_active_heliostats, number_of_rays, number_of_combined_surface_normals_all_facets]. Raises ------ ValueError If the shapes of the ray directions does not match the shapes of the ray magnitudes. .. 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.