Skip to content

Gridded Precipitation

Source revision requirement

This guide includes APIs added on main after tag v0.102.1, including get_gridded_precipitation_capabilities() and the GeoTIFF/GRIB adapters. These APIs are included in v0.103.0; v0.102.1 is insufficient. See release notes for the boundary.

Configure global gridded rainfall with RasUnsteady, then validate the solver-facing precipitation through HEC-RAS preprocessing and a completed simulation. Work on an isolated project copy and make input units, interval semantics, timestamps, and model clock explicit.

Choose the input route

Input Public API Result
Projected NetCDF RasUnsteady.set_gridded_precipitation() Meteorology configuration and native imported-raster HDF
Projected GeoTIFF bands/files RasUnsteady.set_gridded_precipitation_geotiff() Durable cumulative NetCDF plus native HDF
Projected GRIB/GRIB2 bands/files RasUnsteady.set_gridded_precipitation_grib() Durable cumulative NetCDF plus native HDF
Existing gridded DSS RasUnsteady.configure_gridded_dss_precipitation() Meteorology configuration referencing the supplied DSS family

GeoTIFF and GRIB setters return GriddedPrecipitationImportResult with source hashes, cache location, translation route, qualification, and HDF receipt. The established NetCDF setter retains its None return contract. For lower-level array ingestion, use RasPrecipGrid and RasPrecipHdf.

Historic precipitation ratio

HEC-RAS multiplies gridded precipitation by Met BC=Precipitation|Ratio and the matching HDF Ratio attribute. For observed or analysis sources, pass historic=True to the NetCDF, GeoTIFF, GRIB, or DSS setter; it writes 1.0 in both places, replacing a scale factor inherited from a cloned design-storm plan and logging the old value. This applies to MRMS, AORC, Stage IV, gauge-adjusted grids, and analysis QPF. When ratio is omitted, every generic setter also rejects a retained non-unit value in either representation rather than silently scaling new data. Resolve that error with historic=True (or ratio=1.0) for observed data, or an explicit non-unit ratio=<value> to retain a design-storm ARF deliberately. historic=True, ratio=<non-unit> is contradictory and raises.

Install dependencies from a terminal:

Bash Session
uv pip install -e ".[precip]"

DSS product conversion may additionally need HEC-Vortex, HEC-MetVue, or the optional dependencies listed in the product notebook.

PrecipMrms.to_dss runs HEC-Vortex by default. The backend argument selects the optional ras-commander-fast-dss importer (FAST-DSS), which needs no Java or HEC-Vortex install. Install it first with pip install ras-commander-fast-dss (published on PyPI from 0.1.0; see Installation):

Python
from ras_commander.precip import PrecipMrms

PrecipMrms.to_dss(grib_files, "storm.dss", clip_shp="basin.shp", backend="native")

The native route writes one-hour QPE only, each record PER-CUM with a one-hour period in its D and E parts. Other durations raise DssUnsupportedRecordError and write nothing. MRMS GRIB2 states an instant, so the file gives no period for them. backend="shadow" returns HEC-Vortex's output and compares it with the native result on a temporary copy, logging any difference.

The HEC-Vortex route refuses the same durations (15M and 03H to 72H) by default, with a ValueError and nothing written. HEC-Vortex 0.13.3 stored them as PRECIPITATION, MM, INST-VAL with a D part only, and HEC-HMS has read this shape as no rain. To write that shape anyway, on the java and shadow backends only:

Python
PrecipMrms.to_dss(grib_files, "storm.dss", product="MultiSensor_QPE_24H_Pass2_00.00", allow_instantaneous_precip=True)

The call logs a warning. These rules apply to MRMS QPE: a file name, a stated variable or a non-default product that names one. Another GRIB2 with its variable stated, such as HRRR, goes to HEC-Vortex as before. VortexCli.import_gridded called directly is not guarded by any of this, as it is a general converter.

Further points on this route:

  • File names. HEC-Vortex gives a one-hour period when the whole lower-cased file name matches .*gaugecorr.*qpe.*01h.*grib2, or the same with radaronly or multisensor. A one-hour MRMS file named storm.grib2 or RadarOnly_QPE_01H.grib2.backup was stored as INST-VAL, so it is refused too. Keep the archive names. A duration elsewhere in a name is a label: 24H_RadarOnly_QPE_01H.grib2 is a one-hour file.
  • Conflicting durations. If a file's name would get a one-hour period while its accumulation is stated to be otherwise, the call is refused, and allow_instantaneous_precip=True does not change that. HEC-Vortex stamped a real 24H file renamed 01H, with its own variable stated, with a one-hour period on the 24-hour total. The override allows instantaneous output, not relabelling a depth.
  • What cannot be detected without the wheel. With the ras-commander-fast-dss wheel, each file's own variables are read before Vortex starts. Without it, a conflict shows only through the product, the file name or a stated variable. So a 24H file renamed 01H, with no variable stated, passes the check, unless it is RadarOnly. HEC-Vortex 0.13.3 then found no matching variable and raised RuntimeError with no file written. Without the wheel, a non-MRMS file with no variable stated counts as the default MRMS selection and is refused, so state its variable.
  • RadarOnly variable name. With no variable stated, the name is read through HEC-Vortex, which starts Java to list the first and last files, then through the wheel. If neither can list the file, RadarOnly_QPE_<hours>H_altitude_above_msl is used, which every public file inspected holds, and the warning gives the reader's reason. An import that then fails says that the listing failed earlier.

Check version and route qualification

Python
from ras_commander import RasUnsteady

capabilities = RasUnsteady.get_gridded_precipitation_capabilities("6.6")
print(capabilities.qualification_for("geotiff"))
print(capabilities.qualification_for("dss"))
print(capabilities.notes)

Global gridded meteorology starts in HEC-RAS 6.0. The separate uniform-per-area boundary in 5.x is a different mechanism; translating to DSS does not add global gridded support. HEC-RAS 6.0–6.1 ignore the optional precipitation ratio, so the API rejects non-unit ratios. Native period-average timing can shift by one interval through 6.3.1; cumulative materialization avoids that source timing path.

Qualification applies to an exact release and input route. Prerelease versions do not inherit stable-release qualification. See the version matrix for actual runtime evidence and host limitations.

Required meteorology modes

HEC-RAS gridded precipitation files require explicit baseline mode records for evapotranspiration, air density, and air pressure. A missing record can make HEC-RAS report Error processing event conditions while the command-line process still exits with code zero. Every gridded precipitation setter now preserves an existing nonblank choice and completes only an absent or blank record with the RAS-authored defaults:

Text Only
Met BC=Evapotranspiration|Mode=None
Met BC=Air Density|Mode=Constant
Met BC=Air Pressure|Mode=Constant

The API also keeps the complete Met BC= block contiguous and immediately after the top-level meteorology headers. This applies equally to imported raster, GeoTIFF/GRIB translation, and DSS configuration. It does not remove the need to inspect HEC-RAS runtime messages: a zero exit code alone is not proof that event conditions were accepted.

For NetCDF, the default ras_commander route (also named native_hdf) qualifies the library-authored native HDF consumed by preprocessing. The native route means HEC-RAS itself importing the GDAL file; its qualification remains documentation-backed. netcdf_hdf_qualification and native_netcdf_qualification report these separately. An inconclusive receipt can mean either a blocked qualification run or an unresolved version; inspect hec_ras_version and the accompanying warnings.

WPC QPF GRIB2 compression is not accepted by native HEC-RAS import through 7.0.1. Translate it to DSS with RasDssGrid.import_gridded, as notebook 926 does (see below). Notebook 926 previously used qpkit 0.1.0 on GDAL crops of the WPC files; on its committed cycle those grids left 126 cells missing in every frame, so that route failed spatial qualification and is kept only as a disclosed comparison. Generic GRIB ingestion requires an installed GDAL reader capable of decoding the selected bands and a grid meeting the requirements below.

WPC QPF to DSS with FAST-DSS

The FAST-DSS gridded importer decodes WPC's published GRIB2 itself, so the DSS translation needs neither qpkit nor HEC-Vortex, Java or GDAL. Pass the downloaded p06m_<cycle>f<hour>.grb files with the total_precipitation product (or the variable list_variables() reports, Total_precipitation_surface_layer_6_Hour_Accumulation) and an SHG envelope around the model:

Python
from ras_commander_fast_dss import gridded

result = gridded.import_gridded(
    wpc_files, "wpc_qpf.dss", product="total_precipitation",
    envelope=(1494000, 2120000, 1564000, 2188000),   # SHG metres: west, south, east, north
    target_crs="SHG", cell_size=2000, method="bilinear",
    parts={"A": "SHG", "B": "BALD_EAGLE", "F": "WPC-QPF"},
)

Each forecast file becomes one PER-CUM record in millimetres whose D and E parts state its six-hour window. On the 2026-11-07 00Z cycle (f006 to f168), this wrote the 28 records with consecutive six-hour windows. envelope_crs takes WKT, not an EPSG code, so state the envelope in the target CRS, as above. Then attach the DSS with RasUnsteady.configure_gridded_dss_precipitation() and review the precomputed forcing. Notebook 926 runs this route through RasDssGrid.import_gridded and HEC-RAS 7.0: it checks every frame against a full-source GDAL warp and stops if a forcing cell is missing or a mesh cell samples none. See Gridded import and tools for the importer's agreement with HEC-Vortex and its refusals.

Direct GeoTIFF and GRIB ingestion

Assume ras is an initialized, copied project and unsteady file 03 is the intended target:

Python
receipt = RasUnsteady.set_gridded_precipitation_geotiff(
    "03",
    ["rain_1100.tif", "rain_1200.tif", "rain_1300.tif"],
    timestamps=["2024-08-09 11:00", "2024-08-09 12:00", "2024-08-09 13:00"],
    units="mm",
    value_type="amount",
    first_timestep_hours=1.0,
    interpolation="Bilinear",
    ras_object=ras,
)
print(receipt)

For a multiband file, pass one path and bands=[1, 2, 3], with one timestamp per selected band. File order is caller-supplied. For GRIB, use set_gridded_precipitation_grib() with the same temporal arguments and explicitly selected precipitation bands. Review the product's accumulation semantics, including forecast resets.

These routes require north-up, unrotated, projected square cells and matching grids across the sequence. Reproject unsuitable sources deliberately before import. NoData fails by default; nodata_policy="zero" is an explicit choice only when missing pixels legitimately mean no rainfall. Negative rainfall and decreasing cumulative totals are rejected.

Use source_timezone and model_timezone together when converting clocks; otherwise supply timestamps already on the model clock. Cache reuse checks source bytes, interpretation settings, values, time, coordinates, projection, transform, and units. Keep the returned NetCDF in the model package for subsequent HEC-RAS saves/reimports.

MRMS hourly QPE

PrecipMrms.to_ras_netcdf() writes the safe cumulative contract for hourly MRMS QPE. It prepends a zero cumulative frame one interval before the first valid time so HEC-RAS does not use the first nonzero amount as its datum. Pass end_time to repeat the final cumulative surface through the plan end:

Python
from ras_commander.precip import PrecipMrms

mrms_netcdf = PrecipMrms.to_ras_netcdf(
    mrms_stack,
    ras.project_folder / "Precipitation" / "mrms_qpe.nc",
    first_timestep_hours=1.0,
    end_time=simulation_end,
)
RasUnsteady.set_gridded_precipitation(
    "03", mrms_netcdf, dataset_name="APCP_surface",
    units="mm", value_type="cumulative", historic=True, ras_object=ras,
)

MRMS QPE valid times are interval-ending. A 10:00 QPE frame represents the 09:00–10:00 interval, so a simulation intended to include that frame must start no later than 09:00. Notebook 924 demonstrates and verifies this timing against the temporary and completed plan HDFs. Starting the plan at 10:00 correctly excludes that pre-simulation interval.

AORC historical rainfall

Use the implemented PrecipAorc.download() API with WGS84 bounds or a supported extent input. Earlier documentation incorrectly advertised retrieve_aorc_data(), extract_by_watershed(), and aggregate_to_interval(); these are not public methods.

Python
from pathlib import Path
from ras_commander.precip import PrecipAorc

netcdf = PrecipAorc.download(
    bounds=(-77.71, 41.01, -77.25, 41.22),
    start_time="2024-08-09 11:00",
    end_time="2024-08-09 13:00",
    output_path=Path(ras.project_folder) / "Precipitation" / "aorc.nc",
    target_crs="EPSG:5070",
    resolution=2000.0,
)
RasUnsteady.set_gridded_precipitation(
    "03", netcdf, dataset_name="APCP_surface",
    units="mm", value_type="amount", first_timestep_hours=1.0,
    historic=True, ras_object=ras,
)

AORC precipitation is the one-hour accumulation ending at its timestamp, in kg/m² liquid equivalent (numerically mm of water). See NOAA's AORC methods, section 5.1. PrecipAorc.download() preserves the caller's hour-level bounds instead of expanding them to whole calendar days. PrecipAorc.create_storm_plans() uses these explicit semantics for cloned storm plans and requests its first AORC frame at sim_start + 1 hour, allowing the HDF authoring path to place a zero cumulative baseline at sim_start. Check timestamp continuity and source coverage; a gap is not a zero-rainfall observation. The first timestamp above represents 10:00–11:00, so a corresponding plan should start at 10:00.

Use PrecipAorc.get_storm_catalog() and create_storm_plans() for catalog workflows (notebooks 900 and 901). Notebook 900 executes one deterministic catalog event and verifies the exact forcing window, durable import HDF, temporary plan HDF, completed cell precipitation, hydraulic output, runtime messages, and BCO mass balance. Select the event, resolution, and model assumptions using source documentation and project requirements.

Interval semantics

value_type Meaning Example
amount Depth during the interval ending at this timestamp AORC hourly accumulation; MRMS hourly QPE
rate Depth per hour over the interval Atlas 14 ABM export in mm/hr
cumulative Running depth total Already accumulated forcing

The explicit units argument is the depth unit ("mm" or "in"), including when value_type="rate". The latter means depth per hour. Do not pass units="mm/hr" as the explicit depth-unit override.

first_timestep_hours is the HEC-RAS import dialog's First Timestep Duration. Without it, the first band establishes time zero and is not delivered; the library warns if this drops nonzero precipitation. A source containing an explicit zero baseline, such as the ABM export in notebook 727, should leave this argument None. Units describe the source, not the project's unit system; HEC-RAS converts during preprocessing.

Gridded DSS handoff

Python
RasUnsteady.configure_gridded_dss_precipitation(
    "03",
    dss_filename="Precipitation/forecast.dss",
    dss_pathname=reviewed_dss_pathname,
    interpolation="Bilinear",
    ratio=1.0,
    ras_object=ras,
)

Use a cataloged pathname from the intended grid family and verify coverage, interval, units, and data type. ratio=1.0 explicitly clears an inherited scale factor. This function configures the model; it does not create DSS grids. Notebook 728 demonstrates extending a forcing window with a derivative DSS file.

Precompute and post-compute validation

Python
from ras_commander import RasPreprocess, RasCmdr, HdfResultsPlan, RasPlan
import h5py
import numpy as np

prepared = RasPreprocess.preprocess_plan("06", ras_object=ras, max_wait=600)
assert bool(prepared), prepared.error
with h5py.File(prepared.tmp_hdf_path, "r") as hdf:
    values = hdf["Event Conditions/Meteorology/Precipitation/Values"][:]
    times = hdf["Event Conditions/Meteorology/Precipitation/Timestamp"][:]
assert values.ndim == 2 and values.shape[0] == len(times)
assert np.isfinite(values).all() and np.max(values) > 0  # Expected wet event

result = RasCmdr.compute_plan(
    "06", ras_object=ras, force_rerun=True, verify=True,
    hdf_output_variables=["Cell Hydraulic Depth", "Cell Precipitation Rate",
                          "Cell Cumulative Precipitation Depth"],
)
assert bool(result), result
plan_hdf = str(RasPlan.get_plan_path("06", ras_object=ras)) + ".hdf"
print(HdfResultsPlan.get_compute_messages_hdf_only(plan_hdf))

The imported unsteady HDF is authoring evidence. The temporary plan HDF is the precompute source of truth, and the completed final plan HDF is the post-compute source of truth. Do not manually relocate datasets. Compare preprocessed interval depths/timestamps against intended forcing in project units, then inspect final per-cell rainfall and hydraulic response. The assertions above are basic wet-event checks, not a volume or coverage proof. Manual review of all runtime messages and rainfall/result maps remains advisable, including a search for Error processing event conditions even when the HEC-RAS process returns zero.

Terrain backgrounds in flood animations

For gridded arrays and stored-map rasters, PrecipMrms.animate_flood_inundation(..., terrain=terrain_path) reads the terrain raster's CRS, transform, bounds, and NoData value. It warps only the portion needed by the displayed flood grid, computes hillshade at that bounded display resolution, and uses the flood grid's extent and orientation. Terrain and hydraulic rasters therefore need not have identical bounds, resolution, or CRS.

A raw NumPy terrain array has no georeferencing. It is accepted only when its shape exactly matches the flood grid, in which case it is explicitly treated as an already aligned display array. Use a georeferenced raster path whenever the grids differ. Missing raster CRS or missing flood-grid CRS fails rather than silently stretching the background. This overlay is visualization only; it does not alter the terrain used by HEC-RAS or the analytical resolution of the hydraulic results.

The direct plan-HDF route renders mesh centers as a point cloud and does not support a terrain background. Passing terrain= with a plan HDF raises a clear ValueError; export stored-map rasters when a georeferenced terrain overlay is required.

Combined-animation time alignment

PrecipMrms.animate_combined() keeps its historical display behavior by default: precip_alignment="latest_completed" selects the latest precipitation timestamp at or before each hydraulic frame, and coverage_policy="hold" repeats the nearest source frame outside source coverage. This is a latest-observation display contract, not a claim that the selected value is the forcing interval active at the hydraulic timestamp.

For interval-ending accumulations such as hourly MRMS QPE, make the alternative contract explicit:

Python
PrecipMrms.animate_combined(
    precip,
    flood,
    "combined.mp4",
    precip_value_semantics="interval_amount",
    precip_alignment="covering_interval",
    precip_interval="1h",
    coverage_policy="error",
)

covering_interval enforces continuous, fixed-duration, interval-ending source coverage. A frame ending at end covers exactly (end - precip_interval, end]; the interval start is excluded and its end is included. Source gaps, overlaps, duplicate or unordered timestamps, and hydraulic frames that do not belong to the selected interval fail explicitly. coverage_policy="error" also fails when hydraulic frames extend beyond the declared source coverage. Use coverage_policy="dry_tail" only when zero precipitation after the final source interval is an explicit caller assumption; the animation labels those frames as an authorized dry tail. It never converts missing coverage before the first interval to zero.

precip_value_semantics="rate" labels values as in/hr. "interval_amount" labels them as inches per displayed interval without claiming an hourly rate. This display-only name is intentionally distinct from forcing APIs' value_type: it describes how to label and align already-loaded animation values and does not rewrite forcing data. Alignment may repeat a source grid across multiple hydraulic display frames, so never sum the displayed frame stack to calculate cumulative precipitation. Preserve and integrate the original source intervals for forcing or water-balance calculations.

Examples and scope

Notebook Demonstration
727 Atlas 14 spatial/uniform comparison, figures, precompute checks, compute diagnostics, hydraulic results
728 Model-covering DSS derivative with source-hash preservation, three explicit dry intervals, temporary/final HDF plateau checks, HEC-RAS 7.0 compute, and hydraulic figure
729 Direct GeoTIFF on RasExamples, temporary HDF, final rainfall/hydraulic response, figures
900 / 901 AORC catalog and plan creation with precompute checks
914 Archived 48-hour AORC event with source-to-temporary/final-HDF checks, hydraulic diagnostics, and a timezone-correct USGS stage comparison; explicitly diagnostic rather than calibration validation because historical boundaries and operations are not bundled
915 Executed forecast orchestration/readiness guide with a timezone-explicit cycle manifest, current API-signature checks, and a visual audit of the canonical HRRR, STOFS-3D, MRMS, and WPC artifacts; not independent format/version qualification
916 Archived HRRR 15Z forecast: the 18 one-hour APCP messages imported with RasDssGrid to hourly DSS grids, each validated against a full-source GDAL warp with a coverage gate (the earlier qpkit route is kept as a disclosed comparison that fails spatial qualification); a Stage IV analysis for context; no-rain/forecast compute, temporary and final HDF forcing checks, active-cell spatial comparison, hydraulic response, convergence map, and manual diagnostics
732 RasDssGrid (FAST-DSS) import of real AORC Zarr/NetCDF, IMERG HDF5, Stage IV GRIB1/GRIB2 and MRMS GRIB2, then every grid tool and the eight zonal statistics over the NewOrleansMetro 2D area; no HEC-RAS run
917 Two archived MRMS events: inspect spatial DSS grids, apply the arithmetic mean of a rectangular source clip as a uniform boundary, and compare every native cumulative rainfall timestamp and physical cell on the absolute model clock. Retained baseline/event evidence, HDF-based diagnostic maps, pump plots and interval-aligned animations; not spatial rain-on-grid qualification. A native preprocessing section shows RasDssGrid accumulation windows from 1 to 72 hours, overlap and gap reports, shapefile clipping and thread-count equality
924 MRMS NetCDF rain-on-grid with precompute and final model checks
926 Complete WPC cycle (live or fixed) imported with RasDssGrid to 28 six-hour DSS grids, each validated against a full-source GDAL warp with a coverage gate (the earlier qpkit route is kept as a disclosed comparison that fails spatial qualification); objective wettest 24-hour window, temporary/final HDF forcing checks, no-rain/event HEC-RAS 7.0 runs, hydraulic/convergence figures, and manual diagnostics

Notebook 722 directs readers to the implemented Atlas 14 workflow instead of obsolete placeholders and raw meteorology edits. Updated source cells do not imply every live product was rerun on every HEC-RAS release; the version matrix records actual evidence.