Wave Module

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

Note

The names of the functions below are of the convention path.path.function. Only the function name is used when calling the function in MATLAB. For example, to call on mhkit.wave.io.read_NDBC_file simply use read_NDBC_file.

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.

Functions

Description

read_NDBC_file

Reads a NDBC wave buoy data file (from https://www.ndbc.noaa.gov) into a structure.
mhkit.wave.io.read_NDBC_file(file_name, varargin)

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

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 (vector of values (optional)) – vector of values that denote missing data

Returns

data (Structure)

data.Data: named according to header row

data.time: given in datetime

data.units: the units for each data entry

Resource

The resource submodule contains methods to compute wave energy spectra and various metrics from the spectra.

The following options exist to compute wave energy spectra:

Functions

Description

create_spectra

Calculates a spectra of user defined type.

elevation_spectrum

Calculates wave spectra from wave probe timeseries.

The following metrics can be computed from the spectra:

Functions

Description

average_crest_period

Calculate the average creat period from spectra.

average_wave_period

Calculates the average wave period from spectra

average_zero_crossing_period

Calculates wave average zero crossing period from spectra

energy_flux

Calculates the omnidirectional wave energy flux of the spectra

energy_period

Calculates the energy period

frequency_moment

Calculates the Nth frequency moment of the spectrum

peak_period

Calculates wave energy period from spectra

significant_wave_height

Calculates wave height from spectra

spectral_bandwidth

Calculates bandwidth from spectra

spectral_width

Calculates wave spectral width from spectra

surface_elevation

Calculates wave elevation time series from spectrum using a random phase

wave_celerity

Calculates wave celerity (group velocity)

wave_number

Calculates wave number
mhkit.wave.resource.average_crest_period(S, varargin)

Calculates the average crest period

Parameters

S (Spectral Density (m^2/Hz)) –

Pandas data frame

To make a pandas data frame from user supplied frequency and spectra use py.mhkit_python_utils.pandas_dataframe.spectra_to_pandas(frequency,spectra)

OR

structure of form:

S.spectrum: Spectral Density (m^2/Hz)

S.type: String of the spectra type, i.e. Bretschneider, time series, date stamp etc.

S.frequency: frequency (Hz)

frequency_bins: vector (optional)

Bin widths for frequency of S. Required for unevenly sized bins

Returns

Tavg (double) – Average crest Period (s)

mhkit.wave.resource.average_wave_period(S, varargin)

Calculates the average wave period

Parameters

S (Spectral Density (m^2/Hz)) –

Pandas data frame

To make a pandas data frame from user supplied frequency and spectra use py.mhkit_python_utils.pandas_dataframe.spectra_to_pandas(frequency,spectra)

OR

structure of form:

S.spectrum: Spectral Density (m^2/Hz)

S.type: String of the spectra type, i.e. Bretschneider, time series, date stamp etc.

S.frequency: frequency (Hz)

frequency_bins: vector (optional)

Bin widths for frequency of S. Required for unevenly sized bins

Returns

Tavg (float) – Mean wave period (s)

mhkit.wave.resource.average_zero_crossing_period(S, varargin)

Calculates wave average zero crossing period from spectra

Parameters

S (Spectral Density (m^2/Hz)) –

Pandas data frame

To make a pandas data frame from user supplied frequency and spectra use py.mhkit_python_utils.pandas_dataframe.spectra_to_pandas(frequency,spectra,x)

OR

structure of form:

S.spectrum: Spectral Density (m^2/Hz)

S.type: String of the spectra type, i.e. Bretschneider, time series, date stamp etc.

S.frequency: frequency (Hz)

frequency_bins: vector (optional)

Bin widths for frequency of S. Required for unevenly sized bins

Returns

Tz (double) – Average Zero Crossing Period (s)

mhkit.wave.resource.create_spectra(spectra_type, frequency, Tp, varargin)

Calculates wave spectra of user specified type

Parameters

  • spectraType (String of spectra type) – Options are: ‘pierson_moskowitz_spectrum’, ‘bretschneider_spectrum’, or ‘jonswap_spectrum’

  • Frequency (float) – Wave frequency (Hz)

  • Tp (float) – Peak Period (s)

  • Hs (float - Required for 'bretschneider_spectrum', and 'jonswap_spectrum') – Significant Wave Height (s)

  • gamma (float (optional)) – only an optional parameter for ‘jonswap_spectrum’

Returns

S (structure)

S.spectrum=Spectral Density (m^2/Hz)

S.type=String of the spectra type, i.e. Bretschneider, time series, date stamp etc.

S.frequency= frequency (Hz)

S.Te

S.Hm0

mhkit.wave.resource.elevation_spectrum(ts, sample_rate, nnft, time, varargin)

Calculates wave spectra from wave probe timeseries

Parameters

  • ts (matrix or table) – Wave probe time-series data, with each column a different time series

  • sampleRate (float) – Data frequency (Hz)

  • nnft (int) –

  • time (vector or table) – time (s)

  • window (string scalar (Optional)) – Signal window type. “hamming” is used by default given the broadband nature of waves. See scipy.signal.get_window for more options.

  • detrend (logical (Optional)) – Specifies if a linear trend is removed from the data before calculating the wave energy spectrum. Data is detrended by default.

Returns

S (structure)

S.spectrum: vector or matrix Spectral Density (m^2/Hz) per probe

S.type: ‘Spectra from Time Series’

S.frequency: frequency [Hz]

S.sample_rate: sample_rate

S.nnft: nnft

mhkit.wave.resource.energy_flux(S, h, varargin)
Parameters

  • S (Spectral Density (m^2/Hz)) –

    Pandas data frame

    To make a pandas data frame from user supplied frequency and spectra use py.mhkit_python_utils.pandas_dataframe.spectra_to_pandas(frequency,spectra)

    OR

    structure of form:

    S.spectrum: Spectral Density (m^2/Hz)

    S.type: String of the spectra type, i.e. Bretschneider, time series, date stamp etc.

    S.frequency: frequency (Hz)

  • h (float) – Water depth (m)

  • rho (float (optional)) – water density (kg/m^3)

  • g (float (optional)) –

    gravitational acceleration (m/s^2)

    NOTE: In matlab, if you set one optional parameter, you must set both, rho first, then g

Returns

J (double) – Omni-directional wave energy flux (W/m)

mhkit.wave.resource.energy_period(S, varargin)
Parameters

S (Spectral Density (m^2/Hz)) –

Pandas data frame

To make a pandas data frame from user supplied frequency and spectra use py.mhkit_python_utils.pandas_dataframe.spectra_to_pandas(frequency,spectra)

OR

structure of form:

S.spectrum: Spectral Density (m^2/Hz)

S.type: String of the spectra type, i.e. Bretschneider, time series, date stamp etc.

S.frequency: frequency (Hz)

frequency_bins: vector (optional)

Bin widths for frequency of S. Required for unevenly sized bins

Returns

Te (float) – Wave energy Period (s)

mhkit.wave.resource.frequency_moment(S, N, varargin)

Calculates the Nth frequency moment of the spectrum

Parameters

  • S (Spectral Density (m^2/Hz)) –

    Pandas data frame

    To make a pandas data frame from user supplied frequency and spectra use py.mhkit_python_utils.pandas_dataframe.spectra_to_pandas(frequency,spectra)

    OR

    structure of form:

    S.spectrum: Spectral Density (m^2/Hz)

    S.type: String of the spectra type, i.e. Bretschneider, time series, date stamp etc.

    S.frequency: frequency (Hz)

  • N (int) – Moment (0 for 0th, 1 for 1st ….)

  • frequency_bins (vector (optional)) – Bin widths for frequency of S. Required for unevenly sized bins

Returns

m (double)

mhkit.wave.resource.peak_period(S)

Calculates wave energy period from spectra

Parameters

S (Spectral Density (m^2/Hz)) –

Pandas data frame

To make a pandas data frame from user supplied frequency and spectra use py.mhkit_python_utils.pandas_dataframe.spectra_to_pandas(frequency,spectra)

OR

structure of form:

S.spectrum: Spectral Density (m^2/Hz)

S.type: String of the spectra type, i.e. Bretschneider, time series, date stamp etc.

S.frequency: frequency (Hz)

Returns

Tp float – Wave Peak Period (s)

mhkit.wave.resource.significant_wave_height(S, varargin)

Calculates wave height from spectra

Parameters

  • S (Spectral Density (m^2/Hz)) –

    Pandas data frame

    To make a pandas data frame from user supplied frequency and spectra use py.mhkit_python_utils.pandas_dataframe.spectra_to_pandas(frequency,spectra)

    OR

    structure of form:

    S.spectrum: Spectral Density (m^2/Hz)

    S.type: String of the spectra type, i.e. Bretschneider, time series, date stamp etc.

    S.frequency: frequency (Hz)

  • frequency_bins (vector (optional)) – Bin widths for frequency of S. Required for unevenly sized bins

Returns

Hm0 (double) – Significant Wave Height (m)

mhkit.wave.resource.spectral_bandwidth(S, varargin)

Calculates bandwidth from spectra

Parameters

S (Spectral Density (m^2/Hz)) –

Pandas data frame

To make a pandas data frame from user supplied frequency and spectra use py.mhkit_python_utils.pandas_dataframe.spectra_to_pandas(frequency,spectra)

OR

structure of form:

S.spectrum: Spectral Density (m^2/Hz)

S.type: String of the spectra type, i.e. Bretschneider, time series, date stamp etc.

S.frequency: frequency (Hz)

frequency_bins: vector (optional)

Bin widths for frequency of S. Required for unevenly sized bins

Returns

e (double) – Spectral BandWidth

mhkit.wave.resource.spectral_width(S, varargin)

Calculates wave spectral width from spectra

Parameters

S (Spectral Density (m^2/Hz)) –

Pandas data frame

To make a pandas data frame from user supplied frequency and spectra use py.mhkit_python_utils.pandas_dataframe.spectra_to_pandas(frequency,spectra)

OR

structure of form:

S.spectrum: Spectral Density (m^2/Hz)

S.type: String of the spectra type, i.e. Bretschneider, time series, date stamp etc.

S.frequency: frequency (Hz)

frequency_bins: vector (optional)

Bin widths for frequency of S. Required for unevenly sized bins

Returns

e0 (float) – Spectral Width

mhkit.wave.resource.surface_elevation(S, time_index, options)

Calculates wave elevation time series from spectrum using a random phase

Parameters

  • S (Spectral Density (m^2/Hz)) –

    Pandas data frame

    To make a pandas data frame from user supplied frequency and spectra use py.mhkit_python_utils.pandas_dataframe.spectra_to_pandas(frequency,spectra)

    OR

    structure of form:

    S.spectrum: Spectral Density (m^2/Hz)

    S.type: String of the spectra type, i.e. Bretschneider, time series, date stamp etc.

    S.frequency: frequency (Hz)

  • time_index (array) – Time used to create the wave elevation time series [s]

  • seed (Int (optional)) – random seed to call: wave_elevation(S,time_index,”seed”,seed)

  • frequency_bins (vector (optional)) – Bin widths for frequency of S. Required for unevenly sized bins to call: wave_elevation(S,time_index,”frequency_bins”,frequency_bins)

  • phases (vector or matrix (optional)) – Explicit phases for frequency components (overrides seed) to call: wave_elevation(S,time_index,”phases”,phases)

Returns

wave_elevation (structure)

wave_elevation.elevation: Wave surface elevation (m)

wave_elevation.type: ‘Time Series from Spectra’

wave_elevation.time

mhkit.wave.resource.wave_celerity(k, h, varargin)

Calculates wave celerity (group velocity)

Parameters

  • k (wave number (1/m)) –

    Pandas data frame

    To make a pandas data frame from user supplied frequency and spectra use py.mhkit_python_utils.pandas_dataframe.spectra_to_pandas(frequency,spectra)

    OR

    structure of form:

    k.values= wave number

    k.frequency= frequency (Hz)

  • h (float) – Water depth (m)

  • g (float (optional)) – gravitational acceleration (m/s^2)

Returns

Cg (structure)

Cg.values: water celerity

Cg.frequency [Hz]

Cg.h: height [m]

mhkit.wave.resource.wave_number(f, h, varargin)

Calculates wave number

Parameters

  • f (frequency (Hz)) – vector or numpy array

  • h (float) – Water depth (m)

  • rho (float (optional)) – water density (kg/m^3)

  • g – gravitational acceleration (m/s^2)

Returns

k (structure)

k.values: wave number

k.frequency: frequency [Hz]

Performance

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

Functions

Description

dc_power

Calculates the real power from DC voltage and current.

ac_power_three_phase

Calculates the real power from three phase ac voltage and current.

capture_length

Calculates the capture length (often called capture width).

capture_length_matrix

Generates a capture length matrix for a given statistic

mean_annual_energy_production_matrix

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

mean_annual_energy_production_timeseeries

Calculates mean annual energy production (MAEP) from timeseries

power_matrix

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

wave_energy_flux_matrix

Generates a wave eneergy flux matrix for a given statistic
mhkit.wave.performance.ac_power_three_phase(voltage, current, power_factor, varargin)

Calculates the real power from three phase ac voltage and current.

Parameters

  • voltage (Time series of all three measured voltages [V]) –

    Pandas data frame

    To make a pandas data frame from user supplied frequency and spectra use py.mhkit_python_utils.pandas_dataframe.spectra_to_pandas(time,voltage)

    OR

    structure of form:

    voltage.voltage : matrix of all three phases

    voltage.time : time vector

  • current (Time series of all three measured current [A]) –

    Pandas data frame

    To make a pandas data frame from user supplied frequency and spectra use py.mhkit_python_utils.pandas_dataframe.spectra_to_pandas(time,current)

    OR

    structure of form:

    current.current : matrix of all three phases

    current.time : time vector

    power_factorfloat

    power factor for the system

    line_to_line: bool (Optional)

    set true if the given voltage measuremtn is line_to_line

Returns

P (Structure)

P.power [W]

P.time

mhkit.wave.performance.capture_length(Power, J)

Calculates the capture length (often called capture width).

Parameters

  • P (array or vector) – Power [W]

  • J (array or vector) – Omnidirectional wave energy flux [W/m]

Returns

L (vector) – Capture length [m]

mhkit.wave.performance.capture_length_matrix(Hm0, Te, L, statistic, Hm0_bins, Te_bins)

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 vector) – Significant wave height from spectra [m]

  • Te (numpy array or vector) – Energy period from spectra [s]

  • L (numpy array or vector) – 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. or a callable function of python type

  • Hm0_bins (numpy array or vector) – Bin centers for Hm0 [m]

  • Te_bins (numpy array or vector) – Bin centers for Te [s]

Returns

clm (structure)

clm.values

clm.stat

clm.Hm0_bins

clm.Te_bins

mhkit.wave.performance.dc_power(voltage, current)

Calculates the real power from DC voltage and current.

Parameters

  • voltage (Time series of measured voltages [V]) –

    Pandas data frame

    To make a pandas data frame from user supplied frequency and spectra use py.mhkit_python_utils.pandas_dataframe.spectra_to_pandas(time,voltage)

    OR

    structure of form:

    voltage.voltage : matrix or vector

    voltage.time : time vector

  • current (Time series of current [A]) –

    Pandas data frame

    To make a pandas data frame from user supplied frequency and spectra use py.mhkit_python_utils.pandas_dataframe.spectra_to_pandas(time,current)

    OR

    structure of form:

    current.current : matrix or vector

    current.time : time vector

Returns

P (Structure)

P.power [W]

P.gross: gross power from all lines [W]

P.time

mhkit.wave.performance.mean_annual_energy_production_matrix(LM, JM, frequency)

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

Parameters

LM –

Pandas data frame

To make a pandas data frame from user supplied frequency and spectra use py.mhkit_python_utils.pandas_dataframe.spectra_to_pandas(Hm0_bins,L)

OR

structure of form:

LM.values

LM.stat

LM.Hm0_bins

LM.Te_bins

Returns

maep (float) – Mean annual energy production

mhkit.wave.performance.mean_annual_energy_production_timeseries(L, J)

Calculates mean annual energy production (MAEP) from timeseries

Parameters

  • L (numpy array or vector) – Capture length

  • J (numpy array or vector) – Wave energy flux

Returns

maep (float) – Mean annual energy production

mhkit.wave.performance.power_matrix(LM, JM)

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

Parameters

LM –

Pandas data frame

To make a pandas data frame from user supplied frequency and spectra use py.mhkit_python_utils.pandas_dataframe.spectra_to_pandas(Hm0_bins,L)

OR

structure of form:

LM.values

LM.stat

LM.Hm0_bins

LM.Te_bins

Returns

PM (Structure)

PM.values: Power matrix

PM.stat: statistic of the matrix (i.e. “mean”, “max”, etc.) (string)

PM.Hm0_bins

PM.Te_bins

mhkit.wave.performance.wave_energy_flux_matrix(Hm0, Te, J, statistic, Hm0_bins, Te_bins)

Generates a wave eneergy flux 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 vector) – Significant wave height from spectra [m]

  • Te (numpy array or vector) – Energy period from spectra [s]

  • J (numpy array or vector) – 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 with IEC/TS 62600-100.

  • Hm0_bins (numpy array or vector) – Bin centers for Hm0 [m]

  • Te_bins (numpy array or vector) – Bin centers for Te [s]

Returns

WEFM (Structure)

WEFM.values

WEFM.stat

WEFM.Hm0_bins

WEFM.Te_bins

Graphics

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

Functions

Description

plot_elevation_timeseries

Plots wave elevation timeseries

plot_matrix

Plots the matrix with Hm0 and Te on the y and x axis

plot_spectrum

Plots wave amplitude spectrum
mhkit.wave.graphics.plot_elevation_timeseries(wave_elevation)

Plots wave elevation timeseries

Parameters

wave_elevation (Structure of the following form:) –

wave_elevation.elevation: elevation [m]

wave_elevation.time: time (s);

Returns

figure (figure) – Plot of wave elevation vs. time

mhkit.wave.graphics.plot_matrix(M, Mtype)

Plots the matrix with Hm0 and Te on the y and x axis

Parameters

  • M (structure) –

    M.values: matrix

    M.Hm0_bins

    M.Te_bins

    M.stat

  • Mtype (string) – type of matrix (i.e. power, capture length, etc.) to be used in plot title

Returns

figure (plot of the matrix)

mhkit.wave.graphics.plot_spectrum(wave_spectra)

Plots wave amplitude spectrum

Parameters

wave_spectra (Structure of the following form:) –

wave_spectra.spectrum: Spectral Density (m^2-s;

wave_spectra.type: String of the spectra type, i.e. Bretschneider, time series, date stamp etc.

wave_spectra.frequency: frequency (Hz);

Returns

figure (figure) – Plot of wave amplitude spectra versus omega