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 structuresRasCmdr- Plan execution (single, parallel, sequential)RasPlan- Plan file operationsRasFlowOptimization- Native HEC-RAS flow hydrograph optimization settings and trial resultsRasGeo- Geometry file operationsRasUnsteady- Unsteady flow file managementRasSteady- Steady flow file authoring and parsingRasUtils- Utility functionsRasExamples- Example project managementRasMap- RASMapper configuration, layer discovery, and geometry HDF associationsRasProcess- RasProcess.exe CLI automation, stored maps, and native reference validatorsRasControl- 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 rastersBenefitAreaConfig- Pair-aware configuration forRasProcess.store_maps()BenefitAreaResult- Raster paths, thresholds, and class-area statisticsHdfBenefitAreas- Separate 2D mesh/WSE benefit and rise analysis
Hydrofabric Conflation¶
RasNetworkConflation- Extent-first network-edge classification with optional multi-criteria QANetworkEdgeCoverageResult- One model–edge row with inside length and fractionNetworkConflationResult- Resolved matches, ranked candidates, reach metrics, and HUC intersectionsNetworkAdapter- Generic directed-network schema normalization used by NHDPlus, NWM, NextGen, and custom adapters
1D Breakout Extraction¶
RasBreakout1D- Single- and multi-source steady 1D breakout selection, assembly, restationing, validation, execution, and comparisonBreakout1DSelection- Resolved contiguous cross-section selectionBreakout1DSourceCatalog- GeoParquet-ready source model, footprint, centerline, and cross-section catalogBreakout1DPlan- Confirmed source reaches, directed ownership slices, provisional seams, and fail-closed handoff diagnosticsBreakout1DResult- 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 executionBreakout2DSpec- Source plan, 2D area, and contained child-boundary contractBreakout2DPreflight- Spatial checks, feature dispositions, and existing-boundary inventoryBreakout2DPreparationResult- Clone associations, mesh audit, and byte-identical unsteady-file evidenceBreakout2DFluxReview- Oriented parent-face series and unassigned candidate flux zones
HDF Modules¶
Classes for reading HDF result files:
HdfBase- Core HDF operationsHdfPlan- Plan informationHdfMesh- Mesh geometryHdfResultsMesh- 2D mesh resultsHdfResultsProducts- Completed-result inspection and deterministic hydraulic product contractsHdfResultsPlan- Plan-level resultsHdfResultsXsec- 1D cross-section resultsHdfStruc- Structure dataHdfResultsBreach- Dam breach resultsHdfHydraulicTables- Cross section HTAB dataHdfStorageArea- Storage area volume-elevation curvesHdfChannelCapacity- 1D channel capacity analysisHdfStruc1D- 1D inline structure dataHdfPipe- Pipe network analysisHdfPump- Pump station analysis
Geometry Modules¶
Classes for parsing and authoring geometry files:
RasGeometry- Cross sections, storage, connectionsGeomCrossSection- Cross-section builder and blocked obstructionsGeomBridge- Bridge geometry authoringGeomBcLines- 2D boundary condition line authoringGeomLateral- Lateral structure parsingGeomStorage- Storage area and 2D flow area writing- Cross-section levees -
GeomCrossSectionlevee read/write RasGeometryUtils- Parsing utilitiesGeomInlineWeir,GeomBridge, andGeomCulvert- Inline structuresRasBreach- Breach parameters
Terrain Modules¶
Classes for terrain creation, modification writing, and terrain-modification analysis:
RasTerrain- Terrain HDF creation and native registered-terrain GeoTIFF exportRasTerrainModWriter/RasTerrainModification- Line and polygon terrain modification HDF/.rasmap writingRasTerrainMod- 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 nFixResults- Fix operation resultslog_parser- HEC-RAS log parsing for error detection
DSS Modules¶
Classes for reading and writing DSS files:
RasDss- DSS file operationsRasDssGrid- Gridded import and grid tools for DSS files
Containers and Slurm¶
RasDocker- Wine preprocessing and native Linux computationContainerResult/ContainerBatchResult- Stage and batch outcomesRasPortableDocker- Portable request execution through DockerRasSlurm- Portable request pools on Slurm/ApptainerRasApptainer- Prepared native unsteady plans on Slurm
Compare execution backends and select a compatible image from the container catalog.
Remote Modules¶
Classes for distributed execution:
LocalWorker- Local parallel executionPsexecWorker- Windows remote executionDockerWorker- Container executioninit_ras_worker- Factory functioncompute_parallel_remote- 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:
# 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:
@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:
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.
Enable debug logging to see these messages: