artist.raytracing.heliostat_ray_tracer ====================================== .. py:module:: artist.raytracing.heliostat_ray_tracer Attributes ---------- .. autoapisummary:: artist.raytracing.heliostat_ray_tracer.log Classes ------- .. autoapisummary:: artist.raytracing.heliostat_ray_tracer.HeliostatRayTracer Module Contents --------------- .. py:data:: log A logger for the heliostat ray tracer. .. py:class:: HeliostatRayTracer(scenario: artist.scenario.scenario.Scenario, heliostat_group: artist.field.heliostat_group.HeliostatGroup, blocking_active: bool = True, world_size: int = 1, rank: int = 0, batch_size: int = 100, random_seed: int = 7, bitmap_resolution: torch.Tensor = torch.tensor([indices.bitmap_resolution, indices.bitmap_resolution]), dni: float | None = None) Initialize the heliostat ray tracer. "Heliostat"-tracing is one kind of ray tracing applied in ``ARTIST``. For this kind of ray tracing, the rays are initialized on the heliostats. The rays originate in the discrete surface points. There they are multiplied, distorted, and scattered, and then they are sent to the aim points. Letting the rays originate on the heliostats, drastically reduces the number of rays that need to be traced. Parameters ---------- scenario : Scenario The scenario used to perform ray tracing. heliostat_group : HeliostatGroup The selected heliostat group containing active heliostats. blocking_active : bool Flag indicating whether blocking is activated (default is True). world_size : int The world size, i.e., the overall number of processes (default is 1). rank : int The rank, i.e., individual process ID (default is 0). batch_size : int The number of samples (heliostats) processed in parallel within a single rank (default is 100). random_seed : int The random seed used for generating the distortions (default is 7). bitmap_resolution : torch.Tensor The resolution of the bitmap in both directions. (default is torch.tensor([256,256])). Shape is ``[2]``. dni : float | None Direct normal irradiance in W/m^2 (default is None -> ray magnitude = 1.0). .. py:attribute:: scenario .. py:attribute:: heliostat_group .. py:attribute:: blocking_active :value: True .. py:attribute:: world_size :value: 1 .. py:attribute:: rank :value: 0 .. py:attribute:: batch_size :value: 100 .. py:attribute:: light_source .. py:attribute:: distortions_dataset .. py:attribute:: distortions_sampler .. py:attribute:: distortions_loader .. py:attribute:: bitmap_resolution .. py:method:: get_sampler_indices() -> torch.Tensor Get the indices assigned to the current rank by the distributed sampler. Returns ------- torch.Tensor Indices of the distortions dataset that are assigned to this rank. Shape is ``[number_of_samples_assigned_to_current_rank]``. .. py:method:: trace_rays(incident_ray_directions: torch.Tensor, active_heliostats_mask: torch.Tensor, target_area_indices: torch.Tensor, ray_extinction_factor: float = 0.0, mirror_reflectivity: float = 0.935, device: torch.device | None = None) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor] Perform heliostat ray tracing. Scatter the rays according to the distortions, calculate the intersections with the target planes, and sample the resulting bitmaps on the target areas. The bitmaps are generated separately for each active heliostat and are accessed individually. If blocking is activated in the ``HeliostatRayTracer``, rays that are blocked by other heliostats are filtered out. Parameters ---------- incident_ray_directions : torch.Tensor The direction of the incident rays as seen from the heliostats. Shape is ``[number_of_active_heliostats, 4]``. active_heliostats_mask : torch.Tensor A mask where 0 indicates a deactivated heliostat and 1 an activated one. An integer greater than 1 indicates that this heliostat is regarded multiple times. Shape is ``[number_of_heliostats]``. target_area_indices : torch.Tensor The indices of the target areas for each active heliostat. Shape is ``[number_of_active_heliostats]``. ray_extinction_factor : float Amount of global ray extinction, responsible for shading (default is 0.0 -> no extinction). mirror_reflectivity : float Fraction of incident ray intensity reflected by the mirror surface (default is 0.935). 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 not all heliostats used for ray tracing have been aligned. Returns ------- torch.Tensor The resulting bitmaps per heliostat. Shape is ``[number_of_active_heliostats, bitmap_resolution_e, bitmap_resolution_u]``. torch.Tensor The fraction of rays hitting the target, neglecting blocking effects. Shape is ``[number_of_active_heliostats]``. torch.Tensor The fraction of rays not being blocked. Shape is ``[number_of_active_heliostats]``. torch.Tensor The fraction of rays actually hitting the target, taking into account blocking effects. Shape is ``[number_of_active_heliostats]``. .. py:method:: scatter_rays(distortion_u: torch.Tensor, distortion_e: torch.Tensor, original_ray_direction: torch.Tensor, device: torch.device | None = None) -> artist.scene.rays.Rays Scatter the reflected rays around the preferred ray directions for each heliostat. Parameters ---------- distortion_u : torch.Tensor The distortions in up direction (angles for scattering). Shape is ``[number_of_active_heliostats, number_of_rays, number_of_combined_surface_normals_all_facets]``. distortion_e : torch.Tensor The distortions in east direction (angles for scattering). Shape is ``[number_of_active_heliostats, number_of_rays, number_of_combined_surface_normals_all_facets]``. original_ray_direction : torch.Tensor The ray direction around which to scatter. Shape is ``[number_of_active_heliostats, number_of_combined_surface_normals_all_facets, 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 ------- Rays Scattered rays around the preferred reflection directions. .. py:method:: get_bitmaps_per_target(bitmaps_per_heliostat: torch.Tensor, target_area_indices: torch.Tensor, device: torch.device | None = None) -> torch.Tensor Transform bitmaps per heliostat to bitmaps per target area. Parameters ---------- bitmaps_per_heliostat : torch.Tensor Bitmaps per heliostat. Shape is ``[number_of_active_heliostats, bitmap_resolution_e, bitmap_resolution_u]``. target_area_indices : torch.Tensor The mapping from heliostat to target area. Shape is ``[number_of_active_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 Bitmaps per target area. Shape is ``[number_of_target_areas, bitmap_resolution_e, bitmap_resolution_u]``. .. py:method:: bilinear_splatting(bitmap_intersections_e: torch.Tensor, bitmap_intersections_u: torch.Tensor, absolute_intensities: torch.Tensor, device: torch.device | None) -> torch.Tensor Distribute ray intensities onto bitmap pixels using bilinear splatting. Each ray intersection with the target area is treated as a continuously positioned value between four neighboring discrete pixels (east/west and up/down neighbors). The intensity is split among these four pixels proportionally to their proximity to the intersection point, yielding a differentiable approximation of the discrete binning operation. Parameters ---------- bitmap_intersections_e : torch.Tensor The east-component bitmap coordinates of ray intersections. Shape is ``[number_of_active_heliostats, number_of_rays, number_of_surface_points]``. bitmap_intersections_u : torch.Tensor The up-component bitmap coordinates of ray intersections. Shape is ``[number_of_active_heliostats, number_of_rays, number_of_surface_points]``. absolute_intensities : torch.Tensor The intensity of each ray at its intersection point. Shape is ``[number_of_active_heliostats, number_of_rays, number_of_surface_points]``. device : torch.device | None The device on which to perform computations or load tensors and models. If None, ``ARTIST`` will automatically select the most appropriate device (CUDA or CPU) based on availability and OS. Returns ------- torch.Tensor The flux density bitmaps, one per active heliostat. Shape is ``[number_of_active_heliostats, bitmap_resolution_u, bitmap_resolution_e]``.