artist.optim.motor_position_optimizer

Attributes

log

A logger for the motor positions optimizer.

Classes

MotorPositionsOptimizer

Initialize the motor-positions optimizer.

Module Contents

artist.optim.motor_position_optimizer.log: A logger for the motor positions optimizer.

class artist.optim.motor_position_optimizer.MotorPositionsOptimizer(ddp_setup: artist.util.env.DdpSetup, scenario: artist.scenario.scenario.Scenario, optimization_configuration: dict[str, Any], incident_ray_direction: torch.Tensor, target_area_index: int, ground_truth: torch.Tensor, dni: float, bitmap_resolution: torch.Tensor = torch.tensor([256, 256]), epsilon: float = 1e-12, device: torch.device | None = None)

Initialize the motor-positions optimizer.

Parameters

ddp_setupDdpSetup: Information about the distributed environment, process groups, devices, ranks, world size, and heliostat-group-to-ranks mapping.
scenarioScenario: The scenario.
optimization_configurationdict[str, Any]: Parameters for the optimizer, learning rate scheduler, regularizers, and early stopping.
incident_ray_directiontorch.Tensor: Incident ray direction during the optimization. Shape is [4].
target_area_indexint: Index of the target used for the optimization.
ground_truthtorch.Tensor: Desired focal spot or distribution. Shape is [4] or [bitmap_resolution_e, bitmap_resolution_u].
dnifloat: Direct normal irradiance in W/m^2.
bitmap_resolutiontorch.Tensor: Resolution of all bitmaps during optimization (default is torch.tensor([256,256])). Shape is [2].
epsilonfloat: A small value to avoid division by zero (default is 1e-12).
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.

ddp_setup

scenario

optimizer_dict

scheduler_dict

constraint_dict

incident_ray_direction

target_area_index

ground_truth

dni

bitmap_resolution

epsilon = 1e-12

optimize(loss_definition: artist.optim.loss.Loss, device: torch.device | None = None) → tuple[torch.Tensor, dict[str, list], torch.Tensor, torch.Tensor, torch.Tensor]

Optimize the motor positions.

The motor positions are optimized through a reparameterization to ensure stable training across different heliostats with widely varying initial motor positions and ranges. Motor positions can range from 0 to up to ~80000. Instead of directly optimizing the absolute motor positions, which can differ in magnitudes, an unconstrained parameter is optimized. Directly optimizing the absolute motor positions would have very different effects depending on the scale of the motors. For small initial motor positions (e.g. ~100), a gradient update of size 10 may cause a ~10% relative change, drastically altering the motor positions of this heliostat. For large initial motor positions (e.g. ~50000), the same optimizer step would correspond to only a 0.02% relative change in motor positions, effectively freezing the optimization of this heliostat. This mismatch makes it impossible to choose a single learning rate that works robustly across all heliostats. Reparameterizing the motor positions to be optimized defines the optimizable parameter as:

\[\text{motor\_positions\_optimized} = \tanh( \text{torch.nn.Parameter(optimizable\_parameter)} )\]

The true motor positions can be reconstructed by:

\[\text{motor\_positions} = \text{initial\_motor\_positions} + \text{motor\_positions\_normalized} \cdot \text{scale}\]

where scale defines the range (e.g. up to ~80000) for adjustments. By optimizing reparameterized instead of raw motor positions, every heliostat sees updates of comparable relative magnitude, regardless of the absolute size of its motors positions.

Parameters

loss_definitionLoss: The definition of the loss function and pre-processing of the prediction.
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: Final loss of the motor position optimization.
dict[str, list]: Loss history over epochs, with keys "total_loss", "flux_loss", "local_flux_constraint", "intercept_constraint", "flux_integral_constraint", and "flux_integral". Each value is a list of per-epoch scalar floats.
torch.Tensor: Final intercept factors for each heliostat.
torch.Tensor: Final fraction of rays hitting the target, neglecting blocking effects, for each heliostat.
torch.Tensor: Final fraction of rays not being blocked, for each heliostat.