artist.util =========== .. py:module:: artist.util .. autoapi-nested-parse:: Bundle all classes that implement util functionality in ``ARTIST``. Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/artist/util/config/index /autoapi/artist/util/constants/index /autoapi/artist/util/env/index /autoapi/artist/util/indices/index /autoapi/artist/util/type_registry/index Attributes ---------- .. autoapisummary:: artist.util.runtime_log Classes ------- .. autoapisummary:: artist.util.ActuatorConfig artist.util.ActuatorListConfig artist.util.ActuatorParameters artist.util.ActuatorPrototypeConfig artist.util.FacetConfig artist.util.HeliostatConfig artist.util.HeliostatListConfig artist.util.KinematicsConfig artist.util.KinematicsDeviations artist.util.KinematicsPrototypeConfig artist.util.LightSourceConfig artist.util.LightSourceListConfig artist.util.PowerPlantConfig artist.util.PrototypeConfig artist.util.SurfaceConfig artist.util.SurfacePrototypeConfig artist.util.TargetAreaCylindricalConfig artist.util.TargetAreaCylindricalListConfig artist.util.TargetAreaPlanarConfig artist.util.TargetAreaPlanarListConfig artist.util.DdpSetup Functions --------- .. autoapisummary:: artist.util.create_subgroups_for_nested_ddp artist.util.distribute_groups_among_ranks artist.util.get_device artist.util.initialize_ddp_environment artist.util.setup_distributed_environment artist.util.set_logger_config artist.util.set_runtime_logger artist.util.track_runtime Package Contents ---------------- .. py:class:: 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 ---------- key : str The name or descriptor of the actuator. actuator_type : str The type of actuator to use, e.g. linear or ideal. clockwise_axis_movement : bool Boolean indicating if the actuator operates in a clockwise or counterclockwise manner. min_max_motor_positions : list[float] The minimum and maximum motor positions. parameters : ActuatorParameters | None The parameters of the actuator. .. py:attribute:: key .. py:attribute:: actuator_type .. py:attribute:: clockwise_axis_movement .. py:attribute:: min_max_motor_positions .. py:attribute:: parameters :value: None .. py:method:: create_actuator_dict() -> dict[str, Any] Create a dictionary containing the actuator configuration. Returns ------- dict[str, Any] A dictionary containing the actuator configuration. .. py:class:: ActuatorListConfig(actuator_list: list[ActuatorConfig]) Initialize the actuator list configuration. Parameters ---------- actuator_list : list[ActuatorConfig] A list of actuator configurations. .. py:attribute:: actuator_list .. py:method:: 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. .. py:class:: 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 ---------- increment : torch.Tensor | None The increment for the actuator initial_stroke_length : torch.Tensor | None The initial stroke length. offset : torch.Tensor | None The initial actuator offset. pivot_radius : torch.Tensor | None The pivot radius of the considered joint. initial_angle : torch.Tensor | None The initial angle of the actuator. .. py:attribute:: increment :value: None .. py:attribute:: initial_stroke_length :value: None .. py:attribute:: offset :value: None .. py:attribute:: pivot_radius :value: None .. py:attribute:: initial_angle :value: None .. py:method:: 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. .. py:class:: ActuatorPrototypeConfig(actuator_list: list[ActuatorConfig]) Bases: :py:obj:`ActuatorListConfig` Initialize the actuator list prototype configuration. Parameters ---------- actuator_list : list[ActuatorConfig] A list of actuator configurations. .. py:class:: FacetConfig(facet_key: str, control_points: torch.Tensor, degrees: torch.Tensor, translation_vector: torch.Tensor, canting: torch.Tensor) Initialize the facet configuration. Parameters ---------- facet_key : str The key used to identify the facet in the HDF5 file. control_points : torch.Tensor The NURBS control points. degrees : torch.Tensor The NURBS degree in the east and north direction. translation_vector : torch.Tensor The translation_vector of the facet. canting: torch.Tensor The canting vectors in the east and north direction. .. py:attribute:: facet_key .. py:attribute:: control_points .. py:attribute:: degrees .. py:attribute:: translation_vector .. py:attribute:: canting .. py:method:: 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. .. py:class:: 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 ---------- name : str The name used to identify the heliostat in the HDF5 file. heliostat_id : int The numerical ID of the heliostat. position : torch.Tensor The position of the heliostat. surface : SurfaceConfig | None An optional individual surface config for the heliostat. kinematics : KinematicsConfig | None An optional kinematics config for the heliostat. actuators : ActuatorListConfig | None An optional actuator list config for the heliostat. .. py:attribute:: name .. py:attribute:: heliostat_id .. py:attribute:: position .. py:attribute:: surface :value: None .. py:attribute:: kinematics :value: None .. py:attribute:: actuators :value: None .. py:method:: 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. .. py:class:: HeliostatListConfig(heliostat_list: list[HeliostatConfig]) Initialize the heliostat list configuration. Parameters ---------- heliostat_list : list[HeliostatConfig] The list of heliostats to include. .. py:attribute:: heliostat_list .. py:method:: 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. .. py:class:: KinematicsConfig(kinematics_type: str, initial_orientation: torch.Tensor, deviations: KinematicsDeviations | None = None) Initialize the kinematics configuration. Parameters ---------- kinematics_type : str The type of kinematics used. initial_orientation : torch.Tensor The initial orientation of the kinematics configuration. deviations : KinematicsDeviations | None The kinematics deviations. .. py:attribute:: kinematics_type .. py:attribute:: initial_orientation .. py:attribute:: deviations :value: None .. py:method:: 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. .. py:class:: 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_e : torch.Tensor | None The first joint translation in the east direction. first_joint_translation_n : torch.Tensor | None The first joint translation in the north direction. first_joint_translation_u : torch.Tensor | None The first joint translation in the up direction. first_joint_tilt_n : torch.Tensor | None The first joint tilt in the north direction. first_joint_tilt_u : torch.Tensor | None The first joint tilt in the up direction. second_joint_translation_e : torch.Tensor | None The second joint translation in the east direction. second_joint_translation_n : torch.Tensor | None The second joint translation in the north direction. second_joint_translation_u : torch.Tensor | None The second joint translation in the up direction. second_joint_tilt_e : torch.Tensor | None The second joint tilt in the east direction. second_joint_tilt_n : torch.Tensor | None The second joint tilt in the north direction. concentrator_translation_e : torch.Tensor | None The concentrator translation in the east direction. concentrator_translation_n : torch.Tensor | None The concentrator translation in the north direction. concentrator_translation_u : torch.Tensor | None The concentrator translation in the up direction. .. py:attribute:: first_joint_translation_e :value: None .. py:attribute:: first_joint_translation_n :value: None .. py:attribute:: first_joint_translation_u :value: None .. py:attribute:: first_joint_tilt_n :value: None .. py:attribute:: first_joint_tilt_u :value: None .. py:attribute:: second_joint_translation_e :value: None .. py:attribute:: second_joint_translation_n :value: None .. py:attribute:: second_joint_translation_u :value: None .. py:attribute:: second_joint_tilt_e :value: None .. py:attribute:: second_joint_tilt_n :value: None .. py:attribute:: concentrator_translation_e :value: None .. py:attribute:: concentrator_translation_n :value: None .. py:attribute:: concentrator_translation_u :value: None .. py:method:: 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. .. py:class:: KinematicsPrototypeConfig(kinematics_type: str, initial_orientation: torch.Tensor, deviations: KinematicsDeviations | None = None) Bases: :py:obj:`KinematicsConfig` Initialize the kinematics prototype configuration. Parameters ---------- kinematics_type : str The type of kinematics used. initial_orientation : torch.Tensor The initial orientation of the kinematics configuration. deviations : KinematicsDeviations | None The kinematics deviations. .. py:class:: 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_key : str 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_rays : int The number of rays generated by the light source. distribution_type : str The distribution type used to model the light source. mean : float | None The mean used for modeling the light source. covariance : float | None The covariance used for modeling the light source. Raises ------ ValueError If the specified light source distribution type is unknown. .. py:attribute:: light_source_key .. py:attribute:: light_source_type .. py:attribute:: number_of_rays .. py:attribute:: distribution_type .. py:method:: 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. .. py:class:: LightSourceListConfig(light_source_list: list[LightSourceConfig]) Initialize the light source list configuration. Parameters ---------- light_source_list : list[LightSourceConfig] The list of light source configs to be included in the scenario. .. py:attribute:: light_source_list .. py:method:: 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. .. py:class:: PowerPlantConfig(power_plant_position: torch.Tensor) Initialize the power plant configuration. Parameters ---------- power_plant_position : torch.Tensor The position of the power plant as latitude, longitude, altitude. .. py:attribute:: power_plant_position .. py:method:: 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. .. py:class:: PrototypeConfig(surface_prototype: SurfacePrototypeConfig, kinematics_prototype: KinematicsPrototypeConfig, actuators_prototype: ActuatorPrototypeConfig) Initialize the prototype configuration. Parameters ---------- surface_prototype : SurfacePrototypeConfig The prototype for the surface. kinematics_prototype : KinematicsPrototypeConfig The prototype for the kinematics. actuators_prototype : ActuatorPrototypeConfig The prototype for the actuators. .. py:attribute:: surface_prototype .. py:attribute:: kinematics_prototype .. py:attribute:: actuators_prototype .. py:method:: create_prototype_dict() -> dict[str, Any] Create a dictionary containing the prototypes. Returns ------- dict[str, Any] A dictionary containing the prototypes. .. py:class:: SurfaceConfig(facet_list: list[FacetConfig]) Initialize the surface configuration. Parameters ---------- facet_list : list[FacetsConfig] The list of facets to be used for the surface of the heliostat. .. py:attribute:: facet_list .. py:method:: 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. .. py:class:: SurfacePrototypeConfig(facet_list: list[FacetConfig]) Bases: :py:obj:`SurfaceConfig` Initialize the surface prototype configuration. Parameters ---------- facet_list : list[FacetsConfig] The list of facets to be used for the surface of the heliostat prototype. .. py:class:: 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_key : str ID used to identify the target area in the HDF5 file. radius : torch.Tensor Radius of the cylindrical target area. center : torch.Tensor Position of the center of the cylindrical target area. height : torch.Tensor Height of the cylindrical target area. axis : torch.Tensor Axis of the cylindrical target area. normal : torch.Tensor Normal vector of the cylindrical target area. opening_angle : torch.Tensor Opening angle of the cylindrical target area. .. py:attribute:: target_area_key .. py:attribute:: radius .. py:attribute:: center .. py:attribute:: height .. py:attribute:: axis .. py:attribute:: normal .. py:attribute:: opening_angle .. py:method:: 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. .. py:class:: TargetAreaCylindricalListConfig(target_area_list: list[TargetAreaCylindricalConfig]) Initialize the cylindrical target area list configuration. Parameters ---------- target_area_list : list[TargetAreaCylindricalConfig] The list of cylindrical target area configurations included in the scenario. .. py:attribute:: target_area_list .. py:method:: 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. .. py:class:: 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_key : str ID used to identify the target area in the HDF5 file. center : torch.Tensor Position of the target area's center. normal_vector : torch.Tensor Normal vector to the target plane. plane_e : torch.Tensor Size of the target area in the east direction. plane_u : torch.Tensor Size of the target area in the up direction. .. py:attribute:: target_area_key .. py:attribute:: center .. py:attribute:: normal_vector .. py:attribute:: plane_e .. py:attribute:: plane_u .. py:method:: 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. .. py:class:: TargetAreaPlanarListConfig(target_area_list: list[TargetAreaPlanarConfig]) Initialize the planar target area list configuration. Parameters ---------- target_area_list : list[TargetAreaPlanarConfig] The list of planar target area configurations included in the scenario. .. py:attribute:: target_area_list .. py:method:: 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. .. py:class:: DdpSetup Bases: :py:obj:`TypedDict` Initialize self. See help(type(self)) for accurate signature. .. py:attribute:: device :type: torch.device .. py:attribute:: is_distributed :type: bool .. py:attribute:: is_nested :type: bool .. py:attribute:: rank :type: int .. py:attribute:: world_size :type: int .. py:attribute:: process_subgroup :type: torch.distributed.ProcessGroup | None .. py:attribute:: groups_to_ranks_mapping :type: dict[int, list[int]] .. py:attribute:: heliostat_group_rank :type: int .. py:attribute:: heliostat_group_world_size :type: int .. py:attribute:: ranks_to_groups_mapping :type: dict[int, list[int]] .. py:function:: 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 ---------- rank : int The current process. groups_to_ranks_mapping : dict[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. .. py:function:: 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_size : int Total number of processes in the global process group. number_of_heliostat_groups : int 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. .. py:function:: 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 ---------- device : torch.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. .. py:function:: 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 ---------- device : torch.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. .. py:function:: 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_groups : int The number of distinct heliostat groups in the scenario. device : torch.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``. .. py:function:: 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 ---------- level : int The default level for logging. Default is ``logging.INFO``. log_file : str | Path | None The file to save the log to. log_to_stdout : bool A flag indicating if the log should be printed on stdout. Default is True. colors : bool A flag for using colored logs. Default is True. .. py:function:: 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_file : str | Path The file path to write runtime logs. level : int The logging level (default is logging.INFO). Returns ------- logging.Logger The configured runtime logger. .. py:function:: 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 ---------- logger : logging.Logger The runtime logger. Returns ------- Callable[[Callable[..., _T]], Callable[..., _T]] The decorated function with runtime tracking. .. py:data:: runtime_log