artist.optim.surface_reconstructor

Attributes

log

A logger for the surface reconstructor.

Classes

SurfaceReconstructor

Initialize the surface reconstructor.

Module Contents

artist.optim.surface_reconstructor.log: A logger for the surface reconstructor.

class artist.optim.surface_reconstructor.SurfaceReconstructor(ddp_setup: artist.util.env.DdpSetup, scenario: artist.scenario.scenario.Scenario, data: dict[str, artist.io.calibration_parser.CalibrationDataParser | list[tuple[str, list[pathlib.Path], list[pathlib.Path]]]], optimization_configuration: dict[str, Any], dni: float | None = None, number_of_surface_points: torch.Tensor = torch.tensor([50, 50]), bitmap_resolution: torch.Tensor = torch.tensor([256, 256]), epsilon: float | None = 1e-12, device: torch.device | None = None)

Initialize the surface reconstructor.

Parameters

ddp_setupDdpSetup: Information about the distributed environment, process groups, devices, ranks, world size, and heliostat-group-to-ranks mapping.
scenarioScenario: The scenario.
datadict[str, CalibrationDataParser | list[tuple[str, list[pathlib.Path], list[pathlib.Path]]]]: The data parser and the mapping of heliostat name and calibration data.
optimization_configurationdict[str, Any]: The parameters for the optimizer, learning rate scheduler, early stopping, and constraints.
dnifloat | None: Direct normal irradiance in W/m² used to scale the ray-traced flux (default is None). If None, the HeliostatRayTracer uses its own default.
number_of_surface_pointstorch.Tensor: The number of surface points of the reconstructed surfaces (default is torch.tensor([50, 50])). Shape is [2].
bitmap_resolutiontorch.Tensor: The resolution of all bitmaps during reconstruction (default is torch.tensor([256, 256])). Shape is [2].
epsilonfloat | None: Small numerical offset used to avoid division by zero in the energy constraint (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

data

optimizer_dict

scheduler_dict

constraint_dict

number_of_surface_points

dni = None

bitmap_resolution

epsilon = 1e-12

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

Reconstruct NURBS surfaces from bitmaps.

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

The final reconstruction loss per heliostat, one entry per heliostat in the scenario. Shape is [total_number_of_heliostats_in_scenario].

list[list[dict[str, list[float]]]]

Loss histories over epochs grouped by rank.

Outer list: one entry per rank.
Inner list: one entry per heliostat group processed on that rank.
Each group entry is a dict with keys: "total_loss", "flux_loss", "smoothness_regularizer", "ideal_regularizer", "flux_integral", and "flux_integral_constraint". Each value is a list of per-epoch scalar floats.

In non-distributed mode, this is a single-rank container: [local_group_histories].

static lock_control_points_on_outer_edges(gradients: torch.Tensor, device: torch.device | None = None) → torch.Tensor

Lock the u and v values of the control points on the outer edges of each facet.

As the knots of the first and last knots on each facet have full multiplicity, the NURBS surfaces all start and end in control points. If the outer control points are not fixed in their u and v values, the reconstructed surfaces may not be rectangular anymore. To keep them rectangular, this function zeros the gradients of the u and v coordinates of all outer control points.

Parameters

gradientstorch.Tensor: The full control point gradient tensor for all active heliostats. Gradients on the outer edges will be zeroed; interior gradients are returned unchanged. Shape is [number_of_active_heliostats, number_of_facets_per_surface, number_of_control_points_u_direction, number_of_control_points_v_direction, 3].
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: The updated gradients. Shape is [number_of_active_heliostats, number_of_facets_per_surface, number_of_control_points_u_direction, number_of_control_points_v_direction, 3].