feat(env): add wavy projection system and relevant tests

- Introduced the wavy projection system for 2D motion projected on a 3D
  sinusoidal surface with equations for partial derivatives and rollouts.
- Added tests to validate system behavior, including various edge cases
  and conditions.
- Integrated the system into the pipeline and created new configuration
  files for its simulation and testing scenarios.

Author: RedLeader962

src/math_gymnasium/dynamical_systems/__init__.py

@@ -20,6 +20,9 @@
 from .non_linear_system.simple_limit_cycle_system_van_der_pol import (
     rollout_simple_limit_cycle_partial_derivative,
 )
+from .non_linear_system.wavy_projection_system import (
+    rollout_wavy_projection_partial_derivative,
+)
 from .linear_debug_system import rollout_linear_debug_system
 
 __all__ = [
@@ -32,5 +35,6 @@
     "rollout_aizawa_attractor_partial_derivative",
     "rollout_damped_oscillator_partial_derivative",
     "rollout_simple_limit_cycle_partial_derivative",
+    "rollout_wavy_projection_partial_derivative",
     "rollout_linear_debug_system",
 ]

src/math_gymnasium/dynamical_systems/non_linear_system/wavy_projection_system.py

@@ -0,0 +1,95 @@
+# coding=utf-8
+
+import numpy as np
+
+from tools.math_tools.ndarray_tools.custom_msg import nan_infinity_console_warning
+from tools.math_tools.space_conversion_tools.time_to_delta_time import (
+    convert_state_time_to_state_delta_time,
+)
+
+
+def wavy_projection_partial_derivative(
+    xyz: np.ndarray,
+    vx: float = 1.0,
+    vy: float = 1.0,
+    dtype: np.dtype = np.float64,
+    debug: bool = False,
+):
+    """
+    Computes the partial derivatives for a wavy projection system.
+    This is a 2D linear motion in (x, y) projected onto a 3D sinusoidal surface.
+
+    System equations:
+    dx/dt = vx
+    dy/dt = vy
+    dz/dt = cos(x)*vx - sin(y)*vy  =>  (Integration: z = sin(x) + cos(y) + C)
+
+    :param xyz: An array containing the x, y, and z coordinates.
+    :param vx: Velocity in x direction.
+    :param vy: Velocity in y direction.
+    :param dtype: Data type for computations.
+    :param debug: Warn if nan or infinity values are encountered.
+    :return: An array containing the partial derivatives [x_dot, y_dot, z_dot].
+    """
+    xyz = np.nan_to_num(xyz)
+    x, y, z = xyz.astype(dtype)
+
+    x_dot = vx
+    y_dot = vy
+    # z is the projection on sin(x) + cos(y)
+    # dz/dt = d(sin(x) + cos(y))/dt = cos(x)*dx/dt - sin(y)*dy/dt
+    z_dot = np.cos(x) * vx - np.sin(y) * vy
+
+    xyz_dot = np.array([x_dot, y_dot, z_dot], dtype=dtype)
+
+    if debug and not np.all(np.isfinite(xyz_dot)):
+        nan_infinity_console_warning("xyz_dot")
+
+    xyz_dot = np.nan_to_num(xyz_dot)
+    return xyz_dot.squeeze()
+
+
+def rollout_wavy_projection_partial_derivative(
+    time_space: np.ndarray,
+    vx: float = 1.0,
+    vy: float = 1.0,
+    initiale_coordinates=(0.0, 0.0, 1.0), # z = sin(0) + cos(0) = 1.0
+    time_space_is_delta_time: bool = False,
+    dtype: np.dtype = np.float64,
+) -> np.ndarray:
+    """
+    Calculates the trajectory of a wavy projection system over a given time space.
+
+    Assume `time_space` values are increasing if `time_space_is_delta_time=True`
+
+    :param time_space: Array representing time steps in wallclock time or delta time.
+    :param vx: Velocity in x direction.
+    :param vy: Velocity in y direction.
+    :param initiale_coordinates: The state at timestep 0
+    :param time_space_is_delta_time: Set to True if `time_space` is an array of delta time.
+    :param dtype: Data type for computations.
+    :return: Array of computed x, y, z coordinates over the given time space.
+    """
+    assert isinstance(initiale_coordinates, tuple) and len(initiale_coordinates) == 3
+    assert isinstance(time_space, np.ndarray) and time_space.ndim == 1
+
+    xyzs = np.empty((time_space.size, 3), dtype=dtype)
+    xyzs_partial_derivative = np.empty_like(xyzs)
+
+    xyzs[0] = initiale_coordinates
+    xyzs_partial_derivative[0] = (0.0, 0.0, 0.0)
+
+    if not time_space_is_delta_time:
+        delta_time = convert_state_time_to_state_delta_time(time_space.astype(dtype))
+    else:
+        delta_time = time_space.copy().astype(dtype)
+
+    for i in np.arange(time_space.size - 1):
+        xyzs_partial_derivative[i + 1] = wavy_projection_partial_derivative(
+            xyzs[i], vx, vy, dtype
+        )
+        xyzs[i + 1] = xyzs[i] + xyzs_partial_derivative[i + 1] * delta_time[i + 1]
+
+    assert np.all(np.isfinite(xyzs_partial_derivative))
+    assert np.all(np.isfinite(xyzs))
+    return xyzs

tests/tests_tools/tests_non_linear_system/test_wavy_projection_system.py

@@ -0,0 +1,59 @@
+# coding=utf-8
+from typing import Tuple
+
+import numpy as np
+import pytest
+
+from math_gymnasium.dynamical_systems.non_linear_system.wavy_projection_system import (
+    rollout_wavy_projection_partial_derivative,
+)
+
+
+@pytest.fixture
+def setup_wavy_projection_sys_spaces() -> Tuple[
+    np.ndarray,
+    Tuple[float, float, float],
+]:
+    t_time_space = np.arange(10) * 0.1
+    t_init_coord = (0.0, 0.0, 1.0)
+    return t_time_space, t_init_coord
+
+
+class TestRolloutWavyProjectionPartialDerivative:
+    def test_default(self, setup_wavy_projection_sys_spaces):
+        (t_time_space, t_init_coord) = setup_wavy_projection_sys_spaces
+        t_time_space_freeze = t_time_space.copy()
+        coords = rollout_wavy_projection_partial_derivative(
+            t_time_space, vx=1.0, vy=1.0, initiale_coordinates=t_init_coord,
+        )
+        assert np.array_equal(
+            t_time_space_freeze, t_time_space
+        ), "original array was overridden"
+        assert coords.shape == (t_time_space.shape[0], 3)
+        
+        # Check if x and y are linear
+        # x = 0.0, 0.1, 0.2, ...
+        # y = 0.0, 0.1, 0.2, ...
+        assert np.allclose(coords[:, 0], t_time_space)
+        assert np.allclose(coords[:, 1], t_time_space)
+        
+        # Check if z is roughly sin(x) + cos(y)
+        # For the first few steps, z should be close to sin(x) + cos(y)
+        # Note: integration might have some error, so we just check it's not linear
+        z_expected = np.sin(coords[:, 0]) + np.cos(coords[:, 1])
+        # Since it's Euler integration, it won't be exact
+        # We just check it follows the trend
+        assert not np.allclose(coords[:, 2], coords[0, 2] + (coords[1, 2] - coords[0, 2]) * np.arange(10))
+
+    def test_output_coord_using_delta_time(self, setup_wavy_projection_sys_spaces):
+        (t_time_space, t_init_coord) = setup_wavy_projection_sys_spaces
+        t_dt_space = np.ones_like(t_time_space) * 0.1
+        t_dt_space[0] = 0.0
+        
+        coord = rollout_wavy_projection_partial_derivative(
+            t_dt_space, vx=1.0, vy=1.0, initiale_coordinates=t_init_coord, time_space_is_delta_time=True
+        )
+        assert coord.shape == (t_time_space.shape[0], 3)
+        # Initial z is 1.0. 
+        # Next z = 1.0 + (cos(0)*1 - sin(0)*1)*0.1 = 1.0 + 0.1 = 1.1
+        assert np.allclose(coord[1, 2], 1.1)