Blackbird User’s Manual

This is the User’s Manual for the Blackbird project.

Blackbird is a software for rapid fluvial floodplain mapping. More information on the methodology may be found in a peer-reviewed study (R. Chlumsky, Craig, and Tolson 2024).

This manual is under construction! Please excuse missing text sections or lack of details at this time.

Please send all suggestions on Blackbird and related materials to hello@heronhydrologic.ca

1 Introduction

Blackbird is a hydraulic modelling and mapping tool that has been developed by the Blackbird Development Team. The original work was developed by Robert Chlumsky at the University of Waterloo as as part of PhD studies ending in 2024, and has been under continuous development since.

The Blackbird methodology is based on a combination of three primary components:

a one-dimensional (1D) hydraulic solver, which currently supports a standard-step solver under a steady-state assumption;
reach-integrated estimation of hydraulic properties, which allows hydraulic properties to be estimated from 3D reach areas by default (similar to the approach of Zheng et al. (2018)). Hydraulic properties may also be estimated from the traditional cross-section representation if preferred; and
use of the Height Above Nearest Drainage (HAND) or the Dynamic Height Above Nearest Drainage (DHAND) method for mapping needs, including in the estimation of inundated areas for estimating hydraulic properties and in post-processing of results to produce final depth maps.

While Blackbird may be used to solve a variety of hydraulic modelling and mapping needs, the focus of the program is on flood mapping applications. The software may be applied in flood modelling at any scale, including the engineering scale and the regional or global scale. The methodology of Blackbird allows it to produce results and flood maps at much faster computational speeds than two-dimensional models, allowing Blackbird to be applied at larger spatial scales (e.g., regional applications) and/or in real-time inundation mapping or forecasting exercises.

1.1 Algorithmic Description

Please see (R. Chlumsky, Craig, and Tolson 2024) for more details on the algorithmic description of the model.

1.2 Data Requirements

The general data requirements for Blackbird file generation includes the following:

a raster of elevation data, i.e. a digital elevation model (DEM);
a raster of Manning’s roughness values, often derived from land cover data and a table of values to reclassify land cover to roughness;
a shapefile of channel locations (this may also be derived as a preprocessing step); and
flow values to describe the channel flows at each location in the model.

1.3 Workflow

The workflow of Blackbird is to begin by generating the required text and geospatial input files, which may be accomplished with the Blackbird R package (Robert Chlumsky, Craig, and Tolson 2025). This includes the initial processing of DEM and roughness data, delineation of the channels (if not provided), defining the streamnode locations, computing pre-processed hydraulic variables (if needed), and generating the input files in both text and geospatial formats.

Once these inputs have been processed, the compiled Blackbird executable is recommended for operational use of Blackbird.

The focus in this manual is on the use of the compiled Blackbird executable from a set of supplied input files. For assistance with preparing these files, please contact hello@heronhydrologic.ca.

1.4 Comparison to other software

Blackbird is a fully 1D hydraulic model, and is capable of (nearly) emulating a steady-state HEC-RAS 1D (Hydrologic Engineering Center 2023) run. The enhancements in this methodology allow sections to be represented with a reach-integrated area (essentially a 3D catchment area) rather than a cross-section, and compute hydraulic properties needed in 1D calculations directly from this 3D area, removing the need to define explicit cross-sections.

The nodes that define computational points in the model are called streamnodes, and these can be represented using either reach-integrated representations or a cross-section. Blackbird can be run using only reach representations, only cross-sections (essentially emulating a more traditional hydraulic model), or with a mix of reach and cross-section representations. This allows Blackbird to bring in any functionality of a 1D model, including hydraulic structures and ice cover (in principle).

Once the depth at each streamnode is computed, the depths are mapped using either HAND or DHAND (see Introduction) to generate a depth raster. These depths can be mapped in this way regardless of the streamnode representation type (i.e. reach integrated or cross-section). This is an improvement over the imputation of depths at cross-sections, which often requires manual cleanup to remove errors.

1.5 Citing Blackbird

The preferred citation for Blackbird at this time is to the Geoscientific and Model Development article (R. Chlumsky, Craig, and Tolson 2024), which is openly available. This may be cited directly as:

Chlumsky, R., Craig, J. R., and Tolson, B. A.: A reach-integrated hydraulic modelling approach for large-scale and real-time inundation mapping, Geosci. Model Dev., 18, 3387–3403, https://doi.org/10.5194/gmd-18-3387-2025, 2025.

1.6 Contributing

We welcome contributions to Blackbird, either contacting us via email with suggestions or partnerships Contact Us.

We also welcome contributions on our Github code repositories for both the blackbird R package used in preparing input files, as well as the C++ repository for the compiled executable of Blackbird.

2 Running Blackbird

2.1 Installation

Currently, Blackbird is distributed as a Windows executable. Compilation in other platforms is also possible, please contact us directly if you are interested in this option (hello@heronhydrologic.ca).

The Blackbird executable can be downloaded from the Blackbird website. Blackbird’s dependencies are the GDAL library and NetCDF C++ API, both of which are statically linked in the executable. As such, you will not need any additional installations or setup if using the pre-compiled executable in Windows.

2.1.1 Dependency Downloads

If you do not want to use the pre-compiled binary and instead want to compile Blackbird from source on your own, then you will need your own installations of the dependencies linked either statically or dynamically. Here are some instructions on procuring each dependency in Windows.

2.1.1.1 GDAL

Download OSGeo4W Network Installer from the OSGeo4W website
Install GDAL using OSGeo4W
1. Open the OSGeo4W setup tool
2. Choose Advanced Install and click next until the package selection screen
3. Using the search bar, search for and select these packages to install:
  1. gdal
  2. gdal-devel
  3. gdal310-runtime
  4. proj
  5. proj-devel
  6. geos
  7. geos-devel
4. Proceed with the install then hit finish
Configure the GDAL path variable
1. Press the Windows button and search for ‘Edit the system environment variables’
2. Click on Environment Variables..
3. In the upper box, click on the Path variable and click Edit
4. Click New and paste the bin directory of your OSGeo4W installation into the new row (by default this should be C:\OSGeo4W\bin, but check to be sure)
5. Click Ok/Apply on all of the popups and close the System Settings window

2.1.1.2 NetCDF

Download the netCDF and netcdf-cxx4 libraries from Unidata and their dependencies: HDF5 from hdfgroup, zlib from zlib.net and curl from curl.se
If pre-compiled binaries are unavailable, build them from source
For each library, ensure that the folders that contain the .dll (dynamic linking) or .lib (static linking) and .h files have been added to your PATH variable
Link the library and header files to your Visual Studio or CMake compilation settings

2.1.1.3 libpng

Download libpng from sourceforge and zlib from zlib.net
If pre-compiled binaries are unavailable, build them from source
For each library, ensure that the folders that contain the .dll (dynamic linking) or .lib (static linking) and .h files have been added to your PATH variable
Link the library and header files to your Visual Studio or CMake compilation settings

2.1.2 Adding Blackbird to PATH

Optionally, you may wish to configure Blackbird to be run from anywhere on your system as a recognized executable. To do this, follow these steps:

Download the Blackbird executable from the Blackbird website
Unzip and save this in a directory you would like to keep it. This can be anywhere, but is suggested to be something like C:\Program Files\Blackbird
Press the Windows button and search for ‘Edit the system environment variables’
Click on Environment Variables..
In the upper box, click on the Path variable and click Edit
Click New and paste the bin directory of your Blackbird executable into the new row (this may be C:\Program Files\Blackbird)
Click Ok/Apply on all of the popups and close the System Settings window
Test that Blackbird may now be called from anywhere by running Blackbird.exe from Command Prompt in a folder with no such executable. If you see the Blackbird_errors.txt file created, this was successful!

2.2 Input Files and Commands

In order to perform a simulation using Blackbird, the following three text input files are required (where ‘modelname’ is the placeholder for the model name, often named after the project name or location).

modelname.bbi
This is the primary input file for the Blackbird model where run options and the model types are specified. For example, the solver type, options for the solver (tolerance), whether to use DHAND, algorithmic choices for roughness values, choice of post-processing algorithms, output data that is generated, and other options are specified here.
modelname.bbb
This is the boundary conditions file, where the boundary conditions for the model (such as normal depth at the downstream node) as well as flows throughout the model are specified.
modelname.bbg
This is the geometry file, where all geometric information such as a table of streamnode properties, cross-sections, and any pre-processed hydraulic variables are provided.

These files may make use of the :RedirectToFile command to organize long series of data from other files of the same extension, for example, putting large flow data tables into a separate .bbb file or large libraries of cross-section data and pre-processed hydraulic variable data into separate .bbg files.

In addition to the main text input files, some GIS files are required. The location of these is provided from the .bbi file with the :GISPath command. These files are required for the post-processing of results to generate depth rasters. The naming convention of these files is fixed, and is produced by the

(Required) bb_catchments_fromstreamnodes.tif This raster defines the catchment areas associated with each streamnode (whether a reach or cross-section) as a raster of index ID values corresponding to streamnode IDs.
(Required) bb_hand.tifThis raster defines the HAND values across the modelled domain.
(Optional) bb_hand_pourpoint_id.tif This raster defines the index values corresponding to the nearest drainage points used to calculate the HAND raster. This is required if the post-processing method uses interpolation of depths between streamnodes.
(Optional) bb_dhand_depth_xxxm.tif This raster defines the DHAND values across the modelled domain for a depth of xx. This is required if DHAND is used in post-processing of results to generate flood maps. In this case, multiple rasters will be required corresponding to the depths used in DHAND processing.
(Optional) bb_dhand_pourpoint_id_depth_xxxm.tif This raster defines the index values corresponding to the nearest drainage points used to calculate the DHAND raster of the same depth. This is required if the post-processing method uses interpolation of depths between streamnodes and DHAND is used as a post-processing option.
(Optional) bb_snapped_pourpoints_hand.shp This shapefile defines the nearest drainage points used to define the HAND/DHAND rasters. This shapefile contains additional attributes that are required when depths are interpolated between streamnodes.

Alternatively, you can specify the GIS input as a NetCDF file with multiple variables replacing the raster data. The default name of this file is bb_inputs.nc but a file with a different name can be used as long as the new name is specified with :InputNCFile in the .bbi file. The variables/dimensions of the NetCDF are fixed and should be:

(Required) easting This NetCDF variable defines the x dimension of the data.
(Required) northing This NetCDF variable defines the y dimension of the data.
(Required) catchments_streamnodes This NetCDF variable defines the catchment areas associated with each streamnode (whether a reach or cross-section) as a raster of index ID values corresponding to streamnode IDs.
(Optional) depth This NetCDF variable defines the z dimension of the DHAND data if using DHAND methods.
(Required) handThis variable defines the HAND values across the modelled domain.
(Optional) handid This NetCDF variable defines the index values corresponding to the nearest drainage points used to calculate the HAND raster. This is required if the post-processing method uses interpolation of depths between streamnodes.
(Optional) dhand This NetCDF variable defines the DHAND values across the modelled domain for various depths. This is required if DHAND is used in post-processing of results to generate flood maps. In this case, multiple layers will be required corresponding to the depth variable.
(Optional) dhandid This NetCDF variable defines the index values corresponding to the nearest drainage points used to calculate the DHAND layer of the same depth. This is required if the post-processing method uses interpolation of depths between streamnodes and DHAND is used as a post-processing option.
(Optional) bb_snapped_pourpoints_hand.shp This is a separate shapefile and defines the nearest drainage points used to define the HAND/DHAND rasters. This shapefile contains additional attributes that are required when depths are interpolated between streamnodes.

2.2.1 Primary input file (.bbi)

The primary input file (.bbi) stores the model simulation options. An example .bbi file is shown below.

Note that comments may be included on individual lines using the # character as the first word on the line. Inline comments are also allowed - Blackbird will ignore any text that appears to the right of the # character.

## Blackbird Model Input File (.bbi)
# 

### General Model Setup Options ----
:ModelType STEADYFLOW
:RegimeType SUBCRITICAL
:Tolerance 0.003
:IterationLimit 50
:WSLSplit 0.7
:ToleranceNormalDepth 0.001
:IterationLimitNormalDepth 50
:WSLSplitNormalDepth 0.4
:MaxRHRatio 2
:MinRHRatio 0.5
:ExtrapolateDepthTable TRUE
:NumExtrapolationPoints 20
:DynamicHAND FALSE
:FrictionSlopeMethod US_FRICTION
:EnforceDeltaLeff FALSE
:ReachLengthDelta 0.3
:ManningCompositeMethod EQUAL_VELOCITY
:SilentRun FALSE
:PreprocMaxDepth 9
:PreprocDepthStep 0.05
:DHANDMaxDepth 9
:DHANDDepthStep 0.05
:FroudeThreshold 0.94

### Calibration parameter ----
:RoughnessMultiplier 1.1

### XSection Specific Options ----
:XSectionDX 0.1
:XSectionConveyanceMethod DEFAULT_CONVEYANCE
:ManningEnforceValues TRUE

### Reach Specific Options ----
:ReachConveyanceMethod DISCRETIZED_CONVEYANCE
:ReachIntegrationMethod EFFECTIVE_LENGTH

## Solver Options  ----
:SolverMethod BRENT

:EnableExhaustiveSolution

### Other Options  ----
:SkipHeadwaterNodes
:CreateRavenProfiles

### PostProcessing Options ----
:PostprocessingInterpolationMethod INTERP_HAND
:GISPath GIS_files
:WriteNetcdfFormat
:WritePngFormat
:WriteCatchmentJSON

### Runtime Options  ----
:SilentRun
:NoisyRun
:DebugRun

The specific commands are elaborated on below.

:ModelType

The model type is specified as either STEADYFLOW for standard step 1D calculations, or HAND_MANNING, which applies a simplified approach that uses the Manning’s equation to compute depths in each streamnode. In the latter case, the depths in each streamnode are computed independently and hydraulic considerations such as energy losses and backwater effects are not considered.

:RegimeType

The regime type is specified as either SUBCRITICAL, SUPERCRITICAL, or MIXED. Currently, Blackbird only supports the SUBCRITICAL regime.

:Tolerance

Tolerance error in metres within the standard step depth calculations at which the iteration stops and the solution is accepted.

:ToleranceNormalDepth

Tolerance error in metres within the normal depth calculations at which the iteration stops and the solution is accepted.

:IterationLimit

Limit on the number of iterations in the computation of depths by the standard step solver.

:ExtrapolateDepthTable

Boolean indicating whether to extrapolate beyond the data in the preprocessed hydraulic variables (TRUE) or stop if asked to extrapolate beyond the table limits (FALSE)

:FrictionSlopeMethod

The friction slope method which indicates how the average slope term $S_f$ is computed between two streamnodes. This term is applied in calculating the energy loss between two streamnodes. The available options are AVERAGE_CONVEYANCE (default), AVERAGE_FRICTION, GEOMETRIC_FRICTION, HARMONIC_FRICTION, and REACH_FRICTION.

For example, if method is selected as AVERAGE_CONVEYANCE, then $S_f$ is computed as:

\[ S_f = \left( \frac{Q_1+Q_2}{K_1+K_2} \right)^2 \] where $Q_1$ is the flow at the downstream streamnode, $Q_2$ is the flow at the upstream streamnode, $K_1$ is the conveyance of the downstream streamnode, and $K_2$ is the conveyance of the upstream streamnode.

If the method is AVERAGE_FRICTION, the friction slope $S_f$ is computed simply as:

\[S_f = \frac{S_{f_1} + S_{f_2}}{2}\] where $S_{f_1}$ is the friction slope at the downstream streamnode, and $S_{f_2}$ is the friction slope at the upstream streamnode.

:ManningCompositeMethod

This command specifies the method for computing the composite Manning’s roughness for the streamnode at a particular depth. This may be one of the following options: EQUAL_FORCE, WEIGHTED_AVERAGE_AREA, WEIGHTED_AVERAGE_WETPERIMETER, WEIGHTED_AVERAGE_CONVEYANCE, and EQUAL_VELOCITY.

If the method is EQUAL_FORCE (the default), then $n_c$ is computed as:

\[ n_c = \sqrt{\frac{1}{P} \sum P_i*n_i^2} \]

where $P$ is the total wetted perimeter, $P_i$ is the wetted perimeter of the ith section, and $n_i$ is the Manning’s roughness coefficient of the ith section.

If the method is WEIGHTED_AVERAGE_CONVEYANCE, then $n_c$ is computed as:

\[ n_c = \frac{1}{K_T} \sum_{i=1}^{N_b} K_i*n_i \]

where $K_T$ is the total conveyance ($\sum K_i$), $K_i$ is the ith conveyance, $n_i$ is the ith roughness coefficient, and $N_b$ is the number of sections (either cross-sections divisions or raster cells).

:SilentRun

The model runs with minimal output if TRUE, useful for faster and repeated runs.

:NoisyRun

The model runs with additional output if TRUE, useful in model investigations and diagnostics.

:DebugRun

The model runs with even more outputs that are typically used in debugging. This has some overlap with :NoisyRun

:DHANDMaxDepth

The maximum depth (metres) used to compute DHAND rasters. In tandem with :DHANDDepthStep, Blackbird will look to DHAND rasters in the folder defined by :GISPath based on the sequence of DHAND depths.

:DHANDDepthStep

The depth increment (metres) used to compute DHAND rasters. In tandem with :DHANDMaxDepth, Blackbird will look to DHAND rasters in the folder defined by :GISPath based on the sequence of DHAND depths.

:WriteNetcdfFormat

If this command is present, generates output depth rasters in NetCDF format instead of GeoTiff format.

:InputNCFile

Optional name of the input NetCDF file (NOTE: must be relative to :GISPath). If not present, will search for the default name of bb_inputs.nc

:WritePngFormat

If this command is present, generates output depth rasters in PNG format instead of GeoTiff format with metadata provided in JSON format.

:RoughnessMultiplier

A numeric global roughness multiplier that multiplies all Manning’s n roughness values at each streamnode by the given value. Multiplier must be greater than zero.

:XSectionConveyanceMethod

The conveyance method for cross-sections. This may be one of OVERBANK_CONVEYANCE, DEFAULT_CONVEYANCE, COORDINATE_CONVEYANCE, DISCRETIZED_CONVEYANCE_XS, AREAWEIGHTED_CONVEYANCE_ONECALC_XS, or AREAWEIGHTED_CONVEYANCE.

:ReachConveyanceMethod

The conveyance method for reaches. This may be one of DISCRETIZED_CONVEYANCE_R, AREAWEIGHTED_CONVEYANCE_ONECALC_R, or ROUGHZONE_CONVEYANCE.

:ReachIntegrationMethod

The integration method for reaches, which tells Blackbird how the pre-processed hydraulic properties were computed. If the option is set to EFFECTIVE_LENGTH (default), this indicates the effective length was used to normalize properties. If REACH_LENGTH, this indicates the reach length was used for normalization, and Blackbird will automatically recalculate the properties in the pre-processed tables to be normalized to the effective reach length.

:SolverMethod

This indicates the type of solver to be used in computing depths in the model. For steady-state, the options are as follows:

BRENT (default): uses an implementation of the Brent root-finding algorithm (Brent (1973)) to robustly compute the critical and estimated depths. This is the recommended method for all steady-state cases.
SECANT: uses the secant method to estimate critical and estimated depths. This implementation uses a number of rules depending on the depths and iteration number to attempt to produce stable results. If the :EnableExhaustiveSolution is also in the .bbi file, then the secant method will instead of the EXAUSTIVE approach for a given node if a stable solution is not found after a few iterations with the SECANT method.
EXHAUSTIVE: a non-iterative method, this method deploys an ‘exhaustive’ calculation of all points in the pre-processed depth curves to determine which depth has a minimum energy for the critical depth, and which produces the lowest error in the energy balance from the previous node, resulting in the estimated depth. The accuracy of this method is limited by the points in the pre-processed depth curves as no interpolation is performed, and will very likely be slightly slower than the BRENT method.

:SkipHeadwaterNodes

This option allows the model to skip all calculations in headwater nodes, and effectively set the depth to zero in all headwater streamnodes.

This is useful in building coupled hydrologic-hydraulic models, where the flow estimations require the drainage area from headwater basins to be included, even if a complete channel for flood mapping with Blackbird is not defined.

:CreateRavenProfiles

With this option, the model will not be run to estimate depths and/or produce depth maps. Instead, an output file with Raven-compliant channel rating curves will be created for each streamnode in the model. This file can be used as an alternative to specifying channel profiles with cross-sections of elevation and roughness values. The output format of this file is:

:ChannelRatingCurves profile_00002
  :BedSlope 0.0984
  :StageRelations  # [depth, area, top_width, discharge, perimeter]
    0.00, 0.000, 0.000, 0.000, 0.000
    0.50, 2.043, 177.422, 12.089, 177.422
    ...
  :EndStageRelations
:EndChannelRatingCurves

Streamnodes with a bed slope of less than 0.01 are set to 0.01 to comply with Raven limits on bed slope for routing (Raven issues warnings with a bed slope of less than 0.01).

If :SkipHeadwaterNodes is specified, then headwater nodes will also be skipped in the generated channel rating curves file, since it is assumed that headwater nodes will not have useful routing information and are also not required in Raven. Instead, a single default profile is provided for headwaters with placeholder values. This is not anticipated to impact the routing in Raven, as channel routing is not performed for headwater basins.

In addition, a default Raven-compliant .rvh file will be produced, with a :Subbasins and :HRUs block included, which assumes a single HRU per subbasin. A default set of classes are included for each HRU. Slope is set to the bed slope (a bold assumption, as the channel bed slope is likely not the same as the overall subbasin slope), and the aspect is simply set to 90 for each HRU. For more sophisticated Raven models, it is recommended that the HRU properties are recalculated, as the values in this HRU table may not be accurate, and may have implications on rainfall-runoff modelling.

:PostprocessingInterpolationMethod

The post-processing method used to generate depth rasters following the computation of depths at each streamnode. This may be one of:

NONE: no depth raster is computed, only HydraulicOutputs.csv is outputted from results.
CATCHMENT_HAND: the streamnode depth is applied as a constant depth within the streamnode, and depths are computed from the HAND raster
INTERP_HAND: streamnode depths are interpolated, and depths are computed using the HAND raster
CATCHMENT_DHAND: the streamnode depth is applied as a constant depth within the streamnode, and depths are computed from the closest DHAND raster
INTERP_DHAND: streamnode depths are interpolated, and depths are computed from the closest DHAND raster

:WriteNetcdfFormat

The output format of flood rasters is instead written in netcdf as an .nc file.

:WritePngFormat

The output format of flood rasters is instead written as a .png file, which is optimized for viewing in web browsers.

:WriteCatchmentJSON

The JSON files used in BlackbirdView are additional written to the output folder.

:GISPath

Defines the directory where Blackbird will look for relevant GIS files. Standard naming conventions for all inputs GIS files are expected within this folder, others will be ignored.

:RedirectToFile

This command will direct Blackbird to read in another .bbi file at the specified location. This command is useful for organization of multiple large model files.

2.2.2 Boundary Conditions file (.bbb)

The primary input file (.bbb) stores the model boundary conditions, including any upstream or downstream boundaries (e.g., normal depth at the downstream streamnode) and flows provided to the model. An example .bbb file is shown below.

## Blackbird Boundary Conditions File (.bbb)
# 

:BoundaryCondition
  :StationName catch_050
  :Station -99
  :Reach default_reach_name
  :Location downstream
  :BCType NORMAL_DEPTH
  :BCValue 0.005713
  :InitialWSL -99
:EndBoundaryCondition

:SteadyFlows
  :Attributes  nodeID  flowprofile1  flowprofile2  flowprofile3
      2  156.2  246.2  314.7
:EndSteadyFlows

# source and sinks correspond to number of flow profiles
# if none provided assume sources and sinks are all zero
:StreamnodeSourcesSinks
  :Attributes  nodeID  source  sink  source  sink  source  sink
      2  0  0  0  0  0  0
:EndStreamnodeSourcesSinks

The specific commands are elaborated on below.

:BoundaryCondition

The boundary conditions at specific streamnodes that allow the standard step solution to start at either the upstream or downstream ends are provided within this block. For a subcritical regime, this only needs to be defined at the downstream most streamnode (the only regime currently supported).

:StationName

Within the :BoundaryConditions block, the station name defines the name of the streamnode at which the boundary condition is applied.

:Reach

Within the :BoundaryConditions block, the name of the reach on which the streamnode is located.

:Location

Within the :BoundaryConditions block, the location is defined either as DOWNSTREAM or UPSTREAM, depending on the type of boundary condition being applied.

:BCType

Within the :BoundaryConditions block, this defines the type of boundary condition. This can be one of:

NORMAL_DEPTH: computes the normal depth at the streamnode
SET_WSL: sets the water surface level (WSL) to a specified value (must be greater than or equal to the minimum thalweg elevation)
SET_DEPTH: sets the depth in the streamnode (must be greater than zero)

:InitialWSL

Within the :BoundaryConditions block, the initial water surface level may be set. If left as blank (-99), this will be estimated automatically as a starting guess. Only used if :BCType is NORMAL_DEPTH.

:SteadyFlows

This table specifies the flows (in $m^3/s$) at each node by nodeID. Multiple flow profiles may be provided, and each flow profile (i.e., a set of flows describing flow at each streamnode) will be run in each model simulation. The table is provided in the following format:

:SteadyFlows
  :Attributes  nodeID  flowprofile1  flowprofile2  .. flowprofile3
      <nodeID1>  <flow1>  <flow2>  ... <flow3>
      <nodeID2>  <flow1>  <flow2>  ... <flow3>
      ...
:EndSteadyFlows

The flows may vary between streamnodes to represent accumulation of water within the system from rainfall-runoff process or other phenomenon. This table is used in conjunction with :StreamnodeSourcesSinks to compute the flows in each streamnode.

:StreamnodeSourcesSinks

This table (optionally) specifies the flow sources and sinks (in $m^3/s$) at each node by nodeID. For multiple flow profiles, the sources and sinks under each flow profile may be specified.

The table is provided in the following format, where fp refers to flow profile:

:StreamnodeSourcesSinks   
:Attributes  nodeID  source  sink  ... source  sink       
<nodeID1> <fp1_source> <fp1_sink> ... <fpN_source> <fpN_sink>       ... :EndStreamnodeSourcesSinks

These may be a more convenient method for representing explicitly where flows vary from the :SteadyFlows table. If not provided for any nodes (or at all), the sources and sinks for all flow profiles are assumed to be zero (i.e., no change from the :SteadyFlows table).

:ExplicitSteadyFlows

As an alternative to defining flows from headwater nodes with :SteadyFlows and specifying sources and sinks, you may instead define the flows in each streamnode explicitly with this command. This is configured as:

:ExplicitSteadyFlows
  :Attributes  nodeID  flowprofile1 flowprofile2
<nodeID1> <flow_nodeID1_fp1> <flow_nodeID1_fp2>
<nodeID2> <flow_nodeID2_fp1> <flow_nodeID2_fp2>
...
:EndExplicitSteadyFlows

In this case, sources and sinks are ignored if provided, and the flows for one or more profiles will be used directly with calculating flows throughout the system.

:RedirectToFile

This command will direct Blackbird to read in another .bbb file at the specified location. This command is useful for organization of multiple large model files.

2.2.3 Geometry file (.bbg)

The primary input file (.bbg) stores the model geometry data. A partial example .bbg file is shown below.


# :Streamnodes block must be defined first
:Streamnodes
  :Attributes  nodeID  nodetype  downnodeID  upnodeID1  upnodeID2  stationname  station  reachID  ds_reach_length  us_reach_length1  us_reach_length2  contraction_coeff  expansion_coeff  min_elev  bed_slope
      2  REACH  3  -1  -1  catch_002  284.5  1  269.8  284.5  -99  0.1  0.3  454.9058  0.0324
      3  XSECTION  4  2  -1  catch_003  554.4  1  277.6  269.8356  -99  0.1  0.3  454.6  0.02569
      ...
:EndStreamnodes

# point to preprocessed hydraulic variables for reaches
:RedirectToFile waldemar_reaches.bbg

# point to cross-section data
# :RedirectToFile waldemar_xsections.bbg

The specific commands are elaborated on below.

:Streamnodes

This defines the table of streamnodes used in the model, as well as relevant hydraulic properties of the network (such as the upstream and downstream nodes, reach lengths), and the type of streamnode. The type of streamnode may be REACH, in which case pre-processed reach-integrated properties will be expected to be provided later with the :PreprocHydTable command, or of type XSECTION, in which a cross-section profile will be expected with the :StreamnodeCrossSection command.

This table must be defined before other streamnode properties (such as cross-section or reach-integrated data) is provided.

:CrossSections

This defines the section in which cross-section data is provided, and ends with the :EndCrossSections command. Within this block, cross-section data is provided with the :StreamnodeCrossSection command. The format for this table is:

:StreamnodeCrossSection <nodeID> # nodeID
  :BankStations <xx1> <xx2>
  :RoughnessZoneValues <nn1> <nn2> <nn3>
  :Attributes xx zz nn
    0 100.0 0.05 # first one must be defined
    1 99.5        # interpret as the same as previous
    2 98          # interpret as 0.05
    3.5 96   0.035
    4 95.58  0.035
    5 96.5   
    6 97     0.07
    7 99     
:EndStreamnodeCrossSection

where:

within :BankStations, xx1 is the location of the left bank station, xx2 is the location of the right bank station
within :RoughnessZoneValues (optional), nn1 is the roughness value of the left overbank section, nn2 is the roughness at the channel section, nn3 is the roughness at the right overbank section. If provided, these will override the nn values in the Attributes section
within the :Attributes block, xx is the horizontal data perpendicular to the channel, zz is the elevation data in the cross-section, and nn is the Manning’s roughness value for that point. The roughness may be defined irregularly, in which case the previous roughness point is assumed to apply at the next horizontal location as well until a new one is defined.

:PreprocHydTable

This defines the table of pre-processed hydraulic properties for many attributes, and defined for each streamnode of type REACH.

The full description is omitted here for brevity, please see sample files for examples of this type of table.

:RedirectToFile

This command will direct Blackbird to read in another .bbg file at the specified location. This command is useful for organization of multiple large model files.

This is particularly recommended for the .bbg file, which is likely to be the largest file(s) in the Blackbird model setup. It may be especially helpful to separate the base :Streamnodes table, any :CrossSections data, and any :PreprocessedHydraulicTables data.

2.3 Running the Model

Once the installation and model file generation has been completed and you are ready to run Blackbird, you can do so from the Terminal or equivalent (Command Prompt or PowerShell in Windows). Open the terminal application and run:

Blackbird.exe modelname

where ‘modelname’ is the prefix to your .bbi, .bbg, and .bbb files. Blackbird will automatically find these files of the same name within the folder where the command is run. If you have not configured Blackbird to be run from anywhere on your system (see (installation?)), you will need a local copy of Blackbird.exe in the same folder as your model files.

Blackbird also supports the following arguments flags:

-o (output directory) : specifies the directory for generated model output
-g (geometry file) : specifies the .bbg file location
-b (boundary file) : specifies the .bbb file location
-s (silent mode) : runs with minimal output to the console
-n (noisy mode) : runs with lots of diagnostic output to console
-r (run name) : specifies the run name for the simulation and appends the run name to the model output files
-f (output format) : specifies the file format for blackbird to write output to, with options of :
- r : raster
- n : netcdf
- p : png

A useful application of these flags is to organize the model files, allowing for scripted runs with varying input files, and sorting output files into various folders. If the output (-o) flag is used, Blackbird will create a new output directory if it does not already exist.

2.4 Output Files

Blackbird generates a number of output files in each run by default:

Blackbird_errors.txt Contains all errors, warnings and advisories to the user about the model simulation
HydraulicOutput.csv A comma separated values (csv) file of hydraulic output information in table format. This specifies streamnode information as well as depths and other hydraulic outputs for each streamnode
bb_results_depth_<flow profile index>.tif A raster file of depth results is generated by Blackbird if the post-processing option is not NONE. Currently Blackbird only produces depth rasters, though other raster types may be available in future versions. The flow profile index numbering begins at 1 and corresponds to the flow profiles provided in the .bbb file (in order).
bb_results_depth.nc If :WriteNetcdfFormat is specified in the .bbi file, then the depth results are formatted into this NetCDF file instead of a set of GeoTiff files.

2.5 Comment Characters

3 References

Brent, Richard P. 1973. Algorithms for Minimization Without Derivatives. Englewood Cliffs, NJ: Prentice-Hall.

Chlumsky, R., J. R. Craig, and B. A. Tolson. 2024. “A Reach-Integrated Hydraulic Modelling Approach for Large-Scale and Real-Time Inundation Mapping.” Geoscientific Model Development Discussions 2024: 1–28. https://doi.org/10.5194/gmd-2024-184.

Chlumsky, Robert, James R. Craig, and Bryan A. Tolson. 2025. rchlumsk/Blackbird_manuscript_2024: Initial pre- release v2 (version 2). Zenodo. https://doi.org/https://doi.org/10.5281/zenodo.14340564.

Hydrologic Engineering Center. 2023. HEC-RAS User’s Manual Version 6.4. https://www.hec.usace.army.mil/confluence/rasdocs/rasum/latest.

Zheng, Xing, David G. Tarboton, David R. Maidment, Yan Y. Liu, and Paola Passalacqua. 2018. “River Channel Geometry and Rating Curve Estimation Using Height Above the Nearest Drainage.” Journal of the American Water Resources Association 54 (4): 785–806.