Alignment optimization

This PR enables the alignment optimization feature for ARTIST

.github/workflows/python-test.yml

@@ -31,7 +31,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install pytest pytest-cov .
+          python -m pip install pytest pytest-cov pytest-mock .
 
       - name: Test with pytest and coverage badge
         run: |

artist/field/actuator.py

@@ -11,7 +11,7 @@ class Actuator(torch.nn.Module):
     ----------
     joint_number : int
         Descriptor (number) of the joint.
-    clockwise : bool
+    clockwise_axis_movement : bool
         Turning direction of the joint.
     increment : torch.Tensor
         The stroke length change per motor step.
@@ -20,30 +20,30 @@ class Actuator(torch.nn.Module):
     offset : torch.Tensor
         The offset between the linear actuator's pivoting point and the point
         around which the actuator is allowed to pivot.
-    radius : torch.Tensor
+    pivot_radius : torch.Tensor
         The actuator's pivoting radius.
-    phi_0 : torch.Tensor
+    initial_angle : torch.Tensor
         The angle that the actuator introduces to the manipulated coordinate system at the initial stroke length.
 
     Methods
     -------
+    motor_position_to_angle()
+        Calculate the joint angle for a given motor position.
+    angle_to_motor_position()
+        Calculate the motor position for a given angle.
     forward()
-        The forward kinematic.
-    motor_steps_to_angles()
-        Translate motor steps to a joint angle.
-    angles_to_motor_steps()
-        Translate a joint angle to motor steps.
+        Specify the forward pass.
     """
 
     def __init__(
         self,
         joint_number: int,
-        clockwise: bool,
+        clockwise_axis_movement: bool,
         increment: torch.Tensor,
         initial_stroke_length: torch.Tensor,
         offset: torch.Tensor,
-        radius: torch.Tensor,
-        phi_0: torch.Tensor,
+        pivot_radius: torch.Tensor,
+        initial_angle: torch.Tensor,
     ) -> None:
         """
         Initialize an abstract actuator.
@@ -59,7 +59,7 @@ def __init__(
         ----------
         joint_number : int
             Descriptor (number) of the joint.
-        clockwise : bool
+        clockwise_axis_movement : bool
             Turning direction of the joint.
         increment : torch.Tensor
             The stroke length change per motor step.
@@ -68,30 +68,30 @@ def __init__(
         offset : torch.Tensor
             The offset between the linear actuator's pivoting point and the point
             around which the actuator is allowed to pivot.
-        radius : torch.Tensor
+        pivot_radius : torch.Tensor
             The actuator's pivoting radius.
-        phi_0 : torch.Tensor
+        initial_angle : torch.Tensor
             The angle that the actuator introduces to the manipulated coordinate system at the initial stroke length.
         """
         super().__init__()
         self.joint_number = joint_number
-        self.clockwise = clockwise
+        self.clockwise_axis_movement = clockwise_axis_movement
         self.increment = increment
         self.initial_stroke_length = initial_stroke_length
         self.offset = offset
-        self.radius = radius
-        self.phi_0 = phi_0
+        self.pivot_radius = pivot_radius
+        self.initial_angle = initial_angle
 
-    def motor_steps_to_angles(
-        self, motor_steps: torch.Tensor, device: Union[torch.device, str] = "cuda"
+    def motor_position_to_angle(
+        self, motor_position: torch.Tensor, device: Union[torch.device, str] = "cuda"
     ) -> torch.Tensor:
         """
-        Translate motor steps to a joint angle.
+        Calculate the joint angle for a given motor position.
 
         Parameters
         ----------
-        motor_steps : torch.Tensor
-            The motor steps.
+        motor_position : torch.Tensor
+            The motor position.
         device : Union[torch.device, str]
             The device on which to initialize tensors (default is cuda).
 
@@ -102,16 +102,16 @@ def motor_steps_to_angles(
         """
         raise NotImplementedError("Must be overridden!")
 
-    def angles_to_motor_steps(
-        self, angles: torch.Tensor, device: Union[torch.device, str] = "cuda"
+    def angle_to_motor_position(
+        self, angle: torch.Tensor, device: Union[torch.device, str] = "cuda"
     ) -> torch.Tensor:
         """
-        Translate a joint angle to motor steps.
+        Calculate the motor position for a given angle.
 
         Parameters
         ----------
-        angles : torch.Tensor
-            The joint angles.
+        angle : torch.Tensor
+            The joint angle.
         device : Union[torch.device, str]
             The device on which to initialize tensors (default is cuda).
 
@@ -122,22 +122,13 @@ def angles_to_motor_steps(
         """
         raise NotImplementedError("Must be overridden!")
 
-    def forward(
-        self, actuator_pos: torch.Tensor, device: Union[torch.device, str] = "cuda"
-    ) -> torch.Tensor:
+    def forward(self) -> None:
         """
-        Perform forward kinematic.
-
-        Parameters
-        ----------
-        actuator_pos : torch.Tensor
-            The position of the actuator.
-        device : Union[torch.device, str]
-            The device on which to initialize tensors (default is cuda).
+        Specify the forward pass.
 
         Raises
         ------
         NotImplementedError
-            This abstract method must be overridden.
+            Whenever called.
         """
         raise NotImplementedError("Must be overridden!")

artist/field/actuator_array.py

@@ -26,6 +26,11 @@ class ActuatorArray(torch.nn.Module):
     ----------
     actuator_list : List[Actuator]
         The list of actuators to be wrapped.
+
+    Methods
+    -------
+    forward()
+        Specify the forward pass.
     """
 
     def __init__(
@@ -56,19 +61,19 @@ def __init__(
             # Try to load an actuator from the given configuration. This will fail, if ARTIST
             # does not recognize the actuator type defined in the configuration.
             try:
-                actuator_object = actuator_type_mapping[actuator_config.actuator_type]
+                actuator_object = actuator_type_mapping[actuator_config.type]
                 # Check if the actuator configuration contains actuator parameters and initialize an actuator with
                 # these parameters.
-                if actuator_config.actuator_parameters is not None:
+                if actuator_config.parameters is not None:
                     actuator_array.append(
                         actuator_object(
                             joint_number=i + 1,
-                            clockwise=actuator_config.actuator_clockwise,
-                            increment=actuator_config.actuator_parameters.increment,
-                            initial_stroke_length=actuator_config.actuator_parameters.initial_stroke_length,
-                            offset=actuator_config.actuator_parameters.offset,
-                            radius=actuator_config.actuator_parameters.radius,
-                            phi_0=actuator_config.actuator_parameters.phi_0,
+                            clockwise_axis_movement=actuator_config.clockwise_axis_movement,
+                            increment=actuator_config.parameters.increment,
+                            initial_stroke_length=actuator_config.parameters.initial_stroke_length,
+                            offset=actuator_config.parameters.offset,
+                            pivot_radius=actuator_config.parameters.pivot_radius,
+                            initial_angle=actuator_config.parameters.initial_angle,
                         )
                     )
                 # If the actuator config does not contain actuator parameters, initialize an actuator with default
@@ -80,17 +85,28 @@ def __init__(
                     actuator_array.append(
                         actuator_object(
                             joint_number=i + 1,
-                            clockwise=actuator_config.actuator_clockwise,
+                            clockwise_axis_movement=actuator_config.clockwise_axis_movement,
                             increment=torch.tensor(0.0, device=device),
                             initial_stroke_length=torch.tensor(0.0, device=device),
                             offset=torch.tensor(0.0, device=device),
-                            radius=torch.tensor(0.0, device=device),
-                            phi_0=torch.tensor(0.0, device=device),
+                            pivot_radius=torch.tensor(0.0, device=device),
+                            initial_angle=torch.tensor(0.0, device=device),
                         )
                     )
             except KeyError:
                 raise KeyError(
-                    f"Currently the selected actuator type: {actuator_config.actuator_type} is not supported."
+                    f"Currently the selected actuator type: {actuator_config.type} is not supported."
                 )
 
         self.actuator_list = actuator_array
+
+    def forward(self) -> None:
+        """
+        Specify the forward pass.
+
+        Raises
+        ------
+        NotImplementedError
+            Whenever called.
+        """
+        raise NotImplementedError("Not Implemented!")

artist/field/actuator_ideal.py

@@ -13,48 +13,48 @@ class IdealActuator(Actuator):
 
     Methods
     -------
-    motor_steps_to_angles()
-        Calculate the angles given motor steps.
-    angles_to_motor_steps()
-        Calculate the motor steps given the angles.
+    motor_position_to_angle()
+        Calculate the joint angle for a given motor position.
+    angle_to_motor_position()
+        Calculate the motor position for a given angle.
     forward()
-        Perform the forward kinematic.
+        Specify the forward pass.
 
     See Also
     --------
     :class:`Actuator` : The parent class.
     """
 
-    def motor_steps_to_angles(
-        self, motor_steps: torch.Tensor, device: Union[torch.device, str] = "cuda"
+    def motor_position_to_angle(
+        self, motor_position: torch.Tensor, device: Union[torch.device, str] = "cuda"
     ) -> torch.Tensor:
         """
-        Translate motor steps to a joint angle.
+        Calculate the joint angle for a given motor position.
 
         Parameters
         ----------
-        motor_steps : torch.Tensor
-            The motor steps.
+        motor_position : torch.Tensor
+            The motor position.
         device : Union[torch.device, str]
             The device on which to initialize tensors (default is cuda).
 
         Returns
         -------
         torch.Tensor
-            The joint angle.
+            The joint angle corresponding to the motor position.
         """
-        return motor_steps
+        return motor_position
 
-    def angles_to_motor_steps(
-        self, angles: torch.Tensor, device: Union[torch.device, str] = "cuda"
+    def angle_to_motor_position(
+        self, angle: torch.Tensor, device: Union[torch.device, str] = "cuda"
     ) -> torch.Tensor:
         """
-        Translate a joint angle to motor steps.
+        Calculate the motor position for a given angle.
 
         Parameters
         ----------
-        angles : torch.Tensor
-            The joint angles.
+        angle : torch.Tensor
+            The joint angle.
         device : Union[torch.device, str]
             The device on which to initialize tensors (default is cuda).
 
@@ -63,24 +63,15 @@ def angles_to_motor_steps(
         torch.Tensor
             The motor steps.
         """
-        return angles
+        return angle
 
-    def forward(
-        self, actuator_pos: torch.Tensor, device: Union[torch.device, str] = "cuda"
-    ) -> torch.Tensor:
+    def forward(self) -> None:
         """
-        Perform the forward kinematic for an ideal actuator.
-
-        Parameters
-        ----------
-        actuator_pos : torch.Tensor
-            The position of the actuator.
-        device : Union[torch.device, str]
-            The device on which to initialize tensors (default is cuda).
+        Specify the forward pass.
 
-        Returns
-        -------
-        torch.Tensor
-            The required angles.
+        Raises
+        ------
+        NotImplementedError
+            Whenever called.
         """
-        return actuator_pos
+        raise NotImplementedError("Not Implemented!")