HermesPy

HermesPy (Heterogeneous Radio Mobile Simulator - Python) is a semi-static link-level simulator based on time-driven mechanisms.

It provides a framework for the link-level simulation of a multi-RAT wireless link, consisting of multiple transmit and receive modems, which may operate at different carrier frequencies. Besides simulating individual transmission links, HermesPy allows the analysis of both co-channel and adjacent-channel interference among different communication systems.

You can find an introductory video here: https://www.barkhauseninstitut.org/en/results/hermespy

Features

The curent release "Platform Release" serves as a platform for joint development. Beside some core functionality, that can be found beside the release plan, its main focus is to provide a software architecture that can be easily extended.

Installation

There are two supported ways to install hermespy on your system:

From PyPI

This is the recommended method for end-users. Hermespy is registered as an official package in PyPI. We intend to directly serve prebuilt binaries for Windows, most Linux distributions and MacOS. Install the package via

#####Windows users:

• conda create -n <envname> python=3.7 (can be omitted for ubuntu users)
• conda activate <envname> (can be omitted for ubuntu users)
• conda install pip (can be omitted for ubuntu users)
• pip install hermespy

#####Linux users

• python -m venv env
• . env/bin/activate
• pip install hermespy

From Source

This is the recommended method for developers. You can build the package from scratch at any system by cloning the repository via

• git clone <this-repo>
• Change to hermespy/

Install it via

#####Windows users

• conda create -n <envname> python=3.7
• conda activate <envname>
• conda install pip
• pip install -r requirements.txt
• pip install -e .

#####Linux users

• Ensure python is linked to python3.7
• python -m venv env
• . env/bin/activate
• pip install -r requirements.txt
• pip install -e .

Quadriga channel model v2.1.30 is supported by HermesPy. For it to be used, some preliminary steps need to be taken. It can be run with either Octave or matlab. For octave, under Windows, you need to set the environemnt variable that tells python where to find octave-cli executable by calling

setx PATH "%PATH%;<path-to-octave-cli>

and install oct2py via pip install oct2py (Ubuntu sets the environment variable automatically).

If you want to run matlab, you must use the matlab.engine package proided by Matlab. Refer to this link.

Running the simulator

1. Activate your virtual environment:
   1. Windows: conda activate <envname>
   2. ubuntu: . env/bin/activate
2. The simulator can be called by python hermes.py <param> <output_dir>.

The main execution file is hermes.py -p <settings-directory -o <results-directory>. Both command line parameters are optional arguments. <settings-directory> contains settings files for the simulation and <results-directory> tells the simulator where to put the result files. Both are relative paths and have default values namely _settings and results. All parameters values in the settings files are in SI units. Plase refer to our documentation (see below).

Some examples may be found in the _examples folder. Check the readmes.

Quadriga

Set Multipath=QUADRIGA for all channels in settings_scenario.ini. The Quadriga channel model will then use a combination of the values provided in all settings_*.ini files. Quadriga-specific values are located in the settings_quadriga.ini. Check before first use.

Important note: As SNR-Values, use SNR=CUSTOM. Setting this value to custom, values provided for snr_vector are interpreted as actual noise variance (in dB/Hz). Check test files for actual values.

Important note: If you decide to run with matlab/octave, ensure you installed matlab/octave and octpy/matlab.engine. Otherwise the program will crash. Although some catches are implemented, this can lead to errors.

Running the tests

Tests may be run by calling pytest in the root directory. They test for

• type linting using mypy
• basic checks on pep8
• unit tests.

If only unit tests are to be executed, call python run_unit_tests.py.

Attention: Due to current GIT LFS storage issues, integrity tests will be uploaded in the future.

Documentation

Documentation can be found here. It is auto-generated by the github action. Quadriga documentation can be found in hermes/docssource.

Python binding

For running ldpc, we rely on a python binding. For that purpose, we use pybind11. If you want to use it, choose use_binding = True in the settings_ldpc_encoder.ini file. This increases the speed of a factor of 100. If there any errors occuring via building etc., you can choose use_binding = False for running python code.

Known Limitations

• no parallelization of the simulation
• general performance improvemenets required

Authors

• Andre Noll Barreto
• Tobias Kronauer
• Jan Adler

Copyright

Copyright (C) 2021 Barkhausen Institut gGmbH