Skip to content

DeepMIMO Specs

This specifies how each DeepMIMO version organizes files.

DeepMIMOv4 Spec

Note: V4 introduces matrix-based storage which significantly improves data loading performance. Instead of loading data user by user, entire matrices can be loaded at once, making operations orders of magnitude faster.

The scenario name is determined solely by the folder name containing the dataset (e.g., O1_28, I2_60, etc.).

Primary Matrices

Matrix files follow the pattern: {matrix_name}_{code}.mat where code is t{set_id}_tx{tx_id}_r{rx_set_id}. Example with 3 BSs and 1 user grid: - BS-UE matrices (rx_set_id = 000 for user grid): 

delay_t001_tx000_r000.mat  # TX Set 1, BS 0 to RX Set 1 (users)
delay_t001_tx001_r000.mat  # TX Set 1, BS 1 to RX Set 1 (users)
delay_t001_tx002_r000.mat  # TX Set 1, BS 2 to RX Set 1 (users)
- BS-BS matrices (rx_set_id = 001 for BS set): 
delay_t001_tx000_r001.mat  # TX Set 1, BS 0 to RX Set 1 (BSs)
delay_t001_tx001_r001.mat  # TX Set 1, BS 2 to RX Set 1 (BSs)
delay_t001_tx002_r001.mat  # TX Set 1, BS 1 to RX Set 1 (BSs)

Access pattern: 

dataset = dm.load(<scen_name>)

To simplify the notation, the table below considers d = dataset[scene][tx] Note 1: both d.aoa_az and d['aoa_az'] syntax work Note 2: static scenarios (single scene) do not need scene indexing. Similarly for single-tx scenarios.

File Name Dataset Attribute Dimensions Type Description
rx_loc_{code}.mat d.rx_loc N × 3 float32 XYZ coordinates of receiver locations
tx_loc_{code}.mat d.tx_loc 1 × 3 float32 XYZ coordinates of transmitter location
aoa_az_{code}.mat d.aoa_az N × MAX_PATHS float32 Azimuth angle of arrival
aod_az_{code}.mat d.aod_az N × MAX_PATHS float32 Azimuth angle of departure
aoa_el_{code}.mat d.aoa_el N × MAX_PATHS float32 Elevation angle of arrival
aod_el_{code}.mat d.aod_el N × MAX_PATHS float32 Elevation angle of departure
toa_{code}.mat d.toa N × MAX_PATHS float32 Time of arrival
phase_{code}.mat d.phase N × MAX_PATHS float32 Phase of each path
power_{code}.mat d.power N × MAX_PATHS float32 Power of each path
inter_{code}.mat d.inter N × MAX_PATHS int32 Interaction type codes*
inter_loc_{code}.mat d.inter_loc N × MAX_PATHS × MAX_INTER × 3 float32 Interaction point locations
vertices_{code}.mat d.vertices N_vert × 3 float32 XYZ coordinates of vertices

*Interaction codes: - 0: Line of Sight (LoS) - 1: Single reflection - 2: Diffraction - 3: Scattering - 4: Transmission - Example: 21 = Tx - Diffraction - Reflection - Rx

The dimensions are: - N - number of users - MAX_PATHS - maximum number of paths DeepMIMO extracts from the ray tracing simulation, varies per scenario - MAX_INTER - maximum number of interactions along one path. The main limitation on this parameter is ray tracing software, which usually stops at 5 or less.

JSON Files

File Name Description
objects.json Contains scene object metadata including: name, label, id, face_vertex_idxs (indices into vertices.mat), face_material_idxs (indices of the materials in each face)
params.json Ray tracing parameters including: raytracer info, frequency, max_path_depth, interaction settings (reflections, diffractions, scattering, transmissions), ray casting settings, GPS bounding box, materials, and many raw parameters from the ray tracer that should be sufficient to reproduce the simulation.

Secondary (Computed) Matrices

Dataset Attribute Dimensions Type Description
dataset[scene][tx]['chs'] N_RX_ant × N_TX_ant × N_subcarriers complex64 Channel matrices
dataset[scene][tx]['distances'] N × 1 float32 TX-RX distances
dataset[scene][tx]['pathloss'] N × 1 float32 Path loss values

Computed matrices are continuously added for convenience of operations. Check dm.info() for a complete list.

Design Principles

  1. Data Efficiency
  2. Eliminate redundant information storage
  3. Use efficient data structures and formats
  4. Implement lazy evaluation and caching where possible

  5. Pre-allocate memory to avoid unnecessary copies

  6. Consistency

  7. Maintain constant antenna configurations across TX/RX
  8. Preserve fundamental information (angles, phases, etc.)

  9. Flatten single-element lists to reduce nesting

  10. User Experience

  11. Provide transparent access regardless of ray tracer backend
  12. Ensure consistent API across different dataset versions
  13. Low code access to fundamental matrices

  14. Support efficient batch operations

  15. Performance Considerations

  16. GPU acceleration support (optional, via cuPy - yet to implement)

  17. Efficient batch processing for channel computations

  18. Transparency and Accessibility

  19. Direct matrix storage with intuitive dimensions for immediate use
  20. Human-readable JSON files for parameters and metadata
  21. No proprietary parsing required unlike previous versions
  22. Open format that simplifies data conversion and interpretation
  23. Standardized matrix organization that's self-documenting

DeepMIMOv3 Spec

File Structure

N+1 files total, where N = number of RX-TX pairs enabled: - N data files: One per RX-TX pair - 1 params file: params.mat

Example file names: - BS1_BS.mat - For base station to base station paths (BS-BS communication) - BS3_UE_0-1024.mat - For base station 3 to users 0-1024 (BS-UE communication)

Primary Matrices

Access patterns: 

paths_user_u = dataset[scene][tx_id]['user']['paths'][u]  # For BS-UE communication
paths_bs_b = dataset[scene][tx_id]['bs']['paths'][b]      # For BS-BS communication

File Name Dataset Attribute Dimensions Type Description
BS{i}_BS.mat
or
BS{i}_UE_{range}.mat		 paths_user_u['AoA_phi'] num_paths × 1 float32 Azimuth angle of arrival
paths_user_u['AoA_theta'] num_paths × 1 float32 Elevation angle of arrival
paths_user_u['DoD_phi'] num_paths × 1 float32 Azimuth angle of departure
paths_user_u['DoD_theta'] num_paths × 1 float32 Elevation angle of departure
paths_user_u['ToA'] num_paths × 1 float32 Time of arrival
paths_user_u['phase'] num_paths × 1 float32 Phase of each path
paths_user_u['power'] num_paths × 1 float32 Power of each path
paths_user_u['num_paths'] 1 int32 Number of paths

*Note: x,y,z coordinates can be lat,long,alt when scenarios come from OSM

DeepMIMOv2 Spec

Code format: {code} = {scenario}.{bs} where scenario is the environment name (e.g., O1) and bs is the base station ID (e.g., 3p4.1)

Primary Matrices

Access patterns: 

users_dataset = dataset[scene][tx_id]['user']  # For BS-UE communication
bs_dataset = dataset[scene][tx_id]['bs']       # For BS-BS communication

Note: Matrix dimensions are specified in {scenario}.params.mat, which contains carrier frequency, number of BSs, transmit power, and user grid information. While there are as many angles as max paths (usually 10) and users in the grid, the matrix is flattened and needs to be parsed per user based on path loss information.

Example file names: - {code}.CIR.mat - Channel impulse response for user data - {code}.CIR.BSBS.mat - Channel impulse response for BS-BS data - {code}.DoA.mat - Direction of arrival for user data

File Name Dataset Attribute Type Description
{code}.CIR.mat users_dataset['channel'] complex64 Channel impulse response matrices
{code}.CIR.BSBS.mat bs_dataset['channel'] complex64 BS-BS channel impulse response matrices
{code}.DoA.mat users_dataset['paths'][u]['DoA'] float32 Angle of arrival information
{code}.DoA.BSBS.mat bs_dataset['DoA'] float32 BS-BS angle of arrival information
{code}.DoD.mat users_dataset['paths'][u]['DoD'] float32 Angle of departure information
{code}.DoD.BSBS.mat bs_dataset['DoD'] float32 BS-BS angle of departure information
{code}.LoS.mat paths_user_u['LoS'] int32 Line of sight information
{code}.LoS.BSBS.mat bs_dataset['LoS'] int32 BS-BS line of sight information
{code}.PL.mat paths_user_u['PL'] float32 Path loss values
{code}.PL.BSBS.mat bs_dataset['PL'] float32 BS-BS path loss values

Design Principles

  1. Data Efficiency
  2. Eliminate redundant information storage
  3. Use efficient data structures and formats
  4. Implement lazy evaluation and caching where possible

  5. Pre-allocate memory to avoid unnecessary copies

  6. Consistency

  7. Maintain constant antenna configurations across TX/RX
  8. Preserve fundamental information (angles, phases, etc.)

  9. Flatten single-element lists to reduce nesting

  10. User Experience

  11. Provide transparent access regardless of ray tracer backend
  12. Ensure consistent API across different dataset versions
  13. Low code access to fundamental matrices

  14. Support efficient batch operations

  15. Performance Considerations

  16. GPU acceleration support (optional, via cuPy - yet to implement)

  17. Efficient batch processing for channel computations

  18. Transparency and Accessibility

  19. Direct matrix storage with intuitive dimensions for immediate use
  20. Human-readable JSON files for parameters and metadata
  21. No proprietary parsing required unlike previous versions
  22. Open format that simplifies data conversion and interpretation
  23. Standardized matrix organization that's self-documenting