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.

MHKiT Tidal Module

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

IO

The io submodule contains functions to load NOAA and Delft3D 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.
`get_all_time`	Returns all of the time stamps from a D3D simulation passed to the function as a NetCDF object (data)
`index_to_seconds`	The function will return 'seconds_run' if passed a 'time_index'
`seconds_to_index`	The function will return the nearest 'time_index' in the data if passed an integer number of 'seconds_run'
`get_layer_data`	Get variable data from the NetCDF4 object at a specified layer and timestep.
`create_points`	Generate a Dataset of points from combinations of input coordinates.
`variable_interpolation`	Interpolate multiple variables from the Delft3D onto the same points.
`get_all_data_points`	Get data points for a passed variable for all layers at a specified time from the Delft3D NetCDF4 object by iterating over the get_layer_data function.
`turbulent_intensity`	Calculate the turbulent intensity percentage for a given data set for the specified points.

Resource

This module provides utility functions for analyzing river and tidal flow directions and velocities. It includes tools for determining principal flow directions, classifying ebb and flood cycles, and computing probability distributions of flow velocities.

This module provides utility functions for analyzing river and tidal flow directions and velocities. It includes tools for determining principal flow directions, classifying ebb and flood cycles, and computing probability distributions of flow velocities.

`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.exceedance_probability(discharge: Series | DataFrame | DataArray | Dataset, dimension: str = '', to_pandas: bool = True) → DataFrame | Dataset[source]

Calculates the exceedance probability

Parameters:

discharge (pandas Series, pandas DataFrame, xarray DataArray, or xarray Dataset) – Discharge indexed by time [datetime or s].
dimension (string (optional)) – Name of the relevant xarray dimension. If not supplied, defaults to the first dimension. Does not affect pandas input.
to_pandas (bool (optional)) – Flag to output pandas instead of xarray. Default = True.

Returns:

exceedance_prob (pandas DataFrame or xarray Dataset) – Exceedance probability [unitless] indexed by time [datetime or s]

mhkit.tidal.resource.froude_number(v: int | float, h: int | float, g: int | float = 9.80665) → float[source]

Calculate the Froude Number of the river, channel or duct flow, to check subcritical flow assumption (if Fr <1).

Parameters:

v (int/float) – Average velocity [m/s].
h (int/float) – Mean hydraulic depth float [m].
g (int/float) – Gravitational acceleration [m/s2].

Returns:

froude_num (float) – Froude Number of the river [unitless].

mhkit.tidal.resource.principal_flow_directions(directions: ndarray, width_dir: float) → tuple[float, float][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

This module provides functions for analyzing the performance of tidal energy devices using Acoustic Doppler Current Profiler (ADCP) data. It includes methods for calculating power curves, efficiency, velocity profiles, and other metrics relevant to marine energy devices.

performance.py

This module provides functions for analyzing the performance of tidal energy devices using Acoustic Doppler Current Profiler (ADCP) data. It includes methods for calculating power curves, efficiency, velocity profiles, and other metrics relevant to marine energy devices.

`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.circular(diameter: int | float) → Tuple[float, float][source]

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

Parameters:

diameter (int/float) – Turbine diameter [m]

Returns:

equivalent_diameter (float) – Equivalent diameter [m]
projected_capture_area (float) – Projected capture area [m^2]

mhkit.tidal.performance.ducted(duct_diameter: int | float) → Tuple[float, float][source]

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

Parameters:

duct_diameter (int/float) – Duct diameter [m]

Returns:

equivalent_diameter (float) – Equivalent diameter [m]
projected_capture_area (float) – Projected capture area [m^2]

mhkit.tidal.performance.rectangular(h: int | float, w: int | float) → Tuple[float, float][source]

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

Parameters:

h (int/float) – Turbine height [m]
w (int/float) – Turbine width [m]

Returns:

equivalent_diameter (float) – Equivalent diameter [m]
projected_capture_area (float) – Projected capture area [m^2]

mhkit.tidal.performance.multiple_circular(diameters: List[int | float]) → Tuple[float, float][source]

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

Parameters:

diameters (list) – List of device diameters [m]

Returns:

equivalent_diameter (float) – Equivalent diameter [m]
projected_capture_area (float) – Projected capture area [m^2]

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

Parameters:

rotor_speed (numpy array) – Rotor speed [revolutions per second]
rotor_diameter (float/int) – Diameter of rotor [m]
inflow_speed (numpy array) – Velocity of inflow condition [m/s]

Returns:

tip_speed_ratio_values (numpy array) – Calculated tip speed ratio (TSR)

Function that calculates the power coefficient of MEC device

Parameters:

power (numpy array) – Power output signal of device after losses [W]
inflow_speed (numpy array) – Speed of inflow [m/s]
capture_area (float/int) – Projected area of rotor normal to inflow [m^2]
rho (float/int) – Density of environment [kg/m^3]

Returns:

power_coeff (numpy array) – Power coefficient of device [-]

Graphics

This module provides functions for visualizing tidal resource and performance data. It includes tools for creating polar plots, velocity distributions, exceedance probability charts, and current time-series plots.

graphics.py

This module provides functions for visualizing tidal resource and performance data. It includes tools for creating polar plots, velocity distributions, exceedance probability charts, and current time-series plots.

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

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

Parameters:

velocity (array-like) – Velocity [m/s] indexed by time
exceedance_prob (array-like) – Exceedance probability [unitless] indexed by time
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 (matplotlib pyplot axes)