artist.field.heliostat_group
============================

.. py:module:: artist.field.heliostat_group

.. autoapi-nested-parse::

   Heliostat group in ``ARTIST``.



Classes
-------

.. autoapisummary::

   artist.field.heliostat_group.HeliostatGroup


Module Contents
---------------

.. py:class:: HeliostatGroup(names: list[str], positions: torch.Tensor, surface_points: torch.Tensor, surface_normals: torch.Tensor, initial_orientations: torch.Tensor, nurbs_control_points: torch.Tensor, nurbs_degrees: torch.Tensor, device: torch.device | None = None)

   Initialize the heliostat group.

   Parameters
   ----------
   names : list[str]
       The string names of each heliostat in the group in order.
   positions : torch.Tensor
       The positions of all heliostats in the group.
       Tensor of shape [number_of_heliostats, 4].
   surface_points : torch.Tensor
       The surface points of all heliostats in the group.
       Tensor of shape [number_of_heliostats, number_of_combined_surface_points_all_facets, 4].
   surface_normals : torch.Tensor
       The surface normals of all heliostats in the group.
       Tensor of shape [number_of_heliostats, number_of_combined_surface_normals_all_facets, 4].
   initial_orientations : torch.Tensor
       The initial orientations of all heliostats in the group.
       Tensor of shape [number_of_heliostats, 4].
   nurbs_control_points : torch.Tensor
       The control points for NURBS surfaces for all heliostats in the group.
       Tensor of shape [number_of_heliostats, number_of_facets_per_heliostat, number_of_control_points_u_direction, number_of_control_points_v_direction 3].
   nurbs_degrees : torch.Tensor
       The spline degrees for NURBS surfaces in u and then in v direction, for all heliostats in the group.
       Tensor of shape [2].
   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.


   .. py:attribute:: number_of_heliostats


   .. py:attribute:: number_of_facets_per_heliostat


   .. py:attribute:: names


   .. py:attribute:: positions


   .. py:attribute:: surface_points


   .. py:attribute:: surface_normals


   .. py:attribute:: initial_orientations


   .. py:attribute:: nurbs_control_points


   .. py:attribute:: nurbs_degrees


   .. py:attribute:: kinematic


   .. py:attribute:: number_of_active_heliostats
      :value: 0



   .. py:attribute:: active_heliostats_mask


   .. py:attribute:: active_surface_points


   .. py:attribute:: active_surface_normals


   .. py:attribute:: active_nurbs_control_points


   .. py:attribute:: preferred_reflection_directions


   .. py:method:: align_surfaces_with_incident_ray_directions(aim_points: torch.Tensor, incident_ray_directions: torch.Tensor, active_heliostats_mask: torch.Tensor, device: torch.device | None = None) -> None
      :abstractmethod:


      Align surface points and surface normals with incident ray directions.

      Parameters
      ----------
      aim_points : torch.Tensor
          The aim points for all active heliostats.
          Tensor of shape [number_of_active_heliostats, 4].
      incident_ray_directions : torch.Tensor
          The incident ray directions.
          Tensor of shape [number_of_active_heliostats, 4].
      active_heliostats_mask : torch.Tensor
          A mask where 0 indicates a deactivated heliostat and 1 an activated one.
          An integer greater than 1 indicates that this heliostat is regarded multiple times.
          Tensor of shape [number_of_heliostats].
      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.

      Raises
      ------
      NotImplementedError
          Whenever called (abstract base class method).



   .. py:method:: align_surfaces_with_motor_positions(motor_positions: torch.Tensor, active_heliostats_mask: torch.Tensor, device: torch.device | None = None) -> None
      :abstractmethod:


      Align surface points and surface normals with motor positions.

      Parameters
      ----------
      motor_positions : torch.Tensor
          The motor positions for all active heliostats.
          Tensor of shape [number_of_active_heliostats, 2].
      active_heliostats_mask : torch.Tensor
          A mask where 0 indicates a deactivated heliostat and 1 an activated one.
          An integer greater than 1 indicates that this heliostat is regarded multiple times.
          Tensor of shape [number_of_heliostats].
      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.

      Raises
      ------
      NotImplementedError
          Whenever called (abstract base class method).



   .. py:method:: activate_heliostats(active_heliostats_mask: torch.Tensor | None = None, device: torch.device | None = None) -> None

      Activate certain heliostats for alignment, raytracing or optimization.

      Select and repeat indices of all active heliostat and kinematic parameters once according
      to the mask. Doing this once instead of slicing every time when accessing one
      of those parameter tensors saves memory.

      Parameters
      ----------
      active_heliostats_mask : torch.Tensor | None
          A mask where 0 indicates a deactivated heliostat and 1 an activated one (default is None).
          An integer greater than 1 indicates that this heliostat is regarded multiple times.
          If no mask is provided, all heliostats in the scenario will be activated once.
          Tensor of shape [number_of_heliostats].
      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.