rivia.model

Reads and writes HEC-RAS text input files (.prj, .g*, .p*, .f*, .u*).

Project is the primary interface for working with an HEC-RAS project. It binds a COM controller to a specific project file and provides access to all associated file objects (plan, project, results) through lazy-loaded properties.

class rivia.model.Project(project_file, ras_version=None, backup=False)[source]

Bases: MapperExtension

High-level interface for working with an HEC-RAS project via the COM object.

Use this class in preference to com.open. While com.open returns a raw HEC-RAS controller instance that is not associated with any project, Project binds the COM object to a specific HEC-RAS project file and provides project-aware operations.

Warning

Project is bound to the thread that constructs it (COM STA constraint). All method calls must originate from that thread. For parallel simulations use separate processes, not threads.

At most one Project per HEC-RAS version may be live within a process at a time. Constructing a second Project for the same version while the first is still alive raises RuntimeError. Use with Project(...) as m: or call close() explicitly to free the slot.

Parameters:
chaining(cleanup=False)[source]

Context manager that enables run-chaining for the duration of the block.

Chaining is automatically disabled (and optionally restart files deleted) when the block exits, even if an exception is raised:

with model.chaining():
    for window in windows:
        with model.editing():
            model.plan.simulation_window = window
        model.run()
Parameters:

cleanup (bool) – If True, delete all restart files after chaining ends.

close()[source]

Close the COM connection and release all cached file handles.

Safe to call multiple times. Called automatically on __exit__ when used as a context manager. Frees the per-version slot immediately so a new Project of the same version can be constructed right away.

Return type:

None

property controller
delete_restart_files()[source]

Delete all restart files associated with the current plan.

Restart files follow the pattern <plan_file>.<datestamp>.rst where the plan file extension is .p<digits> (e.g. .p01).

Returns:

Paths of the files that were deleted. Empty if none were found.

Return type:

list[Path]

Raises:

ValueError – If the current plan file does not have the expected .p<digits> extension.

property description: str
property dss: DssReader

Lazily created DssReader for this plan’s DSS output file.

Provides time-series access for cross-sections and inline structures:

flow  = model.dss.flow("Canal 1", "Pool 1-4", "7")
hw    = model.dss.stage_hw("Canal 1", "Pool 1-4", "6.9")
gate1 = model.dss.gate_opening(1, "Canal 1", "Pool 1-4", "6.9")
property dss_path: Path

Path to the DSS output file (project file with .dss extension).

editing()[source]

Context manager for batch file edits with automatic save and reload.

All modifications made inside the block are saved and the project is reloaded on exit:

with model.editing():
    model.plan.simulation_window = (start, end)
    model.plan.computation_interval = "30SEC"
# files saved, project reloaded
enable_chaining(enabled)[source]

Enable or disable run-chaining for sequential simulations.

When chaining is enabled the model automatically writes a restart file at the end of each run (via plan.write_ic_at_end) and configures the flow file to use that file as the initial condition for the next run.

Parameters:

enabled (bool) – True to activate chaining; False to deactivate and reset all chaining state.

Raises:

RuntimeError – If the current plan is not an unsteady-flow plan.

Return type:

None

Notes

Calling enable_chaining(True) multiple times is safe — the run counter is not reset on repeated calls, so chaining can be re-configured mid-sequence without losing track of which run is next.

property flow: SteadyFlow | UnsteadyFlow

Lazily parsed flow file for the current plan.

Cached after first access. Call flow.save() then reload() to write changes back to disk and refresh the cache.

Returns a SteadyFlow when the plan references a steady flow file (extension starting with f), or an UnsteadyFlow when it references an unsteady flow file (extension starting with u).

Raises:

  • ValueError – If the plan has no Flow File= entry, or the extension is not a recognised steady (f*) or unsteady (u*) type.

  • FileNotFoundError – If the flow file path does not exist on disk.

property flow_path: Path

Return the current flow file path.

Raises:

ValueError – If the plan file has no Flow File= entry or the entry is blank.

property geometry: Geometry

Lazily parsed geometry file for the current plan.

Cached after first access. Call geom.save() then reload() to write changes back to disk and refresh the cache.

property geometry_hdf_path: Path

Return the current geometry HDF file path.

property geometry_path: Path

Return the current geometry file path.

hide()[source]
property path: Path

Return the project file path.

property plan: Plan

Lazily parsed plan file.

Cached after first access. Call plan.save() then reload() to write changes back to disk and refresh the cache.

property plan_hdf_path: Path

Return the current plan HDF file path.

property plan_index: int
property plan_path: Path

Return the current plan file path.

plan_staleness(plan=None)[source]

Return a detailed staleness diagnostic report for one plan.

Inspects the plan text file, plan HDF, and geometry HDF to report whether geometry layers are stale, whether the geometry was re-preprocessed since the plan was run, and whether the simulation results appear complete.

No active HEC-RAS simulation is required — the check is purely file-based.

Parameters:

plan (PlanSummary | int | str | None) – Identifies the plan to inspect. Accepts a PlanSummary (from plans()), an integer index, a short_id string, or None (default). When None, the currently active plan (as reported by the COM controller) is used.

Return type:

PlanStalenessReport

Raises:

  • IndexError – If plan is an integer that does not match any plan index.

  • KeyError – If plan is a string that does not match any short_id.

Examples

# active plan
report = model.plan_staleness()
print(report)
if not report.run_appears_complete:
    print("Results may be from a prior or incomplete run.")

# specific plan by index
report = model.plan_staleness(2)
plans(invalidate_cache=False)[source]

All plans in the project with index, title, short_id, path, and active flag.

Plan file data (title, short_id, flow_type, sediment_path, water_quality_path) is read once and cached. The active flag is recomputed on every call without re-reading files.

Parameters:

  • invalidate_cache (bool) – If True, discard the cached plan file data and re-read all plan files from disk. Use this after editing plan files outside of a editing() block or after other external changes.

  • Example:: –

    for p in model.plans():

    active = “*” if p.active else “ ” print(f”[{active}] {p.index}: {p.title} ({p.short_id})”)

Return type:

list[PlanSummary]

property project: Proj

Lazily parsed project file.

reload(save_if_modified=True)[source]
Parameters:

save_if_modified (bool)

reset()[source]
property results: SteadyPlan | UnsteadyPlan

Lazily opened HDF results file for the current plan.

Dispatches to the appropriate class based on plan type:

  • Steady flow (plan.is_steady) → SteadyPlan

  • Unsteady flow (plan.is_unsteady) → UnsteadyPlan

The handle is kept open until reload() is called or close() is invoked. For geometry-only access (no results), use hdf.Geometry(model.geometry_hdf_path) directly.

Raises:

  • FileNotFoundError – If the plan HDF does not exist — run the model first, or use hdf.Geometry(model.geometry_hdf_path) for geometry-only access.

  • ValueError – If the plan type cannot be determined from the flow file extension.

run(blocking=True, hide_window=False, reload=False)[source]

Run HEC-RAS computations for the current plan.

Parameters:

  • blocking (bool, optional) – If True (default), block until computations complete. If False, return immediately while HEC-RAS computes in the background. Not supported in HEC-RAS 4.x (always blocking).

  • hide_window (bool, optional) – If True, hide the computation window before running and restore it afterward. Default is False.

  • reload (bool, optional) – If True, call reload() before running to refresh the project from disk. Default is False.

Return type:

tuple[bool, tuple[str, ...]]

Returns:

  • success (bool) – True if the computation completed successfully.

  • messages (tuple[str, …]) – Messages returned by HEC-RAS. Empty for versions below 5.0.3.

Raises:

HecRasComputeError – If HEC-RAS reports a computation failure or a COM error occurs.

property run_history: list[dict]

Last up to 5 run summaries, oldest first.

Each entry is a dict with keys:

  • "plan": plan HDF filename (e.g. "MyModel.p01.hdf")

  • "timestamp": ISO-8601 wall-clock time the run completed (e.g. "2026-04-02T09:27:24")

  • "summary": compute_summary() output as a dict, or None if the summary could not be read (e.g. run failed before writing HDF output, or steady-flow plan).

The container holds at most 5 entries; the oldest is evicted when a sixth run completes.

set_plan(*, index=None, title=None, short_id=None)[source]

Set the active plan, then reload.

Exactly one keyword argument must be supplied.

Parameters:

  • index (int | None) – Zero-based position in the project’s plan list. No-op if already the current plan.

  • title (str | None) – Plan Title= string from the plan file.

  • short_id (str | None) – Short Identifier= string from the plan file.

Raises:

  • ValueError – If not exactly one argument is given, the requested plan is not found, or the COM plan list does not match the project file.

  • RuntimeError – If HEC-RAS fails to switch the active plan.

Return type:

None

show()[source]
property version: int
class rivia.model.PlanSummary(index, title, short_id, path, active, flow_type, sediment_path, water_quality_path)[source]

Bases: object

Lightweight summary of one plan in a project.

Returned by Project.plans.

Variables:

  • index – Zero-based position in the project’s plan list.

  • title – Plan Title= string from the plan file, or None.

  • short_id – Short Identifier= string from the plan file, or None.

  • path – Full path to the plan file.

  • active – True for the plan currently loaded by HEC-RAS.

  • flow_type – 'steady', 'unsteady', or 'quasi_steady' based on the Flow File= extension; None if the key is absent or unrecognised.

  • sediment_path – Full path to the sediment file, or None if the plan has no Sediment File= entry.

  • water_quality_path – Full path to the water quality file, or None if the plan has no Water Quality File= entry.

Parameters:

  • index (int)

  • title (str | None)

  • short_id (str | None)

  • path (Path)

  • active (bool)

  • flow_type (Literal['steady', 'unsteady', 'quasi_steady'] | None)

  • sediment_path (Path | None)

  • water_quality_path (Path | None)

active: bool
flow_type: Literal['steady', 'unsteady', 'quasi_steady'] | None
index: int
path: Path
sediment_path: Path | None
short_id: str | None
title: str | None
water_quality_path: Path | None
class rivia.model.MapperExtension[source]

Bases: object

Mixin that adds RasMapper stored-map export to rivia.model.Model.

Renders hydraulic result maps via RasMapperStoreMap.exe, returning results as VrtMap handles or open rasterio datasets.

Export workflow — two families:

Both families delegate to store_map(). A temporary copy of the project .rasmap file is created with the target map layer injected and OverwriteOutputFilename set; the chosen executable is then invoked with that file. Output lands in {project_dir}/{plan_short_id}/ by default, or in output_path when supplied.

Variables supported: wse, depth, velocity, froude, shear_stress, dv (depth x velocity), dv2 (depth x velocity²).

export_depth(timestep, output_vrt=None, render_mode='horizontal', use_depth_weights=False, shallow_to_flat=False, tight_extent=True, stream_output=True, timeout=None)[source]

Export a water depth raster.

Parameters:

  • timestep (int | None) – Zero-based timestep index. None exports the maximum profile.

  • output_vrt (str | Path | None) – Destination for the exported VRT. Three forms accepted: None — written to {project_dir}/{plan_short_id}/ via the StoreAllMaps strategy; an existing directory — written into that folder with an auto-generated name; a path ending with .vrt — written to that exact file.

  • render_mode (Literal['sloping', 'hybrid', 'horizontal']) – Water-surface interpolation mode passed to store_map(). "horizontal" (default) renders a flat per-cell water surface. "sloping" uses cell-corner facepoints only. "hybrid" adds face centroids with optional depth-weighted interpolation. The mode that matches RasMapper’s output depends on the project’s .rasmap setting.

  • use_depth_weights (bool) – When True, face weights are depth-proportional. Only meaningful with render_mode="hybrid".

  • shallow_to_flat (bool) – When True, shallow cells are rendered flat. Defaults to False. Only meaningful with render_mode="hybrid".

  • tight_extent (bool) – Passed through to store_map().

  • stream_output (bool) – Stream subprocess output to the logger in real time.

  • timeout (int | None) – Subprocess timeout in seconds. None means no limit.

Raises:

ValueError – If output_vrt is not None, not an existing directory, and does not end with .vrt.

Return type:

VrtMap

export_dv(timestep, output_vrt=None, render_mode='horizontal', use_depth_weights=False, shallow_to_flat=False, tight_extent=True, stream_output=True, timeout=None)[source]

Export a depth × velocity (D×V) raster.

Parameters:

  • timestep (int | None) – Zero-based timestep index. None exports the maximum profile.

  • output_vrt (str | Path | None) – Destination for the exported VRT. Three forms accepted: None — written to {project_dir}/{plan_short_id}/ via the StoreAllMaps strategy; an existing directory — written into that folder with an auto-generated name; a path ending with .vrt — written to that exact file.

  • render_mode (Literal['sloping', 'hybrid', 'horizontal']) – Water-surface interpolation mode passed to store_map(). "horizontal" (default) renders a flat per-cell water surface. "sloping" uses cell-corner facepoints only. "hybrid" adds face centroids with optional depth-weighted interpolation. The mode that matches RasMapper’s output depends on the project’s .rasmap setting.

  • use_depth_weights (bool) – When True, face weights are depth-proportional. Only meaningful with render_mode="hybrid".

  • shallow_to_flat (bool) – When True, shallow cells are rendered flat. Defaults to False. Only meaningful with render_mode="hybrid".

  • tight_extent (bool) – Passed through to store_map().

  • stream_output (bool) – Stream subprocess output to the logger in real time.

  • timeout (int | None) – Subprocess timeout in seconds. None means no limit.

Raises:

ValueError – If output_vrt is not None, not an existing directory, and does not end with .vrt.

Return type:

VrtMap

export_dv2(timestep, output_vrt=None, render_mode='horizontal', use_depth_weights=False, shallow_to_flat=False, tight_extent=True, stream_output=True, timeout=None)[source]

Export a depth × velocity² (D×V²) raster.

Parameters:

  • timestep (int | None) – Zero-based timestep index. None exports the maximum profile.

  • output_vrt (str | Path | None) – Destination for the exported VRT. Three forms accepted: None — written to {project_dir}/{plan_short_id}/ via the StoreAllMaps strategy; an existing directory — written into that folder with an auto-generated name; a path ending with .vrt — written to that exact file.

  • render_mode (Literal['sloping', 'hybrid', 'horizontal']) – Water-surface interpolation mode passed to store_map(). "horizontal" (default) renders a flat per-cell water surface. "sloping" uses cell-corner facepoints only. "hybrid" adds face centroids with optional depth-weighted interpolation. The mode that matches RasMapper’s output depends on the project’s .rasmap setting.

  • use_depth_weights (bool) – When True, face weights are depth-proportional. Only meaningful with render_mode="hybrid".

  • shallow_to_flat (bool) – When True, shallow cells are rendered flat. Defaults to False. Only meaningful with render_mode="hybrid".

  • tight_extent (bool) – Passed through to store_map().

  • stream_output (bool) – Stream subprocess output to the logger in real time.

  • timeout (int | None) – Subprocess timeout in seconds. None means no limit.

Raises:

ValueError – If output_vrt is not None, not an existing directory, and does not end with .vrt.

Return type:

VrtMap

export_froude(timestep, output_vrt=None, render_mode='horizontal', use_depth_weights=False, shallow_to_flat=False, tight_extent=True, stream_output=True, timeout=None)[source]

Export a Froude number raster.

Parameters:

  • timestep (int | None) – Zero-based timestep index. None exports the maximum profile.

  • output_vrt (str | Path | None) – Destination for the exported VRT. Three forms accepted: None — written to {project_dir}/{plan_short_id}/ via the StoreAllMaps strategy; an existing directory — written into that folder with an auto-generated name; a path ending with .vrt — written to that exact file.

  • render_mode (Literal['sloping', 'hybrid', 'horizontal']) – Water-surface interpolation mode passed to store_map(). "horizontal" (default) renders a flat per-cell water surface. "sloping" uses cell-corner facepoints only. "hybrid" adds face centroids with optional depth-weighted interpolation. The mode that matches RasMapper’s output depends on the project’s .rasmap setting.

  • use_depth_weights (bool) – When True, face weights are depth-proportional. Only meaningful with render_mode="hybrid".

  • shallow_to_flat (bool) – When True, shallow cells are rendered flat. Defaults to False. Only meaningful with render_mode="hybrid".

  • tight_extent (bool) – Passed through to store_map().

  • stream_output (bool) – Stream subprocess output to the logger in real time.

  • timeout (int | None) – Subprocess timeout in seconds. None means no limit.

Raises:

ValueError – If output_vrt is not None, not an existing directory, and does not end with .vrt.

Return type:

VrtMap

export_plan_terrain(raster_path, copy=False)[source]

Export the terrain used by the current plan to a GeoTIFF or GDAL VRT.

Identifies the terrain HDF from get_plan_terrain(), mosaics all source GeoTIFFs by priority order, applies any Levee- or Channel-type ground-line modifications stored in the same HDF, and writes the result to raster_path.

When raster_path has a .vrt extension the output is a GDAL VRT referencing the original source TIFFs. If modifications are present a sidecar <stem>_mods.tif is written beside the VRT.

Parameters:

  • raster_path (str | Path) – Destination path (e.g. "terrain.tif" or "terrain.vrt"). Parent directories are created automatically.

  • copy (bool) – Only relevant for .vrt output. When True, source TIFFs are copied into the VRT’s parent directory and the VRT uses relative paths. When False (default) the VRT uses absolute paths and no files are copied.

Returns:

Resolved absolute path of the written file.

Return type:

Path

Raises:

  • FileNotFoundError – If the geometry HDF, terrain HDF, or any source TIFF is missing.

  • KeyError – If the geometry HDF has no Terrain Layername attribute, the terrain name is not in the .rasmap file, or the terrain HDF has no source TIFF entries.

export_shear_stress(timestep, output_vrt=None, render_mode='horizontal', use_depth_weights=False, shallow_to_flat=False, tight_extent=True, stream_output=True, timeout=None)[source]

Export a bed shear stress raster.

Parameters:

  • timestep (int | None) – Zero-based timestep index. None exports the maximum profile.

  • output_vrt (str | Path | None) – Destination for the exported VRT. Three forms accepted: None — written to {project_dir}/{plan_short_id}/ via the StoreAllMaps strategy; an existing directory — written into that folder with an auto-generated name; a path ending with .vrt — written to that exact file.

  • render_mode (Literal['sloping', 'hybrid', 'horizontal']) – Water-surface interpolation mode passed to store_map(). "horizontal" (default) renders a flat per-cell water surface. "sloping" uses cell-corner facepoints only. "hybrid" adds face centroids with optional depth-weighted interpolation. The mode that matches RasMapper’s output depends on the project’s .rasmap setting.

  • use_depth_weights (bool) – When True, face weights are depth-proportional. Only meaningful with render_mode="hybrid".

  • shallow_to_flat (bool) – When True, shallow cells are rendered flat. Defaults to False. Only meaningful with render_mode="hybrid".

  • tight_extent (bool) – Passed through to store_map().

  • stream_output (bool) – Stream subprocess output to the logger in real time.

  • timeout (int | None) – Subprocess timeout in seconds. None means no limit.

Raises:

ValueError – If output_vrt is not None, not an existing directory, and does not end with .vrt.

Return type:

VrtMap

export_velocity(timestep, output_vrt=None, render_mode='horizontal', use_depth_weights=False, shallow_to_flat=False, tight_extent=True, stream_output=True, timeout=None)[source]

Export a depth-averaged velocity magnitude raster.

Parameters:

  • timestep (int | None) – Zero-based timestep index. None exports the maximum profile.

  • output_vrt (str | Path | None) – Destination for the exported VRT. Three forms accepted: None — written to {project_dir}/{plan_short_id}/ via the StoreAllMaps strategy; an existing directory — written into that folder with an auto-generated name; a path ending with .vrt — written to that exact file.

  • render_mode (Literal['sloping', 'hybrid', 'horizontal']) – Water-surface interpolation mode passed to store_map(). "horizontal" (default) renders a flat per-cell water surface. "sloping" uses cell-corner facepoints only. "hybrid" adds face centroids with optional depth-weighted interpolation. The mode that matches RasMapper’s output depends on the project’s .rasmap setting.

  • use_depth_weights (bool) – When True, face weights are depth-proportional. Only meaningful with render_mode="hybrid".

  • shallow_to_flat (bool) – When True, shallow cells are rendered flat. Defaults to False. Only meaningful with render_mode="hybrid".

  • tight_extent (bool) – Passed through to store_map().

  • stream_output (bool) – Stream subprocess output to the logger in real time.

  • timeout (int | None) – Subprocess timeout in seconds. None means no limit.

Raises:

ValueError – If output_vrt is not None, not an existing directory, and does not end with .vrt.

Return type:

VrtMap

export_wse(timestep, output_vrt=None, render_mode='horizontal', use_depth_weights=False, shallow_to_flat=False, tight_extent=True, stream_output=True, timeout=None)[source]

Export a water-surface elevation (WSE) raster.

Parameters:

  • timestep (int | None) – Zero-based timestep index. None exports the maximum profile.

  • output_vrt (str | Path | None) – Destination for the exported VRT. Three forms accepted: None — written to {project_dir}/{plan_short_id}/ via the StoreAllMaps strategy; an existing directory — written into that folder with an auto-generated name; a path ending with .vrt — written to that exact file.

  • render_mode (Literal['sloping', 'hybrid', 'horizontal']) – Water-surface interpolation mode passed to store_map(). "horizontal" (default) renders a flat per-cell water surface. "sloping" uses cell-corner facepoints only. "hybrid" adds face centroids with optional depth-weighted interpolation. The mode that matches RasMapper’s output depends on the project’s .rasmap setting.

  • use_depth_weights (bool) – When True, face weights are depth-proportional. Only meaningful with render_mode="hybrid".

  • shallow_to_flat (bool) – When True, shallow cells are rendered flat. Defaults to False. Only meaningful with render_mode="hybrid".

  • tight_extent (bool) – Passed through to store_map().

  • stream_output (bool) – Stream subprocess output to the logger in real time.

  • timeout (int | None) – Subprocess timeout in seconds. None means no limit.

Raises:

ValueError – If output_vrt is not None, not an existing directory, and does not end with .vrt.

Return type:

VrtMap

get_plan_terrain()[source]

Return the TerrainLayer associated with the current plan.

The terrain name is read from the Geometry group attribute Terrain Layername in the geometry HDF file, then matched against the <Terrains> section of the .rasmap file.

Raises:

  • FileNotFoundError – if the geometry HDF file does not exist.

  • KeyError – if the HDF has no Terrain Layername attribute, or the name does not match any layer in <Terrains>.

Return type:

TerrainLayer

open_depth(timestep, render_mode='horizontal', use_depth_weights=False, shallow_to_flat=False, tight_extent=True, stream_output=True, timeout=None)[source]

Context manager: export depth and yield an open rasterio dataset.

See open_map() for parameter and cleanup details.

Return type:

AbstractContextManager[rasterio.io.DatasetReader]

Parameters:

  • timestep (int | None)

  • render_mode (Literal['sloping', 'hybrid', 'horizontal'])

  • use_depth_weights (bool)

  • shallow_to_flat (bool)

  • tight_extent (bool)

  • stream_output (bool)

  • timeout (int | None)

open_dv(timestep, render_mode='horizontal', use_depth_weights=False, shallow_to_flat=False, tight_extent=True, stream_output=True, timeout=None)[source]

Context manager: export D×V and yield an open rasterio dataset.

See open_map() for parameter and cleanup details.

Return type:

AbstractContextManager[rasterio.io.DatasetReader]

Parameters:

  • timestep (int | None)

  • render_mode (Literal['sloping', 'hybrid', 'horizontal'])

  • use_depth_weights (bool)

  • shallow_to_flat (bool)

  • tight_extent (bool)

  • stream_output (bool)

  • timeout (int | None)

open_dv2(timestep, render_mode='horizontal', use_depth_weights=False, shallow_to_flat=False, tight_extent=True, stream_output=True, timeout=None)[source]

Context manager: export D×V² and yield an open rasterio dataset.

See open_map() for parameter and cleanup details.

Return type:

AbstractContextManager[rasterio.io.DatasetReader]

Parameters:

  • timestep (int | None)

  • render_mode (Literal['sloping', 'hybrid', 'horizontal'])

  • use_depth_weights (bool)

  • shallow_to_flat (bool)

  • tight_extent (bool)

  • stream_output (bool)

  • timeout (int | None)

open_froude(timestep, render_mode='horizontal', use_depth_weights=False, shallow_to_flat=False, tight_extent=True, stream_output=True, timeout=None)[source]

Context manager: export Froude number and yield an open rasterio dataset.

See open_map() for parameter and cleanup details.

Return type:

AbstractContextManager[rasterio.io.DatasetReader]

Parameters:

  • timestep (int | None)

  • render_mode (Literal['sloping', 'hybrid', 'horizontal'])

  • use_depth_weights (bool)

  • shallow_to_flat (bool)

  • tight_extent (bool)

  • stream_output (bool)

  • timeout (int | None)

open_map(variable, timestep, render_mode='horizontal', use_depth_weights=False, shallow_to_flat=False, tight_extent=True, stream_output=True, timeout=None)[source]

Store a map in a temporary directory and yield an open rasterio.DatasetReader.

Output is written to a freshly-created system temp directory that is removed with shutil.rmtree() on context exit and registered with atexit() for cleanup on interpreter shutdown.

Parameters:

  • variable (Literal['wse', 'water_surface', 'depth', 'velocity', 'froude', 'shear_stress', 'dv', 'depth_x_velocity', 'dv2', 'depth_x_velocity_sq']) – Hydraulic variable — same accepted values as store_map().

  • timestep (int | None) – Zero-based timestep index. None uses the maximum-value profile.

  • render_mode (Literal['sloping', 'hybrid', 'horizontal']) – Passed through to store_map(). Defaults to "horizontal".

  • use_depth_weights (bool) – Passed through to store_map().

  • shallow_to_flat (bool) – Passed through to store_map().

  • tight_extent (bool) – Passed through to store_map().

  • stream_output (bool) – Passed through to store_map().

  • timeout (int | None) – Subprocess timeout in seconds. None means no limit.

Yields:

  • rasterio.io.DatasetReader – Open dataset positioned at the exported VRT.

  • Usage:: –

    with model.open_map(“wse”, 10) as ds:

    data = ds.read(1)

Return type:

Generator[rasterio.io.DatasetReader, None, None]

open_shear_stress(timestep, render_mode='horizontal', use_depth_weights=False, shallow_to_flat=False, tight_extent=True, stream_output=True, timeout=None)[source]

Context manager: export shear stress and yield an open rasterio dataset.

See open_map() for parameter and cleanup details.

Return type:

AbstractContextManager[rasterio.io.DatasetReader]

Parameters:

  • timestep (int | None)

  • render_mode (Literal['sloping', 'hybrid', 'horizontal'])

  • use_depth_weights (bool)

  • shallow_to_flat (bool)

  • tight_extent (bool)

  • stream_output (bool)

  • timeout (int | None)

open_velocity(timestep, render_mode='horizontal', use_depth_weights=False, shallow_to_flat=False, tight_extent=True, stream_output=True, timeout=None)[source]

Context manager: export velocity and yield an open rasterio dataset.

See open_map() for parameter and cleanup details.

Return type:

AbstractContextManager[rasterio.io.DatasetReader]

Parameters:

  • timestep (int | None)

  • render_mode (Literal['sloping', 'hybrid', 'horizontal'])

  • use_depth_weights (bool)

  • shallow_to_flat (bool)

  • tight_extent (bool)

  • stream_output (bool)

  • timeout (int | None)

open_wse(timestep, render_mode='horizontal', use_depth_weights=False, shallow_to_flat=False, tight_extent=True, stream_output=True, timeout=None)[source]

Context manager: export WSE and yield an open rasterio dataset.

See open_map() for parameter and cleanup details.

Return type:

AbstractContextManager[rasterio.io.DatasetReader]

Parameters:

  • timestep (int | None)

  • render_mode (Literal['sloping', 'hybrid', 'horizontal'])

  • use_depth_weights (bool)

  • shallow_to_flat (bool)

  • tight_extent (bool)

  • stream_output (bool)

  • timeout (int | None)

store_map(variable, timestep=None, raster_name=None, output_path=None, render_mode='horizontal', use_depth_weights=False, shallow_to_flat=False, tight_extent=True, stream_output=True, timeout=None)[source]

Store one hydraulic result map via RasMapperStoreMap.exe.

Returns a VrtMap handle to the written VRT and source tiles.

Parameters:

  • variable (Literal['wse', 'water_surface', 'depth', 'velocity', 'froude', 'shear_stress', 'dv', 'depth_x_velocity', 'dv2', 'depth_x_velocity_sq']) – Hydraulic variable to export. Accepted values and their aliases: "wse" / "water_surface", "depth", "velocity", "froude", "shear_stress", "dv" / "depth_x_velocity", "dv2" / "depth_x_velocity_sq".

  • timestep (int | None) – Zero-based index into the plan’s output time series. None exports the maximum-value profile across all timesteps.

  • raster_name (str | None) – Stem of the output VRT file (no path separators, no extension). Defaults to "{display_name} ({profile_name})".

  • output_path (Path | str | None) – Directory to write the VRT into. Must already exist. When None, uses the StoreAllMaps strategy and output goes to {project_dir}/{plan_short_id}/; when provided, uses the StoreMap XML strategy and output goes directly into that directory.

  • render_mode (Literal['sloping', 'hybrid', 'horizontal']) – Water-surface interpolation mode passed to RasMapperStoreMap.exe. Accepted values: "sloping", "hybrid", or "horizontal" (default). The mode that matches RasMapper’s interactive export depends on the <RenderMode> configured in the project’s .rasmap file.

  • use_depth_weights (bool) – When True, face weights in the hybrid stencil are proportional to the face’s water depth (UseDepthWeightedFaces). Only meaningful with render_mode="hybrid".

  • shallow_to_flat (bool) – When True (default), shallow cells are rendered flat (ReduceShallowToHorizontal). Only meaningful with render_mode="hybrid".

  • tight_extent (bool) – When True (default), the output raster extent is clipped to the model geometry (2D flow area + cross sections + storage areas), pixel-aligned to the terrain grid — matching RasMapper’s “Original Extent” behaviour. When False, output tiles cover the full terrain tile extent; cells outside the model are NoData.

  • stream_output (bool) – When True (default) subprocess stdout/stderr are logged line-by-line in real time. When False output is captured silently and only shown on error.

  • timeout (int | None) – Subprocess timeout in seconds. None (default) means no limit.

Returns:

Handle to the written VRT and its source raster tiles.

Return type:

VrtMap

Raises:

  • ValueError – If variable is not recognised, raster_name is invalid, or output_path exists but is not a directory.

  • FileNotFoundError – If HEC-RAS is not installed, RasMapperStoreMap.exe is missing, the plan HDF is missing, output_path does not exist, or the expected VRT was not produced.

  • PermissionError – If the output VRT is locked by another process (e.g. QGIS).

  • RuntimeError – If RasMapperStoreMap.exe exits with a non-zero return code or writes "error" to stderr.

timestep_to_profile_name(timestep)[source]

Return the HEC-RAS profile name for a given timestep index.

Parameters:

timestep (int | None) – Zero-based index into the plan’s time series. None returns "Max", which selects the maximum-value profile.

Return type:

str

Submodules

project

Read HEC-RAS project files (.prj).

plan

Read/write HEC-RAS plan files (.p**).

geometry

Read/write HEC-RAS geometry files (.g**).

steady_flow

Read/write HEC-RAS steady flow files (.f**).

unsteady_flow

Read/write HEC-RAS unsteady flow files (.u**).