ENH: adds new Function.savetxt method

CHANGELOG.md

@@ -32,6 +32,7 @@ straightforward as possible.
 
 ### Added
 
+- ENH: adds new Function.savetxt method [#514](https://github.com/RocketPy-Team/RocketPy/pull/514)
 - ENH: Argument for Optional Mutation on Function Discretize [#519](https://github.com/RocketPy-Team/RocketPy/pull/519)
 
 ### Changed
@@ -63,8 +64,8 @@ You can install this version by running `pip install rocketpy==1.1.3`
 
 ### Fixed
 
--  FIX: Broken Function.get_value_opt for N-Dimensional Functions [#492](https://github.com/RocketPy-Team/RocketPy/pull/492) 
--  FIX: Never ending Flight simulations when using a GenericMotor [#497](https://github.com/RocketPy-Team/RocketPy/pull/497) 
+- FIX: Broken Function.get_value_opt for N-Dimensional Functions [#492](https://github.com/RocketPy-Team/RocketPy/pull/492)
+- FIX: Never ending Flight simulations when using a GenericMotor [#497](https://github.com/RocketPy-Team/RocketPy/pull/497)
 
 ## [v1.1.2] - 2023-11-25
 

docs/user/function.rst

@@ -406,6 +406,38 @@ Here we have shown that we can integrate the gaussian function over a defined in
     # Compare the function with the integral
     Function.compare_plots([f, f_int], lower=-4, upper=4)
 
+e. Export to a text file (CSV or TXT)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Since rocketpy version 1.2.0, the ``Function`` class supports exporting the
+source data to a CSV or TXT file. This is accomplished by the method
+:meth:`rocketpy.Function.savetxt` and allows for easy data exportation for
+further analysis.
+
+Let's export the gaussian function to a CSV file:
+
+.. jupyter-execute::
+
+    # Define the gaussian function
+    def gaussian(x):
+        return 1 / np.sqrt(2*np.pi) * np.exp(-x**2/2)
+
+    f = Function(gaussian, inputs="x", outputs="f(x)")
+
+    # Export to CSV
+    f.savetxt("gaussian.csv", lower=-4, upper=4, samples=20, fmt="%.2f")
+
+    # Read the CSV file
+    import pandas as pd
+    pd.read_csv("gaussian.csv")
+
+
+.. jupyter-execute::
+
+    # Delete the CSV file
+    import os
+    os.remove("gaussian.csv")
+
 ........
 
 This guide shows some of the capabilities of the ``Function`` class, but there are many other functionalities to enhance your analysis. Do not hesitate in tanking a look at the documentation :class:`rocketpy.Function`.

rocketpy/mathutils/function.py

@@ -5,12 +5,12 @@
 """
 import warnings
 from collections.abc import Iterable
+from copy import deepcopy
 from inspect import signature
 from pathlib import Path
 
 import matplotlib.pyplot as plt
 import numpy as np
-from copy import deepcopy
 from scipy import integrate, linalg, optimize
 
 try:
@@ -2855,6 +2855,78 @@ def compose(self, func, extrapolate=False):
                 extrapolation=self.__extrapolation__,
             )
 
+    def savetxt(
+        self,
+        filename,
+        lower=None,
+        upper=None,
+        samples=None,
+        fmt="%.6f",
+        delimiter=",",
+        newline="\n",
+        encoding=None,
+    ):
+        """Save a Function object to a text file. The first line is the header
+        with inputs and outputs. The following lines are the data. The text file
+        can have any extension, but it is recommended to use .csv or .txt.
+
+        Parameters
+        ----------
+        filename : str
+            The name of the file to be saved, with the extension.
+        lower : float or int, optional
+            The lower bound of the range for which data is to be generated.
+            This is required if the source is a callable function.
+        upper : float or int, optional
+            The upper bound of the range for which data is to be generated.
+            This is required if the source is a callable function.
+        samples : int, optional
+            The number of sample points to generate within the specified range.
+            This is required if the source is a callable function.
+        fmt : str, optional
+            The format string for each line of the file, by default "%.6f".
+        delimiter : str, optional
+            The string used to separate values, by default ",".
+        newline : str, optional
+            The string used to separate lines in the file, by default "\n".
+        encoding : str, optional
+            The encoding to be used for the file, by default None (which means
+            using the system default encoding).
+
+        Raises
+        ------
+        ValueError
+            Raised if `lower`, `upper`, and `samples` are not provided when
+            the source is a callable function. These parameters are necessary
+            to generate the data points for saving.
+        """
+        # create the header
+        header_line = delimiter.join(self.__inputs__ + self.__outputs__)
+
+        # create the datapoints
+        if callable(self.source):
+            if lower is None or upper is None or samples is None:
+                raise ValueError(
+                    "If the source is a callable, lower, upper and samples"
+                    + " must be provided."
+                )
+            # Generate the data points using the callable
+            x = np.linspace(lower, upper, samples)
+            data_points = np.column_stack((x, self.source(x)))
+        else:
+            # If the source is already an array, use it as is
+            data_points = self.source
+
+            if lower and upper and samples:
+                data_points = self.set_discrete(
+                    lower, upper, samples, mutate_self=False
+                ).source
+
+        # export to a file
+        with open(filename, "w", encoding=encoding) as file:
+            file.write(header_line + newline)
+            np.savetxt(file, data_points, fmt=fmt, delimiter=delimiter, newline=newline)
+
     @staticmethod
     def _check_user_input(
         source,

tests/conftest.py

@@ -1166,3 +1166,18 @@ def func_2d_from_csv():
         source="tests/fixtures/function/2d.csv",
     )
     return func
+
+
+@pytest.fixture
+def lambda_quad_func():
+    """Create a lambda function based on a string.
+
+    Returns
+    -------
+    Function
+        A lambda function based on a string.
+    """
+    func = lambda x: x**2
+    return Function(
+        source=func,
+    )

tests/unit/test_function.py

@@ -1,3 +1,9 @@
+"""Unit tests for the Function class. Each method in tis module tests an 
+individual method of the Function class. The tests are made on both the
+expected behaviour and the return instances."""
+
+import os
+
 import numpy as np
 import pytest
 
@@ -160,6 +166,66 @@ def test_get_value_opt(x, y, z):
     assert np.isclose(func.get_value_opt(x, y), z, atol=1e-6)
 
 
+@pytest.mark.parametrize(
+    "func",
+    [
+        "linearly_interpolated_func",
+        "spline_interpolated_func",
+        "func_2d_from_csv",
+        "lambda_quad_func",
+    ],
+)
+def test_savetxt(request, func):
+    """Test the savetxt method of various Function objects.
+
+    This test function verifies that the `savetxt` method correctly writes the
+    function's data to a CSV file and that a new function object created from
+    this file has the same data as the original function object.
+
+    Notes
+    -----
+    The test performs the following steps:
+    1. It invokes the `savetxt` method of the given function object.
+    2. It then reads this file to create a new function object.
+    3. The test asserts that the data of the new function matches the original.
+    4. Finally, the test cleans up by removing the created CSV file.
+
+    Raises
+    ------
+    AssertionError
+        If the `savetxt` method fails to save the file, or if the data of the
+        newly read function does not match the data of the original function.
+    """
+    func = request.getfixturevalue(func)
+    assert (
+        func.savetxt(
+            filename="test_func.csv",
+            lower=0,
+            upper=9,
+            samples=10,
+            fmt="%.6f",
+            delimiter=",",
+            newline="\n",
+            encoding=None,
+        )
+        is None
+    ), "Couldn't save the file using the Function.savetxt method."
+
+    read_func = Function(
+        "test_func.csv", interpolation="linear", extrapolation="natural"
+    )
+    if callable(func.source):
+        source = np.column_stack(
+            (np.linspace(0, 9, 10), func.source(np.linspace(0, 9, 10)))
+        )
+        assert np.allclose(source, read_func.source)
+    else:
+        assert np.allclose(func.source, read_func.source)
+
+    # clean up the file
+    os.remove("test_func.csv")
+
+
 @pytest.mark.parametrize("samples", [2, 50, 1000])
 def test_set_discrete_mutator(samples):
     """Tests the set_discrete method of the Function class."""