Maintenance/docs and tutorials (#188)

Author: mcw92

README.md

@@ -2,7 +2,7 @@
 <img src="https://raw.githubusercontent.com/ARTIST-Association/ARTIST/main/logos/artist_logo.svg" alt="logo" width="500"/>
 </p>
 
-# AI-enhanced differentiable Ray Tracer for Irradiation Prediction in Solar Tower Digital Twins
+# AI-Enhanced Differentiable Ray Tracer for Irradiation Prediction in Solar Tower Digital Twins
 
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17381222.svg)](https://doi.org/10.5281/zenodo.17381222)
 ![PyPI](https://img.shields.io/pypi/v/artist-csp)
@@ -20,37 +20,47 @@
 
 ## What ``ARTIST`` can do for you
 
-The ``ARTIST`` package provides an implementation of a differentiable ray tracer using the `PyTorch` machine-learning
-framework in `Python`. Leveraging automatic differentiation and GPU computation, it facilitates the optimization of
-heliostats, towers, and camera parameters within a solar field by combining gradient-based optimization methods with
-smooth parametric descriptions of heliostats.
+The ``ARTIST`` package provides an implementation of a fully differentiable ray tracer using the ``PyTorch``
+machine-learning framework in ``Python``. Leveraging automatic differentiation and GPU computation, ``ARTIST`` enables
+gradient-based optimization within a differentiable solar tower power plant model using smooth parametric descriptions
+of heliostats. While the underlying framework is designed to support the optimization of arbitrary plant components,
+including towers and receivers, the current implementation focuses on data-driven heliostat surface reconstruction and
+alignment.
 
 **Our contributions include:**
 
-- **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.
+- **Efficient heliostat calibration:** ``ARTIST`` combines a differentiable geometric model of heliostat kinematics with
+  parallelized computation to enable efficient heliostat reconstruction from receiver flux measurements. This results in
+  a flexible and robust calibration approach.
 
-- **Surface reconstruction and flux density prediction:** Leveraging learning Non-Uniform Rational B-Splines (NURBS),
-  `ARTIST` reconstructs heliostat surfaces accurately using calibration images commonly available in solar thermal power plants.
-  Thus, we can achieve sub-millimeter accuracy in mirror reconstruction from focal spot images, contributing to improved
-  operational safety and efficiency. The reconstructed surfaces can be used for predicting unique heliostat flux densities
-  with state-of-the-art accuracy. Check out [this paper](https://doi.org/10.21203/rs.3.rs-2554998/v1) for more details.
+- **Accurate surface reconstruction and flux density prediction:** Leveraging learning Non-Uniform Rational B-Splines (NURBS),
+  `ARTIST` reconstructs heliostat surfaces accurately using calibration images commonly available in solar thermal power
+  plants. Thus, we can achieve sub-millimeter accuracy in mirror reconstruction from focal spot images, contributing to
+  improved operational safety and efficiency. The reconstructed surfaces can be used for predicting unique heliostat
+  flux densities with state-of-the-art accuracy. Check out [this paper](https://doi.org/10.1038/s41467-024-51019-z) for
+  more details:
 
-- **Immediate deployment**: `ARTIST` enables deployment at the beginning of a solar thermal plant's operation,
-  allowing for in situ calibration and subsequent improvements in energy efficiencies and cost reductions.
+  > M. Pargmann, J. Ebert, M. Götz et al. Automatic heliostat learning for in situ concentrating solar power plant
+  metrology with differentiable ray tracing. Nat Commun 15, 6997 (2024). https://doi.org/10.1038/s41467-024-51019-z
 
-- **Optimized flux density:** ``ARTIST`` enables flux density optimization across an entire heliostat field by optimizing
-  the motor positions of all heliostats to distribute the flux optimally over the receiver.
+- **Immediate deployment**: `ARTIST` can be deployed from the beginning of a solar thermal power plant's operation,
+  enabling in situ calibration and subsequent improvements in energy efficiency and cost reduction..
+
+- **Optimized flux density:** ``ARTIST`` enables flux density optimization across an entire heliostat field by adjusting
+  heliostat motor positions to obtain an optimal flux distribution on the receiver.
 
 
 ## Installation
-We heavily recommend installing the `ARTIST` package in a dedicated `Python3.10+` virtual environment. You can
-install ``ARTIST`` directly from the GitHub repository via:
+We recommend installing the `ARTIST` package in a dedicated `Python3.10+` virtual environment. You can install the
+latest stable release from [PyPI](https://pypi.org/project/artist-csp/):
+```bash
+pip install artist-csp
+```
+If you need the latest updates, you can also install ``ARTIST`` directly from the main branch via:
 ```bash
-pip install artist
+pip install git+https://github.com/ARTIST-Association/ARTIST.git
 ```
-Alternatively, you can install ``ARTIST`` locally. To achieve this, there are two steps you need to follow:
+To install `ARTIST` locally, there are two steps you need to follow:
 1. Clone the `ARTIST` repository:
    ```bash
    git clone https://github.com/ARTIST-Association/ARTIST.git
@@ -66,24 +76,24 @@ The ``ARTIST`` repository is structured as shown below:
 .
 ├── artist # Parent package
 │   ├── core # Core functionality of ARTIST, e.g. raytracing, optimizers etc.
-│   ├── data_loader # Deals with loading data into ARTIST from different sources.
-│   ├── field # Objects in the field, e.g. heliostats and target areas like receivers and calibration targets.
+│   ├── data_loader # Deals with loading data into ARTIST from different sources
+│   ├── field # Objects in the field, e.g. heliostats and target areas like receivers and calibration targets
 │   ├── scenario # Functionality to create and load scenarios in ARTIST.
-│   ├── scene # Light sources and factors influencing the surroundings.
+│   ├── scene # Light sources and factors influencing the surroundings
 │   └── util
 ├── tests
 │   ├── data
-│   │   ├── field_data # Real measurements from the PAINT database and STRAL that can be used in ARTIST.
-│   │   ├── scenarios # Scenarios describing an environment that can be loaded by ARTIST.
+│   │   ├── field_data # Real measurements from the PAINT database and STRAL that can be used in ARTIST
+│   │   ├── scenarios # Scenarios describing an environment that can be loaded by ARTIST
 │   │   └── ...
 │   ├── core
 │   ├── data_loader
 │   └── ...
-└── tutorials # Tutorials to help you get started with ARTIST.
-    ├── data # Data accessed in the tutorials.
-    │   ├── paint # Real measurements from the PAINT database.
-    │   ├── scenarios # Scenarios describing an environment that can be loaded by ARTIST.
-    │   └── stral Real # Measurements from STRAL.
+└── tutorials # Tutorials to help you get started with ARTIST
+    ├── data # Data accessed in the tutorials
+    │   ├── paint # Real measurements from the PAINT database
+    │   ├── scenarios # Scenarios describing an environment that can be loaded by ARTIST
+    │   └── stral Real # Measurements from STRAL
     └── ...
 ```
 

artist/core/heliostat_ray_tracer.py

@@ -370,7 +370,7 @@ def trace_rays(
         self,
         incident_ray_directions: torch.Tensor,
         active_heliostats_mask: torch.Tensor,
-        target_area_mask: torch.Tensor,
+        target_area_indices: torch.Tensor,
         ray_extinction_factor: float = 0.0,
         device: torch.device | None = None,
     ) -> torch.Tensor:
@@ -392,7 +392,7 @@ def trace_rays(
             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.
             Tensor of shape [number_of_heliostats].
-        target_area_mask : torch.Tensor
+        target_area_indices : torch.Tensor
             The indices of the target areas for each active heliostat.
             Tensor of shape [number_of_active_heliostats].
         ray_extinction_factor : float
@@ -467,7 +467,9 @@ def trace_rays(
                         active_heliostats_mask_batch
                     ],
                     target_areas=self.scenario.target_areas,
-                    target_area_mask=target_area_mask[active_heliostats_mask_batch],
+                    target_area_indices=target_area_indices[
+                        active_heliostats_mask_batch
+                    ],
                     device=device,
                 )
             )
@@ -534,7 +536,7 @@ def trace_rays(
                 intersections=intersections,
                 absolute_intensities=intensities,
                 active_heliostats_mask=active_heliostats_mask_batch,
-                target_area_mask=target_area_mask[active_heliostats_mask_batch],
+                target_area_indices=target_area_indices[active_heliostats_mask_batch],
                 device=device,
             )
 
@@ -602,7 +604,7 @@ def sample_bitmaps(
         intersections: torch.Tensor,
         absolute_intensities: torch.Tensor,
         active_heliostats_mask: torch.Tensor,
-        target_area_mask: torch.Tensor,
+        target_area_indices: torch.Tensor,
         device: torch.device | None = None,
     ) -> torch.Tensor:
         """
@@ -621,8 +623,8 @@ def sample_bitmaps(
         active_heliostats_mask : torch.Tensor
             Used to map bitmaps per heliostat to correct index.
             Tensor of shape [number_of_heliostats].
-        target_area_mask : torch.Tensor
-            The indices of target areas on which each heliostat is raytraced.
+        target_area_indices : torch.Tensor
+            The indices of target areas on which each heliostat is ray-traced.
             Tensor of shape [number_of_active_heliostats].
         device : torch.device | None
             The device on which to perform computations or load tensors and models (default is None).
@@ -644,28 +646,28 @@ def sample_bitmaps(
 
         # Extract widths and heights of target planes, along with corresponding centers in E and U direction.
         plane_widths = (
-            self.scenario.target_areas.dimensions[target_area_mask][
+            self.scenario.target_areas.dimensions[target_area_indices][
                 :, index_mapping.target_area_width
             ]
             .unsqueeze(index_mapping.number_rays_per_point)
             .unsqueeze(index_mapping.points_dimension)
         )
         plane_heights = (
-            self.scenario.target_areas.dimensions[target_area_mask][
+            self.scenario.target_areas.dimensions[target_area_indices][
                 :, index_mapping.target_area_height
             ]
             .unsqueeze(index_mapping.number_rays_per_point)
             .unsqueeze(index_mapping.points_dimension)
         )
         plane_centers_e = (
-            self.scenario.target_areas.centers[target_area_mask][
+            self.scenario.target_areas.centers[target_area_indices][
                 :, index_mapping.target_area_center_e
             ]
             .unsqueeze(index_mapping.number_rays_per_point)
             .unsqueeze(index_mapping.points_dimension)
         )
         plane_centers_u = (
-            self.scenario.target_areas.centers[target_area_mask][
+            self.scenario.target_areas.centers[target_area_indices][
                 :, index_mapping.target_area_center_u
             ]
             .unsqueeze(index_mapping.number_rays_per_point)
@@ -856,7 +858,7 @@ def sample_bitmaps(
     def get_bitmaps_per_target(
         self,
         bitmaps_per_heliostat: torch.Tensor,
-        target_area_mask: torch.Tensor,
+        target_area_indices: torch.Tensor,
         device: torch.device | None = None,
     ) -> torch.Tensor:
         """
@@ -867,7 +869,7 @@ def get_bitmaps_per_target(
         bitmaps_per_heliostat : torch.Tensor
             Bitmaps per heliostat.
             Tensor of shape [number_of_active_heliostats, bitmap_resolution_e, bitmap_resolution_u].
-        target_area_mask : torch.Tensor
+        target_area_indices : torch.Tensor
             The mapping from heliostat to target area.
             Tensor of shape [number_of_active_heliostats].
         device : torch.device | None
@@ -892,7 +894,7 @@ def get_bitmaps_per_target(
             device=device,
         )
         for index in range(self.scenario.target_areas.number_of_target_areas):
-            mask = target_area_mask == index
+            mask = target_area_indices == index
             if mask.any():
                 group_bitmaps_per_target[index] = bitmaps_per_heliostat[mask].sum(
                     dim=index_mapping.heliostat_dimension

artist/core/kinematics_reconstructor.py

@@ -202,7 +202,7 @@ def _reconstruct_kinematics_parameters_with_raytracing(
                 incident_ray_directions,
                 _,
                 active_heliostats_mask,
-                target_area_mask,
+                target_area_indices,
             ) = parser.parse_data_for_reconstruction(
                 heliostat_data_mapping=heliostat_mapping,
                 heliostat_group=heliostat_group,
@@ -266,7 +266,9 @@ def _reconstruct_kinematics_parameters_with_raytracing(
 
                     # Align heliostats.
                     heliostat_group.align_surfaces_with_incident_ray_directions(
-                        aim_points=self.scenario.target_areas.centers[target_area_mask],
+                        aim_points=self.scenario.target_areas.centers[
+                            target_area_indices
+                        ],
                         incident_ray_directions=incident_ray_directions,
                         active_heliostats_mask=active_heliostats_mask,
                         device=device,
@@ -291,7 +293,7 @@ def _reconstruct_kinematics_parameters_with_raytracing(
                     flux_distributions = ray_tracer.trace_rays(
                         incident_ray_directions=incident_ray_directions,
                         active_heliostats_mask=active_heliostats_mask,
-                        target_area_mask=target_area_mask,
+                        target_area_indices=target_area_indices,
                         device=device,
                     )
 
@@ -302,7 +304,7 @@ def _reconstruct_kinematics_parameters_with_raytracing(
                         ground_truth=focal_spots_measured[
                             sample_indices_for_local_rank
                         ],
-                        target_area_mask=target_area_mask[
+                        target_area_indices=target_area_indices[
                             sample_indices_for_local_rank
                         ],
                         reduction_dimensions=(index_mapping.focal_spots,),

artist/core/loss_functions.py

@@ -168,7 +168,7 @@ def __call__(
             Tensor of shape [number_of_samples, 4].
         \*\*kwargs : Any
             Keyword arguments.
-            The ``reduction_dimensions``, ``target_area_mask`` and ``device`` are expected keyword arguments for the focal spot loss.
+            The ``reduction_dimensions``, ``target_area_indices`` and ``device`` are expected keyword arguments for the focal spot loss.
 
         Raises
         ------
@@ -181,7 +181,7 @@ def __call__(
             The focal spot loss.
             Tensor of shape [number_of_samples].
         """
-        expected_kwargs = ["reduction_dimensions", "device", "target_area_mask"]
+        expected_kwargs = ["reduction_dimensions", "device", "target_area_indices"]
         errors = []
         for key in expected_kwargs:
             if key not in kwargs:
@@ -194,15 +194,15 @@ def __call__(
 
         device = get_device(device=kwargs["device"])
 
-        target_area_mask = kwargs["target_area_mask"]
+        target_area_indices = kwargs["target_area_indices"]
 
         focal_spot = utils.get_center_of_mass(
             bitmaps=prediction,
-            target_centers=self.scenario.target_areas.centers[target_area_mask],
-            target_widths=self.scenario.target_areas.dimensions[target_area_mask][
+            target_centers=self.scenario.target_areas.centers[target_area_indices],
+            target_widths=self.scenario.target_areas.dimensions[target_area_indices][
                 :, index_mapping.target_area_width
             ],
-            target_heights=self.scenario.target_areas.dimensions[target_area_mask][
+            target_heights=self.scenario.target_areas.dimensions[target_area_indices][
                 :, index_mapping.target_area_height
             ],
             device=device,
@@ -263,7 +263,7 @@ def __call__(
             Tensor of shape [number_of_samples, bitmap_resolution_e, bitmap_resolution_u].
         \*\*kwargs : Any
             Keyword arguments.
-            The ``reduction_dimensions``, ``target_area_mask`` and optionally ``device`` are expected keyword arguments for the pixel loss.
+            The ``reduction_dimensions``, ``target_area_indices`` and optionally ``device`` are expected keyword arguments for the pixel loss.
 
         Raises
         ------
@@ -276,7 +276,7 @@ def __call__(
             The summed MSE pixel loss reduced along the specified dimensions.
             Tensor of shape [number_of_samples].
         """
-        expected_kwargs = ["reduction_dimensions", "device", "target_area_mask"]
+        expected_kwargs = ["reduction_dimensions", "device", "target_area_indices"]
         errors = []
         for key in expected_kwargs:
             if key not in kwargs: