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 and Delft3D 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

get_layer_data

Get variable data from the NetCDF4 object at a specified layer and timestep.

create_points

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

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)[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, time_index)[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, seconds_run)[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, variable, layer_index=-1, time_index=-1)[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.

Returns

layer_data (DataFrame) – DataFrame 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)[source]

Turns three coordinate inputs into a single output DataFrame of points. In any order the three inputs can consist of 3 points, 2 points and 1 array, or 1 point and 2 arrays. The final output DataFrame will be the unique combinations of the 3 inputs.

Parameters
  • x (float, array or int) – x values to create points.

  • y (float, array or int) – y values to create points.

  • waterdepth (float, array or int) – waterdepth values to create points.

Returns

points (DateFrame) – DataFrame with columns x, y and waterdepth points.

Example

If the inputs are 2 arrays: and [3,4,5] and 1 point [6], the output will contain 6 array combinations of the 3 inputs as shown.

x=np.array([1,2]) y=np.array([3,4,5]) waterdepth= 6 d3d.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

mhkit.river.io.d3d.variable_interpolation(data, variables, points='cells', edges='none')[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, DataFrame) –

    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 DataFrame of x, y, and waterdepth coordinates - Interpolates data onto user povided points. Can be created with create_points function.

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

Returns

transformed_data (DataFrame) – 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)[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.

Returns

all_data (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)[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, 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.

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

Returns

TI_data (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

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

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 exceedence probability and power.

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

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

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)[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)[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, 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]

mhkit.river.performance.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.performance.tip_speed_ratio(rotor_speed, rotor_diameter, inflow_speed)[source]

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)[source]

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