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

read_noaa_json

Returns site structure from a json saved from the request_noaa_data function

request_noaa_data

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://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 yyyyMMdd

  • end_date (str) – End date in the format yyyyMMdd

  • proxy (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

principal_flow_direction

Calculates the principal flow directions of current data

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

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

multiple_circular

Calculates the equivalent diameter and projected capture area of a multiple circular turbine

rectangular

Calculates the equivalent diameter and projected capture area of a retangular turbine

tip_speed_ratio

Calculates the tip speed ratio (TSR) of a MEC device with rotor

power_coefficient

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

plot_velocity_duration_curve

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

plot_rose

Creates a polar histogram. Direction angles from binned histogram must be specified such that 0 degrees is north.

plot_joint_probability_distribution

Creates a polar histogram. Direction angles from binned histogram must be specified such that 0 is north.

plot_current_timeseries

Returns a plot of velocity from an array of direction and speed data in the direction of the supplied principal_direction.

plot_tidal_phase_exceedance

Creates a stacked area plot of the exceedance probability for the flood and ebb tidal phases.

plot_tidal_phase_probability

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

    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 degrees

  • width_vel (float) – Width of velocity bins for histogram in m/s

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

    time-series of directions [degrees]

    data.s: vector

    time-series of speeds [cm/s]

  • width_dir (float) – Width of directional bins for histogram in degrees

  • width_vel (float) – Width of velocity bins for histogram in m/s

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

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