Skip to content

Commit 1661ab1

Browse files
committed
Merge branch 'features/blocking' of github.com:ARTIST-Association/ARTIST into features/blocking
2 parents 062ea89 + 8f3059a commit 1661ab1

11 files changed

Lines changed: 43 additions & 43 deletions

artist/core/motor_position_optimizer.py

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -20,14 +20,14 @@ class MotorPositionsOptimizer:
2020
"""
2121
An optimizer used to find optimal motor positions for the heliostats.
2222
23-
The optimization loss is defined by the loss between the combined predicted and target
24-
flux densities. Additionally there is one constraint that maximizes the flux integral and
25-
one that constraints the maximum pixel intensity (maximum allowed flux density).
23+
The optimization loss is defined as the loss between the combined predicted and target
24+
flux densities. Additionally, there is one constraint that maximizes the flux integral and
25+
one that constrains the maximum pixel intensity (maximum allowed flux density).
2626
2727
Attributes
2828
----------
2929
ddp_setup : dict[str, Any]
30-
Information about the distributed environment, process_groups, devices, ranks, world_Size, heliostat group to ranks mapping.
30+
Information about the distributed environment, process_groups, devices, ranks, world_size, heliostat group_to_ranks mapping.
3131
scenario : Scenario
3232
The scenario.
3333
optimizer_dict : dict[str, Any]

artist/core/surface_reconstructor.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,7 @@ def __init__(
9898
data : dict[str, CalibrationDataParser | list[tuple[str, list[pathlib.Path], list[pathlib.Path]]]]
9999
The data parser and the mapping of heliostat name and calibration data.
100100
optimization_configuration : dict[str, Any]
101-
The parameters for the optimizer, learning rate scheduler, early stopping and constraints.
101+
The parameters for the optimizer, learning rate scheduler, early stopping, and constraints.
102102
number_of_surface_points : torch.Tensor
103103
The number of surface points of the reconstructed surfaces (default is torch.tensor([50,50])).
104104
Tensor of shape [2].
@@ -543,7 +543,7 @@ def reconstruct_surfaces(
543543
f"Rank: {rank}, Epoch: {epoch}, Loss: {total_loss}, LR: {optimizer.param_groups[index_mapping.optimizer_param_group_0]['lr']}"
544544
)
545545

546-
# Early stopping when loss did not improve since a predefined number of epochs.
546+
# Early stopping when loss did not improve for a predefined number of epochs.
547547
stop = early_stopper.step(loss)
548548

549549
if stop:

artist/util/utils.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -726,14 +726,14 @@ def perform_canting(
726726
727727
Parameters
728728
----------
729-
canting_angles torch.Tensor
729+
canting_angles : torch.Tensor
730730
Canting angles.
731731
Tensor of shape [number_of_surfaces, number_of_facets, 2, 4].
732732
data : torch.Tensor
733733
Data to be canted.
734734
Tensor of shape [number_of_surfaces, number_of_facets, number_of_points_per_Facet, 4].
735735
inverse : bool
736-
Indicating the direction of the rotation. Use inverse=False for canting and inverse=True for decanting (default is False).
736+
Indicates the direction of the rotation. Use inverse=False for canting and inverse=True for decanting (default is False).
737737
device : torch.device | None
738738
The device on which to perform computations or load tensors and models (default is None).
739739
If None, ``ARTIST`` will automatically select the most appropriate

docs/tutorial_motor_position_optimization.rst

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -41,9 +41,9 @@ improve operation of the power plant. Therefore, we have to define the ground tr
4141
index_mapping.unbatched_bitmap_u
4242
) * e_trapezoid.unsqueeze(index_mapping.unbatched_bitmap_e)
4343
44-
For the motor position optimization the flux integral is essential as we usually want to maximize the energy on the receiver while optimally distributing the single heliostat fluxes.
45-
To simulate the energy on the receiver we need to assign meaningful magnitudes to each single ray. This is done by providing the ``dni`` parameter.
46-
The DNI is the insolation measured at a given location on Earth with a surface element perpendicular to the Sun's rays, excluding diffuse insolation.
44+
For the motor position optimization, the flux integral is essential as we usually want to maximize the energy on the receiver while optimally distributing the single heliostat fluxes.
45+
To simulate the energy on the receiver, we need to assign meaningful magnitudes to each single ray. This is done by providing the ``dni`` parameter.
46+
The DNI is the insolation measured at a given location on Earth with a surface element perpendicular to the sun's rays, excluding diffuse insolation.
4747
The DNI needs to be provided in W/m^2 and is then automatically converted to ray magnitudes.
4848
The DNI is a parameter in the ``MotorPositionsOptimizer``, as we will later see.
4949
You can pass a DNI directly into a ``HeliostatRayTracer`` anywhere else in ``ARTIST`` too, but in the previous two reconstructions it is not necessary.
@@ -59,7 +59,7 @@ Next we set the loss function as the ``KLDivergenceLoss``:
5959
6060
loss_definition = KLDivergenceLoss()
6161
62-
The ``KLDivergenceLoss`` measures how one probability distribution is different from a second, reference distribution. In
62+
The ``KLDivergenceLoss`` measures how one probability distribution is different from a second reference distribution. In
6363
this case the reference distribution is the trapezoid distribution, which we compare to the collective distribution
6464
generated by all heliostats in the scenario.
6565

@@ -105,10 +105,10 @@ specific use case. In this tutorial we define the following scheduler and optimi
105105
config_dictionary.constraints: constraint_dict,
106106
}
107107
108-
The optimization configuration is a combination of optimizer parameters, scheduler parameters and the learning constraints.
109-
For the motor position optimization we have two constraints. With ``rho_energy`` and ``lambda_lr`` we define the parameters for Augmented Lagrangian coefficients.
108+
The optimization configuration is a combination of optimizer parameters, scheduler parameters, and the learning constraints.
109+
For the motor position optimization, we have two constraints. With ``rho_energy`` and ``lambda_lr`` we define the parameters for Augmented Lagrangian coefficients.
110110
They enforce that the flux integral strives to maximize itself during the optimization.
111-
Furthermore there are the ``max_flux_density`` and ``rho_pixel`` parameters.
111+
Furthermore, there are the ``max_flux_density`` and ``rho_pixel`` parameters.
112112
They constrain the flux at the pixel level. The parameter ``max_flux_density`` defines the maximum allowable flux density per pixel.
113113
The parameter ``rho_pixel`` controls the strength of the penalty applied when this limit is exceeded.
114114
This is particularly important because, in a real power plant, the receiver is subject to strict safety limits on the allowable flux density. Exceeding this limit could lead to material damage.

docs/tutorial_surface_reconstruction.rst

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,7 @@ in the generated image individually.
102102
loss_definition = KLDivergenceLoss()
103103
104104
105-
Optimizer, Scheduler, Regularizer and Constraints Configuration
105+
Optimizer, Scheduler, Regularizer, and Constraints Configuration
106106
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
107107

108108
The surface reconstruction internally uses the ``torch.optim.Adam`` optimizer. Depending on the data you use, different
@@ -139,11 +139,11 @@ an cyclic or reduce on plateau scheduler:
139139
Regularizers are used to prevent overfitting and ensure that the reconstructed surface is smooth and similar to an ideal
140140
surface. In the surface reconstruction we consider two regularizers:
141141

142-
- ``IdealSurfaceRegularizer``: Pushes the reconstructed surface towards the shape of an ideal, perfectly flat or canted surface. The idea here, is that we know the general canting and shape of a flat surface and what is unknown is the minute deformations. Therefore, any dramatic changes should be avoided and in general the learnt surface should be similar to the ideal surface, apart from these minute deviations.
143-
- ``SmoothnessRegularizer``: This regularizer promotes smoothness by penalizing large gradients. The idea behind this regularize is that neighboring points on the surface should be similar, therefore very large differences between points is unrealistic. We apply this regularize to both the NURBS control points.
142+
- ``IdealSurfaceRegularizer``: Pushes the reconstructed surface towards the shape of an ideal, perfectly flat or canted surface. The idea here is that we know the general canting and shape of a flat surface and what is unknown is the minute deformations. Therefore, any dramatic changes should be avoided and in general the learned surface should be similar to the ideal surface, apart from these minute deviations.
143+
- ``SmoothnessRegularizer``: This regularizer promotes smoothness by penalizing large gradients. The idea behind this regularizer is that neighboring points on the surface should be similar, therefore very large differences between points is unrealistic. We apply this regularizer to both the NURBS control points.
144144

145145
These regularizers are initialized automatically within the ``SurfaceReconstructor``. We can adjust their influence by setting their weights inside the constraints dict.
146-
Weight of zero deactivate the regularizers completely.
146+
Weights of zero deactivate the regularizers completely.
147147

148148
.. code-block::
149149
@@ -155,12 +155,12 @@ Weight of zero deactivate the regularizers completely.
155155
config_dictionary.energy_tolerance: 0.01,
156156
}
157157
158-
As you can see, there are further parameters in the ``constraints`` dictionary than necessary for the two regularizers mentioned before. To further stabilize the reconstruction there is one additional constraints.
158+
As you can see, there are further parameters in the constraints dictionary that are not required for the two regularizers mentioned before. To further stabilize the reconstruction, there is one additional constraint.
159159
This constraint considers the flux integral of the raytraced flux images from the predicted surfaces. During reconstruction the flux integral may not change significantly.
160160
The parameters ``initial_lambda_energy`` and ``rho_energy`` are the Augmented Lagrangian coefficients used to enforce this energy conservation constraint.
161161
The multiplier ``lambda_energy`` represents the Lagrange multiplier associated with the energy integral constraint. It linearly penalizes violations and is updated iteratively during optimization based on the current constraint violation.
162162
If the predicted energy deviates from the reference energy, lambda increases, thereby strengthening the enforcement of the constraint in the next iteration.
163-
The parameter rho is the quadratic penalty weight. It controls how strongly deviations from the reference energy are penalized through the squared constraint term.
163+
The parameter ``rho_energy`` is the quadratic penalty weight. It controls how strongly deviations from the reference energy are penalized through the squared constraint term.
164164
The ``energy_tolerance`` describes how much the flux integral may vary relative to the initial surface.
165165
We can now define the combined optimization parameters in the ``optimization_configuration`` dictionary:
166166

examples/hyperparameter_optimization/generate_plots.py

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ def plot_kinematics_reconstruction_fluxes(
3232
Parameters
3333
----------
3434
reconstruction_results : dict[str, dict[str, Any]]
35-
A dictionary containing the reconstruction results.
35+
The reconstruction results.
3636
save_dir : pathlib.Path
3737
Directory used for saving the plot.
3838
"""
@@ -142,11 +142,11 @@ def plot_error_distribution(
142142
Parameters
143143
----------
144144
reconstruction_results : dict[str, dict[str, Any]]
145-
A dictionary containing the reconstruction results.
145+
The reconstruction results.
146146
save_dir : pathlib.Path
147147
Directory used for saving the plot.
148148
"""
149-
# Set Plot style.
149+
# Set plot style.
150150
plt.rcParams["text.usetex"] = True
151151
plt.rcParams["text.latex.preamble"] = r"\usepackage{cmbright}"
152152
plt.rcParams["text.latex.preamble"] = r"\setlength{\parindent}{0pt}"
@@ -156,7 +156,7 @@ def plot_error_distribution(
156156
data["loss"] for data in reconstruction_results["loss"].values()
157157
]
158158

159-
# Convert to angular error in mrad
159+
# Convert to angular error in mrad.
160160
positions = np.array(
161161
[data["position"] for data in reconstruction_results["loss"].values()],
162162
dtype=float,
@@ -222,7 +222,7 @@ def plot_linear_and_angular_error_against_distance(
222222
Parameters
223223
----------
224224
reconstruction_results : dict[str, dict[str, Any]]
225-
A dictionary containing the reconstruction results.
225+
The reconstruction results.
226226
number_of_points_to_plot : int
227227
Number of points to randomly select and plot.
228228
save_dir : pathlib.Path
@@ -320,7 +320,7 @@ def plot_motor_pos_fluxes(
320320
Parameters
321321
----------
322322
reconstruction_results : dict[str, dict[str, Any]]
323-
A dictionary containing the reconstruction results.
323+
The reconstruction results.
324324
save_dir : pathlib.Path
325325
Directory used for saving the plot.
326326
"""
@@ -345,7 +345,7 @@ def plot_motor_pos_fluxes(
345345
)
346346
axes = []
347347

348-
# Compute global min and max for shared color scale
348+
# Compute global min and max for shared color scale.
349349
all_flux_data = [
350350
reconstruction_results[key].cpu().detach()
351351
for key in ["flux_before", "flux_after", "target_distribution"]
@@ -374,8 +374,8 @@ def plot_motor_pos_fluxes(
374374
axes[1].set_title(r"\textbf{Aim Points Optimized}", fontsize=18, ha="center")
375375
axes[2].set_title(r"\textbf{Target Distribution}", fontsize=18, ha="center")
376376

377-
# Add a single horizontal colorbar beneath all subplots
378-
cbar_ax = fig.add_subplot(gs[1, :]) # spans all columns
377+
# Add a single horizontal colorbar beneath all subplots.
378+
cbar_ax = fig.add_subplot(gs[1, :]) # Spans all columns
379379
cbar = fig.colorbar(im, cax=cbar_ax, orientation="horizontal")
380380
cbar.ax.tick_params(labelsize=14)
381381

examples/hyperparameter_optimization/generate_results_kinematic.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,7 @@ def data_for_flux_plots(
102102
scenario : Scenario
103103
The scenario.
104104
ddp_setup : dict[str, Any]
105-
Information about the distributed environment, process_groups, devices, ranks, world_Size, heliostat group to ranks mapping.
105+
Information about the distributed environment, process_groups, devices, ranks, world_size, heliostat group to ranks mapping.
106106
heliostat_data : dict[str, CalibrationDataParser | list[tuple[str, list[pathlib.Path], list[pathlib.Path]]]]
107107
Heliostat and calibration measurement data.
108108
device : torch.device | None
@@ -113,7 +113,7 @@ def data_for_flux_plots(
113113
Returns
114114
-------
115115
dict[str, dict[str, torch.Tensor]]
116-
Dictionary containing kinematics data per heliostat.
116+
Kinematic data per heliostat.
117117
"""
118118
device = get_device(device)
119119

examples/hyperparameter_optimization/generate_results_motor_position.py

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@ def data_for_flux_plots(
7171
Returns
7272
-------
7373
dict[str, dict[str, torch.Tensor]]
74-
Dictionary containing kinematics data per heliostat.
74+
Kinematics data per heliostat.
7575
"""
7676
device = get_device(device)
7777

@@ -103,7 +103,7 @@ def data_for_flux_plots(
103103
device=device,
104104
)
105105

106-
# Align Heliostats.
106+
# Align heliostats.
107107
if id == "before":
108108
heliostat_group.align_surfaces_with_incident_ray_directions(
109109
aim_points=scenario.target_areas.centers[target_area_mask],
@@ -414,4 +414,4 @@ def generate_reconstruction_results(
414414
results_path.parent.mkdir(parents=True, exist_ok=True)
415415

416416
torch.save(optimization_results, results_path)
417-
print(f"Reconstruction results saved to {results_path}")
417+
print(f"Reconstruction results saved to {results_path}.")

examples/hyperparameter_optimization/generate_scenarios.py

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,7 @@ def find_heliostats(
8888
Parameters
8989
----------
9090
heliostat_properties_list : list[tuple[str, pathlib.Path]]
91-
List of heliostat names and paths.
91+
Heliostat names and paths.
9292
power_plant_position : torch.Tensor
9393
Tower position in WGS84.
9494
Tensor of shape [3].
@@ -166,7 +166,7 @@ def generate_ideal_scenario(
166166
tower_file_path : pathlib.Path
167167
Path to the tower measurements file.
168168
heliostat_properties_list : list[tuple[str, pathlib.Path]]
169-
List of heliostat names and their property files to include in the scenario.
169+
Heliostat names and their property files to include in the scenario.
170170
number_of_heliostats : int
171171
Number of heliostats to select.
172172
device : torch.device | None
@@ -177,7 +177,7 @@ def generate_ideal_scenario(
177177
Returns
178178
-------
179179
list[tuple[str, pathlib.Path]]
180-
List of selected heliostats.
180+
Selected heliostats.
181181
"""
182182
device = get_device(device=device)
183183

@@ -250,7 +250,7 @@ def generate_fitted_scenario(
250250
tower_file_path : pathlib.Path
251251
Path to the tower data file.
252252
selected_heliostats_list : list[tuple[str, pathlib.Path]],
253-
List of heliostat names to include in the scenario.
253+
Heliostat names to include in the scenario.
254254
device : torch.device | None
255255
The device on which to perform computations or load tensors and models (default is None).
256256
If None, ``ARTIST`` will automatically select the most appropriate

examples/hyperparameter_optimization/generate_viable_heliostats_list.py

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -48,9 +48,9 @@ def find_viable_heliostats(
4848
"""
4949
Find heliostats that have at least a minimum number of valid calibration files.
5050
51-
This function iterates through a data directory to find all heliostats having at least the minimum number of measurements
52-
calibration files. All paths are collected, and a sorted list of the heliostats is returned containing tuples including
53-
the heliostat name, path to the calibration file, and path to the flux images for surface and kinematics reconstruction.
51+
This function iterates through a data directory to find all heliostats having at least the minimum number of calibration
52+
measurement files. All paths are collected, and a sorted list of the heliostats is returned containing tuples including
53+
the heliostat name, path to the calibration file, and path to the flux images for surface and kinematic reconstruction.
5454
5555
Parameters
5656
----------

0 commit comments

Comments
 (0)