Features/soa (#37)

This pull request includes the following changes:
- Complete restructure of the ARTIST package to conform with python style.
- Include scenarios as hdf5 files.
- Reimagined how all classes are initialized.
- Cleaned up kinematic and alignment modules.
- Rewrote tests with fewer rays to enable efficient execution on GitHub.

.github/workflows/python-test.yml

@@ -35,7 +35,7 @@ jobs:
       - name: Tests with pytest and no badge
         if: matrix.python-version == '3.12'
         run: |
-          pytest artist
+          pytest --cov=artist
 
       - name: Verify Changed files
         uses: tj-actions/verify-changed-files@v19

README.md

@@ -5,7 +5,8 @@
 [![](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://www.python.org/downloads/)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 ![](./coverage.svg)
-[![](https://img.shields.io/badge/Contact-max.pargmann%40dlr.de-orange)](mailto:[email protected])
+[![](https://img.shields.io/badge/Contact-artist%40lists.kit.edu-orange?label=Contact)]([email protected])
+
 
 ## What ARTIST can do for you
 
@@ -49,22 +50,16 @@ We heavily recommend to install the `ARTIST` package in a dedicated `Python3.8+`
 ## Structure
 ```
 ├──artist # Parent package
-│   ├───io # IO functionality
-│   │   └───tests # IO functionality tests
 │   ├───physics_objects # Physical objects in raytracing environment, e.g., heliostats or receiver
-│   │   └───heliostats
-│   │       ├───alignment
-│   │       │   └───tests
-│   │       │       └───bitmaps
-│   │       └───surface
-│   │           └───facets
 │   ├───raytracing
-│   ├───scenario
-│   │   └───light_source
-│   │       └───tests
+│   ├───scene # Light sources and factors influencing the surroundings
 │   └───util
-└───scenario_objects # Loaded from experiment yaml file to, e.g., define whether the sun or a beamer should be loaded
-    └───heliostats
+└───measurement_data # Real measurements from a solar thermal power plant that can be used to create a scenario
+└───scenarios # Scenarios describing solar thermal power plants which can be loaded
+└───tests
+    ├───physics_objects # Tests for objects in the physics_objects package
+    ├───raytracing # Tests for objects in the raytracing package
+    └───scene # Tests for objects in the scene package
 ```
 ## How to use ARTIST
 We plan to provide an official *ReadTheDocs* documentation including exemplary usage scripts.

artist/__init__.py

@@ -1,4 +1,13 @@
-# -*- coding: utf-8 -*-
+"""This package bundles ARTIST."""
+
 import os
 
 ARTIST_ROOT = f"{os.sep}".join(__file__.split(os.sep)[:-2])
+
+__all__ = [
+    "physics_objects",
+    "raytracing",
+    "scene",
+    "util",
+    "ARTIST_ROOT",
+]

artist/physics_objects/__init__.py

@@ -1,8 +1,23 @@
 """This package bundles all classes that represent physical objects in ARTIST."""
-from artist.physics_objects.module import AModule
-from artist.physics_objects.parameter import AParameter
+
+from .actuator import AActuatorModule
+from .actuator_ideal import IdealActuator
+from .alignment import AlignmentModule
+from .concentrator import ConcentratorModule
+from .facets import AFacetModule
+from .facets_point_cloud import PointCloudFacetModule
+from .heliostat import HeliostatModule
+from .kinematic import AKinematicModule
+from .kinematic_rigid_body import RigidBodyModule
 
 __all__ = [
-    "AModule",
-    "AParameter",
+    "AActuatorModule",
+    "IdealActuator",
+    "AlignmentModule",
+    "ConcentratorModule",
+    "AFacetModule",
+    "PointCloudFacetModule",
+    "HeliostatModule",
+    "AKinematicModule",
+    "RigidBodyModule",
 ]

artist/physics_objects/actuator.py

@@ -0,0 +1,39 @@
+import torch
+
+
+class AActuatorModule(torch.nn.Module):
+    """
+    This class implements the abstract behavior of an actuator.
+
+    Attributes
+    ----------
+    joint_number : int
+        Descriptor (number) of the joint.
+    clockwise : bool
+        Turning direction of the joint.
+
+    Methods
+    -------
+    forward()
+        The forward kinematic.
+    """
+
+    def __init__(
+        self,
+        joint_number: int,
+        clockwise: bool,
+    ) -> None:
+        super().__init__()
+        self.joint_number = joint_number
+        self.clockwise = clockwise
+
+    def forward(self) -> torch.Tensor:
+        """
+        Perform forward kinematic.
+
+        Raises
+        ------
+        NotImplementedError
+            This abstract method must be overridden.
+        """
+        raise NotImplementedError("Must Be Overridden!")

artist/physics_objects/actuator_ideal.py

@@ -0,0 +1,72 @@
+import torch
+
+from artist.physics_objects.actuator import (
+    AActuatorModule,
+)
+
+
+class IdealActuator(AActuatorModule):
+    """
+    This class implements the behavior of an ideal actuator.
+
+    Methods
+    -------
+    motor_steps_to_angles()
+        Calculate the angles given motor steps.
+    angles_to_motor_steps()
+        Calculate the motor steps given the angles.
+    forward()
+        Perform the forward kinematic.
+
+    See Also
+    --------
+    :class:`AActuatorModule` : The parent class.
+    """
+
+    def motor_steps_to_angles(self, motor_steps: torch.Tensor) -> torch.Tensor:
+        """
+        Translate motor steps to a joint angle.
+
+        Parameters
+        ----------
+        motor_steps : torch.Tensor
+            The motor steps.
+
+        Returns
+        -------
+        torch.Tensor
+            The joint angle.
+        """
+        return motor_steps
+
+    def angles_to_motor_steps(self, angles: torch.Tensor) -> torch.Tensor:
+        """
+        Translate a joint angle to motor steps.
+
+        Parameters
+        ----------
+        angles : torch.Tensor
+            The joint angles.
+
+        Returns
+        -------
+        torch.Tensor
+            The motor steps.
+        """
+        return angles
+
+    def forward(self, actuator_pos: torch.Tensor) -> torch.Tensor:
+        """
+        Perform the forward kinematic for an ideal actuator.
+
+        Parameters
+        ----------
+        actuator_pos : torch.Tensor
+            The position of the actuator.
+
+        Returns
+        -------
+        torch.Tensor
+            The required angles.
+        """
+        return actuator_pos

artist/physics_objects/alignment.py

@@ -0,0 +1,89 @@
+"""Alignment module for the heliostat."""
+
+from typing import Any, Dict, Tuple
+
+import torch
+
+
+class AlignmentModule(torch.nn.Module):
+    """
+    This class implements the alignment module for the heliostat.
+
+    Attributes
+    ----------
+    kinematic_model : Union[RigidBodyModule, ...]
+        The kinematic model used.
+
+    Methods
+    -------
+    align_surface()
+        Align given surface points and surface normals according to a calculated orientation.
+    """
+
+    def __init__(
+        self,
+        alignment_type: Any,
+        actuator_type: Any,
+        position: torch.Tensor,
+        aim_point: torch.Tensor,
+        kinematic_deviation_parameters: Dict[str, torch.Tensor],
+        kinematic_initial_orientation_offset: float,
+    ) -> None:
+        """
+        Initialize the alignment module.
+
+        Parameters
+        ----------
+        alignment_type : Any
+            The method by which the heliostat is aligned, currently only rigid-body is possible.
+        actuator_type : Any
+            The type of the actuators of the heliostat.
+        position : torch.Tensor
+            Position of the heliostat for which the alignment model is created.
+        aim_point : torch.Tensor
+            The aimpoint.
+        kinematic_deviation_parameters : Dict[str, torch.Tensor]
+            The 18 deviation parameters of the kinematic module.
+        kinematic_initial_orientation_offset : float
+            The initial orientation-rotation angle of the heliostat.
+        """
+        super().__init__()
+
+        self.kinematic_model = alignment_type(
+            actuator_type=actuator_type,
+            position=position,
+            aim_point=aim_point,
+            deviation_parameters=kinematic_deviation_parameters,
+            initial_orientation_offset=kinematic_initial_orientation_offset,
+        )
+
+    def align_surface(
+        self,
+        incident_ray_direction: torch.Tensor,
+        surface_points: torch.Tensor,
+        surface_normals: torch.Tensor,
+    ) -> Tuple[torch.Tensor, torch.Tensor]:
+        """
+        Align given surface points and surface normals according to a calculated orientation.
+
+        Parameters
+        ----------
+        incident_ray_direction : torch.Tensor
+            The direction of the rays.
+        surface_points : torch.Tensor
+            Points on the surface of the heliostat that reflect the light.
+        surface_normals : torch.Tensor
+            Normals to the surface points.
+
+        Returns
+        -------
+        torch.Tensor
+            The aligned surface points.
+        torch.Tensor
+            The aligned surface normals.
+        """
+        orientation = self.kinematic_model.align(incident_ray_direction).squeeze()
+        aligned_surface_points = (orientation @ surface_points.T).T
+        aligned_surface_normals = (orientation @ surface_normals.T).T
+
+        return (aligned_surface_points, aligned_surface_normals)

artist/physics_objects/concentrator.py

@@ -0,0 +1,37 @@
+from typing import Any
+
+import torch
+
+
+class ConcentratorModule(torch.nn.Module):
+    """
+    Implementation of the concentrator module.
+
+    Attributes
+    ----------
+    facets : List[AFacetModule]
+        The facets of the concentrator.
+    """
+
+    def __init__(
+        self,
+        facets_type: Any,
+        surface_points: torch.Tensor,
+        surface_normals: torch.Tensor,
+    ) -> None:
+        """
+        Initialize the concentrator.
+
+        Parameters
+        ----------
+        facets_type : Any
+            The facet type, for example point cloud.
+        surface_points : torch.Tensor
+            The surface points on the concentrator.
+        surface_normals : torch.Tensor
+            The corresponding normal vectors to the points.
+        """
+        super().__init__()
+        self.facets = facets_type(
+            surface_points=surface_points, surface_normals=surface_normals
+        )