diff --git a/.github/workflows/quarto-publish.yml b/.github/workflows/quarto-publish.yml index c013c3f..f6acf20 100644 --- 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 index 997d493..6e30b19 100644 --- 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 new file mode 100644 index 0000000..09f2867 Binary files /dev/null and b/images/matlab/add-ons-menu.png differ diff --git a/images/matlab/add-to-matlab-menu.PNG b/images/matlab/add-to-matlab-menu.PNG new file mode 100644 index 0000000..73b487f Binary files /dev/null and b/images/matlab/add-to-matlab-menu.PNG differ diff --git a/images/matlab/install-online.png b/images/matlab/install-online.png new file mode 100644 index 0000000..3a7a52e Binary files /dev/null and b/images/matlab/install-online.png differ diff --git a/images/matlab/manage-add-ons-context-menu.png b/images/matlab/manage-add-ons-context-menu.png new file mode 100644 index 0000000..0ffd33b Binary files /dev/null and b/images/matlab/manage-add-ons-context-menu.png differ diff --git a/images/matlab/manage-add-ons-menu.png b/images/matlab/manage-add-ons-menu.png new file mode 100644 index 0000000..c5499a1 Binary files /dev/null and b/images/matlab/manage-add-ons-menu.png differ diff --git a/includes/_cpp_documentation_block.qmd b/includes/cpp/_documentation.qmd similarity index 100% rename from includes/_cpp_documentation_block.qmd rename to includes/cpp/_documentation.qmd diff --git a/includes/matlab/_documentation.qmd b/includes/matlab/_documentation.qmd new file mode 100644 index 0000000..7104aef --- /dev/null +++ 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 new file mode 100644 index 0000000..caff953 --- /dev/null +++ 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. \ No newline at end of file diff --git a/includes/matlab/_getting_started.qmd b/includes/matlab/_getting_started.qmd new file mode 100644 index 0000000..978625d --- /dev/null +++ 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"} \ No newline at end of file diff --git a/includes/_py_documentation_block.qmd b/includes/python/_documentation.qmd similarity index 100% rename from includes/_py_documentation_block.qmd rename to includes/python/_documentation.qmd diff --git a/includes/python/_getting_started.qmd b/includes/python/_getting_started.qmd new file mode 100644 index 0000000..3a095cf --- /dev/null +++ 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. \ No newline at end of file diff --git a/includes/python/_uninstallation.qmd b/includes/python/_uninstallation.qmd new file mode 100644 index 0000000..e632bb8 --- /dev/null +++ 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 index 0e60fc3..f88ea7a 100644 --- 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 index 77d19d0..a7b1d66 100644 --- 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 index 4357c40..36ed840 100644 --- 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 index f11e9ad..b40cbe4 100644 --- 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 >}} \ No newline at end of file +% L_ces__db is approximately 14.3 dB +``` \ No newline at end of file diff --git a/models/P2108/python.qmd b/models/P2108/python.qmd index b34cc1d..191f749 100644 --- 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 ```