Wave Module¶

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

The wave module uses wave elevation time series data and spectra data.

Wave elevation 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 (for example, data from multiple sensors).
Spectra data is stored as a pandas DataFrame index by frequency in Hz. The column names describe the type of data in each column (for example, Bretschneider and JONSWAP spectra).

Note that spectra data is sometimes stored in time series format (data indexed by time, with one column for each frequency). To convert time series format to the spectra data format, use the pandas method transpose.

IO¶

The io submodule contains the following function to load National Data Buoy Center (NDBC) data file into a pandas DataFrame, including real time and historical data.

read_NDBC_file

Reads a NDBC wave buoy data file (from https://www.ndbc.noaa.gov).

mhkit.wave.io.read_NDBC_file(file_name, missing_values=['MM', 9999, 999, 99])[source]¶

Reads a NDBC wave buoy data file (from https://www.ndbc.noaa.gov).

Realtime and historical data files can be loaded with this function.

Note: With realtime data, missing data is denoted by “MM”. With historical data, missing data is denoted using a variable number of # 9’s, depending on the data type (for example: 9999.0 999.0 99.0). ‘N/A’ is automatically converted to missing data.

Data values are converted to float/int when possible. Column names are also converted to float/int when possible (this is useful when column names are frequency).

Parameters

file_name (string) – Name of NDBC wave buoy data file
missing_value (list of values) – List of values that denote missing data

Returns

data (pandas DataFrame) – Data indexed by datetime with columns named according to header row
metadata (dict or None) – Dictionary with {column name: units} key value pairs when the NDBC file contains unit information, otherwise None is returned

Resource¶

The resource submodule contains functions compute wave energy spectra and metrics.

The following functions can be used to compute wave energy spectra:

`elevation_spectrum`	Calculates the wave energy spectrum from wave elevation time-series
`pierson_moskowitz_spectrum`	Calculates Pierson-Moskowitz Spectrum from Tucker and Pitt (2001)
`bretschneider_spectrum`	Calculates Bretschneider Sprectrum from Tucker and Pitt (2001)
`jonswap_spectrum`	Calculates JONSWAP spectrum from Hasselmann et al (1973)

The following functions can be used to compute wave metrics from spectra:

`surface_elevation`	Calculates wave elevation time-series from spectrum using a random phase
`frequency_moment`	Calculates the Nth frequency moment of the spectrum
`significant_wave_height`	Calculates wave height from spectra
`average_zero_crossing_period`	Calculates wave average zero crossing period from spectra
`average_crest_period`	Calculates wave average crest period from spectra
`average_wave_period`	Calculates mean wave period from spectra
`peak_period`	Calculates wave energy period from spectra
`energy_period`	Calculates wave energy period from spectra
`spectral_bandwidth`	Calculates bandwidth from spectra
`spectral_width`	Calculates wave spectral width from spectra
`energy_flux`	Calculates the omnidirectional wave energy flux of the spectra
`wave_celerity`	Calculates wave celerity (group velocity)
`wave_number`	Calculates wave number

mhkit.wave.resource.average_crest_period(S)[source]¶

Calculates wave average crest period from spectra

Parameters: S (pandas DataFrame) – Spectral density [m^2/Hz] indexed by frequency [Hz]
Returns: Tavg (pandas DataFrame) – Average wave period [s] indexed by S.columns

mhkit.wave.resource.average_wave_period(S)[source]¶

Calculates mean wave period from spectra

Parameters: S (pandas DataFrame) – Spectral density [m^2/Hz] indexed by frequency [Hz]
Returns: Tm (pandas DataFrame) – Mean wave period [s] indexed by S.columns

mhkit.wave.resource.average_zero_crossing_period(S)[source]¶

Calculates wave average zero crossing period from spectra

Parameters: S (pandas DataFrame) – Spectral density [m^2/Hz] indexed by frequency [Hz]
Returns: Tz (pandas DataFrame) – Average zero crossing period [s] indexed by S.columns

mhkit.wave.resource.bretschneider_spectrum(f, Tp, Hs)[source]¶

Calculates Bretschneider Sprectrum from Tucker and Pitt (2001)

Parameters

f (numpy array) – Frequency [Hz]
Tp (float/int) – Peak period [s]
Hs (float/int) – Significant wave height [m]

Returns

S (pandas DataFrame) – Spectral density [m^2/Hz] indexed by frequency [Hz]

mhkit.wave.resource.elevation_spectrum(eta, sample_rate, nnft, window='hamming', detrend=True)[source]¶

Calculates the wave energy spectrum from wave elevation time-series

Parameters

eta (pandas DataFrame) – Wave surface elevation [m] indexed by time [datetime or s]
sample_rate (float) – Data frequency [Hz]
nnft (integer) – Number of bins in the Fast Fourier Transform
window (string (optional)) – Signal window type. ‘hamming’ is used by default given the broadband nature of waves. See scipy.signal.get_window for more options.
detrend (bool (optional)) – Specifies if a linear trend is removed from the data before calculating the wave energy spectrum. Data is detrended by default.

Returns

S (pandas DataFrame) – Spectral density [m^2/Hz] indexed by frequency [Hz]

mhkit.wave.resource.energy_flux(S, h, rho=1025, g=9.80665)[source]¶

Calculates the omnidirectional wave energy flux of the spectra

Parameters

S (pandas DataFrame) – Spectral density [m^2/Hz] indexed by frequency [Hz]
h (float) – Water depth [m]
rho (float (optional)) – Water Density [kg/m3]
g (float (optional)) – Gravitational acceleration [m/s^2]

Returns

J (pandas DataFrame) – Omni-directional wave energy flux [W/m] indexed by S.columns

mhkit.wave.resource.energy_period(S)[source]¶

Calculates wave energy period from spectra

Parameters: S (pandas DataFrame) – Spectral density [m^2/Hz] indexed by frequency [Hz]
Returns: Te (pandas DataFrame) – Wave energy period [s] indexed by S.columns

mhkit.wave.resource.frequency_moment(S, N)[source]¶

Calculates the Nth frequency moment of the spectrum

Parameters

S (pandas DataFrame) – Spectral density [m^2/Hz] indexed by frequency [Hz]
N (int) – Moment (0 for 0th, 1 for 1st ….)

Returns

m (pandas DataFrame) – Nth Frequency Moment indexed by S.columns

mhkit.wave.resource.jonswap_spectrum(f, Tp, Hs, gamma=3.3)[source]¶

Calculates JONSWAP spectrum from Hasselmann et al (1973)

Parameters

f (numpy array) – Frequency [Hz]
Tp (float/int) – Peak period [s]
Hs (float/int) – Significant wave height [m]
gamma (float (optional)) – Gamma

Returns

S (pandas DataFrame) – Spectral density [m^2/Hz] indexed frequency [Hz]

mhkit.wave.resource.peak_period(S)[source]¶

Calculates wave energy period from spectra

Parameters: S (pandas DataFrame) – Spectral density [m^2/Hz] indexed by frequency [Hz]
Returns: Tp (pandas DataFrame) – Wave peak period [s] indexed by S.columns

mhkit.wave.resource.pierson_moskowitz_spectrum(f, Tp)[source]¶

Calculates Pierson-Moskowitz Spectrum from Tucker and Pitt (2001)

Parameters

f (numpy array) – Frequency [Hz]
Tp (float/int) – Peak period [s]

Returns

S (pandas DataFrame) – Spectral density [m^2/Hz] indexed frequency [Hz]

mhkit.wave.resource.significant_wave_height(S)[source]¶

Calculates wave height from spectra

Parameters: S (pandas DataFrame) – Spectral density [m^2/Hz] indexed by frequency [Hz]
Returns: Hm0 (pandas DataFrame) – Significant wave height [m] index by S.columns

mhkit.wave.resource.spectral_bandwidth(S)[source]¶

Calculates bandwidth from spectra

Parameters: S (pandas DataFrame) – Spectral density [m^2/Hz] indexed by frequency [Hz]
Returns: e (pandas DataFrame) – Spectral bandwidth [s] indexed by S.columns

mhkit.wave.resource.spectral_width(S)[source]¶

Calculates wave spectral width from spectra

Parameters: S (pandas DataFrame) – Spectral density [m^2/Hz] indexed by frequency [Hz]
Returns: v (pandas DataFrame) – Spectral width [m] indexed by S.columns

mhkit.wave.resource.surface_elevation(S, time_index, seed=123)[source]¶

Calculates wave elevation time-series from spectrum using a random phase

Parameters

S (pandas DataFrame) – Spectral density [m^2/Hz] indexed by frequency [Hz]
time_index (numpy array) – Time used to create the wave elevation time-series [s], for example, time = np.arange(0,100,0.01)
seed (int (optional)) – Random seed

Returns

eta (pandas DataFrame) – Wave surface elevation [m] indexed by time [s]

mhkit.wave.resource.wave_celerity(k, h, g=9.80665)[source]¶

Calculates wave celerity (group velocity)

Parameters

k (pandas DataFrame) – Wave number [1/m] indexed by frequency [Hz]
h (float) – Water depth [m]
g (float (optional)) – Gravitational acceleration [m/s^2]

Returns

Cg (pandas DataFrame) – Water celerity [?] indexed by frequency [Hz]

mhkit.wave.resource.wave_number(f, h, rho=1025, g=9.80665)[source]¶

Calculates wave number

To compute wave number from angular frequency (w), convert w to f before using this function (f = w/2*pi)

Parameters

f (numpy array) – Frequency [Hz]
h (float) – Water depth [m]
rho (float (optional)) – Water density [kg/m^3]
g (float (optional)) – Gravitational acceleration [m/s^2]

Returns

k (pandas DataFrame) – Wave number [1/m] indexed by frequency [Hz]

Performance¶

The performance submodule contains functions to compute capture length, statistics, performance matrices, and mean annual energy production.

`capture_length`	Calculates the capture length (often called capture width).
`statistics`	Calculates statistics, including count, mean, standard deviation (std), min, percentiles (25%, 50%, 75%), and max.
`capture_length_matrix`	Generates a capture length matrix for a given statistic
`wave_energy_flux_matrix`	Generates a wave energy flux matrix for a given statistic
`power_matrix`	Generates a power matrix from a capture length matrix and wave energy flux matrix
`mean_annual_energy_production_timeseries`	Calculates mean annual energy production (MAEP) from time-series
`mean_annual_energy_production_matrix`	Calculates mean annual energy production (MAEP) from matrix data along with data frequency in each bin
`dc_power`	Calculates DC power from voltage and current
`ac_power_three_phase`	Calculates real power from line to neutral voltage and current

mhkit.wave.performance.ac_power_three_phase(voltage, current, power_factor, line_to_line=False)[source]¶

Calculates real power from line to neutral voltage and current

Parameters

voltage (pandas DataFrame) – Time series of all three measured voltage phases [V] indexed by time
current (pandas DataFrame) – Time series of all three measured current phases [A] indexed by time
power_factor (float) – Power factor for the system
line_to_line (bool) – Set to true if the given voltage measurements are line_to_line

Returns

P (pandas DataFrame) – Total power [W] indexed by time

mhkit.wave.performance.capture_length(P, J)[source]¶

Calculates the capture length (often called capture width).

Parameters

P (numpy array or pandas Series) – Power [W]
J (numpy array or pandas Series) – Omnidirectional wave energy flux [W/m]

Returns

L (numpy array or pandas Series) – Capture length [m]

mhkit.wave.performance.capture_length_matrix(Hm0, Te, L, statistic, Hm0_bins, Te_bins)[source]¶

Generates a capture length matrix for a given statistic

Note that IEC/TS 62600-100 requires capture length matrices for the mean, std, count, min, and max.

Parameters

Hm0 (numpy array or pandas Series) – Significant wave height from spectra [m]
Te (numpy array or pandas Series) – Energy period from spectra [s]
L (numpy array or pandas Series) – Capture length [m]
statistic (string) – Statistic for each bin, options include: ‘mean’, ‘std’, ‘median’, ‘count’, ‘sum’, ‘min’, ‘max’, and ‘frequency’. Note that ‘std’ uses a degree of freedom of 1 in accordance with IEC/TS 62600-100.
Hm0_bins (numpy array) – Bin centers for Hm0 [m]
Te_bins (numpy array) – Bin centers for Te [s]

Returns

LM (pandas DataFrames) – Capture length matrix with index equal to Hm0_bins and columns equal to Te_bins

mhkit.wave.performance.dc_power(voltage, current)[source]¶

Calculates DC power from voltage and current

Parameters

voltage (pandas Series or DataFrame) – Measured DC voltage [V] indexed by time
current (pandas Series or DataFrame) – Measured three phase current [A] indexed by time

Returns

P (pandas DataFrame) – DC power [W] from each channel and gross power indexed by time

mhkit.wave.performance.mean_annual_energy_production_matrix(LM, JM, frequency)[source]¶

Calculates mean annual energy production (MAEP) from matrix data along with data frequency in each bin

Parameters

LM (pandas DataFrame) – Capture length
JM (pandas DataFrame) – Wave energy flux
frequency (pandas DataFrame) – Data frequency for each bin

Returns

maep (float) – Mean annual energy production

mhkit.wave.performance.mean_annual_energy_production_timeseries(L, J)[source]¶

Calculates mean annual energy production (MAEP) from time-series

Parameters

L (numpy array or pandas Series) – Capture length
J (numpy array or pandas Series) – Wave energy flux

Returns

maep (float) – Mean annual energy production

mhkit.wave.performance.power_matrix(LM, JM)[source]¶

Generates a power matrix from a capture length matrix and wave energy flux matrix

Parameters

LM (pandas DataFrame) – Capture length matrix
JM (pandas DataFrame) – Wave energy flux matrix

Returns

PM (pandas DataFrames) – Power matrix

mhkit.wave.performance.statistics(X)[source]¶

Calculates statistics, including count, mean, standard deviation (std), min, percentiles (25%, 50%, 75%), and max.

Note that std uses a degree of freedom of 1 in accordance with IEC/TS 62600-100.

Parameters: X (numpy array or pandas Series) – Data
Returns: stats (pandas Series) – Statistics

mhkit.wave.performance.wave_energy_flux_matrix(Hm0, Te, J, statistic, Hm0_bins, Te_bins)[source]¶

Generates a wave energy flux matrix for a given statistic

Parameters

Hm0 (numpy array or pandas Series) – Significant wave height from spectra [m]
Te (numpy array or pandas Series) – Energy period from spectra [s]
J (numpy array or pandas Series) – Wave energy flux from spectra [W/m]
statistic (string) – Statistic for each bin, options include: ‘mean’, ‘std’, ‘median’, ‘count’, ‘sum’, ‘min’, ‘max’, and ‘frequency’. Note that ‘std’ uses a degree of freedom of 1 in accordance of IEC/TS 62600-100.
Hm0_bins (numpy array) – Bin centers for Hm0 [m]
Te_bins (numpy array) – Bin centers for Te [s]

Returns

JM (pandas DataFrames) – Wave energy flux matrix with index equal to Hm0_bins and columns equal to Te_bins

Graphics¶

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

`plot_elevation_timeseries`	Plot wave surface elevation time-series
`plot_spectrum`	Plots wave amplitude spectrum versus omega
`plot_matrix`	Plots values in the matrix as a scatter diagram

mhkit.wave.graphics.plot_elevation_timeseries(eta, ax=None)[source]¶

Plot wave surface elevation time-series

Parameters

eta (pandas DataFrame) – Wave surface elevation [m] indexed by time [datetime or s]
ax (matplotlib axes object) – Axes for plotting. If None, then a new figure is created.

Returns

ax (matplotlib pyplot axes)

mhkit.wave.graphics.plot_matrix(M, xlabel='Te', ylabel='Hm0', zlabel=None, show_values=True, ax=None)[source]¶

Plots values in the matrix as a scatter diagram

Parameters

M (pandas DataFrame) – Matrix with numeric labels for x and y axis, and numeric entries. An example would be the average capture length matrix generated by mhkit.device.wave, or something similar.
xlabel (string (optional)) – Title of the x-axis
ylabel (string (optional)) – Title of the y-axis
zlabel (string (optional)) – Colorbar label
show_values (bool (optional)) – Show values on the scatter diagram
ax (matplotlib axes object) – Axes for plotting. If None, then a new figure is created.

Returns

ax (matplotlib pyplot axes)

mhkit.wave.graphics.plot_spectrum(S, ax=None)[source]¶

Plots wave amplitude spectrum versus omega

Parameters

S (pandas DataFrame) – Spectral density [m^2/Hz] indexed frequency [Hz]
ax (matplotlib axes object) – Axes for plotting. If None, then a new figure is created.

Returns

ax (matplotlib pyplot axes)