River Module
The river module contains a set of functions to calculate quantities of interest for river energy converters (REC).
Note
The names of the functions below are of the convention path.path.function
. Only the function name is used when calling the function in MATLAB. For example, to call on mhkit.river.io.request_usgs_data
simply use request_usgs_data
.
IO
The io submodule contains the following functions to load USGS Discharge data into structures.
Functions 
Description 


Reads a USGS JSON data file (from https://waterdata.usgs.gov/nwis) into a structure 

Loads USGS data directly from https://waterdata.usgs.gov/nwis using a GET request into a structure 
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.
Functions 
Description 


Calculate the Froude Number of the river, channel or duct flow, to check subcritical flow assumption (if Fr <1). 

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

Calculates the exceedance probability 

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, varargin)
Calculate the Froude Number of the river, channel or duct flow, to check subcritical flow assumption (if Fr <1).
 Parameters
v (
float
) – Average Velocity [m/s].h (
float
) – Mean hydrolic depth float [m].g (
float (optional)
) – gravitational acceleration [m/s2].
 Returns
Fr (float) – Froude Number of the river [unitless].
 mhkit.river.resource.exceedance_probability(Q)
Calculates the exceedance probability
 Parameters
Q (
Discharge data [m3/s]
) –Pandas dataframe indexed by time [datetime or s]
To make a pandas data frame from user supplied frequency and spectra use py.mhkit_python_utils.pandas_dataframe.timeseries_to_pandas(timeseries,time,x)
OR
structure of form:
Q.Discharge
Q.time
 Returns
F (Structure)
F.F: Exceedance probability [unitless]
F.time: time [epoch time (s)]
 mhkit.river.resource.energy_produced(P, seconds)
Returns the energy produced for a given time period provided exceedence probability and power.
 Parameters
P (
Power [W]
) –Pandas dataframe indexed by time [datetime or s]:
To make a pandas data frame from user supplied frequency and spectra use py.mhkit_python_utils.pandas_dataframe.timeseries_to_pandas(timeseries,time,x)
OR
structure of form:
P.P
P.time [s]
seconds (
float
) – seconds in the time period of interest
 Returns
E (Structure)
P.P: Power [W]
P.time: epoch time [s]
 mhkit.river.resource.discharge_to_velocity(Q, polynomial_coefficients)
Calculates velocity given discharge data and the relationship between discharge and velocity at an individual turbine
 Parameters
Q (
Discharge data [m3/s]
) –Pandas dataframe indexed by time [datetime or s]:
To make a pandas data frame from user supplied frequency and spectra use py.mhkit_python_utils.pandas_dataframe.timeseries_to_pandas(timeseries,time,x)
OR
structure of form:
Q.Discharge
Q.time
polynomial_coefficients (
numpy polynomial
) – List of polynomial coefficients that discribe the relationship between discharge and velocity at an individual turbine
 Returns
V (Structure)
V.V: Velocity [m/s]
V.time: time [datetime or s]
 mhkit.river.resource.polynomial_fit(x, y, n)
Returns a polynomial fit for y given x of order n.
 Parameters
x (
array
) – x data for polynomial fit.y (
array
) – y data for polynomial fit.n (
int
) – order of the polynomial fit.
 Returns
poly (structure)
poly.coef: polynomial coefficients
poly.fit: fit coefficients
 mhkit.river.resource.velocity_to_power(V, polynomial_coefficients, cut_in, cut_out)
Calculates power given velocity data and the relationship between velocity and power from an individual turbine
 Parameters
V (
Velocity [m/s]
) –Pandas dataframe indexed by time [datetime or s]
To make a pandas data frame from user supplied frequency and spectra use py.mhkit_python_utils.pandas_dataframe.timeseries_to_pandas(timeseries,time,x)
OR
structure of form:
V.V: Velocity [m/s]
V.time: time [datetime or s]
polynomial_coefficients (
vector
) – vector of polynomial coefficients that discribe the relationship between velocity and power at an individual turbinecut_in (
float
) – Velocity values below cut_in are not used to compute Pcut_out (
float
) – Velocity values above cut_out are not used to compute P
 Returns
p (Structure)
P.P: Power [W]
P.time: epoch time [s]
Performance
The performance submodule contains functions to compute equivalent diameter and capture area for circular, ducted, rectangular, and 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. This submodule also contains functions for computing tip speed ratio and the power coefficient from blade/rotor type devices.
Functions 
Description 


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 multiple circular turbine 

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

Calculates the tip speed ratio (TSR) of a MEC device with rotor 

Calculates the calculates the power coefficient of MEC device 
 mhkit.river.performance.power_coefficient(power, inflow_speed, capture_area, rho)
Function that calculates the power coefficient of MEC device
 Parameters
power (
vector
) – Power output signal of device after losses [W]inflow_speed (
vector
) – Velocity of inflow condition [m/s]capture_area (
double or int
) – Projected area of rotor normal to inflow [m^2]rho (
double or int
) – Density of environment [kg/m^3]
 Returns
Cp (vector) – Power coefficient of device []
 mhkit.river.performance.tip_speed_ratio(rotor_speed, rotor_diameter, inflow_speed)
Function used to calculate the tip speed ratio (TSR) of a MEC device with rotor
 Parameters
rotor_speed (
vector
) – Rotor Speed [rps]rotor_diameter (
double or int
) – diameter f rotor [m]inflow_speed (
vector
) – Velocity of inflow condition [m/s]
 Returns
TSR (vector) – Calculated tip speed ratio (TSR)
 mhkit.river.performance.circular(diameter)
Calculates the equivalent diameter and projected capture area of a circular turbine
 Parameters
diameter (
float
) – Turbine diameter [m] Returns
D_E (float) – Equivalent diameter [m]
projected_capture_area (float) – Projected capture area [m^2]
 mhkit.river.performance.rectangular(h, w)
Calculates the equivalent diameter and projected capture area of a retangular turbine
 Parameters
h (
float
) – Turbine height [m]w (
float
) – Turbine width [m]
 Returns
D_E (float) – Equivalent diameter [m]
projected_capture_area (float) – Projected capture area [m^2]
 mhkit.river.performance.multiple_circular(diameters)
Calculates the equivalent diameter and projected capture area of a multiple circular turbine
 Parameters
diameters (
array or vector
) – vector of device diameters [m] Returns
D_E (float) – Equivalent diameter [m]
projected_capture_area (float) – Projected capture area [m^2]
 mhkit.river.performance.ducted(diameter)
Calculates the equivalent diameter and projected capture area of a ducted turbine
 Parameters
diameter (
float
) – ducted diameter [m] Returns
D_E (float) – Equivalent diameter [m]
projected_capture_area (float) – Projected capture area [m^2]
Graphics
The graphics submodule contains functions to plot river data and related metrics. The functions are designed to work in parallel with the resource
submodule.
Functions 
Description 


Plots discharge vs time 

Plots discharge vs velocity 

Plots discharge vs exceedance probability as a Flow Duration Curve (FDC) 

Plots power vs exceedance probability as a Flow Duration Curve (FDC) 

Plots velocity vs exceedance probability as a Flow Duration Curve (FDC) 

Plots velocity vs power along with a polynomial fit 
 mhkit.river.graphics.plot_power_duration_curve(P, F, options)
Plots power vs exceedance probability as a Flow Duration Curve (FDC)
 Parameters
P (
array
) – Power [W]F (
array
) – Exceedance probability [unitless]title (
string (Optional)
) – title for the plot to call: plot_power_duration_curve(P,F,”title”,title)savepath (
string (optional)
) – path and filename to save figure. to call: plot_power_duration_curve(P,F,”savepath”,savepath)
 Returns
figure (plot of power duration curve)
 mhkit.river.graphics.plot_discharge_timeseries(Q, options)
Plots discharge vs time
 Parameters
Q (
structure
) –Q.Discharge: Discharge [m/s]
Q.time: epoch time [s]
title (
string (optional)
) – title for the plot to call: plot_discharge_timeseries(Q,”title”,title)savepath (
string (optional)
) – path and filename to save figure. to call: plot_discharge_timeseries(Q,”savepath”,savepath)
 Returns
figure (Plot of discharge vs. time)
 mhkit.river.graphics.plot_velocity_vs_power(V, P, options)
Plots velocity vs power along with a polynomial fit
 Parameters
V (
array
) – Velocity [m/s]P (
array
) – Power [W]title (
string (optional)
) – title for the plot to call: plot_velocity_vs_power(P,F,”title”,title)savepath (
string (optional)
) – path and filename to save figure. to call: plot_velocity_vs_power(P,F,”savepath”,savepath)polynomial_coeff (
array (optional)
) – polynomial coefficients which can be computed from polynomial_fit.m. Expects poly.coef to call: plot_velocity_vs_power(P,F,”polynomial_coeff”,polynomial_coeff)
 Returns
figure (plot of velocity vs. power)
 mhkit.river.graphics.plot_discharge_vs_velocity(Q, V, options)
Plots discharge vs velocity
 Parameters
Q (
array
) – Discharge [m/s]V (
array
) – Velocity [m/s]title (
string (optional)
) – title for the plot to call: plot_discharge_vs_velocity(Q,V,”title”,title)savepath (
string (optional)
) – path and filename to save figure. to call: plot_discharge_vs_velocity(Q,V,”savepath”,savepath)polynomial_coeff (
array (optional)
) – polynomial coefficients which can be computed from polynomial_fit.m. Expects poly.coef to call: plot_discharge_vs_velocity(Q,V,”polynomial_coeff”,polynomial_coeff)
 Returns
figure (plot of discharge vs. velocity)
 mhkit.river.graphics.plot_velocity_duration_curve(V, F, options)
Plots velocity vs exceedance probability as a Flow Duration Curve (FDC)
 Parameters
V (
array
) – Velocity [m/s]F (
array
) – Exceedance probability [unitless]title (
string (optional)
) – title for the plot to call: plot_velocity_duration_curve(P,F,”title”,title)savepath (
string (optional)
) – path and filename to save figure. to call: plot_velocity_duration_curve(P,F,”savepath”,savepath)
 Returns
figure (plot of velocity vs. exceedance probability)
 mhkit.river.graphics.plot_flow_duration_curve(Q, F, options)
Plots discharge vs exceedance probability as a Flow Duration Curve (FDC)
 Parameters
Q (
array
) – Discharge [m/s]F (
array
) – Exceedance probability [unitless]title (
string (optional)
) – title for the plot to call: plot_flow_duration_curve(Q,F,”title”,title)savepath (
string (optional)
) – path and filename to save figure. to call: plot_flow_duration_curve(Q,F,”savepath”,savepath)
 Returns
figure (plot of discharge vs. exceedance probability)