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

delft_3d_calculate_turbulent_intensity

Returns the turbulent intensity percentage for a given data set for the specified points

delft_3d_calculate_unorm

Calculates the root mean squared value given three arrays.

delft_3d_calculate_variable_interpolation

Interpolates multiple variables from the Delft3D onto the same points.

delft_3d_cleanup_turbulent_kinetic_energy

Cleans up the turbulent kinetic energy values based on a threshold.

delft_3d_convert_time

Converts timestamps into a usable format.

delft_3d_create_points

Turns three coordinate inputs into a single output struct of points

delft_3d_get_all_data_points

Returns all data points for a specific variable at a given time index from a Delft 3D netCDF object.

delft_3d_get_all_time

Returns all time values from a Delft 3D netCDF object.

delft_3d_get_keys

Returns a struct of the key/values of a Delft 3D netCDF object.

delft_3d_get_layer_data

Returns layer data from a Delft 3D netCDF object.

delft_3d_index_to_seconds

Returns the time in seconds corresponding to the given index in the Delft3D dataset.

delft_3d_interpolate_to_centerline

Interpolates data to points along a centerline.

delft_3d_open_netcdf

Opens a Delft 3D netCDF file as a python netCDF4 object

delft_3d_seconds_to_index

Returns the index corresponding to the given number of seconds elapsed in the Delft3D dataset.
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, 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.delft_3d.delft_3d_calculate_turbulent_intensity(delft_3d_py_object, points, intermediate_values)

Returns the turbulent intensity percentage for a given data set for the specified points.

Parameters:

  • delft_3d_py_object (py.netCDF4._netCDF4.Dataset) – A netCDF python object, created with delft_3d_open_netcdf

  • points (struct or string or DataFrame) –

    Points to interpolate data onto.

    ’cells’: interpolates all data onto velocity coordinate system (Default). ‘faces’: interpolates all data onto the TKE coordinate system. DataFrame of x, y, and z coordinates: Interpolates data onto user provided points.

  • intermediate_values (bool (optional)) – If false, the function will return position and turbulent intensity values. If true, the function will return position (x, y, z) and values needed to calculate turbulent intensity (ucx, ucy, uxz, and turkin1) in a DataFrame. Default is false.

Returns:

result_struct (struct) – A struct containing the calculated turbulent intensity data.

mhkit.river.IO.delft_3d.delft_3d_calculate_unorm(x, y, z)

Calculates the root mean squared value given three arrays.

Parameters:

  • x (array) – One input for the root mean squared calculation (e.g., x velocity).

  • y (array) – One input for the root mean squared calculation (e.g., y velocity).

  • z (array) – One input for the root mean squared calculation (e.g., z velocity).

Returns:

result (array) – The root mean squared of x, y, and z.

Example

If the inputs are [1,2,3], [4,5,6], and [7,8,9], the code takes the corresponding value from each array and calculates the root mean squared. The resulting output is [8.1240384, 9.64365076, 11.22497216].

mhkit.river.IO.delft_3d.delft_3d_calculate_variable_interpolation(delft_3d_py_object, variables, points, edges)

Interpolates multiple variables from the Delft3D onto the same points.

Parameters:

  • delft_3d_py_object (py.netCDF4._netCDF4.Dataset) – A netCDF python object, created with delft_3d_open_netcdf

  • variables (cell array of strings) – Name of variables to interpolate, e.g. ‘turkin1’, ‘ucx’, ‘ucy’, and ‘ucz’. The full list can be found using “data.variables.keys()” in the console.

  • points (string or struct or DataFrame) –

    The points to interpolate data onto.

    ’cells’: interpolates all data onto the Delft3D cell coordinate system (Default) ‘faces’: interpolates all data onto the Delft3D face coordinate system DataFrame of x, y, and waterdepth coordinates: Interpolates data onto user provided points. Can be created with create_points function.

  • edges (string, optional) – If edges is set to ‘nearest’, the code will fill in NaN values with nearest interpolation. Otherwise, only linear interpolation will be used.

Returns:

result_struct (struct) – A struct containing the interpolated variables on specified grid points saved under the input variable names and the x, y, and waterdepth coordinates of those points.

mhkit.river.IO.delft_3d.delft_3d_cleanup_turbulent_kinetic_energy(input, threshold)

Cleans up the turbulent kinetic energy values based on a threshold.

Parameters:

  • input (numeric array) – Array of turbulent kinetic energy values.

  • threshold (numeric) – Threshold value for cleaning up the turbulent kinetic energy values.

Returns:

result (numeric) – The cleaned-up turbulent kinetic energy values.

mhkit.river.IO.delft_3d.delft_3d_convert_time(delft_3d_py_object, seconds_run)

Returns

Parameters:

  • delft_3d_py_object (py.netCDF4._netCDF4.Dataset) – A netCDF python object, created with delft_3d_open_netcdf

  • seconds_run (number) – Time index

Returns:

result (number) – The closest time index

mhkit.river.IO.delft_3d.delft_3d_create_points(x, y, waterdepth)

Turns three coordinate inputs into a single output struct of points.

Parameters:

  • x (numeric array or number) – x values to create points.

  • y (numeric array or number) – y values to create points.

  • waterdepth (numeric array or number) – waterdepth values to create points.

Returns:

result (struct) – A struct containing the points with fields x, y, waterdepth, and df (python output pandas DataFrame).

mhkit.river.IO.delft_3d.delft_3d_get_all_data_points(delft_3d_py_object, variable, time_index)

Returns all data points for a specific variable at a given time index from a Delft 3D netCDF object.

Parameters:

  • delft_3d_py_object (py.netCDF4._netCDF4.Dataset) – A netCDF python object, created with delft_3d_open_netcdf

  • variable (string) – Variable in the Delft3D output

  • time_index (int) – Index of the time variable. Points will be selected at this time index

Returns:

result (struct) – A struct containing the data points for the specified variable at the given time index from the Delft 3D netCDF object. - result.time: An array of time values - result.df: A Python dataframe the output data in the original format - result.*: Additional data points at the selected variable and time_index

mhkit.river.IO.delft_3d.delft_3d_get_all_time(delft_3d_py_object)

Returns all time values from a Delft 3D netCDF object.

Parameters:

delft_3d_py_object (py.netCDF4._netCDF4.Dataset) – A netCDF python object, created with delft_3d_open_netcdf

Returns:

result (double) – An array containing all time values from the Delft 3D netCDF object.

mhkit.river.IO.delft_3d.delft_3d_get_keys(delft_3d_py_object)

Returns a struct of the key/values of a Delft 3D netCDF object.

Parameters:

delft_3d_py_object (py.netCDF4._netCDF4.Dataset) – A netCDF python object, created with delft_3d_open_netcdf

Returns:

result (struct) – A struct containing the keys and their corresponding values from the Delft 3D netCDF object.

mhkit.river.IO.delft_3d.delft_3d_get_layer_data(delft_3d_py_object, variable, layer)

Returns layer data from a Delft 3D netCDF object.

Parameters:

  • delft_3d_py_object (py.netCDF4._netCDF4.Dataset) – A netCDF python object, created with delft_3d_open_netcdf

  • variable (string) – Variable in the Delft3D output

  • layer (int) – Layer index

Returns:

result_struct (struct) – A struct containing the layer data with fields corresponding to the DataFrame columns, including the DataFrame itself stored as ‘df’.

mhkit.river.IO.delft_3d.delft_3d_index_to_seconds(delft_3d_py_object, index)

Returns the time in seconds corresponding to the given index in the Delft3D dataset.

Parameters:

  • delft_3d_py_object (py.netCDF4._netCDF4.Dataset) – A netCDF python object, created with delft_3d_open_netcdf

  • index (numeric) – The index for which to retrieve the time in seconds.

Returns:

result (numeric) – The time in seconds.

mhkit.river.IO.delft_3d.delft_3d_interpolate_to_centerline(points, values, xi)

Interpolates data to points along a centerline.

Parameters:

  • points (2-D ndarray of floats) – Data point coordinates

  • values (ndarray of float) – Data values

  • xi (2-D ndarray of floats) – Points at which to interpolate data

Returns:

result (ndarray) – Array of interpolated values

mhkit.river.IO.delft_3d.delft_3d_open_netcdf(filename)

Opens a Delft 3D netCDF file as a python netCDF4 object

Parameters:

filename (str) – The name of the netCDF file to open.

Returns:

result (py.netCDF4._netCDF4.Dataset) – The object representing the opened netCDF dataset.

mhkit.river.IO.delft_3d.delft_3d_seconds_to_index(delft_3d_py_object, seconds_elapsed)

Returns the index corresponding to the given number of seconds elapsed in the Delft3D dataset.

Parameters:

  • delft_3d_py_object (py.netCDF4._netCDF4.Dataset) – A netCDF python object, created with delft_3d_open_netcdf

  • seconds_elapsed (numeric) – The number of seconds elapsed.

Returns:

result (numeric) – The calculated index.

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

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, 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_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_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)

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_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_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)