artist.scenario

Submodules

Classes

`H5ScenarioGenerator`	Initialize the scenario generator.
`Scenario`	Initialize the scenario.
`SurfaceGenerator`	Initialize the surface generator.

Package Contents

class artist.scenario.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_pathpathlib.Path: File path to the HDF5 to be saved.
power_plant_configPowerPlantConfig: Power plant configuration object.
target_area_list_planar_configTargetAreaPlanarListConfig: Planar target area list configuration object.
target_area_list_cylindrical_configTargetAreaCylindricalListConfig: Cylindrical target area list configuration object.
light_source_list_configLightSourceListConfig: Light source list configuration object.
heliostat_list_configHeliostatListConfig: Heliostat_list configuration object.
prototype_configPrototypeConfig: Prototype configuration object.
versionfloat: Version of the scenario generator being used (default is 1.0).

file_path

power_plant_config

target_area_list_planar_config

target_area_list_cylindrical_config

light_source_list_config

heliostat_list_config

prototype_config

version = 1.0

_get_number_of_heliostat_groups() → int

Get the number of heliostat groups in the scenario.

Returns

int: Number of heliostat groups in the scenario.

_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.

_flatten_dict(dictionary: collections.abc.MutableMapping[str, Any], parent_key: str = '', sep: str = '/') → dict[str, Any]

Flatten nested dictionaries to first-level keys.

Parameters

dictionaryMutableMapping[str, Any]: Original nested dictionary to flatten.
parent_keystr: The parent key of nested dictionaries. Should be empty upon initialization.
sepstr: The separator used to separate keys in nested dictionaries.

Returns

dict[str, Any]: A flattened version of the original dictionary.

_flatten_dict_gen(d: collections.abc.MutableMapping[str, Any], parent_key: str, sep: str) → collections.abc.Generator[tuple[str, Any], None, None]

static _include_parameters(file: h5py.File, prefix: str, parameters: dict[str, Any]) → None

Include the parameters from a parameter dictionary.

Parameters

fileh5py.File: The HDF5 file to write to.
prefixstr: The prefix used for naming the parameters.
parametersdict[str, Any]: The parameters to be included into the HDF5 file.

generate_scenario() → None: Generate the scenario and save it as an HDF5 file.

class artist.scenario.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_positiontorch.Tensor,: Position of the power plant as latitude, longitude, and altitude. Shape is [3].
solar_towerSolarTower: Solar tower with all target areas.
light_sourcesLightSourceArray: Light sources included in the scenario. Currently, only a single light source can be provided.
heliostat_fieldHeliostatField: Field of heliostats included in the scenario.

power_plant_position

solar_tower

light_sources

heliostat_field

static get_number_of_heliostat_groups_from_hdf5(scenario_path: pathlib.Path) → int

Get the number of heliostat groups to initiate distributed setup from the HDF5 scenario file.

Parameters

scenario_pathpathlib.Path: File path to the HDF5 scenario file.

Returns

int: Number of heliostat groups to initiate distributed setup.

classmethod 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

Class method to load the scenario from an HDF5 file.

Parameters

scenario_fileh5py.File: The config file containing all the information about the scenario being loaded.
number_of_surface_points_per_facettorch.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_facettorch.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].
devicetorch.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.

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_groupHeliostatGroup: Current heliostat group.
string_mappinglist[tuple[str, str, torch.Tensor]] | None: Map from heliostats to target areas and incident ray directions (default is None).
single_incident_ray_directiontorch.Tensor: Default incident ray direction (default is torch.tensor([0.0, 1.0, 0.0, 0.0])). Shape is [4].
single_target_area_indexint: Default target area index (default is 0).
devicetorch.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].

set_number_of_rays(number_of_rays: int) → None

Set the number of rays simulated by the light source.

Parameters

number_of_raysint: The new number of rays simulated by the light source.

__repr__() → str: Return a string representation of the scenario.

class artist.scenario.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_pointstorch.Tensor: The number of NURBS control points along each direction of each 2D facet (default is torch.tensor([10,10])). Tensor of shape [2].
degreestorch.Tensor: Degree of the NURBS along each direction of each 2D facet (default is torch.tensor([3,3])). Tensor of shape [2].
devicetorch.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.

number_of_control_points

degrees

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_pointstorch.Tensor: The surface points. Tensor of shape [number_of_surface_points, 4].
surface_normalstorch.Tensor: The surface normals. Tensor of shape [number_of_surface_points, 4].
optimizertorch.optim.Optimizer: The optimizer.
schedulertorch.optim.lr_scheduler.LRScheduler | None: The learning rate scheduler (default is None).
fit_methodstr: The method used to fit the NURBS, either from deflectometry points or normals (default is constants.fit_nurbs_from_normals).
tolerancefloat: The tolerance value used for fitting NURBS surfaces (default is 1e-10).
max_epochint: The maximum number of epochs for the NURBS fit (default is 400).
devicetorch.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.

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_namestr: The heliostat name, used for logging.
facet_translation_vectorstorch.Tensor: Translation vectors for each facet from heliostat origin to relative position. Tensor of shape [number_of_facets, 4].
cantingtorch.Tensor: The canting vectors per facet in east and north directions Tensor of shape [number_of_facets, 2, 4].
surface_points_with_facets_listlist[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_listlist[torch.Tensor]: A list of facetted surface normals. Points per facet may vary. Tensors in list of shape [number_of_points, 3].
optimizertorch.optim.Optimizer: The optimizer.
schedulertorch.optim.lr_scheduler.LRScheduler | None: The learning rate scheduler (default is None).
deflectometry_step_sizeint: The step size used to reduce the number of deflectometry points and normals for compute efficiency (default is 100).
fit_methodstr: The method used to fit the NURBS, either from deflectometry points or normals (default is constants.fit_nurbs_from_normals).
tolerancefloat: The tolerance value used for fitting NURBS surfaces (default is 1e-10).
max_epochint: The maximum number of epochs for the NURBS fit (default is 400).
devicetorch.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.

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_vectorstorch.Tensor: Translation vector for each facet from heliostat origin to relative position. Tensor of shape [number_of_facets, 4].
cantingtorch.Tensor: The canting vector per facet in east and north direction. Tensor of shape [number_of_facets, 2, 4].
devicetorch.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.