Tidal Module
The tidal module contains a set of functions to calculate quantities of interest for tidal energy converters.
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.tidal.io.request_noaa_data
simply use request_noaa_data
.
IO
The io submodule contains the following functions to load USGS Discharge data into structures.
Functions |
Description |
---|---|
|
Returns site structure from a json saved from the request_noaa_data function |
|
Loads NOAA current data directly from https://tidesandcurrents.noaa.gov/api/ using a GET request into a structure |
- mhkit.tidal.io.request_noaa_data(station, parameter, start_date, end_date, options)
Loads NOAA current data directly from https://tidesandcurrents.noaa.gov/api/ using a GET request into a structure. NOAA sets max of 31 days between start and end date. See https://co-ops.nos.noaa.gov/api/ for options. All times are reported as GMT and metric units are returned for data.
- Parameters:
station (
str
) – NOAA current station number (e.g. ‘s08010’)parameter (
str
) – NOAA paramter (e.g. ‘currents’)start_date (
str
) – Start date in the format yyyyMMddend_date (
str
) – End date in the format yyyyMMddproxy (
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_noaa_data(station,parameter,start_date,end_date,”write_json”,write_json)
- Returns:
data (structure)
data.id: station ID
data.name: station name
data.lat: station Latitude
data.lon: station Longitude
data.vars: this will vary depending on parameter input.
data.time: epoch time [s]
- mhkit.tidal.io.read_noaa_json(filename)
Returns site structure from a json saved from the request_noaa_data
- Parameters:
filename (
string
) – filename with path of json file to load- Returns:
data (Structure)
data.Data: Timeseries Site data, will be named based on parameters in JSON file
data.time
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 |
---|---|
|
Calculates the principal flow directions of current data |
|
Calculate the Froude Number of the river, channel or duct flow, to check subcritical flow assumption (if Fr <1). |
|
Calculates the exceedance probability |
- mhkit.tidal.resource.principal_flow_directions(directions, width_dir)
Calculates the principal flow directions of current data The weighted average (over the working velocity range of the TEC) should be considered to be the principal direction of the current, and should be used for both the ebb and flood cycles to determine the TEC optimum orientation.
- Parameters:
directions (
vector
) – flow directions [degrees]width_dir (
int or vector
) – width of direction bins [degrees]
- Returns:
ebb (float) – principal ebb direction [degrees]
flood (float) – principal flood direction [degrees]
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. This submodule also contains functions for computing tip speed ratio and the power coefficient from blade/rotor type devices.
Functions |
Description |
---|---|
|
Calculates the equivalent diameter and projected capture area of a circular turbine |
|
Calculates the equivalent diameter and projected capture area of a ducted turbine |
|
Calculates the equivalent diameter and projected capture area of a multiple circular turbine |
|
Calculates the equivalent diameter and projected capture area of a retangular turbine |
|
Calculates the tip speed ratio (TSR) of a MEC device with rotor |
|
Calculates the calculates the power coefficient of MEC device |
- 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.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)
- 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.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.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.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]
Note
Tidal device functions are the same as the River device functions
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 |
---|---|
|
Plots velocity vs exceedance probability as a Flow Duration Curve (FDC) |
|
Creates a polar histogram. Direction angles from binned histogram must be specified such that 0 degrees is north. |
|
Creates a polar histogram. Direction angles from binned histogram must be specified such that 0 is north. |
|
Returns a plot of velocity from an array of direction and speed data in the direction of the supplied principal_direction. |
|
Creates a stacked area plot of the exceedance probability for the flood and ebb tidal phases. |
|
Discretizes the tidal series speed by bin size and returns a plot of the probability for each bin in the flood or ebb tidal phase. |
- mhkit.tidal.graphics.plot_tidal_phase_exceedance(data, flood, ebb, options)
Returns a stacked area plot of the exceedance probability for the flood and ebb tidal phases.
- Parameters:
data (
structure
) –- data.time: vector
days from January 0, 0000 in the proleptic ISO calendar
- data.d: vector
time-series of directions [degrees]
- data.s: vector
time-series of speeds [cm/s]
flood (
float
) – principal flood direction [degrees]ebb (
float
) – principal ebb direction [degrees]bin_size (
numeric (optional)
) – Speed bin size. Default = 0.1 m/s to call: plot_tidal_phase_probability(data, flood, ebb,”bin_size”,bin_size)title (
string (optional)
) – title for the plot to call: plot_tidal_phase_probability(data, flood, ebb,”title”,title)savepath (
string (optional)
) – path and filename to save figure. to call: plot_tidal_phase_probability(data, flood, ebb,”savepath”,savepath)
- Returns:
figure (stacked bar graph of the probability of exceedance in) – flood and ebb directions
- mhkit.tidal.graphics.plot_rose(data, width_dir, width_vel, options)
Creates a polar histogram. Direction angles from binned histogram must be specified such that 0 degrees is north.
- Parameters:
data (
structure
) –- data.time: vector
days from January 0, 0000 in the proleptic ISO calendar
- data.d: vector
time-series of directions [degrees]
- data.s: vector
time-series of speeds [cm/s]
width_dir (
float
) – Width of directional bins for histogram in degreeswidth_vel (
float
) – Width of velocity bins for histogram in m/sflood_ebb (
2 element vector (optional)
) – Direction in degrees added to theta ticks to call: plot_rose(Q, width_dir, width_vel,”flood_ebb”,flood_ebb)title (
string (optional)
) – title for the plot to call: plot_rose(Q, width_dir, width_vel,”title”,title)savepath (
string (optional)
) – path and filename to save figure. to call: plot_rose(Q, width_dir, width_vel,”savepath”,savepath)
- Returns:
figure handle to water current rose plot
- mhkit.tidal.graphics.plot_tidal_phase_probability(data, flood, ebb, options)
Discretizes the tidal series speed by bin size and returns a plot of the probability for each bin in the flood or ebb tidal phase.
- Parameters:
data (
structure
) –- data.time: vector
days from January 0, 0000 in the proleptic ISO calendar
- data.d: vector
time-series of directions [degrees]
- data.s: vector
time-series of speeds [cm/s]
flood (
float
) – principal flood direction [degrees]ebb (
float
) – principal ebb direction [degrees]bin_size (
numeric (optional)
) – Speed bin size. Default = 0.1 m/s to call: plot_tidal_phase_probability(data, flood, ebb,”bin_size”,bin_size)title (
string (optional)
) – title for the plot to call: plot_tidal_phase_probability(data, flood, ebb,”title”,title)savepath (
string (optional)
) – path and filename to save figure. to call: plot_tidal_phase_probability(data, flood, ebb,”savepath”,savepath)
- Returns:
figure (stacked bar graph of the probability of exceedance in) – flood and ebb directions
- mhkit.tidal.graphics.plot_current_timeseries(data, principal_direction, options)
Returns a plot of velocity from an array of direction and speed data in the direction of the supplied principal_direction.
- Parameters:
data (
structure
) –- data.time: vector
days from January 0, 0000 in the proleptic ISO calendar
- data.d: vector
time-series of directions [degrees]
- data.s: vector
time-series of speeds [cm/s]
principal_direction (
numeric
) – Direction to compute the velocity in [degrees]title (
string (optional)
) – title for the plot to call: plot_current_timeseries(data,principal_direction,”title”,title)savepath (
string (optional)
) – path and filename to save figure. to call: plot_current_timeseries(data,principal_direction,”savepath”,savepath)
- Returns:
figure (timeseries plot of current-speed velocity)
- mhkit.tidal.graphics.plot_joint_probability_distribution(Q, width_dir, width_vel, options)
Creates a polar histogram. Direction angles from binned histogram must be specified such that 0 is north.
- Parameters:
data (
structure
) –- data.time: vector
days from January 0, 0000 in the proleptic ISO calendar
- data.d: vector
time-series of directions [degrees]
- data.s: vector
time-series of speeds [cm/s]
width_dir (
float
) – Width of directional bins for histogram in degreeswidth_vel (
float
) – Width of velocity bins for histogram in m/sflood_ebb (
2 element vector (optional)
) – Direction in degrees added to theta ticks to call: plot_joint_probability_distribution(Q, width_dir, width_vel,”flood_ebb”,flood_ebb)title (
string (optional)
) – title for the plot to call: plot_joint_probability_distribution(Q, width_dir, width_vel,”title”,title)savepath (
string (optional)
) – path and filename to save figure. to call: plot_joint_probability_distribution(Q, width_dir, width_vel,”savepath”,savepath)
- Returns:
figure handle to joint probability distribution plot