pr updates

Author: MarleneBusch

README.md

@@ -27,7 +27,7 @@ smooth parametric descriptions of heliostats.
 
 **Our contributions include:**
 
-- **Efficient heliostat calibration:** We develop a parallelized geometric kinematic model that enables efficient
+- **Efficient heliostat calibration:** We develop a parallelized geometric kinematics model that enables efficient
     calibration via either ray tracing-based or motor position data. This offers a flexible and robust approach to
     heliostat calibration.
 

artist/core/__init__.py

@@ -5,15 +5,15 @@
     HeliostatRayTracer,
     RestrictedDistributedSampler,
 )
-from artist.core.kinematic_reconstructor import KinematicReconstructor
+from artist.core.kinematics_reconstructor import KinematicsReconstructor
 from artist.core.motor_position_optimizer import MotorPositionsOptimizer
 from artist.core.surface_reconstructor import SurfaceReconstructor
 
 __all__ = [
     "HeliostatRayTracer",
     "DistortionsDataset",
     "RestrictedDistributedSampler",
-    "KinematicReconstructor",
+    "KinematicsReconstructor",
     "SurfaceReconstructor",
     "MotorPositionsOptimizer",
 ]

artist/core/blocking.py

@@ -10,7 +10,6 @@
 def create_blocking_primitives_rectangle(
     blocking_heliostats_surface_points: torch.Tensor,
     blocking_heliostats_active_surface_points: torch.Tensor,
-    epsilon: float = 0.05,
     device: torch.device | None = None,
 ) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
     """
@@ -40,8 +39,6 @@ def create_blocking_primitives_rectangle(
     blocking_heliostats_active_surface_points : torch.Tensor
         The aligned surface points of all heliostats that might block other heliostats.
         Tensor of shape [number_of_heliostats, number_of_combined_surface_points_all_facets, 4].
-    epsilon : float
-        A small value (default is 0.05).
     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
@@ -263,6 +260,7 @@ def soft_ray_blocking_mask(
         A soft blocking mask.
         Shape is [number_of_blocking_primitives, number_of_rays, number_of_combined_surface_points_all_facets].
     """
+    # Dimensions [#heliostats, #rays, #surface_points, #blocking_primitives, 3D coordinates].
     ray_origins = ray_origins[:, None, :, None, :3]
     ray_directions = ray_directions[:, :, :, None, :3]
 
@@ -271,6 +269,7 @@ def soft_ray_blocking_mask(
     span_v = blocking_primitives_spans[None, None, None, :, 1, :3]
     blocking_primitives_normals = blocking_primitives_normals[None, None, None, :, :3]
 
+    # Solve the plane equation.
     denominator = torch.sum(ray_directions * blocking_primitives_normals, dim=-1)
     distances_to_blocking_planes = torch.sum(
         (corner_0 - ray_origins) * blocking_primitives_normals, dim=-1
@@ -408,14 +407,14 @@ def morton_codes(
     # Normalize coordinates to [0,1 - epsilon).
     spans = bounding_box_max - bounding_box_min
     spans[spans == 0] = 1.0
-    norm = (coordinates - bounding_box_min[None, :]) / spans[None, :]
-    norm = norm.clamp(0.0, 1.0 - epsilon)
+    coordinates_normed = (coordinates - bounding_box_min[None, :]) / spans[None, :]
+    coordinates_normed = coordinates_normed.clamp(0.0, 1.0 - epsilon)
 
     # Determine number of discrete positions along each axis (1024).
     scale = float(1 << bits)
 
     # Scale normalized coordinates to integer values from 0 to 1024.
-    qi = (norm * scale).to(torch.int64)
+    qi = (coordinates_normed * scale).to(torch.int64)
     xi = qi[:, 0].to(torch.int64)
     yi = qi[:, 1].to(torch.int64)
     zi = qi[:, 2].to(torch.int64)
@@ -573,7 +572,7 @@ def build_linear_bounding_volume_hierarchies(
     blocking_primitives_corners: torch.Tensor, device: torch.device | None = None
 ) -> dict[str, torch.Tensor]:
     """
-    Build linear bounding volume heirachies (LBVHs).
+    Build linear bounding volume hierarchies (LBVHs).
 
     Reference: Tero Karras. Maximizing Parallelism in the Construction of BVHs, Octrees, and k‑d Trees.
     In Proceedings of the Fourth ACM SIGGRAPH / Eurographics Symposium on High‑Performance Graphics (HPG 2012)
@@ -591,10 +590,10 @@ def build_linear_bounding_volume_hierarchies(
     Returns
     -------
     dict[str, torch.Tensor]
-        - left, right: Indices of the left and right child of each LBVH node (-1 if leave).
-        - aabb_min, aabb_max: axis aligned bounding boxes.
-        - is_leaf: boolean, indicating whether a node is a leaf node.
-        - primitive_index: indicates which primitives are contained.
+        - left, right: Indices of the left and right child of each LBVH node (-1 if leaf).
+        - aabb_min, aabb_max: Axis aligned bounding boxes.
+        - is_leaf: Boolean, indicating whether a node is a leaf node.
+        - primitive_index: Indicates which primitives are contained.
     """
     device = get_device(device=device)
 
@@ -627,8 +626,9 @@ def build_linear_bounding_volume_hierarchies(
     codes = morton_codes(coordinates=centroids, epsilon=1e-6, device=device)
     sorted_codes, sorted_primitive_indices = torch.sort(codes)
 
-    # Analyse similarities between Morton codes and determine the direction to the more similar Morton codes, in the sorted array: -1 = to the left, +1 = to the right.
-    # The similarity is evaluated by computing leading common prefix lengths for all neighboring pairs of Morton codes.
+    # Analyze similarities between Morton codes and determine the direction to the more similar Morton codes,
+    # in the sorted array: -1 = to the left, +1 = to the right. The similarity is evaluated by computing leading
+    # common prefix lengths for all neighboring pairs of Morton codes.
     if number_of_blocking_primitives > 1:
         lcp_right = longest_common_prefix(
             codes=sorted_codes,
@@ -654,10 +654,9 @@ def build_linear_bounding_volume_hierarchies(
         -torch.ones(number_of_blocking_primitives, dtype=torch.int64, device=device),
     )
 
-    # Find threshold (delta_min) for node expansion by determining how similar the next Morton code in the chosen direction is.
-    # Find the range of blocking primitives that share a common prefix larger than delta_min.
     # Find the contiguous range of Morton codes that belong together.
-    # In the exponential search (the step size doubles in each iteration), find the farthest index j along direction d[i] where LCP > delta_min[i].
+    # Find threshold (delta_min) for node expansion by determining how different the next Morton code in the direction of the less similar neighbor is.
+    # Find the range of blocking primitives that share a common prefix larger than delta_min.
     neighbor_indices = blocker_ids - direction_to_similar_codes
     mask_out_of_bounds = (neighbor_indices >= 0) & (
         neighbor_indices < number_of_blocking_primitives
@@ -673,16 +672,16 @@ def build_linear_bounding_volume_hierarchies(
         mask_out_of_bounds, delta_min, torch.full_like(delta_min, -1, device=device)
     )
 
-    max = (
+    # In the exponential search (the step size doubles in each iteration), find the farthest index j along direction d[i] where LCP > delta_min[i].
+    max_index = (
         math.ceil(math.log2(number_of_blocking_primitives))
         if number_of_blocking_primitives > 1
         else 1
     )
     farthest_expansion = torch.zeros(
         number_of_blocking_primitives, dtype=torch.int64, device=device
     )
-
-    for k in range(0, max + 1):
+    for k in range(0, max_index + 1):
         step = 1 << k
         candidate_indices = blocker_ids + direction_to_similar_codes * (
             farthest_expansion + step

artist/core/heliostat_ray_tracer.py

@@ -318,10 +318,14 @@ def __init__(
             )
             blocking_heliostat_surfaces_active_list = []
             for group in self.scenario.heliostat_field.heliostat_groups:
-                if group.active_heliostats_mask.sum() <= 0:
+                if group.active_heliostats_mask.sum() == 0:
                     blocking_heliostat_surfaces_active_list.append(
                         group.surface_points + group.positions.unsqueeze(1)
                     )
+                    log.warning(
+                        "Not all heliostat groups have been aligned yet."
+                        "Use unaligned, i.e., horizontal heliostats as approximated blocking planes in raytracing."
+                    )
                 if group.active_heliostats_mask.sum() > 0:
                     heliostat_mask = torch.cumsum(group.active_heliostats_mask, dim=0)
                     start_indices = heliostat_mask - group.active_heliostats_mask
@@ -423,6 +427,7 @@ def trace_rays(
         )
 
         if self.blocking_active:
+            # Compute the heliostat blocking primitives.
             (
                 blocking_primitives_corners,
                 blocking_primitives_spans,
@@ -485,6 +490,7 @@ def trace_rays(
                     number_of_heliostats, device=device
                 ).repeat_interleave(number_of_rays * number_of_points)
 
+                # Filter out the blocking primitives that are relevant for blocking.
                 filtered_blocking_primitive_indices = (
                     blocking.lbvh_filter_blocking_planes(
                         points_at_ray_origins=points_at_ray_origins,
@@ -497,7 +503,7 @@ def trace_rays(
                         device=device,
                     )
                 )
-
+                # Create the blocked ray mask based on the relevant blocking primitive indices.
                 if filtered_blocking_primitive_indices.numel() > 0:
                     blocked = blocking.soft_ray_blocking_mask(
                         ray_origins=self.heliostat_group.active_surface_points[

artist/core/kinematic_reconstructor.py artist/core/kinematics_reconstructor.pyartist/core/kinematic_reconstructor.py renamed to artist/core/kinematics_reconstructor.py

@@ -18,14 +18,14 @@
 """A logger for the kinematic reconstructor."""
 
 
-class KinematicReconstructor:
+class KinematicsReconstructor:
     """
-    An optimizer used to reconstruct real-world kinematic deviation parameters.
+    An optimizer used to reconstruct real-world kinematics deviation parameters.
 
-    The kinematic reconstructor learns kinematic parameters. These parameters are
-    specific to a certain kinematic type and can for example include the four
-    kinematic rotation deviation parameters as well as the two initial actuator parameters
-    for each actuator of a rigid body kinematic.
+    The kinematics reconstructor learns kinematics parameters. These parameters are
+    specific to a certain kinematics type and can for example include the four
+    kinematics rotation deviation parameters as well as the two initial actuator parameters
+    for each actuator of a rigid body kinematics.
 
     Attributes
     ----------
@@ -48,8 +48,8 @@ class KinematicReconstructor:
 
     Methods
     -------
-    reconstruct_kinematic()
-        Reconstruct the kinematic parameters.
+    reconstruct_kinematics()
+        Reconstruct the kinematics parameters.
     """
 
     def __init__(
@@ -62,10 +62,10 @@ def __init__(
             | list[tuple[str, list[pathlib.Path], list[pathlib.Path]]],
         ],
         optimization_configuration: dict[str, Any],
-        reconstruction_method: str = config_dictionary.kinematic_reconstruction_raytracing,
+        reconstruction_method: str = config_dictionary.kinematics_reconstruction_raytracing,
     ) -> None:
         """
-        Initialize the kinematic optimizer.
+        Initialize the kinematics optimizer.
 
         Parameters
         ----------
@@ -82,7 +82,7 @@ def __init__(
         """
         rank = ddp_setup[config_dictionary.rank]
         if rank == 0:
-            log.info("Create a kinematic reconstructor.")
+            log.info("Create a kinematics reconstructor.")
 
         self.ddp_setup = ddp_setup
         self.scenario = scenario
@@ -92,15 +92,15 @@ def __init__(
 
         if (
             reconstruction_method
-            == config_dictionary.kinematic_reconstruction_raytracing
+            == config_dictionary.kinematics_reconstruction_raytracing
         ):
             self.reconstruction_method = reconstruction_method
         else:
             raise ValueError(
-                f"ARTIST currently only supports the {config_dictionary.kinematic_reconstruction_raytracing} reconstruction method. The reconstruction method {reconstruction_method} is not recognized. Please select another reconstruction method and try again!"
+                f"ARTIST currently only supports the {config_dictionary.kinematics_reconstruction_raytracing} reconstruction method. The reconstruction method {reconstruction_method} is not recognized. Please select another reconstruction method and try again!"
             )
 
-    def reconstruct_kinematic(
+    def reconstruct_kinematics(
         self,
         loss_definition: Loss,
         device: torch.device | None = None,
@@ -120,31 +120,31 @@ def reconstruct_kinematic(
         Returns
         -------
         torch.Tensor
-            The final loss of the kinematic reconstruction for each heliostat in each group.
+            The final loss of the kinematics reconstruction for each heliostat in each group.
             Tensor of shape [total_number_of_heliostats_in_scenario].
         """
         device = get_device(device=device)
 
         if (
             self.reconstruction_method
-            == config_dictionary.kinematic_reconstruction_raytracing
+            == config_dictionary.kinematics_reconstruction_raytracing
         ):
-            loss = self._reconstruct_kinematic_parameters_with_raytracing(
+            loss = self._reconstruct_kinematics_parameters_with_raytracing(
                 loss_definition=loss_definition,
                 device=device,
             )
 
         return loss
 
-    def _reconstruct_kinematic_parameters_with_raytracing(
+    def _reconstruct_kinematics_parameters_with_raytracing(
         self,
         loss_definition: Loss,
         device: torch.device | None = None,
     ) -> torch.Tensor:
         """
-        Reconstruct the kinematic parameters using ray tracing.
+        Reconstruct the kinematics parameters using ray tracing.
 
-        This reconstruction method optimizes the kinematic parameters by extracting the focal points
+        This reconstruction method optimizes the kinematics parameters by extracting the focal points
         of calibration images and using heliostat-tracing.
 
         Parameters
@@ -159,15 +159,15 @@ def _reconstruct_kinematic_parameters_with_raytracing(
         Returns
         -------
         torch.Tensor
-            The final loss of the kinematic reconstruction for each heliostat in each group.
+            The final loss of the kinematics reconstruction for each heliostat in each group.
             Tensor of shape [total_number_of_heliostats_in_scenario].
         """
         device = get_device(device=device)
 
         rank = self.ddp_setup[config_dictionary.rank]
 
         if rank == 0:
-            log.info("Beginning kinematic reconstruction with ray tracing.")
+            log.info("Beginning kinematics reconstruction with ray tracing.")
 
         final_loss_per_heliostat = torch.full(
             (self.scenario.heliostat_field.number_of_heliostats_per_group.sum(),),
@@ -214,8 +214,8 @@ def _reconstruct_kinematic_parameters_with_raytracing(
                 # Create the optimizer.
                 optimizer = torch.optim.Adam(
                     [
-                        heliostat_group.kinematic.rotation_deviation_parameters.requires_grad_(),
-                        heliostat_group.kinematic.actuators.optimizable_parameters.requires_grad_(),
+                        heliostat_group.kinematics.rotation_deviation_parameters.requires_grad_(),
+                        heliostat_group.kinematics.actuators.optimizable_parameters.requires_grad_(),
                     ],
                     lr=float(
                         self.optimizer_dict[config_dictionary.initial_learning_rate]
@@ -342,12 +342,12 @@ def _reconstruct_kinematic_parameters_with_raytracing(
                                     ]
 
                     torch.nn.utils.clip_grad_norm_(
-                        [heliostat_group.kinematic.rotation_deviation_parameters],
+                        [heliostat_group.kinematics.rotation_deviation_parameters],
                         max_norm=1.0,
                     )
 
                     torch.nn.utils.clip_grad_norm_(
-                        [heliostat_group.kinematic.actuators.optimizable_parameters],
+                        [heliostat_group.kinematics.actuators.optimizable_parameters],
                         max_norm=1.0,
                     )
 
@@ -391,7 +391,7 @@ def _reconstruct_kinematic_parameters_with_raytracing(
 
                 final_loss_per_heliostat[final_indices] = loss_per_heliostat
 
-                log.info(f"Rank: {rank}, Kinematic reconstructed.")
+                log.info(f"Rank: {rank}, Kinematics reconstructed.")
 
         if self.ddp_setup[config_dictionary.is_distributed]:
             for index, heliostat_group in enumerate(
@@ -401,17 +401,17 @@ def _reconstruct_kinematic_parameters_with_raytracing(
                     index
                 ]
                 torch.distributed.broadcast(
-                    heliostat_group.kinematic.rotation_deviation_parameters,
+                    heliostat_group.kinematics.rotation_deviation_parameters,
                     src=source[index_mapping.first_rank_from_group],
                 )
                 torch.distributed.broadcast(
-                    heliostat_group.kinematic.actuators.optimizable_parameters,
+                    heliostat_group.kinematics.actuators.optimizable_parameters,
                     src=source[index_mapping.first_rank_from_group],
                 )
             torch.distributed.all_reduce(
                 final_loss_per_heliostat, op=torch.distributed.ReduceOp.MIN
             )
 
-            log.info(f"Rank: {rank}, synchronized after kinematic reconstruction.")
+            log.info(f"Rank: {rank}, synchronized after kinematics reconstruction.")
 
         return final_loss_per_heliostat