Recommendation ITU-R P.2108 - Python® Wrapper

This repository contains a Python wrapper for the NTIA/ITS implementation of Recommendation ITU-R P.2108. This Recommendation contains three methods for the prediction of clutter loss: Height Gain Terminal Correction Model, Terrestrial Statistical Model, and Aeronautical Statistical Model. The software implements Section 3 of Annex 1 of the Recommendation. This Python package wraps the NTIA/ITS C++ implementation.

Getting Started

This software is distributed on PyPI and is easily installable using the following command.

pip install proplib-p2108

General information about using this model is available on its page on the NTIA/ITS Propagation Library Wiki. Additionally, Python-specific instructions and code examples are available here.

If you're a developer and would like to contribute to or extend this repository, please review the guide for contributors here or open an issue to start a discussion.

Development

This repository contains code which wraps the C++ shared library as an importable Python module. If you wish to contribute to this repository, testing your changes will require the inclusion of this shared library. You may retrieve this either from the relevant GitHub Releases page, or by compiling it yourself from the C++ source code. Either way, ensure that the shared library (.dll, .dylib, or .so file) is placed in src/ITS/ITU/PSeries/P2108/, alongside __init__.py.

Below are the steps to build and install the Python package from the source code. Working installations of Git and a currently-supported version of Python are required. Additional requirements exist if you want to compile the shared library from C++ source code; see relevant build instructions here.

1. Optionally, configure and activate a virtual environment using a tool such as venv or conda.

2. Clone this repository, then initialize the Git submodule containing the test data.

   # Clone the repository
   git clone https://github.com/NTIA/p2108-python
   cd p2108-python
   
   # Initialize Git submodule containing test data
   git submodule init
   
   # Clone the submodule
   git submodule update
   

3. Download the shared library (.dll, .so, or .dylib) from a GitHub Release. Then place the downloaded file in src/ITS/ITU/PSeries/P2108/ (alongside __init__.py).

4. Install the local package and development dependencies into your current environment:

   pip install .[dev]
   

5. To build the wheel for your platform:

   hatchling build
   

Running Tests

Python unit tests can be run to confirm successful installation. You will need to clone this repository's test data submodule (as described above). Then, run the tests with pytest using the following command.

pytest

Additionally, the Study Group Clutter Excel Workbook contains an extensive set of example values which are useful as validation cases.

References

• ITS Propagation Library Wiki
• P2108 Wiki Page
• ITS.ITU.PSeries.P2108 C++ API Reference
• Recommendation ITU-R P.2108
• Report ITU-R P.2402

License

See LICENSE.

"Python" and the Python logos are trademarks or registered trademarks of the Python Software Foundation, used by the National Telecommunications and Information Administration with permission from the Foundation.

Contact

For technical questions, contact code@ntia.gov.

Disclaimer

Certain commercial equipment, instruments, or materials are identified in this project were used for the convenience of the developers. In no case does such identification imply recommendation or endorsement by the National Telecommunications and Information Administration, nor does it imply that the material or equipment identified is necessarily the best available for the purpose.