Gridded Precipitation Version and Format Matrix¶

This report separates vendor documentation, schema evidence, native Windows execution, and Wine execution. A process exit by itself is not a qualification: the precipitation input must materialize, HEC-RAS messages must identify the precipitation stage, final cell rainfall must be nonzero and quantitatively consistent, and the hydraulic result must be nonempty.

The machine-readable companion is gridded-precipitation-version-matrix.json. The repeatable native harness is scripts/qualification/gridded_precipitation_matrix.py.

Conclusions¶

Global gridded meteorology begins in HEC-RAS 6.0. The 5.x uniform precipitation-per-area mechanism is a separate feature.
The existing Python route normalizes raster inputs and authors the native precipitation HDF. The new native route reads NetCDF through the selected HEC-RAS release's GDAL and accumulated-raster writer.
Native NetCDF needs an explicit Import Raster Data step before preprocessing. Writing the source filename and selector alone did not import the payload in the tested configuration-only controls.
“Native NetCDF has never been tested” is incorrect: the retained Davis fixture records a 6.6 GUI import. It did not establish an unattended API or Wine qualification. Those were implementation and testing gaps addressed here.
Qualification is specific to the release, platform, adapter revision, source semantics and model. A completed solver, nonzero rain or a plausible map alone cannot establish equivalence. The current harness compares imported values, temporary forcing, final cell rain, water surfaces and hydraulic depths.
GRIB selection, instantaneous rates, interval amounts through the native accumulator, and nonzero first-duration rate inputs remain outside this adapter's qualified scope. Use the Python/HDF or DSS route as appropriate.

Native GDAL evidence and configuration¶

The Davis regression fixture records a HEC-RAS 6.6 GUI Import Raster Data action on NetCDF, acceptance of five timesteps, and subsequent preprocessing of plan p02. Its retained precipitation HDF provides native GUI-import evidence; therefore, “native NetCDF has never been tested on any release” is too broad. This fixture does not establish unattended NetCDF ingestion during preprocessing or GDAL NetCDF import under Wine. The fixture provenance is retained in tests/fixtures/precipitation/gdal_netcdf_davis/README.md.

Use RasUnsteady.configure_gridded_gdal_precipitation() to configure a single NetCDF or GRIB source without Python importing its raster values:

Python

RasUnsteady.configure_gridded_gdal_precipitation(
    unsteady_file="03",
    raster_filename="Precipitation/rain.nc",
    dataset_name="precip",  # Explicit selector understood by the vendor GDAL reader
    historic=True,
    ras_object=project,
)

The method writes the source records and matching sidecar attributes. It does not decode the source, convert units or timestamps, or write Imported Raster Data. The source must carry the metadata required by HEC-RAS. A sidecar with existing precipitation datasets is rejected before mutation: use a separately staged clean project to prevent a previous import from masking a failed source read. Stage the raster under the project folder for portable Windows/Wine paths.

Then perform the vendor import explicitly, before preprocessing:

Python

receipt = RasUnsteady.import_gridded_gdal_precipitation(
    "03", units="mm", data_type="cumulative",
    hecras_dir="C:/Program Files (x86)/HEC/HEC-RAS/6.6", ras_object=project,
)

The native helper reads values through HEC's installed GDAL and writes them through HEC's accumulated raster writer. Python validates and atomically replaces a staged sidecar; it does not decode or author raster values in this route. It requires the installed .NET Framework compiler and, on Linux, a private configured Wine prefix. Sources are unchanged and failed imports leave the target unchanged.

Cross-release qualification (October 15, 2026)¶

The stable-release cohort is 6.0, 6.1, 6.2, 6.3, 6.3.1, 6.4, 6.4.1, 6.5, 6.6, 7.0 and 7.0.1. Global gridded meteorology begins in 6.0; 5.x uniform precipitation per area is a separate feature. Archived 6.7 betas are historical checks and do not inherit stable-release qualification.

Native Windows cumulative and rate qualification passes on all eleven stable releases. Wine source-import checks also pass on all eleven. The companion JSON records full Wine status separately from source import and retains the conditions for each platform. Full Wine qualification passes on ten releases; 6.0 remains blocked at startup. Both positive routes pass all thirteen gates on each qualified platform, including retrospectively inspected compiled inputs. Qualification applies to these exact releases, the tested source semantics and the official Bald Eagle example.

The source checks cover cumulative depth, interval-ending period-average hourly rates, irregular fractional-hour offsets and a date-only epoch. Nine negative cases per runtime verify that failed imports preserve both unsteady text and sidecar. An exported midnight/2040 NetCDF cache was also imported successfully by 6.6 and 7.0.1.

Comparison protocol¶

Each full run uses separate configuration-only, Python/HDF, vendor-cumulative and vendor-rate copies. Native imports start without cached raster values. The configuration-only negative control must fail at event conditions. Preprocessing must finish and its owned writers must stop before temporary forcing is inspected. The solver then runs with one requested core, written and read back before preprocessing by the current driver. Earlier receipts may set the requested core count at compute; their original protocol is retained. Imported values, temporary forcing, final cell rainfall, water surfaces and hydraulic depths must match the Python/HDF control exactly. Final rain must be positive and hydraulics nonempty.

The revised protocol additionally compares compiled geometry datasets, attributes and layer associations with HdfBase.fingerprint_model_inputs(). Only explicitly named audit dates and the known-schema execution-history table are excluded from equality. The keyed Manning's region/cell mapping is compared as sorted exact pairs, preserving duplicates; raw hashes are retained. Missing land cover, infiltration or impervious associations, changed roughness and changed hydraulic tables fail this gate. A saved rainfall match cannot compensate for a different model. The companion JSON identifies retrospective input checks separately from a run executed with the revised protocol. The current driver also fingerprints source layer bindings before raster configuration and requires both final routes to preserve them. This strengthens the compiled-input gate against matching fallback models on both sides. Retained results receive a separate source-binding audit; original reports remain unchanged and the JSON distinguishes retrospective audits from the current driver's recorded baseline. The final unwrapped Wine 7.0 run passes all 13 cumulative and 13 rate gates with the baseline recorded before import; all 21 qualified platform/release pairs preserve the eight source-binding fields.

Earlier 7.0 Wine comparisons had equal rainfall but different hydraulics when physical layer associations were lost. A later integration run again failed the rate route's compiled-input and hydraulic gates, despite exact final rainfall. A read-only instrumented retry with the same package and driver files passed all gates. The mutation step remains unisolated; this intermittent behavior is tracked in issue #536.

After explicit preprocessing, the current driver retains its geometry inputs with clear_geompre=False, records the geometry fingerprint and .c## state before compute, and still forces a new verified solve. --complete-geometry explicitly requests a separate Mapper rebuild and invalidation. Avoiding the redundant invalidation is a workflow correction, not a demonstrated causal repair of the intermittent native behavior. Compiled-input and hydraulic checks remain mandatory; the JSON retains the failed attempt separately from qualified results.

A focused Mapper probe also exposed premature completion detection under Wine: old valid HDF tables could survive while a new rebuild was still at stage 2/4. RasProcess.compute_geometry() now requires this invocation's terminal Completed Writing Geometry message, a changed geometry file and stable valid tables before its Wine hang fallback can report success. Native Windows still waits for normal exit. Both disposable Wine probes (with and without Mapper configuration) now finish by normal process exit. This method mutates geometry; use a disposable model copy.

Retained regression fixtures reject completed solves with excessive rainfall and solves with exact precipitation but divergent hydraulics. Source-only runs and --routes subsets cannot qualify a release. Historical results without independent temporary-HDF inspection remain historical evidence.

Runtime conditions and remaining limits¶

The tested Wine 7.x profile requires RasCmdr.compute_plan(..., disable_omp_affinity=True). This sets KMP_AFFINITY=disabled only for the engine and its descendants, preserves the caller environment and defaults to False. The choice is recorded in execution_details. Default-profile controls failed on Intel OpenMP affinity calls, including Wine's unimplemented GetNumaNodeProcessorMaskEx. Intel describes disabled in its Thread Affinity Interface.

HEC-RAS 6.0 under Wine remains unqualified for full preprocessing and compute. Both Python/HDF and native controls stall after explicit TCU acceptance. The exact vendor registry query matches the API's release key and sentinel name. Both registry views contain the expected value, but wizard closure leaves only a background window. Registry contents alone cannot establish a usable GUI profile. Bounded OLE, registry and loader traces have not established a missing module, missing COM class or alternate-key fix. No speculative registry or component changes were made. This runtime failure is tracked in issue #532.

Exact 6.4 Windows qualification used a runtime extracted from the signed official installer on a temporary local NTFS volume. Network runtime attempts failed; runtime location is part of the tested profile. Older Windows releases can require the existing process-local CPU-only WMIC shim. Older event writers use CompleteEventConditions; preprocessing recognizes it alongside CompletePreProcess, with exact temporary-file and launch-time ownership checks. When a release runs no separate writer, a witnessed owned solver start with a successful no-writer inventory can signal handoff. Owned processes must still stop and completed artifacts must pass validation before inspection. Incomplete inventories block result inspection.

Supported native import semantics are cumulative depth and interval-ending period-average hourly rates with a zero baseline frame. At least two strictly increasing whole-second timestamps and Gregorian CF seconds/minutes/hours/days are required. GRIB selection, interval amounts (per-cum), instantaneous rates (inst-val), other calendars, subsecond times and nonzero first-duration rates are rejected by this adapter. These are interop-path limits; they do not describe every HEC-RAS GUI workflow.

Diagnostics and explicit acceptance¶

RasCmdr.inspect_plan_windows() reads bounded text from exact-plan owned windows after complete process inventory and PID identity checks. It performs no UI actions and excludes editable/password text. Native ANSI and Unicode controls use their corresponding text APIs. RasPrecipHdf.inspect_gridded_precipitation() reports imported, temporary and final arrays after writers stop; HdfBase.fingerprint_model_inputs() records exact compiled inputs without following external HDF storage.

RasTcu.inspect_acceptance() reads only the selected release's acceptance sentinel in both registry views. export_acceptance() and import_acceptance() support explicitly authorized profile provisioning; exports exclude personal preferences and recent projects. Export requires a registry-backed value; a task-probe record alone is not portable acceptance. Acceptance exports are trusted operator configuration, not signed attestations. accept_gui_terms() requires explicit assent, a stable enabled main window and graceful exit.

For an authorized preprocessing launch, pass RasPreprocess.preprocess_plan(..., accept_tcu=True); the default is False. RasTcu.accept_running_terms() scopes the same affirmative action to an already-owned exact PID, executable and creation time. Wizard closure does not relax forcing, writer-quiescence or solver checks. Ordinary computation and dialog watchdogs never grant assent.

The repeatable driver is scripts/qualification/native_gdal_windows_versions.py, using Windows Python on Windows or Wine (--execution-platform wine). Source semantics are exercised by native_gdal_source_semantics.py; shared assessment and portable requests are in native_gdal_precipitation_matrix.py. All engine execution and result inspection use ras-commander APIs. For example, from a repository checkout in Windows Python:

Bash

python -m scripts.qualification.native_gdal_windows_versions --root working/native-gdal-sources --phase sources --versions 6.6 --semantics-source tests/fixtures/precipitation/gdal_netcdf_davis/clb704_precip_5step.nc --semantics-template tests/fixtures/precipitation/gdal_netcdf_davis/DavisStormSystem.gui_imported.u01

Use --runtime-root for a nonstandard installation directory, containing one subdirectory per version. Full runs require --phase full --source-project pointing to a staged Bald Eagle plan06 project with cumulative NetCDF already configured and all dependencies under that project folder. Output directories must be new. The driver inspects TCU state by default; seeding requires --operator-accept-tcu or an explicitly supplied trusted --tcu-acceptance export. Native Windows/Wine comparisons pass require_linux_solver_ready=False to preprocessing; the default True additionally requires geometry tables for the Linux solver.

Release chronology and capability¶

Release	Public date	Global gridded precipitation	Evidence classification
5.0	2016-03-04	Unsupported	Official documentation/examples and 5.0.7-to-6.0 schema comparison
5.0.1	2016-04	Unsupported	Same 5.x family evidence
5.0.2	2016-08	Unsupported; withdrawn	Official release notes; no unofficial binary acquired
5.0.3	2016-09	Unsupported	Same 5.x family evidence
5.0.4	2018-03	Unsupported	Same 5.x family evidence
5.0.5	2018-06	Unsupported	Same 5.x family evidence
5.0.6	2018-11	Unsupported	Same 5.x family evidence
5.0.7	2019-03	Unsupported	Official examples plus focused binary-schema comparison
6.0	2021-05-28	Introduced	Native NetCDF cumulative/rate end-to-end Windows qualification; process-local WMIC shim
6.1	2021-09-21	Native NetCDF qualified on Windows and Wine	Cumulative/rate import, independent temporary forcing, solver and exact hydraulic parity; Windows DSS also qualified
6.2	2022-03-11	Native NetCDF qualified on Windows and Wine; version limitations remain	Windows DSS and native NetCDF cumulative/rate qualification; Windows WMIC shim
6.3	2022-08-25	Native NetCDF qualified on Windows and Wine; timing limitation	Cumulative/rate import, temporary forcing and exact hydraulic parity; exact-release process-local WMIC fallback
6.3.1	2022-09-30	Native NetCDF qualified on Windows and Wine; timing limitation	Cumulative/rate import, temporary forcing and exact hydraulic parity; Windows process-local WMIC fallback
6.4	2023-06-05	Native NetCDF qualified on Windows and Wine	Signed extracted runtime on temporary NTFS virtual disk; cumulative/rate import, preprocessing, solver and exact hydraulic parity
6.4.1	2023-06-22	Native NetCDF qualified on Windows and Wine	Cumulative/rate import, temporary forcing, completed solver and exact hydraulic parity
6.5	2024-02-02	Native NetCDF qualified on Windows and Wine	Full cumulative/rate parity; earlier Wine hydraulic mismatch retained as a failed attempt
6.6	2024-09-30	Native NetCDF qualified on Windows and Wine; DSS/translated GeoTIFF also qualified	Native NetCDF full cumulative/rate parity; earlier DSS/GeoTIFF Windows and Wine evidence retained separately
6.7 Beta 5	2025-10	Historical beta only	Native NetCDF rainfall matched but hydraulics differed; failed strict qualification
7.0	2026-04-17	Native NetCDF qualified on Windows and Wine; DSS/translated GeoTIFF qualified on Windows	Native NetCDF cumulative/rate full parity; earlier source-route evidence retained separately
7.0.1	2026-06-02	Native NetCDF qualified on Windows and Wine; DSS qualified on Windows	Cumulative/rate import, temporary forcing, completed solver and exact hydraulic parity

HEC withdrew 5.0.2 because of a critical simplified-breach defect. The official archive does not offer it, and this audit did not use an unofficial mirror. The main archive lists 6.4.1 rather than 6.4; its signed legacy 6.4 setup URL remained available for this investigation.

Why 5.x is classified unsupported¶

The 5.0.7 official examples contain none of the 6.x global meteorology grammar (Precipitation Mode, Met BC=Precipitation, or equivalent gridded entries). A focused UTF-16 string inspection found none of Precipitation Mode, Gridded Source, Meteorology, Point Interpolation, or Constant Units in the matching 5.0.7 RasMapperLib.dll; every string is present in 6.0.

This was a schema-string comparison, not vendor-source decompilation. No vendor source was copied. Reproducibility identifiers are:

Assembly	Size	File version	SHA-256
5.0.7 `RasMapperLib.dll`	3,685,888	2.0.0.0	`f23f43304d445356e50f760f1e54ee17d5b46b2c7a97991e7d73dad740c735ba`
6.0 `RasMapperLib.dll`	6,174,720	2.0.0.0	`be896702ff0705034b3d17dab86a4d91e290dc69884f50dd3fdfb83518faf8c8`

The old 5.x uniform hyetograph assigned to a storage area or 2D area remains a valid, separate capability. It must not be labeled as gridded rain-on-grid.

Initial DSS qualification evidence (historical profiles)¶

This table records the initial DSS test phase. Its 6.0 and 6.5 host failures were superseded by successful native-NetCDF qualifications in the current owner context. Its missing 6.4 runtime was subsequently acquired. These old attempts are retained as profile-specific evidence.

The test case is plan 06, Gridded Precip - Infiltration, from HEC-RAS 6.0's official Bald Eagle Creek Multi-2D examples. It references a real NEXRAD HEC-DSS grid and was shortened to a wet 80-minute window. The solver-facing input has shape 3 x 268830, maximum 3.6177184582, and 230,735 nonzero values. Successful nine-output-time runs have a final cell cumulative-rainfall maximum of 0.1145427823, 144,528 nonzero values, and nonzero water surfaces.

Version	Integrated precipitation preprocessing	Solver/result	Classification
6.0	`RasTcu.accept()` reports exact-runtime acceptance, but the same executable raises the actual TCU dialog	Not run	ras-commander TCU registry/runtime compatibility blocker, not precipitation evidence
6.1	`Processing` and `Finished Processing Precipitation`; fresh temporary HDF contains the expected `3 x 268830` values	Raw run reaches solver then fails because WMIC is absent. With process-local CIM shim: verified finish, cumulative max `0.1145427823`, 126,462 nonzero values over 8 output times, nonzero WSE	Precipitation passes; host compatibility fails without shim
6.2	Same expected materialization and precipitation messages	Raw WMIC failure; shimmed run verified, 144,528 nonzero cumulative values over 9 output times, nonzero WSE	Precipitation passes; host compatibility fails without shim
6.3	Expected materialization and precipitation messages	`Finished Unsteady Flow Simulation`; expected rain and WSE	Qualified with documented period-average limitation; exact-release WMIC fallback available when the host lacks WMIC
6.3.1	Expected materialization and precipitation messages	`Finished Unsteady Flow Simulation`; expected rain and WSE	Qualified with documented period-average limitation; exact-release WMIC fallback available when the host lacks WMIC
6.4	No executable	Not run	Missing runtime
6.4.1 on Linux/Wine 11	Native registered profile: `RasTcu.accept()` cannot find an accepted donor. Mixed accepted profile: `RasMapper Component did not load` / `ActiveX component can't create object`	Not reached	Exact-profile provisioning/COM blocker; no precipitation claim
6.5	No fresh result materialized before HEC-owned `Error: Unexpected error; quitting` dialog	Not reached	Confirmed startup/install/runtime failure on this host
6.6	Expected materialization and precipitation messages	`Finished Unsteady Flow Simulation`; expected rain and WSE	Qualified on Windows
6.6 on Linux/Wine 11, native DSS	Preprocessing completed in 13.3 seconds after removing the disabling DLL override; 3 x 268830 values	Verified completion; final cumulative max 0.11454278230667114 in, 144528 nonzero entries; WSE max 923.1984252929688 ft	Qualified; rainfall and WSE metrics match Windows 6.6 exactly
6.6 on Linux/Wine 11, translated GeoTIFF	Four exact interval rows materialized at 10:00, 11:00, 12:00, and 13:00; `Processing` and `Finished Processing Precipitation`	`Finished Unsteady Flow Simulation`; final cumulative max `0.1157457530` in over 18,066 cells; final hydraulic depth max `9.7182655334` ft over 7,576 wet cells	Qualified for the feature-snapshot GeoTIFF-to-NetCDF/native-HDF route
6.7 Beta 5	Expected materialization and precipitation messages	`Finished Unsteady Flow Simulation`; expected rain and WSE	Historical beta evidence only
7.0	Expected materialization and precipitation messages; translated GeoTIFF route completed required meteorology modes and materialized all four expected frames	`Finished Unsteady Flow Simulation`; translated-route final cumulative maximum `0.1157457530` in and hydraulic-depth maximum `9.7182655334` ft	DSS and translated GeoTIFF routes qualified on Windows
7.0.1	Expected materialization and precipitation messages	`Finished Unsteady Flow Simulation`; expected rain and WSE	Qualified on Windows

The 6.1/6.2 controlled rerun supplies only the CPU fields requested by the legacy engine, using read-only Windows CIM queries in a temporary process-local PATH. It does not change the HEC-RAS executable or project. The unmodified failure emitted an empty systemInfo.txt followed by Intel Fortran severe error 24. This evidence supports a separate ras-commander host-compatibility fix; it is not a precipitation-format workaround. The controlled rerun used the shim only for 6.1 and 6.2. HEC-RAS 6.3 and 6.3.1 qualified in this matrix without it, while the library retains its earlier evidence-backed fallback for those two exact releases. No shim claim is extrapolated to 6.3.2 or another untested patch release.

Linux/Wine 6.6 native DSS control and successful rerun¶

The successful final plan HDF SHA-256 is 6f8aa85125809c10393e47ed7c2f412203a2121db4e0b116493ca7ea7516e106. The executable SHA-256 remains a34e56a172ba06cde2d546f4d7282801c2b67040969d4ed23b41dfc755772134. Evidence receipts wine66-dss-short.json, wine66-dss-fresh.json, and wine66-dss-dotnet.json and the diagnosis are retained in the research worktree's ignored working/ directory. The successful isolated model is retained with those private research artifacts. The comparison establishes matching rainfall/WSE summary metrics, not a bitwise comparison of all hydraulic arrays. No other release is qualified by this test.

Linux/Wine 6.6 translated GeoTIFF evidence¶

The direct Wine run used the HEC-RAS 6.6 RasExamples BaldEagleCrkMulti2D project and three deterministic, asymmetric, single-band GeoTIFF interval amounts. The feature snapshot translated those files to its cached NetCDF plus native unsteady-HDF representation, then public RasPreprocess and RasCmdr APIs performed preprocessing and compute. The HEC-RAS executable SHA-256 was a34e56a172ba06cde2d546f4d7282801c2b67040969d4ed23b41dfc755772134. RasTcu.accept() returned already-accepted; no GUI interaction occurred.

The temporary plan HDF contained exactly four 4 x 408 interval rows:

Timestamp	Exact interval values (inches)	Counts
`09Aug2024 10:00:00.000`	`0.0`	408
`09Aug2024 11:00:00.000`	`0.01968505047`, `0.03937010095`	204, 204
`09Aug2024 12:00:00.000`	`0.00984252524`, `0.03937010095`	192, 216
`09Aug2024 13:00:00.000`	`0.00393700646` or its float32 rounding neighbor, `0.03937010095`	272, 136

The final HDF reported Processing Precipitation data, Finished Processing Precipitation data, Finished Unsteady Flow Simulation, and Complete Process, with no precipitation error. Final cell cumulative rainfall reached 0.1157457530 inches in 18,066 cells; final hydraulic depth reached 9.7182655334 feet in 7,576 cells. The final HDF SHA-256 was 0be34dbaf339192b44bee51134c50a3a0d31ba5980aa0c12c1e72a1d1d449afe. These results qualify this translation route on Wine 11 / HEC-RAS 6.6; they do not imply native HEC-RAS GeoTIFF meteorology support or support on other versions.

The issue #324 implementation was requalified on the same Wine route on 26 September 2026. The authored file contained all three required modes in one contiguous Met BC= block. Preprocessing completed in 3.60 seconds, the simulation completed without an event-condition error, and the final rainfall and hydraulic metrics matched the prior qualification. The retained compact receipt SHA-256 is ba36c065802fe46edba4292076e3a83a1df3c92556af14c4fd62926d8cde502e; the requalified final HDF SHA-256 is 278115f26937d64810faa6175229a502e2fb90dbb8c03efe6d525879bf91928b.

Format matrix¶

Source or representation	Vendor support	Qualification state	Required treatment
HEC-DSS grid	Documented from 6.0	Executed on selected 6.x/7.x Windows releases	Preserve DSS pathname, units, and period semantics; validate temporary and final HDF
GDAL NetCDF	Documented from 6.0	Explicit vendor import plus full cumulative/rate qualification on all eleven stable Windows releases and ten Wine releases; see current investigation above	Configure source, explicitly import, inspect temporary forcing, then verify final rainfall and hydraulics; unsupported semantics are rejected
GDAL GRIB/GRIB2	Documented from 6.0	Real filtered NOAA HRRR GRIB2 decoded and authored to native HDF; native executable preprocessing remains open	Qualify native preprocessing across representative encodings; never equate GDAL readability or ras-commander translation with native HEC-RAS support
WPC QPF GRIB2	Vendor-known compression incompatibility through 7.0.1	Fully executed qpkit/pydsstools translation and HEC-RAS 7.0 qualification on the 26 September 2026 00Z cycle	Crop in the GRIB's native projection, verify the crop, translate to validated DSS, then inspect temporary/final HDF values; do not use qpkit 0.1.0's unreliable `QPFGridOptions.extents` mask
GeoTIFF precipitation series	Not documented as a vendor-native meteorology source	Supported through ras-commander translation; qualified on Windows 6.6/7.0 and Linux/Wine 11 with HEC-RAS 6.6	Explicit timestamps/units/semantics → content-addressed NetCDF plus native HDF payload; never advertise direct vendor GeoTIFF ingestion
Imported Raster Data HDF	Internal RAS materialization	Issue #371 implementation/test concern	Treat as internal solver-facing payload, not an external input-format promise

Version-specific defects and limitations¶

Affected version(s)	Vendor finding	ras-commander policy candidate
6.0-6.1	Optional precipitation ratio is not applied; HEC lists the fix in 6.2	Warn or reject non-unit ratio unless source values are intentionally pre-scaled; never silently compensate
6.0-6.3.1	Period-average to instantaneous interpolation can shift the result in time. The claimed 6.3 fix was incomplete; 6.4 centers the period and removes the one-period shift	Prefer interval totals/PER-CUM where semantics permit, or require 6.4+ for period-average data; add timing assertions
6.2	Storage areas can fail to receive simple time-series precipitation; HEC lists the fix in 6.3	Keep this distinct from the global gridded route; test only if uniform storage-area precipitation is in scope
6.2 and earlier visualization	Cumulative spatial-precipitation display and some constant/DSS surface defaults were corrected in 6.3	Do not use map appearance alone as solver evidence; inspect HDF values
6.4.1-6.6	HEC lists missing infiltration losses for 1D elements using the finite-volume method, causing total rather than excess precipitation to enter the 1D system	Warn for 1D finite-volume plus infiltration; the 2D fixture in this report does not exercise this defect. A 7.x fix was not established from the reviewed notes
6.5	Newly created infiltration layers may not be recognized; HEC lists correction in 6.6	Version-specific geometry/infiltration authoring test, separate from rainfall source routing
6.5 and earlier migration	HEC 6.6 fixed migration of infiltration/percent-impervious associations and layer typing	Recompute and audit property tables when moving older projects; do not infer successful migration from project load
6.3.1-7.0.1	WPC QPF GRIB2 compression is not accepted	Route explicitly through Vortex/MetVue to DSS

The WPC qualification also identified an external-tool limitation independent of HEC-RAS version: qpkit 0.1.0 produced the same undersized 2-by-2 DSS grid for materially different QPFGridOptions.extents requests. Notebook 926 avoids that path by cropping and reopening every GRIB in its native projection before calling kit.qpf_dss.write() without extents.

The HEC known-issues pages use rolling status labels that can appear adjacent to the next row when extracted. This report relies on the issue description and the later release's resolved-issues entry, not the color/status word alone.

Downstream workflow audit¶

The table below records the initial audit. PR #376 follow-up changes retired 722's obsolete authoring cells, added explicit temporal semantics and temporary-HDF checks to 727/900/901/914/916, corrected 924's precompute depth label, and clarified the scope of 915/917/926. A fresh Windows 6.6 execution of 729 passed after the cache transform correction. A RasExamples regression verifies AORC's first nonzero interval in the authored HDF. Full live-product reruns for each changed notebook and the remaining cross-version semantic matrix are still separate qualification tasks; old outputs are not evidence for newly changed source cells.

Notebook	Current route	Current evidence	Required requalification
727 Atlas 14	Atlas 14 grid to NetCDF to native rain-on-grid	All 20 code cells executed; compute plus rainfall-rate figures	Retain as the design-storm canonical example; add temporary-HDF and manual-message/map review checks
722 Atlas 14	Legacy/conceptual mix of raw edits, gridded setup, and uniform comparison	29 code cells, no committed outputs	Replace with a concise link/migration explanation to 727; do not keep raw text mutation as canonical
728 DSS window extension	Model-covering deterministic DSS family copied with an explicit zero tail, then applied through `configure_gridded_dss_precipitation()`	Fully executed under HEC-RAS 7.0: source SHA preserved, 3 source plus 3 appended records, five-hour model window, exact three-hour dry tail, 0.0000002-inch DSS-to-temporary-HDF maximum error, zero flagged BCO diagnostics, 18,066 active final-HDF cells, 0.000005-inch mean error and 0.000693-inch RMSE, positive hydraulic results, and 4 review figures	Retain source-immutability, temporary/final-HDF, zero-tail plateau, hydraulic, and manual-review gates; the helper remains mechanical preparation and does not infer a scientifically appropriate drain-down window
729 GeoTIFF	Explicit GeoTIFF series translated to durable NetCDF plus native HDF	Windows and Linux/Wine 11 HEC-RAS 6.6 passed authoring, temporary-HDF validation, compute, and final rainfall/hydraulics	Retain as the canonical GeoTIFF example and keep Windows/Wine evidence release-specific
900/901 AORC	AORC NetCDF and `set_gridded_precipitation()`	Nearly all cells executed; bulk plan creation/compute	Add explicit units/value semantics, first-timestep checks, temporary-HDF rainfall, final totals, hydraulic response, and manual diagnostics reminder
914 historical diagnostic	Archived AORC NetCDF direct route plus USGS stage	Fully executed under HEC-RAS 7.0: exact 48-hour source timing, durable native-HDF authoring, 0.000003-inch source-to-temporary and source-to-final maximum errors, 18,066 active final-HDF cells, zero flagged BCO diagnostics, 0.001523% volume error, five review figures, and a timezone-correct USGS comparison	Retain the source/precompute/final-HDF gates and explicit manual review. The gauge comparison is diagnostic, not calibration validation, because the fixture does not include reviewed historical boundary hydrographs, initial conditions, or gate/control histories.
924 MRMS	MRMS NetCDF direct route	Strong code contract but 12 code cells have no committed outputs	Re-execute after core writer lands; retain cumulative/rate and hydraulic visual checks; add temporary-HDF assertion and manual review reminder
917 MRMS	GRIB2 to DSS for spatial source inspection; rectangular-clip mean to uniform boundary hyetographs	Four hourly US-customary HEC-RAS 7.0 baseline/event runs. Every cumulative rainfall value matches the written curve at 505 times across 2,705 Davis physical cells and 361 times across 19,711 New Orleans physical cells; maximum event errors are 2.10e-7 and 5.85e-7 inches. Boundary-only cells and selected-area baselines are dry. Saved outputs inspect retained computations and regenerate consistent HDF-based diagnostic figures; native and inspection runtimes are separate.	Limited to simulation-start boundaries and the stated models/version/units. Davis DS Channel precipitation datasets are unavailable. New Orleans cell 16058 is included through verified native connectivity despite its detailed-polygon omission (#438). Broader forcing and hydraulic acceptance remain open (#398); notebook 924 is the spatial MRMS rain-on-grid route.
916 HRRR	Archived HRRR GRIB cumulative APCP differenced into 18 hourly native DSS grids	Fully executed under HEC-RAS 7.0 with source/DSS plots, exact DSS-to-temporary-HDF check (0.000002-inch maximum error), active-cell final-HDF comparison, no-rain/forecast hydraulics, mass balance, runtime-message audit, and mapped localized convergence exceptions	Retain as the forecast/DSS canonical example; qualify additional supported version families separately and continue manual review of messages, rainfall maps, and the three localized cells above 0.1-foot maximum water-surface error
915 forecast orchestration	Deterministic cycle manifest, current public-signature audit, timezone conversion, and executed-component dashboard	Fully executed: 6 of 6 code cells, zero stored errors, two review figures, and artifact checks over executed notebooks 916/923/924/926	Retain as an orchestration/readiness guide. It deliberately performs no live download or HEC-RAS compute and does not count as format/version qualification; component notebooks retain that evidence.
926 WPC	Current WPC GRIB2 cropped in its native projection, translated to DSS, and applied through global gridded meteorology	Fully executed under HEC-RAS 7.0: 11 of 11 code cells, complete 28-grid 26 September 2026 00Z cycle, objective wettest 24-hour window, source-to-DSS regional checks, exact DSS-to-temporary-HDF check (0.0000002-inch maximum error), no-rain/event computes, zero flagged BCO diagnostics, active-cell final-HDF comparison (-0.000229-inch mean error; 0.003105-inch RMSE), hydraulic response, and 5 review figures	Retain the native-projection pre-crop workaround for qpkit 0.1.0, the explicit manual-review requirement, and mapped review of the three localized cells above 0.1-foot maximum WSEL error

Notebook 917's New Orleans event retains a pipe-network iteration-table diagnostic for node 426, "Mine Blvd - Node 1," at 2024-04-10 14:32:28, with native ERROR value 0.450. Its reported volume-accounting error is 8.03992 acre-ft / 0.122344%. A zero structured error count does not erase that diagnostic or establish hydraulic acceptance; the retained native messages remain part of the required engineering review.

Every canonical notebook should finish by reminding users that automated checks supplement, rather than replace, manual review of HEC-RAS runtime messages, precipitation maps, timing, units, and hydraulic response.

Historical proposed PR boundaries¶

Version evidence PR (this branch): this report, compact JSON capability evidence, the public-API qualification harness, and deterministic harness tests. No production guards or speculative support claims.
Legacy Windows host compatibility PR: extend the existing library-owned WMIC compatibility path to the evidence-backed 6.0/6.1/6.2 cohort (now qualified on the native-NetCDF fixture). Test process scoping, exact queried fields, environment restoration, and unmodified-versus-shim evidence.
Capability and routing PR: one normalized-version registry; reject global gridded meteorology before 6.0; issue evidence-backed warnings for 6.0/6.1 ratio and 6.0-6.3.1 period-average behavior; report route/reason. Keep the initial DSS 6.5 profile failure separate from the subsequently qualified native-NetCDF route.
Native raster semantic qualification PR: deterministic asymmetric, non-hourly NetCDF and representative GRIB payloads across the minimum releases needed to prove schema transitions. Cover rate, interval amount, cumulative depth, first timestep, inches/millimeters, orientation, nodata, temporary HDF, messages, final rainfall, and hydraulics.
Translation adapter PR: establish a canonical precipitation cube, first-class GeoTIFF/GRIB-to-NetCDF ingestion, and explicit translation routes. The GeoTIFF feature now has direct HEC-RAS 6.6 Windows and Wine evidence; retain its value/timing/CRS/nodata acceptance tests. Qualify WPC QPF and other encodings separately rather than generalizing from GeoTIFF.
Wine qualification PR: retain the 6.6 translated-GeoTIFF and native DSS evidence, including the resolved disabling-DLL-override control. Resolve 6.4.1 exact-profile TCU provisioning and COM registration before making any 6.4.1 precipitation claim. Keep Windows and Wine claims separate.
Product/notebook PRs: requalify AORC, MRMS, HRRR, WPC, Atlas 14, and NEXRAD/DSS using the common semantics and routing layer, then commit cleaned notebooks plus compact receipts rather than model outputs.