BUG: All NOAA NOMADS Dependent Atmosphere Models Broken

MateusStano · MateusStano · commit c612e43d0461 · 2026-03-17T22:46:11.000-03:00
Fixes #933
diff --git a/docs/user/environment/1-atm-models/ensemble.rst b/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,16 +87,12 @@ 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
diff --git a/docs/user/environment/1-atm-models/forecast.rst b/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,
-    )
-
-    env_hiresw.set_atmospheric_model(
-        type="Forecast",
-        file="HIRESW",
-        dictionary="HIRESW",
-    )
-
-    env_hiresw.plots.atmospheric_model()
-
-.. note::
+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``.
 
-    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,6 @@ 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>`_.
 
diff --git a/docs/user/environment/1-atm-models/soundings.rst b/docs/user/environment/1-atm-models/soundings.rst
@@ -57,26 +57,20 @@ 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::
 
diff --git a/docs/user/environment/1-atm-models/standard_atmosphere.rst b/docs/user/environment/1-atm-models/standard_atmosphere.rst
@@ -1,3 +1,5 @@
+.. _standard_atmosphere:
+
 Standard Atmosphere
 ===================
 
diff --git a/docs/user/environment/3-further/other_apis.rst b/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,52 @@ 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)
+
+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
diff --git a/rocketpy/environment/environment.py b/rocketpy/environment/environment.py

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+.. _standard_atmosphere:`
	`2`	`+`
`1`	`3`	`Standard Atmosphere`
`2`	`4`	`===================`
`3`	`5`