Merge pull request #1 from NTIA/staging

Public Release of C++ Repo

.gitattributes

@@ -0,0 +1,22 @@
+# Auto detect text files and perform LF normalization
+* text=auto
+
+# Custom for Visual Studio
+*.cs     diff=csharp
+*.sln    merge=union
+*.csproj merge=union
+*.vbproj merge=union
+*.fsproj merge=union
+*.dbproj merge=union
+
+# Standard to msysgit
+*.doc	 diff=astextplain
+*.DOC	 diff=astextplain
+*.docx diff=astextplain
+*.DOCX diff=astextplain
+*.dot  diff=astextplain
+*.DOT  diff=astextplain
+*.pdf  diff=astextplain
+*.PDF	 diff=astextplain
+*.rtf	 diff=astextplain
+*.RTF	 diff=astextplain

.gitignore

@@ -0,0 +1,72 @@
+############
+## Windows
+############
+
+# Windows image file caches
+Thumbs.db
+*.o
+
+# Folder config file
+Desktop.ini
+
+#################
+## Visual Studio
+#################
+
+## Ignore Visual Studio temporary files, build results, and
+## files generated by popular Visual Studio add-ons.
+# User-specific files
+**/Debug
+**/Release
+**/packages
+**/.vs
+*.tlog
+*.obj
+*.log
+*.lastbuildstate
+*.manifest
+*.cache
+*.users
+*.user
+*.res
+*.opendb
+*.db
+*.unsuccessfulbuild
+*.ipch
+*.pdb
+*.exp
+*.ilk
+*.idb
+*.opensdf
+*.sdf
+*.u2d
+*.suo
+*.tiff
+*.aps
+
+################
+# Linux and OSX
+###############
+\.DS*
+*.so
+*.d
+
+
+# Created by https://www.gitignore.io
+
+### Xcode ###
+build/
+*.pbxuser
+!default.pbxuser
+*.mode1v3
+!default.mode1v3
+*.mode2v3
+!default.mode2v3
+*.perspectivev3
+!default.perspectivev3
+xcuserdata
+*.xccheckout
+*.moved-aside
+DerivedData
+*.xcuserstate
+

ERRORS_AND_WARNINGS.md

@@ -0,0 +1,56 @@
+# Return Codes and Warning Flags #
+
+## Return Codes ##
+
+ITM supports the following list of return codes.
+
+| Value | Const Name                       | Description  |
+| ------|----------------------------------|--------------|
+|     0 | `SUCCESS`                        | Successful execution |
+|     1 | `SUCCESS_WITH_WARNINGS`          | Successful execution, but warning flags set |
+|  1000 | `ERROR__TX_TERMINAL_HEIGHT`      | TX terminal height is out of range |
+|  1001 | `ERROR__RX_TERMINAL_HEIGHT`      | RX terminal height is out of range |
+|  1002 | `ERROR__INVALID_RADIO_CLIMATE`   | Invalid value for radio climate |
+|  1003 | `ERROR__INVALID_TIME`            | Time percentage is out of range |
+|  1004 | `ERROR__INVALID_LOCATION`        | Location percentage is out of range |
+|  1005 | `ERROR__INVALID_SITUATION`       | Situation percentage is out of range |
+|  1006 | `ERROR__INVALID_CONFIDENCE`      | Confidence percentage is out of range |
+|  1007 | `ERROR__INVALID_RELIABILITY`     | Reliability percentage is out of range |
+|  1008 | `ERROR__REFRACTIVITY`            | Refractivity is out of range |
+|  1009 | `ERROR__FREQUENCY`               | Frequency is out of range |
+|  1010 | `ERROR__POLARIZATION`            | Invalid value for polarization |
+|  1011 | `ERROR__EPSILON`                 | Epsilon is out of range |
+|  1012 | `ERROR__SIGMA`                   | Sigma is out of range |
+|  1013 | `ERROR__GROUND_IMPEDANCE`        | The imaginary portion of the complex impedance is larger than the real portion |
+|  1014 | `ERROR__MDVAR`                   | Invalid value for mode of variability |
+|  1015 | `ERROR__MDVAR_BROADCAST_MODE`    | Broadcast variability modes are not supported in confidence/reliability functions |
+|  1016 | `ERROR__EFFECTIVE_EARTH`         | Internally computed effective earth radius is invalid |
+|  1017 | `ERROR__PATH_DISTANCE`           | Path distance is out of range |
+|  1018 | `ERROR__DELTA_H`                 | Delta H (terrain irregularity parameter) is out of range |
+|  1019 | `ERROR__TX_SITING_CRITERIA`      | Invalid value for TX siting criteria |
+|  1020 | `ERROR__RX_SITING_CRITERIA`      | Invalid value for RX siting criteria |
+|  1021 | `ERROR__SURFACE_REFRACTIVITY_SMALL`    | Internally computed surface refractivity value is too small |
+|  1022 | `ERROR__SURFACE_REFRACTIVITY_LARGE`    | Internally computed surface refractivity value is too large |
+
+## Warning Flags ##
+
+In addition to return codes, ITM supports return warning flags to the caller.  Warning flags are bitwise set, allowing the ITM model to return multiple warnings for a single function call.  Warning flags only need to be parsed if a return code of `SUCCESS_WITH_WARNINGS` is returned by a function call.
+
+| Value  | Const Name                       | Description  |
+| -------|----------------------------------|--------------|
+| 0x0000 | `NO_WARNINGS`                    | No warning flags |
+| 0x0001 | `WARN__TX_TERMINAL_HEIGHT`       | TX terminal height is near its limits |
+| 0x0002 | `WARN__RX_TERMINAL_HEIGHT`       | RX terminal height is near its limits |
+| 0x0004 | `WARN__FREQUENCY`                | Frequency is near its limits |
+| 0x0008 | `WARN__PATH_DISTANCE_TOO_BIG_1`  | Path distance is near its upper limit |
+| 0x0010 | `WARN__PATH_DISTANCE_TOO_BIG_2`  | Path distance is large - care must be taken with result |
+| 0x0020 | `WARN__PATH_DISTANCE_TOO_SMALL_1` | Path distance is near its lower limit |
+| 0x0040 | `WARN__PATH_DISTANCE_TOO_SMALL_2` | Path distance is small - care must be taken with result
+| 0x0080 | `WARN__TX_HORIZON_ANGLE`         | TX horizon angle is large - small angle approximations could break down |
+| 0x0100 | `WARN__RX_HORIZON_ANGLE`         | RX horizon angle is large - small angle approximations could break down |
+| 0x0200 | `WARN__TX_HORIZON_DISTANCE_1`    | TX horizon distance is less than 1/10 of the smooth earth horizon distance |
+| 0x0400 | `WARN__RX_HORIZON_DISTANCE_1`    | RX horizon distance is less than 1/10 of the smooth earth horizon distance |
+| 0x0800 | `WARN__TX_HORIZON_DISTANCE_2`    | TX horizon distance is greater than 3 times the smooth earth horizon distance |
+| 0x1000 | `WARN__RX_HORIZON_DISTANCE_2`    | RX horizon distance is greater than 3 times the smooth earth horizon distance |
+| 0x2000 | `WARN__EXTREME_VARIABILITIES`    | One of the provided variabilities is located far in the tail of its distribution |
+| 0x4000 | `WARN__SURFACE_REFRACTIVITY`     | Internally computed surface refractivity value is small - care must be taken with result |

LICENSE.md

@@ -0,0 +1,14 @@
+SOFTWARE DISCLAIMER / RELEASE
+
+This software was developed by employees of the National Telecommunications and Information Administration (NTIA), an agency of the Federal Government and is provided to you as a public service.  Pursuant to Title 15 United States Code Section 105, works of NTIA employees are not subject to copyright protection within the United States.
+
+The software is provided by NTIA “AS IS.”  NTIA MAKES NO WARRANTY OF ANY KIND, EXPRESS, IMPLIED OR STATUTORY, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT AND DATA ACCURACY. NTIA does not warrant or make any representations regarding the use of the software or the results thereof, including but not limited to the correctness, accuracy, reliability or usefulness of the software. 
+
+To the extent that NTIA holds rights in countries other than the United States, you are hereby granted the non-exclusive irrevocable and unconditional right to print, publish, prepare derivative works and distribute the NTIA software, in any medium, or authorize others to do so on your behalf, on a royalty-free basis throughout the World.
+
+You may improve, modify, and create derivative works of the software or any portion of the software, and you may copy and distribute such modifications or works. Modified works should carry a notice stating that you changed the software and should note the date and nature of any such change.
+
+You are solely responsible for determining the appropriateness of using and distributing the software and you assume all risks associated with its use, including but not limited to the risks and costs of program errors, compliance with applicable laws, damage to or loss of data, programs or equipment, and the unavailability or interruption of operation. This software is not intended to be used in any situation where a failure could cause risk of injury or damage to property. 
+
+Please provide appropriate acknowledgments of NTIA’s creation of the software in any copies or derivative works of this software.
+

README.md

@@ -1,2 +1,115 @@
-# itm
-The Irregular Terrain Model (ITM)
+# 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**: Verion 1.3 of this code base is functionally identical to version 1.2.2 of the FORTRAN source, which has been archived [here](https://github.com/NTIA/itm-longley-rice).  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 precombiled DLL in the [Release](https://github.com/NTIA/itm/releases) 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](https://github.com/NTIA/itm/packages).
+
+2. A supporting command-line driver is also included in this repository, with its own corresponding [readme](cmdREADME.md).  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 provide for testing purposes.  This is not a comprehensive validation test set.  For ITM in Point-to-Point Prediction Mode, [p2p.csv](p2p.csv) defines the set of inputs and outputs with [pfls.csv](pfls.csv) containing the corresponding set of terrain profiles.  For Area Prediction Mode, inputs and outputs are defined in [area.csv](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  <ul><li>1 = Equatorial</li><li>2 = Continental  Subtropical</li><li>3 = Maritime Subtropical</li><li>4 = Desert</li><li>5 = Continental Temperate</li><li>6 = Maritime Temperate Over Land</li><li>7 = Maritime Temperate Over Sea</li></ul>|
+| `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  <ul><li>0 = Horizontal</li><li>1 = Vertical</li></ul> |
+| `epsilon`         | double |       | 1 < `epsilon` | Relative permittivity |
+| `sigma`           | double | S/m   | 0 < `sigma`   | Conductivity |
+| `mdvar`           | int    |       | enum          | Mode of variability <ul><li>0 = Single Message Mode</li><li>1 = Accidental Mode</il><li>2 = Mobile Mode</li><li>3 = Broadcast Mode</li></ul> 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 <ul><li>`pfl[0]` : Number of elevation points - 1</li><li>`pfl[1]` : Resolution, in meters</li><li>`pfl[i]` : Elevation above sea level, in meters</li></ul> |
+
+### 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 <ul><li>0 = Random</li><li>1 = Careful</li><li>2 = Very Careful</li></ul>|
+| `rx_siting_criteria` | int |       | enum         | Siting criteria of RX <ul><li>0 = Random</li><li>1 = Careful</li><li>2 = Very Careful</li></ul>|
+
+### 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 <ul><li>1 = Line of Sight</li><li>2 = Diffraction</li><li>3 = Troposcatter</li></ul>|
+
+## Error Codes and Warning Flags ##
+
+ITM supports a defined list of error codes and warning flags.  A complete list can be found [here](ERRORS_AND_WARNINGS.md).
+
+## 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 ##
+
+* G.A. Hufford, A.G. Longley, W.A. Kissick, [A Guide to the Use of the ITS Irregular Terrain Model in the Area Prediction Mode](https://www.its.bldrdoc.gov/publications/details.aspx?pub=2091), NTIA Technical Report TR-82-100, April 1982.
+* G.A. Hufford, [The ITS Irregular Terrain Model, version 1.2.2 Algorithm](https://www.its.bldrdoc.gov/media/50676/itm_alg.pdf).
+* G.A. Hufford, [1985 ITM Memo](https://www.its.bldrdoc.gov/media/50675/Hufford_1985_Memo.pdf), Dr. George Hufford's 1985 Memo describing the changes to ITM version 1.2.1 (dated April, 1979) in ITM version 1.2.2 (dated September, 1984)
+* G.A. Hufford, [The Irregular Terrain Model](https://www.its.bldrdoc.gov/media/50674/itm.pdf), The "definitive" representation of the ITS Irregular Terrain Model. It contains both the source code and rather extensive documentation.
+* A.G. Longley and P.L. Rice, [Prediction of Tropospheric Radio Transmission Loss Over Irregular Terrain: A Computer Method - 1968](https://www.its.bldrdoc.gov/publications/details.aspx?pub=2784), NTIA Technical Report ERL 79-ITS 67, July 1968.
+
+## Contact ##
+
+For technical questions about ITM, contact Paul McKenna, (303) 497-3474, pmckenna@ntia.gov.