RAN Digital Twin

The following sections describe how to run simulations in three different modes - EM, RAN, and ML training.

The EM simulation mode simulates the electromagnetic propagation between transmitters and receivers and does not include the transfer of information from RAN to UEs or vice versa.

Attaching a worker from the UI

As discussed in the previous sections, the Aerial Omniverse Digital Twin consists of five subcomponents:

• the graphical user interface

• Nucleus

• ClickHouse

• the scene importer

• and the RAN digital twin,

where the Nucleus server is the element that allows all the others to interact with one another.

Our entry point to running simulations is the graphical user interface. After opening the graphical interface, we can navigate to the Configuration tab to attach to an instance of the RAN digital twin, here referred to also as a worker.

Once in the Configuration tab, we shall enter the DB host, DB port for the ClickHouse server and press the Connect button. If the server is reached successfully, the indicator next to the Connect button will go from red to green. Continuing, we can then add a DB name, and optionally a DB author. DB notes can be left empty or can be used to describe key characteristics of the simulation which can help us to retrieve at a later point. We can disconnect from the DB at any time by clicking the Disconnect button.

Next, we can enter the Nucleus server URL, e.g. omniverse://<Nucleus IP or hostname>, and the desired live Session Name. The Broadcast Channel Name is an optional parameter to additionally isolate multiple workers running on the same node. By default, Broadcast Channel Name is simply broadcast. Finally, we can specify the URLs of the Assets installed on the selected Nucleus server during installation.

After these steps, we are ready to click on the Attach worker button from the toolbar, which is the icon represented by a set of gears. If there is a problem with the installation and the graphical user interface is not able to communicate with the worker, an error window will pop up.

Differently, if the worker attaches successfully, the gear icon will turn green as shown below. To detach the worker, we can click the gear icon again and confirm we want to detach the work. The icon will turn gray again.

It is worth mentioning that it is not necessary to explicitly connect to the database each time since attaching the worker will also connect to the database. Of course, the DB host and DB port need to be valid for this to happen.

After attaching the worker, we are ready to open a scene. We can do so by going to File > Open and selecting a scene, e.g. tokyo.usd, from the Nucleus server. Alternatively, we can use the Content tab and double click on the file we want to open.

After the UI and the worker both open the scene, we will see a 3D map in the viewport, and the Live session icon in the top right will turn green, indicating that the live session is active.

Adding antenna panels

Next, we need to create the antenna panels that the RUs and UEs will use.

First, we can create a new antenna array by right clicking on the Stage widget and selecting the Aerial > Create Panel entry from the context menu. The new panel can be found in the Stage widget under the Panels entry. By selecting the new panel, we can inspect its properties and change using the Antenna Elements tab and the Property widget as illustrated in the figure below.

Custom antenna patterns

In release 1.0, the Aerial Omniverse Digital Twin supports the possibility of importing and using a custom antenna pattern. An example of the format in which the pattern needs to be specified can be found in

            

            
/aodt/aodt_sim/antennas/infinitesimal_dipole.csv
        

in the aodt_sim container.

To use a custom antenna file, e.g., user_antenna_pattern.csv, the current process is as follows:

1. Access the host where the aodt_sim container is running or will run

2. Copy

   Copied!

               
   
               
   cd $HOME/backend_bundle
   docker-compose down
   vi docker-compose.yml
           

3. Edit docker-compose.yml and set

   Copy

   Copied!

               
   
               
   services:
   	connector:
   	
   		[...]
   		
   		command: ./aodt_sim --nucleus omniverse://omniverse-server --broadcast broadcast --log debug --antenna-pattern-path /aodt_sim/antennas/user_antenna_pattern.csv
   		
   		[...]
   
   		volumes:
   			- ./aodt_sim/antennas:/aodt/aodt_sim/antennas
   			
           [...]
           

4. Bring the container up again

   Copy

   Copied!

               
   
               
   docker-compose up -d
           

Deploying RUs

To deploy new radio units (RUs), it is sufficient to right click on the map with the mouse and select Aerial > Deploy RU. This will create a movable asset which follows the mouse. Once the location of the RU is found, we can click to confirm the position of the RU. The RU can be later moved by selecting it, right clicking on it and using Aerial > Move RU from the context menu.

After a given RU is in the intended position, its attributes can be modified using the property widget. Most importantly we need to associate a Panel Type is the field is empty.

Deploying UEs

The UEs can be deployed in two ways - procedurally or manually. To deploy manually, we can navigate to the viewport and right click on the position where we would like the UE to be located. Selecting Aerial > Deploy UE from the context menu will create a capsule in the desired location. The corresponding entry in the UEs group of the stage widget will have the Manually Created flag active.

For a manually created UE, we can also specify its mobility path by clicking on the Edit Waypoints button in the UE property widget. Then, in the viewport we can draw a polyline defining the intended trajectory of the UE across the map.

This approach is typically sufficient to simulate small scenarios, where the number of UEs is limited. For larger populations of UEs, we can procedurally generate a set of UEs by changing the parameter Number of UEs in the Scenario entry of the Stage widget. Pressing the Generate UEs button in the toolbar, when the worker is attached, will procedurally create enough UEs, so that the total number of UEs the one specified in Scenario.

We can constrain where the procedural UEs are generated and can move by creating a Spawn Zone, i.e., by right clicking in the viewport and selecting Aerial > Deploy Spawn Zone. This will create the bounding box show in the figure.

We can adjust the size and position of the bounding box using the Move, Rotate, and Scale buttons in the toolbar. More in detail, after selecting one of such actions, we can drag the red/blue/green arrows and rectangles show in the figure to execute the desired transformation.

It is important that bounding box intersects with the ground of the stage. Otherwise, the procedural UEs will not be dropped in the spawn zone. For this reason, we might want to modify the spawn zone bounding box from the top view, instead of perspective view (the view can be changed from the Camera view widget at the top of the viewport).

If there is no spawn zone or if the spawn zone bounding box is too small, then procedural UEs will be dropped in a random position in the stage.

Procedural and manual UEs can be mixed for a given deployment, and manual UEs are not moved at every press of the Generate UEs button.

Changing the scattering properties of the environment

The proper association of materials to the scene geometry plays a key role in producing a realistic representation of the radio environment. Currently, materials can be assigned to each building and to the terrain as a whole. To do so,

• we can select the building we want to edit using either the stage view or the viewport and then proceed to alter the field Building Material from the property widget;

• similarly, for the terrain, we can select the ground_plane asset in the stage view and then modify the Ground Plane Material field from the property widget.

For the buildings, it is also possible to batch assign a given material to the whole map by selecting World/buildings in the stage widget.

With a similar procedure and interface, we can also assign two other important properties:

• Enable RF: this flag indicates whether the mesh or meshes representing

  • one building,

  • all of the buildings

  • or the terrain

  can interact with the electromagnetic field. If this flag is not enabled the electromagnetic field will not be able to interact with the geometry of the selected asset;

• Enable Diffusion: this option in turn specifies whether the mesh or meshes - again representing

  • one building

  • all of the buildings

  • or the terrain

  can interact with the electromagnetic field in a diffuse fashion, i.e., whether the surface of such meshes can produce non-specular reflections.

Running simulations

Before running the simulation, it is important to check that all of the parameters in the Scenario property widget are aligned with our intentions that Enable Training and Simulate RAN are unchecked.

As mentioned in the previous section, the duration and the sampling period of the simulation is determined by the Simulation Mode in Scenario. The user is given two options: duration and interval, or slot and symbol per slot.

• Simulation Mode: Duration requires to set

  • Batches,

  • Duration,

  • Interval

• Simulation Mode: Slots instead requires

  • Batches,

  • Slots Per Batch,

  • Samples Per Slot.

Refer to the Graphical User Interface section describing the Scenario stage widget for more details on these and other parameters.

Now, we can generate the UEs and the trajectories that they will follow during the simulation using the Generate UEs button. The trajectories appear in the viewport widget as polylines in white on the ground plane, and in the Stage widget as entries of the runtime scope. Once the UE and their trajectories are available, we can start the simulation by pressing the Start UE mobility button in the toolbar.

While running, the simulation can be paused and stopped using the Pause UE mobility and the Stop UE mobility buttons of the toolbar. While the simulation is paused, the Generate UEs button can be pressed but it will not generate a new set of trajectories. In order to so, the simulation will have to be stopped first using the Stop UE mobility button. The progress of the simulation is shown in the progress bar.

Viewing simulation results

When the simulation is complete, press the Play button on the toolbar or move the blue indicator in the Timeline widget to a specific frame of interest. To stop the replay, we can click the Stop button.

The visualization of the rays can be turned on or off for each RU-UE pair by selecting the UE ahead of the simulation and using the Property widget as illustrated in the figure.

If a given RU is not selected before the simulation was launched, and we are interested in seeing the rays from that RU, we can use the Refresh telemetry button.

Radio environment

The radio environment results stored in the database are for the RU to UE direction, i.e., for downlink. Specifically, if we take

• the total transmitted power \(P^{\left(RU\right)}\) at RU,

• the number of polarizations used at RU per transmitting antenna site \(N^{\left(RU\right)}_{pol.}\)

• the number of horizontal antenna elements used at the RU \(N^{\left(RU\right)}_{hor.}\)

• the number of vertical antenna elements used at the RU \(N^{\left(RU\right)}_{vert.}\)

• the number of FFT points \(n\)

• the channel frequency response per link \(\mathbf{H}_{i,j}^{\left(UE\right)}\left( k \right)\) observed at the UE for a given subcarrier \(k\), across the link from the \(i\)-transmitter antenna to the \(j\)-th receiver antenna

• the channel frequency response per link \(\mathbf{H}_{i,j}^{\left(ch\right)}\left( k \right)\) observed at the UE for a given subcarrier \(k\), across the link from the \(i\)-transmitter antenna to the \(j\)-th receiver antenna when each subcarrier is allocated unitary power at transmission

the results are such that

\( \left<\mathbf{H}_{i,j}^{\left(UE\right)}, \mathbf{H}_{i,j}^{\left(UE\right)} \right> = \dfrac{P^{\left(RU\right)}}{n \cdot N^{\left(RU\right)}_{pol.} \cdot N^{\left(RU\right)}_{hor.} \cdot N^{\left(RU\right)}_{vert.}} \left<\mathbf{H}_{i,j}^{\left(ch\right)}, \mathbf{H}_{i,j}^{\left(ch\right)} \right>. \) The set of \(\left\{\mathbf{H}_{i,j}^{\left(UE\right)}\left( k \right)\right\}_{i,j,k}\) is stored in the cfrs table discussed in the next section.

If we define \( \mathbf{h}_{i,j}^{\left(UE\right)} = \dfrac{{\rm{iFFT}}_n \left[ \mathbf{H}_{i,j} ^ {\left( UE \right)}\right]}{\sqrt{n}} \) and the geometrically calculated channel impulse response as \( h^{UE}_{i,j} \left(t\right) = \sum_w h^{\left(w \right)}_{i,j} \delta\left(t - \tau^{\left(w \right)}_{i,j} \right) \) we also have \( \left<h^{UE}_{i,j}, h^{UE}_{i,j}\right> = \left<\mathbf{h}_{i,j}^{\left(wb\right)}, \mathbf{h}_{i,j}^{\left(wb\right)}\right> \) where the set of \(\left\{h_{i,j}^{\left(UE\right)}\right\}_{i,j}\) is stored in the raypaths table discussed in the upcoming section.

Finally, if we are interested in calculating the channel frequency response in uplink, we can do so by imposing \( \left<\mathbf{H}_{i,j}^{\left(RU\right)}, \mathbf{H}_{i,j}^{\left(RU\right)} \right>_{UL} = \dfrac{P^{\left(UE\right)}}{N^{\left(UE\right)}_{pol.} \cdot N^{\left(UE\right)}_{hor.} \cdot N^{\left(UE\right)}_{vert.}} \cdot \dfrac{N^{\left(RU\right)}_{pol.} \cdot N^{\left(RU\right)}_{hor.} \cdot N^{\left(RU\right)}_{vert.}}{P^{\left(RU\right)}} \left<\mathbf{H}_{i,j}^{\left(UE\right)}, \mathbf{H}_{i,j}^{\left(UE\right)} \right>_{DL}. \)

The RAN simulation mode builds on top of the EM mode and adds key elements of the physical (PHY) and medium access control (MAC) layers. To enable the simulation of the RAN, we can select the Scenario entry under the Stage widget and enable the Simulate RAN checkbox, as shown in the figure below. This will restrict the Simulation mode field in Scenario to Slots.

We can then define the number of batches, number of slots per batch and samples per slot as in EM mode. Specifically,

• when Samples Per Slot is set to 1, a single front-loaded realization of the channel will be used across the whole slot

• whereas when Samples Per Slot is set to 14, every OFDM symbol will be convolved with a different channel realization.

RAN Parameters

The RAN parameters are stored in

            

            
/aodt/aodt_sim/src_be/components/common/config_ran.json
        

where the following parameters can be changed

Simulation

After the parameters described in config_ran.json are set, we can run the simulation using the same sequence of as for the EM mode. The results are then propagated to

• the graphical interface, where we can visualize instantaneous throughput and modulation coding scheme (MCS) for each UE

• the local console, where detailed scheduling information (e.g., PRB allocations and number of layers) are printed slot-by-slot

• the selected ClickHouse database, where the full telemetry will be stored.

Graphical user interface

After the simulation is complete, we can select a specific UE under in the Stage widget and press the play button from the toolbar. In the Property widget, we will see the time series of the instantaneous throughput and the MCS allocated to the UE, for both downlink and uplink, as in the figure below.

Additionally, we can observe the instantaneous throughput of the UE directly above their representation in the viewport, as shown below.

The MCS allocated by the MAC scheduler in serving a given UE can also be found right below the instantaneous throughput.

Local console

If accessible, additional details can be observed in the console where the RAN digital twin is running. At the end of each slot, a table is printed listing all scheduled UEs, PRB allocations (start PRB index and number of allocated PRBs), MCS, number of layers, redundancy version in presence of HARQ, pre-equalization SINR, post-equalization SINR, and CRC results, with 0 denoting a successful decoding.

            

            
==============================================  results  ================================================
cell idx    grp idx   rnti     startPrb     nPrb    MCS   layer     RV   sinrPreEq    sinrPostEq     CRC
   0         0         94       176          80       4      2       0     5.67         4.16           0
   0         1         95         4          36       0      2       0    -3.94        -2.43           0
   0         2        155        40          40       3      2       0     1.47         1.10           0
   0         3        175        80          96      27      1       0    34.94        40.00           0
   0         4        192       256          16       1      1       0    -6.14        -1.21           0
   0         5        193         0           4      26      2       0    36.21        26.23        9860658
   1         6         28       200          16      15      1       0    10.12        16.60           0
   1         7         58       216          56      10      1       0     3.95        10.01           0
   1         8         89         0          80      24      1       0    12.64        22.68        7891203
   1         9         92        80          12      27      1       0    35.69        40.00           0
   1        10        178       148          52      12      1       0     6.74        11.62           0
   1        11        184        92          56       7      1       0     2.02         7.28           0
   2        12         34       244          28      27      1       0    34.56        39.19           0
   2        13         47       124          48      15      1       0     6.36        15.37           0
   2        14         60        16          92      16      1       0     5.22        15.24           0
   2        15         68       172          72       9      1       0     3.41         9.45           0
   2        16        194         0          16      11      1       0     3.72        10.74           0
   2        17        199       108          16       3      2       0     9.68         4.18           0
   3        18         23       200           8      27      1       0    31.78        37.85           0
   3        19         56       208          28      20      1       0    14.68        19.20           0
   3        20         57         0          60       3      1       0    -0.52         5.20           0
   3        21         62        60         140      27      1       0    33.20        37.99           0
   3        22        160       260          12      15      1       0    14.91        20.29           0
   3        23        187       236          24      27      1       0    36.80        39.92           0
=========================================================================================================
        

ClickHouse database

Comprehensive telemetry data is available in the telemetry table of the database used for the simulation. For instance,

            

            
clickhouse-client

aerial :) select * from aerial_2024_4_16_14_28_33.telemetry

SELECT *
FROM aerial_2024_4_16_14_28_33.telemetry

Query id: e463ec6a-4e11-4197-88e0-8762a630181d

┌batch_id─┬─slot_id─┬─link─┬─ru_id─┬─ue_id─┬─startPrb─┬─nPrb─┬─mcs─┬─layers─┬───tbs─┬─rv─┬─outcome─┬───scs─┐
│       0 │       0 │ UL   │     0 │    46 │       28 │  132 │   0 │      1 │   372 │  0 │       1 │ 30000 │
│       0 │       0 │ UL   │     0 │    49 │        0 │   28 │   0 │      1 │    80 │  0 │       1 │ 30000 │
│       0 │       0 │ UL   │     0 │    53 │      160 │   24 │   0 │      2 │   141 │  0 │       1 │ 30000 │
│       0 │       0 │ UL   │     0 │    94 │      184 │   88 │   0 │      2 │   497 │  0 │       0 │ 30000 │
│       0 │       0 │ UL   │     1 │   124 │        0 │  272 │   0 │      1 │   769 │  0 │       1 │ 30000 │
│       0 │       1 │ UL   │     1 │   124 │        0 │  272 │   9 │      1 │  7813 │  0 │       1 │ 30000 │
│       0 │       1 │ UL   │     2 │    34 │        0 │  272 │   0 │      1 │   769 │  0 │       1 │ 30000 │
│       0 │       1 │ UL   │     3 │    23 │       20 │  252 │   0 │      1 │   705 │  0 │       1 │ 30000 │
...
        

where the meaning of each column is explained in the Database schemas.

MAC Scheduling

The MAC scheduling tasks are performed by cuMAC, with full support for both UL and DL, HARQ and single-cell as well multi-cell jointly scheduling. The data flow for the scheduling process is illustrated in the following figure.

In each time slot, after the required input data gets passed to cuMAC, the following scheduler functions are executed serially on GPU:

• UE selection: UE down-selection using the SINR reported reported by the PHY layer,

• PRB allocation: PRB allocation for the selected UEs using the CFRs from the EM engine

• Layer selection: layer selection for each selected UE

• MCS selection: MCS selection for each of the selected UEs using the SINR reported from the PHY. An outer-loop link adaptation is employed to add a positive/negative offset to the reported SINR. The offset is tuned by the ACK/NACK result of the last scheduled transmission for the given UE.

The Aerial Omniverse​​ Digital Twin can be used to generate site-specific data to train machine learning models. After running a simulation, we can import simulation data from the ClickHouse database to train a model offline. More details of the data saved for a simulation is available in the appendix of this guide.

In order to speed up development workflows, the Aerial Omniverse Digital Twin can also be used to train models online, while the simulation is evolving. This is achieved by exposing Python bindings from the aodt_sim application. For each simulation time step, aodt_sim passes state, including UE position, speed, and channel data from the EM engine to Python code outside of the application. This allows the user to train a model using a machine learning framework of choice.

Example - training a channel predictor

To illustrate how to perform online training, we can use a minimal example to train a channel predictor based on the channel frequency responses (CFRs) computed by the EM engine. In subsequent releases, we will provide more examples to support training additional PHY/MAC components.

Channel aging is a well-known problem for reciprocal beamforming, especially for UEs moving with high speed. This is due to the difference between in the radio environment between when the channel is sounded and when the base station applies the beamforming weights.  One way to address this problem is to use a neural network to predict the channel when the beamforming weights are planned to be applied.

To train a neural network attempting to predict the channel, we can start by setting the following parameters in the Scenario stage widget.

• Scenario: 5 UEs and 1 RU

• Antenna Panels: 2 horizontal, 2 vertical elements, with dual polarization unchecked

• Batches: 250

• Slots per batch: 6

• Sample per slot: 1

• UE speed: min and max speeds set to 2.0 m/s

• Enable Training: checked

• Simulate RAN: unchecked

In this example, the channel predictor treats the channel from each RU and UE antenna pair independently, so we can optionally add more RUs, UEs, and antenna elements, resulting in more channels generated per batch.

Our neural network will estimate the channel 5 slots in advance. That is, given the channel at slot 0, it will predict the channel at slot 5. Thus, we set the slots per batch to 6. We set the number of batches to 250, which provides a good tradeoff between simulation time and achieving a reasonable training loss for this example. At each batch, the UEs are redropped.

Following the steps described in the EM mode, we can click Generate UEs and Start UE mobility to start the simulation. After the simulation finishes, the training and the validation losses are retrieved from the training_result table of the database and shown as part of the properties of Scenario. In the example, such losses are compared to the loss from a LMMSE filter attempting to perform the same action. Such loss appears in the graphical interface as baseline loss.

In the next section, we will go into further detail on how to train a more generic model.

Example - training our own model

In this section, we will discuss the Python API to train our own model using the Aerial Omniverse Digital Twin. As previously mentioned, the API exposes position information from the UE mobility model and channel information from the EM engine. Thus, it is possible to train any other model that relies on such data. The following discusses the minimum set of functions and data structures to consider when training any of such models.

Specifically, the aodt_sim application makes calls into the Python source code in the channel_predictor directory via Python bindings. The directory includes the following files.

            

            
|-- aodt_sim
|-- channel_predictor
|   |-- channel_predictor.py
|   |-- channel_predictor_bindings.cpython-310-x86_64-linux-gnu.so
|   |-- config.ini
|   |-- data_source.py
|   |-- plot_channels.py
|   |-- torch_utils.py
|   |-- train.py
|   |-- trainer.py
|   `-- weiner_filter.py

1 directory, 10 files
        

Only the Trainer class with member functions scenario and append_cfr in channel_predictor/trainer.py are required for the aodt_sim Python bindings, and must therefore be present in any user-modified Python code. The scenario function is called once at the beginning of a simulation, and the append_cfr function is called for every time step of the simulation. The rest of the files are local to the channel predictor example and do not interface with the aodt_sim application. The reader can refer to the Python docstrings in those files for further details. The user may substitute them with their own Python code.

            

            
class Trainer():
    """Class that manages training state"""
    def scenario(self, scenario_info, ru_ue_info):
    """Load scenario and initialize torch parameters

Args:
scenario_info (ScenarioInfo): Object containing information about the simulation scenario
ru_ue_info (RuUeInfo): Object containing information about RUs and UEs

Returns:
int: Return code if status was successful (=0) or not (<0)
"""
    def append_cfr(self, time_info, ru_assoc_infos, cfrs):
    """Append channel frequency response (CFR)

Args:
time_info (TimeInfo): Simulation time information including batch/slot/symbol
ru_assoc_infos (list(RuAssocInfo)): List of RU to UE association information
cfrs (numpy.ndarray): Numpy array of channel frequency response

Returns:
TrainingInfo: Result of training including information about number of iterations trained for and losses
"""
        

The following data structures are passed between aodt_sim and the Trainer class.

ScenarioInfo

RuUeInfo

TimeInfo

UeInfo

RuAssocInfo

CFRs

TrainingInfo

As previously mentioned, additional APIs to train RAN models will be added in subsequent releases.

* Consider a setup consisting of 4 RUs, 4 UEs, 4 ants per UE, 4 ants per RU. There will be 256 CFRs computed every time step of the simulation. The channel predictor considers each RU/UE antenna pair independently. If we configure prediction 6 slots in advance, then slots 0-4 will be spent accumulating data. Then for a training batch size of 16, there will be enough data to train 256 CFRs / 16 (training batch size) = 16 training iterations (16 forward/backward passes) on slot 5.