Skip to content

NTIA/itm

Repository files navigation

ITS Irregular Terrain Model (ITM)

This code repository contains the ITS Irregular Terrain Model (ITM). ITM predicts terrestrial radiowave propagation for frequencies between 20 MHz and 20 GHz based on electromagnetic theory and empirical models developed by Anita Longley and Phil Rice. Propagation mechanisms considered include free space loss, diffraction, and troposcatter. Specifically, ITM predicts attenuation as a function of distance (greater than 1 km), terminal heights, meteorological conditions, terrain effects, and the variability of the signal in time and in space.

Note: Version 1.3 of this code base is functionally identical to version 1.2.2 of the FORTRAN source, which has been archived here. ITS plans to apply all future ITM updates to this C++ code base.

Quick Start

Users of ITM have two options to immediately begin using ITM:

  1. The ITM software is made available to the user as a precompiled DLL in the Release page. A user can add this DLL to their own software project as a dependency and call ITM through its function definitions. Additionally, a C#/.NET software wrapper is provided. Distribution and updates of this wrapper code are provided through the published NuGet package.

  2. A supporting command-line driver is also included in this repository, with its own corresponding readme. This tool allows a user to call ITM without any programming required through the use of ASCII input/output files.

A select set of example inputs and outputs are provided for testing purposes. This is not a comprehensive validation test set. For ITM in Point-to-Point Prediction Mode, p2p.csv defines the set of inputs and outputs with pfls.csv containing the corresponding set of terrain profiles. For Area Prediction Mode, inputs and outputs are defined in area.csv.

Inputs

ITM can be called in either Area Prediction Mode or Point-to-Point Prediction Mode. Additionally, variabilities can be defined by either time/location/situation or confidence/reliability. The below inputs are organized accordingly.

Common Inputs

Variable Type Units Limits Description
h_tx__meter double meter 0.5 <= h_tx__meter <= 3000 Structural height of the TX
h_rx__meter double meter 0.5 <= h_rx__meter <= 3000 Structural height of the RX
climate int enum Radio climate of the path
  • 1 = Equatorial
  • 2 = Continental Subtropical
  • 3 = Maritime Subtropical
  • 4 = Desert
  • 5 = Continental Temperate
  • 6 = Maritime Temperate Over Land
  • 7 = Maritime Temperate Over Sea
N_0 double N-Units 250 <= N_0 <= 400 Minimum monthly mean surface refractivity reduced to sea level
f__mhz double MHz 20 <= f__mhz <= 20000 Frequency
pol int enum Polarization
  • 0 = Horizontal
  • 1 = Vertical
epsilon double 1 < epsilon Relative permittivity
sigma double S/m 0 < sigma Conductivity
mdvar int enum Mode of variability
  • 0 = Single Message Mode
  • 1 = Accidental Mode
  • 2 = Mobile Mode
  • 3 = Broadcast Mode
Additionally, +10 if location variability is to be eliminated, and +20 if direct situation variability is to be eliminated

Point-to-Point Mode Specific Inputs

Variable Type Units Limits Description
pfl double[] Terrain profile data in PFL format, from TX to RX
  • pfl[0] : Number of elevation points - 1
  • pfl[1] : Resolution, in meters
  • pfl[i] : Elevation above sea level, in meters

Area Mode Inputs

Variable Type Units Limits Description
d__km double km 0 < d__km Path distance
delta_h__meter double meter 0 <= delta_h__meter Terrain irregularity parameter
tx_siting_criteria int enum Siting criteria of TX
  • 0 = Random
  • 1 = Careful
  • 2 = Very Careful
rx_siting_criteria int enum Siting criteria of RX
  • 0 = Random
  • 1 = Careful
  • 2 = Very Careful

Variability Inputs

A user either supplies values for time/location/situation or confidence/reliability.

Variable Type Units Limits Description
time double 0 < time < 100 Time variability
location double 0 < location < 100 Location variability
situation double 0 < situation < 100 Situation variability
confidence double 0 < confidence < 100 Confidence variability
reliability double 0 < reliability < 100 Reliability variability

Outputs

Variable Type Units Description
A__db double dB Basic transmission loss
warnings int Warning flags

Intermediate Values

Internal intermediate values can be extracted from ITM via functions that are suffixed with _Ex. These functions will populate the IntermediateValues data structure with intermediate values from the ITM calculations.

Variable Type Units Description
theta_hzn double[] radians Terminal horizon angles
d_hzn__meter double[] meter Terminal horizon distances
h_e__meter double[] meter Effective terminal heights
N_s double N-Units Surface refractivity
delta_h__meter double meter Terrain irregularity parameter
A_ref__db double dB Reference attenuation
A_fs__db double dB Free space basic transmission loss
d__km double km Path distance
mode int Mode of propagation
  • 1 = Line of Sight
  • 2 = Diffraction
  • 3 = Troposcatter

Error Codes and Warning Flags

ITM supports a defined list of error codes and warning flags. A complete list can be found here.

Notes on Code Style

  • In general, variables follow the naming convention in which a single underscore denotes a subscript (pseudo-LaTeX format), and where a double underscore is followed by the units, i.e. h_tx__meter.
  • Variables are named to match their corresponding mathematical variables in the underlying references.
  • Wherever possible, equation numbers and source documentation are provided.

Configure and Build

C++ Software

The software is designed to be built into a DLL (or corresponding library for non-Windows systems). The source code can be built for any OS that supports the standard C++ libraries. A Visual Studio 2019 project file is provided for Windows users to support the build process and configuration.

C#/.NET Wrapper Software

The .NET support of ITM consists of a simple pass-through wrapper around the native DLL. It is compiled to target .NET Framework 4.7.2.

References

Contact

For technical questions about ITM, contact Paul McKenna, [email protected].