NTIA · aromanielloNTIA · Nov 1, 2024 · Nov 6, 2024 · Nov 21, 2024 · Nov 21, 2024
diff --git a/.github/workflows/quarto-publish.yml b/.github/workflows/quarto-publish.yml
@@ -28,7 +28,7 @@ jobs:
       uses: quarto-dev/quarto-actions/setup@v2
 
     - name: Setup Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: '3.10'
     - run: pip install jupyter

diff --git a/.gitignore b/.gitignore
@@ -7,3 +7,4 @@ models/P528
 **/index_files/
 **/*_files
 /env/
+.vscode
diff --git a/images/matlab/add-ons-menu.png b/images/matlab/add-ons-menu.png
diff --git a/images/matlab/add-to-matlab-menu.PNG b/images/matlab/add-to-matlab-menu.PNG
diff --git a/images/matlab/install-online.png b/images/matlab/install-online.png
diff --git a/images/matlab/manage-add-ons-context-menu.png b/images/matlab/manage-add-ons-context-menu.png
diff --git a/images/matlab/manage-add-ons-menu.png b/images/matlab/manage-add-ons-menu.png
diff --git a/includes/_cpp_documentation_block.qmd → includes/cpp/_documentation.qmd b/includes/_cpp_documentation_block.qmd → includes/cpp/_documentation.qmd
diff --git a/includes/matlab/_documentation.qmd b/includes/matlab/_documentation.qmd
@@ -0,0 +1,3 @@
+## Documentation
+
+All functions and/or objects provided by this MATLAB Toolbox contain built-in help documentation. This means that you can find details about inputs, outputs, and usage syntax right from the MATLAB Command Window. For example:
diff --git a/includes/matlab/_examples.qmd b/includes/matlab/_examples.qmd
@@ -0,0 +1,13 @@
+## Examples
+
+The code examples provided here are also included in the toolbox itself, as MATLAB Live Scripts. To access these, view the toolbox "Getting Started" guide as follows.
+
+1. Once installed, view the toolbox in the **Add-Ons > Manage Add-Ons** menu as shown in @fig-matlab-manage-add-ons-menu-2.
+
+    ![](/images/matlab/manage-add-ons-menu.png){#fig-matlab-manage-add-ons-menu-2 fig-alt="A screenshot showing the MATLAB 'Manage Add-Ons' menu option" width=300 fig-align="left"}
+
+1. Find the installed toolbox in the list, and click the **⋮** icon and select **View Getting Started Guide** as shown in @fig-matlab-manage-add-ons-context-menu.
+
+    ![](/images/matlab/manage-add-ons-context-menu.png){#fig-matlab-manage-add-ons-context-menu fig-alt="A screenshot showing the context menu for an installed toolbox in the MATLAB 'Manage Add-Ons' menu" width=300 fig-align="left"}
+
+1. Under the **Examples** heading, links are provided for Live Script example programs which demonstrate usage of the toolbox in an interactive way. The same code examples are additionally provided below.
diff --git a/includes/matlab/_getting_started.qmd b/includes/matlab/_getting_started.qmd
@@ -0,0 +1,31 @@
+There are two easy ways to install the toolbox: [from a browser](#installing-from-a-browser) or [from within MATLAB](#installing-from-within-matlab).
+
+### Installation from a Browser
+
+1. Open this package's page on the File Exchange using the link provided [above](#getting-started).
+
+1. In the upper-right, click **Download > Toolbox** as shown in @fig-matlab-install-online. A file with a `.mltbx` extension will download.
+
+    ![](/images/matlab/install-online.png){#fig-matlab-install-online fig-alt="Screenshot showing the 'Download Toolbox' option on the MathWorks File Exchange website" width=250 fig-align="left"}
+
+1. Optionally, move the downloaded file into your project directory.
+
+1. Within MATLAB, navigate to the `.mltbx` file and double-click it.
+
+### Installation from Within MATLAB
+
+1. Open MATLAB and select **Add-Ons > Get Add-Ons** in the toolbar, as shown in @fig-matlab-add-ons-menu. The Add-On Explorer window will open.
+
+    ![](/images/matlab/add-ons-menu.png){#fig-matlab-add-ons-menu fig-alt="A screenshot showing the MATLAB 'Get Add-Ons' menu option" width=300 fig-align="left"}
+
+1. Search for this package by its name.
+
+1. In the upper-right, click **Add > Add to MATLAB** as shown in @fig-matlab-add-to-matlab-menu.
+
+    ![](/images/matlab/add-to-matlab-menu.png){#fig-matlab-add-to-matlab-menu fig-alt="A screenshot showing the 'Add to MATLAB' option for a toolbox within the Add-On Explorer" width=200 fig-align="left"}
+
+### Uninstallation
+
+Regardless of how you installed the toolbox, you can uninstall it at any time from the **Add-Ons > Manage Add-Ons** menu. This is available in the MATLAB toolbar as shown in @fig-matlab-manage-add-ons-menu.
+
+![](/images/matlab/manage-add-ons-menu.png){#fig-matlab-manage-add-ons-menu fig-alt="A screenshot showing the MATLAB 'Manage Add-Ons' menu option" width=300 fig-align="left"}
diff --git a/includes/_py_documentation_block.qmd → includes/python/_documentation.qmd b/includes/_py_documentation_block.qmd → includes/python/_documentation.qmd
diff --git a/includes/python/_getting_started.qmd b/includes/python/_getting_started.qmd
@@ -0,0 +1,12 @@
+## Getting Started
+
+All ITS PropLib Python packages require a
+[currently-supported](https://devguide.python.org/versions/)
+version of Python. You may choose to use a tool such as
+[pyenv](https://github.com/pyenv/pyenv) or
+[conda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html)
+to manage multiple Python versions on your machine. Additionally,
+you may choose to set up a virtual environment for your project,
+using conda or a tool such as [`venv`](https://docs.python.org/3/library/venv.html).
+Installation instructions assume that you have a supported version of Python installed,
+and that you're working from the desired Python environment.
diff --git a/includes/python/_uninstallation.qmd b/includes/python/_uninstallation.qmd
@@ -0,0 +1,4 @@
+### Uninstallation
+
+Uninstalling this Python package is also simple. Run the following
+command in your Python environment.
diff --git a/models/P2108/cpp.qmd b/models/P2108/cpp.qmd
@@ -1,12 +1,12 @@
 ---
-title: "ITU-R P.2108 – C++"
+title: "Recommendation ITU-R P.2108 – C++"
 date: 2024-07-09
-date-modified: 2024-11-20
+date-modified: 2024-12-03
 ---
 
 {{< include /includes/_under_construction.qmd >}}
 
-This page details the installation and usage of the C++ version of the U.S. Reference Implementation of Recommendation ITU-R P.2108.
+This page details the installation and usage of the C++ version of the PropLib implementation of Recommendation ITU-R P.2108.
 
 {{< include /includes/_link_to_model_home.qmd >}}
 
@@ -28,7 +28,7 @@ using namespace ITS::ITU::PSeries:P2108;  // Optional: makes later code more con
 
 This library has no external C++ dependencies.
 
-{{< include /includes/_cpp_documentation_block.qmd >}}
+{{< include /includes/cpp/_documentation.qmd >}}
 
 [Docs](https://ntia.github.io/p2108){.btn .btn-secondary .btn role="button"}
 

diff --git a/models/P2108/dotnet.qmd b/models/P2108/dotnet.qmd
@@ -2,7 +2,9 @@
 title: "Recommendation ITU-R P.2108 – .NET"
 ---
 
-{{< include /includes/_under_construction.qmd >}}
+This page details the installation and usage of the .NET version of Recommendation ITU-R P.2108.
+
+{{< include /includes/_link_to_model_home.qmd >}}
 
 ## Getting Started
 

diff --git a/models/P2108/index.qmd b/models/P2108/index.qmd
@@ -52,7 +52,7 @@ This table also provides the integer values mapped to each clutter type in the e
 
 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.
 
-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 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 terrestrial 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.
 
 | Variable | Type   | Units | Limits               | Description   |
 |----------|--------|-------|----------------------|---------------|

diff --git a/models/P2108/matlab.qmd b/models/P2108/matlab.qmd
@@ -2,26 +2,76 @@
 title: "Recommendation ITU-R P.2108 – MATLAB"
 ---
 
-{{< include /includes/_under_construction.qmd >}}
+This page details the installation and usage of the MATLAB® Toolbox version of the PropLib implementation of Recommendation ITU-R P.2108.
+
+{{< include /includes/_link_to_model_home.qmd >}}
 
 ## Getting Started
 
-{{< include /includes/_package_install_not_ready.qmd >}}
+This MATLAB® Toolbox is distributed on [MathWorks® File Exchange](#TODO).
+
+{{< include /includes/matlab/_getting_started.qmd >}}
+
+{{< include /includes/matlab/_documentation.qmd >}}
+
+```matlab
+help ITS.ITU.PSeries.P2108.AeronauticalStatisticalModel
+
+% Prints detailed usage information!
+```
+
+{{< include /includes/matlab/_examples.qmd >}}
+
+### Height Gain Terminal Correction Model
+
+This example shows multiple equivalent ways to specify the clutter type input.
+
+```matlab
+import ITS.ITU.PSeries.P2108.*
+
+% Define inputs
+f__ghz = 1;        % Frequency, in GHz
+h__meter = 1.5;    % Antenna height, in meters
+w_s__meter = 27;   % Street width, in meters
+R__meter = 20;     % Representative clutter height, in meters
+clutter_type = 6;  % Clutter type enum value
+clutter_type = ClutterType.DENSE_URBAN;
+clutter_type = "DENSE_URBAN";
+
+% Call the model
+A_h__db = HeightGainTerminalCorrectionModel(f__ghz, h__meter, w_s__meter, R__meter, clutter_type);
+
+% A_h__db is approximately 25.5 dB
+```
+
+### Terrestrial Statistical Model
 
-## Documentation
+```matlab
+import ITS.ITU.PSeries.P2108.*
 
-{{< include /includes/_under_construction.qmd >}}
+% Define inputs
+f__ghz = 3;   % Frequency, in GHz
+d__km = 0.5;  % Path distance, in km
+p = 50;       % Percentage of locations, in %
 
-# Examples
+% Call the model
+L_ctt__db = TerrestrialStatisticalModel(f__ghz, d__km, p);
 
-## Height Gain Terminal Correction Model
+% L_ctt__db is approximately 26.6 dB
+```
 
-{{< include /includes/_under_construction.qmd >}}
+### Aeronautical Statistical Model
 
-## Terrestrial Statistical Model
+```matlab
+import ITS.ITU.PSeries.P2108.*
 
-{{< include /includes/_under_construction.qmd >}}
+% Define inputs
+f__ghz = 15;      % Frequency, in GHz
+theta__deg = 10;  % Elevation angle, in degrees
+p = 50;           % Percentage of locations, in %
 
-## Aeronautical Statistical Model
+% Call the model
+L_ces__db = AeronauticalStatisticalModel(f__ghz, theta__deg, p);
 
-{{< include /includes/_under_construction.qmd >}}
+% L_ces__db is approximately 14.3 dB
+```
diff --git a/models/P2108/python.qmd b/models/P2108/python.qmd
@@ -4,24 +4,36 @@ date: 2024-06-25
 date-modified: 2024-11-20
 ---
 
-This page details the installation and usage of the Python version of the U.S. Reference Implementation of Recommendation ITU-R P.2108.
+This page details the installation and usage of the Python version of the PropLib implementation of Recommendation ITU-R P.2108.
 
 {{< include /includes/_link_to_model_home.qmd >}}
 
-## Installation
+{{< include /includes/python/_getting_started.qmd >}}
 
-{{< include /includes/_package_install_not_ready.qmd >}}
+### Installation
 
-The following code snippet shows how to import the package and check the installed version:
+This Python package is distributed through the
+[Python Package Index (PyPI)](https://pypi.org/project/proplib-p2108).
+Run the following command to install the package, and any required dependencies, into your Python environment.
+
+```default
+pip install proplib-p2108
+```
+
+The following code snippet shows how to import the package and check the installed version.
 
 ```python
 from ITS.ITU.PSeries import P2108
 print(P2108.__version__)
 ```
 
-This package has no external Python dependencies.
+{{< include /includes/python/_uninstallation.qmd >}}
 
-{{< include /includes/_py_documentation_block.qmd >}}
+```default
+pip uninstall proplib-p2108
+```
+
+{{< include /includes/python/_documentation.qmd >}}
 
 ```python
 help(P2108.TerrestrialStatisticalModel)
@@ -43,14 +55,12 @@ clutter_type = 6    # Clutter type, enum
 
 # Call height gain terminal correction model (P.2108 Section 3.1)
 A_h__db = P2108.HeightGainTerminalCorrectionModel(f__ghz, h__meter, w_s__meter, R__meter, clutter_type)
-assert(A_h__db == 8.769394261533549)
-
-# can also use clutter type IntEnum
-clutter_type = P2108.ClutterType.DenseUrban
+# A_h__db is approximately 25.54 dB
 
-# call clutter model
+# can also use enum to provide clutter type
+clutter_type = P2108.ClutterType.DenseUrban  # int value is 6
 A_h__db = P2108.HeightGainTerminalCorrectionModel(f__ghz, h__meter, w_s__meter, R__meter, clutter_type)
-assert(A_h__db == 8.769394261533549)
+# A_h__db is approximately 25.54 dB
 ```
 
 ### Terrestrial Statistical Model
@@ -63,7 +73,7 @@ p = 50              # Percentage of locations, in %
 
 # call terrestrial statistical model
 L_ctt__db = P2108.TerrestrialStatisticalModel(f__ghz, d__km, p)
-assert(L_ctt__db == 26.10075036783342)
+# L_ctt__db is approximately 26.63 dB
 ```
 
 ### Aeronautical Statistical Model
@@ -76,5 +86,5 @@ p = 50              # Percentage of locations, in %
 
 # call clutter model
 L_ces__db = P2108.AeronauticalStatisticalModel(f__ghz, theta__deg, p)
-assert(L_ces__db == 14.333686040067786)
+# L_ces__db is approximately 14.33 dB
 ```
-Original file line number
+Diff line change
@@ Expand Up / @@ -7,3 +7,4 @@ models/P528 @@
     **/index_files/
     **/*_files
     /env/
+    .vscode
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		## Documentation

		All functions and/or objects provided by this MATLAB Toolbox contain built-in help documentation. This means that you can find details about inputs, outputs, and usage syntax right from the MATLAB Command Window. For example: