Loads Module

The loads module contains a set of functions to calculate quantities of interest for mechanical loads assessments.

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.

General

The graphics submodule contains functions to compute loads related metrics.

Functions

Description

bin_statistics

Bins calculated statistics against data signal (or channel) according to IEC TS 62600-3:2020 ED1.

damage_equivalent_load

Calculates the damage equivalent load of a single data signal (or channel) based on IEC TS 62600-3:2020 ED1.

blade_moments

Transfer function for deriving blade flap and edge moments using blade matrix.
mhkit.loads.general.bin_statistics(data, bin_against, bin_edges, varargin)

Bins calculated statistics against data signal (or channel) according to IEC TS 62600-3:2020 ED1.

Parameters:

  • data (Strucutre or Table with handles- data.data and data.time) – data.data contains a vector or matrix containing time-series statistics of variables

  • bin_against (vector) – Data signal to bin data against (ie. current speed)

  • bin_edges (vector) – Bin edges with consistent step size.

  • data_signal (cell array (optional)) – List of data signal(s) to bin, default = all data signals

Returns:

bins (structure)

bins.averages = means of each bin

bins.std = standard deviation of each bin

mhkit.loads.general.blade_moments(blade_coefficients, flap_offset, flap_raw, edge_offset, edge_raw)

Transfer function for deriving blade flap and edge moments using blade matrix.

Parameters:

  • blade_coefficients (vector) – Derived blade calibration coefficients listed in order of D1, D2, D3, D4

  • flap_offset (double or int) – Derived offset of raw flap signal obtained during calibration process

  • flap_raw (vector) – Raw strain signal of blade in the flapwise direction

  • edge_offset (double or int) – Derived offset of raw edge signal obtained during calibration process

  • edge_raw (vector) – Raw strain signal of blade in the edgewise direction

Returns:

  • M_flap (vector) – Blade flapwise moment in SI units

  • M_edge (vector) – Blade edgewise moment in SI units

mhkit.loads.general.damage_equivalent_load(data_signal, m, options)

Calculates the damage equivalent load of a single data signal (or channel) based on IEC TS 62600-3:2020 ED1. 4-point rainflow counting algorithm from fatpack module is based on the following resources:

  • C. Amzallag et. al. Standardization of the rainflow counting method for fatigue analysis. International Journal of Fatigue, 16 (1994) 287-293 ISO 12110-2, Metallic materials - Fatigue testing - Variable amplitude fatigue testing.

  • G. Marsh et. al. Review and application of Rainflow residue processing techniques for accurate fatigue damage estimation. International Journal of Fatigue, 82 (2016) 757-765

Parameters:

  • data_signal (vector) – Data signal being analyzed

  • m (double or int) – Fatigue slope factor of material

  • bin_num (int (optional)) – Number of bins for rainflow counting method (minimum=100) to call: get_DELs(data,chan_info,”bin_num”,binNum)

  • data_length (double or int (optional)) – Length of data in sec. Default for 1Hz is 600 seconds for 10min data to call: get_DELs(data,chan_info,”data_length”,t)

Returns:

DEL (Structure) – Damage equivalent load of signal

Extreme

The extreme submodule contains tools and functions for extreme value analysis and wave data statistics. It includes methods for calculating peaks over threshold, estimating short-term extreme distributions,and performing wave amplitude normalization for most likely extreme response analysis.

Functions

Description

block_maxima

Find the block maxima of a time-series.

full_seastate_long_term_extreme

Return the long-term extreme distribution of a response of interest using the full sea state approach.

global_peaks

Find the global peaks of a zero-centered response time-series.

mler_coefficients

Calculate MLER (most likely extreme response) coefficients from a sea state spectrum and a response RAO.

mler_export_time_series

Generate the wave amplitude time series at X0 from the calculated MLER coefficients

mler_simulation

Define the simulation parameters that are used in various MLER functionalities.

mler_wave_amp_normalize

Renormalizes the incoming amplitude of the MLER wave to the desired peak height (peak to MSL).

number_of_short_term_peaks

Estimate the number of peaks in a specified period.

peaks_distribution_peaks_over_threshold

Estimate the peaks distribution by fitting a generalized Pareto distribution.

peaks_distribution_weibull

Estimate the peaks distribution by fitting a Weibull distribution to the peaks of the response.

peaks_distribution_weibull_tail_fit

Estimate the peaks distribution by using the Weibull tail fit method.

short_term_extreme

Estimate the peaks distribution by fitting a Weibull distribution to the peaks of the response.

ste_block_maxima_gev

Approximate the short-term extreme distribution using the block maxima method and the Generalized Extreme Value distribution.

ste_block_maxima_gumbel

Approximate the short-term extreme distribution using the block maxima method and the Gumbel (right) distribution.

ste_peaks

Estimate the peaks distribution by fitting a Weibull distribution to the peaks of the response.
mhkit.loads.extreme.block_maxima(t, x, t_st)

Find the block maxima of a time-series.

The timeseries (t,x) is divided into blocks of length t_st, and the maxima of each block is returned.

Parameters:

  • t (array) – Time array

  • x (array) – Global peaks time-series

  • t_st – Short-term period

mhkit.loads.extreme.full_seastate_long_term_extreme(ste_all, weights, x, method, options)

Return the long-term extreme distribution of a response of interest using the full sea state approach.

Parameters:

  • ste_all (cell array) – Short-term extreme distribution of the quantity of interest for each sample sea state.

  • weights – The weights from the full sea state sampling

mhkit.loads.extreme.global_peaks(t, data)

Find the global peaks of a zero-cenered response time-series.

The global peaks are the maxima between consecutive zero up-crossings.

Parameters:

  • t (array) – Time array

  • data – Response time-series

mhkit.loads.extreme.mler_coefficients(RAO, wave_spectrum, response_desired)

Calculate MLER (most likely extreme response) coefficients from a sea state spectrum and a response RAO.

Parameters:

  • RAO (array) – Response amplitude operator [-]

  • wave_spectrum (struct) – Struct with wave spectral density [m^2/Hz] and frequency [Hz]

  • response_desired – Latitude longitude pairs at which to extract data.

mhkit.loads.extreme.mler_export_time_series(RAO, mler, sim, k)

Generate the wave amplitude time series at X0 from the calculated MLER coefficients

Parameters:

  • RAO (array) – Response amplitude operator.

  • mler (struct) – MLER coefficients dataframe generated from an MLER function.

  • sim (struct) – Simulation parameters formatted by output from ‘mler_simulation’.

  • k (array) – Wave number.

Returns:

mler_ts (struct) – Contains resulting wave height [m] and linear response [*] indexed by time [s].

mhkit.loads.extreme.mler_simulation(sim)

Define the simulation parameters that are used in various MLER functionalities. If no input is given, then default values are returned.

Parameters:

sim – Simulation parameters Keys: —– ‘startTime’: starting time [s] ‘endTime’: ending time [s] ‘dT’: time-step size [s] ‘T0’: time of maximum event [s] ‘startX’: start of simulation space [m] ‘endX’: end of simulation space [m] ‘dX’: horizontal spacing [m] ‘X0’: position of maximum event [m]

mhkit.loads.extreme.mler_wave_amp_normalize(wave_amp, mler, sim, k)

Function that renormalizes the incoming amplitude of the MLER wave to the desired peak height (peak to MSL).

Parameters:

  • wave_amp (float) – Desired wave amplitude (peak to MSL).

  • mler (struct) – MLER coefficients generated by ‘mler_coefficients’ function.

  • sim (struct) – Simulation parameters formatted by output from ‘mler_simulation’.

  • k (array) – Wave number.

Returns:

mler_norm (struct) – Normalized MLER coefficients

mhkit.loads.extreme.number_of_short_term_peaks(n, t, t_st)

Estimate the number of peaks in a specified period.

Parameters:

  • n (int) – Number of peaks in analyzed timeseries.

  • t (double) – Length of time of analyzed timeseries.

  • t_st – Short-term period for which to estimate the number of peaks.

mhkit.loads.extreme.peaks_distribution_peaks_over_threshold(peaks, x, method, options)

Estimate the peaks distribution by fitting a Weibull distribution to the peaks of the response.

To learn more about the methods that can be used in this function, refer to the scipy.stats.rv_continuous methods documentation!

Parameters:

  • peaks (array) – Global peaks

  • x (array or double) – Input for the statistical function/method

  • method (str) – Statistical method to apply to resulting data. Options to choose from are: “pdf”, “cdf”, “ppf”, or “sf”

  • threshold – Threshold value. Only peaks above this value will be used. Default value calculated as: mean(x) + 1.4 * std(x)

mhkit.loads.extreme.peaks_distribution_weibull(peaks, x, method)

Estimate the peaks distribution by fitting a Weibull distribution to the peaks of the response.

To learn more about the methods that can be used in this function, refer to the scipy.stats.rv_continuous methods documentation!

Parameters:

  • peaks (array) – Global peaks

  • x (array or double) – Input for the statistical function/method

  • method – Statistical method to apply to resulting data. Options to choose from are: “pdf”, “cdf”, “ppf”, or “sf”

mhkit.loads.extreme.peaks_distribution_weibull_tail_fit(peaks, x, method)

Estimate the peaks distribution by using the Weibull tail fit method.

To learn more about the methods that can be used in this function, refer to the scipy.stats.rv_continuous methods documentation!

Parameters:

  • peaks (array) – Global peaks

  • x (array or double) – Input for the statistical function/method

  • method – Statistical method to apply to resulting data. Options to choose from are: “pdf”, “cdf”, “ppf”, or “sf”

mhkit.loads.extreme.short_term_extreme(t, data, t_st, type, x, method, options)

Estimate the peaks distribution by fitting a Weibull distribution to the peaks of the response.

To learn more about the methods that can be used in this function, refer to the scipy.stats.rv_continuous methods documentation!

Parameters:

  • t (array) – Time array

  • data (array) – Response timeseries

  • t_st (double or int) – Short time period

  • type (string) – Method for estimating the short-term extreme distribution

  • x (array or double) – Input for the statistical function/method

  • method (str) – Statistical method to apply to resulting data. Options to choose from are: “pdf”, “cdf”, “ppf”, or “sf”

  • output_py – Select if you want to return the native python result for use in long term extreme calculations.

mhkit.loads.extreme.ste_block_maxima_gev(block_maxima, x, method)

Approximate the short-term extreme distribution using the block maxima method and the Generalized Extreme Value distribution.

To learn more about the methods that can be used in this function, refer to the scipy.stats.rv_continuous methods documentation!

Parameters:

  • block_maxima (array) – Block maxima (i.e. largest peak in each block).

  • x (array) – Input for the statistical function/method

  • method – Statistical method to apply to resulting data. Options to choose from are: “pdf”, “cdf”, “ppf”, or “sf”

mhkit.loads.extreme.ste_block_maxima_gumbel(block_maxima, x, method)

Approximate the short-term extreme distribution using the block maxima method and the Gumbel (right) distribution.

To learn more about the methods that can be used in this function, refer to the scipy.stats.rv_continuous methods documentation!

Parameters:

  • block_maxima (array) – Block maxima (i.e. largest peak in each block)

  • x (array or double) – Input for the statistical function/method

  • method – Statistical method to apply to resulting data. Options to choose from are: “pdf”, “cdf”, “ppf”, or “sf”

mhkit.loads.extreme.ste_peaks(peaks_distribution, npeaks, x, method)

Estimate the peaks distribution by fitting a Weibull distribution to the peaks of the response.

To learn more about the methods that can be used in this function, refer to the scipy.stats.rv_continuous methods documentation!

Parameters:

  • peaks_distribution (scipy.stats.rv_frozen) – Probability distribution of the peaks

  • npeaks (double or int) – Number of peaks in short term period

  • x (array or double) – Input for the statistical function/method

  • method – Statistical method to apply to resulting data. Options to choose from are: “pdf”, “cdf”, “ppf”, or “sf”

Graphics

The graphics submodule contains functions to plot loads data and related metrics. The functions are designed to work in parallel with the general submodule.

Functions

Description

plot_statistics

Plot showing standard raw statistics of variable

plot_bin_statistics

Plot showing standard binned statistics of single variable
mhkit.loads.graphics.plot_bin_statistics(bin_centers, bin_mean, bin_max, bin_min, bin_mean_std, bin_max_std, bin_min_std, options)

Plot showing standard binned statistics of single variable

Parameters:

  • bin_centers (vector) – x-axis bin center values

  • bin_mean (vector) – Binned mean statistical values of variable

  • bin_max (vector) – Binned max statistical values of variable

  • bin_min (vector) – Binned min statistical values of variable

  • bin_mean_std (vector) – Standard deviations of mean binned statistics

  • bin_max_std (vector) – Standard deviations of max binned statistics

  • bin_min_std (vector) – Standard deviations of min binned statistics

  • xlabel (string (optional)) – x-axis lable for the plot to call: binplotter(bcenters,bmean,bmax,bmin,bstdmean,bstdmax,bstdmin,”xlable”,xlable)

  • ylabel (string (optional)) – y-axis lable for the plot to call: binplotter(bcenters,bmean,bmax,bmin,bstdmean,bstdmax,bstdmin,”ylable”,ylable)

  • title (string (optional)) – title for the plot to call: binplotter(bcenters,bmean,bmax,bmin,bstdmean,bstdmax,bstdmin,”title”,title)

  • savepath (string (optional)) – path and filename to save figure. to call: binplotter(bcenters,bmean,bmax,bmin,bstdmean,bstdmax,bstdmin,”savepath”,savepath)

Returns:

figure (figure)

mhkit.loads.graphics.plot_statistics(x, y_mean, y_min, y_max, options)

Plot showing standard raw statistics of variable

Parameters:

  • x (vector) – vector of x-axis values

  • y_mean (vector) – Vector of mean values

  • y_max (vector) – Vector of max values

  • y_min (vector) – Vector of min values

  • y_stdev (vector (optional)) – Vector of stand drviations to call: statplotter(x,y_mean,y_max,y_min,”y_stdev”,vstdev)

  • xlabel (string (optional)) – x-axis lable for the plot to call: statplotter(x,y_mean,y_max,y_min,”xlable”,xlable)

  • ylabel (string (optional)) – y-axis lable for the plot to call: statplotter(x,y_mean,y_max,y_min,”ylable”,ylable)

  • title (string (optional)) – title for the plot to call: statplotter(x,y_mean,y_max,y_min,”title”,title)

  • savepath (string (optional)) – path and filename to save figure. to call: statplotter(x,y_mean,y_max,y_min,”savepath”,savepath)

Returns:

figure (figure) – scatter plot of statistics