Merge pull request #1 from NTIA/version-1

Public Release of LFMF, version 1.0

.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,74 @@
+############
+## 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
+win32/packages/
+**/.vs
+*.tlog
+*.obj
+*.log
+*.filters
+*.lastbuildstate
+*.manifest
+*.cache
+*.users
+*.user
+*.res
+*.opendb
+*.db
+*.unsuccessfulbuild
+*.ipch
+*.pdb
+*.exp
+*.ilk
+*.idb
+*.opensdf
+*.sdf
+*.u2d
+*.suo
+*.tiff
+*.txt
+*.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
+

LFMF_Examples.csv

@@ -0,0 +1,6 @@
+h_tx__meter,h_rx__meter,f__mhz,P_tx__watt,N_s,d__km,epsilon,sigma,pol,rtn,A_btl__db,E_dBuVm,P_rx__dbm,method
+0,0,0.01,1000,301,1000,15,0.005,0,0,184.5,-82.5,-114.9,1
+0,0,1,5000,301,5000,15,0.005,1,0,536.5,-387.5,-459.9,1
+5.5,1.5,10,500,315,15,15,0.005,0,0,151.3,7.6,-84.8,0
+1,1,0.45,1000,315,3000,15,0.005,1,0,264.3,-129.3,-194.8,1
+10,10,30,10000,315,5000,15,0.005,0,0,1574.9,-1393.3,-1495.3,1

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,77 @@
-# LFMF
-Low Frequency / Medium Frequency (LF/MF) Propagation Model
+# Low Frequency / Medium Frequency (LF/MF) Propagation Model
+
+This code repository contains an the NTIA/ITS implementation of the Low Frequency / Medium Frequency (LF/MF) Propagation Model. LF/MF 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.
+
+## Inputs ##
+
+| Variable          | Type   | Units | Limits       | Description  |
+|-------------------|--------|-------|--------------|--------------|
+| `h_tx__meter`     | double | meter | 0 <= `h_tx__meter` <= 50 | Height of the transmitter |
+| `h_rx__meter`     | double | meter | 0 <= `h_rx__meter` <= 50 | Height of the receiver |
+| `f__mhz`          | double | MHz   | 0.01 <= `f__mhz` <= 30 | Frequency |
+| `P_tx__watt`      | double | Watt  | 0 < `P_tx__watt` | Transmitter power |
+| `N_s`             | double | N-Units | 250 <= `N_s` <= 400 | Surface refractivity |
+| `d__km`           | double | km    | 0 < `d__km`  | Path distance |
+| `epsilon`         | double |       | 1 <= `epsilon` | Relative permittivity |
+| `sigma`           | double | S/m   | 0 < `sigma` | Conductivity |
+| `pol`             | int    |       |              | Polarization <ul><li>0 = Horizontal</li><li>1 = Vertical</li></ul> |
+
+## Outputs ##
+
+Outputs to LFMF are contained within a defined `Result` structure.
+
+| Variable      | Type   | Units | Description |
+|---------------|--------|-------|-------------|
+| `A_btl__db`   | double | dB    | Basic transmission loss |
+| `E_dBuVm`     | double | dB(uV/m) | Electrice field strength |
+| `P_rx__dbm`   | double | dBm   | Received power |
+| `method`      | int    |       | Solution method <ul><li>0 = Flat earth with curve correction</li><li>1 = Residue series</li></ul> |
+
+## Return Codes ##
+
+Possible return codes, including the corresponding defined constant name as defined in `LFMF.h`:
+
+| Value | Const Name                       | Description  |
+| ------|----------------------------------|--------------|
+|     0 | `SUCCESS`                        | Successful execution |
+|  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__FREQUENCY`               | Frequency is out of range |
+|  1003 | `ERROR__TX_POWER`                | Transmit power is out of range |
+|  1004 | `ERROR__SURFACE_REFRACTIVITY`    | Surface refractivity is out of range |
+|  1005 | `ERROR__PATH_DISTANCE`           | Path distance is out of range |
+|  1006 | `ERROR__EPSILON`                 | Epsilon is out of range |
+|  1007 | `ERROR__SIGMA`                   | Sigma is out of range |
+|  1008 | `ERROR__POLARIZATION`            | Invalid value for polarization |
+
+## Example Values ##
+
+A set of example inputs and outputs are provided for testing purposes.  This is not a comprehensive validation test set.  The test set can be found in [LFMF_Examples.csv](LFMF_Examples.csv).
+
+## Notes on Code Style ##
+
+* In general, variables follow the naming convention in which a single underscore denotes a subscript (pseudo-LaTeX format), where a double underscore is followed by the units, i.e. h_tx__meter.
+* Variables are named to match their corresponding mathematical variables from their publication text.
+* Wherever possible, equation numbers 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 LFMF consists of a simple pass-through wrapper around the native DLL.  It is compiled to target .NET Framework 4.7.2.  Distribution and updates are provided through the published NuGet package.
+
+## References ##
+
+* Bremmer, H. "Terrestrial Radio Waves" _Elsevier_, 1949. 
+* DeMinco, N. "Medium Frequency Propagation Prediction Techniques and Antenna Modeling for Intelligent Transportation Systems (ITS) Broadcast Applications", [_NTIA Report 99-368_](https://www.its.bldrdoc.gov/publications/2399.aspx), August 1999
+* DeMinco, N. "Ground-wave Analysis Model For MF Broadcast System", [_NTIA Report 86-203_](https://www.its.bldrdoc.gov/publications/2226.aspx), September 1986
+* Sommerfeld, A. "The propagation of waves in wireless telegraphy", _Ann. Phys._, 1909, 28, p.665
+* Wait, J. "Radiation From a Vertical Antenna Over a Curved Stratified Ground", _Journal of Research of the National Bureau of Standards_.  Vol 56, No. 4, April 1956. Research Paper 2671
+
+## Contact ##
+
+For questions, contact Nick DeMinco, (303) 497-3453, [email protected]

dotnet/ITS.Propagation.LFMF/ITS.Propagation.LFMF.csproj

@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project ToolsVersion="15.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+  <Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" Condition="Exists('$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props')" />
+  <PropertyGroup>
+    <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
+    <Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>
+    <ProjectGuid>{1C761232-C4C0-4403-AA3A-7160DCDF48C8}</ProjectGuid>
+    <OutputType>Library</OutputType>
+    <AppDesignerFolder>Properties</AppDesignerFolder>
+    <RootNamespace>ITS.Propagation</RootNamespace>
+    <AssemblyName>ITS.Propagation.LFMF</AssemblyName>
+    <TargetFrameworkVersion>v4.7.2</TargetFrameworkVersion>
+    <FileAlignment>512</FileAlignment>
+    <Deterministic>true</Deterministic>
+  </PropertyGroup>
+  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
+    <DebugSymbols>true</DebugSymbols>
+    <DebugType>full</DebugType>
+    <Optimize>false</Optimize>
+    <OutputPath>bin\Debug\</OutputPath>
+    <DefineConstants>DEBUG;TRACE</DefineConstants>
+    <ErrorReport>prompt</ErrorReport>
+    <WarningLevel>4</WarningLevel>
+    <DocumentationFile>bin\Debug\ITS.Propagation.LFMF.xml</DocumentationFile>
+  </PropertyGroup>
+  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
+    <DebugType>pdbonly</DebugType>
+    <Optimize>true</Optimize>
+    <OutputPath>bin\Release\</OutputPath>
+    <DefineConstants>TRACE</DefineConstants>
+    <ErrorReport>prompt</ErrorReport>
+    <WarningLevel>4</WarningLevel>
+    <DocumentationFile>bin\Release\ITS.Propagation.LFMF.xml</DocumentationFile>
+  </PropertyGroup>
+  <ItemGroup>
+    <Reference Include="System" />
+    <Reference Include="System.Core" />
+    <Reference Include="System.Xml.Linq" />
+    <Reference Include="System.Data.DataSetExtensions" />
+    <Reference Include="Microsoft.CSharp" />
+    <Reference Include="System.Data" />
+    <Reference Include="System.Net.Http" />
+    <Reference Include="System.Xml" />
+  </ItemGroup>
+  <ItemGroup>
+    <Compile Include="LFMF.cs" />
+    <Compile Include="Properties\AssemblyInfo.cs" />
+    <Compile Include="Result.cs" />
+  </ItemGroup>
+  <Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />
+</Project>

dotnet/ITS.Propagation.LFMF/ITS.Propagation.LFMF.sln

@@ -0,0 +1,25 @@
+
+Microsoft Visual Studio Solution File, Format Version 12.00
+# Visual Studio Version 16
+VisualStudioVersion = 16.0.30320.27
+MinimumVisualStudioVersion = 10.0.40219.1
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "ITS.Propagation.LFMF", "ITS.Propagation.LFMF.csproj", "{1C761232-C4C0-4403-AA3A-7160DCDF48C8}"
+EndProject
+Global
+	GlobalSection(SolutionConfigurationPlatforms) = preSolution
+		Debug|Any CPU = Debug|Any CPU
+		Release|Any CPU = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(ProjectConfigurationPlatforms) = postSolution
+		{1C761232-C4C0-4403-AA3A-7160DCDF48C8}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{1C761232-C4C0-4403-AA3A-7160DCDF48C8}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{1C761232-C4C0-4403-AA3A-7160DCDF48C8}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{1C761232-C4C0-4403-AA3A-7160DCDF48C8}.Release|Any CPU.Build.0 = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(SolutionProperties) = preSolution
+		HideSolutionNode = FALSE
+	EndGlobalSection
+	GlobalSection(ExtensibilityGlobals) = postSolution
+		SolutionGuid = {ECF2AF6A-510E-4A3F-BAA6-51FDC7F311C6}
+	EndGlobalSection
+EndGlobal

dotnet/ITS.Propagation.LFMF/LFMF.cs

@@ -0,0 +1,82 @@
+using System;
+using System.Runtime.InteropServices;
+
+namespace ITS.Propagation
+{
+    /// <summary>
+    /// The Low Frequency / Medium Frequency (LF/MF) Propagation Model
+    /// </summary>
+    public static partial class LFMF
+    {
+        #region 32-Bit P/Invoke Definitions
+
+        [DllImport("LFMF_x86.dll", CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Ansi, EntryPoint = "LFMF")]
+        private static extern int LFMF_x86(double h_tx__meter, double h_rx__meter, double f__mhz, double P_tx__watt,
+            double N_s, double d__km, double epsilon, double sigma, int pol, out Result result);
+
+        #endregion
+
+        #region 64-Bit P/Invoke Definitions
+
+        [DllImport("LFMF_x64.dll", CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Ansi, EntryPoint = "LFMF")]
+        private static extern int LFMF_x64(double h_tx__meter, double h_rx__meter, double f__mhz, double P_tx__watt,
+            double N_s, double d__km, double epsilon, double sigma, int pol, out Result result);
+
+        #endregion
+
+        private delegate int LFMF_Delegate(double h_tx__meter, double h_rx__meter, double f__mhz, double P_tx__watt,
+            double N_s, double d__km, double epsilon, double sigma, int pol, out Result result);
+
+        private static LFMF_Delegate LFMF_Invoke;
+
+        static LFMF()
+        {
+            if (Environment.Is64BitProcess)
+                LFMF_Invoke = LFMF_x64;
+            else
+                LFMF_Invoke = LFMF_x86;
+        }
+
+        /// <summary>
+        /// Compute the LFMF propagation prediction
+        /// </summary>
+        /// <param name="h_tx__meter">Transmitter height, in meters</param>
+        /// <param name="h_rx__meter">Receiver height, in meters</param>
+        /// <param name="f__mhz">Frequency, in MHz</param>
+        /// <param name="P_tx__watt">Transmit power, in Watts</param>
+        /// <param name="N_s">Surface refractivity, in N-Units</param>
+        /// <param name="d__km">Path distance, in km</param>
+        /// <param name="epsilon">Relative permittivity</param>
+        /// <param name="sigma">Conductivity</param>
+        /// <param name="pol">Polarization</param>
+        /// <param name="result">Prediction result</param>
+        /// <returns>Error code</returns>
+        public static int Invoke(double h_tx__meter, double h_rx__meter, double f__mhz, double P_tx__watt,
+            double N_s, double d__km, double epsilon, double sigma, Polarization pol, out Result result)
+        {
+            return LFMF_Invoke(h_tx__meter, h_rx__meter, f__mhz, P_tx__watt, N_s,
+                d__km, epsilon, sigma, (int)pol, out result);
+        }
+
+        /// <summary>
+        /// Compute the LFMF propagation prediction
+        /// </summary>
+        /// <param name="h_tx__meter">Transmitter height, in meters</param>
+        /// <param name="h_rx__meter">Receiver height, in meters</param>
+        /// <param name="f__mhz">Frequency, in MHz</param>
+        /// <param name="P_tx__watt">Transmit power, in Watts</param>
+        /// <param name="N_s">Surface refractivity, in N-Units</param>
+        /// <param name="d__km">Path distance, in km</param>
+        /// <param name="epsilon">Relative permittivity</param>
+        /// <param name="sigma">Conductivity</param>
+        /// <param name="pol">Polarization</param>
+        /// <param name="result">Prediction result</param>
+        /// <returns>Error code</returns>
+        public static int Invoke(double h_tx__meter, double h_rx__meter, double f__mhz, double P_tx__watt,
+            double N_s, double d__km, double epsilon, double sigma, int pol, out Result result)
+        {
+            return LFMF_Invoke(h_tx__meter, h_rx__meter, f__mhz, P_tx__watt, N_s,
+                d__km, epsilon, sigma, pol, out result);
+        }
+    }
+}

dotnet/ITS.Propagation.LFMF/Properties/AssemblyInfo.cs

@@ -0,0 +1,36 @@
+using System.Reflection;
+using System.Runtime.CompilerServices;
+using System.Runtime.InteropServices;
+
+// General Information about an assembly is controlled through the following
+// set of attributes. Change these attribute values to modify the information
+// associated with an assembly.
+[assembly: AssemblyTitle("ITS.Propagation.LFMF")]
+[assembly: AssemblyDescription("")]
+[assembly: AssemblyConfiguration("")]
+[assembly: AssemblyCompany("")]
+[assembly: AssemblyProduct("ITS.Propagation.LFMF")]
+[assembly: AssemblyCopyright("")]
+[assembly: AssemblyTrademark("")]
+[assembly: AssemblyCulture("")]
+
+// Setting ComVisible to false makes the types in this assembly not visible
+// to COM components.  If you need to access a type in this assembly from
+// COM, set the ComVisible attribute to true on that type.
+[assembly: ComVisible(false)]
+
+// The following GUID is for the ID of the typelib if this project is exposed to COM
+[assembly: Guid("1c761232-c4c0-4403-aa3a-7160dcdf48c8")]
+
+// Version information for an assembly consists of the following four values:
+//
+//      Major Version
+//      Minor Version
+//      Build Number
+//      Revision
+//
+// You can specify all the values or you can default the Build and Revision Numbers
+// by using the '*' as shown below:
+// [assembly: AssemblyVersion("1.0.*")]
+[assembly: AssemblyVersion("1.0.0.0")]
+[assembly: AssemblyFileVersion("1.0.0.0")]