radio-gyms 0.7.0

an open-source bundle of AI environments for radio communications

Radio Gyms

Radio Gyms is an open-source bundle of AI environments for radio communications. The simulations are built for AI gyms with the support of radio-related calculation modules, and theoretical radio propagation models to simulate an accurate prediction, specifically to perform reinforcement learning algorithms.

Installation

PyPi Package via pip

pip install radio_gyms

Build from source

git clone https://github.com/intelek-ai/radio-gyms
cd radio-gyms
python -m pip install .
cd ..
rm -rf radio_gyms

Dependencies

• python 3.8+
• numpy
• pyglet
• pywavefront

Features

Radio gyms provides the toolkit for building wireless communication simulations including modules can be called to build and customize the radio propagation simulation.

1. Calling Primitive Ray Tracer for Outdoor Propagation

The ray tracer can be called for computing the radio propagation paths in the following example.

from radio_gyms.engines import Tracer

SCENE_FILE_PATH = "./city.obj"
tracer = Tracer(SCENE_FILE_PATH)
# position (x, y, z)
tx_pos = [0, 15, 0]
rx_pos = [-30, 1.5, 45]
# get traced result
result = tracer.trace_outdoor(tx_pos, rx_pos)
# result
# {'direct': False, 
# 'reflections': {'single': [   array([-28.94988531,   4.22886929,  62.39469675]),
#                               array([-70.80339945,   7.04682531,  15.22840999])],
#                  'double': []},
# 'roof_edges': [array([-19.24403786,   8.5621709 ,  28.8660568 ]
# 'tx_pos': array([ 0, 15,  0]),
# 'rx_pos': array([-30. ,   1.5,  45. ]),
# )]}

2. Calculate the traced result with the theoretical outdoor model

The result from the ray tracer can be calculated by the propagation models in radio_gyms.models. In this example, TheoreticalOutdoorModel can compute the traced results to predict the signal strength and delay between the receiver and transmitter based on the theoretical radio propagation models.

from radio_gyms.models import TheoreticalOutdoorModel
result = {
    'direct': False, 
    'reflections': {'single': [ [-28.94988531, 4.22886929, 62.39469675],
                                [-70.80339945, 7.04682531, 15.22840999]],
                    'double': []},
    'roof_edges': [[-19.24403786, 8.5621709 , 28.8660568 ]],
    'tx_pos': [ 0, 15, 0],
    'rx_pos': [-30., 1.5, 45. ],
}
model = TheoreticalOutdoorModel(result, tx_power_dbm=20)
maximum_received_power = model.calculate_max_received_power(frequency=5.4e9) 
# -72.51 dBm
impulses = model.calculate_signal_impulses(freq=5.4e9)
# [{'strength': -85.94590320344925, 'delay': 1.8653420787826134e-07},
# {'strength': -74.3214622218488, 'delay': 2.910702009034143e-07}, 
# {'strength': -77.80902883055407, 'delay': 4.125241781539828e-07}]

3. Visualize the data with window

As we obtain the traced paths from the tracer, we can convert these paths into lines for the visualization. Window() can be called to read the lines and the scene to visualize the scene in 3D by window.run().

import numpy as np
from radio_gyms.visualizers import Window
from radio_gyms.engines.ray_tracer.tracer import Tracer
from radio_gyms.utils import OutdoorResultToLines

MAT_OBJ_PATH = "./city.obj

window = Window()
window.load_obj_to_scene(MAT_OBJ_PATH)
tracer = Tracer(MAT_OBJ_PATH)
tx_pos = np.array([0, 5, 0])
lines = []
while True:
    rx_pos = (np.random.rand(3)*2-1)*100
    rx_pos[1] = 1.2
    if tracer.is_outdoor(rx_pos):
        break
result = tracer.trace_outdoor(tx_pos, rx_pos)
lines = lines + OutdoorResultToLines(result)
window.line_sets = lines
window.run()

With the .run() The camera can be moved by W A S D keys and rotated by Q E.

4. Visualize the scene and radio propagation paths during running a simulation

window.render() can be called to visualize the simulation frame as the simulation updates the components.

from radio_gyms.engines.ray_tracer.tracer import Tracer
from radio_gyms.visualizers import Window
from radio_gyms.utils.converters import outdoor_traced_result_to_line as OutdoorResultToLines
from radio_gyms.simulations import OldtownWalk

MAP_OBJ_PATH = "./city.obj"

window = Window()
window.load_obj_to_scene(MAP_OBJ_PATH)
tracer = Tracer(MAP_OBJ_PATH, ref_max=2) # ref_max == max reflection tracing
simulation = OldtownWalk(tracer, 1, 5)
# Run 100 episodes
for i in range(100):
    simulation.update(1) # update time in the simulation by 1 second
    results = simulation.get_results() # get result from simulation
    window.line_sets = []
    # convert the results to lines for visualizing in window
    for result in results:
        result_lines = OutdoorResultToLines(result)
        window.line_sets += result_lines
    # render the scene    
    window.render()
    window.dispatch_events()

5. Visualize the scene and radio propagation paths on notebook

Radio gyms can be visualized on a notebook in 2D by using utils.Plotter. Plotter() requires definition of boundary of the map to visualize. The parameters such as points and lines can be passed to Plotter to visualize the data.

from radio_gyms.engines import Tracer
from radio_gyms.utils import Plotter, OutdoorResultToLines
MAP_SCENE = "./city.obj"

tracer = Tracer(MAP_SCENE)
rx = [0, 1.2, 0]
tx = [-50, 4, 40]
result = tracer.trace_outdoor(tx, rx)
terrain_map = tracer.get_terrain_depth(64, 64)
plotter = Plotter( tracer.min_bound, tracer.max_bound, terrain_map)
plotter.rx_pos.append(rx)
plotter.tx_pos.append(tx)
plotter.lines =  OutdoorResultToLines(result)

plotter.render_top() # Display from top view

Gyms

1. radio-gym-01 : Cooperative Small Cell Power Switching (Coming soon, V1.0.0)

• Environment

The environment consists of mobile UEs as pedestrians walk in the old town and multiple small cells. The small cells can sense the signal strength and delay of pedestrians where UEs only connect to the cell which provides the strongest signal.

• Reward

The reward is considered for average connected signal strength of all UEs to cells, the average signal-to-noise (SNR) of UEs between connected cell and disconnected cell, and the consumption transmitting power.

• Action

Each cell can control its own transmitting power.

2. radio-gym-02: Beamformer by antenna node control (Expected in v1.5)

Documentation

Radio Gyms provides radio propagation engines and tools for customizations. The official documentation can be found at radio-gyms.intelek.ai

Citations

The pre-released source code can be cited with the following bibtex entry.

@misc{radiogyms2022,
  author = {Supawat Tamsri},
  title = {Radio Gyms},
  year = {2022},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/intelek-ai/radio-gyms}},
}

Contributors

• Supawat Tamsri, [e-mail]
  • Founds and develops.
• Muhammad Aamir Khan, [e-mail]
  • Supervises on machine learning research and AI environments.
• Prof. Eng. Krzysztof Cichoń, [e-mail]
  • Supervises on radio propagation and channel modelling features.
  • Validates and verifies theoretical models and simulated results.

Community

Feel free to suggest an environment idea or contribute with us.

• Discord

Road Map

• v0.1.x - Radio Ray Tracer
• v0.2.x - Theoretical Outdoor Propagation Model
• v0.3.x - Transmitter and Receiver Controller
• v0.4.x - Visualization for desktop
• v0.5.x - Visualization for notebook
• v0.6.x - Outdoor Simulation
• v0.7.x - Radio Gym 01: Wireless UAV Location Control
• v0.8.x - Radio Gym 02: UE Location Prediction
• v0.9.x - Radio Gym 03: Cooperative Small Cell Power Control
• v0.9.5 - Beamforming Engine
• v1.0.x - Radio Gym 04: Intelligent Beamformer
• v1.1.x - FDTD Engine

License

The digital contents in /assets are available under Creative Commons (CC) license.

Source code is licensed under © Intelek AI MIT.

MIT License

Copyright (c) 2022 Intelek AI

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.