deploy: efd2cca

_sources/user_guide.rst.txt

@@ -41,6 +41,41 @@ Building Height Limit
 
 Following NUDAPT, **naturf** bins building heights into five meter increments from 0 to 75 meters. Any building with a height greater than 75 meters is considered as ending at 75 meters.
 
+Glossary of Terms
+~~~~~~~~~~~~~~~~~
+
+* `FAD`: Frontal area density (unitless)
+* :math:`A_f`: Frontal area of a wall from a given direction and height (:math:`m^2`)
+* :math:`A_F`: Total frontal area of a wall from a given direction (:math:`m^2`)
+* :math:`A_P`: Total plan area (:math:`m^2`)
+* :math:`\lambda_p`: Plan area density (unitless)
+* :math:`A_b`: Building plan area (:math:`m^2`)
+* `AWMH`: Area weighted mean of building heights (`m`)
+* :math:`z_h`: Building height (`m`)
+* :math:`\lambda_f`: Frontal area index from a given direction (unitless)
+* `CAR`: Complete aspect ratio (unitless)
+* `BSA`: Building surface area (:math:`m^2`)
+* :math:`\overline{\lambda_s}`: Average height-to-width ratio for given building and neighbors (unitless)
+* :math:`\overline{z_h}`: Average building height for given building and neighbors (`m`)
+* `SVF`: Sky-view factor (unitless)
+* :math:`\overline{W}`: Average distance between given building and neighbors (`m`)
+* :math:`rl_{go}`: Grimmond & Oke rougness length (`m`)
+* :math:`dh_{go}`: Grimmond & Oke displacement height (`m`)
+* :math:`rl_r`: Raupach roughness length (`m`)
+* :math:`dh_r`: Raupach displacement height (`m`)
+* :math:`\kappa`: von Kármán's constant = 0.4 (unitless)
+* :math:`C_S`: Substrate-surface drag coefficient = 0.003 (unitless)
+* :math:`C_R`: Roughness-element drag coefficient = 0.3 (unitless)
+* :math:`\Psi_h`: Roughness-sublayer influence function = 0.193 (unitless)
+* :math:`c_{d1}`: Constant = 7.5 (unitless)
+* :math:`\Lambda`: Frontal area index times 2 (unitless)
+* :math:`rl_m`: Macdonald roughness length (`m`)
+* :math:`dh_m`: Macdonald displacement height (`m`)
+* :math:`\beta` Beta coefficient = 1 (unitless)
+* :math:`C_D` Obstacle drag coefficient = 1.12 (unitless)
+* :math:`A_l` Lot area (:math:`m^2`)
+* `A`: Constant = 3.59 (unitless)
+
 Output Parameters
 ~~~~~~~~~~~~~~~~~
 
@@ -50,19 +85,17 @@ Frontal Area Density (1-60)
 Frontal area density is the frontal area at a certain height increment divided by the total plan area. **naturf** calculates frontal area density from the four cardinal directions (east, north, west, south) and at 5 meter increments from ground level to 75 meters. Parameters 1-15 represent the north, parameters 16-30 represent the west, parameters 31-45 represent the south, and parameters 46-60 represent the east. For instance, parameter 1 gives the north-facing wall area for each building and its neighbors divided by the total plan area. [Burian2003]_ Eq. 14
 
 .. math::
-  FAD = \frac{FA}{TPA}
+  FAD = \frac{A_{f}}{A_{P}}
 
-where `FAD` is Frontal area density; `FA` is the frontal area of the wall from the current direction and height level in :math:`m^2`; `TPA` is the total plan area in :math:`m^2`.
 
 Plan Area Density (61-75)
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Plan area density is the ratio of building plan area to the total plan area, calculated in 5 meter increments from ground level to 75 meters. **naturf** projects the building footprint vertically to the building height, meaning plan area density is the same at every vertical level. [Burian2003]_ Eq. 7
 
 .. math::
-  PAD = \frac{BPA}{TPA}
+  \lambda_p = \frac{A_{b}}{A_{P}}
 
-where, `PAD` is the plan area density; `BPA` is the building plan area in :math:`m^2`; `TPA` is the total plan area in :math:`m^2`.
 
 Rooftop Area Density (76-90)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -91,9 +124,8 @@ The average height of all buildings within the total plan area weighted by the t
 
 .. math::
 
-  AWMH = \frac{\Sigma{A_i zh_i}}{\Sigma{A_i}}
+  AWMH = \frac{\Sigma{A_{b} z_{h}}}{\Sigma{A_{b}}
 
-where, `AWMH` is the area weighted mean height in m; `A_i` is the current building plan area in `m^2`; `zh_i` is the current building height in m.
 
 Building Surface Area to Plan Area Ratio (95)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -106,19 +138,17 @@ Frontal Area Index (96-99)
 Frontal area index is the ratio of the entire frontal area of a building to the total plan area. **naturf** calculates the frontal area index from the four cardinal directions. Because buildings often do not face a cardinal direction head on, **naturf** uses the average alongwind and crosswind distance from the current building centroid to all other building centroids for the total plan area. [Burian2003]_ Eq. 12
 
 .. math::
-  FAI = \frac{FA}{TPA}
+  \lambda_{f} = \frac{A_{F}`}{A_{P}}
 
-where, `FAI` is frontal area index; `FA` is the frontal area of the wall from the current direction in :math:`m^2`; `TPA` is the total plan area in :math:`m^2`.
 
 Complete Aspect Ratio (100)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The ratio of building surface area and exposed ground area to the total plan area. [Burian2003]_ Eq. 15
 
 .. math::
-  CAR = \frac{BSA + (PA - BPA)}{TPA}
+  CAR = \frac{BSA + (A_{P} - A_{b)}{A_{P}}
 
-where, `BSA` is the building surface area in :math:`m^2`; `BPA` is the building plan area in :math:`m^2`; `TPA` is the total plan area in :math:`m^2`.
 
 Height-to-Width Ratio (101)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -128,37 +158,33 @@ The ratio of the building height to the street width. **naturf** generalizes thi
 .. math::
   \overline{\lambda_s} = \frac{\overline{z_h}}{\overline{W}}
 
-where, :math:`\overline{\lambda_s}` is the average height-to-width ratio; :math:`\overline{z_h}` is the average building height in m; :math:`\overline{W}` is the average distance between buildings.
 
 Sky-View Factor (102)
 ^^^^^^^^^^^^^^^^^^^^^
 
 The fraction of visible sky in a given area. **naturf** generalizes the distance between buildings to be the average distance between the current building and all other buildings in the total plan area.  [Dirksen2019]_ Eq. 1
 
 .. math::
-  SVF = cos(arctan(\frac{H}{0.5W}))
+  SVF = cos(arctan(\frac{z_{h}}{0.5W}))
 
-where, `SVF` is the sky-view factor; `H` is the building height in m; `W` is the distance between buildings in m.
 
 Grimmond & Oke Roughness Length (103)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 [GrimmondOke1999]_ Eq. 2
 
 .. math::
-  GORL = 0.1 \cdot zh
+  rl_{go} = 0.1 \cdot z_{h}
 
-where, `GORL` is Grimmond & Oke rougness length in m; `zh` is the building height in m.
 
 Grimmond & Oke Displacement Height (104)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 [GrimmondOke1999]_ Eq. 1
 
 .. math::
-  GODH = 0.67 \cdot zh
+  dh_{go} = 0.67 \cdot z_{h}
 
-where, `GODH` is Grimmond & Oke displacement height in m; `zh` is building height in m.
 
 
 Raupach Roughness Length (105, 107, 109, 111)
@@ -167,9 +193,7 @@ Raupach Roughness Length (105, 107, 109, 111)
 [Raupach1994]_ Eq. 4
 
 .. math::
-  RRL = zh \cdot (1 - \frac{RDH}{zh}) \cdot exp(-\kappa \cdot (C_{S} + C_{R} \cdot \lambda)^{-0.5} - \Psi_{h})
-
-where, `RRL` is the Raupach roughness length in m; `RDH` is the Raupach displacement height in m; :math:`\kappa` is von Kármán's constant = 0.4; `C_S` is the substrate-surface drag coefficient = 0.003; `C_R` is the roughness-element drag coefficient = 0.3; :math:`\lambda` is the frontal area index; :math:`\Psi_h` is the roughness-sublayer influence function = 0.193.
+  rl_{r} = z_{h} \cdot (1 - \frac{dh_{r}}{z_{h}}) \cdot exp(-\kappa \cdot (C_{S} + C_{R} \cdot \lambda_{f})^{-0.5} - \Psi_{h})
 
 
 Raupach Displacment Height (106, 108, 110, 112)
@@ -178,29 +202,26 @@ Raupach Displacment Height (106, 108, 110, 112)
 [Raupach1994]_ Eq. 8
 
 .. math::
-  RDH = zh \cdot (1 - (\frac{1 - \exp(-\sqrt(c_{d1} \cdot \Lambda))}{\sqrt(c_{d1} \cdot \Lambda)}))
+  dh_{r} = z_{h} \cdot (1 - (\frac{1 - \exp(-\sqrt(c_{d1} \cdot \Lambda))}{\sqrt(c_{d1} \cdot \Lambda)}))
 
-where, `RDH` is the Raupach displacement height in m; :math:`c_{d1}` is a constant = 7.5; :math:`\Lambda` is frontal area index times 2.
 
 Macdonald et al. Roughness Length (113-116)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 [Macdonald1998]_ Eq. 22
 
 .. math::
-  MRL = zh \cdot (1 - \frac{MDH}{zh})\exp(-(0.5*\beta\frac{C_{D}}{\kappa^2}(1 - \frac{MDH}{zh})\frac{A_{f}}{A_{l}})^{-0.5})
+  rl_{m} = z_{h} \cdot (1 - \frac{dh_{m}}{z_{h}})\exp(-(0.5*\beta\frac{C_{D}}{\kappa^2}(1 - \frac{MDH}{z_{h}})\frac{A_{F}}{A_{l}})^{-0.5})
 
-where, `MRL` is the Macdonald roughness length in m; `zh` is the building height in m; `MDH` is the Macdonald displacement height in m; :math:`\beta` is the beta coefficient = 1; :math:`C_D` is the obstacle drag coefficient = 1.12; :math:`\kappa` is von Kármán's constant = 0.4; :math:`A_f` is the frontal area of the building in :math:`m^2`; :math:`A_l` is the lot area of the building in :math:`m^2`.
 
 Macdonald et al. Displacement Height (117)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 [Macdonald1998]_ Eq. 23
 
 .. math::
-  MDH = zh \cdot (1 + \frac{1}{A^\lambda} \cdot (\lambda - 1))
+  dh_{m} = z_{h} \cdot (1 + \frac{1}{A^\lambda_{p} \cdot (\lambda_{p} - 1))
 
-where, `MDH` is the Macdonald displacement height in m; `zh` is the building height in m; `A` is a constant = 3.59; :math:`\lambda` is the plan area density.
 
 Vertical Distribution of Building Heights (118-132)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^