River Module

The river module contains a set of functions to calculate quantities of interest for river energy converters (REC).

IO

The io submodule contains the following functions to load USGS discharge and Delft3D data.

USGS

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.usgs.read_usgs_file(file_name, to_pandas=True)

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

Parameters:

• file_name (str) – Name of USGS JSON data file

• to_pandas (bool (optional)) – Flag to output pandas instead of xarray. Default = True.

Returns:

data (pandas DataFrame or xarray Dataset) – Data indexed by datetime with columns named according to the parameter’s variable description

mhkit.river.io.usgs.request_usgs_data(station, parameter, start_date, end_date, data_type='Daily', proxy=None, write_json=None, clear_cache=False, to_pandas=True)

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

• clear_cache (bool) – If True, the cache for this specific request will be cleared.

• to_pandas (bool (optional)) – Flag to output pandas instead of xarray. Default = True.

Returns:

data (pandas DataFrame or xarray Dataset) – Data indexed by datetime with columns named according to the parameter’s variable description

D3D

get_all_time	Returns all of the time stamps from a D3D simulation passed to the function as a NetCDF object (data)
index_to_seconds	The function will return 'seconds_run' if passed a 'time_index'
seconds_to_index	The function will return the nearest 'time_index' in the data if passed an integer number of 'seconds_run'
get_layer_data	Get variable data from the NetCDF4 object at a specified layer and timestep.
create_points	Generate a Dataset of points from combinations of input coordinates.
variable_interpolation	Interpolate multiple variables from the Delft3D onto the same points.
get_all_data_points	Get data points for a passed variable for all layers at a specified time from the Delft3D NetCDF4 object by iterating over the get_layer_data function.
turbulent_intensity	Calculate the turbulent intensity percentage for a given data set for the specified points.

mhkit.river.io.d3d.get_all_time(data)

Returns all of the time stamps from a D3D simulation passed to the function as a NetCDF object (data)

Parameters:

data (NetCDF4 object) – A NetCDF4 object that contains spatial data, e.g. velocity or shear stress generated by running a Delft3D model.

Returns:

seconds_run (array) – Returns an array of integers representing the number of seconds after the simulation started and that the data object contains a snapshot of simulation conditions at that time.

mhkit.river.io.d3d.index_to_seconds(data, time_index)

The function will return ‘seconds_run’ if passed a ‘time_index’

Parameters:

• data (NetCDF4 object) – A NetCDF4 object that contains spatial data, e.g. velocity or shear stress, generated by running a Delft3D model.

• time_index (int) – A positive integer to pull the time index from the dataset. 0 being closest to time 0. Default is last time index -1.

Returns:

seconds_run (int, float) – The ‘seconds_run’ is the seconds corresponding to the ‘time_index’ increments.

mhkit.river.io.d3d.seconds_to_index(data, seconds_run)

The function will return the nearest ‘time_index’ in the data if passed an integer number of ‘seconds_run’

Parameters:

• data (NetCDF4 object) – A NetCDF4 object that contains spatial data, e.g. velocity or shear stress, generated by running a Delft3D model.

• seconds_run (int, float) – A positive integer or float that represents the amount of time in seconds passed since starting the simulation.

Returns:

time_index (int) – The ‘time_index’ is a positive integer starting from 0 and incrementing until in simulation is complete.

mhkit.river.io.d3d.get_layer_data(data, variable, layer_index=-1, time_index=-1, to_pandas=True)

Get variable data from the NetCDF4 object at a specified layer and timestep. If the data is 2D the layer_index is ignored.

Parameters:

• data (NetCDF4 object) – A NetCDF4 object that contains spatial data, e.g. velocity or shear stress, generated by running a Delft3D model.

• variable (string) – Delft3D outputs many vairables. The full list can be found using “data.variables.keys()” in the console.

• layer_index (int) – An integer to pull out a layer from the dataset. 0 being closest to the surface. Default is the bottom layer, found with input -1.

• time_index (int) – An integer to pull the time index from the dataset. 0 being closest to the start time. Default is last time index, found with input -1.

• to_pandas (bool (optional)) – Flag to output pandas instead of xarray. Default = True.

Returns:

layer_data (pd.DataFrame or xr.Dataset) – Dataset with columns of “x”, “y”, “waterdepth”, and “waterlevel” location of the specified layer, variable values “v”, and the “time” the simulation has run. The waterdepth is measured from the water surface and the “waterlevel” is the water level diffrencein meters from the zero water level.

mhkit.river.io.d3d.create_points(x, y, waterdepth, to_pandas=True)

Generate a Dataset of points from combinations of input coordinates.

This function accepts three inputs and combines them to generate a Dataset of points. The inputs can be: - 3 points - 2 points and 1 array - 1 point and 2 arrays - 3 arrays (x and y must have the same size)

For 3 points or less, every combination will be in the output. For 3 arrays, x and y are treated as coordinate pairs and combined with each value from the waterdepth array.

Parameters:

• x (int, float, array-like) – X values (longitude) for the points.

• y (int, float, array-like) – Y values (latitude) for the points.

• waterdepth (int, float, array-like) – Waterdepth values for the points.

• to_pandas (bool (optional)) – Flag to output pandas instead of xarray. Default = True.

Returns:

points (xr.Dataset or pd.DataFrame) – A Dataset with columns ‘x’, ‘y’, and ‘waterdepth’ representing the generated points.

Example

2 arrays and 1 point: >>> x = np.array([1, 2]) >>> y = np.array([3, 4, 5]) >>> waterdepth = 6 >>> create_points(x, y, waterdepth)

x y waterdepth

0 1.0 3.0 6.0 1 2.0 3.0 6.0 2 1.0 4.0 6.0 3 2.0 4.0 6.0 4 1.0 5.0 6.0 5 2.0 5.0 6.0

3 arrays (x and y must have the same length): >>> x = np.array([1, 2, 3]) >>> y = np.array([4, 5, 6]) >>> waterdepth = np.array([1, 2]) >>> create_points(x, y, waterdepth)

x y waterdepth

0 1.0 4.0 1.0 1 2.0 5.0 1.0 2 3.0 6.0 1.0 3 1.0 4.0 2.0 4 2.0 5.0 2.0 5 4.0 6.0 2.0

mhkit.river.io.d3d.variable_interpolation(data, variables, points='cells', edges='none', x_max_lim=inf, x_min_lim=-inf, y_max_lim=inf, y_min_lim=-inf, to_pandas=True)

Interpolate multiple variables from the Delft3D onto the same points.

Parameters:

• data (NetCDF4 object) – A NetCDF4 object that contains spatial data, e.g. velocity or shear stress generated by running a Delft3D model.

• variables (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, pd.DataFrame, or xr.Dataset) –

  The points to interpolate data onto.

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

• edges (string: 'nearest') – If edges is set to ‘nearest’ the code will fill in nan values with nearest interpolation. Otherwise only linear interpolarion will be used.

• to_pandas (bool (optional)) – Flag to output pandas instead of xarray. Default = True.

Returns:

transformed_data (pd.DataFrame or xr.Dataset) – Variables on specified grid points saved under the input variable names and the x, y, and waterdepth coordinates of those points.

mhkit.river.io.d3d.get_all_data_points(data, variable, time_index=-1, to_pandas=True)

Get data points for a passed variable for all layers at a specified time from the Delft3D NetCDF4 object by iterating over the get_layer_data function.

Parameters:

• data (Netcdf4 object) – A NetCDF4 object that contains spatial data, e.g. velocity or shear stress, generated by running a Delft3D model.

• variable (string) – Delft3D variable. The full list can be of variables can be found using “data.variables.keys()” in the console.

• time_index (int) – An integer to pull the time step from the dataset. Default is last time step, found with the input -1.

• to_pandas (bool (optional)) – Flag to output pandas instead of xarray. Default = True.

Returns:

all_data (xr.Dataset or pd.Dataframe) – Dataframe with columns x, y, waterdepth, waterlevel, variable, and time. The waterdepth is measured from the water surface and the “waterlevel” is the water level diffrence in meters from the zero water level.

mhkit.river.io.d3d.turbulent_intensity(data, points='cells', time_index=-1, intermediate_values=False, to_pandas=True)

Calculate the turbulent intensity percentage for a given data set for the specified points. Assumes variable names: ucx, ucy, ucz and turkin1.

Parameters:

• data (NetCDF4 object) – A NetCDF4 object that contains spatial data, e.g. velocity or shear stress, generated by running a Delft3D model.

• points (string, pd.DataFrame, xr.Dataset) –

  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.

• time_index (int) – An integer to pull the time step from the dataset. Default is late time step -1.

• intermediate_values (boolean (optional)) – If false the function will return position and turbulent intensity values. If true the function will return position(x,y,z) and values need to calculate turbulent intensity (ucx, uxy, uxz and turkin1) in a Dataframe. Default False.

• to_pandas (bool (optional)) – Flag to output pandas instead of xarray. Default = True.

Returns:

TI_data (xr.Dataset or pd.DataFrame) – If intermediate_values is true all values are output. If intermediate_values is equal to false only turbulent_intesity and x, y, and z variables are output.

x- position in the x direction y- position in the y direction waterdepth- position in the vertical direction turbulet_intesity- turbulent kinetic energy divided by the root

mean squared velocity

turkin1- turbulent kinetic energy ucx- velocity in the x direction ucy- velocity in the y direction ucz- velocity in the vertical direction

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).
exceedance_probability	Calculates the exceedance probability
polynomial_fit	Returns a polynomial fit for y given x of order n with an R-squared score of the fit
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 exceedance probability and power.

mhkit.river.resource.Froude_number(v, h, g=9.80665)

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 hydraulic depth float [m].

• g (int/float) – Gravitational acceleration [m/s2].

Returns:

Fr (float) – Froude Number of the river [unitless].

mhkit.river.resource.exceedance_probability(D, dimension='', to_pandas=True)

Calculates the exceedance probability

Parameters:

• D (pandas Series, pandas DataFrame, xarray DataArray, or xarray Dataset) – Discharge indexed by time [datetime or s].

• dimension (string (optional)) – Name of the relevant xarray dimension. If not supplied, defaults to the first dimension. Does not affect pandas input.

• to_pandas (bool (optional)) – Flag to output pandas instead of xarray. Default = True.

Returns:

F (pandas DataFrame or xarray Dataset) – Exceedance probability [unitless] indexed by time [datetime or s]

mhkit.river.resource.polynomial_fit(x, y, n)

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.discharge_to_velocity(D, polynomial_coefficients, dimension='', to_pandas=True)

Calculates velocity given discharge data and the relationship between discharge and velocity at an individual turbine

Parameters:

• D (numpy ndarray, pandas DataFrame, pandas Series, xarray DataArray, or xarray Dataset) – Discharge data [m3/s] indexed by time [datetime or s]

• polynomial_coefficients (numpy polynomial) – List of polynomial coefficients that describe the relationship between discharge and velocity at an individual turbine

• dimension (string (optional)) – Name of the relevant xarray dimension. If not supplied, defaults to the first dimension. Does not affect pandas input.

• to_pandas (bool (optional)) – Flag to output pandas instead of xarray. Default = True.

Returns:

V (pandas DataFrame or xarray Dataset) – Velocity [m/s] indexed by time [datetime or s]

mhkit.river.resource.velocity_to_power(V, polynomial_coefficients, cut_in, cut_out, dimension='', to_pandas=True)

Calculates power given velocity data and the relationship between velocity and power from an individual turbine

Parameters:

• V (numpy ndarray, pandas DataFrame, pandas Series, xarray DataArray, or xarray Dataset) – Velocity [m/s] indexed by time [datetime or s]

• polynomial_coefficients (numpy polynomial) – List of polynomial coefficients that describe 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

• dimension (string (optional)) – Name of the relevant xarray dimension. If not supplied, defaults to the first dimension. Does not affect pandas input.

• to_pandas (bool (optional)) – Flag to output pandas instead of xarray. Default = True.

Returns:

P (pandas DataFrame or xarray Dataset) – Power [W] indexed by time [datetime or s]

mhkit.river.resource.energy_produced(P, seconds)

Returns the energy produced for a given time period provided exceedance probability and power.

Parameters:

• P (numpy ndarray, pandas DataFrame, pandas Series, xarray DataArray, or xarray Dataset) – 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 length of time

Performance

The performance 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. The performance module also includes functions for calculating a turbine coeffcient of power and tip speed ratio.

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
tip_speed_ratio	Function used to calculate the tip speed ratio (TSR) of a MEC device with rotor
power_coefficient	Function that 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 (int/float) – Turbine diameter [m]

Returns:

• equivalent_diameter (float) – Equivalent diameter [m]

• projected_capture_area (float) – Projected capture area [m^2]

mhkit.river.performance.ducted(duct_diameter)

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.performance.rectangular(h, w)

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]

mhkit.river.performance.multiple_circular(diameters)

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.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 (numpy array) – Rotor speed [revolutions per second]

• rotor_diameter (float/int) – Diameter of rotor [m]

• inflow_speed (numpy array) – Velocity of inflow condition [m/s]

Returns:

TSR (numpy array) – Calculated tip speed ratio (TSR)

mhkit.river.performance.power_coefficient(power, inflow_speed, capture_area, rho)

Function that calculates the power coefficient of MEC device

Parameters:

• power (numpy array) – Power output signal of device after losses [W]

• inflow_speed (numpy array) – Speed of inflow [m/s]

• capture_area (float/int) – Projected area of rotor normal to inflow [m^2]

• rho (float/int) – Density of environment [kg/m^3]

Returns:

Cp (numpy array) – Power coefficient of device [-]

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_flow_duration_curve(D, F, label=None, ax=None)

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_velocity_duration_curve(V, F, label=None, ax=None)

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_power_duration_curve(P, F, label=None, ax=None)

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_discharge_timeseries(Q, time_dimension='', label=None, ax=None)

Plots discharge time-series

Parameters:

• Q (array-like) – Discharge [m3/s] indexed by time

• time_dimension (string (optional)) – Name of the xarray dimension corresponding to time. If not supplied, defaults to the first dimension.

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

Plots discharge vs velocity data along with the polynomial fit

Parameters:

• D (array-like) – Discharge [m/s] indexed by time

• V (array-like) – 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_velocity_vs_power(V, P, polynomial_coeff=None, label=None, ax=None)

Plots velocity vs power data along with the polynomial fit

Parameters:

• V (array-like) – Velocity [m/s] indexed by time

• P (array-like) – 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)