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

`read_usgs_file`	Reads a USGS JSON data file (from https://waterdata.usgs.gov/nwis)
`request_usgs_data`	Loads USGS data directly from https://waterdata.usgs.gov/nwis using a GET request

mhkit.river.io.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.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 ‘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) – 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.

`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

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

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

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.

`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
`rectangular`	Calculates the equivalent diameter and projected capture area of a retangular turbine
`multiple_circular`	Calculates the equivalent diameter and projected capture area of a multiple circular turbine

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

Graphics¶

The graphics submodule contains functions to plot river resource data and related metrics.

`plot_flow_duration_curve`	Plots discharge vs exceedance probability as a Flow Duration Curve (FDC)
`plot_velocity_duration_curve`	Plots velocity vs exceedance probability as a Velocity Duration Curve (VDC)
`plot_power_duration_curve`	Plots power vs exceedance probability as a Power Duration Curve (PDC)
`plot_discharge_timeseries`	Plots discharge time-series
`plot_discharge_vs_velocity`	Plots discharge vs velocity data along with the polynomial fit
`plot_velocity_vs_power`	Plots velocity vs power data along with the polynomial fit

mhkit.river.graphics.plot_discharge_timeseries(Q, label=None, ax=None)[source]¶

Plots discharge time-series

Parameters

Q (array-like) – 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_flow_duration_curve(D, F, label=None, ax=None)[source]¶

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

Parameters

D (array-like) – Discharge [m/s] indexed by time
F (array-like) – 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 (array-like) – Power [W] indexed by time
F (array-like) – 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 (array-like) – Velocity [m/s] indexed by time
F (array-like) – 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_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)