artist.scenario =============== .. py:module:: artist.scenario Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/artist/scenario/h5_scenario_generator/index /autoapi/artist/scenario/scenario/index /autoapi/artist/scenario/surface_generator/index Classes ------- .. autoapisummary:: artist.scenario.H5ScenarioGenerator artist.scenario.Scenario artist.scenario.SurfaceGenerator Package Contents ---------------- .. py:class:: H5ScenarioGenerator(file_path: pathlib.Path, power_plant_config: artist.util.config.PowerPlantConfig, target_area_list_planar_config: artist.util.config.TargetAreaPlanarListConfig, target_area_list_cylindrical_config: artist.util.config.TargetAreaCylindricalListConfig, light_source_list_config: artist.util.config.LightSourceListConfig, heliostat_list_config: artist.util.config.HeliostatListConfig, prototype_config: artist.util.config.PrototypeConfig, version: float = 1.0) Initialize the scenario generator. Scenarios in ``ARTIST`` describe the whole environment and all the components of a solar tower power plant. The scenario generator creates the scenarios. A scenario encompasses the tower target area(s), the light source(s), prototypes, and the heliostat(s). The generated scenarios are then saved in HDF5 files. Parameters ---------- file_path : pathlib.Path File path to the HDF5 to be saved. power_plant_config : PowerPlantConfig Power plant configuration object. target_area_list_planar_config : TargetAreaPlanarListConfig Planar target area list configuration object. target_area_list_cylindrical_config : TargetAreaCylindricalListConfig Cylindrical target area list configuration object. light_source_list_config : LightSourceListConfig Light source list configuration object. heliostat_list_config : HeliostatListConfig Heliostat_list configuration object. prototype_config : PrototypeConfig Prototype configuration object. version : float Version of the scenario generator being used (default is 1.0). .. py:attribute:: file_path .. py:attribute:: power_plant_config .. py:attribute:: target_area_list_planar_config .. py:attribute:: target_area_list_cylindrical_config .. py:attribute:: light_source_list_config .. py:attribute:: heliostat_list_config .. py:attribute:: prototype_config .. py:attribute:: version :value: 1.0 .. py:method:: _get_number_of_heliostat_groups() -> int Get the number of heliostat groups in the scenario. Returns ------- int Number of heliostat groups in the scenario. .. py:method:: _check_equal_facet_numbers() -> None Check that each heliostat has the same number of facets. Raises ------ ValueError If at least one heliostat has a different number of facets. .. py:method:: _flatten_dict(dictionary: collections.abc.MutableMapping[str, Any], parent_key: str = '', sep: str = '/') -> dict[str, Any] Flatten nested dictionaries to first-level keys. Parameters ---------- dictionary : MutableMapping[str, Any] Original nested dictionary to flatten. parent_key : str The parent key of nested dictionaries. Should be empty upon initialization. sep : str The separator used to separate keys in nested dictionaries. Returns ------- dict[str, Any] A flattened version of the original dictionary. .. py:method:: _flatten_dict_gen(d: collections.abc.MutableMapping[str, Any], parent_key: str, sep: str) -> collections.abc.Generator[tuple[str, Any], None, None] .. py:method:: _include_parameters(file: h5py.File, prefix: str, parameters: dict[str, Any]) -> None :staticmethod: Include the parameters from a parameter dictionary. Parameters ---------- file : h5py.File The HDF5 file to write to. prefix : str The prefix used for naming the parameters. parameters : dict[str, Any] The parameters to be included into the HDF5 file. .. py:method:: generate_scenario() -> None Generate the scenario and save it as an HDF5 file. .. py:class:: Scenario(power_plant_position: torch.Tensor, solar_tower: artist.field.solar_tower.SolarTower, light_sources: artist.scene.light_source_array.LightSourceArray, heliostat_field: artist.field.heliostat_field.HeliostatField) Initialize the scenario. A scenario defines the physical objects and scene to be used by ``ARTIST``. Therefore, a scenario contains at least one solar tower with at least one target area, at least one light source, and at least one heliostat in a heliostat field. ``ARTIST`` also supports scenarios that contain multiple target areas, multiple light sources, and multiple heliostats. Note that currently only a single light source can be provided. Parameters ---------- power_plant_position : torch.Tensor, Position of the power plant as latitude, longitude, and altitude. Shape is ``[3]``. solar_tower : SolarTower Solar tower with all target areas. light_sources : LightSourceArray Light sources included in the scenario. Currently, only a single light source can be provided. heliostat_field : HeliostatField Field of heliostats included in the scenario. .. py:attribute:: power_plant_position .. py:attribute:: solar_tower .. py:attribute:: light_sources .. py:attribute:: heliostat_field .. py:method:: get_number_of_heliostat_groups_from_hdf5(scenario_path: pathlib.Path) -> int :staticmethod: Get the number of heliostat groups to initiate distributed setup from the HDF5 scenario file. Parameters ---------- scenario_path : pathlib.Path File path to the HDF5 scenario file. Returns ------- int Number of heliostat groups to initiate distributed setup. .. py:method:: load_scenario_from_hdf5(scenario_file: h5py.File, number_of_surface_points_per_facet: torch.Tensor = torch.tensor([50, 50]), change_number_of_control_points_per_facet: torch.Tensor | None = None, device: torch.device | None = None) -> Self :classmethod: Class method to load the scenario from an HDF5 file. Parameters ---------- scenario_file : h5py.File The config file containing all the information about the scenario being loaded. number_of_surface_points_per_facet : torch.Tensor The number of sampling points along each direction of each 2D facet (default is torch.tensor([50,50])). Shape is ``[2]``. change_number_of_control_points_per_facet : torch.Tensor | None The updated number of control points along each direction of each 2D facet (default is None). Providing this parameter should be done with caution. In a scenario with surfaces generated by deflectometry, this parameter should be None, otherwise the deflectometry surface will be overwritten and become ideal. For ideal surfaces, this parameter can be used to change the number of control points specified in the .h5 scenario. Shape is ``[2]``. 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 ------- Scenario The ``ARTIST`` scenario loaded from the HDF5 file. .. py:method:: index_mapping(heliostat_group: artist.field.heliostat_group.HeliostatGroup, string_mapping: list[tuple[str, str, torch.Tensor]] | None = None, single_incident_ray_direction: torch.Tensor | None = None, single_target_area_index: int = 0, device: torch.device | None = None) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor] Create an index mapping from heliostat names, target area names and incident ray directions. If no mapping is provided, a default mapping for all heliostats within this group will be created. The default mapping will map all heliostats to the default ``single_incident_ray_direction``, which simulates a light source positioned in the south and the default ``single_target_area_index``, which is 0. To overwrite these defaults, please provide a ``single_incident_ray_direction`` or a ``single_target_area_index``. Parameters ---------- heliostat_group : HeliostatGroup Current heliostat group. string_mapping : list[tuple[str, str, torch.Tensor]] | None Map from heliostats to target areas and incident ray directions (default is None). single_incident_ray_direction : torch.Tensor Default incident ray direction (default is torch.tensor([0.0, 1.0, 0.0, 0.0])). Shape is ``[4]``. single_target_area_index : int Default target area index (default is 0). 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 Mask specifying which heliostat is selected and how many times. Shape is ``[number_of_heliostats_in_group]``. torch.Tensor Indices of target areas for all selected heliostats in order. Shape is ``[number_of_active_heliostats_in_group]``. torch.Tensor Incident ray directions for the selected heliostats in order. Shape is ``[number_of_active_heliostats_in_group, 4]``. .. py:method:: set_number_of_rays(number_of_rays: int) -> None Set the number of rays simulated by the light source. Parameters ---------- number_of_rays : int The new number of rays simulated by the light source. .. py:method:: __repr__() -> str Return a string representation of the scenario. .. py:class:: SurfaceGenerator(number_of_control_points: torch.Tensor = torch.tensor([10, 10]), degrees: torch.Tensor = torch.tensor([3, 3]), device: torch.device | None = None) Initialize the surface generator. Heliostat data, including information regarding their surfaces and structure, can be generated via ``STRAL`` and exported to a binary file or downloaded from ``PAINT``. The data formats are different depending on their source. To convert this data into a surface configuration format suitable for ``ARTIST``, this converter first loads the data and then learns or creates NURBS surfaces based on the data. Finally, the converter returns a list of facets that can be used directly in an ``ARTIST`` scenario. Parameters ---------- number_of_control_points : torch.Tensor The number of NURBS control points along each direction of each 2D facet (default is torch.tensor([10,10])). Tensor of shape [2]. degrees : torch.Tensor Degree of the NURBS along each direction of each 2D facet (default is torch.tensor([3,3])). Tensor of shape [2]. 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:: number_of_control_points .. py:attribute:: degrees .. py:method:: fit_nurbs(surface_points: torch.Tensor, surface_normals: torch.Tensor, optimizer: torch.optim.Optimizer, scheduler: torch.optim.lr_scheduler.LRScheduler | None = None, fit_method: str = constants.fit_nurbs_from_normals, tolerance: float = 1e-10, max_epoch: int = 400, device: torch.device | None = None) -> artist.nurbs.surfaces.NURBSSurfaces Fit a NURBS surface. The surface points are first normalized and shifted to the range (0,1) to be compatible with the knot vector of the NURBS surface. The NURBS surface is then initialized with the correct number of control points, degrees, and knots. The origin of the control points is set based on the width and height of the point cloud. The control points are then fitted to the surface points or surface normals using the provided optimizer. Parameters ---------- surface_points : torch.Tensor The surface points. Tensor of shape [number_of_surface_points, 4]. surface_normals : torch.Tensor The surface normals. Tensor of shape [number_of_surface_points, 4]. optimizer : torch.optim.Optimizer The optimizer. scheduler : torch.optim.lr_scheduler.LRScheduler | None The learning rate scheduler (default is None). fit_method : str The method used to fit the NURBS, either from deflectometry points or normals (default is constants.fit_nurbs_from_normals). tolerance : float The tolerance value used for fitting NURBS surfaces (default is 1e-10). max_epoch : int The maximum number of epochs for the NURBS fit (default is 400). 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 If the NURBS fit method is unknown. Returns ------- NURBSSurfaces A fitted NURBS surface. .. py:method:: generate_fitted_surface_config(heliostat_name: str, facet_translation_vectors: torch.Tensor, canting: torch.Tensor, surface_points_with_facets_list: list[torch.Tensor], surface_normals_with_facets_list: list[torch.Tensor], optimizer: torch.optim.Optimizer, scheduler: torch.optim.lr_scheduler.LRScheduler | None = None, deflectometry_step_size: int = 100, fit_method: str = constants.fit_nurbs_from_normals, tolerance: float = 1e-10, max_epoch: int = 400, device: torch.device | None = None) -> artist.util.config.SurfaceConfig Generate a fitted surface configuration. The fitted surface configuration is composed of separate facets. Each facet is defined by fitted control points, meaning the control points are fitted to measured point cloud or surface normals data. Initializing a surface from this configuration results in an imperfect heliostat surface with dents or bulges, reflecting real-world conditions. The surface can be fitted to deflectometry data or any other provided point cloud data. Parameters ---------- heliostat_name : str The heliostat name, used for logging. facet_translation_vectors : torch.Tensor Translation vectors for each facet from heliostat origin to relative position. Tensor of shape [number_of_facets, 4]. canting : torch.Tensor The canting vectors per facet in east and north directions Tensor of shape [number_of_facets, 2, 4]. surface_points_with_facets_list : list[torch.Tensor] A list of facetted surface points. Points per facet may vary. Tensors in list of shape [number_of_points, 3]. surface_normals_with_facets_list : list[torch.Tensor] A list of facetted surface normals. Points per facet may vary. Tensors in list of shape [number_of_points, 3]. optimizer : torch.optim.Optimizer The optimizer. scheduler : torch.optim.lr_scheduler.LRScheduler | None The learning rate scheduler (default is None). deflectometry_step_size : int The step size used to reduce the number of deflectometry points and normals for compute efficiency (default is 100). fit_method : str The method used to fit the NURBS, either from deflectometry points or normals (default is constants.fit_nurbs_from_normals). tolerance : float The tolerance value used for fitting NURBS surfaces (default is 1e-10). max_epoch : int The maximum number of epochs for the NURBS fit (default is 400). 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 ------- SurfaceConfig A surface configuration. .. py:method:: generate_ideal_surface_config(facet_translation_vectors: torch.Tensor, canting: torch.Tensor, device: torch.device | None = None) -> artist.util.config.SurfaceConfig Generate an ideal surface configuration. The ideal surface configuration is composed of separate facets. Each facet is defined by ideal control points, meaning the control points start as 3D points on a flat, equidistant grid around the origin. These control points are then canted (rotated) and translated to the facet positions. Initializing a surface from this configuration results in an ideal heliostat surface without dents or bulges but with canting. This ideal heliostat surface can be used as a starting point for a surface reconstruction based on measured flux distributions. Parameters ---------- facet_translation_vectors : torch.Tensor Translation vector for each facet from heliostat origin to relative position. Tensor of shape [number_of_facets, 4]. canting : torch.Tensor The canting vector per facet in east and north direction. Tensor of shape [number_of_facets, 2, 4]. 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 ------- SurfaceConfig A surface configuration.