DeepMIMO v2 - Python

Table of Contents

DeepMIMO v2 Features

  • Includes all features of DeepMIMO v1

  • Optimized memory requirements and generation speed

  • Generates the channels between BSs and UEs

  • Generates the channels between BSs and BSs (enabling integrated access-backhaul, RIS, etc.)

  • Allows for multiple antennas at both the BSs and UEs

  • Allows for changing panel orientations at the BS and UEs

  • Allows for applying receiver filtering for more accurate channel generation 

  • Generates OFDM and time-domain channels

  • Outputs path parameters, path-loss, distances, among other possible outputs

  • Outputs transmitter/receiver locations

  • Available in Matlab, Octave, and Python

How Does it Work?

DeepMIMO v2 dataset generator processes the input ray-tracing file based on the parameters’ values specified in the DeepMIMO parameters file to generate the output dataset

 

Check the detailed documentation below for more information about the DeepMIMO v2 parameters and outputs

Download and Installation

Step 1: (Generator Package)

  • Install DeepMIMO package from pip by
				
					pip install DeepMIMO

Step 2: (Scenario)

  • Select and download a scenario from the scenarios page.
  • Extract scenario folder into a dataset folder.

Step 3: (Parameter Configuration and Dataset Generation)

  • Start a new python script as follows
				
					import DeepMIMO

# Load the default parameters
parameters = DeepMIMO.default_params() 

# Set scenario name
parameters['scenario'] = 'O1_60' 

# Set the main folder containing extracted scenarios
parameters['dataset_folder'] = r'C:\Users\xxx\Desktop\scenarios'

# Generate data
dataset = DeepMIMO.generate_data(parameters)
  • Configure the parameters (For details, please refer to the input/output parameters and examples below)
  • Run the code to generate the dataset!

Input Parameters

dataset_folder string


Folder of the unzipped scenarios. Inside the dataset folder, each scenario should have their own folder with the dataset files inside.

				
					# If the O1_60 scenario is extracted in "C:/dataset/" folder, set
parameters['dataset_folder'] = r'C:/dataset/'

# The default value is set as './Raytracing_scenarios/'

scenario string


Name of the scenario to be loaded. To check and download available scenarios, please check the scenarios page.

				
					# To load scenario O1_60, set the dictionary variable by
parameters['scenario'] = 'O1_60'

Dynamic scenario settings – first_scene, last_scene integers

 

[For dynamic scenarios] Determines the range of dynamic scenario scenes to be loaded [scene_first, scene_last]
				
					# To load the first five scenes, set
parameters['dynamic_settings']['first_scene'] = 1
parameters['dynamic_settings']['last_scene'] = 5

num_paths integer in [1, 25]

 

Maximum number of paths to be considered (a value between 1 and 25), e.g., choose 1 if you are only interested in the strongest path 

				
					# To only include 10 strongest paths in the channel computation, set
parameters['num_paths'] = 10

active_BS integer numpy array

 

The ID of the basestations to be included in the dataset. The basestation IDs can be selected from the scenario description. In the final dataset, the activated basestations IDs are renumbered in the same order starting from 1 to the number of active basestations.

				
					# To activate only the first basestation, set
parameters['active_BS'] = np.array([1])
				
			
				
					# To activate the basestations 1, 5, and 8, set
parameters['active_BS'] = np.array([1, 5, 8])

user_row_first, user_row_last integers

 

The range of rows are determined by these parameters. 

Specifically, the row of users with the ID in the range [user_row_first, user_row_last] are selected.

				
					# To activate the user rows 1-5, set
parameters['user_row_first'] = 1
parameters['user_row_last'] = 5

row_subsampling float in the range (0, 1]

 

This parameter determines the ratio of the rows to be activated within the interval [user_row_first, user_row_last].

Specifically, it randomly samples round(row_subsampling*(user_row_last-user_row_first)) rows within the given interval.

The value 1 activates all the rows within the interval.

				
					# To activate the half of the selected rows randomly, set
parameters['row_subsampling'] = 0.5

user_subsampling float in the range (0,1)

 

This parameter determines the ratio of the users to be activated within the active rows determined by the parameters row_subsampling, user_row_first and user_row_last. In each row, it allows random sampling of round(user_subsampling*number_of_users_in_row) users for activation.

The value 1 activates all the users within the active rows.

				
					# To activate the half of the users in each selected row randomly, set
parameters['user_subsampling'] = 0.5

User antenna – shape integer numpy array, spacing float, rotation float numpy array, radiation_pattern string

 

The user antenna parameters. shape is a 3-dimensional array of number of antenna elements in x-y-z dimensions. The antenna spacing between array elements is determined as (spacing x wavelength).

 

An antenna array (UPA) of (shape[0] x shape[1] x shape[2]) elements is adopted for each active UE. The axes of the antennas match the axes of the ray-tracing scenario.

 

If the rotation is defined, the antennas are rotated with the angles defined by rotation[0], rotation[1] and rotation[2] around the x-y-z axes from the initial orientation. For a uniformly random user rotation, define rotation by a 3×2 numpy matrix in the form of [[x_min, x_max], [y_min, y_max], [z_min, z_max]]. 

 

There are two available radiation pattern options:

  • ‘isotropic’ – This option does not apply any extra radiation gain to the ray-tracing scenario.
  • ‘halfwave-dipole’ – This option applies halfwave dipole antenna radiation pattern. To generate the same results with DeepMIMOv1 scenarios, use this option.

If the antenna pattern is not defined, it is set as ‘isotropic’.

				
					# To adopt a 4 element ULA in y direction, set
parameters['ue_antenna']['shape'] = np.array([1, 4, 1])
parameters['ue_antenna']['rotation'] = np.array([0, 0, 30]) # Rotate array 30 degrees around z-axis
				
			
				
					# To adopt a 4x2 UPA in y-z directions with spacing 0.5*wavelength, set
parameters['ue_antenna']['shape'] = np.array([1, 4, 2])
parameters['ue_antenna']['spacing'] = 0.5
				
			
				
					# To rotate UEs 30 degrees around z-axis, set
parameters['ue_antenna']['rotation'] = np.array([0, 0, 30]) # Rotate array 30 degrees in z-axis
				
			
				
					# To (uniformly) randomly rotate each UE 0-30, 30-60 and 60-90 degrees around x-y-z axes, set
parameters['ue_antenna']['rotation'] = np.array([[0, 30], [30, 60], [60, 90])
# After the dataset is generated, the rotation of UE i can be accessed at
parameters['ue_antenna']['rotation'][i]
				
			
				
					# To adopt an halfwave Dipole antenna pattern, set
parameters['ue_antenna']['radiation_pattern'] = 'halfwave-dipole'

Basestation antenna – shape integer numpy array, spacing float, rotation float numpy array,  radiation_pattern string

 

The basestation antenna parameters. shape is a 3-dimensional array of number of antenna elements in x-y-z dimensions. The antenna spacing between array elements is determined as (spacing x wavelength).

 

An antenna array (UPA) of (shape[0] x shape[1] x shape[2]) elements is adopted for each active BS. The axes of the antennas match the axes of the ray-tracing scenario.

 

If the rotation is defined, the antennas are rotated with the angles defined by rotation[0], rotation[1] and rotation[2] around the x-y-z axes from the initial orientation.

 

There are two available radiation pattern options:

  • ‘isotropic’ – This option does not apply any extra radiation gain to the ray-tracing scenario.
  • ‘halfwave-dipole’ – This option applies halfwave dipole antenna radiation pattern. To generate the same results with DeepMIMOv1 scenarios, apply this option.

If the antenna pattern is not defined, it is set as ‘isotropic’.

				
					# To adopt a 4 element ULA in y direction, set
parameters['bs_antenna']['shape'] = np.array([1, 4, 1])
				
			
				
					# To adopt a 4x2 UPA in y-z directions with spacing 0.5*wavelength, set
parameters['bs_antenna']['shape'] = np.array([1, 4, 2])
parameters['bs_antenna']['spacing'] = 0.5
				
			
				
					# To rotate BSs 30 degrees around z-axis, set
parameters['bs_antenna']['rotation'] = np.array([0, 0, 30]) # Rotate array 30 degrees in z-axis
				
			
				
					# To adopt an halfwave Dipole antenna pattern, set
parameters['ue_antenna']['radiation_pattern'] = 'halfwave-dipole'

If there are multiple active basestations, different antennas can be assigned to those by giving a list of antenna dictionaries as the input. For instance, the following example can be utilized with 3 BSs:

				
					# Consider 3 active basestations
parameters['active_BS'] = np.array([1, 5, 8])

# Define 3 different antennas:
antenna1 = {'shape': np.array([1, 1, 1]),
            'spacing': 0.5,
            'rotation': np.array([0, 30, 0])}
antenna2 = {'shape': np.array([1, 2, 2]),
            'spacing': 0.5,
            'rotation': np.array([-15, 0, 30])}
antenna3 = {'shape': np.array([1, 3, 4]),
            'spacing': 0.5,
            'rotation': np.array([-15, 0, 0])}
# Assign the defined antennas to the active basestations:
parameters['bs_antenna'] = [antenna1, antenna2, antenna3]

enable_BS2BS boolean

 

Enable (1) or disable (0) generation of the channels between basestations

				
					# To generate basestation to basestation output variables, set
parameters['enable_BS2BS'] = True

OFDM_channels boolean

 

(0) activate time domain (TD) channel impulse response generation for non-OFDM systems

(1) activate frequency domain (FD) channel generation for OFDM systems

				
					# For OFDM channels, set
parameters['activate_OFDM'] = 1
				
			
				
					# For time-domain channels, set
parameters['activate_OFDM'] = 0

OFDM – bandwidth float

Total bandwidth of the channel in GHz. 

				
					# To generate channels at 50 MHz bandwidth, set
parameters['OFDM']['bandwidth'] = 0.05

OFDM – subcarriers integer

 

Number of OFDM subcarriers

				
					# To generate OFDM channels with 256 subcarriers, set
parameters['OFDM']['subcarriers'] = 256

OFDM – subcarriers_limit, subcarriers_sampling integers

 

The constructed channels will be calculated only at the sampled subcarriers to reduce the size of the dataset. The first subcarriers_limit subcarriers are subsampled with OFDM_sampling_factor spacing between the selected consecutive subcarriers.

For subcarriers_limit = 64 and OFDM_sampling_factor = 8, the subcarriers {1, 9, 17, 26, 33, …} are subsampled from the available subcarriers {1, 2, …, 64}.

				
					# To sample first 64 subcarriers by 8 spacing between each, set
parameters['OFDM']['subcarriers_limit'] = 64
parameters['OFDM']['subcarriers_sampling'] = 8

OFDM – RX_filter boolean

 

The boolean options do the following:

(0) Applies no receive filter

(1) Activates ideal receive LPF: This option convolves channel paths with sinc at the time domain before taking FFT for the frequency domain conversion.

				
					# For an ideal LPF (rectangular in frequency domain and sinc in time domain), set
parameters['OFDM']['RX_filter'] = 1

Default Input Parameters

The default input parameters can be loaded in three different ways:

Load the default parameter dictionary using the python package:

				
					parameters = DeepMIMO.default_params()

Directly defining a dictionary of all the parameters:

Adding elements to a dictionary:

				
					parameters = { 'dataset_folder': './Raytracing_scenarios',
               'scenario': 'O1_60',
               'dynamic_settings': {'first_scene': 1, 'last_scene': 1},
               'num_paths': 5,
               'active_BS': np.array([1]),
               'user_row_first': 1,
               'user_row_last': 1,
               'row_subsampling': 1,
               'user_subsampling': 1,
               'bs_antenna': {'shape': np.array([1, 8, 4]),
                              'spacing': 0.5,
                              'radiation_pattern': 'isotropic'
                              },
               'ue_antenna': {'shape': np.array([1, 4, 2]),
                              'spacing': 0.5,
                              'radiation_pattern': 'isotropic'
                              },
               'enable_BS2BS': 1,
               'OFDM_channels': 1,
               'OFDM': {'subcarriers': 512,
                        'subcarriers_limit': 64,
                        'subcarriers_sampling': 1,
                        'bandwidth': 0.05,
                        'RX_filter': 0
                        }
               }
				
			
				
					parameters = {}
parameters['dynamic_settings'] = {}
parameters['OFDM'] = {}
parameters['bs_antenna'] = {}
parameters['ue_antenna'] = {}

parameters['dataset_folder'] = './Raytracing_scenarios'
parameters['scenario'] = 'O1_60'
parameters['dynamic_settings']['first_scene'] = 1
parameters['dynamic_settings']['last_scene'] = 1

parameters['num_paths'] = 5
parameters['active_BS'] = np.array([1])
parameters['user_row_first'] = 1
parameters['user_row_last'] = 1
parameters['row_subsampling'] = 1
parameters['user_subsampling'] = 1

parameters['bs_antenna']['shape'] = np.array([1, 8, 4])
parameters['bs_antenna']['spacing'] = 0.5
# parameters['bs_antenna']['rotation'] = np.array([0, 0, 0])
parameters['bs_antenna']['radiation_pattern'] = 'isotropic'

parameters['ue_antenna']['shape'] = np.array([1, 4, 2])
parameters['ue_antenna']['spacing'] = 0.5
# parameters['ue_antenna']['rotation'] = np.array([0, 0, 0])
parameters['ue_antenna']['radiation_pattern'] = 'isotropic'

parameters['enable_BS2BS'] = 1

parameters['OFDM_channels'] = 1 # Frequency (OFDM) or time domain channels
parameters['OFDM']['subcarriers'] = 512
parameters['OFDM']['subcarriers_limit'] = 64
parameters['OFDM']['subcarriers_sampling'] = 1
parameters['OFDM']['bandwidth'] = 0.05
parameters['OFDM']['RX_filter'] = 0

Output Parameters

Examples

How Are the Channels Generated?

The following report provides a detailed formulation on the DeepMIMO v2 channel generation process

DeepMIMOv2 Channel Generation Report

The detailed formulation of the channel generation process in the DeepMIMO v2 dataset

DeepMIMOv2_Channel_Construction_v20_viewer

Built By

Umut Demirhan, Abdelrahman Taha, Ahmed Alkhateeb

Supported by

The DeepMIMO Dataset

GitHub Repositories

DeepMIMO v2

DeepMIMO 5G NR

Ray-tracing Scenarios

Machine Learning Applications

Forum

Send Feedback/Question

© 2024 by the Wireless Intelligence Lab