diff --git a/index.qmd b/index.qmd index b18c6d8..a698adf 100644 --- a/index.qmd +++ b/index.qmd @@ -6,15 +6,6 @@ date-modified: 2024-06-11 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++, 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. -## Quick Start - -For each supported programming language, we've prepared "quick start" guides to help you get up and running with PropLib software. These pages should be helpful regardless of which specific package(s) you may be interested in using. Choose your programming language below to get started. - -[C++](quick-start/cpp.qmd){.btn .btn-secondary role="button"} -[C#/.NET](quick-start/dotnet.qmd){.btn .btn-secondary role="button"} -[MATLAB](quick-start/matlab.qmd){.btn .btn-secondary role="button"} -[Python](quick-start/python.qmd){.btn .btn-secondary role="button"} - ## Packages Currently, PropLib includes implementations of propagation models developed by the U.S. (NTIA/ITS) and by the International Telecommunication Union Radiocommunication Sector (ITU-R). The following are categorized lists of available packages within PropLib. diff --git a/quick-start/cpp.qmd b/quick-start/cpp.qmd deleted file mode 100644 index 3b805f6..0000000 --- a/quick-start/cpp.qmd +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "Quick Start - C++" ---- - -{{< include /includes/_under_construction.qmd >}} diff --git a/quick-start/dotnet.qmd b/quick-start/dotnet.qmd deleted file mode 100644 index 12653f2..0000000 --- a/quick-start/dotnet.qmd +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: "Quick Start - C#/.NET" -date: 2024-06-11 -date-modified: 2024-06-11 ---- - -{{< include /includes/_under_construction.qmd >}} - -This page provides a walkthrough on how to quickly get up and running calling the ITS Propagation Library packages from the .NET development environment. - -## Dependencies and Limitations - -Users are assumed to be developing in .NET Framework 4.7 or greater. Explicit support is not present at this time for .NET Core, although it is being considered in the near future (if this is a requested feature, please reach out to [code@ntia.gov](mailto:code@ntia.gov) to bump its priority). - -## Internal Package Repository -::: {.callout-warning} -Internal Repository to be Superceded - -Soon, PropLib packages will migrate to public-facing package repositories. Check back later for updates. -::: - -All packages are hosted on an internal NTIA NuGet Server. The location of the server is dependent on your office (packages are cloned between the two locations): - -ITS/Boulder: `\\ntinetapp001g.ntiadc.ntia.doc.gov\ntiadropbox\itsdata\NuGet` or `\\itsfs01\Tools\NuGet` - -OSM/HCHB: `\\nthnetapp002g.ntiadc.ntia.doc.gov\ntiadropbox\itsdata\NuGet` - -### Configuring Visual Studio - -1. Open Visual Studio. -1. Open Options and Select *Package Sources* under NuGet Package Manager - - ![Accessing NuGet package manager settings in Visual Studio](images/nuget_set_up_1.jpg) - -1. Click the green plus symbol to create a new package source -1. For the newly created package source, fill in the details for *Name* and *Source* as follows: - * Name: NTIA NuGet - * Source: - -![Configuring the NuGet package source](images/nuget_set_up_2.jpg) - -1. Click *Update* to confirm the configuration of the new package source - -![Updating the list of NuGet package sources](images/nuget_set_up_3.jpg) - -# Quick Start - -::: {.callout-warning} -TO DO -::: \ No newline at end of file diff --git a/quick-start/images/matpak_install.jpg b/quick-start/images/matpak_install.jpg deleted file mode 100644 index c288e99..0000000 Binary files a/quick-start/images/matpak_install.jpg and /dev/null differ diff --git a/quick-start/images/matpak_propcore_files.jpg b/quick-start/images/matpak_propcore_files.jpg deleted file mode 100644 index b1473f4..0000000 Binary files a/quick-start/images/matpak_propcore_files.jpg and /dev/null differ diff --git a/quick-start/images/nuget_set_up_1.jpg b/quick-start/images/nuget_set_up_1.jpg deleted file mode 100644 index 1b8ad24..0000000 Binary files a/quick-start/images/nuget_set_up_1.jpg and /dev/null differ diff --git a/quick-start/images/nuget_set_up_2.jpg b/quick-start/images/nuget_set_up_2.jpg deleted file mode 100644 index 8216384..0000000 Binary files a/quick-start/images/nuget_set_up_2.jpg and /dev/null differ diff --git a/quick-start/images/nuget_set_up_3.jpg b/quick-start/images/nuget_set_up_3.jpg deleted file mode 100644 index 7bcccee..0000000 Binary files a/quick-start/images/nuget_set_up_3.jpg and /dev/null differ diff --git a/quick-start/matlab.qmd b/quick-start/matlab.qmd deleted file mode 100644 index 36ad9ba..0000000 --- a/quick-start/matlab.qmd +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: "Quick Start - MATLAB" -date: 2024-06-11 -date-modified: 2024-06-11 ---- - -{{< include /includes/_under_construction.qmd >}} - -::: {.callout-warning} -### TO DO - -The matpak approach is abandoned in favor of MEX files and this page needs to be updated accordingly. -::: - -This page provides a walkthrough on how to quickly get up and running calling the ITS Propagation Library packages from a MATLAB development environment. Included in this is a brief introduction to the internal MATLAB package manager, `matpak`. - -## Dependencies and Limitations - -Any reasonably newer version of MATLAB should work. Backwards compatibility with older versions of MATLAB is not possible due to not having access to the software. However, versions starting in 2019 have not shown to have any issues. - -Support is currently limited to Windows users only. This is due to MATLAB's use of the .NET Framework, as opposed to the cross-platform .NET Core. MATLAB currently has not given a timeline to switch to .NET Core, however, as Microsoft is moving everything onto .NET Core in the near future, this implies that as some (hopefully soon) future date, cross-platform support can be achieved. - -## Getting Packages - -::: {.callout-warning} -### TO DO - -Add section detailing workflow for installing new packages -::: - -# Quick Start - -::: {.callout-warning} -### TO DO - -Section needs to be updated with new instructions for MEX -::: - -This example walks a user will: - -1. Configure their machine by installing the ITS MATLAB package manager -2. Install the PropCore package -3. Call into the PropCore library - -## System Setup - -MATLAB support for the ITS Propagation Library relies on an internally developed package manager called `matpak`. Generally speaking, `matpak` allows users to download, update, and manage library packages in MATLAB. More information on `matpak` can be found [here](Matpak). - -![matpak install screenshot](images/matpak_install.jpg) - -To install `matpak`, from the below location: - -For ITS users, - * \\\\itsfs01\\Tools\\Matpak\\installers - -For OSM (or HCHB) users, - * \\\\nthnetapp002g.ntiadc.ntia.doc.gov\\ntiadropbox\\itsdata\\Matlab\\installers - - Install the most recent version. Run the installer with User access (not as Admin). Accept the default file location for install. The installer assumes that MATLAB has been installed onto your machine in the default locations (if this is not true, reach out to [Billy Kozma](wkozma@ntia.gov)). - -## Setting the Correct Package Location - -**Note:** If you are an ITS user, you should be able to skip this step. - -Once the installion has completed, you can verify and update the package location of `matpak`. To do this, open "Windows Explorer" and nagivate to "Documents". Inside the "MATLAB" directory, you should see a "matpak" subdirectory which contains a `settings.ini` file. Open this file in a text editor. The default setting should be: - -```cmd -SOURCE=\\itsfs01\tools\Matpak\packages -``` - -This is the location that `matpak` will use to search for packages. Update this location according to the package source you have access to (listed in previous subsection). - -## Installing Packages - -Installing packages requires only a single command. To install the PropCore package, run: - -```cmd ->> matpak install propcore -Matpak: Package 'PropCore' (Version 1.0.0) has been installed. ->> -``` - -![matpak install screenshot](images/matpak_propcore_files.jpg) - -`matpak` will install the package files in the current directory. The files can be instead installed into a different location and that directory added to the path at runtime. - -## Calling PropCore in MATLAB - -In a script file or the Command Window, copy the following snippet of code: - -```matlab -theta = Terrestrial.TakeoffAngle(5, 1, 100, 8400) -``` - -It should result in: `theta = -0.0459` \ No newline at end of file diff --git a/quick-start/python.qmd b/quick-start/python.qmd deleted file mode 100644 index 80a13a7..0000000 --- a/quick-start/python.qmd +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: "Quick Start - Python" -date: 2024-06-11 -date-modified: 2024-06-11 ---- - -{{< include /includes/_under_construction.qmd >}} - -This page provides a walkthrough on how to quickly get up and running installing and running ITS PropLib software in a Python development environment. - -## Dependencies and Limitations - -Users are assumed to be using a [current version](https://devguide.python.org/versions/) of Python 3. All officially-released versions of Python which have not reached end-of-life are supported. Package dependencies are defined on a per-package basis in each project's `pyproject.toml` file, which will allow your package manager (e.g., `pip`) to discover and install required dependencies automatically when you install a PropLib package. - -## Getting Packages -::: {.callout-warning} -### TO DO - -Update this section when packages are available on PyPi -::: - -# Quick Start - -This example walks a user through how to install and call into ITM. - -## Installing Packages -::: {.callout-warning} -### TO DO - -Modify example to avoid use of `conda` -::: - -Create a new conda environment: - -```cmd -conda create --name prop -conda activate prop -``` - -Install `numpy` as it's a dependency of the `itm` package - -```cmd -pip install numpy -``` -or -```cmd -conda install -c anaconda numpy -``` - -Install `pythonnet` as it's a dependency of the `ohiopyle` package -```cmd -pip install -i https://pypi.anaconda.org/pythonnet/simple pythonnet -``` -or -```cmd -conda install -c pythonnet pythonnet=2.5.2 -``` - -Install `itm` from the local repository - -```cmd -pip install itm --no-index --find-links file://itsfs01/Tools/Python/pip -``` - -Install `ohiopyle` from the local repository -```cmd -pip install ohiopyle --no-index --find-links file://itsfs01/Tools/Python/pip -``` - -## Calling PropCore in Python - -::: {.callout-warning} -### TO DO - -Replace with an interactive Jupyter example -::: - -Open Spyder (or your Python IDE of choice) and copy the following snippet of code: - -```python -import itm - -# 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. -``` \ No newline at end of file