Add main code, configuration and documentation.

README.md

@@ -0,0 +1,69 @@
+# Wireless Suite
+
+## Overview
+Wireless Suite is a collection of problems in wireless telecommunications.
+
+Comparing research results in telecoms remains a challenge due to the lack of standard problem implementations against
+which to benchmark.
+To solve this, Wireless Suite implements some well-known problems, built as Open-AI Gym compatible classes.
+These are intended to establish performance benchmarks, stimulate reproducible research and foster quantitative
+comparison of algorithms for telecommunication problems.
+
+## Getting started
+The code has been tested to work on Python 3.7 under Windows 10.
+
+1. Get the code:
+    ```
+    git clone https://github.com/nokia/wireless-suite.git
+    ```
+
+2. Use `pip` to install the package:
+   ```
+   pip install --upgrade pip
+   pip install .
+   ```
+3. Modify the script *scripts/launch_agent.py* to execute an  environment of your choosing and obtain performance results.
+
+## Provided problems 
+
+### TimeFreqResourceAllocation-v0
+This environment simulates a OFDM resource allocation task, where a limited number of frequency resources are to be
+allocated to a large number of User Equipments (UEs) over time.
+An agent interacting with this environment plays the role of the MAC scheduler. On each time step, the agent must
+allocate one frequency resource to one of a large number of UEs. The agent gets rewarded for these resource allocation
+decisions. The reward increases with the number of UEs, whose traffic requirements are satisfied.
+The traffic requirements for each UE are expressed in terms of their Guaranteed Bit Rate (if any) and their Packet
+Delay Budget (PDP).
+
+You are invited to develop a new agent that interacts with this environment and takes effective resource allocation
+decisions.
+Four sample agents are provided for reference in the *wireless/agents* folder.
+The performance obtained by the default agents on the default environment configuration is:
+* Random                       -69590
+* Round Robin                  -69638
+* Round Robin IfTraffic        -3284
+* Proportional Fair            -9595
+
+Note that the above average rewards are negative values. The best performing agent is thus the Round Robin IfTraffic.
+
+Additional details about this problem are provided in document *wireless/doc/TimeFreqResourceAllocation-v0.pdf*
+
+#### Evaluation
+The script *wireless/scripts/launch_agent.py* runs 16 episodes with a maximum of 65536 time steps each, and collects the reward
+obtained by the agent on each time step. The result is calculated as the average reward obtained in all time steps on
+all episodes.
+
+## How to contribute
+There are two main ways of contributing to Wireless Suite:
+
+1. **Implementing new problems**: The first version of Wireless Suite contains only one problem implementation. New
+problems can be easily added as simple variations of the first one (e.g. by changing its parameters), or by introducing
+fully new problem implementations (e.g. Adaptive Modulation and Coding, Open Loop Power Control, Handover optimization,
+etc).
+
+2. **Implementing new agents**: Ideally, new agent contributions shall perform better than the default ones.
+
+## References
+1. [Open AI Gym Documentation](http://gym.openai.com/docs/)
+2. [How to create new environments for Gym](https://github.com/openai/gym/blob/master/docs/creating-environments.md)
+3. [Sacred Documentation](https://sacred.readthedocs.io/en/stable/index.html)

config/config_agent.json

@@ -0,0 +1,7 @@
+{
+  "agent": {
+    "agent_type": "round robin",
+    "t_max": 65536,
+    "n_episodes": 16
+  }
+}

config/config_environment.json

@@ -0,0 +1,11 @@
+{
+  "env": {
+    "n_ues": 32,
+    "n_prbs": 25,
+    "buffer_max_size": 8,
+    "eirp_dbm": 13,
+    "f_carrier_mhz": 2655,
+    "max_pkt_size_bits": 41250,
+    "non_gbr_traffic_mean_interarrival_time_ttis": 10
+  }
+}

config/config_sacred.json

@@ -0,0 +1,12 @@
+{
+  "sacred": {
+    "sacred_host": "127.0.0.1",
+    "sacred_port": "27017",
+    "sacred_user": "sacred_user",
+    "sacred_pwd": "sacred_pwd",
+    "sacred_db": "sacred0000",
+    "n_metrics_points": 128,
+    "experiment_name": "Random"
+  },
+  "seed": 0
+}

setup.py

@@ -0,0 +1,14 @@
+"""
+© 2020 Nokia
+Licensed under the BSD 3 Clause license
+SPDX-License-Identifier: BSD-3-Clause
+"""
+from setuptools import setup
+
+setup(name='wireless_suite',
+      version='1.0',
+      packages=['wireless_suite'],
+      license='„2020 Nokia. Licensed under the BSD 3 Clause license. SPDX-License-Identifier: BSD-3-Clause',
+      description='Modules for executing wireless communication problems as OpenAI Gym environments.',
+      install_requires=['gym', 'numpy', 'scipy', 'sacred', 'pytest']
+      )

wireless/__init__.py

@@ -0,0 +1,6 @@
+from gym.envs.registration import register
+
+register(
+    id='TimeFreqResourceAllocation-v0',
+    entry_point='wireless.envs:TimeFreqResourceAllocationV0',
+)

wireless/agents/proportional_fair.py

@@ -0,0 +1,42 @@
+"""
+© 2020 Nokia
+Licensed under the BSD 3 Clause license
+SPDX-License-Identifier: BSD-3-Clause
+"""
+from .random_agent import RandomAgent
+import numpy as np
+
+
+class ProportionalFairAgent(RandomAgent):
+    def __init__(self, action_space, n_ues, buffer_max_size):
+        RandomAgent.__init__(self, action_space)
+        self.t = 0      # Current time step
+
+        self.K = n_ues              # Number of UEs
+        self.L = buffer_max_size    # Maximum number of packets per UE buffer
+        self.n = np.zeros(n_ues)    # Number of past PRB assignments for each UE
+
+    def act(self, state, reward, done):
+        s = np.reshape(state[self.K:self.K*(1 + self.L)], (self.K, self.L))  # Sizes in bits of packets in UEs' buffers
+        buffer_size_per_ue = np.sum(s, axis=1)
+
+        e = np.reshape(state[self.K*(1 + self.L):self.K*(1 + 2*self.L)], (self.K, self.L))  # Packet ages in TTIs
+        o = np.max(e, axis=1)  # Age of oldest packet for each UE
+
+        qi_ohe = np.reshape(state[self.K + 2 * self.K * self.L:5 * self.K + 2 * self.K * self.L], (self.K, 4))
+        qi = np.array([np.where(r == 1)[0][0] for r in qi_ohe])  # Decode One-Hot-Encoded QIs
+
+        # Extract packet delay budget for all UEs
+        b = np.zeros(qi.shape)
+        b[qi == 3] = 100
+        b[qi == 2] = 150
+        b[qi == 1] = 30
+        b[qi == 0] = 300
+
+        priorities = (1+o)/b * buffer_size_per_ue / (1 + self.n)
+
+        action = np.argmax(priorities)
+        self.n[action] += 1
+
+        self.t += 1
+        return action

wireless/agents/random_agent.py

@@ -0,0 +1,21 @@
+"""
+© 2020 Nokia
+Licensed under the BSD 3 Clause license
+SPDX-License-Identifier: BSD-3-Clause
+"""
+
+
+class RandomAgent:
+    """
+    The world's simplest agent!
+
+    See: https://github.com/openai/gym/blob/master/examples/agents/random_agent.py
+    """
+    def __init__(self, action_space):
+        self.action_space = action_space
+
+    def act(self, state, reward, done):
+        return self.action_space.sample()
+
+    def seed(self, seed=0):
+        self.action_space.seed(seed)

wireless/agents/round_robin_agent.py

@@ -0,0 +1,41 @@
+"""
+© 2020 Nokia
+Licensed under the BSD 3 Clause license
+SPDX-License-Identifier: BSD-3-Clause
+"""
+from .random_agent import RandomAgent
+import numpy as np
+
+
+class RoundRobinAgent(RandomAgent):
+    def __init__(self, action_space, n_ues, buffer_max_size):
+        RandomAgent.__init__(self, action_space)
+        self.t = 0      # Current time step
+
+        self.K = n_ues              # Number of UEs
+        self.L = buffer_max_size    # Maximum number of packets per UE buffer
+
+    def act(self, state, reward, done):
+        action = self.t % self.K
+        self.t += 1
+        return action
+
+
+class RoundRobinIfTrafficAgent(RoundRobinAgent):
+    def __init__(self, action_space, n_ues, buffer_max_size):
+        RoundRobinAgent.__init__(self, action_space, n_ues, buffer_max_size)
+
+    def act(self, state, reward, done):
+        action0 = self.t % self.K
+
+        s = np.reshape(state[self.K:self.K*(1 + self.L)], (self.K, self.L))
+        buffer_size_per_ue = np.sum(s, axis=1)
+
+        action = action0
+        while buffer_size_per_ue[action] == 0:
+            action = (action + 1) % self.K
+            if action == action0:
+                break
+
+        self.t += 1
+        return action

wireless/envs/__init__.py

@@ -0,0 +1 @@
+from wireless.envs.time_freq_resource_allocation_v0 import TimeFreqResourceAllocationV0