Merge remote-tracking branch 'origin/master' into develop

Author: MateusStano

docs/conf.py

@@ -27,7 +27,7 @@
 author = "RocketPy Team"
 
 # The full version, including alpha/beta/rc tags
-release = "1.12.0"
+release = "1.12.1"
 
 
 # -- General configuration ---------------------------------------------------

docs/user/compare_flights.rst

@@ -26,8 +26,8 @@ This is done following the same steps as in the :ref:`firstsimulation` example.
 
 .. jupyter-execute::
 
-      after_tomorrow = datetime.now() + timedelta(days=2)
-      env = Environment(latitude=-23, longitude=-49, date=after_tomorrow)
+      tomorrow = datetime.now() + timedelta(days=1)
+      env = Environment(latitude=-23, longitude=-49, date=tomorrow)
       env.set_atmospheric_model(type="Forecast", file="GFS")
 
       cesaroni_motor = SolidMotor(

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

@@ -1,3 +1,5 @@
+.. _ensemble_atmosphere:
+
 Ensemble
 ========
 
@@ -21,7 +23,21 @@ Ensemble Forecast
 Global Ensemble Forecast System (GEFS)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The ``GEFS`` model is a global ensemble forecast model ...
+.. danger::
+
+    **GEFS shortcut unavailable**: ``file="GEFS"`` is currently disabled in
+    RocketPy because NOMADS OPeNDAP is deactivated for this endpoint.
+
+.. note::
+
+    If you have a GEFS-compatible NetCDF or OPeNDAP dataset from another
+    provider (or a local copy), you can still load it explicitly by passing the
+    dataset path/URL in ``file`` and a compatible mapping in ``dictionary``.
+
+
+The ``GEFS`` model is a global ensemble forecast system useful for uncertainty
+analysis, but RocketPy's automatic ``file="GEFS"`` shortcut is temporarily
+disabled.
 
 
 .. code-block:: python
@@ -71,20 +87,16 @@ CMC Ensemble
     resulted in a change of the model's endpoint. Efforts are underway to \
     restore access to the CMC Ensemble model as swiftly as possible.
 
-.. code-block:: python
+At the moment, there is no built-in ``file="CMC"`` shortcut in
+``Environment.set_atmospheric_model``.
 
-    env_cmc = Environment(
-        date=date_info,
-        latitude=-21.960641,
-        longitude=-47.482122,
-        elevation=640,
-    )
-    env_cmc.set_atmospheric_model(type="Ensemble", file="CMC")
-    env_cmc.all_info()
+If you have a CMC-compatible NetCDF or OPeNDAP dataset, load it explicitly by
+passing the dataset path/URL in ``file`` and a matching mapping dictionary in
+``dictionary``.
 
 
 Ensemble Reanalysis
 -------------------
 
 Ensemble reanalyses are also possible with RocketPy. See the
-:ref:`reanalysis_ensemble` section for more information.
+:ref:`reanalysis_ensemble` section for more information.

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

@@ -24,7 +24,7 @@ Global Forecast System (GFS)
 
 Using the latest forecast from GFS is simple.
 Set the atmospheric model to ``forecast`` and specify that GFS is the file you want.
-Note that since data is downloaded from the NOMADS server, this line of code can
+Note that since data is downloaded from a remote OPeNDAP server, this line of code can
 take longer than usual.
 
 .. jupyter-execute::
@@ -111,36 +111,15 @@ The same coordinates for SpacePort America will be used.
 High Resolution Window (HIRESW)
 -------------------------------
 
-The High Resolution Window (HIRESW) model is a sophisticated weather forecasting
-system that operates at a high spatial resolution of approximately 3 km.
-It utilizes two main dynamical cores: the Advanced Research WRF (WRF-ARW) and
-the Finite Volume Cubed Sphere (FV3), each designed to enhance the accuracy of
-weather predictions.
+.. danger::
 
-You can easily set up HIRESW in RocketPy by specifying the date, latitude, and
-longitude of your location. Let's use SpacePort America as an example.
+    **HIRESW shortcut unavailable**: ``file="HIRESW"`` is currently disabled in
+    RocketPy because NOMADS OPeNDAP is deactivated for this endpoint.
 
-.. jupyter-execute::
-
-    env_hiresw = Environment(
-        date=tomorrow,
-        latitude=32.988528,
-        longitude=-106.975056,
-    )
+If you have a HIRESW-compatible dataset from another provider (or a local copy),
+you can still load it explicitly by passing the path/URL in ``file`` and an
+appropriate mapping in ``dictionary``.
 
-    env_hiresw.set_atmospheric_model(
-        type="Forecast",
-        file="HIRESW",
-        dictionary="HIRESW",
-    )
-
-    env_hiresw.plots.atmospheric_model()
-
-.. note::
-
-    The HRES model is updated every 12 hours, providing forecasts with a \
-    resolution of 3 km. The model can predict weather conditions up to 48 hours \
-    in advance. RocketPy uses the CONUS domain with ARW core.
 
 
 Using Windy Atmosphere
@@ -248,6 +227,5 @@ Also, the servers may be down or may face high traffic.
 
 .. seealso::
 
-    To see a complete list of available models on the NOAA's NOMADS server, visit
-    `NOMADS <https://nomads.ncep.noaa.gov/>`_.
-
+    To browse available NCEP model collections on UCAR THREDDS, visit
+    `THREDDS NCEP Catalog <https://thredds.ucar.edu/thredds/catalog/grib/NCEP/GFS/Global_0p25deg/catalog.html>`_.

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

@@ -57,31 +57,22 @@ This service allows users to download virtual soundings from numerical weather
 prediction models such as GFS, RAP, and NAM, and also real soundings from the
 Integrated Global Radiosonde Archive (IGRA).
 
-These options can be retrieved as a text file in GSD format.
-By generating such a file through the link above, the file's URL can be used to
-import the atmospheric data into RocketPy.
-
-We will use the same sounding station as we did for the Wyoming Soundings.
+These options can be retrieved as a text file in GSD format. However,
+RocketPy no longer provides a dedicated ``set_atmospheric_model`` type for
+NOAA RUC Soundings.
 
 .. note::
 
     Select ROABs as the initial data source, specify the station through its \
     WMO-ID, and opt for the ASCII (GSD format) button.
 
-Initialize a new Environment instance:
-
-.. code-block:: python
+If you need to use RUC-sounding-like data in RocketPy, convert it to one of the
+supported workflows:
 
-    url = r"https://rucsoundings.noaa.gov/get_raobs.cgi?data_source=RAOB&latest=latest&start_year=2019&start_month_name=Feb&start_mday=5&start_hour=12&start_min=0&n_hrs=1.0&fcst_len=shortest&airport=83779&text=Ascii%20text%20%28GSD%20format%29&hydrometeors=false&start=latest"
-
-    env = Environment()
-    env.set_atmospheric_model(type="NOAARucSounding", file=url)
-    env.plots.atmospheric_model()
+- Use :ref:`custom_atmosphere` after parsing the text data.
+- Use :ref:`reanalysis` or :ref:`forecast` with NetCDF/OPeNDAP sources.
 
 .. note::
 
     The leading `r` in the URL string is used to indicate a raw string, which \
-    is useful when dealing with backslashes in URLs.
-
-
-
+    is useful when dealing with backslashes in URLs.

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

@@ -1,3 +1,5 @@
+.. _standard_atmosphere:
+
 Standard Atmosphere
 ===================
 
@@ -29,4 +31,4 @@ The International Standard Atmosphere can also be reset at any time by using the
 
 .. jupyter-execute::
 
-    env.set_atmospheric_model(type="standard_atmosphere")
+    env.set_atmospheric_model(type="standard_atmosphere")

docs/user/environment/3-further/other_apis.rst

@@ -1,3 +1,5 @@
+.. _environment_other_apis:
+
 Connecting to other APIs
 ========================
 
@@ -25,14 +27,19 @@ the following dimensions and variables:
 - Latitude
 - Longitude
 - Pressure Levels
+- Temperature (as a function of Time, Pressure Levels, Latitude and Longitude)
 - Geopotential Height (as a function of Time, Pressure Levels, Latitude and Longitude)
+- or Geopotential (as a function of Time, Pressure Levels, Latitude and Longitude)
 - Surface Geopotential Height (as a function of Time, Latitude and Longitude)
+    (optional)
 - Wind - U Component (as a function of Time, Pressure Levels, Latitude and Longitude)
 - Wind - V Component (as a function of Time, Pressure Levels, Latitude and Longitude)
 
+Some projected grids also require a ``projection`` key in the mapping.
+
 
-For example, let's imagine we want to use the HIRESW model from this endpoint: 
-`https://nomads.ncep.noaa.gov/dods/hiresw/ <https://nomads.ncep.noaa.gov/dods/hiresw/>`_
+For example, let's imagine we want to use a forecast model available via an
+OPeNDAP endpoint.
 
 
 Looking through the variable list in the link above, we find the following correspondence:
@@ -72,15 +79,85 @@ Therefore, we can create an environment like this:
         dictionary=name_mapping,
     )
 
+Built-in mapping dictionaries
+-----------------------------
+
+Instead of a custom dictionary, you can pass a built-in mapping name in the
+``dictionary`` argument. Common options include:
+
+- ``"ECMWF"``
+- ``"ECMWF_v0"``
+- ``"NOAA"``
+- ``"GFS"``
+- ``"NAM"``
+- ``"RAP"``
+- ``"HIRESW"`` (mapping available; latest-model shortcut currently disabled)
+- ``"GEFS"`` (mapping available; latest-model shortcut currently disabled)
+- ``"MERRA2"``
+- ``"CMC"`` (for compatible datasets loaded explicitly)
+
+What a mapping name means
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Base mapping names (for example ``"GFS"``, ``"NAM"`` and ``"RAP"``) map
+    RocketPy weather keys to the current default variable naming used by the
+    corresponding provider datasets.
+- These defaults are aligned with current shortcut workflows (for example,
+    THREDDS-backed latest model sources) and may use projected coordinates
+    (``x``/``y`` plus ``projection``) depending on the model.
+
+Legacy mapping names
+^^^^^^^^^^^^^^^^^^^^
+
+If you are loading archived or older NOMADS-style datasets, use the explicit
+legacy aliases:
+
+- ``"GFS_LEGACY"``
+- ``"NAM_LEGACY"``
+- ``"NOAA_LEGACY"``
+- ``"RAP_LEGACY"``
+- ``"CMC_LEGACY"``
+- ``"GEFS_LEGACY"``
+- ``"HIRESW_LEGACY"``
+- ``"MERRA2_LEGACY"``
+
+Legacy aliases primarily cover older variable naming patterns such as
+``lev``, ``tmpprs``, ``hgtprs``, ``ugrdprs`` and ``vgrdprs``.
+
+.. note::
+
+        Mapping names are case-insensitive. For example,
+        ``"gfs_legacy"`` and ``"GFS_LEGACY"`` are equivalent.
+
+For custom dictionaries, the canonical structure is:
+
+.. code-block:: python
+
+    mapping = {
+        "time": "time",
+        "latitude": "lat",
+        "longitude": "lon",
+        "level": "lev",
+        "temperature": "tmpprs",
+        "surface_geopotential_height": "hgtsfc",  # optional
+        "geopotential_height": "hgtprs",          # or geopotential
+        "geopotential": None,
+        "u_wind": "ugrdprs",
+        "v_wind": "vgrdprs",
+    }
+
+.. important::
+
+    Ensemble datasets require an additional key for member selection:
+    ``"ensemble": "<your_member_dimension_name>"``.
+
 .. caution::
 
-    Notice the ``file`` argument were suppressed in the code above. This is because \
-    the URL depends on the date you are running the simulation. For example, as \
-    it for now, a possible link could be: https://nomads.ncep.noaa.gov/dods/hiresw/hiresw20240803/hiresw_conusfv3_12z \
-    (for the 3rd of August, 2024, at 12:00 UTC). \
-    You should replace the date in the URL with the date you are running the simulation. \
-    Different models may have different URL structures, so be sure to check the \
-    documentation of the model you are using.
+    The ``file`` argument was intentionally omitted in the example above. This is
+    because the URL depends on the provider, dataset, and date you are running
+    the simulation. Build the endpoint according to the provider specification
+    and always validate that the target service is active before running your
+    simulation workflow.
 
 
 Without OPeNDAP protocol
@@ -94,4 +171,3 @@ Environment class, for example:
 
 - `Meteomatics <https://www.meteomatics.com/en/weather-api/>`_: `#545 <https://github.com/RocketPy-Team/RocketPy/issues/545>`_
 - `Open-Meteo <https://open-meteo.com/>`_: `#520 <https://github.com/RocketPy-Team/RocketPy/issues/520>`_
-

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "rocketpy"
-version = "1.12.0"
+version = "1.12.1"
 description="Advanced 6-DOF trajectory simulation for High-Power Rocketry."
 dynamic = ["dependencies"]
 readme = "README.md"