Skip to content

Profile Line Flow Extraction

Extract a hydrograph and peak flow for one named line from completed 2D results. This is a flow-versus-time example, not a velocity/depth-versus-station plot. Use 416 for station profiles and 314 for reference features authored before computation and plotted in batches.

Required input Returned output
Completed plan HDF, exact line/mesh names, and (for an ad-hoc line) its Mapper feature source Time-series DataFrame with time, flow, selection source, face count, and direction metadata
Same inputs for the peak helper Peak time and flow with the same selection provenance

The current canonical methods use pythonnet and HEC-RAS RasMapperLib. They first try a precomputed hydrograph that RasMapperLib associates with the reference line (try_read_ref_line_flow); its provenance has not been independently qualified as solver-recorded rather than observed/event-associated data. Otherwise they read selected face flows, using native Mapper perimeter-face selection for an ad-hoc line. Use HdfResultsXsec.get_ref_lines_timeseries() to read the solver-recorded HDF reference-line result group explicitly. The explicitly named _legacy method is the separate offline reconstruction path. See 2D profile and reference workflows and native profile API reference for the contracts.

Saved-run scope: the retained Chippewa tables report selection_source="profile_lines_geometry" with six faces. They document the historical reconstruction run, not a fresh test of the current canonical native path. Code and outputs are unchanged in this editorial update. A current native rerun is required before treating these outputs as native-runtime qualification.

The committed native regression fixture for the same Chippewa plan/line/mesh records seven faces (rasmapper_perimeter_faces), a first absolute flow of 18,093.43 cfs, first signed flow of -18,093.43 cfs, and peak absolute flow of 38,000.63 cfs. The historical outputs below show six faces, 1,948.33 cfs absolute and +494.81 cfs signed at the first time, and 2,316.14 cfs peak. Rerunning the unchanged code against that fixture is therefore expected to change the face set and the numerical results substantially. These are different extraction paths, not interchangeable validation targets; this comparison does not establish which flow should be accepted for engineering use. See the native regression tests and retained native CSV.

Python
from pathlib import Path
import os

import matplotlib.pyplot as plt
import pandas as pd

from ras_commander import HdfResultsMesh

Development mode: run this notebook with PYTHONPATH pointed at the repository root when testing local source changes. The committed import cell above intentionally uses the installed/importable package form.

Inputs, Direction, And Comparison Scope

The input folder is an external completed Chippewa validation fixture, not a bundled dataset. Set CLB214_PROFILE_LINE_VALIDATION or supply your own completed plan and line source. The selected-face path requires saved Face Flow output; a map image alone is insufficient.

Inspect selection_source before interpreting the result:

  • With selection_source="try_read_ref_line_flow", the native-associated precomputed hydrograph is used as returned; direction="absolute" takes its magnitude. Its solver-versus-observed provenance remains unqualified. Do not treat the native call alone as proof that these are computed model results.
  • A selected-face result with direction="absolute" sums individual face-flow magnitudes. With direction="signed", it sums their native signs. Those signs belong to mesh face orientation, not a common transect-normal convention. Neither operation automatically establishes net downstream discharge.

The signed/absolute comparison exposes cancellation and selection behavior. Agreement with the optional manual face-sum CSV checks that calculation, not agreement with a flow-weighted Mapper statistic, recorded line hydrograph, or measured discharge. Review selected faces, wet/dry conditions, structures, line orientation, and possible recirculation before using a peak for design.

The retained plot labels flow in cfs for this project. For another model, read returned units metadata and confirm units before setting labels. The peak is selected from saved result times, not necessarily the computational-timestep peak. For many lines, repeat with explicit line/mesh names and retain provenance with each exported plot.

Python
validation_root = Path(
    os.environ.get(
        "CLB214_PROFILE_LINE_VALIDATION",
        r"H:/Symphony/ras-commander/CLB-214/profile_line_flow_validation",
    )
)
project_dir = validation_root / "project" / "Chippewa_2D_profile_line_flow"
plan_hdf = project_dir / "Chippewa_2D.p02.hdf"
profile_lines_path = validation_root / "profile_line_input"

line_name = "Upstream"
mesh_name = "Perimeter 1"

if not plan_hdf.exists():
    raise FileNotFoundError(
        f"Completed plan HDF not found: {plan_hdf}. "
        "Set CLB214_PROFILE_LINE_VALIDATION or replace plan_hdf/profile_lines_path "
        "with a completed project that outputs Face Flow."
    )

print(f"Plan HDF: {plan_hdf}")
print(f"Profile line source: {profile_lines_path}")
Text Only
Plan HDF: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
Profile line source: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\profile_line_input
Python
flow_ts = HdfResultsMesh.get_profile_line_flow_timeseries(
    plan_hdf,
    line_name,
    mesh_name=mesh_name,
    profile_lines_path=profile_lines_path,
    direction="absolute",
)

peak_q = HdfResultsMesh.get_profile_line_peak_flow(
    plan_hdf,
    line_name,
    mesh_name=mesh_name,
    profile_lines_path=profile_lines_path,
)

display(flow_ts.head())
display(peak_q)
Text Only
2026-05-01 12:58:20 - ras_commander.hdf.HdfResultsMesh - INFO - Using existing Path object HDF file: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf


2026-05-01 12:58:20 - ras_commander.hdf.HdfResultsMesh - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf


2026-05-01 12:58:20 - ras_commander.hdf.HdfMesh - INFO - Using existing Path object HDF file: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.g01.hdf


2026-05-01 12:58:20 - ras_commander.hdf.HdfMesh - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.g01.hdf


2026-05-01 12:58:20 - ras_commander.hdf.HdfMesh - INFO - Using existing Path object HDF file: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf


2026-05-01 12:58:20 - ras_commander.hdf.HdfMesh - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf


2026-05-01 12:58:20 - ras_commander.hdf.HdfMesh - INFO - Using existing Path object HDF file: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf


2026-05-01 12:58:20 - ras_commander.hdf.HdfMesh - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf


2026-05-01 12:58:20 - ras_commander.hdf.HdfBase - INFO - Using HDF file from h5py.File object: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf


2026-05-01 12:58:20 - ras_commander.hdf.HdfBase - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf


2026-05-01 12:58:20 - ras_commander.hdf.HdfBase - CRITICAL - No valid projection found. Checked:
1. HDF file projection attribute: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2. RASMapper projection file H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\.Winona_Upload\LifeSim model\Winona Levee SQRA 2019\RAS\AW\MMC_Projection.prj found in RASMapper file, but was invalid
To fix this:
1. Open RASMapper
2. Click Map > Set Projection
3. Select an appropriate projection file or coordinate system
4. Save the RASMapper project


2026-05-01 12:58:20 - ras_commander.hdf.HdfMesh - INFO - Found 6 faces along profile line


2026-05-01 12:58:20 - ras_commander.hdf.HdfResultsMesh - INFO - Using existing Path object HDF file: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf


2026-05-01 12:58:20 - ras_commander.hdf.HdfResultsMesh - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf


2026-05-01 12:58:20 - ras_commander.hdf.HdfResultsMesh - INFO - Using existing Path object HDF file: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf


2026-05-01 12:58:20 - ras_commander.hdf.HdfResultsMesh - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf


2026-05-01 12:58:21 - ras_commander.hdf.HdfResultsMesh - INFO - Using existing Path object HDF file: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf


2026-05-01 12:58:21 - ras_commander.hdf.HdfResultsMesh - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf


2026-05-01 12:58:21 - ras_commander.hdf.HdfMesh - INFO - Using existing Path object HDF file: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.g01.hdf


2026-05-01 12:58:21 - ras_commander.hdf.HdfMesh - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.g01.hdf


2026-05-01 12:58:21 - ras_commander.hdf.HdfMesh - INFO - Using existing Path object HDF file: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf


2026-05-01 12:58:21 - ras_commander.hdf.HdfMesh - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf


2026-05-01 12:58:21 - ras_commander.hdf.HdfMesh - INFO - Using existing Path object HDF file: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf


2026-05-01 12:58:21 - ras_commander.hdf.HdfMesh - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf


2026-05-01 12:58:21 - ras_commander.hdf.HdfBase - INFO - Using HDF file from h5py.File object: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf


2026-05-01 12:58:21 - ras_commander.hdf.HdfBase - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf


2026-05-01 12:58:21 - ras_commander.hdf.HdfBase - CRITICAL - No valid projection found. Checked:
1. HDF file projection attribute: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2. RASMapper projection file H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\.Winona_Upload\LifeSim model\Winona Levee SQRA 2019\RAS\AW\MMC_Projection.prj found in RASMapper file, but was invalid
To fix this:
1. Open RASMapper
2. Click Map > Set Projection
3. Select an appropriate projection file or coordinate system
4. Save the RASMapper project


2026-05-01 12:58:21 - ras_commander.hdf.HdfMesh - INFO - Found 6 faces along profile line


2026-05-01 12:58:21 - ras_commander.hdf.HdfResultsMesh - INFO - Using existing Path object HDF file: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf


2026-05-01 12:58:21 - ras_commander.hdf.HdfResultsMesh - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
time flow line_name mesh_name direction face_count selection_source
0 2019-04-02 00:00:00 1948.334485 Upstream Perimeter 1 absolute 6 profile_lines_geometry
1 2019-04-02 00:30:00 1945.119192 Upstream Perimeter 1 absolute 6 profile_lines_geometry
2 2019-04-02 01:00:00 1919.116215 Upstream Perimeter 1 absolute 6 profile_lines_geometry
3 2019-04-02 01:30:00 1881.967214 Upstream Perimeter 1 absolute 6 profile_lines_geometry
4 2019-04-02 02:00:00 1849.279263 Upstream Perimeter 1 absolute 6 profile_lines_geometry
line_name mesh_name peak_time peak_flow direction face_count selection_source
0 Upstream Perimeter 1 2019-04-21 01:00:00 2316.140572 absolute 6 profile_lines_geometry
Python
signed_flow_ts = HdfResultsMesh.get_profile_line_flow_timeseries(
    plan_hdf,
    line_name,
    mesh_name=mesh_name,
    profile_lines_path=profile_lines_path,
    direction="signed",
)

comparison = flow_ts[["time", "flow"]].rename(columns={"flow": "absolute_flow"}).merge(
    signed_flow_ts[["time", "flow"]].rename(columns={"flow": "signed_flow"}),
    on="time",
)
display(comparison.head())
Text Only
2026-05-01 12:58:21 - ras_commander.hdf.HdfResultsMesh - INFO - Using existing Path object HDF file: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf


2026-05-01 12:58:21 - ras_commander.hdf.HdfResultsMesh - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf


2026-05-01 12:58:21 - ras_commander.hdf.HdfMesh - INFO - Using existing Path object HDF file: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.g01.hdf


2026-05-01 12:58:21 - ras_commander.hdf.HdfMesh - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.g01.hdf


2026-05-01 12:58:21 - ras_commander.hdf.HdfMesh - INFO - Using existing Path object HDF file: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf


2026-05-01 12:58:21 - ras_commander.hdf.HdfMesh - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf


2026-05-01 12:58:21 - ras_commander.hdf.HdfMesh - INFO - Using existing Path object HDF file: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf


2026-05-01 12:58:21 - ras_commander.hdf.HdfMesh - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf


2026-05-01 12:58:21 - ras_commander.hdf.HdfBase - INFO - Using HDF file from h5py.File object: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf


2026-05-01 12:58:21 - ras_commander.hdf.HdfBase - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf


2026-05-01 12:58:21 - ras_commander.hdf.HdfBase - CRITICAL - No valid projection found. Checked:
1. HDF file projection attribute: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2. RASMapper projection file H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\.Winona_Upload\LifeSim model\Winona Levee SQRA 2019\RAS\AW\MMC_Projection.prj found in RASMapper file, but was invalid
To fix this:
1. Open RASMapper
2. Click Map > Set Projection
3. Select an appropriate projection file or coordinate system
4. Save the RASMapper project


2026-05-01 12:58:22 - ras_commander.hdf.HdfMesh - INFO - Found 6 faces along profile line


2026-05-01 12:58:22 - ras_commander.hdf.HdfResultsMesh - INFO - Using existing Path object HDF file: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf


2026-05-01 12:58:22 - ras_commander.hdf.HdfResultsMesh - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
time absolute_flow signed_flow
0 2019-04-02 00:00:00 1948.334485 494.805432
1 2019-04-02 00:30:00 1945.119192 490.561087
2 2019-04-02 01:00:00 1919.116215 466.979741
3 2019-04-02 01:30:00 1881.967214 432.740896
4 2019-04-02 02:00:00 1849.279263 406.301601
Python
manual_validation_csv = validation_root / "manual_face_flow_validation.csv"
if manual_validation_csv.exists():
    manual = pd.read_csv(manual_validation_csv, parse_dates=["time"])
    validation = comparison.merge(manual, on="time")
    print(
        "Max absolute-flow difference:",
        validation["absolute_difference"].abs().max(),
    )
    print(
        "Max signed-flow difference:",
        validation["signed_difference"].abs().max(),
    )
Text Only
Max absolute-flow difference: 0.0
Max signed-flow difference: 0.0
Python
fig, ax = plt.subplots(figsize=(10, 4))
ax.plot(flow_ts["time"], flow_ts["flow"], label="Absolute flow")
ax.plot(signed_flow_ts["time"], signed_flow_ts["flow"], label="Signed flow")
ax.set_ylabel("Flow (cfs)")
ax.set_title(f"{line_name} profile-line flow")
ax.legend()
ax.grid(True, alpha=0.3)
fig.autofmt_xdate()
plt.show()

png