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
|
Loads NOAA current data directly from https://tidesandcurrents.noaa.gov/api/ using a get request into a pandas DataFrame. |
|
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 |
Resource
The resource module allows the user to calculate the ebb and flood directions of the tidal resource given a timeseries of directional data.
Calculates principal flow directions for ebb and flood cycles |
|
Calculate the Froude Number of the river, channel or duct flow, to check subcritical flow assumption (if Fr <1). |
|
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 (pandas.Series or numpy.ndarray) – 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.
- mhkit.tidal.resource.Froude_number(v, h, g=9.80665)[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 hydrolic depth float [m].
g (int/float) – Gravitational acceleration [m/s2].
- Returns
Fr (float) – Froude Number of the river [unitless].
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.
Calculates the equivalent diameter and projected capture area of a circular turbine |
|
Calculates the equivalent diameter and projected capture area of a ducted turbine |
|
Calculates the equivalent diameter and projected capture area of a retangular turbine |
|
Calculates the equivalent diameter and projected capture area of a multiple circular turbine |
|
Function used to calculate the tip speed ratio (TSR) of a MEC device with rotor |
|
Function that calculates the power coefficient of MEC device |
|
Calculates power curve and power statistics for a marine energy device based on IEC/TS 62600-200 section 9.3. |
|
Calculates marine energy device efficiency based on IEC/TS 62600-200 Section 9.7. |
|
Calculates profiles of the mean, root-mean-square (RMS), or standard deviation(std) of velocity. |
- 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)[source]
Calculates power curve and power statistics for a marine energy device based on IEC/TS 62600-200 section 9.3.
- Parameters
power (pandas.Series or xarray.DataArray (time)) – Device power output timeseries.
velocity (pandas.Series or xarray.DataArray ([range,] time)) – 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.
- Returns
pandas.DataFrame – 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')[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 (pandas.Series or xarray.DataArray ([range,] time)) – 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’
- Returns
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)[source]
Calculates marine energy device efficiency based on IEC/TS 62600-200 Section 9.7.
- Parameters
power (pandas.Series or xarray.DataArray (time)) – Device power output timeseries in Watts.
velocity (pandas.Series or xarray.DataArray ([range,] time)) – 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.
- Returns
pandas.Series – Device efficiency (power coefficient) in percent.
- mhkit.tidal.performance.circular(diameter)[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)[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, w)[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)[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]
- mhkit.tidal.performance.tip_speed_ratio(rotor_speed, rotor_diameter, inflow_speed)[source]
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
TSR (numpy array) – Calculated tip speed ratio (TSR)
- mhkit.tidal.performance.power_coefficient(power, inflow_speed, capture_area, rho)[source]
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
Cp (numpy array) – Power coefficient of device [-]
Graphics
The graphics submodule contains functions to plot tidal resource data and related metrics.
Creates a polar histogram. |
|
Creates a polar histogram. |
|
Returns a plot of velocity from an array of direction and speed data in the direction of the supplied principal_direction. |
|
|
Plots velocity vs exceedance probability as a Velocity Duration Curve (VDC) |
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. |
|
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)
- mhkit.tidal.graphics.plot_velocity_duration_curve(V, F, label=None, ax=None)[source]
Plots velocity vs exceedance probability as a Velocity Duration Curve (VDC)
- Parameters
V (array-like) – Velocity [m/s] indexed by time
F (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)