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.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
 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://coops.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]
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 multiplecircular 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.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)
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_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
timeseries of directions [degrees]
 data.s: vector
timeseries 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 currentspeed 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
timeseries of directions [degrees]
 data.s: vector
timeseries 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
 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
timeseries of directions [degrees]
 data.s: vector
timeseries 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_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
timeseries of directions [degrees]
 data.s: vector
timeseries 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_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
timeseries of directions [degrees]
 data.s: vector
timeseries 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