Converter

The converter module provides functionality to automatically detect and convert raytracing data from various supported formats into a standardized DeepMIMO format.

converters/
  ├── converter.py (Main converter)
  ├── converter_utils.py (Helper functions)
  ├── aodt/ (AODT format)
  │   └── aodt_converter.py
  ├── sionna_rt/ (Sionna RT format)
  │   └── sionna_converter.py
  └── wireless_insite/ (Wireless InSite format)
      └── insite_converter.py

Create a standardized scenario from raytracing data.

This function automatically detects the raytracing data format based on file extensions and uses the appropriate converter to generate a standardized scenario. It supports AODT, Sionna RT, and Wireless Insite formats. It will check both the root directory and immediate subdirectories for the required files.

Parameters:

Name	Type	Description	Default
path_to_rt_folder	str	Path to the folder containing raytracing data. If the folder contains multiple scenes, the function will sort them with sorted() and convert each folder to a time snapshot.	required
**conversion_params	dict[str, Any]	Additional parameters for the conversion process	{}

Returns:

Type	Description
str | None	Optional[Any]: Scenario object if conversion is successful, None otherwise

import deepmimo as dm

# Convert raytracing data
scenario = dm.convert(
    path_to_rt_folder,  # Path to raytracing data
    **conversion_params  # Additional parameters
)

Conversion Process:

1. Format Detection

   # Automatic format detection based on file extensions (internal logic)
   if '.aodt' in files:
       converter = aodt_rt_converter
   elif '.pkl' in files:
       converter = sionna_rt_converter
   elif '.setup' in files:
       converter = insite_rt_converter
   

2. Read Ray Tracing Parameters

3. Read TXRX Configuration
4. Read Paths
5. Save DeepMIMO Core Matrices
6. Read Materials
7. Read Scene Objects
8. Save vertices.mat and objects.json
9. Save params.json

Use the auto converter

Always let the auto converter pick the right converter based on folder contents. Your parameters must match one of the converters below.

Wireless InSite

from deepmimo.converters import insite_rt_converter

# Convert Wireless InSite project
scenario = insite_rt_converter('path/to/insite_project')

# Required files:
# - <scen_name>.setup (Project setup)
# - <scen_name>.txrx (Project setup)
# - <scen_name>.xml (Project setup)
# - <p2m_folder>/*.paths (Ray paths)
# - <p2m_folder>/*.pl (Pathloss files)

Wireless InSite example

See the Conversion From Wireless InSite section in the manual for an end-to-end example.

Convert Wireless InSite ray-tracing data to DeepMIMO format.

This function handles the conversion of Wireless InSite ray-tracing simulation data into the DeepMIMO dataset format. It processes path files (.p2m), setup files, and transmitter/receiver configurations to generate channel matrices and metadata.

Parameters:

Name	Type	Description	Default
rt_folder	str	Path to folder containing .setup, .txrx, and material files.	required
copy_source	bool	Whether to copy ray-tracing source files to output.	False
overwrite	Optional[bool]	Whether to overwrite existing files. Prompts if None.	None
vis_scene	bool	Whether to visualize the scene layout. Defaults to False.	True
scenario_name	str	Custom name for output folder. Uses p2m folder name if empty.	''
print_params	bool	Whether to print the parameters to the console. Defaults to False.	True
parent_folder	str	Name of parent folder containing the scenario. If empty, the scenario is saved in the DeepMIMO scenarios folder. This parameter is only used if the scenario is time-varying.	''
num_scenes	int	Number of scenes in the scenario. Defaults to 1. This parameter is only used if the scenario is time-varying.	1

Returns:

Name	Type	Description
str	str	Path to output folder containing converted DeepMIMO dataset.

Raises:

Type	Description
FileNotFoundError	If required input files are missing.
ValueError	If transmitter or receiver IDs are invalid.

Sionna RT

Conversion from Sionna involves 2 steps: 1. Exporting: Since Sionna RT does not save files, we must save them. 2. Converting: Use the saved files to create a DeepMIMO scenario.

Exporting

from deepmimo.exporters import sionna_exporter

sionna_save_folder = 'sionna_test_scen/'

sionna_exporter(
   scene,
   path_list,
   my_compute_path_params,
   save_folder=sionna_save_folder
)

Export a complete Sionna simulation to a format that can be converted by DeepMIMO.

This function exports all necessary data from a Sionna ray tracing simulation to files that can be converted into the DeepMIMO format. The exported data includes: - Ray paths and their properties - Scene materials and their properties - Ray tracing parameters used in the simulation - Scene geometry (vertices and objects)

Parameters:

Name	Type	Description	Default
scene	Scene	Sionna Scene containing the simulation environment.	required
path_list	list[Paths] | Paths	Ray paths from Sionna's ray tracer (single or multi TX).	required
my_compute_path_params	dict	Parameters passed to compute_paths (Sionna does not persist them internally).	required
save_folder	str	Directory to write the exported files.	required

Notes

• Tested with Sionna v0.19.1 and v1.0.2.
• In Sionna 1.x, paths are exported during RT, so they may already be serialized.

Converting

from deepmimo.converters import sionna_rt_converter
# Convert Sionna RT data
scenario = sionna_rt_converter(sionna_save_folder)

# Required files:
# - *.pkl (Scene data)

Sionna RT example

See the Conversion From Sionna RT section in the manual for an example (Sionna 1.0 support coming May 2025).

Convert Sionna ray-tracing data to DeepMIMO format.

This function handles the conversion of Sionna ray-tracing simulation data into the DeepMIMO dataset format. It processes path data, setup files, and transmitter/receiver configurations to generate channel matrices and metadata.

Parameters:

Name	Type	Description	Default
rt_folder	str	Path to folder containing Sionna ray-tracing data.	required
copy_source	bool	Whether to copy ray-tracing source files to output.	False
overwrite	bool	Whether to overwrite existing files. Prompts if None. Defaults to None.	None
vis_scene	bool	Whether to visualize the scene layout. Defaults to False.	True
scenario_name	str	Custom name for output folder. Uses rt folder name if empty.	''
print_params	bool	Whether to print the parameters to the console. Defaults to False.	False
parent_folder	str	Name of parent folder containing the scenario. If empty, the scenario is saved in the DeepMIMO scenarios folder. This parameter is only used if the scenario is time-varying.	''
num_scenes	int	Number of scenes in the scenario. Defaults to 1. This parameter is only used if the scenario is time-varying.	1

Returns:

Name	Type	Description
str	str	Path to output folder containing converted DeepMIMO dataset.

Raises:

Type	Description
FileNotFoundError	If required input files are missing.
ValueError	If transmitter or receiver IDs are invalid.

AODT

Conversion from AODT (Aerial Optical Digital Twin) involves 2 steps: 1. Exporting: Export data from the AODT database to parquet files. This must be executed in a place with access to the clickhouse database used to store simulation results. In case of AODT On the Cloud, this should run in the jupyter notebook tab. 2. Converting: Convert the exported parquet files to DeepMIMO format. This can be executed either along side the export code, or any place with access to the exported parquet files. For example, we can export the files on the cloud, zip them, download them, and convert them locally.

Dependencies

AODT support requires additional dependencies. Install them using:

pip install --pre deepmimo[aodt]

Exporting

from clickhouse_driver import Client
from deepmimo.exporters import aodt_exporter

# Connect to AODT database
db_client = Client('clickhouse')

# Export database to parquet files
aodt_rt_folder = aodt_exporter(
    db_client,
    database='',  # Uses first available database if empty
    output_dir='.'  # Directory to save parquet files
)

Export a database to parquet files.

Parameters:

Name	Type	Description	Default
client	Client	Clickhouse client instance	required
database	str	Database name to export. If empty, uses first available database.	''
output_dir	str	Directory to save parquet files. Defaults to current directory.	'.'
ignore_tables	list[str]	List of tables to ignore. Defaults to EXCEPT_TABLES.	EXCEPT_TABLES

Returns:

Name	Type	Description
str	str	Path to the directory containing the exported files.

Converting

from deepmimo.converters import aodt_rt_converter

# Convert AODT data
scenario = aodt_rt_converter(aodt_rt_folder)

# Required files:
# - scenario.parquet (Scenario parameters)
# - raypaths.parquet (Ray paths and interactions)
# - cirs.parquet (Channel information)
# - rus.parquet, ues.parquet (TX/RX configurations)
# - materials.parquet (Material properties)
# - patterns.parquet (Antenna patterns)
# - time_info.parquet (Time information)

Convert AODT ray-tracing data to DeepMIMO format.

This function handles the conversion of AODT ray-tracing simulation data into the DeepMIMO dataset format. It processes parquet files containing path data, scenario parameters, and transmitter/receiver configurations.

Parameters:

Name	Type	Description	Default
rt_folder	str	Path to folder containing AODT parquet files.	required
copy_source	bool	Whether to copy ray-tracing source files to output.	False
overwrite	Optional[bool]	Whether to overwrite existing files. Prompts if None.	None
vis_scene	bool	Whether to visualize the scene layout. Defaults to True.	True
scenario_name	str	Custom name for output folder. Uses folder name if empty.	''
print_params	bool	Whether to print parameters to console. Defaults to True.	True
parent_folder	str	Parent folder for time-varying scenarios. Defaults to empty.	''
num_scenes	int	Number of scenes in time-varying scenario. Defaults to 1.	1

Returns:

Name	Type	Description
str	str	Path to output folder containing converted DeepMIMO dataset.

Raises:

Type	Description
FileNotFoundError	If required parquet files are missing.
ValueError	If transmitter or receiver IDs are invalid.