4. Limit State¶

The design conditions, such as the design wave height and the damage number, are described in a limit state. A limit state is defined by standard NEN-EN 1990:2002 (2002), as the state beyond which the structure no longer fulfils the relevant design criteria. Two of the most common limit states are:

The Ultimate Limit State (ULS), which is the state associated with collapse of the breakwater or with other similar forms of failure
The Serviceability Limit State (SLS), which is the state that corresponds to the conditions beyond which specified service requirements for the breakwater or part of the breakwater are no longer met.

4.1. Define Limit State¶

class breakwater.conditions.LimitState(h, label, **kwargs)[source]¶

Generate LimitState for design

Define a design limit state, for instance the Ultimate Limit State (ULS) or Serviceability Limit State (SLS). The defined limit state[s] can then be given as arguments to design one of the supported breakwater types, see Table 1 for the required parameters for these design classes. A full list of possible arguments can be seen under Keyword Arguments.

Table 1: Required parameters for each design class

Parameter	RRM	CRM	RC	CC
h	x	x	x	x
q	x	x	x	x
H13	o ¹	o ¹	o ¹	o ¹
Hm0	o ¹	o ¹	o ¹	o ¹
H2_per	o ²
Hmax			x	x
Tm	o ³
T13			o ³	o ³
T_m_min_1	o ³	o ³	o ³	o ³
Nod	o ⁴	x
Sd	o ⁴

1 uses get_Hs() to get Hs, so at least one of the
wave heights must be given
2 if H2_per not specified in the limit state it is computed
with get_H2()
3 wave periods can be transformed in deep water with
transform_periods()
4 either Nod or Sd is required, the other can be computed
with Nod() or Sd()

Note

The design classes bw.RockRubbleMound, bw.ConcreteRubbleMound and bw.Caisson perform ¹ and ² automatically, but not ³ and ⁴

Parameters:

h (float) – the water depth [m]
label (str) – label to identify the LimitState, for instance ULS or SLS

Keyword Arguments:

q (float) – mean overtopping discharge per meter structure width [l/s per m]
Hs (float) – the significant wave height [m]
H13 (float) – mean of the highest 1/3 of the wave heights [m]
Hm0 (float) – the spectral wave height [m]
Ho (float) – deep water wave height [m]
H2_per (float) – the wave height exceeded by 2% of the waves [m]
Hmax (float) – design wave height for the Goda formula, equal to the mean of the highest 1/250 of the wave heights [m].
H1250 (float) – mean of the highest 1/250 of the wave heights [m], automatically interpreted as Hmax.
Tm (float) – the mean wave period [s]
T13 (float) – the significant wave period [s]
Ts (float) – the significant wave period [s]
T_m_min_1 (float) – \(T_{m-1.0}\), the energy wave period [s]
Tp (float) – the peak period [s]
Nod (float) – Damage number, used in the formula for the toe stability. Can also be computed with Nod() [-]
Sd (float) – Damage level parameter, used in Van der Meer formula. Can also be computed with Sd() [-]

conditions¶

Dictionary with all parameters

Type:	dict

deep_water¶

True if deep water assumption is valid, False if not valid. The bool is computed with the Tm, Tp, T_m_min_1 or T13 (in this order)

Type:	bool

h¶

the water depth [m]

Type:	float

label¶

identifier of the LimitState

Type:	str

L(period, deep_water=False)[source]¶

Compute the wave length with the dispersion relation

\[L = L_{o} \tanh \left( \frac{2 \pi h}{L}\right)\]

in which the deep water wave length is:

\[L_{o} = \frac{g T^{2}}{2 \pi}\]

Parameters:	period (str) – keyword argument of a wave period, must be in LimitState deep_water (bool, optional, default: False) – if False the dispersion relation will be used, if True the deep water wave length will be used. Note that this parameter is not equal to the attribute deep_water
Raises:	KeyError – If the specified wave period is not in the LimitState

Nod(G, nv)[source]¶

Compute the damage number Nod

This method approximates Nod by using equation 5.150 from the Rock Manual (CIRIA, CUR, CETMEF, 2007), and adds Nod to the LimitState. The equation to compute Nod is given as:

\[N_{od} = G (1 - n_{v}) S_{d}\]

Parameters:	G (float) – gradation factor [-] nv (float) – porosity of the armour layer [-]
Returns:	Nod (float) – damage number [-]
Raises:	KeyError – If Sd is not in the LimitState, use `Sd()` instead

Sd(G, nv)[source]¶

Compute the damage level parameter Sd

This method approximates Sd by using equation 5.150 from the Rock Manual (CIRIA, CUR, CETMEF, 2007), and adds Sd to the LimitState. The equation to compute Sd is given as:

\[S_{d} = \frac{N_{od}}{G (1 - n_{v})}\]

Parameters:	G (float) – gradation factor [-] nv (float) – porosity of the armour layer [-]
Returns:	Sd (float) – damage level parameter [-]
Raises:	KeyError – If Nod is not in the LimitState, use `Nod()` instead

check_deep_water()[source]¶

Check if the deep water assumption is valid

Deep water assumption is valid if h/L > 0.5, where L is computed with the dispersion relation using the mean period. Method updates the attribute deep_water based on the check.

Raises:	KeyError – If Tm is not in the LimitState

get_H2(slope_foreshore)[source]¶

Get the wave height exceeded by 2% of the waves, H2%

Attempts to return H2% from the defined limit state, if not defined in the limit state it is computed with BattjesGroenendijk.

Parameters:	slope_foreshore (float) – the slope of the foreshore [rad]
Returns:	H2_per (float) – the wave height exceeded by 2% of the waves [m]
Raises:	KeyError – If Hm0 is not in the LimitState

get_Hs(definition)[source]¶

Get the significant wave height

Multiple definitions are used for the significant wave height, and formulas use different definitions. This method returns the desired definition of the significant wave height. For overtopping this is Hm0 and H1/3 is used in the Van der Meer and Hudson formula.

Note

If Hm0, Hs or H13 are in the LimitState this method will always return a significant wave height. The table depicts the order in which Hs is returned if a value is missing. For example: if the chosen definition is Hm0, then first Hm0 is returned, if Hm0 is not included in the Limitstate Hs will be retuned, if Hs is also missing H13 will be returned.

definition	Hm0	Hs	H13
1	Hm0	Hs	H13
2	Hs	H13	Hs
3	H13	Hm0	Hm0

Parameters:	definition ({'Hm0', 'Hs', 'H13'}) – definition of the significant wave height to use
Returns:	Hs (float) – significant wave height based on the definition
Raises:	InputError – If there is no significant wave height (Hm0, Hs, H1/3) in the LimitState KeyError – If the definition is not ‘Hm0’, ‘H13’ or ‘Hs’

s(number=None, H=None, T=None)[source]¶

Compute the fictitious wave steepness

\[s_{0} = \frac{H}{L_{o}}\]

the fictitious wave steepness combines the value of the wave height at the location of the breakwater with the deep water wave length. It is possible to select a number or specify which wave height and period must be used for the computation.

Note

When computing the fictitious wave steepness the significant wave height is needed, to get the significant wave height form the LimitState the method get_Hs() is used.

Parameters:	number ({'mean', 'spectral'}, optional, default: None) – definition to use, will automatically select the correct definitions for H and T H (str, optional, default: None) – wave height in the LimitState T (str, optional, default: None) – wave period in the LimitState returns – s_0 (float) – the fictitious wave steepness
Raises:	InputError – If there is no significant wave height (Hm0, Hs, H1/3) in the LimitState. KeyError – if the specified wave period is not in the LimitState

surf_similarity(alpha, number=None, H=None, T=None)[source]¶

Compute the surf similarity parameter

\[\xi = \frac{tan{\alpha}}{\sqrt{s_{o}}}\]

Computes the surf similarity parameter, also known as the Iribarren number. It is possible to select a number or specify which wave height and period must be used for the computation.

Parameters:	alpha (float) – slope of the structure [rad] number ({'mean', 'spectral'}, optional, default: None) – definition to use, will automatically select the correct definitions for H and T H (str, optional, default: None) – wave height in the LimitState T (str, optional, default: None) – wave period in the LimitState
Returns:	xi (float) – the surf similarity parameter [-]
Raises:	InputError – If there is no significant wave height (Hm0, Hs, H1/3) in the LimitState KeyError – If the specified wave period is not in the LimitState

transform_periods(scalar)[source]¶

Transform the wave periods with the Rayleigh characteristics

Transforms the missing wave periods in the LimitState with the characteristics for Rayleigh distributed waves in deep water, by using the wave periods which are in the LimitState.

Table 2: characteristic wave periods (Van den Bos and Verhagen, 2018)

Name	T/Tp
\(T_{p}\)	1
\(T_{m}\)	0.75 to 0.85
\(T_{s}\)	0.90 to 0.95
\(T_{m-1.0}\)	1.1

Parameters:	scalar (float) – Should be between 0 and 1, 0 being the lower bound, 1 the upper bound of the characteristics. For instance, scalar of 1 results in Tm/Tp = 0.85.
Raises:	InputError – If the scalar is not between 0 and 1

4.2. Compute wave heights¶

Design criteria for coastal structures require, among other parameters, a certain type of characteristic wave height, for instance the significant wave height. In deep water the behaviour of the waves can be determined with the characteristic of the Rayleigh distribution. However, in shallow water the waves are no longer Rayleigh distributed, but a designer still wants to determine the significant wave height.

Two methods have been implemented to determine the nearshore wave characteristics. The first is Battjes and Groenendijk, which determines the wave characteristics from the output of a wave energy model (Battjes and Groenendijk, 2000). Secondly, the formulation by Goda (2000) which is based on experimental data.

4.2.1. Battjes and Groenendijk¶

class breakwater.core.battjes.BattjesGroenendijk(Hm0, h, slope_foreshore)[source]¶

Formulas of Battjes and Groenendijk (2000)

The wave height distributions on shallow foreshores deviates from those in deep water due to the effects of the restricted depth-to-height ratio and of wave breaking. Battjes and Groenendijk (2000), therefore derived a generalised empirical parameterisations based on laboratory data to determine these effects. This allows for the computation of all statistical wave heights based on the spectral wave height, water depth and slope of the foreshore.

Parameters:	Hm0 (float) – the spectral wave height [m] h (float) – the water depth [m] slope_foreshore (float or tuple) – the slope of the foreshore [rad], or as tuple formatted as (V,H)

Hrms¶

the root-mean-square wave height [m]

Type:	float

Htr_tilde¶

the transitional wave height, made dimensionless with Hrms [m]

Type:	float

k1, k2

shape parameters of the Composite Weibull Distribution (CWD) [-]

Type:	floats

static gammainc_lower(a, x)[source]¶

Lower incomplete gamma function

Defined as

\[\Gamma(a,x) = \int_0^x t^{a - 1}e^{-t} dt\]

Implemented using scipy.special as gamma(a)*gammainc(a,x)

Parameters:	a (float) – positive parameter x (float) – nonnegative argument
Returns:	float – value of the lower incomplete gamma function

static gammainc_upper(a, x)[source]¶

Upper incomplete gamma function

Defined as

\[\Gamma(a,x) = \int_x^\infty t^{a - 1}e^{-t} dt\]

Implemented using scipy.special as gamma(a)*gammaincc(a,x)

Parameters:	a (float) – positive parameter x (float) – nonnegative argument
Returns:	float – value of the upper incomplete gamma function

get_Hn(N)[source]¶

Computes \(H_{1/N}\)

This method computes the mean of the highest 1/N-part of the wave heights. It uses scipy.optimize.fsolve to determine H1~ and H2~, which are then used to compute \(H_{1/N}\).

Parameters:	N (float) – highest 1/N-part of the wave heights [-]
Returns:	H_1/N (float) – mean of the highest 1/N part of the waves
Raises:	ValueError – if N is smaller than 1

get_Hp(P)[source]¶

Computes \(H_{P}\)

This method computes the wave height exceeded by P% of the waves. It uses scipy.optimize.fsolve to determine H1~ and H2~, which are then used to compute \(H_{P}\)

Parameters:	P (float) – exceedance probability as a fractal [-]
Returns:	H_P (float) – wave height exceeded by P% of the waves
Raises:	ValueError – If P is entered as a percentage, must be entered as P%/100

4.2.2. Goda wave heights¶

breakwater.core.goda.goda_wave_heights(h, d, Ho, T, slope_foreshore, Ks=None, factor=1.8)[source]¶

Compute the design wave height

Computes the design wave height \(H_{1/3}\) and \(H_{max}\) with the empirical formulas of Goda (2000)

Parameters:

h (float) – water depth [m]
d (float) – water depth in front of the caisson, on top of the foundation [m]
Ho (float) – deep water wave height [m]
T (float) – wave period, Goda (2000) advises to use \(T_{1/3}\) [s]
slope_foreshore (tuple) – slope of the foreshore (V, H). For example a slope of 1:100 is defined as (1,100)
Ks (float, optional, default: None) – non-linear shoaling coefficient. If the shoaling coefficient is not specified it is automatically computed with shoaling_coefficient() [-]
factor (float, optional, default: 1.8) – Hmax is a probabilistic quantity. But to avoid possible confusion in design, a definite value of Hmax = 1.8 * Ks * H0 is recommended. The value of 1.8 is, however, a recommendation and the user is free to choose another value, such as 1.6 or 2.0 (Goda, 2000)

breakwater.utils.wave.shoaling_coefficient(h, T, H0, linear=False)[source]¶

Closed form equation for the non-linear shoaling coefficient

Computes the non-linear shoaling coefficient using a closed form equation. The equation uses the coefficient derived in Kweon and Goda (1996).

Parameters:	h (float) – water depth [m] T (float) – wave period, Goda (2000) advises to use \(T_{1/3}\) [s] H0 (float) – equivalent deep water significant wave height [m] linear (bool, optional, default: False) – if true the linear shoaling coefficient is returned, if false the non-linear shoaling coefficient is returned
Returns:	Ks (float) – the non-linear shoaling coefficient