https://github.com/tamsri/radio-gyms
Radio Gyms is an open-source bundle of AI environments for radio communications.
https://github.com/tamsri/radio-gyms
5g-simulation artificial-intelligence machine-learning open-source python radio reinforcement-learning-environments simulation telecommunications wireless-communication
Last synced: 5 months ago
JSON representation
Radio Gyms is an open-source bundle of AI environments for radio communications.
- Host: GitHub
- URL: https://github.com/tamsri/radio-gyms
- Owner: tamsri
- License: mit
- Created: 2022-03-18T15:11:21.000Z (about 4 years ago)
- Default Branch: master
- Last Pushed: 2022-05-10T21:45:08.000Z (about 4 years ago)
- Last Synced: 2026-01-13T15:56:38.844Z (5 months ago)
- Topics: 5g-simulation, artificial-intelligence, machine-learning, open-source, python, radio, reinforcement-learning-environments, simulation, telecommunications, wireless-communication
- Language: Jupyter Notebook
- Homepage:
- Size: 3.78 MB
- Stars: 13
- Watchers: 3
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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
```shell
pip install radio_gyms
```
### Build from source
```shell
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.
```python
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.
```python
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()```.
```python
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.
```python
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.
```python
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``` : Wireless UAV
### 2. ```radio-gym-02```: UE Location Prediction
### 3. ```radio-gym-03```: UE Location Prediction
## Documentation
Radio Gyms provides radio propagation engines and tools for customizations.
The official documentation can be found at ***[radio-gyms.intelek.ai](https://radio-gyms.intelek.ai)***
## Citations
The pre-released source code can be cited with the following bibtex entry.
```text
@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](https://github.com/tamsri), supawat@intelek.ai
- Builds and implements.
- [Muhammad Aamir Khan](https://scholar.google.com/citations?user=Q7YdzQEAAAAJ), aamir@intelek.ai
- Supervises on ML research and AI.
## Disclaimer
Radio gyms is the implementation from WCSim which is a part of the engineering thesis ["Deep Reinforcement Learning for 5G Base Station Planning"](https://www.academia.edu/75221445/Deep_Reinforcement_Learning_in_5G_Base_Station_Planning_with_3D_Ray_Tracing_Engine) by Supawat Tamsri.
WCSim and Radio Gyms were significantly advised and supported by [Prof. Krzysztof Cichoń](https://scholar.google.com/citations?user=GmzK3-oAAAAJ).
## Community
Feel free to suggest an environment idea or contribute with us.
* [Discord](https://discord.gg/Rp2KhXcpPh)
## Road Map
- [x] v0.1.x - Radio Ray Tracer
- [x] v0.2.x - Theoretical Outdoor Propagation Model
- [x] v0.3.x - Transmitter and Receiver Controller
- [x] v0.4.x - Visualization for desktop
- [x] v0.5.x - Visualization for notebook
- [x] v0.6.x - Outdoor Simulation
- [x] 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](https://github.com/intelek-ai/radio-gyms/blob/master/LICENSE)**.