Merge branch 'develop' into copilot/enhance-drag-curve-functionality

Author: aZira371

CHANGELOG.md

@@ -33,14 +33,20 @@ Attention: The newest changes should be on top -->
 ### Added
 
 - ENH: Add multi-dimensional drag coefficient support (Cd as function of M, Re, α) [#875](https://github.com/RocketPy-Team/RocketPy/pull/875)
+- ENH: Add save functionality to `_MonteCarloPlots.all` method [#848](https://github.com/RocketPy-Team/RocketPy/pull/848)
+- ENH: Add persistent caching for ThrustCurve API [#881](https://github.com/RocketPy-Team/RocketPy/pull/881)
+- ENH: Compatibility with MERRA-2 atmosphere reanalysis files [#825](https://github.com/RocketPy-Team/RocketPy/pull/825)
 - ENH: Enable only radial burning [#815](https://github.com/RocketPy-Team/RocketPy/pull/815)
 - ENH: Add thrustcurve api integration to retrieve motor eng data [#870](https://github.com/RocketPy-Team/RocketPy/pull/870)
-- ENH: Custom Exception errors and messages [#285](https://github.com/RocketPy-Team/RocketPy/issues/285)
+- ENH: custom warning no motor or aerosurface [#871](https://github.com/RocketPy-Team/RocketPy/pull/871)
 
 ### Changed
 
+-
+
 ### Fixed
 
+- BUG: Fix parallel Monte Carlo simulation showing incorrect iteration count [#806](https://github.com/RocketPy-Team/RocketPy/pull/806)
 - BUG: Fix CSV column header spacing in FlightDataExporter [#864](https://github.com/RocketPy-Team/RocketPy/issues/864)
 
 

docs/user/environment/1-atm-models/reanalysis.rst

@@ -46,6 +46,27 @@ ERA5 data can be downloaded from the
     processed by RocketPy. It is recommended that you download only the \
     necessary data.
 
+MERRA-2
+-------
+
+The Modern-Era Retrospective analysis for Research and Applications, Version 2 (MERRA-2) is a NASA atmospheric reanalysis for the satellite era using the Goddard Earth Observing System, Version 5 (GEOS-5) with its Atmospheric Data Assimilation System (ADAS).
+
+You can download these files from the `NASA GES DISC <https://disc.gsfc.nasa.gov/>`_.
+
+To use MERRA-2 data in RocketPy, you generally need the **Assimilated Meteorological Fields** collection (specifically the 3D Pressure Level data, usually named ``inst3_3d_asm_Np``). Note that MERRA-2 files typically use the ``.nc4`` extension (NetCDF-4), which is fully supported by RocketPy.
+
+You can load these files using the ``dictionary="MERRA2"`` argument:
+
+.. code-block:: python
+
+    env.set_atmospheric_model(
+        type="Reanalysis",
+        file="MERRA2_400.inst3_3d_asm_Np.20230620.nc4",
+        dictionary="MERRA2"
+    )
+
+RocketPy automatically handles the unit conversion for MERRA-2's surface geopotential (energy) to geometric height (meters).
+
 
 Setting the Environment
 ^^^^^^^^^^^^^^^^^^^^^^^

docs/user/environment/1-atm-models/standard_atmosphere.rst

@@ -22,8 +22,7 @@ Other profiles can be derived from it, however, winds are automatically set to
 
     env.plots.atmospheric_model()
 
-.. skip one line with |
-| 
+|
 
 The International Standard Atmosphere can also be reset at any time by using the
 :meth:`rocketpy.Environment.set_atmospheric_model` method. For example:

docs/user/first_simulation.rst

@@ -90,6 +90,7 @@ regarding the launch site:
 
 | This roughly corresponds to the location of Spaceport America, New Mexico.
 
+
 Next, we need to specify the atmospheric model to be used. In this example,
 we will get GFS forecasts data from tomorrow.
 
@@ -110,6 +111,7 @@ of tomorrow:
 
 | Now we set the atmospheric model to be used:
 
+
 .. jupyter-execute::
 
     env.set_atmospheric_model(type="Forecast", file="GFS")
@@ -189,6 +191,7 @@ to specify several parameters:
 
 | We can see its characteristics by calling the info method:
 
+
 .. jupyter-execute::
 
     Pro75M1670.info()
@@ -637,8 +640,9 @@ and the rocket Mach number (see :meth:`rocketpy.Flight.mach_number`) to the file
     )
 
 | As you can see, the first argument is the file name to be created. The following
-arguments are the attributes to be exported. We can check the file by reading it
-with :func:`pandas.read_csv`:
+  arguments are the attributes to be exported. We can check the file by reading it
+  with :func:`pandas.read_csv`:
+
 
 .. jupyter-execute::
 
@@ -647,8 +651,9 @@ with :func:`pandas.read_csv`:
     pd.read_csv("calisto_flight_data.csv")
 
 | The file header specifies the meaning of each column. The time samples are
-obtained from the simulation solver steps. To export the data at a different
-sampling rate, use the ``time_step`` argument:
+  obtained from the simulation solver steps. To export the data at a different
+  sampling rate, use the ``time_step`` argument:
+
 
 .. jupyter-execute::
 

docs/user/motors/genericmotor.rst

@@ -109,17 +109,29 @@ note that the user can still provide the parameters manually if needed.
 The ``load_from_thrustcurve_api`` method
 ----------------------------------------
 
-The ``GenericMotor`` class provides a convenience loader that downloads a temporary
+The ``GenericMotor`` class provides a convenience loader that downloads an
 `.eng` file from the ThrustCurve.org public API and builds a ``GenericMotor``
 instance from it. This is useful when you know a motor designation (for example
-``"M1670"``) but do not want to manually download and
-save the `.eng` file.
+``"M1670"``) but do not want to manually download and save the `.eng` file.
+
+The method also includes automatic caching for faster repeated usage.  
+Downloaded `.eng` files are stored in the user's RocketPy cache folder
+(``~/.rocketpy_cache``). When a subsequent request is made for the same motor,
+the cached copy is used instead of performing another network request.
+
+You can bypass the cache by setting ``no_cache=True``:
+
+- ``no_cache=False`` (default):  
+  Use a cached file if available; otherwise download and store it.
+
+- ``no_cache=True``:  
+  Always fetch a fresh version from the API and overwrite the cache.
 
 .. note::
 
-    This method performs network requests to the ThrustCurve API. Use it only
-    when you have network access. For automated testing or reproducible runs,
-    prefer using local `.eng` files.
+    This method performs network requests to the ThrustCurve API unless a cached
+    version exists. For automated testing or fully reproducible workflows, prefer
+    local `.eng` files or set ``no_cache=True`` explicitly.
 
 Example
 -------
@@ -128,8 +140,19 @@ Example
 
     from rocketpy.motors import GenericMotor
 
-    # Build a motor by name (requires network access)
+    # Build a motor by name (requires network access unless cached)
     motor = GenericMotor.load_from_thrustcurve_api("M1670")
 
-    # Use the motor as usual
+    # Print the motor information
+    motor.info()
+
+Using the no_cache option
+-------------------------
+
+If you want to force RocketPy to ignore the cache and download a fresh copy
+every time, use:
+
+.. jupyter-execute::
+
+    motor = GenericMotor.load_from_thrustcurve_api("M1670", no_cache=True)
     motor.info()

docs/user/three_dof_simulation.rst

@@ -67,7 +67,7 @@ The environment setup is identical to standard simulations:
         elevation=1400
     )
 
-    env.set_atmospheric_model(type="StandardAtmosphere")
+    env.set_atmospheric_model(type="standard_atmosphere")
 
 Step 2: Create a PointMassMotor
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -123,7 +123,7 @@ Or use a custom thrust function:
 .. seealso::
 
     For detailed information about :class:`rocketpy.PointMassMotor` parameters,
-    see the :ref:`API reference <api_reference>`.
+    see the :class:`rocketpy.PointMassMotor` class documentation.
 
 Step 3: Create a PointMassRocket
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -279,6 +279,14 @@ Export trajectory data to CSV:
         "vz",
     )
 
+
+.. jupyter-execute::
+    :hide-code:
+
+    import os
+    os.remove("trajectory_3dof.csv")
+
+
 Complete Example
 ----------------
 
@@ -294,7 +302,7 @@ Here's a complete 3-DOF simulation from start to finish:
         longitude=-8.2889,
         elevation=100
     )
-    env.set_atmospheric_model(type="StandardAtmosphere")
+    env.set_atmospheric_model(type="standard_atmosphere")
 
     # 2. Motor
     motor = PointMassMotor(
@@ -412,7 +420,6 @@ See Also
 - :ref:`First Simulation <firstsimulation>` - Standard 6-DOF simulation tutorial
 - :ref:`Rocket Class Usage <rocketusage>` - Full rocket modeling capabilities
 - :ref:`Flight Class Usage <flightusage>` - Complete flight simulation options
-- :doc:`../examples/3_dof_trial_sim` - Jupyter notebook example
 
 Further Reading
 ---------------

rocketpy/environment/environment.py

@@ -607,7 +607,7 @@ def __set_earth_rotation_vector(self):
 
     def __validate_dictionary(self, file, dictionary):
         # removed CMC until it is fixed.
-        available_models = ["GFS", "NAM", "RAP", "HIRESW", "GEFS", "ERA5"]
+        available_models = ["GFS", "NAM", "RAP", "HIRESW", "GEFS", "ERA5", "MERRA2"]
         if isinstance(dictionary, str):
             dictionary = self.__weather_model_map.get(dictionary)
         elif file in available_models:
@@ -1186,7 +1186,7 @@ def set_atmospheric_model(  # pylint: disable=too-many-statements
             ``Reanalysis`` or ``Ensemble``. It specifies the dictionary to be
             used when reading ``netCDF`` and ``OPeNDAP`` files, allowing the
             correct retrieval of data. Acceptable values include ``ECMWF``,
-            ``NOAA`` and ``UCAR`` for default dictionaries which can generally
+            ``NOAA``, ``UCAR`` and ``MERRA2`` for default dictionaries which can generally
             be used to read datasets from these institutes. Alternatively, a
             dictionary structure can also be given, specifying the short names
             used for time, latitude, longitude, pressure levels, temperature
@@ -1893,10 +1893,20 @@ def process_forecast_reanalysis(self, file, dictionary):  # pylint: disable=too-
         self._max_expected_height = max(height[0], height[-1])
 
         # Get elevation data from file
-        if dictionary["surface_geopotential_height"] is not None:
+        if dictionary.get("surface_geopotential_height") is not None:
             self.elevation = get_elevation_data_from_dataset(
                 dictionary, data, time_index, lat_index, lon_index, x, y, x1, x2, y1, y2
             )
+        # 2. If not found, try Geopotential (m^2/s^2) and convert
+        elif dictionary.get("surface_geopotential") is not None:
+            temp_dict = dictionary.copy()
+            temp_dict["surface_geopotential_height"] = dictionary[
+                "surface_geopotential"
+            ]
+            surface_geopotential_value = get_elevation_data_from_dataset(
+                temp_dict, data, time_index, lat_index, lon_index, x, y, x1, x2, y1, y2
+            )
+            self.elevation = surface_geopotential_value / self.standard_g
 
         # Compute info data
         self.atmospheric_model_init_date = get_initial_date_from_time_array(time_array)

rocketpy/environment/weather_model_mapping.py

@@ -114,6 +114,19 @@ class WeatherModelMapping:
         "u_wind": "ugrdprs",
         "v_wind": "vgrdprs",
     }
+    MERRA2 = {
+        "time": "time",
+        "latitude": "lat",
+        "longitude": "lon",
+        "level": "lev",
+        "temperature": "T",
+        "surface_geopotential_height": None,
+        "surface_geopotential": "PHIS",  # special key for Geopotential (m^2/s^2)
+        "geopotential_height": "H",
+        "geopotential": None,
+        "u_wind": "U",
+        "v_wind": "V",
+    }
 
     def __init__(self):
         """Initialize the class, creates a dictionary with all the weather models
@@ -129,6 +142,7 @@ def __init__(self):
             "CMC": self.CMC,
             "GEFS": self.GEFS,
             "HIRESW": self.HIRESW,
+            "MERRA2": self.MERRA2,
         }
 
     def get(self, model):

rocketpy/motors/motor.py

@@ -6,6 +6,7 @@
 from abc import ABC, abstractmethod
 from functools import cached_property
 from os import path, remove
+from pathlib import Path
 
 import numpy as np
 import requests
@@ -15,8 +16,11 @@
 from ..prints.motor_prints import _MotorPrints
 from ..tools import parallel_axis_theorem_from_com, tuple_handler
 
-
 # pylint: disable=too-many-public-methods
+# ThrustCurve API cache
+CACHE_DIR = Path.home() / ".rocketpy_cache"
+
+
 class Motor(ABC):
     """Abstract class to specify characteristics and useful operations for
     motors. Cannot be instantiated.
@@ -1918,7 +1922,7 @@ def load_from_rse_file(
         )
 
     @staticmethod
-    def _call_thrustcurve_api(name: str):
+    def _call_thrustcurve_api(name: str, no_cache: bool = False):  # pylint: disable=too-many-statements
         """
         Download a .eng file from the ThrustCurve API
         based on the given motor name.
@@ -1929,6 +1933,8 @@ def _call_thrustcurve_api(name: str):
             The motor name according to the API (e.g., "Cesaroni_M1670" or "M1670").
             Both manufacturer-prefixed and shorthand names are commonly used; if multiple
             motors match the search, the first result is used.
+        no_cache : bool, optional
+            If True, forces a new API fetch even if the motor is cached.
 
         Returns
         -------
@@ -1941,9 +1947,31 @@ def _call_thrustcurve_api(name: str):
             If no motor is found or if the downloaded .eng data is missing.
         requests.exceptions.RequestException
             If a network or HTTP error occurs during the API call.
+
+        Notes
+        -----
+        - The cache prevents multiple network requests for the same motor name across sessions.
+        - Cached files are stored in `~/.rocketpy_cache` and reused unless `no_cache=True`.
+        - Filenames are sanitized to avoid invalid characters.
         """
-        base_url = "https://www.thrustcurve.org/api/v1"
+        try:
+            CACHE_DIR.mkdir(exist_ok=True)
+        except OSError as e:
+            warnings.warn(f"Could not create cache directory: {e}. Caching disabled.")
+            no_cache = True
+        # File path in the cache
+        safe_name = re.sub(r"[^A-Za-z0-9_.-]", "_", name)
+        cache_file = CACHE_DIR / f"{safe_name}.eng.b64"
+        if not no_cache and cache_file.exists():
+            try:
+                return cache_file.read_text()
+            except (OSError, UnicodeDecodeError) as e:
+                warnings.warn(
+                    f"Failed to read cached motor file '{cache_file}': {e}. "
+                    "Fetching fresh data from API."
+                )
 
+        base_url = "https://www.thrustcurve.org/api/v1"
         # Step 1. Search motor
         response = requests.get(f"{base_url}/search.json", params={"commonName": name})
         response.raise_for_status()
@@ -1979,10 +2007,20 @@ def _call_thrustcurve_api(name: str):
             raise ValueError(
                 f"Downloaded .eng data for motor '{name}' is empty or invalid."
             )
+        if not no_cache:
+            try:
+                cache_file.write_text(data_base64)
+            except (OSError, PermissionError) as e:
+                warnings.warn(
+                    f"Could not write to cache file '{cache_file}': {e}. "
+                    "Continuing without caching.",
+                    RuntimeWarning,
+                )
+
         return data_base64
 
     @staticmethod
-    def load_from_thrustcurve_api(name: str, **kwargs):
+    def load_from_thrustcurve_api(name: str, no_cache: bool = False, **kwargs):
         """
         Creates a Motor instance by downloading a .eng file from the ThrustCurve API
         based on the given motor name.
@@ -2010,7 +2048,7 @@ def load_from_thrustcurve_api(name: str, **kwargs):
             If a network or HTTP error occurs during the API call.
         """
 
-        data_base64 = GenericMotor._call_thrustcurve_api(name)
+        data_base64 = GenericMotor._call_thrustcurve_api(name, no_cache=no_cache)
         data_bytes = base64.b64decode(data_base64)
 
         # Step 3. Create the motor from the .eng file