River Module

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

The river module provides tools and utilities for analyzing river energy resources.

IO

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

This module provides input/output functionality for river energy related data in MHKiT.

USGS

This module provides functions for retrieving and processing data from the United States Geological Survey (USGS) National Water Information System (NWIS). It enables access to river flow data and related measurements useful for hydrokinetic resource assessment.

`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: str, to_pandas: bool = True) → DataFrame | Dataset[source]

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: str, parameter: str, start_date: str, end_date: str, options: Dict | None = None) → DataFrame | Dataset[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 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’)
options (dict, optional) –
Dictionary containing optional parameters: - data_type: str

Data type, options include ‘Daily’ (return the mean daily value) and ‘Instantaneous’. Default = ‘Daily’
- proxy: dict or None
  Proxy settings for the request. Default = None
- write_json: str or None
  Name of json file to write data. Default = None
- clear_cache: bool
  If True, the cache for this specific request will be cleared. Default = False
- to_pandas: bool
  Flag to output pandas instead of xarray. Default = True
- timeout: int
  Timeout in seconds for the HTTP request. Default = 30

Returns:

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

D3D

This module provides functions for reading and processing Delft3D (D3D) model output data. It includes utilities for handling NetCDF files generated by Delft3D simulations, with specific focus on hydrodynamic data analysis for marine and hydrokinetic applications.

`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.
`list_variables`	List all variables in a DataArray, Dataset, or NetCDF4 Dataset.

mhkit.river.io.d3d.get_all_time(data: Dataset) → ndarray[tuple[int, ...], dtype[_ScalarType_co]][source]

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: Dataset, time_index: int) → int | float[source]

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: Dataset, seconds_run: int | float) → int[source]

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: Dataset, variable: str, layer_index: int = -1, time_index: int = -1, to_pandas: bool = True) → DataFrame | Dataset[source]

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 difference in meters from zero.

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: Dataset, variables: List[str], points: str | DataFrame | Dataset = 'cells', edges: str = 'none', x_max_lim: float = inf, x_min_lim: float = -inf, y_max_lim: float = inf, y_min_lim: float = -inf, to_pandas: bool = True) → DataFrame | Dataset[source]

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 provided 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: Dataset, variable: str, time_index: int = -1, to_pandas: bool = True) → DataFrame | Dataset[source]

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: Dataset, points: str | DataFrame | Dataset = 'cells', time_index: int = -1, intermediate_values: bool = False, to_pandas: bool = True) → DataFrame | Dataset[source]

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 needed 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 turbulent_intensity- 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

mhkit.river.io.d3d.list_variables(data: Dataset | Dataset | DataArray) → List[str][source]

List all variables in a DataArray, Dataset, or NetCDF4 Dataset.

Parameters:: data (Union[netCDF4.Dataset, xr.Dataset, xr.DataArray]) – The data object containing variables to list.
Returns:: List[str] – A list of variable names in the data object.

Examples

>>> # List variables in a NetCDF4 Dataset
>>> variables = list_variables(nc_data)
>>> print(variables)
['time', 'x', 'y', 'waterdepth', 'ucx', 'ucy', 'ucz', 'turkin1']

>>> # List variables in an xarray Dataset
>>> variables = list_variables(xr_dataset)
>>> print(variables)
['time', 'x', 'y', 'waterdepth', 'ucx', 'ucy', 'ucz', 'turkin1']

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.

Computes resource assessment metrics, including exceedance probability, inflow velocity, and power (theoretical resource). Calculations are based on IEC TS 62600-301:2019 ED1.

`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: int | float, h: int | float, g: int | float = 9.80665) → float[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 hydraulic depth float [m].
g (int/float) – Gravitational acceleration [m/s2].

Returns:

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

mhkit.river.resource.exceedance_probability(discharge: Series | DataFrame | DataArray | Dataset, dimension: str = '', to_pandas: bool = True) → DataFrame | Dataset[source]

Calculates the exceedance probability

Parameters:

discharge (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:

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

mhkit.river.resource.polynomial_fit(x: ndarray, y: ndarray, n: int) → Tuple[poly1d, float][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
r_squared (float) – Polynomial fit coefficient of determination

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

Parameters:

discharge (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:

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

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

Parameters:

velocity (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 power
cut_out (int/float) – Velocity values above cut_out are not used to compute power
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:

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

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

Parameters:

power_data (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:

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

Computes device metrics such as equivalent diameter, tip speed ratio, and capture area. Calculations are based on IEC TS 62600-300:2019 ED1.

`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: int | float) → Tuple[float, float][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.performance.ducted(duct_diameter: int | float) → Tuple[float, float][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.performance.rectangular(h: int | float, w: int | float) → Tuple[float, float][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]

mhkit.river.performance.multiple_circular(diameters: List[int | float]) → Tuple[float, float][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]

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:

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

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:

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

Graphics

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

The graphics module provides plotting utilities for river energy resource data.

`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

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

Parameters:

discharge (array-like) – Discharge [m3/s] indexed by time
exceedance_prob (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)

Plots velocity vs exceedance probability as a Velocity Duration Curve (VDC)

Parameters:

velocity (array-like) – Velocity [m/s] indexed by time
exceedance_prob (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)

Plots power vs exceedance probability as a Power Duration Curve (PDC)

Parameters:

power (array-like) – Power [W] indexed by time
exceedance_prob (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)

Plots discharge time-series

Parameters:

discharge (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)

Plots discharge vs velocity data along with the polynomial fit

Parameters:

discharge (array-like) – Discharge [m3/s] indexed by time
velocity (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)

Plots velocity vs power data along with the polynomial fit

Parameters:

velocity (array-like) – Velocity [m/s] indexed by time
power (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)