Skip to content

API Reference

This section provides documentation for the RAS Commander Python API.

Use the capability map to choose an operation by its inputs and outputs. The example catalog adds selected runtime requirements and evidence scope; the execution contract explains single-plan and batch return semantics.

Core Classes

Primary classes for project management and execution:

  • RasPrj - Project management and data structures
  • RasCmdr - Plan execution (single, parallel, sequential)
  • RasPlan - Plan file operations
  • RasFlowOptimization - Native HEC-RAS flow hydrograph optimization settings and trial results
  • RasGeo - Geometry file operations
  • RasUnsteady - Unsteady flow file management
  • RasSteady - Steady flow file authoring and parsing
  • RasUtils - Utility functions
  • RasExamples - Example project management
  • RasMap - RASMapper configuration, layer discovery, and geometry HDF associations
  • RasProcess - RasProcess.exe CLI automation, stored maps, and native reference validators
  • RasControl - Legacy COM interface

Meshing and Spatial Operations

  • Meshing — generation, layout/cell diagnostics, containment, BC conflicts, repairs, and property tables
  • RASMapper — screenshots, map/geometry layers, display, associations, and geometry completion
  • Results Queries — offline sampling, native profiles, and recorded reference hydrographs
  • Stored Maps — export existing results to raster products
  • Mapping computed results — depth, WSE, velocity, derived and temporal products, storage-area level pools and inundation boundaries

Benefits Analysis

Rasterized depth-comparison benefits and mesh-based WSE comparison:

  • RasBenefits - Categorical BenefitArea GeoTIFF generation from aligned pre/post Depth rasters
  • BenefitAreaConfig - Pair-aware configuration for RasProcess.store_maps()
  • BenefitAreaResult - Raster paths, thresholds, and class-area statistics
  • HdfBenefitAreas - Separate 2D mesh/WSE benefit and rise analysis

Hydrofabric Conflation

1D Breakout Extraction

  • RasBreakout1D - Single- and multi-source steady 1D breakout selection, assembly, restationing, validation, execution, and comparison
  • Breakout1DSelection - Resolved contiguous cross-section selection
  • Breakout1DSourceCatalog - GeoParquet-ready source model, footprint, centerline, and cross-section catalog
  • Breakout1DPlan - Confirmed source reaches, directed ownership slices, provisional seams, and fail-closed handoff diagnostics
  • Breakout1DResult - Independent project artifacts, validation, and boundary provenance

2D Breakout Geometry Preparation

  • RasBreakout2D - Pure-2D qualification, component cloning, geometry trimming/remeshing, and parent-flux review without boundary authoring or plan execution
  • Breakout2DSpec - Source plan, 2D area, and contained child-boundary contract
  • Breakout2DPreflight - Spatial checks, feature dispositions, and existing-boundary inventory
  • Breakout2DPreparationResult - Clone associations, mesh audit, and byte-identical unsteady-file evidence
  • Breakout2DFluxReview - Oriented parent-face series and unassigned candidate flux zones

HDF Modules

Classes for reading HDF result files:

Geometry Modules

Classes for parsing and authoring geometry files:

Terrain Modules

Classes for terrain creation, modification writing, and terrain-modification analysis:

  • RasTerrain - Terrain HDF creation and native registered-terrain GeoTIFF export
  • RasTerrainModWriter / RasTerrainModification - Line and polygon terrain modification HDF/.rasmap writing
  • RasTerrainMod - Terrain profile and volume comparison with modifications applied

Fixit Module

Automated geometry repair:

  • RasFixit - Obstructions, HTAB starting elevations, bank stations, ineffective areas, and Manning’s n
  • FixResults - Fix operation results
  • log_parser - HEC-RAS log parsing for error detection

DSS Modules

Classes for reading and writing DSS files:

  • RasDss - DSS file operations
  • RasDssGrid - Gridded import and grid tools for DSS files

Containers and Slurm

Compare execution backends and select a compatible image from the container catalog.

Remote Modules

Classes for distributed execution:

Usage Pattern

Most operation classes, such as RasCmdr and HdfMesh, are static namespaces. Call them directly. RasPrj, workers, result records, and configuration objects are instances; follow their constructors rather than applying this pattern to every exported type:

Python
# No instantiation needed
from ras_commander import RasCmdr, RasPlan

# Direct static method calls
RasCmdr.compute_plan("01")
RasPlan.set_num_cores("01", 4)

Decorators

RAS Commander uses two key decorators that affect method behavior:

@standardize_input

Automatically converts various input types to the correct HDF file path. Input support is method-specific; use the documented signature and decorator for the selected method. Some low-level readers require an explicit path.

Accepted Input Types:

Input Type Example Behavior
Plan number (str) "01", "p01" Looks up HDF path in ras.plan_df
Plan number (int) 1, 2 Converted to string, then lookup
Path object Path("x.hdf") Used directly if file exists
String path "/path/to.hdf" Converted to Path, used directly
h5py.File hdf_file Extracts filename from object

file_type Parameter:

Text Only
@standardize_input(file_type='plan_hdf')  # Default - looks for .p##.hdf
@standardize_input(file_type='geom_hdf')  # Looks for .g##.hdf
@standardize_input(file_type='plan')      # Looks for .p## (plain text)

Usage Examples:

Python
from pathlib import Path
from ras_commander import HdfResultsMesh, init_ras_project

init_ras_project("/path/to/project", "6.5")

# All of these are equivalent:
HdfResultsMesh.get_mesh_max_ws("01")           # Plan number string
HdfResultsMesh.get_mesh_max_ws(1)              # Integer
HdfResultsMesh.get_mesh_max_ws("p01")          # With 'p' prefix
HdfResultsMesh.get_mesh_max_ws(Path("x.hdf"))  # Path object
HdfResultsMesh.get_mesh_max_ws("/path/to.hdf") # String path

Project Initialization Required

When using plan/geometry numbers (not direct paths), you must first call init_ras_project() to populate the ras.plan_df lookup table.

@log_call

Automatic logging decorator applied to most methods. Logs function entry/exit at DEBUG level.

Python
@log_call
def my_function():
    ...

# Logs: "Calling my_function"
# Logs: "Finished my_function"

Enable debug logging to see these messages:

Python
import logging
logging.getLogger('ras_commander').setLevel(logging.DEBUG)