From 1509a2921067c294bf59c48c9eeb9b35e8c48651 Mon Sep 17 00:00:00 2001 From: Yuri Ishizawa Date: Wed, 5 Jun 2024 01:02:42 -0300 Subject: [PATCH 1/3] Add rainfall intensity calculation function --- physics/rainfall_intensity.py | 115 ++++++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 physics/rainfall_intensity.py diff --git a/physics/rainfall_intensity.py b/physics/rainfall_intensity.py new file mode 100644 index 000000000000..dbe7b0974b1b --- /dev/null +++ b/physics/rainfall_intensity.py @@ -0,0 +1,115 @@ +""" +Rainfall Intensity +================== +This module contains functions to calculate the intensity of +a rainfall event for a given duration and return period. +""" + + +def rainfall_intensity( + k: float, a: float, b: float, c: float, tr: float, t: float +) -> float: + """ + Calculate the intensity of a rainfall event for a given duration and return period. + The coefficients K, a, b, and c are obtained from the Sherman + intensity-duration-frequency curve for a specific location. + + Parameters + ---------- + k : float + Coefficient [adm]. + a : float + Coefficient [adm]. + b : float + Coefficient [adm]. + c : float + Coefficient [adm]. + tr : float + Return period in years. + t : float + Rainfall event duration in minutes. + + Returns + ------- + intensity : float + Intensity of the rainfall event in mm/h. + + References + ---------- + - Aparicio, F. (1997): Fundamentos de Hidrología de Superficie. + Balderas, México, Limusa. 303 p. + - https://en.wikipedia.org/wiki/Intensity-duration-frequency_curve + + Examples + -------- + + >>> rainfall_intensity(1000, 0.2, 11.6, 0.81, 10, 60) + 49.83339231138578 + + >>> rainfall_intensity(1000, 0.2, 11.6, 0.81, 10, 30) + 77.36319588106228 + + >>> rainfall_intensity(1000, 0.2, 11.6, 0.81, 5, 60) + 43.382487747633625 + + >>> rainfall_intensity(0, 0.2, 11.6, 0.81, 10, 60) + Traceback (most recent call last): + ... + ValueError: Please ensure that all parameters are positive. + + >>> rainfall_intensity(1000, -0.2, 11.6, 0.81, 10, 60) + Traceback (most recent call last): + ... + ValueError: Please ensure that all parameters are positive. + + >>> rainfall_intensity(1000, 0.2, -11.6, 0.81, 10, 60) + Traceback (most recent call last): + ... + ValueError: Please ensure that all parameters are positive. + + >>> rainfall_intensity(1000, 0.2, 11.6, -0.81, 10, 60) + Traceback (most recent call last): + ... + ValueError: Please ensure that all parameters are positive. + + >>> rainfall_intensity(1000, 0, 11.6, 0.81, 10, 60) + Traceback (most recent call last): + ... + ValueError: Please ensure that all parameters are positive. + + >>> rainfall_intensity(1000, 0.2, 0, 0.81, 10, 60) + Traceback (most recent call last): + ... + ValueError: Please ensure that all parameters are positive. + + >>> rainfall_intensity(1000, 0.2, 11.6, 0, 10, 60) + Traceback (most recent call last): + ... + ValueError: Please ensure that all parameters are positive. + + >>> rainfall_intensity(0, 0.2, 11.6, 0.81, 10, 60) + Traceback (most recent call last): + ... + ValueError: Please ensure that all parameters are positive. + + >>> rainfall_intensity(1000, 0.2, 11.6, 0.81, 0, 60) + Traceback (most recent call last): + ... + ValueError: Please ensure that all parameters are positive. + + >>> rainfall_intensity(1000, 0.2, 11.6, 0.81, 10, 0) + Traceback (most recent call last): + ... + ValueError: Please ensure that all parameters are positive. + + """ + if k <= 0 or a <= 0 or b <= 0 or c <= 0 or tr <= 0 or t <= 0: + raise ValueError("Please ensure that all parameters are positive.") + intensity = (k * (tr**a)) / ((t + b) ** c) + return intensity + + +if __name__ == "__main__": + import doctest + + doctest.testmod() From 9faab406687ec9c6384d328358fde46495b3be57 Mon Sep 17 00:00:00 2001 From: Yuri Ishizawa Date: Mon, 10 Jun 2024 15:09:07 -0300 Subject: [PATCH 2/3] chore: improve fuction and coefficient documentation --- physics/rainfall_intensity.py | 90 +++++++++++++++++++++++------------ 1 file changed, 59 insertions(+), 31 deletions(-) diff --git a/physics/rainfall_intensity.py b/physics/rainfall_intensity.py index dbe7b0974b1b..cd678f95d14f 100644 --- a/physics/rainfall_intensity.py +++ b/physics/rainfall_intensity.py @@ -3,30 +3,50 @@ ================== This module contains functions to calculate the intensity of a rainfall event for a given duration and return period. + +This function uses the Sherman intensity-duration-frequency curve. + +References +---------- +- Aparicio, F. (1997): Fundamentos de Hidrología de Superficie. + Balderas, México, Limusa. 303 p. +- https://en.wikipedia.org/wiki/Intensity-duration-frequency_curve """ def rainfall_intensity( - k: float, a: float, b: float, c: float, tr: float, t: float + coefficient_k: float, + coefficient_a: float, + coefficient_b: float, + coefficient_c: float, + return_period: float, + duration: float, ) -> float: """ Calculate the intensity of a rainfall event for a given duration and return period. - The coefficients K, a, b, and c are obtained from the Sherman - intensity-duration-frequency curve for a specific location. + It's based on the Sherman intensity-duration-frequency curve: + + I = K * T^a / (D + b)^c + + where: + I = Intensity of the rainfall event [mm/h] + k, a, b, c = Coefficients obtained through statistical distribution adjust + T = Return period in years + D = Rainfall event duration in minutes Parameters ---------- - k : float - Coefficient [adm]. - a : float - Coefficient [adm]. - b : float - Coefficient [adm]. - c : float - Coefficient [adm]. - tr : float + coefficient_k : float + Coefficient obtained through statistical distribution adjust. + coefficient_a : float + Coefficient obtained through statistical distribution adjust. + coefficient_b : float + Coefficient obtained through statistical distribution adjust. + coefficient_c : float + Coefficient obtained through statistical distribution adjust. + return_period : float Return period in years. - t : float + duration : float Rainfall event duration in minutes. Returns @@ -34,11 +54,10 @@ def rainfall_intensity( intensity : float Intensity of the rainfall event in mm/h. - References - ---------- - - Aparicio, F. (1997): Fundamentos de Hidrología de Superficie. - Balderas, México, Limusa. 303 p. - - https://en.wikipedia.org/wiki/Intensity-duration-frequency_curve + Raises + ------ + ValueError + If any of the parameters are not positive. Examples -------- @@ -55,57 +74,66 @@ def rainfall_intensity( >>> rainfall_intensity(0, 0.2, 11.6, 0.81, 10, 60) Traceback (most recent call last): ... - ValueError: Please ensure that all parameters are positive. + ValueError: All parameters must be positive. >>> rainfall_intensity(1000, -0.2, 11.6, 0.81, 10, 60) Traceback (most recent call last): ... - ValueError: Please ensure that all parameters are positive. + ValueError: All parameters must be positive. >>> rainfall_intensity(1000, 0.2, -11.6, 0.81, 10, 60) Traceback (most recent call last): ... - ValueError: Please ensure that all parameters are positive. + ValueError: All parameters must be positive. >>> rainfall_intensity(1000, 0.2, 11.6, -0.81, 10, 60) Traceback (most recent call last): ... - ValueError: Please ensure that all parameters are positive. + ValueError: All parameters must be positive. >>> rainfall_intensity(1000, 0, 11.6, 0.81, 10, 60) Traceback (most recent call last): ... - ValueError: Please ensure that all parameters are positive. + ValueError: All parameters must be positive. >>> rainfall_intensity(1000, 0.2, 0, 0.81, 10, 60) Traceback (most recent call last): ... - ValueError: Please ensure that all parameters are positive. + ValueError: All parameters must be positive. >>> rainfall_intensity(1000, 0.2, 11.6, 0, 10, 60) Traceback (most recent call last): ... - ValueError: Please ensure that all parameters are positive. + ValueError: All parameters must be positive. >>> rainfall_intensity(0, 0.2, 11.6, 0.81, 10, 60) Traceback (most recent call last): ... - ValueError: Please ensure that all parameters are positive. + ValueError: All parameters must be positive. >>> rainfall_intensity(1000, 0.2, 11.6, 0.81, 0, 60) Traceback (most recent call last): ... - ValueError: Please ensure that all parameters are positive. + ValueError: All parameters must be positive. >>> rainfall_intensity(1000, 0.2, 11.6, 0.81, 10, 0) Traceback (most recent call last): ... - ValueError: Please ensure that all parameters are positive. + ValueError: All parameters must be positive. """ - if k <= 0 or a <= 0 or b <= 0 or c <= 0 or tr <= 0 or t <= 0: - raise ValueError("Please ensure that all parameters are positive.") - intensity = (k * (tr**a)) / ((t + b) ** c) + if ( + coefficient_k <= 0 + or coefficient_a <= 0 + or coefficient_b <= 0 + or coefficient_c <= 0 + or return_period <= 0 + or duration <= 0 + ): + raise ValueError("All parameters must be positive.") + intensity = (coefficient_k * (return_period**coefficient_a)) / ( + (duration + coefficient_b) ** coefficient_c + ) return intensity From c9e20ab04475033a93c1903325d5ccbe2ada1a08 Mon Sep 17 00:00:00 2001 From: Tianyi Zheng Date: Tue, 11 Jun 2024 02:41:30 -0700 Subject: [PATCH 3/3] Update physics/rainfall_intensity.py --- physics/rainfall_intensity.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/physics/rainfall_intensity.py b/physics/rainfall_intensity.py index cd678f95d14f..cee8d50ddc2f 100644 --- a/physics/rainfall_intensity.py +++ b/physics/rainfall_intensity.py @@ -26,7 +26,7 @@ def rainfall_intensity( Calculate the intensity of a rainfall event for a given duration and return period. It's based on the Sherman intensity-duration-frequency curve: - I = K * T^a / (D + b)^c + I = k * T^a / (D + b)^c where: I = Intensity of the rainfall event [mm/h]