Update P.2108 index page

includes/_code_examples.qmd

@@ -0,0 +1,3 @@
+#### Examples
+
+Language-specific code examples showing the use of this function are available by following these links:

models/P2108/index.qmd

@@ -2,70 +2,90 @@
 title: "ITU-R P.2108"
 ---
 
-{{< include ../includes/_under_construction.qmd >}}
+{{< include /includes/_under_construction.qmd >}}
 
-Recommendation ITU-R P.2108 (Prediction of clutter loss) provides three methods to predict terminal clutter loss.  Two of these methods are for terrestrial paths and one if for aeronautical paths.  Frequencies vary depending on the clutter model.
+Recommendation ITU-R P.2108 _Prediction of clutter loss_ contains three methods for the prediction of clutter loss: the [Height Gain Terminal Correction Model](#height-gain-terminal-correction-model), [Terrestrial Statistical Model](#terrestrial-statistical-model), and [Aeronautical Statistical Model](#aeronautical-statistical-model) [@p2108-1, Sections 3.1-3.3]. This software implements each of the three models.
 
-{{< include ../includes/_getting_started.qmd >}}
+{{< include /includes/_getting_started.qmd >}}
 
-# Functions
+## Model Selection
 
-## Height Gain Terminal Correction Model
+Selection and use of the appropriate model is required to obtain meaningful outputs. Refer to Table 1 from @p2108-1 [Section 2] for a summary of the applicable scenarios for each model. Further details about the applicability and assumptions of each of the P.2108 models are available in the sections of the Recommendation in which they are described.
 
-This method, gives the median of losses due to different terminal surroundings. The possible mechanisms include obstruction loss and reflections due to clutter objects at the representative height, and scattering and reflection from the ground and smaller clutter objects. When using a computer implementation, with terrain profile extracted from a digital terrain model, and with the terminal surroundings defined by a clutter category, it is not practicable to identify individual mechanisms. The method used here distinguishes between two general cases: for woodland and urban categories. It is assumed that the dominant mechanism is diffraction over clutter. For other categories, it is assumed that reflection or scattering dominates.
+## Functions
 
-This model in valid for frequencies from 0.03 to 3 GHz.
+### Height Gain Terminal Correction Model
 
-The model supports the following clutter types and their respective input value.  Note that for language-specific code, enumerations and/or constants are provided for easy-of-use.
+The height gain terminal correction model is described in @p2108-1 [Section 3.1]. This model calculates an additional loss, $A_h$, which can be added to the basic transmission loss of a path calculated above the clutter. Therefore basic transmission loss should be calculated to/from the height of the representative clutter height used. This model can be applied to both transmitting and receiving ends of the path.
 
-| Clutter Type | Value |
-|--------------|:-----:|
-| Water/sea    |     1 |
-| Open/rural   |     2 |
-| Suburban     |     3 |
-| Urban        |     4 |
-| Trees/forest |     5 |
-| Dense urban  |     6 |
 
-Two parameters additional allow that define the clutter at the terminal allow for either path-specific definitions as well as provide default values.
+| Variable       | Type   | Units | Limits              | Description                       |
+|----------------|--------|-------|---------------------|-----------------------------------|
+| `f__ghz`       | double | GHz   | $0.3 \leq f \leq 3$ | Frequency                         |
+| `h__meter`     | double | meter | $0 \leq h$          | Antenna height                    |
+| `w_s__meter`   | double | meter | $0 < w_s$           | Street width                      |
+| `R__meter`     | double | meter | $0 < R$             | Representative clutter height     |
+| `clutter_type` | `ClutterType` enum | N/A | enum      | See @tbl-p2108-3p1-clutter-types  |
+: Inputs for the height gain terminal correction model {#tbl-p2108-3p1-inputs}
 
-### Street Width
+The values for $w_s$ and $R$ should be set based upon local information. If local information is not available, @p2108-1 [Section 3.1.1] defines appropriate default values: $w_s=27$ and a set of values for $R$ based on the clutter type, which are reproduced in @tbl-p2108-3p1-clutter-types.
+This table also provides the integer values mapped to each clutter type in the enumeration objects are provided by the software for ease of use.
 
-The parameter `w_s__meter` defines the width of the street at the location of the terminal in clutter.  If site-specific information is not available, the value of 27 should be used.
+| Clutter Type | Enum Value | Default $R$ (m) |
+|--------------|:----------:|-----------------|
+| Water/sea    |          1 |              10 |
+| Open/rural   |          2 |              10 |
+| Suburban     |          3 |              10 |
+| Urban        |          4 |              15 |
+| Trees/forest |          5 |              15 |
+| Dense urban  |          6 |              20 |
+: Clutter types for the @p2108-1 [Section 3.1] model {#tbl-p2108-3p1-clutter-types}
 
-### Representative Clutter Height
+{{< include /includes/_code_examples.qmd >}}
 
-The parameter `R__meter` defines the representative clutter height at the location of the terminal in clutter.  Default values for each clutter type are listed in the below table:
+[C++](cpp.qmd#height-gain-terminal-correction){.btn .btn-outline-primary .btn role="button"}
+[C#/.NET](dotnet.qmd#height-gain-terminal-correction){.btn .btn-outline-primary .btn role="button"}
+[MATLAB](matlab.qmd#height-gain-terminal-correction){.btn .btn-outline-primary .btn role="button"}
+[Python](python.qmd#height-gain-terminal-correction){.btn .btn-outline-primary .btn role="button"}
 
-| Clutter Type | `R__meter` |
-|--------------|:----------:|
-| Water/sea    |         10 |
-| Open/rural   |         10 |
-| Suburban     |         10 |
-| Urban        |         15 |
-| Trees/forest |         15 |
-| Dense urban  |         20 |
+### Terrestrial Statistical Model
 
-Example: [C#](P2108-(.NET)#height-gain-terminal-correction-model) | [MATLAB](P2108-(MATLAB)#height-gain-terminal-correction-model) | [Python](P2108-(Python)#height-gain-terminal-correction-model)
+The terrestrial statistical model is described in @p2108-1 [Section 3.2]. The model can be applied for urban and suburban environments provided terminal heights are well below the clutter height. The correction produced by this model can be applied at one terminal, or, if the path length is at least 1 km, at both terminals.
 
-## Terrestrial Statistical Model
+This model calculates an additional loss, $L_{ctt}$, which can be added to the transmission loss or basic transmission loss. As this is a statistical model, the term $L_{ctt}$ is the clutter loss not exceeded for $p$ percent of locations for a terrestial path of length $d$. If the transmission loss or basic transmission loss has been calculated using a model that inherently accounts for clutter over the entire path then this model should not be applied.
 
-This model gives equations that gives a statistical distribution of clutter loss. The model can be applied for urban and suburban clutter loss modelling.  Validity of the model is as follows:
+| Variable | Type   | Units | Limits             | Description   |
+|----------|--------|-------|--------------------|---------------|
+| `f__ghz` | double | GHz   | $2 \leq f \leq 67$ | Frequency     |
+| `d__km`  | double | km    | $0.25 \leq d$      | Path distance |
+| `p`      | double | %     | $0 < p < 100$      | Percentage of locations at which predicted clutter loss will not be exceeded |
+: Inputs for the terrestrial statistical model {#tbl-p2108-3p2-inputs}
 
- * Frequency range: 2 to 67 GHz
- * Minimum path length: 
-   * 0.25 km (for the correction to be applied at only one end of the path)
-   * 1.0 km (for the correction to be applied at both ends of the path)
- * Percentage locations range: 0 < `p` < 100
+{{< include /includes/_code_examples.qmd >}}
 
-Example: [C#](P2108-(.NET)#terrestrial-statistical-model) | [MATLAB](P2108-(MATLAB)#terrestrial-statistical-model) | [Python](P2108-(Python)#terrestrial-statistical-model)
+[C++](cpp.qmd#terrestrial-statistical-model){.btn .btn-outline-primary .btn role="button"}
+[C#/.NET](dotnet.qmd#terrestrial-statistical-model){.btn .btn-outline-primary .btn role="button"}
+[MATLAB](matlab.qmd#terrestrial-statistical-model){.btn .btn-outline-primary .btn role="button"}
+[Python](python.qmd#terrestrial-statistical-model){.btn .btn-outline-primary .btn role="button"}
 
-## Aeronautical Statistical Model
+### Aeronautical Statistical Model
 
-This model provides equations to calculate the statistical distribution of clutter loss where one end of the interference path is within man-made clutter, and the other is a satellite, aeroplane, or other platform above the surface of the Earth.  Validity of the model is as follows:
+The Earth-space and aeronautical statistical clutter loss model is described in @p2108-1 [Section 3.3]. This model is applicable when one terminal is within man-made clutter and the other is a satellite, aeroplane, or other platform above the surface of the Earth. The model is applicable to urban and suburban clutter environments.
 
-* Frequency range: 10 to 100 GHz
-* Elevation angle range: 0 to 90 degrees
-* Percentage locations range: 0 < `p` < 100
+This model calculates an additional loss, $L_{ces}$, which can be added to the basic transmission loss of a path calculated. As this is a statistical model, the term $L_{ces}$ is the clutter loss not exceeded for $p$ percent of locations.
 
-Example: [C#](P2108-(.NET)#aeronautical-statistical-model) | [MATLAB](P2108-(MATLAB)#aeronautical-statistical-model) | [Python](P2108-(Python)#aeronautical-statistical-model)
+The method used to develop this model is described in @p2402-0.
+
+| Variable      | Type   | Units  | Limits                  | Description     |
+|---------------|--------|--------|-------------------------|-----------------|
+| `f__ghz`      | double | GHz    | $10 \leq f \leq 100$    | Frequency       |
+| `theta__deg`  | double | degree | $0 \leq \theta \leq 90$ | Elevation angle |
+| `p`           | double | %      | $0 < p < 100$           | Percentage of locations at which predicted clutter loss will not be exceeded |
+: Inputs for the aeronautical statistical model {#tbl-p2108-3p3-inputs}
+
+{{< include /includes/_code_examples.qmd >}}
+
+[C++](cpp.qmd#aeronautical-statistical-model){.btn .btn-outline-primary .btn role="button"}
+[C#/.NET](dotnet.qmd#aeronautical-statistical-model){.btn .btn-outline-primary .btn role="button"}
+[MATLAB](matlab.qmd#aeronautical-statistical-model){.btn .btn-outline-primary .btn role="button"}
+[Python](python.qmd#aeronautical-statistical-model){.btn .btn-outline-primary .btn role="button"}

references.bib

@@ -7,4 +7,26 @@ @techreport{longley-rice
   number      = "ERL 79-ITS 67",
   month       = "7",
   url         = "https://its.ntia.gov/publications/2784.aspx"
+}
+
+@techreport{p2108-1,
+  author      = "",
+  title       = {{Prediction of clutter loss}},
+  institution = "International Telecommunications Union",
+  year        = "2021",
+  type        = "Recommendation ITU-R",
+  number      = "P.2108-1",
+  month       = "9",
+  url         = "https://www.itu.int/rec/R-REC-P.2108"
+}
+
+@techreport{p2402-0,
+  author      = "",
+  title       = {{A method to predict the statistics of clutter loss for earth-space and aeronautical paths}},
+  institution = "International Telecommunications Union",
+  year        = "2017",
+  type        = "Recommendation ITU-R",
+  number      = "P.2402-0",
+  month       = "3",
+  url         = "https://www.itu.int/pub/R-REP-P.2402-2017"
 }