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, varargin)

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 (structure (optional)) – To request data from behind a firewall, define a structure of proxy settings, for example proxy.http = “localhost:8080”

  • write_json (str (optional)) – Name of json file to write data

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]

Device

The device 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.

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
mhkit.river.device.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.device.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.device.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.device.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]

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.
mhkit.tidal.graphics.plot_current_timeseries(data, principal_direction, varargin)

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

Returns

figure (timeseries plot of current-speed velocity)

mhkit.tidal.graphics.plot_joint_probability_distribution(Q, width_dir, width_vel, varargin)

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

  • title (string (optional)) – title for the plot

Returns

figure handle to joint probability distribution plot

mhkit.tidal.graphics.plot_rose(data, width_dir, width_vel, varargin)

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

  • title (string (optional)) – title for the plot

Returns

figure handle to water current rose plot