BMI_Tutorial
The tutorial runs on top of the standard Lower Colorado V4 tutorial directory structure, i.e., it runs entirely in t-route's V4 mode, and with HYfeatures data. Due to its simplicity, the Cedar Bayou example is used to demonstrate the capability and reported on here. The following inputs will need to be collected:
- Cedar Bayou geopackage (of geopackage containing same), e.g.,
Diff_Texas_CedarBayou_NGENv201.gpkg. - Coastal boundary input file (in this example, DFLOW output), e.g.,
coastal_boundary_input_file = boundary_forcing/FlowFM_0000_his.nc - Coastal domain yaml boundary file, e.g.,
domain/coastal_domain_LC_US_DS.yaml. - qlat input forcing files, e.g.,
qlat_file_pattern_filter = "*.CHRTOUT_DOMAIN1.csv"in a designatedqlat_input_folder. - usgs timeslices and rfc input folders (other gages are not enabled; e.g.,
usgs_timeslicesandrfc_timeseries)
In the main BMI script, reference is made to a dedicated Standard_Coastal_AnA.yaml script. That script needs to be adapted to the aforementioned inputs.
The main script run_BMI_Coastal.py is available in the standard repository of t-route, in the test/LowerColorado_TX_v4 folder. It relies on the following standard and t-route libraries:
Standard libraries:
import sys
import glob
import os
import numpy as np
import pandas as pd
import geopandas as gpd
import pickle
from datetime import datetime, timedelta
import time
import xarray as xr
T-route repository libraries:
import bmi_troute
import bmi_DAforcing
from troute.HYFeaturesNetwork import HYFeaturesNetwork
from troute.AbstractNetwork import *
import bmi_df2array as df2a
In order to simulate a BMI "transmitter", a troute model is initiated, and initialized with the Standard_Coastal_AnA.yaml configuration file:
Initialize troute model with configuration file
print('Initialize t-route Module...')
troute = bmi_troute.bmi_troute()
troute.initialize(bmi_cfg_file = base_path + config_dict[config]['yaml'])
troute is an instance of the bmi_troute class that, when initialized, reads a yaml configuration file and creates and initializes a values dictionary (as a member of the class) that holds all the necessary data needed by a troute run. In addition, the bmi_troute class has member functions, the most important of which are set_value and get_value.
In addition to the BMI "transmitter", a BMI "receiver" is defined as a BMI data assimilation module:
Initialize DA model with configuration file
print('Initialize DA Module...')
DAforcing = bmi_DAforcing.bmi_DAforcing()
DAforcing.initialize(bmi_cfg_file = base_path + config_dict[config]['yaml'])
DAforcing, in turn, is an instance of the bmi_DAforcing class, which ingests BMI compliant data (in principle, numpy.ndarrays), and converts them into dataframes that t-route can work with. When initialized, the bmi_DAforcing class combines groups of numpy.ndarrays corresponding to a dataframe (e.g., usgs_df or rfc_timeseries_df) and builds that dataframe. Complementary to bmi_troute, there are other member functions, the most important of which is set_value.
Specifically, the coastal dataframe is imported from a DFLOW file, using the xarray library. Please note that while the read_DFlow_output helper function from t-route is used, troute here does not actually read in the coastal dataframe directly - this is only done to simulate BMI functionality, since no coastal BMI data "transmitter" is available:
coastalFile = 'boundary_forcing/FlowFM_0000_his.nc'
ds = xr.open_dataset(coastalFile)
coastalDataFrame = read_DFlow_output(ds)
BMI compatible arrays are prepared for transmission by setting corresponding values dictionaries in the troute class using set_value. For each dataframe to be imported, there are at least three numpy.ndarrays: (1) one flattened array containing the values of the data entries (usually 64 bit floats of physical quantities such as flow rates or water depths), (2) column names (typically time stamps), and (3) row indices (typically a coded designation of a flow path element). The preparation is shown, for the dataframe containing the coastal water depth, in the following image:
