River Module
The river module contains a set of functions to calculate quantities of interest for river energy converters (REC).
 Discharge time series data is stored as a pandas DataFrame indexed by time.
Time can be specified in datetime or in seconds. The column names describe the type of data in each column.
IO
The io submodule contains the following functions to load USGS discharge and Delft3D data.
Reads a USGS JSON data file (from https://waterdata.usgs.gov/nwis) 

Loads USGS data directly from https://waterdata.usgs.gov/nwis using a GET request 

Get variable data from the NetCDF4 object at a specified layer and timestep. 

Turns three coordinate inputs into a single output DataFrame of points. 

Interpolate multiple variables from the Delft3D onto the same points. 

Get data points for a passed variable for all layers at a specified time from the Delft3D NetCDF4 object by iterating over the get_layer_data function. 

Calculate the turbulent intensity percentage for a given data set for the specified points. 
 mhkit.river.io.d3d.get_all_time(data)[source]
Returns all of the time stamps from a D3D simulation passed to the function as a NetCDF object (data)
 Parameters
data (NetCDF4 object) – A NetCDF4 object that contains spatial data, e.g. velocity or shear stress generated by running a Delft3D model.
 Returns
seconds_run (array) – Returns an array of integers representing the number of seconds after the simulation started and that the data object contains a snapshot of simulation conditions at that time.
 mhkit.river.io.d3d.index_to_seconds(data, time_index)[source]
The function will return ‘seconds_run’ if passed a ‘time_index’
 Parameters
data (NetCDF4 object) – A NetCDF4 object that contains spatial data, e.g. velocity or shear stress, generated by running a Delft3D model.
time_index (int) – A positive integer to pull the time index from the dataset. 0 being closest to time 0. Default is last time index 1.
 Returns
seconds_run (int, float) – The ‘seconds_run’ is the seconds corresponding to the ‘time_index’ increments.
 mhkit.river.io.d3d.seconds_to_index(data, seconds_run)[source]
The function will return the nearest ‘time_index’ in the data if passed an integer number of ‘seconds_run’
 Parameters
data (NetCDF4 object) – A NetCDF4 object that contains spatial data, e.g. velocity or shear stress, generated by running a Delft3D model.
seconds_run (int, float) – A positive integer or float that represents the amount of time in seconds passed since starting the simulation.
 Returns
time_index (int) – The ‘time_index’ is a positive integer starting from 0 and incrementing until in simulation is complete.
 mhkit.river.io.d3d.get_layer_data(data, variable, layer_index=1, time_index=1)[source]
Get variable data from the NetCDF4 object at a specified layer and timestep. If the data is 2D the layer_index is ignored.
 Parameters
data (NetCDF4 object) – A NetCDF4 object that contains spatial data, e.g. velocity or shear stress, generated by running a Delft3D model.
variable (string) – Delft3D outputs many vairables. The full list can be found using “data.variables.keys()” in the console.
layer_index (int) – An integer to pull out a layer from the dataset. 0 being closest to the surface. Default is the bottom layer, found with input 1.
time_index (int) – An integer to pull the time index from the dataset. 0 being closest to the start time. Default is last time index, found with input 1.
 Returns
layer_data (DataFrame) – DataFrame with columns of “x”, “y”, “waterdepth”, and “waterlevel” location of the specified layer, variable values “v”, and the “time” the simulation has run. The waterdepth is measured from the water surface and the “waterlevel” is the water level diffrencein meters from the zero water level.
 mhkit.river.io.d3d.create_points(x, y, waterdepth)[source]
Turns three coordinate inputs into a single output DataFrame of points. In any order the three inputs can consist of 3 points, 2 points and 1 array, or 1 point and 2 arrays. The final output DataFrame will be the unique combinations of the 3 inputs.
 Parameters
x (float, array or int) – x values to create points.
y (float, array or int) – y values to create points.
waterdepth (float, array or int) – waterdepth values to create points.
 Returns
points (DateFrame) – DataFrame with columns x, y and waterdepth points.
Example
If the inputs are 2 arrays: and [3,4,5] and 1 point [6], the output will contain 6 array combinations of the 3 inputs as shown.
x=np.array([1,2]) y=np.array([3,4,5]) waterdepth= 6 d3d.create_points(x,y,waterdepth)
x y waterdepth
0 1.0 3.0 6.0 1 2.0 3.0 6.0 2 1.0 4.0 6.0 3 2.0 4.0 6.0 4 1.0 5.0 6.0 5 2.0 5.0 6.0
 mhkit.river.io.d3d.variable_interpolation(data, variables, points='cells', edges='none')[source]
Interpolate multiple variables from the Delft3D onto the same points.
 Parameters
data (NetCDF4 object) – A NetCDF4 object that contains spatial data, e.g. velocity or shear stress generated by running a Delft3D model.
variables (array of strings) – Name of variables to interpolate, e.g. ‘turkin1’, ‘ucx’, ‘ucy’ and ‘ucz’. The full list can be found using “data.variables.keys()” in the console.
points (string, DataFrame) –
 The points to interpolate data onto.
’cells’ interpolates all data onto the Delft3D cell coordinate system (Default) ‘faces’ interpolates all dada onto the Delft3D face coordinate system DataFrame of x, y, and waterdepth coordinates  Interpolates data onto user povided points. Can be created with create_points function.
edges (sting: 'nearest') – If edges is set to ‘nearest’ the code will fill in nan values with nearest interpolation. Otherwise only linear interpolarion will be used.
 Returns
transformed_data (DataFrame) – Variables on specified grid points saved under the input variable names and the x, y, and waterdepth coordinates of those points.
 mhkit.river.io.d3d.get_all_data_points(data, variable, time_index=1)[source]
Get data points for a passed variable for all layers at a specified time from the Delft3D NetCDF4 object by iterating over the get_layer_data function.
 Parameters
data (Netcdf4 object) – A NetCDF4 object that contains spatial data, e.g. velocity or shear stress, generated by running a Delft3D model.
variable (string) – Delft3D variable. The full list can be of variables can be found using “data.variables.keys()” in the console.
time_index (int) – An integer to pull the time step from the dataset. Default is last time step, found with the input 1.
 Returns
all_data (DataFrame) – Dataframe with columns x, y, waterdepth, waterlevel, variable, and time. The waterdepth is measured from the water surface and the “waterlevel” is the water level diffrence in meters from the zero water level.
 mhkit.river.io.d3d.turbulent_intensity(data, points='cells', time_index=1, intermediate_values=False)[source]
Calculate the turbulent intensity percentage for a given data set for the specified points. Assumes variable names: ucx, ucy, ucz and turkin1.
 Parameters
data (NetCDF4 object) – A NetCDF4 object that contains spatial data, e.g. velocity or shear stress, generated by running a Delft3D model.
points (string, DataFrame) –
 Points to interpolate data onto.
’cells’: interpolates all data onto velocity coordinate system (Default). ‘faces’: interpolates all data onto the TKE coordinate system. DataFrame of x, y, and z coordinates: Interpolates data onto user provided points.
time_index (int) – An integer to pull the time step from the dataset. Default is late time step 1.
intermediate_values (boolean (optional)) – If false the function will return position and turbulent intensity values. If true the function will return position(x,y,z) and values need to calculate turbulent intensity (ucx, uxy, uxz and turkin1) in a Dataframe. Default False.
 Returns
TI_data (Dataframe) – If intermediate_values is true all values are output. If intermediate_values is equal to false only turbulent_intesity and x, y, and z variables are output.
x position in the x direction y position in the y direction waterdepth position in the vertical direction turbulet_intesity turbulent kinetic energy divided by the root
mean squared velocity
turkin1 turbulent kinetic energy ucx velocity in the x direction ucy velocity in the y direction ucz velocity in the vertical direction
 mhkit.river.io.usgs.read_usgs_file(file_name)[source]
Reads a USGS JSON data file (from https://waterdata.usgs.gov/nwis)
 Parameters
file_name (str) – Name of USGS JSON data file
 Returns
data (pandas DataFrame) – Data indexed by datetime with columns named according to the parameter’s variable description
 mhkit.river.io.usgs.request_usgs_data(station, parameter, start_date, end_date, data_type='Daily', proxy=None, write_json=None)[source]
Loads USGS data directly from https://waterdata.usgs.gov/nwis using a GET request
The request URL prints to the screen.
 Parameters
station (str) – USGS station number (e.g. ‘08313000’)
parameter (str) – USGS paramter ID (e.g. ‘00060’ for Discharge, cubic feet per second)
start_date (str) – Start date in the format ‘YYYYMMDD’ (e.g. ‘20180101’)
end_date (str) – End date in the format ‘YYYYMMDD’ (e.g. ‘20181231’)
data_type (str) – Data type, options include ‘Daily’ (return the mean daily value) and ‘Instantaneous’.
proxy (dict or None) – To request data from behind a firewall, define a dictionary of proxy settings, for example {“http”: ‘localhost:8080’}
write_json (str or None) – Name of json file to write data
 Returns
data (pandas DataFrame) – Data indexed by datetime with columns named according to the parameter’s variable description
Resource
The resource submodule uses discharge data to compute exeedance probability, velocity, and power. The module also contains functions to compute the Froude number and to fit a polynomial to a series of points. The polynomial is used to estimate the relationship between discharge and velocity or velocity and power at an individual turbine.
Calculate the Froude Number of the river, channel or duct flow, to check subcritical flow assumption (if Fr <1). 

Calculates the exceedance probability 

Returns a polynomial fit for y given x of order n with an Rsquared score of the fit 

Calculates velocity given discharge data and the relationship between discharge and velocity at an individual turbine 

Calculates power given velocity data and the relationship between velocity and power from an individual turbine 

Returns the energy produced for a given time period provided exceedence probability and power. 
 mhkit.river.resource.Froude_number(v, h, g=9.80665)[source]
Calculate the Froude Number of the river, channel or duct flow, to check subcritical flow assumption (if Fr <1).
 Parameters
v (int/float) – Average velocity [m/s].
h (int/float) – Mean hydrolic depth float [m].
g (int/float) – Gravitational acceleration [m/s2].
 Returns
Fr (float) – Froude Number of the river [unitless].
 mhkit.river.resource.exceedance_probability(D)[source]
Calculates the exceedance probability
 Parameters
D (pandas Series) – Data indexed by time [datetime or s].
 Returns
F (pandas DataFrame) – Exceedance probability [unitless] indexed by time [datetime or s]
 mhkit.river.resource.polynomial_fit(x, y, n)[source]
Returns a polynomial fit for y given x of order n with an Rsquared score of the fit
 Parameters
x (numpy array) – x data for polynomial fit.
y (numpy array) – y data for polynomial fit.
n (int) – order of the polynomial fit.
 Returns
polynomial_coefficients (numpy polynomial) – List of polynomial coefficients
R2 (float) – Polynomical fit coeffcient of determination
 mhkit.river.resource.discharge_to_velocity(D, polynomial_coefficients)[source]
Calculates velocity given discharge data and the relationship between discharge and velocity at an individual turbine
 Parameters
D (pandas Series) – Discharge data [m3/s] indexed by time [datetime or s]
polynomial_coefficients (numpy polynomial) – List of polynomial coefficients that discribe the relationship between discharge and velocity at an individual turbine
 Returns
V (pandas DataFrame) – Velocity [m/s] indexed by time [datetime or s]
 mhkit.river.resource.velocity_to_power(V, polynomial_coefficients, cut_in, cut_out)[source]
Calculates power given velocity data and the relationship between velocity and power from an individual turbine
 Parameters
V (pandas Series) – Velocity [m/s] indexed by time [datetime or s]
polynomial_coefficients (numpy polynomial) – List of polynomial coefficients that discribe the relationship between velocity and power at an individual turbine
cut_in (int/float) – Velocity values below cut_in are not used to compute P
cut_out (int/float) – Velocity values above cut_out are not used to compute P
 Returns
P (pandas DataFrame) – Power [W] indexed by time [datetime or s]
 mhkit.river.resource.energy_produced(P, seconds)[source]
Returns the energy produced for a given time period provided exceedence probability and power.
 Parameters
P (pandas Series) – Power [W] indexed by time [datetime or s]
seconds (int or float) – Seconds in the time period of interest
 Returns
E (float) – Energy [J] produced in the given time frame
Performance
The performance submodule contains functions to compute equivalent diameter and capture area for circular, ducted, rectangular, adn multiple circular devices. A circular device is a vertical axis water turbine (VAWT). A rectangular device is a horizontal axis water turbine. A ducted device is an enclosed VAWT. A multiplecircular devices is a device with multiple VAWTs per device. The performance module also includes functions for calculating a turbine coeffcient of power and tip speed ratio.
Calculates the equivalent diameter and projected capture area of a circular turbine 

Calculates the equivalent diameter and projected capture area of a ducted turbine 

Calculates the equivalent diameter and projected capture area of a retangular turbine 

Calculates the equivalent diameter and projected capture area of a multiple circular turbine 

Function used to calculate the tip speed ratio (TSR) of a MEC device with rotor 

Function that calculates the power coefficient of MEC device 
 mhkit.river.performance.circular(diameter)[source]
Calculates the equivalent diameter and projected capture area of a circular turbine
 Parameters
diameter (int/float) – Turbine diameter [m]
 Returns
equivalent_diameter (float) – Equivalent diameter [m]
projected_capture_area (float) – Projected capture area [m^2]
 mhkit.river.performance.ducted(duct_diameter)[source]
Calculates the equivalent diameter and projected capture area of a ducted turbine
 Parameters
duct_diameter (int/float) – Duct diameter [m]
 Returns
equivalent_diameter (float) – Equivalent diameter [m]
projected_capture_area (float) – Projected capture area [m^2]
 mhkit.river.performance.rectangular(h, w)[source]
Calculates the equivalent diameter and projected capture area of a retangular turbine
 Parameters
h (int/float) – Turbine height [m]
w (int/float) – Turbine width [m]
 Returns
equivalent_diameter (float) – Equivalent diameter [m]
projected_capture_area (float) – Projected capture area [m^2]
 mhkit.river.performance.multiple_circular(diameters)[source]
Calculates the equivalent diameter and projected capture area of a multiple circular turbine
 Parameters
diameters (list) – List of device diameters [m]
 Returns
equivalent_diameter (float) – Equivalent diameter [m]
projected_capture_area (float) – Projected capture area [m^2]
 mhkit.river.performance.tip_speed_ratio(rotor_speed, rotor_diameter, inflow_speed)[source]
Function used to calculate the tip speed ratio (TSR) of a MEC device with rotor
 Parameters
rotor_speed (numpy array) – Rotor speed [revolutions per second]
rotor_diameter (float/int) – Diameter of rotor [m]
inflow_speed (numpy array) – Velocity of inflow condition [m/s]
 Returns
TSR (numpy array) – Calculated tip speed ratio (TSR)
 mhkit.river.performance.power_coefficient(power, inflow_speed, capture_area, rho)[source]
Function that calculates the power coefficient of MEC device
 Parameters
power (numpy array) – Power output signal of device after losses [W]
inflow_speed (numpy array) – Speed of inflow [m/s]
capture_area (float/int) – Projected area of rotor normal to inflow [m^2]
rho (float/int) – Density of environment [kg/m^3]
 Returns
Cp (numpy array) – Power coefficient of device []
Graphics
The graphics submodule contains functions to plot river resource data and related metrics.
Plots discharge vs exceedance probability as a Flow Duration Curve (FDC) 

Plots velocity vs exceedance probability as a Velocity Duration Curve (VDC) 

Plots power vs exceedance probability as a Power Duration Curve (PDC) 

Plots discharge timeseries 

Plots discharge vs velocity data along with the polynomial fit 

Plots velocity vs power data along with the polynomial fit 
 mhkit.river.graphics.plot_flow_duration_curve(D, F, label=None, ax=None)[source]
Plots discharge vs exceedance probability as a Flow Duration Curve (FDC)
 Parameters
D (arraylike) – Discharge [m/s] indexed by time
F (arraylike) – Exceedance probability [unitless] indexed by time
label (string) – Label to use in the legend
ax (matplotlib axes object) – Axes for plotting. If None, then a new figure with a single axes is used.
 Returns
ax (matplotlib pyplot axes)
 mhkit.river.graphics.plot_velocity_duration_curve(V, F, label=None, ax=None)[source]
Plots velocity vs exceedance probability as a Velocity Duration Curve (VDC)
 Parameters
V (arraylike) – Velocity [m/s] indexed by time
F (arraylike) – Exceedance probability [unitless] indexed by time
label (string) – Label to use in the legend
ax (matplotlib axes object) – Axes for plotting. If None, then a new figure with a single axes is used.
 Returns
ax (matplotlib pyplot axes)
 mhkit.river.graphics.plot_power_duration_curve(P, F, label=None, ax=None)[source]
Plots power vs exceedance probability as a Power Duration Curve (PDC)
 Parameters
P (arraylike) – Power [W] indexed by time
F (arraylike) – Exceedance probability [unitless] indexed by time
label (string) – Label to use in the legend
ax (matplotlib axes object) – Axes for plotting. If None, then a new figure with a single axes is used.
 Returns
ax (matplotlib pyplot axes)
 mhkit.river.graphics.plot_discharge_timeseries(Q, label=None, ax=None)[source]
Plots discharge timeseries
 Parameters
Q (arraylike) – Discharge [m3/s] indexed by time
label (string) – Label to use in the legend
ax (matplotlib axes object) – Axes for plotting. If None, then a new figure with a single axes is used.
 Returns
ax (matplotlib pyplot axes)
 mhkit.river.graphics.plot_discharge_vs_velocity(D, V, polynomial_coeff=None, label=None, ax=None)[source]
Plots discharge vs velocity data along with the polynomial fit
 Parameters
D (pandas Series) – Discharge [m/s] indexed by time
V (pandas Series) – Velocity [m/s] indexed by time
polynomial_coeff (numpy polynomial) – Polynomial coefficients, which can be computed using river.resource.polynomial_fit. If None, then the polynomial fit is not included int the plot.
ax (matplotlib axes object) – Axes for plotting. If None, then a new figure with a single axes is used.
 Returns
ax (matplotlib pyplot axes)
 mhkit.river.graphics.plot_velocity_vs_power(V, P, polynomial_coeff=None, label=None, ax=None)[source]
Plots velocity vs power data along with the polynomial fit
 Parameters
V (pandas Series) – Velocity [m/s] indexed by time
P (pandas Series) – Power [W] indexed by time
polynomial_coeff (numpy polynomial) – Polynomial coefficients, which can be computed using river.resource.polynomial_fit. If None, then the polynomial fit is not included int the plot.
ax (matplotlib axes object) – Axes for plotting. If None, then a new figure with a single axes is used.
 Returns
ax (matplotlib pyplot axes)