artist.field.kinematics
=======================

.. py:module:: artist.field.kinematics

.. autoapi-nested-parse::

   Kinematics modules in ``ARTIST``.



Classes
-------

.. autoapisummary::

   artist.field.kinematics.Kinematics


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

.. py:class:: Kinematics

   Bases: :py:obj:`torch.nn.Module`


   Initialize the kinematics.

   The abstract kinematics implements a template for the construction of inheriting kinematics which currently
   can only be rigid body kinematics. The kinematics is concerned with the mechanics and motion of the heliostats
   and their actuators. The abstract base class defines two methods to determine orientation matrices, which all
   kinematics need to overwrite.


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


      Compute orientation matrices given incident ray directions.

      Parameters
      ----------
      incident_ray_directions : torch.Tensor
          The directions of the incident rays as seen from the heliostats.
          Shape is ``[number_of_active_heliostats, 4]``.
      aim_points : torch.Tensor
          The aim points for the active heliostats.
          Shape is ``[number_of_active_heliostats, 4]``.
      device : torch.device
          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:: motor_positions_to_orientations(motor_positions: torch.Tensor, device: torch.device | None = None) -> torch.Tensor
      :abstractmethod:


      Compute orientation matrices given the motor positions.

      Parameters
      ----------
      motor_positions : torch.Tensor
          The motor positions.
          Shape is ``[number_of_active_heliostats, 2]``.
      device : torch.device
          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:: forward(incident_ray_directions: torch.Tensor, aim_points: torch.Tensor, device: torch.device | None = None) -> torch.Tensor

      Specify the forward operation of the kinematics, i.e., calculate orientation matrices given the incident ray directions.

      Parameters
      ----------
      incident_ray_directions : torch.Tensor
          The directions of the incident rays as seen from the heliostats.
          Shape is ``[number_of_active_heliostats, 4]``.
      aim_points : torch.Tensor
          The aim points for the active heliostats.
          Shape is ``[number_of_active_heliostats, 4]``.
      device : torch.device
          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 orientation matrices.
          Shape is ``[number_of_active_heliostats, 4, 4]``.