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
read_usgs_file	Reads a USGS JSON data file (from https://waterdata.usgs.gov/nwis) into a structure
request_usgs_file	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
Froude_number	Calculate the Froude Number of the river, channel or duct flow, to check subcritical flow assumption (if Fr <1).
polynomial_fit	Returns a polynomial fit for y given x of order n with an R-squared score of the fit
exceedance_probability	Calculates the exceedance probability
discharge_to_velocity	Calculates velocity given discharge data and the relationship between discharge and velocity at an individual turbine
velocity_to_power	Calculates power given velocity data and the relationship between velocity and power from an individual turbine
energy_produced	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 turbine

• cut_in (float) – Velocity values below cut_in are not used to compute P

• cut_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 multiple-circular 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
circular	Calculates the equivalent diameter and projected capture area of a circular turbine
ducted	Calculates the equivalent diameter and projected capture area of a ducted turbine
multiple_circular	Calculates the equivalent diameter and projected capture area of a multiple circular turbine
rectangular	Calculates the equivalent diameter and projected capture area of a retangular turbine
tip_speed_ratio	Calculates the tip speed ratio (TSR) of a MEC device with rotor
power_coefficient	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
plot_discharge_timeseries	Plots discharge vs time
plot_discharge_vs_velocity	Plots discharge vs velocity
plot_flow_duration_curve	Plots discharge vs exceedance probability as a Flow Duration Curve (FDC)
plot_power_duration_curve	Plots power vs exceedance probability as a Flow Duration Curve (FDC)
plot_velocity_duration_curve	Plots velocity vs exceedance probability as a Flow Duration Curve (FDC)
plot_velocity_vs_power	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)