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 1 o 1 o 1 o 1 Hm0 o 1 o 1 o 1 o 1 H2_per o 2 Hmax x x Tm o 3 T13 o 3 o 3 T_m_min_1 o 3 o 3 o 3 o 3 Nod o 4 x Sd o 4 1 usesget_Hs()
to get Hs, so at least one of the wave heights must be given2 if H2_per not specified in the limit state it is computed withget_H2()
3 wave periods can be transformed in deep water withtransform_periods()
Note
The design classes
bw.RockRubbleMound
,bw.ConcreteRubbleMound
andbw.Caisson
perform 1 and 2 automatically, but not 3 and 4Parameters: - 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