>>> import ripple1d
>>> print(ripple1d.__version__)Ripple1D
Executive summary
As one of the foundational hydraulic modeling systems, HEC-RAS needs no introduction. This modeling system is so prolific that it’s one and two dimensional flood modeling capabilities provide the authoritative baseline for flood insurance and the default against which other modeling efforts compare. One of the most critical outputs of a HEC-RAS model is a Flood Inundation Map. However, as a complex piece of engineering and water resource science software, it’s use is difficult for many and can be difficult to scale. Starting with compliant one-dimensional HEC-RAS floodplain models, the Ripple1D process can be used to create a library of flood depth inundation rasters for a range of storm water discharges and hydraulic conditions. These libraries can be used with the National Water Model. More details can be found on the official repository at https://github.com/Dewberry/ripple1d and the official docs
Installation from 0
Ripple1D is a Python utility designed to repurpose HEC-RAS 1D models to produce Flood Inundation Maps (FIMs) and synthetic rating curves (SRCs). Much like [RAS2FIM], Ripple1D relies on the HEC-RAS engine, which means it mandates a Windows environment. Here I’ll outline the steps to get Ripple1D installed cleanly, assuming you are starting from a fresh Windows virtual machine or a dedicated modeling PC.
1) Prerequisites
Before diving into Python packages, ensure your base environment is solid:
- HEC-RAS: You need HEC-RAS installed. Currently, version 6.3.1 is the officially supported release for Ripple1D.
- Python: Ripple1D requires Python
>= 3.10. - OS: A Windows environment with a GUI (VirtualBox setups like the one used for RAS2FIM work perfectly here).
2) Setting up the Environment
While you could technically install this straight to your base Python installation, keeping it in an isolated virtual environment (either venv or conda/mamba) is highly recommended to prevent dependency hell.
- Open your Anaconda/Miniforge Prompt.
- Create a fresh environment for Ripple1D:
mamba create -n ripple1d_env python=3.10 - Activate the environment:
mamba activate ripple1d_env - Install the ripple1d package via pip:
pip install ripple1d
- Open PowerShell or Command Prompt.
- Create a virtual environment:
python -m venv ripple1d_env - Activate the environment:
.\ripple1d_env\Scripts\activate - Install the package:
pip install ripple1d
3) Verifying the Installation
Before we start throwing models at it, let’s make sure the engine actually turns over. Open up a Python shell in your active environment and test the import.
If you see a version number print out without any traceback errors, you’re locked and loaded.
Note
Headless Environment Warning If you attempt to run this on a headless server or an environment without the HEC-RAS GUI available, you will inevitably run into COM errors or Huey consumer crashes. The HECRASController needs that desktop experience to execute properly.
Running Ripple1D over a Model Ripple1D isn’t just a simple command-line script; it uses a Flask API and a Huey queueing system under the hood for managing parallel compute tasks. However, for a standard programmatic run over an existing model, you can interact with it via its Python API.
Starting a Job Depending on what you want to extract (e.g., FIMs, SRCs), your workflow will usually look like this:
Ensure your HEC-RAS 1D model (.prj, .p01, .g01, etc.) is clean, calibrated, and runnable in the native HEC-RAS GUI.
Formulate your Python script to point Ripple1D at your model directory.
import ripple1dAdd your execution script here based on the specific ripple1d modules you are calling.
Example: Setting up the model repurposing parameters and executing the run.
Note: As Ripple1D is actively developed, refer to the official Ripple1D docs for the most up-to-date execution functions and API calls for your specific use case, such as submitting Huey tasks or running batch extractions.
Congratulations! You now have a working Ripple1D installation ready to churn out mapping libraries and rating curves.