Updated Doc Strings and Examples

Updated doc strings to give better refrences, added an example for the Britter-McQuaid plume model

src/models/britter_mcquaid_plume.jl

@@ -16,13 +16,13 @@ struct BritterMcQuaidPlumeSolution <: Plume
 end
 
 """
-    plume(scenario::Scenario, BritterMcQuaidPlume)
+    plume(::Scenario, BritterMcQuaidPlume)
 
 Returns the solution to a Britter-McQuaid dispersion model for the given
 scenario.
 
-Currently only implements the max concentration at a downwind distance x, the
-other coordinates are ignored.
+# References
++ Britter, R.E. and J. McQuaid, *Workbook on the Dispersion of Dense Gases* HSE Contract Research Report No. 17/1988, 1988
 
 """
 function plume(scenario::Scenario, ::Type{BritterMcQuaidPlume})

src/models/gaussian_plume.jl

@@ -18,9 +18,6 @@ end
 
 Returns the solution to a Gaussian plume dispersion model for the given scenario.
 
-The Gaussian plume model is per *Guidelines for Consequence Analysis of Chemical
-Release*, CCPS, New York (1999)
-
 ```math
 c\left(x,y,z\right) = { \dot{m} \over { 2 \pi \sigma_{y} \sigma_{z} u } }
 \exp \left[ -\frac{1}{2} \left( y \over \sigma_{y} \right)^2 \right] \\
@@ -30,9 +27,13 @@ c\left(x,y,z\right) = { \dot{m} \over { 2 \pi \sigma_{y} \sigma_{z} u } }
 
 where the σs are dispersion parameters correlated with the distance x
 
+# References
++ CCPS, *Guidelines for Consequence Analysis of Chemical Releases*, American Institute of Chemical Engineers, New York (1999)
+
 # Arguments
 - `downwash::Bool=false`: when true, includes stack-downwash effects
 - `plumerise::Bool=false`: when true, includes plume-rise effects using Briggs' model
+
 """
 function plume(scenario::Scenario, ::Type{GaussianPlume}; downwash::Bool=false, plumerise::Bool=false)
     # parameters of the jet

src/models/gaussian_puff.jl

@@ -12,13 +12,10 @@ struct GaussianPuffSolution{S<:StabilityClass} <: Puff
 end
 
 @doc doc"""
-    puff(scenario::Scenario, GaussianPuff)
+    puff(::Scenario, GaussianPuff)
 
 Returns the solution to a Gaussian puff dispersion model for the given scenario.
 
-The Gaussian puff model is per *Guidelines for Consequence Analysis of Chemical
-Release*, CCPS, New York (1999)
-
 ```math
 c\left(x,y,z,t\right) = \dot{m} \Delta t
 { { \exp \left( -\frac{1}{2} \left( {x - u t } \over \sigma_x \right)^2 \right) } \over { \sqrt{2\pi} \sigma_x } }
@@ -27,6 +24,9 @@ c\left(x,y,z,t\right) = \dot{m} \Delta t
 + \exp \left( -\frac{1}{2} \left( {z + h} \over \sigma_z \right)^2 \right) } \over { \sqrt{2\pi} \sigma_z } }
 ```
 
+# References
++ CCPS, *Guidelines for Consequence Analysis of Chemical Releases*, American Institute of Chemical Engineers, New York (1999)
+
 """
 function puff(scenario::Scenario, ::Type{GaussianPuff})
 

src/models/intpuff.jl

@@ -13,7 +13,7 @@ struct IntPuffSolution{T<:Number,S<:StabilityClass} <: Puff
 end
 
 @doc doc"""
-    puff(scenario::Scenario, IntPuff; kwargs...)
+    puff(::Scenario, IntPuff; kwargs...)
 
 Returns the solution to an integrated Gaussian dispersion model, where the
 release is modeled as a sequence of Gaussian puffs, for the given scenario.

src/models/simple_jet.jl

@@ -14,14 +14,11 @@ struct SimpleJetSolution <: Plume
 end
 
 @doc doc"""
-    plume(scenario::Scenario, SimpleJet; kwargs...)
+    plume(::Scenario, SimpleJet; kwargs...)
 
 Returns the solution to a simple turbulent jet dispersion model for the given
 scenario.
 
-The turbulent jet model is per Long, V.D., "Estimation of the Extent of Hazard
-Areas Around a Vent", *Chem. Process Hazard*, II, 6, 1963
-
 ```math
 c\left(x,y,z\right) = k_2 c_0 \left( d \over z \right) \sqrt{ \rho_j \over \rho_a }
 \exp \left( - \left( k_3 { r \over z } \right)^2 \right)
@@ -31,10 +28,14 @@ where *r* is the radial distance from the jet centerline. Assumes a circular jet
 with diameter equal to the jet diameter. Ground-reflection is included by method
 of images.
 
+# References
++ Long, V.D., "Estimation of the Extent of Hazard Areas Around a Vent" *Chem. Process Hazard*, II:6 (1963)
+
 # Arguments
 - `release_angle::Number=0`: the angle at which the jet is released, in radians
 - `k2::Number=6` parameter of the model, default value is recommended by Long
 - `k3::Number=5` parameter of the model, default value is recommended by Long
+
 """
 function plume(scenario::Scenario, ::Type{SimpleJet}; release_angle::Number=0.0, k2::Number=6.0, k3::Number=5.0)
     # Density correction

src/source_models/jet_source.jl

@@ -7,8 +7,8 @@ Returns returns a scenario for a simple jet from a circular hole. The
 jet can either be a liquid or a gas (in which case it is assumed to be an ideal
 gas and the jet is isentropic).
 
-Liquid and gas discharge models are per *Guidelines for Consequence Analysis of
-Chemical Release*, CCPS, New York (1999)
+# References
++ CCPS, *Guidelines for Consequence Analysis of Chemical Releases*, American Institute of Chemical Engineers, New York (1999)
 
 # Arguments
 - `phase=:liquid`: the phase, either :liquid or :gas

src/utils/britter_mcquaid_correls.jl

@@ -1,5 +1,4 @@
-# Britter-McQuaid plume correlations
-# as digitzed in TSCREEN
+
 function _bm_pl_c_1(α)
     # corresponds to (Cm/C0) = 0.10
     if α ≤ -0.55
@@ -94,6 +93,15 @@ function _bm_pl_c_002(α)
     end
 end
 
+"""
+    _bm_pl_c(α)
+
+Britter-McQuaid plume correlations as digtized in TSCREEN
+
+# References
++ EPA, *User's Guide to TSCREEN* U.S. Environmental Protection Agency EPA-454/B-94-023 (1994)
+
+"""
 function _bm_pl_c(α)
     concs = [0.10, 0.05, 0.02, 0.01, 0.005, 0.002]
     βs = [

src/utils/monin_obukhov.jl

@@ -2,8 +2,10 @@
     _monin_obukhov(roughness, StabilityClass)
 returns the Monin-Obukhov length for a given Pasquill-Gifford stability class
 and surface roughness (in meters)
-Curve fit from
-    Pasquill, F., *Atmospheric Diffusion, 2nd Ed.*, Halstead Press, New York, 1974.
+
+# References
++ Pasquill, F., *Atmospheric Diffusion, 2nd Ed.*, Halstead Press, New York (1974)
+
 """
 _monin_obukhov(zR, ::Type{ClassA}) = -11.4*zR^0.10
 _monin_obukhov(zR, ::Type{ClassB}) = -26.0*zR^0.17

src/utils/pasquill_gifford.jl

@@ -1,8 +1,12 @@
-# Plume crosswind dispersion correlations
-# Reference:
-#  Spicer, T. O. and J. A. Havens, "Development of Vapor Dispersion Models
-#  for Non-Neutrally Buoyant Gas Mixtures--Analysis of TFI/NH3 Test Data"
-#  USAF Engineering and Services Laboratory, Final Report, 1988
+"""
+    crosswind_dispersion(x, Plume, StabilityClass; avg_time=600.0)
+
+Plume crosswind dispersion correlations
+
+# References
++ Spicer, T. O. and J. A. Havens, "Development of Vapor Dispersion Models for Non-Neutrally Buoyant Gas Mixtures--Analysis of TFI/NH3 Test Data" USAF Engineering and Services Laboratory, Final Report (1988)
+
+"""
 function crosswind_dispersion(x, ::Type{Plume}, ::Type{ClassA}; avg_time=600.0)
     δ, β, tₐ = 0.423, 0.9, 18.4
     δ = δ*(max(avg_time, tₐ)/600)^0.2
@@ -39,10 +43,16 @@ function crosswind_dispersion(x, ::Type{Plume}, ::Type{ClassF}; avg_time=600.0)
     return δ*x^β
 end
 
-# Plume vertical dispersion correlations
-# Reference:
-#  Seinfeld, J. H. *Atmospheric Chemistry and Physics of Air Pollution*, John
-#  Wiley and Sons, New York, 1986
+
+"""
+    vertical_dispersion(x, Plume, StabilityClass)
+
+Plume vertical dispersion correlations
+
+References:
++ Seinfeld, J. H. *Atmospheric Chemistry and Physics of Air Pollution*, John Wiley and Sons, New York (1986)
+
+"""
 function vertical_dispersion(x, ::Type{Plume}, ::Type{ClassA})
     δ = 107.7
     β = -1.7172
@@ -85,26 +95,46 @@ function vertical_dispersion(x, ::Type{Plume}, ::Type{ClassF})
     return δ*(x^β)*exp(γ*log(x)^2)
 end
 
-# Puff crosswind dispersion correlations
-# Reference:
-#  CCPS, *Guidelines for Consequence Analysis of Chemical Releases*, American
-#  Institute of Chemical Engineers, New York, 1999
+"""
+    crosswind_dispersion(x, Puff, StabilityClass)
+
+Puff crosswind dispersion correlations
+
+References:
++ CCPS, *Guidelines for Consequence Analysis of Chemical Releases*, American Institute of Chemical Engineers, New York (1999)
+
+"""
 crosswind_dispersion(x, ::Type{Puff}, ::Type{ClassA}) = 0.18*x^0.92
 crosswind_dispersion(x, ::Type{Puff}, ::Type{ClassB}) = 0.14*x^0.92
 crosswind_dispersion(x, ::Type{Puff}, ::Type{ClassC}) = 0.10*x^0.92
 crosswind_dispersion(x, ::Type{Puff}, ::Type{ClassD}) = 0.06*x^0.92
 crosswind_dispersion(x, ::Type{Puff}, ::Type{ClassE}) = 0.04*x^0.92
 crosswind_dispersion(x, ::Type{Puff}, ::Type{ClassF}) = 0.02*x^0.89
 
-# Puff downwind dispersion correlations
+
+"""
+    downwind_dispersion(x, Puff, StabilityClass)
+
+Puff downwind dispersion correlations
+
+References:
++ CCPS, *Guidelines for Consequence Analysis of Chemical Releases*, American Institute of Chemical Engineers, New York (1999)
+
+"""
 function downwind_dispersion(x, ::Type{Puff}, stab::Union{Type{ClassA},Type{ClassB},Type{ClassC},Type{ClassD},Type{ClassE},Type{ClassF}})
     return crosswind_dispersion(x, Puff, stab)
 end
 
-# Puff vertical dispersion functions
-# Reference:
-#  CCPS, *Guidelines for Consequence Analysis of Chemical Releases*, American
-#  Institute of Chemical Engineers, New York, 1999
+
+"""
+    vertical_dispersion(x, Puff, StabilityClass)
+
+Puff vertical dispersion correlations
+
+References:
++ CCPS, *Guidelines for Consequence Analysis of Chemical Releases*, American Institute of Chemical Engineers, New York (1999)
+
+"""
 vertical_dispersion(x, ::Type{Puff}, ::Type{ClassA}) = 0.60*x^0.75
 vertical_dispersion(x, ::Type{Puff}, ::Type{ClassB}) = 0.53*x^0.73
 vertical_dispersion(x, ::Type{Puff}, ::Type{ClassC}) = 0.34*x^0.71

src/utils/plume_rise.jl

@@ -29,9 +29,14 @@ Base.isapprox(a::MomentumPlume, b::MomentumPlume) = all([
     if typeof(getproperty(a,k))<:Number ])
 
 """
-    plume_rise(Dⱼ, uⱼ, Tᵣ, u, Tₐ, ::Type{Union{ClassA, ClassB, ClassC, ClassD}})
+    plume_rise(Dⱼ, uⱼ, Tᵣ, u, Tₐ, StabilityClass)
 Implements the Briggs plume rise equations for buoyancy and momentum driven
-plume rise as described in the ISC3 model guide EPA-454/B-95-003b
+plume rise.
+
+# References
++ Briggs, G.A. *Plume Rise* U.S. Atomic Energy Commission, Oak Ridge (1969)
++ EPA, *User's Guide for the Industrial Source Complex (ISC3) Dispersion Models, vol 2*, U.S. Environmental Protection Agency EPA-454/B-95-003b (1995)
+
 """
 function plume_rise(Dⱼ,uⱼ,Tᵣ,u,Tₐ, stab::Union{Type{ClassA},Type{ClassB},Type{ClassC},Type{ClassD}})
     # physics parameters

src/utils/wind_profile.jl

@@ -29,16 +29,16 @@ end
 returns the windspeed function u(z) for a given Pasquill-Gifford
 stability class, `z` is assumed to be in meters and `u` is in m/s
 
-# Arguments
-`u` friction velocity
-`zR` surface roughness
-`λ`  Monin-Obukhov length
-`stability_class` Pasquill stability class (A, B, C, D, E, F)
-`k`  von Karman's constant, 0.35
+# References
++ Businger et al. 1971
 
+# Arguments
+- `u` friction velocity
+- `zR` surface roughness
+- `λ`  Monin-Obukhov length
+- `stability_class` Pasquill stability class (A, B, C, D, E, F)
+- `k`  von Karman's constant, 0.35
 
-# References
-    Businger et al. 1971
 """
 function _windspeed(z, u, zR, λ, ::Union{Type{ClassA},Type{ClassB},Type{ClassC}}; k=0.35)
     a = (1-15*(z/λ))^0.25