A completed HEC-RAS simulation leaves you with results, not yet with answers. Comparing an existing-condition plan with a proposed design still means locating the right outputs, checking units and timestamps, plotting hydrographs, and investigating where water levels or flow behavior changed. A convincing map alone cannot establish whether those differences are meaningful.

Claude Code can help organize that analysis. It can prepare scripts to inspect result files, extract selected time series, calculate differences, and produce charts with traceable source references. HEC-RAS stores substantial output in HDF5 result files, while its own tables and RAS Mapper provide reference checks.

Vagon Cloud Computer brings HEC-RAS, Claude Code, Python, and the project files into one Windows workspace. You can analyze the outputs and inspect flagged locations in the application without moving large result files between computers.

This guide follows two completed plans from initial inventory to a reviewed comparison report. Claude Code supports the analysis; you retain responsibility for the hydraulic interpretation.

Source: USACE Hydrologic Engineering Center

Define the Questions Before Opening the Results

Start with a comparison brief, not a request to “analyze everything.” For this example, assume two completed plans represent existing and proposed conditions for the same flood event. Your first job is to identify what the comparison needs to explain.

Keep these questions separate. A change in water-surface elevation is not automatically the same change in flood depth, particularly if terrain differs between plans. Likewise, a higher peak does not establish a complete change in flood risk.

Give Claude Code a bounded planning task:

The brief should also define deliverables: a comparison table, selected hydrographs, and an exception list for further review. Any threshold must come from the project requirements or a qualified reviewer, not from the assistant’s judgment.

Keep HEC-RAS, Claude Code, and the Analysis Files Together

Set up the workspace so Claude Code can analyze the result files while you check the same plans in HEC-RAS. Keeping both tasks on one computer avoids repeatedly transferring large outputs just to investigate a flagged location.

1. Select the applications

During Vagon computer creation, use application selection to choose HEC-RAS, the available Claude tooling, and Python.

Once the desktop is ready, open HEC-RAS and confirm its version. Check that Claude Code is available in the terminal and complete the required sign-in. A Claude desktop application and the Claude Code command-line tool are not interchangeable, so verify the tool you will actually use:

2. Prepare the analysis environment

Create a dedicated Python environment inside the analysis folder:

python -m venv .venv
.\.

python -m venv .venv
.\.

h5py reads HDF5 datasets, pandas organizes tables and time series, and matplotlib produces charts. Ask Claude Code to use this environment’s interpreter consistently.

These packages support post-processing. They do not replace HEC-RAS or establish that extracted variables have been interpreted correctly.

3. Transfer the project and preserve its sources

Use Vagon Files to bring in the project, completed plan outputs, computation logs, and supporting terrain or mapping files needed for review.

Keep their existing relative folder structure intact. A plan HDF may contain useful results on its own, but opening the complete project and associated maps can require additional dependencies.

Place generated analysis in separate folders:

Before proceeding, confirm that the intended plans open and their results are accessible. Instruct Claude Code to read from source_project and write only to the analysis folders. That instruction sets the workflow boundary; use filesystem permissions or a protected source copy when you need enforcement.

Build an Inventory of What Was Actually Computed

Before extracting values, establish which results belong to each completed run. A filename such as RiverModel.p01.hdf identifies a plan output, but it does not establish the scenario, simulation period, or variables available inside it.

Source: USACE Hydrologic Engineering Center

Ask Claude Code to inspect the project without changing it:

For HDF files, have the script inspect dataset names, dimensions, and attributes before reading large arrays. HEC-RAS documents HDF5 output, but available variables depend on the model, software version, and output settings.

Separate the plan from the completed result

A plan can reference a geometry file that someone edited after the simulation. The result HDF contains a copy of the geometry used during that run, making it important evidence when establishing what was actually computed.

Build a compact inventory table with one row per result set: scenario label, plan identifier, simulation period, model components, units, and verification status.

Also distinguish the computational timestep from recorded output intervals. Saved time series may not contain every internal calculation step, and different output groups may use different timestamps.

Resolve those uncertainties before comparing scenarios. If a required variable or location is absent, report the gap rather than substituting a similarly named dataset.

Check the Run Before Summarizing Its Results

Before calculating scenario differences, check whether both simulations completed and whether their records contain numerical issues that require investigation. An output file can exist even when a run stopped early.

Start with the computation logs and any saved computational messages. HEC-RAS records numerical stability and volume accounting information, including locations where the solution did not meet the specified numerical tolerance. Repeated maximum-iteration messages accompanied by significant errors deserve closer inspection.

Source: USACE Hydrologic Engineering Center

Ask Claude Code to organize the evidence, not declare the model “stable”:

Turn messages into a review list

Use a table that connects each finding to a specific follow-up:

HEC-RAS provides volume accounting for the overall model and individual 2D flow areas. Preserve those distinctions rather than reducing everything to one percentage.

A small volume error does not establish calibration, correct boundary conditions, or design suitability. Likewise, a warning is a reason to investigate, not automatic proof that every result is unusable.

Keep unresolved findings attached to the analysis. If the proposed-condition peak occurs during a flagged period, that limitation belongs beside the comparison, not buried in an appendix. Decisions about changing timestep, mesh, roughness, or other model settings remain a separate, explicitly approved modeling task.

Extract Only the Results Your Analysis Needs

Choose the simplest extraction route that answers the comparison questions. For a few review locations, application tables may be enough. For repeated analysis across many locations or plans, a read-only HDF5 script is more practical.

HEC-RAS supports copying values from time-series plots and tables. When saving those values as CSV, record the plan, selected element, variable, units, and time basis alongside them. A column of numbers without that context is not a reliable analysis input.

Inspect HDF datasets before selecting values

For direct extraction, begin with a structure report rather than loading the entire file:

Replace the example filename with the inventoried result file. The "r" mode opens it read-only; this script lists datasets without reading their full arrays.

Source: USACE Hydrologic Engineering Center

Next, ask Claude Code to inspect the attributes and associated identifiers for the required datasets. Confirm which dimension represents time and which represents model elements. Match the values to their actual timestamp dataset rather than assuming every output group shares one time axis.

Preserve the meaning of each variable

A 1D cross-section water level, a 2D cell water level, and a cell-face velocity are not interchangeable observations. In particular, face-normal velocity is a directional component, not automatically the velocity magnitude displayed on a map.

Extract only the required locations and time slices. Save each extracted table with a companion record containing:

• Source file and exact dataset paths.

• Element identifiers and location-matching method.

• Units, timestamps, and any conversions.

• Missing-value handling and extraction script version.

Finally, compare several extracted values against the corresponding HEC-RAS table or hydrograph. If they disagree, investigate indexing, timestamps, variable definitions, and display precision before calculating scenario differences. Do not repair the mismatch by applying an unexplained offset or scale factor.

Source: USACE Hydrologic Engineering Center

Compare Scenarios Without Mixing Locations or Time Steps

Before subtracting one result from another, confirm that the values represent a meaningful comparison. Two plans can use similar names while differing in simulation period, geometry, terrain, or boundary conditions.

Have Claude Code produce a compatibility table first:

Use HEC-RAS’s Model Comparison Tool, where supported by your installed version, to help identify differences in the underlying plans and results.

Source: USACE Hydrologic Engineering Center

Define the subtraction explicitly

For this example:

A positive water-surface elevation difference therefore means the proposed result is higher. Put that convention in table headings, chart labels, and report captions.

Source: USACE Hydrologic Engineering Center

If the mesh changed, do not match results by cell number alone. The same identifier may refer to a different location. Use an approved spatial matching or common-grid method, and document any interpolation. Even unchanged coordinates require care when nearby structures or cell geometry differ.

Separate peak differences from simultaneous differences

These calculations answer different questions:

The two peaks may occur at different times. Label the first calculation as a difference between recorded peaks, not the largest increase at a shared instant.

For simultaneous comparisons, align timestamps using a documented rule. Do not silently fill missing observations with zero or interpolate across gaps. If temporal interpolation is approved, retain the original series and identify the derived values.

Ask Claude Code to flag incompatible locations or time ranges instead of forcing every record into a comparison. A shorter table of defensible differences is more useful than a complete-looking table built on uncertain matches.

Create Hydrographs and an Exception Table

Once locations and timestamps are matched, turn the extracted results into a small set of review outputs. Start with an overlaid hydrograph, a simultaneous-difference plot, and a summary table for each selected location.

Source: USACE Hydrologic Engineering Center

Use consistent units and axes. Label water-surface elevation as elevation, not depth, and include the vertical reference where confirmed. Mark recorded peaks without smoothing the curves or removing inconvenient values.

Ask Claude Code to generate the outputs with explicit calculation rules:

Define threshold duration before calculating it

If the review includes time above an elevation, specify the threshold and duration method. Counting samples is not enough when output intervals vary.

For example, a calculation might sum intervals whose starting sample exceeds the threshold. Another method might linearly interpolate threshold crossings. These approaches can produce different durations, so obtain approval for the method and describe it in the output.

Report the result as an estimate based on saved observations. The recorded output interval may be coarser than the computational timestep, limiting how precisely peaks and crossings can be located. If several samples share the maximum value, report the tie or plateau rather than inventing one unique peak time.

Keep exceptions actionable

Each exception row should contain:

Call this a review list, not a safety classification. Claude Code can identify where a supplied rule was exceeded; a qualified reviewer determines what that finding means.

Verify the Findings in RAS Mapper and Package the Report

Use the exception table to guide application-level review. Start with the largest changes, locations affected by numerical warnings, and any result that appears inconsistent with nearby behavior.

Open the correct completed plan in RAS Mapper, then confirm the variable and selected profile before interpreting the display. A maximum-depth layer and a water-surface elevation layer answer different questions, even when their colors look similar.

Source: USACE Hydrologic Engineering Center

Match the map to the calculation

HEC-RAS distinguishes dynamic and stored results maps. Dynamic depth mapping depends on terrain and display resolution, so a value read from a zoomed-out map is not necessarily equivalent to a computational-cell result.

Check each flagged finding against the appropriate reference:

A maximum map is an envelope of local maxima, which may occur at different times. Do not describe it as the flood condition at one shared instant. For a simultaneous comparison, select the same timestamp in both plans.

Source: USACE Hydrologic Engineering Center

Where available, use the Model Comparison Tool as an additional check. Confirm its subtraction direction before comparing it with the Python analysis.

Package evidence, not just conclusions

Save the reviewed analysis as a reproducible package:

• Comparison tables and extracted time series.

• Labeled hydrographs and difference plots.

• An exception table with review notes.

• Source-file and dataset references.

• Scripts, environment details, and calculation settings.

• Assumptions, unresolved issues, and a concise findings summary.

Give Claude Code a constrained reporting task:

Review the generated text against the tables. Check scenario names, difference signs, units, and timestamps, especially where peaks occur at different times.

Screenshots can illustrate the findings, but retain the numerical outputs behind them. The final report should let another reviewer trace a statement back to the selected result and reproduce the calculation without relying on the assistant’s explanation alone.

Keep Large Result Files Manageable

A large HDF file does not need to become one equally large in-memory array. Ask Claude Code to inspect dataset dimensions first, then read only the variables, locations, and time ranges required by the analysis.

With h5py, slicing a dataset can avoid loading its full contents. Actual performance depends on how the file is organized, including chunking and compression, so measure a representative extraction before scaling up.

Keep the workflow efficient:

Do not treat an existing CSV as current simply because its filename matches the plan. Link cached extracts to the source result file, dataset paths, and script settings. Regenerate them when the source changes.

CPU, RAM, and storage throughput usually deserve attention before GPU capacity for this type of tabular post-processing. GPU acceleration requires an implementation that actually uses it.

Keeping the results and scripts on the cloud workstation reduces repeated transfers to your own device. Start with one reader process, measure runtime and memory, and increase concurrency only when it improves the workload without exhausting resources.

Final Thoughts

Claude Code is most useful when it makes HEC-RAS analysis easier to trace and repeat. It can organize outputs, prepare extraction scripts, compare verified time series, and draft evidence-linked summaries. It should not decide whether a hydraulic result is acceptable on its own.

With Vagon Cloud Computer, HEC-RAS, Claude Code, Python, and the result files stay in one Windows workspace. Start with a few review locations, verify the calculations in the application, and expand the analysis once that foundation is reliable.

FAQs

Can Claude Code read HEC-RAS HDF files?

It can prepare and run Python scripts using libraries such as h5py, subject to your permissions. The script must inspect the file structure and verify dataset meanings, dimensions, units, and timestamps before extracting values.

Do I need MCP or HEC-RAS Controller for post-processing?

Not for the file-based workflow described here. Reading existing HDF files and analyzing exported tables does not require either integration. Controlling the application or launching simulations is a separate task.

Can I analyze results without rerunning the model?

Yes, when the required information exists in the saved outputs. Missing variables or reference-location results may require another extraction approach or an explicitly approved rerun. The assistant should report missing information rather than fabricate it.

Are 1D and 2D results extracted in the same way?

They can share the same file format, but their structures and meanings differ. Cross sections, cells, faces, and reference locations require appropriate identifiers and interpretation.

Can I compare plans with different meshes?

Yes, with a documented spatial comparison method. Matching cell numbers alone is insufficient. Confirm physical locations, terrain, coordinate references, and any interpolation used.

Does a low volume error prove the model is accurate?

No. Volume accounting is one numerical check. It does not establish calibration, correct inputs, suitable boundary conditions, or engineering validity.

Can Claude Code certify flood risk or design safety?

No. It can support calculations and organize evidence, but qualified professionals remain responsible for hydraulic interpretation, design review, and any required certification.