Tidal Module

The tidal module contains a set of functions to calculate quantities of interest for tidal energy converters (TEC).

The tidal module uses timeseries data of velocity and direction.

  • Velocity/ direction 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 NOAA velocity/ direction data

request_noaa_data

Loads NOAA current data directly from https://tidesandcurrents.noaa.gov/api/ using a get request into a pandas DataFrame.
mhkit.tidal.io.read_noaa_json(filename)[source]

Returns site DataFrame and metadata from a json saved from the request_noaa_data :param filename: filename with path of json file to load :type filename: string

Returns

  • data (DataFrame) – Timeseries Site data of direction and speed

  • metadata (dictionary) – Site metadata

mhkit.tidal.io.request_noaa_data(station, parameter, start_date, end_date, proxy=None, write_json=None)[source]

Loads NOAA current data directly from https://tidesandcurrents.noaa.gov/api/ using a get request into a pandas DataFrame. 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.

The request URL prints to the screen.

Parameters

  • station (str) – NOAA current station number (e.g. ‘cp0101’)

  • parameter (str) – NOAA paramter (e.g. ‘’ for Discharge, cubic feet per second)

  • start_date (str) – Start date in the format yyyyMMdd

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

  • 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 module allows the user to calculate the ebb and flood directions of the tidal resource given a timeseries of directional data. The

principal_flow_directions

Calculates principal flow directions for ebb and flood cycles

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

Calculates principal flow directions for ebb and flood cycles

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 (pd.Series or numpy array) – Directions in degrees with 0 degrees specified as true north

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

Returns

  • ebb (float) – Principal ebb direction in degrees

  • flood (float) – Principal flood direction in 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 (HAWT). A ducted device is an enclosed VAWT. A multiple-circular devices is a device with multiple VAWTs per device.

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

Graphics

The graphics submodule contains functions to plot tidal resource data and related metrics.

plot_rose

Creates a polar histogram.

plot_joint_probability_distribution

Creates a polar histogram.

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(directions, speeds, principal_direction, label=None, ax=None)[source]

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

Parameters

  • direction (array like) – Time-series of directions [degrees]

  • speed (array like) – Time-series of speeds [m/s]

  • principal_direction (float) – Direction to compute the velocity in [degrees]

  • 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 (figure) – Time-series plot of current-speed velocity

mhkit.tidal.graphics.plot_joint_probability_distribution(directions, velocities, width_dir, width_vel, metadata=None, flood=None, ebb=None)[source]

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

Parameters

  • directions (array like) – Directions in degrees with 0 degrees specified as true north

  • velocities (array like) – Velocities in m/s

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

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

  • metadata (dictonary) – If provided needs keys [‘name’, ‘Lat’, ‘Lon’] for plot title and information box on plot

  • flood (float) – Direction in degrees added to theta ticks

  • ebb (float) – Direction in degrees added to theta ticks

Returns

ax (figure) – Joint probability distribution

mhkit.tidal.graphics.plot_rose(directions, velocities, width_dir, width_vel, metadata=None, flood=None, ebb=None)[source]

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

Parameters

  • directions (array like) – Directions in degrees with 0 degrees specified as true north

  • velocities (array like) – Velocities in m/s

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

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

  • metadata (dictonary) – If provided needs keys [‘name’, ‘lat’, ‘lon’] for plot title and information box on plot

  • flood (float) – Direction in degrees added to theta ticks

  • ebb (float) – Direction in degrees added to theta ticks

Returns

ax (figure) – Water current rose plot