Updated documentation

Updated the docs to refer to the Gaussian Mixing Layer model

Author: aefarrell

docs/src/equation_sets.md

@@ -9,7 +9,7 @@ plume
 
 ## Gaussian Plume Models
 
-### Simple Gaussian Plumes
+### Simple Gaussian Plume
 
 ```@docs
 plume(::Scenario{Substance,VerticalJet,Atmosphere}, ::Type{GaussianPlume})
@@ -210,26 +210,26 @@ plot(g, xlims=(0,50), ylims=(-10,10), height=3.5, clims=(0,LEL),
      aspect_ratio=:equal)
 ```
 
-### Gaussian Plumes with Mixing Layers
+### Gaussian Plume within a Mixing Layer
 
 ```@docs
-plume(::Scenario, ::Type{GaussianMixingLayer})
+plume(::Scenario{Substance,VerticalJet,Atmosphere}, ::Type{GaussianMixingLayer})
 ```
 
 The gaussian mixing layer model allows for the plume to be contained entirely within a mixing layer of a given height. This can be done using either the method of images or a periodic boundary.
 
 ```math
-c(x, y, z) = \frac{m_i}{u} { \exp\left(-\frac{1}{2}\left(\frac{y}{\sigma_y}\right)^2\right) \over { \sqrt{2\pi} \sigma_y} } F_z
+c(x, y, z) = \frac{m_i}{u} \frac{1}{\sqrt{2\pi} \sigma_y} \exp\left(-\frac{1}{2}\left(\frac{y}{\sigma_y}\right)^2\right) F_z
 ```
 
 Where $F_z$ is the vertical dispersion term. For the method of images this takes the form of the infinite sum:
 
 ```math
-F_z = {\left( \exp \left[ -\frac{1}{2} \left( { z -h } \over \sigma_{z} \right)^2 \right]
-+ \exp \left[ -\frac{1}{2} \left( { z + h } \over \sigma_{z} \right)^2 \right] \right) \over {\sqrt{2\pi} \sigma_z} } 
+F_z = \frac{1}{\sqrt{2\pi} \sigma_z} \left( \exp \left( -\frac{1}{2} \left( { z -h } \over \sigma_{z} \right)^2 \right)
++ \exp \left( -\frac{1}{2} \left( { z + h } \over \sigma_{z} \right)^2 \right) \right) \\
 \sum_{i=1}^{n} \left[ \exp\left(-\frac{1}{2}\left(\frac{z - h + 2i h_m}{\sigma_z}\right)^2\right) 
-+ \exp\left(-\frac{1}{2}\left(\frac{z - h - 2i h_m}{\sigma_z}\right)^2\right) 
-+ \exp\left(-\frac{1}{2}\left(\frac{z + h + 2i h_m}{\sigma_z}\right)^2\right) 
++ \exp\left(-\frac{1}{2}\left(\frac{z - h - 2i h_m}{\sigma_z}\right)^2\right) \\
++ \exp\left(-\frac{1}{2}\left(\frac{z + h + 2i h_m}{\sigma_z}\right)^2\right) \\
 + \exp\left(-\frac{1}{2}\left(\frac{z + h - 2i h_m}{\sigma_z}\right)^2\right) \right]
 ```
 
@@ -239,10 +239,15 @@ For the periodic boundary it takes the form of another infinite sum:
 F_z = ...
 ```
 
-## Simple Jet Plumes
+As `SimpleAtmosphere`s do not define mixing height, one is calculated based on the following:
+- for stable atmospheres (class E and F) the mixing height is assumed to be infinite, and the model defaults back to a [Simple Gaussian Plume](@ref)
+- for unstable and neutral atmospheres (classes A through D) the mixing height is calculated from the friction velocity $u^{*}$ and the coriolis parameter $f$: $h_m = 0.3 \frac{u^{*}}{f}$ where $f$ is calculated at a default latitude of 40°N (consistent with [US EPA 1995](references.md)).
+
+## Jet Plumes
+### Simple Jet Model
 
 ```@docs
-plume(::Scenario, ::Type{SimpleJet})
+plume(::Scenario{Substance,VerticalJet,Atmosphere}, ::Type{SimpleJet})
 ```
 
 Simple jet dispersion models are a useful tool for evaluating dispersion near the region where a jet release is occurring. They are based on a simplified model where the air is stationary and all of the momentum needed to mix the release is supplied by the jet. This is in some ways the opposite assumptions than are used in the Gaussian Plume model -- where the release is assumed to have negligible velocity and the momentum is entirely supplied by the wind.
@@ -259,7 +264,7 @@ with
 +  $\rho_j$ - initial density of the jet material, kg/m^3
 +  $\rho_a$ - density of the ambient atmosphere, kg/m^3
 
-### Model Parameters
+#### Model Parameters
 
 The model parameters $k_2$ and $k_3$ are per [Long (1963)](references.md)
 
@@ -274,7 +279,7 @@ the initial concentration is calculated from the mass flowrate and volumetric fl
  c_0 = { Q_i \over Q } = { \dot{m} \over \rho Q } = { \dot{m} \over { \rho \frac{\pi}{4} d^2 u } } 
 ```
 
-### Example
+#### Example
 
 Suppose we wish to model the dispersion of gaseous propane using the same scenario, `scn`, worked out above.
 
@@ -294,7 +299,8 @@ plot(j, xlims=(0,100), ylims=(-10,10), height=2)
 ```
 
 
-## Britter-McQuaid Model
+## Top-Hat Models
+### Britter-McQuaid Model
 
 ```@docs
 plume(::Scenario, ::Type{BritterMcQuaidPlume})

docs/src/plume.md

@@ -19,7 +19,8 @@ A simple gaussian puff model assumes the release is instantaneous, and all mass
 ```math
 c_{puff} = { m_i \over { (2 \pi)^{3/2} \sigma_x \sigma_y \sigma_z } } 
 \exp \left( -\frac{1}{2} \left( {x - ut} \over \sigma_x \right)^2 \right) 
-\exp \left( -\frac{1}{2} \left( {y} \over \sigma_y \right)^2 \right)  \left[ \exp \left( -\frac{1}{2} \left( {z - h} \over \sigma_z \right)^2 \right) 
+\exp \left( -\frac{1}{2} \left( {y} \over \sigma_y \right)^2 \right)  \\
+\left[ \exp \left( -\frac{1}{2} \left( {z - h} \over \sigma_z \right)^2 \right) 
 + \exp \left( -\frac{1}{2} \left( {z + h} \over \sigma_z \right)^2 \right)\right]
 ```
 
@@ -320,7 +321,7 @@ in the provided equationset are for windspeed.
 ### SLAB Jet Model
 
 ```@docs
-puff(::Scenario, ::Type{SLAB})
+puff(::Scenario{Substance,VerticalJet,Atmosphere}, ::Type{SLAB})
 ```
 
 The SLAB jet model is derived from the SLAB software package developed by 

docs/src/puff.md

@@ -24,15 +24,15 @@ function vertical_term(z, h, σz, ml::SimpleMixingLayer)
 end
 
 @doc doc"""
-    plume(::Scenario, GaussianMixingLayer[, ::EquationSet]; h_min=1.0, n_terms=10)
+    plume(::Scenario, GaussianMixingLayer[, ::EquationSet]; **kwargs...)
 
 Returns the solution to a Gaussian plume dispersion model with a simple reflective mixing layer.
 
 ```math
 c(x, y, z) = \frac{m_i}{u} { \exp\left(-\frac{1}{2}\left(\frac{y}{\sigma_y}\right)^2\right) \over { \sqrt{2\pi} \sigma_y} } F_z
 ```
 
-where \(F_z\) is the vertical dispersion term, a function of the mixing height \(h_m\), \(n\) is the number of image terms, and other symbols are as defined for a Gaussian
+where $ Fz $ is the vertical dispersion term, a function of the mixing height $ h_m $, *n* is the number of image terms, and other symbols are as defined for a Gaussian
 plume model.
 
 # Keyword Arguments
@@ -95,15 +95,15 @@ function plume(scenario::Scenario, ::Type{GaussianMixingLayer}, eqs=DefaultSet()
 end
 
 @doc doc"""
-    plume(::Scenario{AbstractSubstance,VerticalJet,Atmosphere}, GaussianPlume[, ::EquationSet]; **kwargs...)
+    plume(::Scenario{Substance,VerticalJet,Atmosphere}, GaussianMixingLayer[, ::EquationSet]; **kwargs...)
 
 Returns the solution to a Gaussian plume dispersion model with a simple reflective mixing layer.
 
 ```math
 c(x, y, z) = \frac{m_i}{u} { \exp\left(-\frac{1}{2}\left(\frac{y}{\sigma_y}\right)^2\right) \over { \sqrt{2\pi} \sigma_y} } F_z
 ```
 
-where \(F_z\) is the vertical dispersion term, a function of the mixing height \(h_m\), \(n\) is the number of image terms, and other symbols are as defined for a Gaussian
+where $ Fz $ is the vertical dispersion term, a function of the mixing height $ h_m $, *n* is the number of image terms, and other symbols are as defined for a Gaussian
 plume model.
 
 # Keyword Arguments

src/models/gaussian_mixing_layer.jl

@@ -84,7 +84,7 @@ function plume(scenario::Scenario, ::Type{GaussianPlume}, eqs=DefaultSet(); h_mi
 end
 
 @doc doc"""
-    plume(::Scenario{AbstractSubstance,VerticalJet,Atmosphere}, GaussianPlume[, ::EquationSet]; kwargs...)
+    plume(::Scenario{Substance,VerticalJet,Atmosphere}, GaussianPlume[, ::EquationSet]; kwargs...)
 
 Returns the solution to a Gaussian plume dispersion model for a vertical jet. By default the Briggs
 plume rise model is used.

src/models/gaussian_plume.jl

@@ -37,7 +37,7 @@ downwind dispersion, σx, is calculated:
 - `:tno` follows the TNO Yellow Book eqn 4.60b, using the distance *x* while the plume is still attached and the distance to the cloud center, *ut*, afterwards
 
 # Arguments
-- `plume_model::Type{Plume} = GaussianPlume` : the plume model $\Chi$
+- `plume_model::Type{Plume} = GaussianPlume` : the plume model $\chi$
 - `disp_method = :default` : the method for calculating the downwind dispersion
 
 # References

src/models/palazzi_puff.jl

@@ -65,6 +65,29 @@ function plume(scenario::Scenario, ::Type{SimpleJet}, eqs::EquationSet=DefaultSe
 
 end
 
+@doc doc"""
+    plume(::Scenario{Substance,VerticalJet,Atmosphere}, SimpleJet; kwargs...)
+
+Returns the solution to a simple turbulent jet dispersion model for a vertical jet.
+
+```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)
+```
+
+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. 1963. "Estimation of the Extent of Hazard Areas Round a Vent." *Chem. Process Hazard*. II:6
+
+# Arguments
+- `release_angle::Number=π/2`: 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{<:AbstractSubstance,<:VerticalJet,<:Atmosphere}, ::Type{SimpleJet}, eqs::EquationSet=DefaultSet(); release_angle::Number=π/2, k2::Number=6.0, k3::Number=5.0)
     # Density correction
     ρj = _release_density(scenario)

src/models/simple_jet.jl

@@ -128,6 +128,21 @@ function puff(scenario::Scenario, ::Type{SLAB}, eqs::EquationSet=DefaultSet();
                         AkimaInterpolation(out.cc.betax[tperm], out.cc.t[tperm]))
 end
 
+
+@doc doc"""
+    puff(::Scenario{Substance,VerticalJet,Atmosphere}, SLAB; kwargs...)
+
+Returns the solution to the SLAB vertical jet dispersion model for the given
+scenario.
+
+# References
++ Ermak, Donald L. 1990. *User's Manual for SLAB: An Atmospheric Dispersion Model For Denser-Than-Air Releases* Lawrence Livermore National Laboratory
+
+# Arguments
+- `t_av::Number=10`: averaging time, seconds
+- `x_max::Number=2000`: maximum downwind distance, meters, this defines the problem domain
+
+"""
 function puff(scenario::Scenario{<:AbstractSubstance,<:VerticalJet,<:Atmosphere}, ::Type{SLAB}, eqs::EquationSet=DefaultSet();
               t_av=10, x_max=2000)
     c_max = 1.0