feat: Generic cos sin from rad filter (#180)

## Description
This filter converts a variable in radian to the cosine and sine of the
variable.

## What problem does this change solve?
The available `cos_sin_mean_wave_direction` filter expects values in
degree.

## What issue or task does this change relate to?

##  Additional notes ##

***As a contributor to the Anemoi framework, please ensure that your
changes include unit tests, updates to any affected dependencies and
documentation, and have been tested in a parallel setting (i.e., with
multiple GPUs). As a reviewer, you are also responsible for verifying
these aspects and requesting changes if they are not adequately
addressed. For guidelines about those please refer to
https://anemoi.readthedocs.io/en/latest/***

By opening this pull request, I affirm that all authors agree to the
[Contributor License
Agreement.](https://github.com/ecmwf/codex/blob/main/Legal/contributor_license_agreement.md)

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: MeraX

src/anemoi/transform/filters/cos_sin_from_rad.py

@@ -0,0 +1,123 @@
+# (C) Copyright 2025 Anemoi contributors.
+#
+# This software is licensed under the terms of the Apache Licence Version 2.0
+# which can be obtained at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# In applying this licence, ECMWF does not waive the privileges and immunities
+# granted to it by virtue of its status as an intergovernmental organisation
+# nor does it submit to any jurisdiction.
+
+
+from collections.abc import Iterator
+from typing import Any
+
+import earthkit.data as ekd
+import numpy as np
+
+from anemoi.transform.filters import filter_registry
+from anemoi.transform.filters.matching import MatchingFieldsFilter
+from anemoi.transform.filters.matching import matching
+
+
+@filter_registry.register("cos_sin_from_rad")
+class CosSinFromRad(MatchingFieldsFilter):
+    """A filter to convert any variable in radians to cos() and sin() and back."""
+
+    @matching(
+        select="param",
+        forward=("param",),
+        backward=("cos_param", "sin_param"),
+    )
+    def __init__(
+        self,
+        param: str,
+        cos_param: str | None = None,
+        sin_param: str | None = None,
+    ) -> None:
+        """Initialize the CosSinFromRad filter.
+
+        Parameters
+        ----------
+        param : str
+            The name of the variable.
+        cos_param : str, optional
+            The name of the cosine of the variable. Default is to prefix "cos_".
+        sin_param : str, optional
+            The name of the sine of the variable. Default is to prefix "sin_".
+        """
+
+        self.param = param
+        self.cos_param = cos_param if cos_param is not None else f"cos_{param}"
+        self.sin_param = sin_param if sin_param is not None else f"sin_{param}"
+
+    def forward_transform(
+        self,
+        param: ekd.Field,
+    ) -> Iterator[ekd.Field]:
+        """Convert a direction variable to its cosine and sine components.
+
+        Parameters
+        ----------
+        param : ekd.Field
+            The direction field.
+
+        Returns
+        -------
+        Iterator[ekd.Field]
+            Fields of cosine and sine of the direction.
+        """
+        data = param.to_numpy()
+        if (min := data.min()) < -2 * np.pi:
+            raise ValueError(f"Param {self.param} is expected in radians in the range [-2pi, pi], but {min=}")
+        if (max := data.max()) > 2 * np.pi:
+            raise ValueError(f"Param {self.param} is expected in radians in the range [-2pi, pi], but {max=}")
+
+        yield self.new_field_from_numpy(np.cos(data), template=param, param=self.cos_param)
+        yield self.new_field_from_numpy(np.sin(data), template=param, param=self.sin_param)
+
+    def backward_transform(
+        self,
+        cos_param: ekd.Field,
+        sin_param: ekd.Field,
+    ) -> Iterator[ekd.Field]:
+        """Convert cosine and sine components back to direction in radians in the range [-pi, pi).
+
+        Parameters
+        ----------
+        cos_param : ekd.Field
+            The cosine of the direction field.
+        sin_param : ekd.Field
+            The sine of the  direction field.
+
+        Returns
+        -------
+        Iterator[ekd.Field]
+            Field of the direction.
+        """
+        direction = np.arctan2(sin_param.to_numpy(), cos_param.to_numpy())
+
+        yield self.new_field_from_numpy(direction, template=cos_param, param=self.param)
+
+    def patch_data_request(self, data_request: dict[str, Any]) -> dict[str, Any]:
+        """Modify the data request to include the direction.
+
+        Parameters
+        ----------
+        data_request : Dict[str, Any]
+            The original data request.
+
+        Returns
+        -------
+        Dict[str, Any]
+            The modified data request.
+        """
+
+        param = data_request.get("param")
+        if param is None:
+            return data_request
+
+        if self.cos_param in param or self.sin_param in param:
+            data_request["param"] = [p for p in param if p not in (self.cos_param, self.sin_param)]
+            data_request["param"].append(self.param)
+
+        return data_request

tests/test_cos_sin_from_rad.py

@@ -0,0 +1,134 @@
+# (C) Copyright 2025 Anemoi contributors.
+#
+# This software is licensed under the terms of the Apache Licence Version 2.0
+# which can be obtained at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# In applying this licence, ECMWF does not waive the privileges and immunities
+# granted to it by virtue of its status as an intergovernmental organisation
+# nor does it submit to any jurisdiction.
+import numpy as np
+import pytest
+
+from anemoi.transform.filters import filter_registry
+
+from .utils import assert_fields_equal
+from .utils import collect_fields_by_param
+
+MOCK_FIELD_METADATA = {
+    "latitudes": [10.0, 0.0, -10.0],
+    "longitudes": [20, 40.0],
+    "valid_datetime": "2018-08-01T09:00:00Z",
+}
+
+RAD_VALUES = np.array([[2.67687254, 2.59108576], [1.83746659, 1.73104875], [1.1348185, 2.23051268]])
+
+COS_RAD_VALUES = np.array([[-0.89394704, -0.85225947], [-0.26352086, -0.15956740], [0.42229696, -0.61289275]])
+
+SIN_RAD_VALUES = np.array([[0.44817262, 0.52311930], [0.96465370, 0.98718704], [0.90645754, 0.79016611]])
+
+
+@pytest.fixture
+def RAD_source(test_source):
+    RAD_SPEC = [
+        {"param": "RAD", "values": RAD_VALUES, **MOCK_FIELD_METADATA},
+    ]
+    return test_source(RAD_SPEC)
+
+
+@pytest.fixture
+def DEG_source(test_source):
+    DEG_SPEC = [
+        {"param": "DEG", "values": np.rad2deg(RAD_VALUES), **MOCK_FIELD_METADATA},
+    ]
+    return test_source(DEG_SPEC)
+
+
+@pytest.fixture
+def cos_sin_RAD_source(test_source):
+    COS_SIN_RAD = [
+        {"param": "cos_RAD", "values": COS_RAD_VALUES, **MOCK_FIELD_METADATA},
+        {"param": "sin_RAD", "values": SIN_RAD_VALUES, **MOCK_FIELD_METADATA},
+    ]
+    return test_source(COS_SIN_RAD)
+
+
+def test_forward(RAD_source):
+    """Test the cos_sin_from_rad filter."""
+    filter = filter_registry.create(
+        "cos_sin_from_rad",
+        param="RAD",
+    )
+    pipeline = RAD_source | filter
+
+    output_fields = collect_fields_by_param(pipeline)
+
+    assert set(output_fields) == {"cos_RAD", "sin_RAD"}
+    assert len(output_fields["cos_RAD"]) == 1
+    assert len(output_fields["sin_RAD"]) == 1
+
+    np.testing.assert_allclose(output_fields["cos_RAD"][0].to_numpy(), COS_RAD_VALUES)
+    np.testing.assert_allclose(output_fields["sin_RAD"][0].to_numpy(), SIN_RAD_VALUES)
+
+
+def test_reverse(cos_sin_RAD_source):
+    """Test the cos_sin_from_rad filter in reverse."""
+    filter = filter_registry.create(
+        "cos_sin_from_rad",
+        param="some_rad",
+        cos_param="cos_RAD",
+        sin_param="sin_RAD",
+    ).reverse()
+    pipeline = cos_sin_RAD_source | filter
+
+    output_fields = collect_fields_by_param(pipeline)
+
+    assert set(output_fields) == {"some_rad"}
+    assert len(output_fields["some_rad"]) == 1
+
+    np.testing.assert_allclose(output_fields["some_rad"][0].to_numpy(), RAD_VALUES)
+
+
+def test_round_trip(RAD_source):
+    """Test the cos_sin_from_rad filter reproduces inputs on a round trip."""
+    filter = filter_registry.create(
+        "cos_sin_from_rad",
+        param="RAD",
+    )
+    cos_sin_RAD_source = RAD_source | filter
+    pipeline = cos_sin_RAD_source | filter.reverse()
+
+    input_fields = collect_fields_by_param(RAD_source)
+    intermediate_fields = collect_fields_by_param(cos_sin_RAD_source)
+    output_fields = collect_fields_by_param(pipeline)
+
+    assert set(input_fields) == {"RAD"}
+    assert set(intermediate_fields) == {"cos_RAD", "sin_RAD"}
+    assert set(output_fields) == {"RAD"}
+
+    for input_field, output_field in zip(input_fields["RAD"], output_fields["RAD"]):
+        assert_fields_equal(input_field, output_field)
+
+
+def test_exception(DEG_source):
+    """Test the cos_sin_from_rad exception.
+
+    Inpupt data in degrees.
+    """
+    filter = filter_registry.create(
+        "cos_sin_from_rad",
+        param="DEG",
+    )
+    pipeline = DEG_source | filter
+
+    with pytest.raises(ValueError):
+        collect_fields_by_param(pipeline)
+
+
+if __name__ == "__main__":
+    """
+    Run all test functions that start with 'test_'.
+    """
+    for name, obj in list(globals().items()):
+        if name.startswith("test_") and callable(obj):
+            print(f"Running {name}...")
+            obj()