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.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

mhkit.river.io.request_usgs_data(station, parameter, start_date, end_date, varargin)

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’.

  • proxy (dict or None (optional)) – To request data from behind a firewall, define a dictionary of proxy settings, for example {“http”: ‘localhost:8080’}

  • write_json (str or None (optional)) – Name of json file to write data

Returns

datast (structure)

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

datast.time: datetime

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.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.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.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.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]

Device

The device 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 multiple-circular devices is a device with multiple VAWTs per device.

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
mhkit.river.device.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.device.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]

mhkit.river.device.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.device.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]

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_discharge_timeseries(Q, varargin)

Plots discharge vs time

Parameters

  • Q (structure) –

    Q.Discharge: Discharge [m/s]

    Q.time: epoch time [s]

  • title (string (optional)) – title for the plot

Returns

figure (Plot of discharge vs. time)

mhkit.river.graphics.plot_discharge_vs_velocity(Q, V, varargin)

Plots discharge vs velocity

Parameters

  • Q (array) – Discharge [m/s]

  • V (array) – Velocity [m/s]

  • title – title for the plot

Returns

figure (plot of discharge vs. velocity)

mhkit.river.graphics.plot_flow_duration_curve(Q, F, varargin)

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

Returns

figure (plot of discharge vs. exceedance probability)

mhkit.river.graphics.plot_power_duration_curve(P, F, varargin)

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

Returns

figure (plot of power vs. exceedance probability)

mhkit.river.graphics.plot_velocity_duration_curve(V, F, varargin)

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

Returns

figure (plot of velocity vs. exceedance probability)

mhkit.river.graphics.plot_velocity_vs_power(V, P, varargin)

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

  • polynomial_coeff (array (optional)) – polynomial coefficients which can be computed from polynomial_fit.m. Expects poly.coef

Returns

figure (plot of velocity vs. power)