API Reference

This API reference is mostly for developers, though regular users might also be able to use the following functions in their own scripts and other software.

cord/modelrun.py

Functions to calculate the downstream water surface elevation by minimizing the difference between flows calculated via the Manning Formula for discharge and the historical peak flood values.

(https://en.wikipedia.org/wiki/Manning_formula) (https://en.wikipedia.org/wiki/Volumetric_flow_rate)

Author:

Matthew A. Turner <maturner01@gmail.com>

Date:

19 April 2016

class cord.modelrun.BoundarySolutionInfo(ws_elev, streamflow, error, success)

error

Alias for field number 2

streamflow

Alias for field number 1

success

Alias for field number 3

ws_elev

Alias for field number 0

class cord.modelrun.ModelRun

A single coupled run. First DFLOW then RipCAS. CoupledRunSequence will encapsulate a series of coupled runs commencing with preparation of the initial vegetation map for DFLOW. For now, assume that the vegetation map is provided to the run_dflow method.

calculate_bc(target_streamflow, dbc_geometry_file, streambed_roughness, slope)

Arguments:

target_streamflow (float): historical or other streamflow that

will be used to drive DFLOW model; this calculation recovers an estimate for the Water Surface elevation (WS) for this given streamflow.

dbc_geometry_file (str): path to the stream’s cross-sectional

geometry xyz file

streambed_roughness (float): Manning’s n-value for the streambed slope (float): slope taken for the reach

Returns:

(BoundaryCondition, BoundaryCondition): tuple of upstream and

downstream BoundaryCondition instances

run_dflow(dflow_run_directory, vegetation_map, veg_roughness_shearres_lookup, streambed_roughness, clobber=True, pbs_script_name='dflow_mpi.pbs', dflow_run_fun=None)

Both input and output dflow files will go into the dflow_run_directory, but in input/ and output/ subdirectories.

Arguments:

dflow_run_directory (str): directory where DFLOW files should be

put and where the dflow_run_fun will be run from

vegetation_map (str): path to the input vegetation.pol file. This

function assumes this has already been generated in the proper format b/c this seems like the best separation of responsibilities.

clobber (bool): whether or not to overwrite dflow_run_directory if

it exists

pbs_script_name (str): name of .pbs script w/o directory dflow_run_fun (function): argument-free function to run DFLOW.

Ex. dflow_run_fun=f where f defined by def f: subprocess.call([‘qsub’, ‘dflow_mpi.pbs’])

Returns:

None

class cord.modelrun.StreamflowTuple(ws_elev, streamflow)

streamflow

Alias for field number 1

ws_elev

Alias for field number 0

cord.modelrun.modelrun_series(data_dir, initial_vegetation_map, vegzone_map, veg_roughness_shearres_lookup, peak_flows_file, geometry_file, streambed_roughness, streambed_floodplain_roughness, streambed_slope, dflow_run_fun=None, log_f=None, debug=False)

Run a series of flow and succession models with peak flows given in peak_flows_file.

Arguments:

data_dir (str): write directory for modelrun series. Must exist initial_vegetation_map (str): location of year zero veg map vegzone_map (str): vegetation zone map location veg_roughness_shearres_lookup (str): Excel spreadsheet containing

conversion from vegetation code to roughness value and vegetation code to shear stress resistance

peak_flow_file (str): location of text file record of peak flows in

cubic meters per second

geometry_file (str): location of channel geometry at the downstream

location for calculating streamflow

streambed_roughness (float): streambed roughness in channel only; used

when converting vegetation map to roughness map

streambed_floodplain_roughness (float): an average roughness of

stream channel and floodplain used in calculation of downstream boundary condition for DFLOW

streambed_slope (float): rise over run of the channel used in

calculation of downstream boundary condition for DFLOW

dflow_run_fun (function): function delegate for the user to provide a

custom way to run DFLOW. If none is given, defaults to submitting a PBS job as is done on CARC systems

log_f (str): log file. if none is given, defaults to data_dir.log

with dashes replacing slashes

debug (bool): whether or not to run in debug mode. If running in debug

mode, each DFLOW run returns fake data and each RipCAS run takes cord/data/shear_out.asc as input

returns:

None

cord/ripcas_dflow.py

Utilities for interacting with dflow and ripcas models

Author:

Matthew A. Turner <maturner01@gmail.com>

Date:

9 May 2016

class cord.ripcas_dflow.Pol

Wrapper creating and/or reading the .pol files of n-values for DFLOW

classmethod from_ascii(asc)

Generate a polygon file from ESRIAsc

write(out_path)

write the Pol to file

Returns: None

cord.ripcas_dflow.ripcas(vegetation_map, zone_map, shear_map, ripcas_required_data)

Simple version of the CASiMiR model for vegetation succession. Before the model is run, we check that all the unique values from vegetation_map are present in the shear_resistance_dict. Otherwise the process will fail wherever the vegetation map value is not present in the dictionary on lookup.

Arguments:

vegetation_map (str or ESRIAsc): location on disk or ESRIAsc

representation of the vegetation map

zone_map (str or ESRIAsc): location on disk or ESRIAsc representation

of the zone map.

shear_map (str or ESRIAsc): location on disk or ESRIAsc representation

of the shear stress map

ripcas_required_data (str): Excel spreadsheet of data needed for

ripcas run. Encompasses the landscape model for the watershed. Can have one or two ‘Code’ columns and must have exactly one ‘shear_resis’ column and exactly one ‘n_val’ column

Returns:

(ESRIAsc) vegetation map updated with new values corresponding to

succession rules

cord.ripcas_dflow.ripcas_with_dflow_io(vegetation_map, zone_map, streambed_roughness, shear_nc_path, ripcas_required_data)

Wrapper for using DFLOW input/output with ripcas. Note instead of shear_map we have shear_nc_path. Use shear_mesh_to_asc to convert the shear_mesh that comes from D-FLOW to a shear_map for input to ripcas. When ripcas finishes its vegetation updates, convert the updated vegetation map to a Manning n-value map for use by DFLOW. See the ripcas function below for more details on the model and arguments.

Arguments:

vegetation_map (ESRIAsc): location on disk or ESRIAsc

representation of the vegetation map

zone_map (ESRIAsc): location on disk or ESRIAsc representation

of the zone map.

shear_nc_path (str): location on disk of DFLOW shear output netCDF ripcas_required_data (str): Excel spreadsheet of data needed for

ripcas run. Encompasses the landscape model for the watershed. Can have one or two ‘Code’ columns and must have exactly one ‘shear_resis’ column and exactly one ‘n_val’ column

Returns:

(Pol): polygon representation of the map of nvalues

cord.ripcas_dflow.shear_mesh_to_asc(shear_nc_path, header_dict)

Extract flow element values and locations from the dflow output netcdf and project these onto the grid defined by the corner of the grid defined by the lower-left corner of the bounding box and the cell size. The results are saved in ESRI .asc format to asc_out_path.

Arguments:

shear_nc_path (str): location of the dflow netcdf on disk header_dict (dict): dictionary with six fields as required to build

ESRIAsc; NODATA_value, cellsize, ncols, nrows, yllcorner, xllcorner

Returns:

(ESRIAsc) representation of gridded representation of the mesh shear

stress data output from dflow

cord.ripcas_dflow.veg2n(veg_map, ripcas_required_data, streambed_roughness)

Creat an ESRIAsc representation of an ESRI .asc file that contains roughness values substituted for vegetation codes. The translation is found in the Excel file found at lookup_path.

Arguments:

veg_map (ESRIAsc): path to ESRI .asc file with vegetation codes ripcas_required_data (str): path to Excel file with vegetation

codes mapped to Manning’s roughness n-values. The Excel file must have four columns with headers

Code shear_resis Code n_val

on the first sheet.

streambed_roughness (float): Manning’s roughness value for the

streambed itself, which is represented with zeros in the veg map

Raises:

(ValueError) if there is a vegetation code in the .asc that is not

found in the lookup table

Returns:

(ESRIAsc) ESRI .asc map of Manning’s n-values in place of veg codes