DeepMIMO v3 - Python
Table of Contents
DeepMIMO v3 Features
Includes all features of DeepMIMO v1 and v2
Optimized memory requirements and generation speed
Antenna panel orientation and field of view
- Dual polar antenna (when available in the scenario)
Addition of the Doppler shift for dynamic scenarios
Faster and more efficient data structure
Available in Matlab & 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 – dynamic_scenario_scenes numpy array
[For dynamic scenarios] Determines the dynamic scenario scenes to be loaded.
# To load the first five scenes, set
parameters['dynamic_scenario_scenes'] = np.arange(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_rows numpy array
The rows of users to be generated.
Specifically, the row of users in the given array are selected.
# To activate the user rows 1-5, set
parameters['user_rows'] = np.arange(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, FoV float numpy array, radiation_pattern string
The user antenna parameters. shape is a 2-dimensional array of number of antenna elements in horizontal-vertical dimensions. The antenna spacing between array elements is determined as (spacing x wavelength).
An antenna array (UPA) of (shape[0] x shape[1]) elements is adopted for each active UE. With no rotation ([0, 0, 0]), the antenna array is directed towards +x lying on the y axis.
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]].
The FoV parameter allows to adjust field of view of in horizontal and vertical directions. Specifically, the antenna’s horizontal and vertical field of views are limited to FoV[0] and FoV[1] degrees.
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 with 120 degrees horizontal 180 degrees vertical FoV, set
parameters['ue_antenna']['shape'] = np.array([4, 1])
parameters['ue_antenna']['rotation'] = np.array([0, 0, 30]) # Rotate array 30 degrees around z-axis
parameters['ue_antenna']['FoV'] = np.array([120, 180])
# To adopt a 4x2 UPA in y-z directions with spacing 0.5*wavelength, set
parameters['ue_antenna']['shape'] = np.array([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, FoV float numpy array, radiation_pattern string
The basestation antenna parameters. shape is a 2-dimensional array of number of antenna elements in horizontal-vertical dimensions. The antenna spacing between array elements is determined as (spacing x wavelength).
An antenna array (UPA) of (shape[0] x shape[1]) elements is adopted for each active BS. An antenna array (UPA) of (shape[0] x shape[1]) elements is adopted for each active UE. With no rotation ([0, 0, 0]), the antenna array is directed towards +x lying on the y axis.
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.
The FoV parameter allows to adjust field of view of in horizontal and vertical directions. Specifically, the antenna’s horizontal and vertical field of views are limited to FoV[0] and FoV[1] degrees.
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’.2horizontal-vertical
# To adopt a 4 element ULA in y direction, set
parameters['bs_antenna']['shape'] = np.array([4, 1])
# To adopt a 4x2 UPA in y-z directions with spacing 0.5*wavelength, set
parameters['bs_antenna']['shape'] = np.array([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]),
'spacing': 0.5,
'rotation': np.array([0, 30, 0])}
antenna2 = {'shape': np.array([2, 2]),
'spacing': 0.5,
'rotation': np.array([-15, 0, 30])}
antenna3 = {'shape': np.array([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 – selected_subcarriers numpy array of integers
The constructed channels will be calculated only at the sampled subcarriers to reduce the size of the dataset. Only the subcarriers corresponding to the indices in selected_subcarriers will be generated.
For selected_subcarriers=np.array([0, 8, 16, 24, 32]) , the subcarriers {0, 8, 16, 24, 32} are subsampled from the available subcarriers {1, 2, …, num_OFDM}.
# To sample first 64 subcarriers by 8 spacing between each, set
parameters['OFDM']['selected_subcarriers'] = np.arange(0, 64, 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
Output Variables of Basestation i – User j
Channel Matrix
dataset[i]['user']['channel'][j]
Type and Dimensions: Float matrix of size (number of RX antennas) x (number of TX antennas) x (number of OFDM subcarriers)
Description: The channel matrix between basestation i and user j. Each of the first two dimensions follows a certain reshaping sequence that can be obtained using the following function:
antennamap = DeepMIMO.ant_indices(parameters['ue_antenna']['shape'])
# or
antennamap = DeepMIMO.ant_indices(np.array([x, y, z]))
Returns a matrix antennamap; each column in the matrix has 3 integers in the form of ‘x y z’ representing the antenna index of the channel element in the x, y, z directions.
Note: The DeepMIMO generator does not apply an array based normalization for the power. The details on the channel generation can be found in the channel generation document at the bottom of this page.
Ray-tracing Path Parameters
dataset[i]['user']['paths'][j]
Type and Dimensions: Dictionary
Description: The parameters of the ray tracing is provided within the dictionary. Specifically, for each path
- Azimuth and zenith angle-of-arrivals – degrees (DoA_phi, DoA_theta)
- Azimuth and zenith angle-of-departure – degrees (DoD_phi, DoD_theta)
- Time of arrival – seconds (ToA)
- Phase – degrees (phase)
- Power – watts (power)
- Number of paths (num_paths)
are provided in this dictionary.
Line-of-Sight Status
dataset[i]['user']['LoS'][j]
Type and Dimensions: Integer of values {-1, 0, 1}
Description: The variable that indicates the existence of the LOS path in the channel.
The values correspond to
(1): The LoS path exists.
(0): Only NLoS paths exist. The LoS path is blocked (LoS blockage).
(-1): No paths exist between the transmitter and the receiver (Full blockage).
TX-RX Distance
dataset[i]['user']['distance'][j]
Type and Dimensions: Float
Description: The Euclidian distance between the RX and TX locations in meters.
Path loss
dataset[i]['user']['pathloss'][j]
Type and Dimensions: Float
Description: The combined path-loss of the channel between the RX and TX in dB.
User Location
dataset[i]['user']['location'][j]
Type and Dimensions: Float array of 3 dimensions
Description: The Euclidian location of the user in the form of [x, y, z].
Basestation Location
dataset[i]['location']
Type and Dimensions: Float array of 3 dimensions
Description: The Euclidian location of the user in the form of [x, y, z].
Output Variables of Basestation i – User j at Scene s
Channel Matrix
dataset[s][i]['user']['channel'][j]
Type and Dimensions: Float matrix of size (number of RX antennas) x (number of TX antennas) x (number of OFDM subcarriers)
Description: The channel matrix between basestation i and user j. Each of the first two dimensions follows a certain reshaping sequence that can be obtained using the following function:
antennamap = DeepMIMO.ant_indices(parameters['ue_antenna']['shape'])
# or
antennamap = DeepMIMO.ant_indices(np.array([x, y, z]))
Returns a matrix antennamap; each column in the matrix has 3 integers in the form of ‘x y z’ representing the antenna index of the channel element in the x, y, z directions.
Note: The DeepMIMO generator does not apply an array based normalization for the power. The details on the channel generation can be found in the channel generation document at the bottom of this page.
Ray-tracing Path Parameters
dataset[s][i]['user']['paths'][j]
Type and Dimensions: Dictionary
Description: The parameters of the ray tracing is provided within the dictionary. Specifically, for each path
- Azimuth and zenith angle-of-arrivals – degrees (DoA_phi, DoA_theta)
- Azimuth and zenith angle-of-departure – degrees (DoD_phi, DoD_theta)
- Time of arrival – seconds (ToA)
- Phase – degrees (phase)
- Power – watts (power)
- Number of paths (num_paths)
are provided in this dictionary.
Line-of-Sight Status
dataset[s][i]['user']['LoS'][j]
Type and Dimensions: Integer of values {-1, 0, 1}
Description: The variable that indicates the existence of the LOS path in the channel.
The values correspond to
(1): The LoS path exists.
(0): Only NLoS paths exist. The LoS path is blocked (LoS blockage).
(-1): No paths exist between the transmitter and the receiver (Full blockage).
TX-RX Distance
dataset[s][i]['user']['distance'][j]
Type and Dimensions: Float
Description: The Euclidian distance between the RX and TX locations in meters.
Path loss
dataset[s][i]['user']['pathloss'][j]
Type and Dimensions: Float
Description: The combined path-loss of the channel between the RX and TX in dB.
User Location
dataset[s][i]['user']['location'][j]
Type and Dimensions: Float array of 3 dimensions
Description: The Euclidian location of the user in the form of [x, y, z].
Basestation Location
dataset[s][i]['location']
Type and Dimensions: Float array of 3 dimensions
Description: The Euclidian location of the user in the form of [x, y, z].
Output Variables of Basestation i – Basestation j
Channel Matrix
dataset[i]['basestation']['channel'][j]
Type and Dimensions: Float matrix of size (number of RX antennas) x (number of TX antennas) x (number of OFDM subcarriers)
Description: The channel matrix between basestation i and basestation j. Each of the first two dimensions follows a certain reshaping sequence that can be obtained using the following function:
antennamap = DeepMIMO.ant_indices(parameters['bs_antenna']['shape'])
# or
antennamap = DeepMIMO.ant_indices(np.array([x, y, z]))
Returns a matrix antennamap; each column in the matrix has 3 integers in the form of ‘x y z’ representing the antenna index of the channel element in the x, y, z directions.
Note: The DeepMIMO generator does not apply an array based normalization for the power. The details on the channel generation can be found in the channel generation document at the bottom of this page.
Ray-tracing Path Parameters
dataset[i]['basestation']['paths'][j]
Type and Dimensions: Dictionary
Description: The parameters of the ray tracing is provided within the dictionary. Specifically, for each path
- Azimuth and zenith angle-of-arrivals – degrees (DoA_phi, DoA_theta)
- Azimuth and zenith angle-of-departure – degrees (DoD_phi, DoD_theta)
- Time of arrival – seconds (ToA)
- Phase – degrees (phase)
- Power – watts (power)
- Number of paths (num_paths)
are provided in this dictionary.
Line-of-Sight Status
dataset[i]['basestation']['LoS'][j]
Type and Dimensions: Integer of values {-1, 0, 1}
Description: The variable that indicates the existence of the LOS path in the channel.
The values correspond to
(1): The LoS path exists.
(0): Only NLoS paths exist. The LoS path is blocked (LoS blockage).
(-1): No paths exist between the transmitter and the receiver (Full blockage).
TX-RX Distance
dataset[i]['basestation']['distance'][j]
Type and Dimensions: Float
Description: The Euclidian distance between the RX and TX locations in meters.
Path loss
dataset[i]['basestation']['pathloss'][j]
Type and Dimensions: Float
Description: The combined path-loss of the channel between the RX and TX in dB.
RX Basestation Location
dataset[i]['basestation']['location'][j]
Type and Dimensions: Float array of 3 dimensions
Description: The Euclidian location of the receive basestation j in the form of [x, y, z].
TX Basestation Location
dataset[i]['location']
Type and Dimensions: Float array of 3 dimensions
Description: The Euclidian location of the transmit basestation i in the form of [x, y, z].
Output Variables of Basestation i – Basestation j at Scene s
Channel Matrix
dataset[s][i]['basestation']['channel'][j]
Type and Dimensions: Float matrix of size (number of RX antennas) x (number of TX antennas) x (number of OFDM subcarriers)
Description: The channel matrix between basestation i and basestation j. Each of the first two dimensions follows a certain reshaping sequence that can be obtained using the following function:
antennamap = DeepMIMO.ant_indices(parameters['bs_antenna']['shape'])
# or
antennamap = DeepMIMO.ant_indices(np.array([x, y, z]))
Returns a matrix antennamap; each column in the matrix has 3 integers in the form of ‘x y z’ representing the antenna index of the channel element in the x, y, z directions.
Note: The DeepMIMO generator does not apply an array based normalization for the power. The details on the channel generation can be found in the channel generation document at the bottom of this page.
Ray-tracing Path Parameters
dataset[s][i]['basestation']['paths'][j]
Type and Dimensions: Dictionary
Description: The parameters of the ray tracing is provided within the dictionary. Specifically, for each path
- Azimuth and zenith angle-of-arrivals – degrees (DoA_phi, DoA_theta)
- Azimuth and zenith angle-of-departure – degrees (DoD_phi, DoD_theta)
- Time of arrival – seconds (ToA)
- Phase – degrees (phase)
- Power – watts (power)
- Number of paths (num_paths)
are provided in this dictionary.
Line-of-Sight Status
dataset[s][i]['basestation']['LoS'][j]
Type and Dimensions: Integer of values {-1, 0, 1}
Description: The variable that indicates the existence of the LOS path in the channel.
The values correspond to
(1): The LoS path exists.
(0): Only NLoS paths exist. The LoS path is blocked (LoS blockage).
(-1): No paths exist between the transmitter and the receiver (Full blockage).
TX-RX Distance
dataset[s][i]['basestation']['distance'][j]
Type and Dimensions: Float
Description: The Euclidian distance between the RX and TX locations in meters.
Path loss
dataset[s][i]['basestation']['pathloss'][j]
Type and Dimensions: Float
Description: The combined path-loss of the channel between the RX and TX in dB.
RX Basestation Location
dataset[s][i]['basestation']['location'][j]
Type and Dimensions: Float array of 3 dimensions
Description: The Euclidian location of the receive basestation j in the form of [x, y, z].
TX Basestation Location
dataset[s][i]['location']
Type and Dimensions: Float array of 3 dimensions
Description: The Euclidian location of the transmit basestation i in the form of [x, y, z].
Examples
How Are the Channels Generated?
The following report provides a detailed formulation on the DeepMIMO v2 channel generation process
The detailed formulation of the channel generation process in the DeepMIMO v2 dataset
