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..b9057ee 100644 --- a/.gitignore +++ b/.gitignore @@ -1,9 +1,6 @@ /.quarto/ _site -models/eHata -models/ITM-MidBand -models/TIREM -models/P528 **/index_files/ **/*_files /env/ +.vscode diff --git a/_quarto.yml b/_quarto.yml index 041574b..5f95117 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -9,7 +9,7 @@ website: description: | The NTIA/ITS Propagation Library: a versatile and robust set of tools for propagation modeling. Learn more on our wiki. - image: images/ntia-logo-300px.png + image: images/ntia-logo-dark-bg-1946px.png image-alt: National Telecommunications and Information Administration Logo image-width: 300 image-height: 300 @@ -19,7 +19,7 @@ website: description: | The NTIA/ITS Propagation Library: a versatile and robust set of tools for propagation modeling. Learn more on our wiki. - image: images/ntia-logo-300px.png + image: images/ntia-logo-dark-bg-1200x630.png image-alt: National Telecommunications and Information Administration Logo image-width: 300 image-height: 300 @@ -32,7 +32,7 @@ website: text: Home - text: "U.S. Models" menu: - - Coming Soon + - models/LFMF/index.qmd - text: "ITU-R Models" menu: - models/P2108/index.qmd 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/images/ntia-logo-300px.png b/images/ntia-logo-300px.png deleted file mode 100644 index 4e22859..0000000 Binary files a/images/ntia-logo-300px.png and /dev/null differ diff --git a/images/ntia-logo-dark-bg-1200x630.png b/images/ntia-logo-dark-bg-1200x630.png new file mode 100644 index 0000000..9494fc1 Binary files /dev/null and b/images/ntia-logo-dark-bg-1200x630.png differ diff --git a/images/ntia-logo-dark-bg-1946px.png b/images/ntia-logo-dark-bg-1946px.png new file mode 100644 index 0000000..9191609 Binary files /dev/null and b/images/ntia-logo-dark-bg-1946px.png differ diff --git a/includes/_getting_started.qmd b/includes/_getting_started.qmd index 243ee91..6ec57e1 100644 --- a/includes/_getting_started.qmd +++ b/includes/_getting_started.qmd @@ -2,6 +2,7 @@ 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. +[Command-Line Driver](driver.qmd){.btn .btn-secondary role="button"} [C++](cpp.qmd){.btn .btn-secondary role="button"} [.NET](dotnet.qmd){.btn .btn-secondary role="button"} [MATLAB](matlab.qmd){.btn .btn-secondary role="button"} 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/driver/_general_usage.qmd b/includes/driver/_general_usage.qmd new file mode 100644 index 0000000..77da4ce --- /dev/null +++ b/includes/driver/_general_usage.qmd @@ -0,0 +1,9 @@ +# General Usage + +## Input Files + +Inputs to the command-line driver are specified in an ASCII text file using the common `key,value` format. Each line holds a single `key,value` combination, with the `key` representing the model input variable name and the `value` representing its value. Refer to the [examples](#examples) below to see the specific keys required for this model's inputs. Note that key names are not case-sensitive. + +## Output Files + +After parsing the inputs and running the software, the command-line driver will generate an output report file containing the results. This file contains a record of the input parameters along with the model outputs and human-readable supporting details. Refer to the [examples](#examples) below to see the expected format of output files generated by this model. \ No newline at end of file diff --git a/includes/driver/_intro_and_installation.qmd b/includes/driver/_intro_and_installation.qmd new file mode 100644 index 0000000..dcd584e --- /dev/null +++ b/includes/driver/_intro_and_installation.qmd @@ -0,0 +1,9 @@ +Each model in the Propagation Library is distributed with an accompanying command-line driver program. +This program allows the user to run the model from the command line on Windows, macOS, or Linux. +The model inputs and outputs are handled using simple text files. No programming experience is required to +use the command-line driver. + +{{< include /includes/_link_to_model_home.qmd >}} + +# Installation + 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/index.qmd b/index.qmd index a531ea7..93791e6 100644 --- a/index.qmd +++ b/index.qmd @@ -1,7 +1,7 @@ --- title: "ITS Propagation Library Wiki" date: 2024-06-11 -date-modified: 2024-11-20 +date-modified: 2024-12-02 --- The ITS Propagation Library (**"PropLib"**) is a collection of open source software developed by [ITS](about.qmd), focused on modeling radio wave propagation under a wide variety of circumstances. The library currently supports C++, .NET, MATLAB®, and Python users through exposing common functionality across multiple programming environments. One of the key benefits of this approach is that users are assured of identical results across languages, allowing researchers to work in their most efficient development environment while benefitting from common library improvements. @@ -12,25 +12,35 @@ Currently, PropLib includes implementations of propagation models developed by t ### U.S. Propagation Models +Over the years, ITS has developed and refined various programs for the prediction of radio propagation in a wide range of situations. + Documentation pages are being worked on, and will soon be available through links in the following table, for the following U.S. propagation models: ::: {.callout-warning} ## Page Under Construction -The listed U.S. propagation models have public code repositories, but +The HF, IF77, and MPM models are distributed as legacy software, and do not +yet have public GitHub repositories. +The eHata and ITM models have public code repositories, but documentation is not yet available on this website. Please check back later, and contact [code@ntia.gov](mailto:code@ntia.gov) with questions in the meantime. ::: -+----------:+:-------------------------------------:+:----:+:---------------------------------------------------+ -| **eHata** | [Repo](https://github.com/NTIA/eHata) | Docs | Extended Hata Urban Propagation Model | -+-----------+---------------------------------------+------+----------------------------------------------------+ -| **ITM** | [Repo](https://github.com/NTIA/ITM) | Docs | Irregular Terrain Model | -+-----------+---------------------------------------+------+----------------------------------------------------+ -| **LFMF** | [Repo](https://github.com/NTIA/LFMF) | Docs | Low Frequency / Medium Frequency Propagation Model | -+-----------+---------------------------------------+------+----------------------------------------------------+ -: U.S. propagation models available in the ITS Propagation Library {tbl-colwidths="[15,10,10,65]"} ++----------:+:-------------------------------------:+:-----------------------------------------------------------------------:+:---------------------------------------------------+ +| **eHata** | [Repo](https://github.com/NTIA/eHata) | Docs | Extended Hata Urban Propagation Model | ++-----------+---------------------------------------+-------------------------------------------------------------------------+----------------------------------------------------+ +| **HF** | [Legacy Software](https://its.ntia.gov/software/high-frequency/high-frequency-propagation-models/) | High Frequency Propagation Models | ++-----------+---------------------------------------+-------------------------------------------------------------------------+----------------------------------------------------+ +| **IF77** | [Legacy Software](https://its.ntia.gov/software/if-77-electromagnetic-wave-propagation-model-gierhart-johnson/) | The IF-77 Electromagnetic Wave Propagation Model | ++-----------+---------------------------------------+-------------------------------------------------------------------------+----------------------------------------------------+ +| **ITM** | [Repo](https://github.com/NTIA/ITM) | Docs | Irregular Terrain Model | ++-----------+---------------------------------------+-------------------------------------------------------------------------+----------------------------------------------------+ +| **LFMF** | [Repo](https://github.com/NTIA/LFMF) | [Docs](models/LFMF/) | Low Frequency / Medium Frequency Propagation Model | ++-----------+---------------------------------------+-------------------------------------------------------------------------+----------------------------------------------------+ +| **MPM** | [Legacy Software](https://its.ntia.gov/software/millimeter-wave-propagation-model-mpm/) | Millimeter-wave Propagation Model | ++-----------+---------------------------------------+-------------------------------------------------------------------------+----------------------------------------------------+ +: U.S. propagation models available in the ITS Propagation Library {tbl-colwidths="[15,20,10,55]"} ### ITU-R Recommendations @@ -43,10 +53,10 @@ The P.528 model has a public code repository, but documentation is not yet avail in the meantime. ::: -+-----------:+:-------------------------------------:+:------------------------------:+:------------------------------------------------------------+ -| **P.528** | [Repo](https://github.com/NTIA/P528) | Docs | A propagation prediction method for aeronautical mobile and | -| | | | radionavigation services using the VHF, UHF, and SHF bands | -+------------+---------------------------------------+--------------------------------+-------------------------------------------------------------+ -| **P.2108** | [Repo](https://github.com/NTIA/p2108) | [Docs](models/P2108/index.qmd) | Prediction of clutter loss | -+------------+---------------------------------------+--------------------------------+-------------------------------------------------------------+ ++-----------:+:-------------------------------------:+:---------------------:+:------------------------------------------------------------+ +| **P.528** | [Repo](https://github.com/NTIA/P528) | Docs | A propagation prediction method for aeronautical mobile and | +| | | | radionavigation services using the VHF, UHF, and SHF bands | ++------------+---------------------------------------+-----------------------+-------------------------------------------------------------+ +| **P.2108** | [Repo](https://github.com/NTIA/p2108) | [Docs](models/P2108/) | Prediction of clutter loss | ++------------+---------------------------------------+-----------------------+-------------------------------------------------------------+ : ITU-R Recommendations implemented in the ITS Propagation Library {tbl-colwidths="[15,10,10,65]"} diff --git a/models/ITM/_metadata.yml b/models/ITM/_metadata.yml deleted file mode 100644 index 4e88b66..0000000 --- a/models/ITM/_metadata.yml +++ /dev/null @@ -1,15 +0,0 @@ -format: - html: - code-links: - - text: NTIA/itm - icon: github - href: https://github.com/NTIA/itm - - text: NTIA/itm-dotnet - icon: github - href: https://github.com/NTIA/itm-dotnet - - text: NTIA/itm-matlab - icon: github - href: https://github.com/NTIA/itm-matlab - - text: NTIA/itm-python - icon: github - href: https://github.com/NTIA/itm-python \ No newline at end of file diff --git a/models/ITM/cpp.qmd b/models/ITM/cpp.qmd deleted file mode 100644 index 5e8f96a..0000000 --- a/models/ITM/cpp.qmd +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "Irregular Terrain Model (ITM) – C++" ---- - -{{< include /includes/_under_construction.qmd >}} diff --git a/models/ITM/dotnet.qmd b/models/ITM/dotnet.qmd deleted file mode 100644 index d03f32a..0000000 --- a/models/ITM/dotnet.qmd +++ /dev/null @@ -1,195 +0,0 @@ ---- -title: "Irregular Terrain Model (ITM) – .NET" ---- - -{{< include /includes/_under_construction.qmd >}} - -## Getting Started - -To begin, install the NuGet package, `ITM`, from the NTIA NuGet repository - -![itm nuget install screenshot](images/nuget_itm.jpg) - -All of the below code snippets requires the including the following `using` statement. - -```csharp -using ITS.Propagation; -``` - -## Documentation - -The `itm` library is packaged to support IntelliSense when developing in Visual Studio. This documentation will provide the developer with information on function descriptions, variable details, etc. - -# Examples - -The following code examples show how to use C# to call ITM functions from the .NET package. - -**Note:** These examples use an artificial terrain profile. - -## Point-to-Point Basic Transmission Loss (TLS) - -```csharp -// define the terrain profile in PFL format -var pfl = new double[] { 5, 200, 5, 7, 2, 4, 7, 5 }; - -// define link parameters -double f__mhz = 3500; // MHz -double h_tx__meter = 10; // meters, AGL -double h_rx__meter = 5; // meters, AGL -double N_0 = 301; // N-Units -double epsilon = 15; // average ground -double sigma = 0.005; // average ground -var climate = ITM.Climate.ContinentalTemperate; -var pol = ITM.Polarization.Horizontal; - -// define variability parameters -int mdvar = 13; -double time = 50; // median -double location = 50; // median -double situation = 50; // median - -// call ITM -int rtn = ITM.ITM_P2P_TLS_Ex(h_tx__meter, h_rx__meter, pfl, - climate, N_0, f__mhz, pol, epsilon, sigma, mdvar, - time, location, situation, out double A__db, - out ITM.Warnings warnings, out ITM.IntermediateValues ivals); - -// rtn = 0 // no errors -// A__db = 105.8590 // basic transmission loss, in dB -// warnings = 0 // no warnings - -// can use the intermediate values object to access additional information -// from the ITM prediction -Console.WriteLine($"The mode of propagation is {ivals.Mode}"); -Console.WriteLine($"The effective height of the TX is {ivals.h_e__meter[0]} meters"); -Console.WriteLine($"The free space basic transmission loss is {ivals.A_fs__db} dB"); -// The mode of propagation is LineOfSight -// The effective height of the TX is 10.222222222222221 meters. -// The free space basic transmission loss is 103.33136088700552 dB. -``` - -## Point-to-Point Basic Transmission Loss (CR) - -```csharp -// define the terrain profile in PFL format -var pfl = new double[] { 5, 200, 5, 7, 2, 4, 7, 5 }; - -// define link parameters -double f__mhz = 1500; // MHz -double h_tx__meter = 10; // meters, AGL -double h_rx__meter = 5; // meters, AGL -double N_0 = 301; // N-Units -double epsilon = 15; // average ground -double sigma = 0.005; // average ground -var climate = ITM.Climate.ContinentalTemperate; -var pol = ITM.Polarization.Horizontal; - -// define variability parameters -int mdvar = 13; -double confidence = 50; // median -double reliability = 50; // median - -// call ITM -int rtn = ITM.ITM_P2P_CR_Ex(h_tx__meter, h_rx__meter, pfl, - climate, N_0, f__mhz, pol, epsilon, sigma, mdvar, - confidence, reliability, out double A__db, - out ITM.Warnings warnings, out ITM.IntermediateValues ivals); - -// rtn = 0 // no errors -// A__db = 99.9744 // basic transmission loss, in dB -// warnings = 0 // no warnings - -// can use the intermediate values object to access additional information -// from the ITM prediction -Console.WriteLine($"The mode of propagation is {ivals.Mode}"); -Console.WriteLine($"The effective height of the TX is {ivals.h_e__meter[0]} meters"); -Console.WriteLine($"The free space basic transmission loss is {ivals.A_fs__db} dB"); -// The mode of propagation is LineOfSight -// The effective height of the TX is 10.222222222222221 meters. -// The free space basic transmission loss is 95.971825 dB. -``` - -## Area Mode Basic Transmission Loss (TLS) - -```csharp -// define link parameters -double f__mhz = 1500; // MHz -double h_tx__meter = 10; // meters, AGL -double h_rx__meter = 5; // meters, AGL -double N_0 = 301; // N-Units -double epsilon = 15; // average ground -double sigma = 0.005; // average ground -double d__km = 100; // km -double delta_h__meter = 40; // meter -var tx_site_criteria = ITM.SitingCriteria.Careful; -var rx_site_criteria = ITM.SitingCriteria.Careful; -var climate = ITM.Climate.ContinentalTemperate; -var pol = ITM.Polarization.Horizontal; - -// define variability parameters -int mdvar = 13; -double time = 50; // median -double location = 50; // median -double situation = 50; // median - -// call ITM -int rtn = ITM.ITM_AREA_TLS_Ex(h_tx__meter, h_rx__meter, - tx_site_criteria, rx_site_criteria, d__km, delta_h__meter, - climate, N_0, f__mhz, pol, epsilon, sigma, mdvar, - time, location, situation, out double A__db, - out ITM.Warnings warnings, out ITM.IntermediateValues ivals); -// rtn = 0 // no errors -// A__db = 191.0266 // basic transmission loss, in dB -// warnings = 0 // no warnings - -// can use the intermediate values object to access additional information -// from the ITM prediction -Console.WriteLine($"The mode of propagation is {ivals.Mode}"); -Console.WriteLine($"The effective height of the TX is {ivals.h_e__meter[0]} meters."); -Console.WriteLine($"The free space basic transmission loss is {ivals.A_fs__db} dB."); -// The mode of propagation is Troposcatter -// The effective height of the TX is 13.032653 meters. -// The free space basic transmission loss is 135.971825 dB. -``` - -## Area Mode Basic Transmission Loss (CR) - -```csharp -// define link parameters -double f__mhz = 5000; // MHz -double h_tx__meter = 10; // meters, AGL -double h_rx__meter = 5; // meters, AGL -double N_0 = 301; // N-Units -double epsilon = 15; // average ground -double sigma = 0.005; // average ground -double d__km = 100; // km -double delta_h__meter = 40; // meter -var tx_site_criteria = ITM.SitingCriteria.Careful; -var rx_site_criteria = ITM.SitingCriteria.Careful; -var climate = ITM.Climate.ContinentalTemperate; -var pol = ITM.Polarization.Horizontal; - -// define variability parameters -int mdvar = 13; -double confidence = 50; // median -double reliability = 50; // median - -// call ITM -int rtn = ITM.ITM_AREA_CR_Ex(h_tx__meter, h_rx__meter, - tx_site_criteria, rx_site_criteria, d__km, delta_h__meter, - climate, N_0, f__mhz, pol, epsilon, sigma, mdvar, - confidence, reliability, out double A__db, - out ITM.Warnings warnings, out ITM.IntermediateValues ivals); -// rtn = 0 // no errors -// A__db = 205.7474 // basic transmission loss, in dB -// warnings = 0 // no warnings - -// can use the intermediate values object to access additional information -// from the ITM prediction -Console.WriteLine($"The mode of propagation is {ivals.Mode}"); -Console.WriteLine($"The effective height of the TX is {ivals.h_e__meter[0]} meters."); -Console.WriteLine($"The free space basic transmission loss is {ivals.A_fs__db} dB."); -// The mode of propagation is Troposcatter -// The effective height of the TX is 13.032653 meters. -// The free space basic transmission loss is 146.429400 dB. -``` \ No newline at end of file diff --git a/models/ITM/images/nuget_itm.jpg b/models/ITM/images/nuget_itm.jpg deleted file mode 100644 index d57c694..0000000 Binary files a/models/ITM/images/nuget_itm.jpg and /dev/null differ diff --git a/models/ITM/index.qmd b/models/ITM/index.qmd deleted file mode 100644 index 7642821..0000000 --- a/models/ITM/index.qmd +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Irregular Terrain Model (ITM) ---- - -{{< include /includes/_under_construction.qmd >}} - -A description of the Irregular Terrain Model (ITM), as well as details on input parameters, can be found at the [public GitHub repo](https://github.com/NTIA/itm). - -{{< include /includes/_getting_started.qmd >}} - -# Functions - -## Point-to-Point Basic Transmission Loss (TLS) - -Generate a basic transmission loss prediction by operating ITM in point-to-point mode. Variabilities are provided as time, location, and situation percentages. - -Example: [C#](ITM-(.NET)#point-to-point-basic-transmission-loss-tls) | [MATLAB](ITM-(MATLAB)#point-to-point-basic-transmission-loss-tls) | [Python](ITM-(Python)#site-specific-basic-transmission-loss-tls) - -## Point-to-Point Basic Transmission Loss (CR) - -Generate a basic transmission loss prediction by operating ITM in point-to-point mode. Variabilities are provided as confidence and reliability percentages. - -Example: [C#](ITM-(.NET)#point-to-point-basic-transmission-loss-cr) | [MATLAB](ITM-(MATLAB)#point-to-point-basic-transmission-loss-cr) | [Python](ITM-(Python)#site-specific-basic-transmission-loss-cr) - -## Area Mode Basic Transmission Loss (TLS) - -Generate a basic transmission loss prediction by operating ITM in area mode. Variabilities are provided as time, location, and situation percentages. - -Example: [C#](ITM-(.NET)#area-mode-basic-transmission-loss-tls) | [MATLAB](ITM-(MATLAB)#area-mode-basic-transmission-loss-tls) | [Python](ITM-(Python)#area-mode-basic-transmission-loss-tls) - -## Area Mode Basic Transmission Loss (CR) - -Generate a basic transmission loss prediction by operating ITM in area mode. Variabilities are provided as confidence and reliability percentages. - -Example: [C#](ITM-(.NET)#area-mode-basic-transmission-loss-cr) | [MATLAB](ITM-(MATLAB)#area-mode-basic-transmission-loss-cr) | [Python](ITM-(Python)#area-mode-basic-transmission-loss-cr) \ No newline at end of file diff --git a/models/ITM/matlab.qmd b/models/ITM/matlab.qmd deleted file mode 100644 index f2c5aee..0000000 --- a/models/ITM/matlab.qmd +++ /dev/null @@ -1,205 +0,0 @@ ---- -title: "Irregular Terrain Model (ITM) – MATLAB" ---- - -{{< include /includes/_under_construction.qmd >}} - -## Getting Started - -{{< include /includes/_package_install_not_ready.qmd >}} - -## Documentation - -All `itm` functions are docummented with detailed headers, such as: - -```matlab -% Function ITM_P2P_TLS(...) -% -% Description: Calculates the propagation loss between antennas -% using ITM -% -% Inputs: -% h_tx__meter : Structural height of the TX, in meters -% h_rx__meter : Structural height of the RX, in meters -% radio_climate : Radio climate -% time : Time percentage (0 < p < 100) -% location : Location percentage (0 < p < 100) -% situation : Situation percentage (0 < p < 100) -% pfl : Terrain data, in PFL format -% N_0 : Refractivity, in N-Units -% f__mhz : Frequency, in MHz -% polarization : Polarization -% epsilon : Relative permittivity -% sigma : Conductivity -% mdvar : Mode of variability -% -% Outputs: -% rtn : Error code -% A__db : Basic transmission loss, in dB -% warnings : Warning flags -% interValues : Intermedate values -``` - -# Examples - -**Note:** These examples use an artificial terrain profile. - -## Point-to-Point Basic Transmission Loss (TLS) - -```matlab -% define the terrain profile in PFL format -pfl = [5, 200, 5, 7, 2, 4, 7, 5]; - -% define link parameters -f__mhz = 3500; % MHz -h_tx__meter = 10; % meters, AGL -h_rx__meter = 5; % meters, AGL -N_0 = 301; % N-Units -epsilon = 15; % average ground -sigma = 0.005; % average ground -climate = ITMClimate.ContinentalTemperate; -pol = ITMPolarization.Horizontal; - -% define variability parameters -mdvar = 13; -time = 50; % median -location = 50; % median -situation = 50; % median - -% call ITM -[rtn, A__db, warnings, ivals] = ITM.ITM_P2P_TLS(h_tx__meter, h_rx__meter, ... - pfl, climate, N_0, f__mhz, pol, epsilon, sigma, mdvar, ... - time, location, situation) -% rtn = 0 % no errors -% A__db = 105.8590 % basic transmission loss, in dB -% warnings = 0 % no warnings - -% can use the intermediate values object to access additional information -% from the ITM prediction -fprintf('The mode of propagation is %s\n', ivals.Mode) -fprintf('The effective height of the TX is %f meters\n', ivals.h_e__meter(1)) -fprintf('The free space basic transmission loss is %f dB\n', ivals.A_fs__db) -% The mode of propagation is LineOfSight -% The effective height of the TX is 10.222222222222221 meters. -% The free space basic transmission loss is 103.33136088700552 dB. -``` - -## Point-to-Point Basic Transmission Loss (CR) - -```matlab -% define the terrain profile in PFL format -pfl = [5, 200, 5, 7, 2, 4, 7, 5]; - -% define link parameters -f__mhz = 1500; % MHz -h_tx__meter = 10; % meters, AGL -h_rx__meter = 5; % meters, AGL -N_0 = 301; % N-Units -epsilon = 15; % average ground -sigma = 0.005; % average ground -climate = ITMClimate.ContinentalTemperate; -pol = ITMPolarization.Horizontal; - -% define variability parameters -mdvar = 13; -confidence = 50; % median -reliability = 50; % median - -% call ITM -[rtn, A__db, warnings, ivals] = ITM.ITM_P2P_CR(h_tx__meter, h_rx__meter, ... - pfl, climate, N_0, f__mhz, pol, epsilon, sigma, mdvar, ... - confidence, reliability) -% rtn = 0 % no errors -% A__db = 99.9744 % basic transmission loss, in dB -% warnings = 0 % no warnings - -% can use the intermediate values object to access additional information -% from the ITM prediction -fprintf('The mode of propagation is %s\n', ivals.Mode) -fprintf('The effective height of the TX is %f meters\n', ivals.h_e__meter(1)) -fprintf('The free space basic transmission loss is %f dB\n', ivals.A_fs__db) -% The mode of propagation is LineOfSight -% The effective height of the TX is 10.222222222222221 meters. -% The free space basic transmission loss is 95.971825 dB. -``` - -## Area Mode Basic Transmission Loss (TLS) - -```matlab -% define link parameters -f__mhz = 1500; % MHz -h_tx__meter = 10; % meters, AGL -h_rx__meter = 5; % meters, AGL -N_0 = 301; % N-Units -epsilon = 15; % average ground -sigma = 0.005; % average ground -d__km = 100; % km -delta_h__meter = 40; % meter -tx_site_criteria = ITMSitingCriteria.Careful; -rx_site_criteria = ITMSitingCriteria.Careful; -climate = ITMClimate.ContinentalTemperate; -pol = ITMPolarization.Horizontal; - -% define variability parameters -mdvar = 13; -time = 50; % median -location = 50; % median -situation = 50; % median - -% call ITM -[rtn, A__db, warnings, ivals] = ITM.ITM_AREA_TLS(h_tx__meter, h_rx__meter, ... - tx_site_criteria, rx_site_criteria, d__km, delta_h__meter, climate, ... - N_0, f__mhz, pol, epsilon, sigma, mdvar, time, location, situation) -% rtn = 0 % no errors -% A__db = 191.0266 % basic transmission loss, in dB -% warnings = 0 % no warnings - -% can use the intermediate values object to access additional information -% from the ITM prediction -fprintf('The mode of propagation is %s\n', ivals.Mode) -fprintf('The effective height of the TX is %f meters.\n', ivals.h_e__meter(1)) -fprintf('The free space basic transmission loss is %f dB.\n', ivals.A_fs__db) -% The mode of propagation is Troposcatter -% The effective height of the TX is 13.032653 meters. -% The free space basic transmission loss is 135.971825 dB. -``` - -## Area Mode Basic Transmission Loss (CR) - -```matlab -% define link parameters -f__mhz = 5000; % MHz -h_tx__meter = 10; % meters, AGL -h_rx__meter = 5; % meters, AGL -N_0 = 301; % N-Units -epsilon = 15; % average ground -sigma = 0.005; % average ground -d__km = 100; % km -delta_h__meter = 40; % meter -tx_site_criteria = ITMSitingCriteria.Careful; -rx_site_criteria = ITMSitingCriteria.Careful; -climate = ITMClimate.ContinentalTemperate; -pol = ITMPolarization.Horizontal; - -% define variability parameters -mdvar = 13; -confidence = 50; % median -reliability = 50; % median - -% call ITM -[rtn, A__db, warnings, ivals] = ITM.ITM_AREA_CR(h_tx__meter, h_rx__meter, ... - tx_site_criteria, rx_site_criteria, d__km, delta_h__meter, climate, ... - N_0, f__mhz, pol, epsilon, sigma, mdvar, confidence, reliability) -% rtn = 0 % no errors -% A__db = 205.7474 % basic transmission loss, in dB -% warnings = 0 % no warnings - -% can use the intermediate values object to access additional information -% from the ITM prediction -fprintf('The mode of propagation is %s\n', ivals.Mode) -fprintf('The effective height of the TX is %f meters.\n', ivals.h_e__meter(1)) -fprintf('The free space basic transmission loss is %f dB.\n', ivals.A_fs__db) -% The mode of propagation is Troposcatter -% The effective height of the TX is 13.032653 meters. -% The free space basic transmission loss is 146.429400 dB. -``` \ No newline at end of file diff --git a/models/ITM/python.qmd b/models/ITM/python.qmd deleted file mode 100644 index cdeae5c..0000000 --- a/models/ITM/python.qmd +++ /dev/null @@ -1,202 +0,0 @@ ---- -title: "Irregular Terrain Model (ITM) – Python" ---- - -{{< include /includes/_under_construction.qmd >}} - -## Getting Started - -{{< include /includes/_package_install_not_ready.qmd >}} - - -### Dependencies - -The `itm` package requires `numpy`. - -### Installing Package - -Use the following command to install `itm` from the local pip repo: - -```cmd -pip install itm --no-index --find-links file://itsfs01/Tools/Python/pip -``` - -Importing `itm` is as simple as including the following in your `.py` file: - -```python -import itm -``` - -## Documentation - -All `itm` functions contain built-in docstring help. This means that if your python development editor supports it, it can provide you with assistance on information such as function description, parameter types and descriptions, and return details. - -This also means that `help()` is supported in the console to provide information. - -# Examples - -**Note:** These examples use an artificial terrain profile as a python list. The `itm` package supports terrain profiles to be passed as either python lists or numpy arrays. - -## Site Specific Basic Transmission Loss (TLS) - -```python -# define the terrain profile in PFL format -pfl = [5, 200, 5, 7, 2, 4, 7, 5] - -# define link parameters -f__mhz = 3500 # MHz -h_tx__meter = 10 # meters, AGL -h_rx__meter = 5 # meters, AGL -N_0 = 301 # N-Units -epsilon = 15 # average ground -sigma = 0.005 # average ground -climate = itm.Climate.ContinentalTemperate -pol = itm.Polarization.Horizontal - -# define variability parameters -mdvar = 13 -time = 50 # median -location = 50 # median -situation = 50 # median - -# call ITM -rtn, A__db, warnings, ivals = itm.ITM_P2P_TLS(h_tx__meter, h_rx__meter, - pfl, climate, N_0, f__mhz, pol, epsilon, sigma, mdvar, - time, location, situation) - -assert(rtn == 0) # no errors -assert(A__db == 105.85899333756423) # basic transmission loss, in dB -assert(warnings == 0) # no warnings - -# can use the intermediate values object to access additional information -# from the ITM prediction -print(f"The mode of propagation is {ivals.mode.name}") -print(f"The effective height of the TX is {ivals.h_e__meter[0]} meters.") -print(f"The free space basic transmission loss is {ivals.A_fs__db} dB.") -# The mode of propagation is LineOfSight -# The effective height of the TX is 10.222222222222221 meters. -# The free space basic transmission loss is 103.33136088700552 dB. -``` - -## Site Specific Basic Transmission Loss (CR) - -```python -# define the terrain profile in PFL format -pfl = [5, 200, 5, 7, 2, 4, 7, 5] - -# define link parameters -f__mhz = 1500 # MHz -h_tx__meter = 10 # meters, AGL -h_rx__meter = 5 # meters, AGL -N_0 = 301 # N-Units -epsilon = 15 # average ground -sigma = 0.005 # average ground -climate = itm.Climate.ContinentalTemperate -pol = itm.Polarization.Horizontal - -# define variability parameters -mdvar = 13 -confidence = 50 # median -reliability = 50 # median - -# call ITM -rtn, A__db, warnings, ivals = itm.ITM_P2P_CR(h_tx__meter, h_rx__meter, - pfl, climate, N_0, f__mhz, pol, epsilon, sigma, mdvar, confidence, - reliability) - -assert(rtn == 0) # no errors -assert(A__db == 99.97444366973738) # basic transmission loss, in dB -assert(warnings == 0) # no warnings - -# can use the intermediate values object to access additional information -# from the ITM prediction -print(f"The mode of propagation is {ivals.mode.name}") -print(f"The effective height of the TX is {ivals.h_e__meter[0]} meters.") -print(f"The free space basic transmission loss is {ivals.A_fs__db} dB.") -# The mode of propagation is LineOfSight -# The effective height of the TX is 10.222222222222221 meters. -# The free space basic transmission loss is 95.97182518111363 dB. -``` - -## Area Mode Basic Transmission Loss (TLS) - -```python -# define link parameters -f__mhz = 1500 # MHz -h_tx__meter = 10 # meters, AGL -h_rx__meter = 5 # meters, AGL -N_0 = 301 # N-Units -epsilon = 15 # average ground -sigma = 0.005 # average ground -d__km = 100 # km -delta_h__meter = 40 # meter -tx_site_criteria = itm.SitingCriteria.Careful -rx_site_criteria = itm.SitingCriteria.Careful -climate = itm.Climate.ContinentalTemperate -pol = itm.Polarization.Horizontal - -# define variability parameters -mdvar = 13 -time = 50 # median -location = 50 # median -situation = 50 # median - -# call ITM -rtn, A__db, warnings, ivals = itm.ITM_AREA_TLS(h_tx__meter, h_rx__meter, - tx_site_criteria, rx_site_criteria, d__km, delta_h__meter, climate, - N_0, f__mhz, pol, epsilon, sigma, mdvar, time, location, situation) - -assert(rtn == 0) # no errors -assert(A__db == 191.02659749297175) # basic transmission loss, in dB -assert(warnings == 0) # no warnings - -# can use the intermediate values object to access additional information -# from the ITM prediction -print(f"The mode of propagation is {ivals.mode.name}") -print(f"The effective height of the TX is {ivals.h_e__meter[0]} meters.") -print(f"The free space basic transmission loss is {ivals.A_fs__db} dB.") -# The mode of propagation is Troposcatter -# The effective height of the TX is 13.032653298563167 meters. -# The free space basic transmission loss is 135.97182518111362 dB. -``` - -## Area Mode Basic Transmission Loss (CR) - -```python -# define link parameters -f__mhz = 5000 # MHz -h_tx__meter = 10 # meters, AGL -h_rx__meter = 5 # meters, AGL -N_0 = 301 # N-Units -epsilon = 15 # average ground -sigma = 0.005 # average ground -d__km = 100 # km -delta_h__meter = 40 # meter -tx_site_criteria = itm.SitingCriteria.Careful -rx_site_criteria = itm.SitingCriteria.Careful -climate = itm.Climate.ContinentalTemperate -pol = itm.Polarization.Horizontal - -# define variability parameters -mdvar = 13 -confidence = 50 # median -reliability = 50 # median - -# call ITM -rtn, A__db, warnings, ivals = itm.ITM_AREA_CR(h_tx__meter, h_rx__meter, - tx_site_criteria, rx_site_criteria, d__km, delta_h__meter, climate, - N_0, f__mhz, pol, epsilon, sigma, mdvar, confidence, reliability) - -assert(rtn == 0) # no errors -assert(A__db == 205.7473567880463) # basic transmission loss, in dB -assert(warnings == 0) # no warnings - -# can use the intermediate values object to access additional information -# from the ITM prediction -print(f"The mode of propagation is {ivals.mode.name}") -print(f"The effective height of the TX is {ivals.h_e__meter[0]} meters.") -print(f"The free space basic transmission loss is {ivals.A_fs__db} dB.") -# The mode of propagation is Troposcatter -# The effective height of the TX is 13.032653298563167 meters. -# The free space basic transmission loss is 146.42940008672036 dB. -``` \ No newline at end of file diff --git a/models/LFMF/_metadata.yml b/models/LFMF/_metadata.yml new file mode 100644 index 0000000..0153fe3 --- /dev/null +++ b/models/LFMF/_metadata.yml @@ -0,0 +1,15 @@ +format: + html: + code-links: + - text: NTIA/LFMF + icon: github + href: https://github.com/NTIA/LFMF + - text: NTIA/LFMF-dotnet + icon: github + href: https://github.com/NTIA/LFMF-dotnet + - text: NTIA/LFMF-matlab + icon: github + href: https://github.com/NTIA/LFMF-matlab + - text: NTIA/LFMF-python + icon: github + href: https://github.com/NTIA/LFMF-python \ No newline at end of file diff --git a/models/LFMF/cpp.qmd b/models/LFMF/cpp.qmd new file mode 100644 index 0000000..a473b84 --- /dev/null +++ b/models/LFMF/cpp.qmd @@ -0,0 +1,68 @@ +--- +title: "Low Frequency / Medium Frequency Propagation Model – C++" +date: 2024-12-02 +date-modified: 2025-01-24 +--- + +This page details the installation and usage of the C++ version of the PropLib implementation of the Low Frequency / Medium Frequency (LF/MF) propagation model. + +{{< 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 shared library (`.dll` on Windows, `.dylib` on macOS, or `.so` on Linux) and the header file. These are distributed for each supported platform as part of the [GitHub Releases](https://github.com/NTIA/LFMF/releases/) starting with v1.1. Prior to v1.1, support was only provided for Windows platforms. + +To use the shared 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 "LFMF.h" + +using namespace ITS::Propagation::LFMF; // Optional: makes later code more concise +``` + +This library has no external C++ dependencies. + +{{< include /includes/cpp/_documentation.qmd >}} + +[Docs](https://ntia.github.io/lfmf){.btn .btn-secondary .btn role="button"} + +## Examples + +The following code example shows how the LF/MF model can be called in a C++ program. + +### Calling the Model + +```cpp +#include "LFMF.h" +using namespace ITS::Propagation; + +int main() { + // Define inputs + double h_tx__meter = 0.0; // Height of the transmitter + double h_rx__meter = 0.0; // Height of the receiver + double f__mhz = 0.01; // Frequency + double P_tx__watt = 1000.0; // Transmitter power + double N_s = 301.0; // Surface refractivity + double d__km = 1000.0; // Path distance + double epsilon = 15.0; // Relative permittivity + double sigma = 0.005; // Conductivity + LFMF::Polarization pol = LFMF::Polarization::HORIZONTAL; // Polarization + + // Create struct to store outputs + LFMF::Result result; + LFMF::ReturnCode rtn; // Return code + + // Call the model + rtn = LFMF::LFMF_CPP(h_tx__meter, h_rx__meter, f__mhz, P_tx__watt, N_s, d__km, epsilon, sigma, pol, &result); + + // rtn is 0 (SUCCESS) + // result.A_btl__db is 184.49 dB + // result.E_dBuVm is -82.50 dB(uV/m) + // result.P_rx__dbm is -114.93 dBm + // result.method is 1 (residue series) +} +``` diff --git a/models/LFMF/driver.qmd b/models/LFMF/driver.qmd new file mode 100644 index 0000000..02798b2 --- /dev/null +++ b/models/LFMF/driver.qmd @@ -0,0 +1,170 @@ +--- +title: "Low Frequency / Medium Frequency Propagation Model – Command-Line Driver" +date: 2025-01-10 +date-modified: 2025-01-10 +--- + +This page details the usage of the cross-platform command-line driver version of the Low Frequency / Medium Frequency (LF/MF) propagation model. + +{{< include /includes/driver/_intro_and_installation.qmd >}} + +{{< include /includes/driver/_general_usage.qmd >}} + +# Command-Line Arguments + +Executing the command-line driver requires specifying input arguments, defined in @tbl-lfmf-driver-input-args below. + + +| Flag | Type | Required | Description | +|----------|--------|----------|--------------------------------------------------------------| +| `-i` | string | true | File specifying model input parameters in `key,value` format | +| `-o` | string | true | Filename where output results should be written | +: Arguments for the LF/MF command-line driver {#tbl-lfmf-driver-input-args} + +Additional arguments are available to print help text and version information without running any model. +When using these options, none of the arguments from @tbl-lfmf-driver-input-args are required. +The additional arguments are defined in @tbl-lfmf-driver-additional-args + +| Flag | Description | +|------|--------------------------------------------------------| +| `-h` | Display help text | +| `-v` | Display version information for the library and driver | +: Additional arguments for the LF/MF command-line driver {#tbl-lfmf-driver-additional-args} + +# Examples + +The LF/MF model can be run by simply providing the input and output files on the command line. +For example: + +```cmd +# Windows (64-bit) +LFMFDriver-1.1.0-Windows-x64.exe -i input.txt -o output.txt + +# macOS +./LFMFDriver-1.1.0-Darwin-universal -i input.txt -o output.txt + +# Linux +./LFMFDriver-1.1.0-Linux-x86_64 -i input.txt -o output.txt +``` + +Three example sets of input/output file pairs are provided below. + +## Example 1 + +```{.default filename="Input File Contents"} +h_tx__meter,0 +h_rx__meter,0 +f__mhz,0.01 +P_tx__watt,1000 +N_s,301 +d__km,1000 +epsilon,15 +sigma,0.005 +pol,0 +``` + +```{.default filename="Output File Contents"} +Model LFMF +Library Version v1.1 +Driver Version v1.1.0 +Date Generated Mon Nov 18 13:56:29 2024 +Input Arguments -i i_lfmf_01.txt -o o_lfmf_01.txt + +Inputs: +h_tx__meter 0 [meter] +h_rx__meter 0 [meter] +f__mhz 0.01 [MHz] +p_tx__watt 1000 [Watts] +n_s 301 [N-Units] +d__km 1000 [km] +epsilon 15 +sigma 0.005 +pol 0 [0 = Horizontal, 1 = Vertical] + +Results: +Return Code 0 [LFMF v1.0 Status: Successful execution] +Basic transmission loss 184.49 [dB] +Electric field strength -82.50 [dB(uV/m)] +Received power -114.93 [dB] +Solution method 1 [0 = Flat earth with curve correction, 1 = Residue series] +``` + +## Example 2 + +```{.default filename="Input File Contents"} +h_tx__meter,5.5 +h_rx__meter,1.5 +f__mhz,10 +P_tx__watt,500 +N_s,315 +d__km,15 +epsilon,15 +sigma,0.005 +pol,0 +``` + +```{.default filename="Output File Contents"} +Model LFMF +Library Version v1.1 +Driver Version v1.1.0 +Date Generated Mon Nov 18 13:56:51 2024 +Input Arguments -i i_lfmf_02.txt -o o_lfmf_02.txt + +Inputs: +h_tx__meter 5.5 [meter] +h_rx__meter 1.5 [meter] +f__mhz 10 [MHz] +p_tx__watt 500 [Watts] +n_s 315 [N-Units] +d__km 15 [km] +epsilon 15 +sigma 0.005 +pol 0 [0 = Horizontal, 1 = Vertical] + +Results: +Return Code 0 [LFMF v1.1 Status: Successful execution] +Basic transmission loss 151.33 [dB] +Electric field strength 7.65 [dB(uV/m)] +Received power -84.78 [dB] +Solution method 0 [0 = Flat earth with curve correction, 1 = Residue series] +``` + +## Example 3 + +```{.default filename="Input File Contents"} +h_tx__meter,1 +h_rx__meter,1 +f__mhz,0.45 +P_tx__watt,1000 +N_s,315 +d__km,3000 +epsilon,15 +sigma,0.005 +pol,1 +``` + +```{.default filename="Output File Contents"} +Model LFMF +Library Version v1.1 +Driver Version v1.1.0 +Date Generated Mon Nov 18 13:56:57 2024 +Input Arguments -i i_lfmf_03.txt -o o_lfmf_03.txt + +Inputs: +h_tx__meter 1 [meter] +h_rx__meter 1 [meter] +f__mhz 0.45 [MHz] +p_tx__watt 1000 [Watts] +n_s 315 [N-Units] +d__km 3000 [km] +epsilon 15 +sigma 0.005 +pol 1 [0 = Horizontal, 1 = Vertical] + +Results: +Return Code 0 [LFMF v1.1 Status: Successful execution] +Basic transmission loss 264.33 [dB] +Electric field strength -129.28 [dB(uV/m)] +Received power -194.77 [dB] +Solution method 1 [0 = Flat earth with curve correction, 1 = Residue series] +``` diff --git a/models/LFMF/index.qmd b/models/LFMF/index.qmd new file mode 100644 index 0000000..2bcf526 --- /dev/null +++ b/models/LFMF/index.qmd @@ -0,0 +1,79 @@ +--- +title: "Low Frequency / Medium Frequency Propagation Model" +date: 2024-12-02 +date-modified: 2025-01-25 +--- + +The Low Frequency / Medium Frequency (LF/MF) propagation model predicts basic transmission loss in the frequency range 0.01 - 30 MHz for propagation paths over a smooth Earth and antenna heights less than 50 meters. [@ntia-tr-99-368] + +{{< include /includes/_getting_started.qmd >}} + +## Model Background + +This model fundamentally predicts basic transmission loss using @eq-lfmf-btl. + +$$ +\begin{align} +\text{BTL (dB)} =&\ 10\log(P_{tx} \cdot G_{tx}) + 10\log(\eta_0) + 20\log(f) \\ +&-20\log(E_{gw}) - 20\log(c) +\end{align} +$$ {#eq-lfmf-btl} + +In @eq-lfmf-btl, $P_{tx}$ and $f$ are model inputs, where $P_{tx}$ is in watts and $f$ has been converted to hertz. The constants $\eta_0$ and $c$ are the impedance of free space and the speed of light in vacuum, respectively. $G_{tx}$ is the linear conversion of the transmitter antenna gain, which is set to 4.77 dBi. This factor is included to remove the impacts of an equivalent scaling factor which is used when calculating the ground wave. Finally, $E_{gw}$ is the internally-computed ground wave field strength, in volts per meter. + +This smooth earth model implements two different methods to compute the ground wave, depending on the path distance and frequency. A cutoff distance for the use of the flat earth approximation is determined using the method described in the ITU-R Ground Wave Propagation handbook [@itu-r-sg3-ground-wave-handbook, pp. 7]. Up to this distance, a flat-Earth approximation with curvature correction is used [@ntia-tr-99-368, pp. 13; @wait-radiation-from-vertical-antenna]. Beyond this distance, the ground wave strength is calculated by evaluating the full-wave theory integral using the residue series. + +The model additionally outputs the predicted electric field strength of the ground wave, the received power, and the method used to calculate the ground wave. + +## Functions + +### Low Frequency / Mid Frequency Propagation Model + +This model's functionality is exposed through a single function. The inputs for this function are shown below in @tbl-lfmf-inputs. +The model outputs are provided in @tbl-lfmf-outputs. + +| Variable | Type | Units | Limits | Description | +|---------------|--------|--------|-------------------------|------------------------------| +| `h_tx__meter` | double | meter | $0 \leq h_{tx} \leq 50$ | Height of the transmitter | +| `h_rx__meter` | double | meter | $0 \leq h_{rx} \leq 50$ | Height of the receiver | +| `f__mhz` | double | MHz | $0.01 \leq f \leq 30$ | Frequency | +| `P_tx__watt` | double | watt | $0 < P_{tx}$ | Transmitter power | +| `N_s` | double | N-Unit | $250 \leq N_s \leq 400$ | Surface refractivity | +| `d__km` | double | kilometer | $0 < d$ | Path distance | +| `epsilon` | double | none | $1 \leq \epsilon$ | Relative permittivity | +| `sigma` | double | siemens per meter | $0 < \sigma$ | Conductivity | +| `pol` | `Polarization` enum | N/A | enum | See @tbl-lfmf-polarizations | +: Inputs for the LF/MF model {#tbl-lfmf-inputs} + +The `pol` input must be one of the two valid supported polarization types, as defined in @tbl-lfmf-polarizations. + +| Enum Value | Polarization | +|------------|--------------| +| 0 | Horizontal | +| 1 | Vertical | +: Allowed polarization values for the LF/MF model {#tbl-lfmf-polarizations} + +The LF/MF model produces an output which contains four values. These results indicate the predicted basic transmission loss, the ground wave electric field strength, the received power and the solution method used to calculate the ground wave. + +| Variable | Type | Units | Description | +|-------------|---------|-------------------|-------------------------| +| `A_btl__db` | double | dB | Basic transmission loss | +| `E_dBuVm` | double | dB(μV/m) | Electric field strength | +| `P_rx__dbm` | double | dBm | Received power | +| `method` | `SolutionMethod` enum | N/A | Solution method; see @tbl-lfmf-solution-methods | +: Outputs of the LF/MF model {#tbl-lfmf-outputs} + +The `method` output indicates the solution method used internally by the model while generating the other outputs. The possible returned values are provided in @tbl-lfmf-solution-methods. + +| Enum Value | Solution Method | +|------------|----------------------------------| +| 0 | Flat earth with curve correction | +| 1 | Residue series | +: Possible solution methods used by the LF/MF model {#tbl-lfmf-solution-methods} + +{{< include /includes/_code_examples.qmd >}} + +[C++](cpp.qmd#calling-the-model){.btn .btn-secondary .btn role="button"} +[.NET](dotnet.qmd#calling-the-model){.btn .btn-secondary .btn role="button"} +[MATLAB](matlab.qmd#calling-the-model){.btn .btn-secondary .btn role="button"} +[Python](python.qmd#calling-the-model){.btn .btn-secondary .btn role="button"} \ No newline at end of file diff --git a/models/LFMF/matlab.qmd b/models/LFMF/matlab.qmd new file mode 100644 index 0000000..5b89b1a --- /dev/null +++ b/models/LFMF/matlab.qmd @@ -0,0 +1,62 @@ +--- +title: "Low Frequency / Medium Frequency Propagation Model – MATLAB" +date: 2025-01-24 +date-modified: 2025-01-25 +--- + +This page details the installation and usage of the MATLAB® version of the PropLib implementation of the Low Frequency / Medium Frequency (LF/MF) propagation model. + +{{< include /includes/_under_construction.qmd >}} + +{{< include /includes/_link_to_model_home.qmd >}} + +