Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
32 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added images/dotnet/dotnet-add-nuget.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion includes/_code_examples.qmd
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
#### Examples
**Examples**

Language-specific code examples showing the use of this function are available by following these links:
6 changes: 3 additions & 3 deletions includes/driver/_general_usage.qmd
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# General Usage
## General Usage

## Input Files
### 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
### 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.
2 changes: 1 addition & 1 deletion includes/driver/_intro_and_installation.qmd
Original file line number Diff line number Diff line change
Expand Up @@ -5,5 +5,5 @@ use the command-line driver.

{{< include /includes/_link_to_model_home.qmd >}}

# Installation
## Installation

2 changes: 1 addition & 1 deletion includes/matlab/_getting_started.qmd
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
There are two easy ways to install the toolbox: [from a browser](#installing-from-a-browser) or [from within MATLAB](#installing-from-within-matlab).
There are two easy ways to install the toolbox: [from a browser](#installation-from-a-browser) or [from within MATLAB](#installation-from-within-matlab).

### Installation from a Browser

Expand Down
22 changes: 14 additions & 8 deletions index.qmd
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
---
title: "ITS Propagation Library Wiki"
date: 2024-06-11
date-modified: 2024-12-02
date-modified: 2025-06-12
---

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.
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&reg;, 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.

## Packages

Expand Down Expand Up @@ -53,10 +53,16 @@ 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/) | 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.676** | [Repo](https://github.com/NTIA/P676) | [Docs](models/P676/) | Prediction methods for the specific attenuation, terrestrial and |
| | | | slant path gaseous attenuation due to oxygen and water vapour |

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Vapour" is British spelling where typically write as "Vapor". However, this is considered good, where simply looked weird as haven't seen that spelling.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, this follows the P676 and P835 paper. Was thinking change to "Vapor", but everywhere in code is using "Vapour".

+------------+---------------------------------------+-----------------------+------------------------------------------------------------------+
| **P.835** | [Repo](https://github.com/NTIA/P835) | [Docs](models/P835/) | Expressions and data for reference standard atmospheres required |
| | | | for the calculation of gaseous attenuation on Earth-space paths |
+------------+---------------------------------------+-----------------------+------------------------------------------------------------------+
| **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]"}
34 changes: 16 additions & 18 deletions models/LFMF/cpp.qmd
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: "Low Frequency / Medium Frequency Propagation Model – C++"
date: 2024-12-02
date-modified: 2025-01-24
date-modified: 2025-06-12
---

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.
Expand All @@ -10,8 +10,6 @@ This page details the installation and usage of the C++ version of the PropLib i

## 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.
Expand All @@ -34,35 +32,35 @@ This library has no external C++ dependencies.

The following code example shows how the LF/MF model can be called in a C++ program.

### Calling the Model
### Calling the LFMF Model

```cpp
#include "LFMF.h"
using namespace ITS::Propagation;
using namespace ITS::Propagation::LFMF;

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
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
Polarization pol = Polarization::HORIZONTAL; // Polarization

// Create struct to store outputs
LFMF::Result result;
LFMF::ReturnCode rtn; // Return code
Result result; // LFMF result structure
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 = 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)
// result.method is 1 (RESIDUE_SERIES)
}
```
79 changes: 79 additions & 0 deletions models/LFMF/dotnet.qmd
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
---
title: "Low Frequency / Medium Frequency Propagation Model – .NET"
date: 2025-01-24
date-modified: 2025-06-12
---

This page details the installation and usage of the .NET version of the PropLib implementation of the Low Frequency / Medium Frequency (LF/MF) propagation model.

{{< include /includes/_link_to_model_home.qmd >}}

## Installation

This .NET package is distributed on
[NuGet](https://www.nuget.org/packages/ITS.Propagation.LFMF).

There are two easy ways to install the NuGet package: [dotnet CLI](#installation-with-dotnet-cli) or [Visual Studio](#installation-with-visual-studio).

### Installation with dotnet CLI

1. Run the following command to install the package.

```default
dotnet add package ITS.Propagation.LFMF
```

1. After the command completes, open the project csproj file to see the added NuGet package reference:

```default
<ItemGroup>
<PackageReference Include="ITS.Propagation.LFMF" Version="1.1.0" />
</ItemGroup>
```

### Installation with Visual Studio

1. Open your project in **Visual Studio** and select **Project > Manage NuGet Packages**.

1. In the **NuGet Package Manager** page, choose **nuget.org** as the **Package source**.

1. From the **Browse** tab, search for **ITS.Propagation.LFMF**, select ITS.Propagation.LFMF in the list, and then select Install as shown in @fig-dotnet-add-nuget.

![](/images/dotnet/dotnet-add-nuget.png){#fig-dotnet-add-nuget fig-alt="A screenshot showing the 'NuGet Package Manager'" width=600 fig-align="left"}

1. If you're prompted to verify the installation, select OK.

## Examples

The following code examples show how the LF/MF model can be called from .NET project.

### Calling the LFMF Model

```c#
using ITS.Propagation;

// define inputs
double h_tx__meter = 0; // Height of the transmitter
double h_rx__meter = 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
int pol = 0; // Polarization (enum value)
// Alternately, `pol` can be specified using the enum:
// LFMF.Polarization pol = LFMF.Polarization.Horizontal;

// Call the LF/MF model
int rtn = LFMF.LFMFModel(h_tx__meter, h_rx__meter, f__mhz, P_tx__watt, N_s,
d__km, epsilon, sigma, pol, out LFMF.Result result);

// rtn is 0 (SUCCESS)
// The result is a data structure containing four elements:
// result.A_btl__db is approximately 184.49
// result.E__dBuVm is approximately -82.50
// result.P_rx__dbm is approximately -114.93
// result.method is ITS.Propagation.LFMF.SolutionMethod.ResidueSeries
// (SolutionMethod enum value 1)
```
30 changes: 18 additions & 12 deletions models/LFMF/driver.qmd
Original file line number Diff line number Diff line change
@@ -1,16 +1,22 @@
---
title: "Low Frequency / Medium Frequency Propagation Model – Command-Line Driver"
date: 2025-01-10
date-modified: 2025-01-10
date-modified: 2025-06-12
---

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 >}}

To use the command-line driver program, you'll need to download the driver program
(`LFMFDriver-1.1.0-Windows-x64.exe` or `LFMFDriver-1.1.0-Windows-x86.exe` on Windows, `LFMFDriver-1.1.0-Darwin-universal` on macOS, or `LFMFDriver-1.1.0-Linux-x86_64` on Linux)
and the shared library (`.dll` on Windows, `.dylib` on macOS, or `.so` on Linux).
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.

{{< include /includes/driver/_general_usage.qmd >}}

# Command-Line Arguments
## Command-Line Arguments

Executing the command-line driver requires specifying input arguments, defined in @tbl-lfmf-driver-input-args below.

Expand All @@ -31,7 +37,7 @@ The additional arguments are defined in @tbl-lfmf-driver-additional-args
| `-v` | Display version information for the library and driver |
: Additional arguments for the LF/MF command-line driver {#tbl-lfmf-driver-additional-args}

# Examples
## Examples

The LF/MF model can be run by simply providing the input and output files on the command line.
For example:
Expand All @@ -49,7 +55,7 @@ LFMFDriver-1.1.0-Windows-x64.exe -i input.txt -o output.txt

Three example sets of input/output file pairs are provided below.

## Example 1
### Example 1

```{.default filename="Input File Contents"}
h_tx__meter,0
Expand All @@ -67,29 +73,29 @@ pol,0
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
Date Generated Tue Jul 01 13:38:18 2025
Input Arguments -i input.txt -o results.txt

Inputs:
h_tx__meter 0 [meter]
h_rx__meter 0 [meter]
h_tx__meter 0 [meters]

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Plural and lowercase is better here where I think, stating units is usually arbitrary. But this format is correct:

https://en.wikipedia.org/wiki/SI_derived_unit#Special_names

h_rx__meter 0 [meters]
f__mhz 0.01 [MHz]
p_tx__watt 1000 [Watts]
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]
Return Code 0 [LFMF v1.1 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
### Example 2

```{.default filename="Input File Contents"}
h_tx__meter,5.5
Expand Down Expand Up @@ -129,7 +135,7 @@ Received power -84.78 [dB]
Solution method 0 [0 = Flat earth with curve correction, 1 = Residue series]
```

## Example 3
### Example 3

```{.default filename="Input File Contents"}
h_tx__meter,1
Expand Down
12 changes: 6 additions & 6 deletions models/LFMF/index.qmd
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: "Low Frequency / Medium Frequency Propagation Model"
date: 2024-12-02
date-modified: 2025-01-25
date-modified: 2025-06-12
---

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]
Expand All @@ -27,7 +27,7 @@ The model additionally outputs the predicted electric field strength of the grou

## Functions

### Low Frequency / Mid Frequency Propagation Model
### Low Frequency / Medium Frequency (LF/MF) 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.
Expand Down Expand Up @@ -73,7 +73,7 @@ The `method` output indicates the solution method used internally by the model w

{{< 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"}
[C++](cpp.qmd#calling-the-lfmf-model){.btn .btn-secondary .btn role="button"}
[.NET](dotnet.qmd#calling-the-lfmf-model){.btn .btn-secondary .btn role="button"}
[MATLAB](matlab.qmd#calling-the-lfmf-model){.btn .btn-secondary .btn role="button"}
[Python](python.qmd#calling-the-lfmf-model){.btn .btn-secondary .btn role="button"}
20 changes: 7 additions & 13 deletions models/LFMF/matlab.qmd
Original file line number Diff line number Diff line change
@@ -1,34 +1,30 @@
---
title: "Low Frequency / Medium Frequency Propagation Model – MATLAB"
date: 2025-01-24
date-modified: 2025-01-25
date-modified: 2025-06-12
---

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 >}}
This page details the installation and usage of the MATLAB&reg; version of the PropLib implementation of the Low Frequency / Medium Frequency (LF/MF) propagation model.

{{< include /includes/_link_to_model_home.qmd >}}

<!--

## Getting Started

This MATLAB® Toolbox is distributed on [MathWorks® File Exchange](#TODO).
This MATLAB&reg; Toolbox is distributed on [MathWorks&reg; File Exchange](#TODO).

{{< include /includes/matlab/_getting_started.qmd >}}

{{< include /includes/matlab/_documentation.qmd >}}

```matlab
help ITS.Propagation.LFMF.LFMF
help ITS.Propagation.LFMF.LFMFModel

% Prints detailed usage information!
```

{{< include /includes/matlab/_examples.qmd >}}

### Calling the Model
### Calling the LFMF Model

This example shows multiple equivalent ways to specify the polarization input.

Expand All @@ -55,8 +51,6 @@ pol = Polarization.HORIZONTAL; % An equivalent way to specify the polarization

% A_btl__db is approximately 184.49
% E__dBuVm is approximately -82.50
% P_rx__dbm is approximately -115.93
% method is 1 (SolutionMethod enum value)
% P_rx__dbm is approximately -114.93
% method is RESIDUE_SERIES (SolutionMethod enum value 1)
```

->
Loading