artist.util

Bundle all classes that implement util functionality in ARTIST.

Submodules

Attributes

runtime_log

Classes

`ActuatorConfig`	Initialize the actuator configuration.
`ActuatorListConfig`	Initialize the actuator list configuration.
`ActuatorParameters`	Initialize the actuator parameters.
`ActuatorPrototypeConfig`	Initialize the actuator list prototype configuration.
`FacetConfig`	Initialize the facet configuration.
`HeliostatConfig`	Initialize the single heliostat configuration.
`HeliostatListConfig`	Initialize the heliostat list configuration.
`KinematicsConfig`	Initialize the kinematics configuration.
`KinematicsDeviations`	Initialize the kinematics deviations.
`KinematicsPrototypeConfig`	Initialize the kinematics prototype configuration.
`LightSourceConfig`	Initialize the light source configuration.
`LightSourceListConfig`	Initialize the light source list configuration.
`PowerPlantConfig`	Initialize the power plant configuration.
`PrototypeConfig`	Initialize the prototype configuration.
`SurfaceConfig`	Initialize the surface configuration.
`SurfacePrototypeConfig`	Initialize the surface prototype configuration.
`TargetAreaCylindricalConfig`	Initialize the target area configuration for cylindrical target areas.
`TargetAreaCylindricalListConfig`	Initialize the cylindrical target area list configuration.
`TargetAreaPlanarConfig`	Initialize the target area configuration for planar target areas.
`TargetAreaPlanarListConfig`	Initialize the planar target area list configuration.
`DdpSetup`	Initialize self. See help(type(self)) for accurate signature.

Functions

`create_subgroups_for_nested_ddp`(→ tuple[int, int, ...)	Assign the current process (rank) to a subgroup based on a predefined group assignment map.
`distribute_groups_among_ranks`(→ tuple[dict[int, ...)	Distribute groups among ranks in round-robin fashion.
`get_device`(→ torch.device)	Get the correct GPU device type for common operating systems, default to CPU if none is found.
`initialize_ddp_environment`(→ tuple[torch.device, bool, ...)	Set up the distributed environment.
`setup_distributed_environment`(...)	Set up the distributed environment.
`set_logger_config`(→ None)	Set up the logger. Should only need to be done once. Generally, logging should only be done on the master rank.
`set_runtime_logger`(→ logging.Logger)	Configure and return a shared runtime logger that logs execution times of functions.
`track_runtime`(...)	Track and log start, finish, and duration of function execution.

Package Contents

class artist.util.ActuatorConfig(key: str, actuator_type: str, clockwise_axis_movement: bool, min_max_motor_positions: list[float], parameters: ActuatorParameters | None = None)

Initialize the actuator configuration.

Parameters

keystr: The name or descriptor of the actuator.
actuator_typestr: The type of actuator to use, e.g. linear or ideal.
clockwise_axis_movementbool: Boolean indicating if the actuator operates in a clockwise or counterclockwise manner.
min_max_motor_positionslist[float]: The minimum and maximum motor positions.
parametersActuatorParameters | None: The parameters of the actuator.

key

actuator_type

clockwise_axis_movement

min_max_motor_positions

parameters = None

create_actuator_dict() → dict[str, Any]

Create a dictionary containing the actuator configuration.

Returns

dict[str, Any]: A dictionary containing the actuator configuration.

class artist.util.ActuatorListConfig(actuator_list: list[ActuatorConfig])

Initialize the actuator list configuration.

Parameters

actuator_listlist[ActuatorConfig]: A list of actuator configurations.

actuator_list

create_actuator_list_dict() → dict[str, Any]

Create a dictionary containing a list of actuator configurations.

Returns

dict[str, Any]: A dictionary containing a list of actuator configurations.

class artist.util.ActuatorParameters(increment: torch.Tensor | None = None, initial_stroke_length: torch.Tensor | None = None, offset: torch.Tensor | None = None, pivot_radius: torch.Tensor | None = None, initial_angle: torch.Tensor | None = None)

Initialize the actuator parameters.

Parameters

incrementtorch.Tensor | None: The increment for the actuator
initial_stroke_lengthtorch.Tensor | None: The initial stroke length.
offsettorch.Tensor | None: The initial actuator offset.
pivot_radiustorch.Tensor | None: The pivot radius of the considered joint.
initial_angletorch.Tensor | None: The initial angle of the actuator.

increment = None

initial_stroke_length = None

offset = None

pivot_radius = None

initial_angle = None

create_actuator_parameters_dict() → dict[str, torch.Tensor]

Create a dictionary containing the parameters for the actuator.

Returns

dict[str, torch.Tensor]: A dictionary containing the configuration parameters for the actuator.

class artist.util.ActuatorPrototypeConfig(actuator_list: list[ActuatorConfig])

Bases: ActuatorListConfig

Initialize the actuator list prototype configuration.

Parameters

actuator_listlist[ActuatorConfig]: A list of actuator configurations.

class artist.util.FacetConfig(facet_key: str, control_points: torch.Tensor, degrees: torch.Tensor, translation_vector: torch.Tensor, canting: torch.Tensor)

Initialize the facet configuration.

Parameters

facet_keystr: The key used to identify the facet in the HDF5 file.
control_pointstorch.Tensor: The NURBS control points.
degreestorch.Tensor: The NURBS degree in the east and north direction.
translation_vectortorch.Tensor: The translation_vector of the facet.
canting: torch.Tensor: The canting vectors in the east and north direction.

facet_key

control_points

degrees

translation_vector

canting

create_facet_dict() → dict[str, Any]

Create a dictionary containing the configuration parameters for a facet.

Returns

dict[str, Any]: A dictionary containing the configuration parameters for the facet.

class artist.util.HeliostatConfig(name: str, heliostat_id: int, position: torch.Tensor, surface: SurfaceConfig | None = None, kinematics: KinematicsConfig | None = None, actuators: ActuatorListConfig | None = None)

Initialize the single heliostat configuration.

Parameters

namestr: The name used to identify the heliostat in the HDF5 file.
heliostat_idint: The numerical ID of the heliostat.
positiontorch.Tensor: The position of the heliostat.
surfaceSurfaceConfig | None: An optional individual surface config for the heliostat.
kinematicsKinematicsConfig | None: An optional kinematics config for the heliostat.
actuatorsActuatorListConfig | None: An optional actuator list config for the heliostat.

name

heliostat_id

position

surface = None

kinematics = None

actuators = None

create_heliostat_config_dict() → dict[str, Any]

Create a dictionary containing the heliostat configuration parameters.

Returns

dict[str, Any]: A dictionary containing the heliostat configuration parameters.

class artist.util.HeliostatListConfig(heliostat_list: list[HeliostatConfig])

Initialize the heliostat list configuration.

Parameters

heliostat_listlist[HeliostatConfig]: The list of heliostats to include.

heliostat_list

create_heliostat_list_dict() → dict[str, Any]

Create a dictionary containing the heliostat list configuration parameters.

Returns

dict[str, Any]: A dictionary containing the heliostat list configuration parameters.

class artist.util.KinematicsConfig(kinematics_type: str, initial_orientation: torch.Tensor, deviations: KinematicsDeviations | None = None)

Initialize the kinematics configuration.

Parameters

kinematics_typestr: The type of kinematics used.
initial_orientationtorch.Tensor: The initial orientation of the kinematics configuration.
deviationsKinematicsDeviations | None: The kinematics deviations.

kinematics_type

initial_orientation

deviations = None

create_kinematics_dict() → dict[str, Any]

Create a dictionary containing the configuration parameters for the kinematics.

Returns

dict[str, Any]: A dictionary containing the configuration parameters for the kinematics.

class artist.util.KinematicsDeviations(first_joint_translation_e: torch.Tensor | None = None, first_joint_translation_n: torch.Tensor | None = None, first_joint_translation_u: torch.Tensor | None = None, first_joint_tilt_n: torch.Tensor | None = None, first_joint_tilt_u: torch.Tensor | None = None, second_joint_translation_e: torch.Tensor | None = None, second_joint_translation_n: torch.Tensor | None = None, second_joint_translation_u: torch.Tensor | None = None, second_joint_tilt_e: torch.Tensor | None = None, second_joint_tilt_n: torch.Tensor | None = None, concentrator_translation_e: torch.Tensor | None = None, concentrator_translation_n: torch.Tensor | None = None, concentrator_translation_u: torch.Tensor | None = None)

Initialize the kinematics deviations.

Parameters

first_joint_translation_etorch.Tensor | None: The first joint translation in the east direction.
first_joint_translation_ntorch.Tensor | None: The first joint translation in the north direction.
first_joint_translation_utorch.Tensor | None: The first joint translation in the up direction.
first_joint_tilt_ntorch.Tensor | None: The first joint tilt in the north direction.
first_joint_tilt_utorch.Tensor | None: The first joint tilt in the up direction.
second_joint_translation_etorch.Tensor | None: The second joint translation in the east direction.
second_joint_translation_ntorch.Tensor | None: The second joint translation in the north direction.
second_joint_translation_utorch.Tensor | None: The second joint translation in the up direction.
second_joint_tilt_etorch.Tensor | None: The second joint tilt in the east direction.
second_joint_tilt_ntorch.Tensor | None: The second joint tilt in the north direction.
concentrator_translation_etorch.Tensor | None: The concentrator translation in the east direction.
concentrator_translation_ntorch.Tensor | None: The concentrator translation in the north direction.
concentrator_translation_utorch.Tensor | None: The concentrator translation in the up direction.

first_joint_translation_e = None

first_joint_translation_n = None

first_joint_translation_u = None

first_joint_tilt_n = None

first_joint_tilt_u = None

second_joint_translation_e = None

second_joint_translation_n = None

second_joint_translation_u = None

second_joint_tilt_e = None

second_joint_tilt_n = None

concentrator_translation_e = None

concentrator_translation_n = None

concentrator_translation_u = None

create_kinematics_deviations_dict() → dict[str, Any]

Create a dictionary containing the configuration parameters for the kinematics deviations.

Returns

dict[str, Any]: A dictionary containing the configuration parameters for the kinematics deviations.

class artist.util.KinematicsPrototypeConfig(kinematics_type: str, initial_orientation: torch.Tensor, deviations: KinematicsDeviations | None = None)

Bases: KinematicsConfig

Initialize the kinematics prototype configuration.

Parameters

kinematics_typestr: The type of kinematics used.
initial_orientationtorch.Tensor: The initial orientation of the kinematics configuration.
deviationsKinematicsDeviations | None: The kinematics deviations.

class artist.util.LightSourceConfig(light_source_key: str, light_source_type: str, number_of_rays: int, distribution_type: str, mean: float | None = None, covariance: float | None = None)

Initialize the light source configuration.

Parameters

light_source_keystr: The key used to identify the light source in the HDF5 file.
light_source_type:: The type of light source used, e.g. a sun.
number_of_raysint: The number of rays generated by the light source.
distribution_typestr: The distribution type used to model the light source.
meanfloat | None: The mean used for modeling the light source.
covariancefloat | None: The covariance used for modeling the light source.

Raises

ValueError: If the specified light source distribution type is unknown.

light_source_key

light_source_type

number_of_rays

distribution_type

create_light_source_dict() → dict[str, Any]

Create a dictionary containing the configuration parameters for the light source.

Returns

dict[str, Any]: A dictionary containing the configuration parameters for the light source.

class artist.util.LightSourceListConfig(light_source_list: list[LightSourceConfig])

Initialize the light source list configuration.

Parameters

light_source_listlist[LightSourceConfig]: The list of light source configs to be included in the scenario.

light_source_list

create_light_source_list_dict() → dict[str, Any]

Create a dictionary containing the configuration parameters for the light source list.

Returns

dict[str, Any]: A dictionary containing the configuration parameters for the light source list.

class artist.util.PowerPlantConfig(power_plant_position: torch.Tensor)

Initialize the power plant configuration.

Parameters

power_plant_positiontorch.Tensor: The position of the power plant as latitude, longitude, altitude.

power_plant_position

create_power_plant_dict() → dict[str, Any]

Create a dictionary containing the configuration parameters for the power plant.

Returns

dict[str, Any]: A dictionary containing the configuration parameters for the power plant.

class artist.util.PrototypeConfig(surface_prototype: SurfacePrototypeConfig, kinematics_prototype: KinematicsPrototypeConfig, actuators_prototype: ActuatorPrototypeConfig)

Initialize the prototype configuration.

Parameters

surface_prototypeSurfacePrototypeConfig: The prototype for the surface.
kinematics_prototypeKinematicsPrototypeConfig: The prototype for the kinematics.
actuators_prototypeActuatorPrototypeConfig: The prototype for the actuators.

surface_prototype

kinematics_prototype

actuators_prototype

create_prototype_dict() → dict[str, Any]

Create a dictionary containing the prototypes.

Returns

dict[str, Any]: A dictionary containing the prototypes.

class artist.util.SurfaceConfig(facet_list: list[FacetConfig])

Initialize the surface configuration.

Parameters

facet_listlist[FacetsConfig]: The list of facets to be used for the surface of the heliostat.

facet_list

create_surface_dict() → dict[str, Any]

Create a dictionary containing the configuration parameters for the surface.

Returns

dict[str, Any]: A dictionary containing the configuration parameters for the surface.

class artist.util.SurfacePrototypeConfig(facet_list: list[FacetConfig])

Bases: SurfaceConfig

Initialize the surface prototype configuration.

Parameters

facet_listlist[FacetsConfig]: The list of facets to be used for the surface of the heliostat prototype.

class artist.util.TargetAreaCylindricalConfig(target_area_key: str, radius: torch.Tensor, center: torch.Tensor, height: torch.Tensor, axis: torch.Tensor, normal: torch.Tensor, opening_angle: torch.Tensor)

Initialize the target area configuration for cylindrical target areas.

Parameters

target_area_keystr: ID used to identify the target area in the HDF5 file.
radiustorch.Tensor: Radius of the cylindrical target area.
centertorch.Tensor: Position of the center of the cylindrical target area.
heighttorch.Tensor: Height of the cylindrical target area.
axistorch.Tensor: Axis of the cylindrical target area.
normaltorch.Tensor: Normal vector of the cylindrical target area.
opening_angletorch.Tensor: Opening angle of the cylindrical target area.

target_area_key

radius

center

height

axis

normal

opening_angle

create_target_area_dict() → dict[str, Any]

Create a dictionary containing the configuration parameters for the cylindrical target area.

Returns

dict[str, Any]: A dictionary containing the configuration parameters for the cylindrical target area.

class artist.util.TargetAreaCylindricalListConfig(target_area_list: list[TargetAreaCylindricalConfig])

Initialize the cylindrical target area list configuration.

Parameters

target_area_listlist[TargetAreaCylindricalConfig]: The list of cylindrical target area configurations included in the scenario.

target_area_list

create_target_area_list_dict() → dict[str, Any]

Create a dictionary containing the configuration parameters for the list of cylindrical target areas.

Returns

dict[str, Any]: A dictionary containing the configuration parameters for the list of cylindrical target areas.

class artist.util.TargetAreaPlanarConfig(target_area_key: str, center: torch.Tensor, normal_vector: torch.Tensor, plane_e: torch.Tensor, plane_u: torch.Tensor)

Initialize the target area configuration for planar target areas.

Parameters

target_area_keystr: ID used to identify the target area in the HDF5 file.
centertorch.Tensor: Position of the target area’s center.
normal_vectortorch.Tensor: Normal vector to the target plane.
plane_etorch.Tensor: Size of the target area in the east direction.
plane_utorch.Tensor: Size of the target area in the up direction.

target_area_key

center

normal_vector

plane_e

plane_u

create_target_area_dict() → dict[str, Any]

Create a dictionary containing the configuration parameters for the planar target area.

Returns

dict[str, Any]: A dictionary containing the configuration parameters for the planar target area.

class artist.util.TargetAreaPlanarListConfig(target_area_list: list[TargetAreaPlanarConfig])

Initialize the planar target area list configuration.

Parameters

target_area_listlist[TargetAreaPlanarConfig]: The list of planar target area configurations included in the scenario.

target_area_list

create_target_area_list_dict() → dict[str, Any]

Create a dictionary containing the configuration parameters for the list of planar target areas.

Returns

dict[str, Any]: A dictionary containing the configuration parameters for the list of planar target areas.

class artist.util.DdpSetup

Bases: TypedDict

Initialize self. See help(type(self)) for accurate signature.

device: torch.device

is_distributed: bool

is_nested: bool

rank: int

world_size: int

process_subgroup: torch.distributed.ProcessGroup | None

groups_to_ranks_mapping: dict[int, list[int]]

heliostat_group_rank: int

heliostat_group_world_size: int

ranks_to_groups_mapping: dict[int, list[int]]

artist.util.create_subgroups_for_nested_ddp(rank: int, groups_to_ranks_mapping: dict[int, list[int]]) → tuple[int, int, torch.distributed.ProcessGroup | None, dict[int, list[int]]]

Assign the current process (rank) to a subgroup based on a predefined group assignment map.

Parameters

rankint: The current process.
groups_to_ranks_mappingdict[int, list[int]]: The mapping from heliostat group to rank.

Returns

int: The rank within the heliostat group.
int: The world size of the heliostat group.
torch.distributed.ProcessGroup | None: The distributed process group.
dict[int, list[int]]: The mapping from ranks to heliostat groups.

artist.util.distribute_groups_among_ranks(world_size: int, number_of_heliostat_groups: int) → tuple[dict[int, list[int]], bool]

Distribute groups among ranks in round-robin fashion.

If there are fewer ranks than groups, some ranks receive multiple groups. If there are more ranks than groups, some groups are handled by multiple ranks, enabling nested distribution.

Parameters

world_sizeint: Total number of processes in the global process group.
number_of_heliostat_groupsint: The number of heliostat groups.

Returns

dict[int, list[int]]: The dictionary mapping heliostat groups to ranks.
bool: Indicates whether the distributed setup is nested or not.

artist.util.get_device(device: torch.device | None = None) → torch.device

Get the correct GPU device type for common operating systems, default to CPU if none is found.

Parameters

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. MPS (for Mac) is not supported due to limitations in torch.

Returns

torch.device: The device.

artist.util.initialize_ddp_environment(device: torch.device | None = None) → tuple[torch.device, bool, int, int]

Set up the distributed environment.

Based on the available devices, the outer process group is initialized with the appropriate backend. For computation on GPUs the nccl backend optimized for NVIDIA GPUs is chosen. For computation on CPUs gloo is used as backend. If the program is run without the intention of being distributed, the world_size will be set to 1, accordingly the only rank is 0.

Parameters

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.

Yields

torch.device: The device for each rank.
bool: Distributed mode enabled or disabled.
int: The rank of the current process.
int: The world size or total number of processes.

artist.util.setup_distributed_environment(number_of_heliostat_groups: int, device: torch.device | None = None) → collections.abc.Generator[DdpSetup, None, None]

Set up the distributed environment.

Parameters

number_of_heliostat_groupsint: The number of distinct heliostat groups in the scenario.
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.

Yields

DdpSetup: A typed dictionary describing the full distributed setup, containing: device, is_distributed, is_nested, rank, world_size, process_subgroup, groups_to_ranks_mapping, heliostat_group_rank, heliostat_group_world_size, and ranks_to_groups_mapping.

artist.util.set_logger_config(level: int = logging.INFO, log_file: str | pathlib.Path | None = None, log_to_stdout: bool = True, colors: bool = True) → None

Set up the logger. Should only need to be done once. Generally, logging should only be done on the master rank.

Parameters

levelint: The default level for logging. Default is logging.INFO.
log_filestr | Path | None: The file to save the log to.
log_to_stdoutbool: A flag indicating if the log should be printed on stdout. Default is True.
colorsbool: A flag for using colored logs. Default is True.

artist.util.set_runtime_logger(log_file: str | pathlib.Path = 'runtime_log.txt', level: int = logging.INFO) → logging.Logger

Configure and return a shared runtime logger that logs execution times of functions.

Parameters

log_filestr | Path: The file path to write runtime logs.
levelint: The logging level (default is logging.INFO).

Returns

logging.Logger: The configured runtime logger.

artist.util.track_runtime(logger: logging.Logger) → collections.abc.Callable[[collections.abc.Callable[Ellipsis, _T]], collections.abc.Callable[Ellipsis, _T]]

Track and log start, finish, and duration of function execution.

Parameters

loggerlogging.Logger: The runtime logger.

Returns

Callable[[Callable[…, _T]], Callable[…, _T]]: The decorated function with runtime tracking.

artist.util.runtime_log