Usage Guides

This section provides detailed usage guides for each tool in the vewutils package.

Channelpaving

The channelpaving module provides tools for adding or editing 1D/2D channels in an ADCIRC mesh. The primary interface is through Python API and MATLAB scripts rather than command-line tools. See the examples directory for detailed examples of using this module.

DEM2ADCDP

Maps Digital Elevation Model (DEM) data onto ADCIRC mesh nodes.

python -m vewutils.dem2adcdp.dem2adcdp meshfile outmeshfile tiffile [options]

Arguments:

  • meshfile: Input mesh file

  • outmeshfile: Output mesh file with updated depths

  • tiffile: DEM file in GeoTIFF format

Options:

  • --f13file FILE: F13 file containing VEW information

  • --cachefile FILE: Cache file for storing intermediate results

  • --assign_channelnode_depths: Force to assign depths at channel nodes

  • --target_add_all: Add all nodes to target list

  • --target_remove_all: Remove all nodes from target list

  • --target_add_by_polygons POLYGONS: Add nodes within specified polygons (comma-separated list of polygon files)

  • --target_remove_by_polygons POLYGONS: Remove nodes within specified polygons

  • --target_remove_by_polygons_outside POLYGONS: Remove nodes outside specified polygons

  • --target_add_channelnodes: Add channel nodes to target list

  • --target_remove_channelnodes: Remove channel nodes from target list

  • --target_add_banknodes: Add bank nodes to target list

  • --target_remove_banknodes: Remove bank nodes from target list

  • --target_add_boundarynodes: Add boundary nodes to target list

  • --channel_deeper_by FLOAT: Difference in depth by which channel node is deepened compared to bank (default: 0.001)

  • --channel_deeper_by_threshold FLOAT: Threshold for applying channel_deeper_by option (default: 10000)

  • --deepen: Assign an extracted value only when it is deeper than the current depth

  • --land_only: Assign depth only when the resulting elevation is above 0 m

  • --submerged_only: Assign depth only when both the current and resulting elevations are below 0 m

  • --min_depth FLOAT: Minimum depth value to be assigned to mesh nodes (default: -100000.0)

  • --min_depth_tapering_end FLOAT: Depth at which tapering of the minimum depth application ends

  • --max_depth FLOAT: Maximum depth value to be assigned to mesh nodes (default: 100000.0)

  • --method {mean,max,min}: Extract method for elevation values (default: mean)

  • --ignore_tiff: Ignore values in tiff file and apply min_depth/max_depth only

  • --ncores INT: Number of CPU cores to use (default: 1)

  • --chunk_size_poly INT: Chunk size for polygon operations (default: 1000)

  • --chunk_size_zonalstats INT: Chunk size for zonal statistics operations (default: 1000)

Hydrologyboundary

The hydrologyboundary module provides tools for generating flow boundary condition files for ADCIRC. It supports retrieving flow data from both USGS gauges and the National Water Model (NWM).

Primary components: * fluxboundaries: Core module for handling flux boundary conditions * nwm: Utilities for working with National Water Model data * usgs: Utilities for working with USGS streamflow data

Example usage in Python:

from vewutils.hydrologyboundary import fluxboundaries as fluxb
from vewutils.hydrologyboundary import usgs
from vewutils.hydrologyboundary import nwm
from datetime import datetime, timezone, timedelta

# Create a flux boundary handler
flux_boundaries = fluxb.FluxBoundaries()

# Generate flux boundary segments from an ADCIRC mesh
adcmesh_file = "path/to/mesh.grd"
flux_boundaries.generate_fluxboundary_segments_from_adcmesh(adcmesh_file)

# Initialize boundary definitions
flux_boundaries.init_boundary_defs()

# Set boundary conditions using different methods:

# 1. Set USGS gauge at specific location
flux_boundaries.set_boundary_defs_at_lonlat(-77.5825, 35.4289, "usgs_siteid", '02091500')

# 2. Set NWM feature at specific location
flux_boundaries.set_boundary_defs_at_lonlat(-77.9974, 35.3370, "nwm_featureid", 11239411)

# 3. Set constant flow rate (in m³/s)
flux_boundaries.set_boundary_defs_at_lonlat(-77.5078, 35.4230, "const_m3s", 0.0)

# 4. Automatically assign NWM features to remaining boundaries
hydrofabricfile = "path/to/nwm_channels.shp"
flux_boundaries.set_boundary_defs_to_nwm_at_NA(hydrofabricfile, max_dist=100.0)

# 5. Set remaining undefined boundaries to zero flow
flux_boundaries.set_boundary_defs_at_NA("const_m3s", 0.0)

# Process the boundary definitions
flux_boundaries.digest_boundary_defs()

# Set the time range and generate discharges
start = datetime(2018, 8, 23, 0, 0, tzinfo=timezone.utc)
end = datetime(2018, 10, 9, 3, 0, tzinfo=timezone.utc)
step = timedelta(seconds=900)  # 15-minute intervals

# Retrieve discharge data from database
flux_boundaries.set_discharge_from_database(start, end)

# Write the fort.20 file
flux_boundaries.write_fort20("output.fort20", start, end, step)

Mesh

Mesh Merger

Merges multiple ADCIRC meshes together.

python -m vewutils.mesh.mesh_merger channelmesh landmesh [-o OUTPUT] [-d DESCRIPTION] [-b {merge,vew}] [--use-land-values]

Arguments:

  • channelmesh: Path to the channel mesh file

  • landmesh: Path to the land mesh file

  • -o, --output: Path to save the merged mesh (default: merged_mesh.grd)

  • -d, --description: Description for the merged mesh (default: merged)

  • -b, --boundary-mode: How to handle mesh boundaries: ‘merge’ to merge nodes, ‘vew’ to use VEW boundaries (default: merge)

  • --use-land-values: Use land mesh values at matching nodes (default: use channel mesh values)

Mesh Subtractor

Subtracts one mesh from another while preserving boundaries.

python -m vewutils.mesh.mesh_subtractor mesh_a mesh_b [-o OUTPUT] [-d DESCRIPTION]

Arguments:

  • mesh_a: Path to first mesh file (mesh to subtract from)

  • mesh_b: Path to second mesh file (mesh defining subtraction boundary)

  • -o, --output: Output mesh file path (default: subtracted_mesh.grd)

  • -d, --description: Description for the subtracted mesh (default: subtracted)

Add Land Boundaries

Adds land boundaries to an ADCIRC mesh.

python -m vewutils.mesh.add_land_boundaries input_mesh [-o OUTPUT] [-d DESCRIPTION]

Arguments:

  • input_mesh: Path to the input mesh file

  • -o, --output: Path to save the output mesh (default: mesh_with_land_boundaries.grd)

  • -d, --description: Description for the output mesh (default: mesh with land boundaries)

Adjust VEW Channel Elevations

Adjusts the elevation of VEW channels in an ADCIRC mesh.

python -m vewutils.mesh.adjust_vew_channel_elevations input_mesh [-o OUTPUT] [-t TOLERANCE]

Arguments:

  • input_mesh: Path to the input mesh file

  • -o, --output: Path to save the output mesh file (default: adjusted_mesh.14)

  • -t, --tolerance: Amount to lower channel node elevations below bank node elevations in meters (default: 0.001)

Adjust VEW Barrier Heights

Adjusts the height of VEW barriers in an ADCIRC mesh.

python -m vewutils.mesh.adjust_vew_barrier_heights input_mesh [-o OUTPUT] [-t TOLERANCE]

Arguments:

  • input_mesh: Path to the input mesh file

  • -o, --output: Path to save the output mesh file (default: adjusted_mesh.14)

  • -t, --tolerance: Minimum amount that barrier heights should be above bank elevations in meters (default: 0.001)

Nodal Attribute

Manning’s n Extractor

Extracts Manning’s n values from landuse data.

python -m vewutils.nodalattribute.manningsn_extractor mesh landcover class_to_mn [-o OUTPUT] [-s SELECTED-NODES] [-f FORT13] [--format {fort13,csv}]

Arguments:

  • mesh: Path to the mesh file

  • landcover: Path to the land cover raster file

  • class_to_mn: Path to the class to Manning’s n mapping file

  • -o, --output: Output file path (default: mannings_n.fort.13)

  • -s, --selected-nodes: Path to CSV file containing selected nodes

  • -f, --fort13: Path to input fort.13 file

  • --format: Output format: ‘fort13’ or ‘csv’ (default: fort13)

Attribute Transfer

Transfers attributes from one mesh to another.

python -m vewutils.nodalattribute.attribute_transfer source_mesh source_attrs target_mesh [-o OUTPUT]

Arguments:

  • source_mesh: Path to source grid file (fort.14)

  • source_attrs: Path to source nodal attribute file (fort.13)

  • target_mesh: Path to target grid file (fort.14)

  • -o, --output: Output nodal attribute file path (default: transferred_attributes.fort.13)

Plot

Plot Hydrograph at Station

Plots hydrographs from simulation results and observations.

python -m vewutils.plot.plot_hydrograph_at_station --station_owner STATION_OWNER --station_id STATION_ID [--station_lon STATION_LON] [--station_lat STATION_LAT] --station_datum STATION_DATUM --date_start DATE_START --date_end DATE_END --f63files F63FILES [F63FILES ...] --f63starts F63STARTS [F63STARTS ...] --f63labels F63LABELS [F63LABELS ...] [--plot_movingaverage] --outputfile OUTPUTFILE

Arguments:

  • --station_owner: Station owner: NOAA or USGS

  • --station_id: Station ID

  • --station_lon: Station longitude (optional)

  • --station_lat: Station latitude (optional)

  • --station_datum: Station datum: MSL or NAVD

  • --date_start: Start date (YYYY-MM-DD)

  • --date_end: End date (YYYY-MM-DD)

  • --f63files: List of fort.63.nc files

  • --f63starts: List of f63 start times (YYYY-MM-DD)

  • --f63labels: List of labels for f63 files

  • --plot_movingaverage: Plot moving average (flag)

  • --outputfile: Output figure file name

Utils

Node Selector

Selects nodes from an ADCIRC mesh based on specified criteria.

python -m vewutils.utils.node_selector mesh_file [-o OUTPUT] [-p POLYGON] [-m BOUNDARY-MESH] [-c CSV] [-t TOLERANCE] [-b {channel,bank,both}] [-op {union,intersection}]

Arguments:

  • mesh_file: Path to the ADCIRC mesh file

  • -o, --output: Output CSV file path (default: selected_nodes.csv)

  • -p, --polygon: Path to geospatial file containing polygons

  • -m, --boundary-mesh: Path to mesh file defining boundary

  • -c, --csv: Path to CSV file containing node IDs

  • -t, --tolerance: Tolerance in meters for boundary proximity (default: 1e-6)

  • -b, --boundary-type: Type of boundary nodes to include: ‘channel’, ‘bank’, or ‘both’ (default: both)

  • -op, --operation: Operation to combine multiple selections: ‘union’ or ‘intersection’ (default: union)

VEW Processing

Polyline Converter

Converts polylines to VEW strings in YAML format.

python -m vewutils.vewprocessing.polyline_converter meshfile polylinefile [-o OUTPUT] [-d DISTANCE] [-e ELEVATION] [-n MANNINGS]

Arguments:

  • meshfile: Path to the ADCIRC mesh file (fort.14)

  • polylinefile: Path to the polyline file (shapefile, geojson, etc.)

  • -o, --output: Path to save the VEW strings (default: vewstrings.yaml)

  • -d, --distance: Maximum distance for nearest neighbor search in meters (default: 10.0)

  • -e, --elevation: Bank elevation for VEW strings (default: 1.0)

  • -n, --mannings: Manning’s n value for VEW strings (default: 0.02)

VEW Adder

Adds Vertical Element Walls to a mesh using node strings from a YAML file.

python -m vewutils.vewprocessing.vew_adder f14file vewfile -o OUTPUT

Arguments:

  • f14file: Input fort.14 file

  • vewfile: Input YAML file containing VEW string definitions

  • -o, --output: Output fort.14 file

VEW Scraper

Extracts VEW boundaries from an ADCIRC mesh and saves them to YAML format.

python -m vewutils.vewprocessing.vew_scraper input_mesh -o OUTPUT_MESH -y OUTPUT_YAML [-d DESCRIPTION]

Arguments:

  • input_mesh: Path to the input mesh file with VEW boundaries

  • -o, --output-mesh: Path to save the mesh without VEW boundaries

  • -y, --output-yaml: Path to save the extracted VEW strings in YAML format

  • -d, --description: Description for the output mesh (default: Generated by vew_scraper)