From ad1ef2847b9e9c67cc43d7b934277573899cf529 Mon Sep 17 00:00:00 2001 From: Anthony Romaniello Date: Tue, 9 Jul 2024 17:19:37 -0400 Subject: [PATCH] Add P2108 C++ docs page Also disable buttons linking to .NET and MATLAB pages for now --- includes/_cpp_documentation_block.qmd | 3 + includes/_getting_started.qmd | 4 +- models/P2108/cpp.qmd | 104 ++++++++++++++++++++++++++ models/P2108/index.qmd | 12 +-- 4 files changed, 115 insertions(+), 8 deletions(-) create mode 100644 includes/_cpp_documentation_block.qmd diff --git a/includes/_cpp_documentation_block.qmd b/includes/_cpp_documentation_block.qmd new file mode 100644 index 0000000..393c08b --- /dev/null +++ b/includes/_cpp_documentation_block.qmd @@ -0,0 +1,3 @@ +## Documentation + +All functions and/or objects provided by this C++ library are documented using [Doxygen](https://www.doxygen.nl/). These auto-generated documentation pages constitute an API reference which documents any available functions, classes, structs, etc. For functions, the documentation details the input, output, and return types and describes all parameters. Visit the C++ API reference documentation site using the button below. \ No newline at end of file diff --git a/includes/_getting_started.qmd b/includes/_getting_started.qmd index 595990b..dbfb05e 100644 --- a/includes/_getting_started.qmd +++ b/includes/_getting_started.qmd @@ -3,6 +3,6 @@ This page documents the inputs, outputs, and primary functions of this software in a language-agnostic way. Language-specific documentation is additionally provided for this library. The pages linked below include installation instructions as well as usage examples for each supported language. [C++](cpp.qmd){.btn .btn-secondary role="button"} -[C#/.NET](dotnet.qmd){.btn .btn-secondary role="button"} -[MATLAB](matlab.qmd){.btn .btn-secondary role="button"} +[C#/.NET](dotnet.qmd){.btn .btn-secondary disabled role="button"} +[MATLAB](matlab.qmd){.btn .btn-secondary disabled role="button"} [Python](python.qmd){.btn .btn-secondary role="button"} \ No newline at end of file diff --git a/models/P2108/cpp.qmd b/models/P2108/cpp.qmd index f93dfae..f91be31 100644 --- a/models/P2108/cpp.qmd +++ b/models/P2108/cpp.qmd @@ -3,3 +3,107 @@ title: "ITU-R P.2108 – C++" --- {{< 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. + +{{< include /includes/_link_to_model_home.qmd >}} + +## Installation + +{{< include /includes/_package_install_not_ready.qmd >}} + +To use the C++ library in your code, you'll need to download the dynamic library (`.dll` on Windows, `.dylib` on macOS, or `.so` on Linux) and the header file. These are distributed for each platform as part of the [GitHub Releases](https://github.com/NTIA/p2108/releases/) starting with v1.0. Prior to v1.0, support was only provided for Windows platforms. + +To use the dynamic library in your project, you'll need to link against it. The details for this process differ depending on your compiler and/or IDE, but generally you will need to somehow provide the path to the files you downloaded from the GitHub release. + +Once you've linked the dynamic library to your project, all you need to do is include the appropriate header file and, optionally, use its namespace: + +```cpp +#include "P2108.h" + +using namespace ITS::ITU::PSeries:P2108; // Optional: makes later code more concise +``` + +This library has no external C++ dependencies. + +{{< include /includes/_cpp_documentation_block.qmd >}} + +[Docs](https://ntia.github.io/p2108){.btn .btn-secondary .btn role="button"} + +## Examples + +The following code examples show how each of the three models from Recommendation ITU-R P.2108 can be called from Python. + +### Height Gain Terminal Correction Model + +```cpp +#include "P2108.h" +using namespace ITS::ITU::PSeries; + +int main() { + // Define inputs + double f__ghz = 1; // Frequency, in GHz + double h__meter = 1.5; // Antenna height, in meters + double w_s__meter = 27; // Street width, in meters + double R__meter = 20; // Representative clutter height, in meters + P2108::ClutterType clutter_type = DENSE_URBAN; // Clutter type, enum + + // Create variables to store outputs + double A_h__db; // Predicted additional loss, in dB + int rtn; // Return code + + // Call height gain terminal correction model (P.2108 Section 3.1) + rtn = P2108::HeightGainTerminalCorrectionModel(f__ghz, h__meter, w_s__meter, R__meter, clutter_type, &A_h__db); + + // rtn is 0 (SUCCESS) + // A_h__dB is approx. 8.8 dB +} +``` + +### Terrestrial Statistical Model + +```cpp +#include "P2108.h" +using namespace ITS::ITU::PSeries; + +int main() { + // Define inputs + double f__ghz = 3; // Frequency, in GHz + double d__km = 0.5; // Path distance, in km + double p = 50; // Percentage of locations, in % + + // Create variables to store outputs + double L_ctt__db; // Predicted additional loss, in dB + int rtn; // Return code + + // Call terrestrial statistical model (P.2108 Section 3.2) + rtn = P2108::TerrestrialStatisticalModel(f__ghz, d__km, p, &L_ctt__db); + + // rtn is 0 (SUCCESS) + // L_ctt__db is approx. 26.1 dB +} +``` + +### Aeronautical Statistical Model + +```cpp +#include "P2108.h" +using namespace ITS::ITU::PSeries; + +int main() { + // Define inputs + double f__ghz = 15; // Frequency, in GHz + double theta__deg = 10; // Elevation angle, in degrees + double p = 50; // Percentage of locations, in % + + // Create variables to store outputs + double L_ces__db; // Predicted additional loss, in dB + int rtn; // Return code + + // Call aeronautical statistical model (P.2108 Section 3.3) + rtn = P2108::AeronauticalStatisticalModel(f__ghz, theta__deg, p, &L_ces__db); + + // rtn is 0 (SUCCESS) + // L_ces__db is approx. 14.3 dB +} +``` diff --git a/models/P2108/index.qmd b/models/P2108/index.qmd index 63902f2..6d81a36 100644 --- a/models/P2108/index.qmd +++ b/models/P2108/index.qmd @@ -44,8 +44,8 @@ This table also provides the integer values mapped to each clutter type in the e {{< include /includes/_code_examples.qmd >}} [C++](cpp.qmd#height-gain-terminal-correction-model){.btn .btn-secondary role="button"} -[C#/.NET](dotnet.qmd#height-gain-terminal-correction-model){.btn .btn-secondary role="button"} -[MATLAB](matlab.qmd#height-gain-terminal-correction-model){.btn .btn-secondary role="button"} +[C#/.NET](dotnet.qmd#height-gain-terminal-correction-model){.btn .btn-secondary disabled role="button"} +[MATLAB](matlab.qmd#height-gain-terminal-correction-model){.btn .btn-secondary disabled role="button"} [Python](python.qmd#height-gain-terminal-correction-model){.btn .btn-secondary role="button"} ### Terrestrial Statistical Model @@ -64,8 +64,8 @@ This model calculates an additional loss, $L_{ctt}$, which can be added to the t {{< include /includes/_code_examples.qmd >}} [C++](cpp.qmd#terrestrial-statistical-model){.btn .btn-secondary .btn role="button"} -[C#/.NET](dotnet.qmd#terrestrial-statistical-model){.btn .btn-secondary .btn role="button"} -[MATLAB](matlab.qmd#terrestrial-statistical-model){.btn .btn-secondary .btn role="button"} +[C#/.NET](dotnet.qmd#terrestrial-statistical-model){.btn .btn-secondary .btn disabled role="button"} +[MATLAB](matlab.qmd#terrestrial-statistical-model){.btn .btn-secondary disabled .btn role="button"} [Python](python.qmd#terrestrial-statistical-model){.btn .btn-secondary .btn role="button"} ### Aeronautical Statistical Model @@ -86,6 +86,6 @@ The method used to develop this model is described in @p2402-0. {{< include /includes/_code_examples.qmd >}} [C++](cpp.qmd#aeronautical-statistical-model){.btn .btn-secondary .btn role="button"} -[C#/.NET](dotnet.qmd#aeronautical-statistical-model){.btn .btn-secondary .btn role="button"} -[MATLAB](matlab.qmd#aeronautical-statistical-model){.btn .btn-secondary .btn role="button"} +[C#/.NET](dotnet.qmd#aeronautical-statistical-model){.btn .btn-secondary .btn disabled role="button"} +[MATLAB](matlab.qmd#aeronautical-statistical-model){.btn .btn-secondary .btn disabled role="button"} [Python](python.qmd#aeronautical-statistical-model){.btn .btn-secondary .btn role="button"} \ No newline at end of file