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.

IO

The io submodule contains the following functions to load NOAA velocity/ direction data.

request_noaa_data

Loads NOAA current data directly from https://api.tidesandcurrents.noaa.gov/api/prod/ into a pandas DataFrame.

read_noaa_json

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 :param to_pandas: Flag to output pandas instead of xarray.

Resource

The resource module allows the user to calculate the ebb and flood directions of the tidal resource given a timeseries of directional data.

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 (numpy ndarray, pandas DataFrame, pandas Series, xarray DataArray, or xarray Dataset) – Flow direction in degrees CW from North, from 0 to 360

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

Returns:

principal directions (tuple(float,float)) – Principal directions 1 and 2 in degrees

Notes

One must determine which principal direction is flood and which is ebb based on knowledge of the measurement site.

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 (HAWT). 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 the tip speed ratio and power coefficient from a blade/rotor type 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

tip_speed_ratio

Function used to calculate the tip speed ratio (TSR) of a MEC device with rotor

power_coefficient

Function that calculates the power coefficient of MEC device

power_curve

Calculates power curve and power statistics for a marine energy device based on IEC/TS 62600-200 section 9.3.

velocity_profiles

Calculates profiles of the mean, root-mean-square (RMS), or standard deviation(std) of velocity.

device_efficiency

Calculates marine energy device efficiency based on IEC/TS 62600-200 Section 9.7.
mhkit.tidal.performance.power_curve(power, velocity, hub_height, doppler_cell_size, sampling_frequency, window_avg_time=600, turbine_profile='circular', diameter=None, height=None, width=None, to_pandas=True)[source]

Calculates power curve and power statistics for a marine energy device based on IEC/TS 62600-200 section 9.3.

Parameters:

  • power (numpy ndarray, pandas DataFrame, pandas Series, xarray DataArray, or xarray Dataset) – Device power output timeseries.

  • velocity (numpy ndarray, pandas DataFrame, pandas Series, xarray DataArray, or xarray Dataset) – 1D or 2D streamwise sea water velocity or sea water speed.

  • hub_height (numeric) – Turbine hub height altitude above the seabed. Assumes ADCP depth bins are referenced to the seafloor.

  • doppler_cell_size (numeric) – ADCP depth bin size.

  • sampling_frequency (numeric) – ADCP sampling frequency in Hz.

  • window_avg_time (int, optional) – Time averaging window in seconds. Defaults to 600.

  • turbine_profile ('circular' or 'rectangular', optional) – Shape of swept area of the turbine. Defaults to ‘circular’.

  • diameter (numeric, optional) – Required for turbine_profile=’circular’. Defaults to None.

  • height (numeric, optional) – Required for turbine_profile=’rectangular’. Defaults to None.

  • width (numeric, optional) – Required for turbine_profile=’rectangular’. Defaults to None.

  • to_pandas (bool, optional) – Flag to output pandas instead of xarray. Default = True.

Returns:

device_power_curve (pandas DataFrame or xarray Dataset) – Power-weighted velocity, mean power, power std dev, max and min power vs hub-height velocity.

mhkit.tidal.performance.velocity_profiles(velocity, hub_height, water_depth, sampling_frequency, window_avg_time=600, function='mean', to_pandas=True)[source]

Calculates profiles of the mean, root-mean-square (RMS), or standard deviation(std) of velocity. The chosen metric, specified by function, is calculated for each window_avg_time and bin-averaged based on ensemble velocity, as per IEC/TS 62600-200 sections 9.4 and 9.5.

Parameters:

  • velocity (numpy ndarray, pandas DataFrame, pandas Series, xarray DataArray, or xarray Dataset) – 1D or 2D streamwise sea water velocity or sea water speed.

  • hub_height (numeric) – Turbine hub height altitude above the seabed. Assumes ADCP depth bins are referenced to the seafloor.

  • water_depth (numeric) – Water depth to seafloor, in same units as velocity range coordinate.

  • sampling_frequency (numeric) – ADCP sampling frequency in Hz.

  • window_avg_time (int, optional) – Time averaging window in seconds. Defaults to 600.

  • func (string) – Function to apply. One of ‘mean’,’rms’, or ‘std’

  • to_pandas (bool, optional) – Flag to output pandas instead of xarray. Default = True.

Returns:

iec_profiles (pandas.DataFrame) – Average velocity profiles based on ensemble mean velocity.

mhkit.tidal.performance.device_efficiency(power, velocity, water_density, capture_area, hub_height, sampling_frequency, window_avg_time=600, to_pandas=True)[source]

Calculates marine energy device efficiency based on IEC/TS 62600-200 Section 9.7.

Parameters:

  • power (numpy ndarray, pandas DataFrame, pandas Series, xarray DataArray, or xarray Dataset) – Device power output timeseries in Watts.

  • velocity (numpy ndarray, pandas DataFrame, pandas Series, xarray DataArray, or xarray Dataset) – 1D or 2D streamwise sea water velocity or sea water speed in m/s.

  • water_density (float, pandas.Series or xarray.DataArray) – Sea water density in kg/m^3.

  • capture_area (numeric) – Swept area of marine energy device.

  • hub_height (numeric) – Turbine hub height altitude above the seabed. Assumes ADCP depth bins are referenced to the seafloor.

  • sampling_frequency (numeric) – ADCP sampling frequency in Hz.

  • window_avg_time (int, optional) – Time averaging window in seconds. Defaults to 600.

  • to_pandas (bool, optional) – Flag to output pandas instead of xarray. Default = True.

Returns:

device_eta (pandas.Series or xarray.DataArray) – Device efficiency (power coefficient) in percent.

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.

plot_velocity_duration_curve

Plots velocity vs exceedance probability as a Velocity Duration Curve (VDC)

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.

tidal_phase_exceedance

Returns a stacked area plot of the exceedance probability for the flood and ebb tidal phases.
mhkit.tidal.graphics.plot_rose(directions, velocities, width_dir, width_vel, ax=None, 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

  • ax (float) – Polar plot axes to add polar histogram

  • 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

mhkit.tidal.graphics.plot_joint_probability_distribution(directions, velocities, width_dir, width_vel, ax=None, 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

  • ax (float) – Polar plot axes to add polar histogram

  • 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_current_timeseries(directions, velocities, 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:

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

  • velocities (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.tidal_phase_probability(directions, velocities, flood, ebb, bin_size=0.1, ax=None)[source]

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:

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

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

  • flood (float or int) – Principal component of flow in the flood direction [degrees]

  • ebb (float or int) – Principal component of flow in the ebb direction [degrees]

  • bin_size (float) – Speed bin size. Optional. Deaful = 0.1 m/s

  • ax (matplotlib axes object) – Axes for plotting. If None, then a new figure with a single axes is used.

Returns:

ax (figure)

mhkit.tidal.graphics.tidal_phase_exceedance(directions, velocities, flood, ebb, bin_size=0.1, ax=None)[source]

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

Parameters:

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

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

  • flood (float or int) – Principal component of flow in the flood direction [degrees]

  • ebb (float or int) – Principal component of flow in the ebb direction [degrees]

  • bin_size (float) – Speed bin size. Optional. Deaful = 0.1 m/s

  • ax (matplotlib axes object) – Axes for plotting. If None, then a new figure with a single axes is used.

Returns:

ax (figure)