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
mhkit.river.IO.request_usgs_data(station, parameter, start_date, end_date, options)

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

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 ‘YYYY-MM-DD’ (e.g. ‘2018-01-01’)

  • end_date (str) – End date in the format ‘YYYY-MM-DD’ (e.g. ‘2018-12-31’)

  • data_type (str (optional)) – Data type, options include ‘Daily’ (return the mean daily value) and ‘Instantaneous’. Default = ‘Daily’ to call: request_usgs_data(station,parameter,start_date.end_date,”data_type”,data_type)

  • proxy (None) –

    Parameter is now deprecated. To request data from behind a firewall, configure in MATLAB Preferences by navigating to:

    Home -> Environment -> Preferences

    then:

    MATLAB -> Web -> Use a proxy server to connect to the Internet

    See the following for details:

    https://www.mathworks.com/help/matlab/import_export/proxy.html

  • write_json (str or None (optional)) – Name of json file to write data to call: request_usgs_data(station,parameter,start_date,end_date,”write_json”,write_json)

Returns:

datast (structure)

datast.Data: named according to the parameter’s variable description

datast.time: datetime

datast.units: units for each parameter

mhkit.river.IO.read_usgs_file(file_name)

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

Parameters:

file_name (str) – Name of USGS JSON data file

Returns:

datast (structure)

datast.Data: named according to the parameter’s variable description

datast.time: epoch time [s]

datast.units: units for each parameter

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)