Database¶

DeepMIMO API leverages a database which is globally available and provides an excellent distribution network for both uploads and downloads worldwide.

Search¶

The search functionality allows you to find scenarios in the DeepMIMO database based on various parameters.

import deepmimo as dm

# Define search parameters
query = {
    'bands': ['sub6', 'mmW'],
    'environment': 'outdoor',
    'numRx': {'min': 10e3, 'max': 10e5}
}

# Perform search
scenarios = dm.search(query)  # returns ['scenario1', 'scenario2', ...]

# Can be used later to download scenarios systematically
for scenario in scenarios:
    dm.download(scenario)

Search for scenarios in the DeepMIMO database.

Parameters:

Name	Type	Description	Default
`query`	`dict \| None`	Dictionary containing search parameters from the following list: * bands (list[str]): Frequency bands ['sub6', 'mmW', 'subTHz'] * raytracerName (str): Raytracer name or 'all' * environment (str): 'indoor', 'outdoor', or 'all' * numTx (dict): Numeric range filter {'min': number, 'max': number} * numRx (dict): Numeric range filter {'min': number, 'max': number} * pathDepth (dict): Numeric range filter {'min': number, 'max': number} * maxReflections (dict): Numeric range filter {'min': number, 'max': number} * numRays (dict): Numeric range filter {'min': number, 'max': number} * multiRxAnt (bool): Boolean filter or 'all' to ignore * multiTxAnt (bool): Boolean filter or 'all' to ignore * dualPolarization (bool): Boolean filter or 'all' to ignore * BS2BS (bool): Boolean filter or 'all' to ignore * dynamic (bool): Boolean filter or 'all' to ignore * diffraction (bool): Boolean filter or 'all' to ignore * scattering (bool): Boolean filter or 'all' to ignore * transmission (bool): Boolean filter or 'all' to ignore * digitalTwin (bool): Boolean filter or 'all' to ignore * city (str): City name text filter * bbCoords (dict): Bounding box coordinates {'minLat': float, 'minLon': float, 'maxLat': float, 'maxLon': float} * hasRtSource (bool): Boolean filter or 'all' to ignore. Note: Unlike other flags which are derived in the package during conversion, hasRtSource is set server-side when RT source is uploaded with upload_rt_source()	`None`

Returns:

Type	Description
`list[str] \| None`	Dict containing count and list of matching scenario names if successful, None otherwise

Download¶

Download scenarios from the DeepMIMO database to your local environment.

import deepmimo as dm

# Download a specific scenario
scenario_name = 'asu_campus_3p5'
download_path = dm.download(scenario_name)
print(f"Downloaded to: {download_path}")

Download a DeepMIMO scenario from the database.

Parameters:

Name	Type	Description	Default
`scenario_name`	`str`	Name of the scenario	required
`output_dir`	`str \| None`	Directory to save file (defaults to current directory)	`None`
`rt_source`	`bool`	Whether to download the raytracing source file instead of the scenario	`False`

Returns:

Type	Description
`str \| None`	Path to downloaded file if successful, None otherwise

Upload¶

The upload functionality allows you to contribute scenarios, images, and ray tracing sources to the DeepMIMO database.

Get API Key¶

Some operations in the DeepMIMO Database API require an API key, which can be obtained from the Contribute dashboard on the DeepMIMO website. You will need to create a Google account to access this dashboard.

Currently only the upload functions require an API key.

Scenario¶

Upload a scenario to the DeepMIMO database.

import deepmimo as dm

# Upload a scenario
scenario_name = 'my_scenario'
key = 'your_api_key'
dm.upload(scenario_name, key=key)

Upload a DeepMIMO scenario to the server.

Uploads a scenario to the DeepMIMO database by zipping the scenario folder, uploading to the database, and creating a submission on the server.

Parameters:

Name	Type	Description	Default
`scenario_name`	`str`	Name of the scenario to upload.	required
`key`	`str`	Authorization key for upload access.	required
`details`	`list[str]`	List of details about the scenario for detail boxes.	`None`
`extra_metadata`	`dict`	Additional metadata fields including: digitalTwin (bool): Whether scenario is a digital twin environment (str): Either 'indoor' or 'outdoor' bbCoords (dict): Bounding box coordinates with keys: - minLat (float): Minimum latitude - minLon (float): Minimum longitude - maxLat (float): Maximum latitude - maxLon (float): Maximum longitude city (str): City name	`None`
`skip_zip`	`bool`	If True, skip zipping scenario folder. Defaults to False.	`False`
`include_images`	`bool`	If True, generate and upload visualization images. Defaults to True.	`True`
`submission_only`	`bool`	If True, skip database upload and only create server submission. Use when scenario is already uploaded. Defaults to False.	`False`

Returns:

Name	Type	Description
`str`	`str`	Name of submitted scenario if initial submission succeeds, None otherwise. Image upload status does not affect return value.

Images¶

Upload additional images for a scenario.

import deepmimo as dm

# Upload images
scenario_name = 'my_scenario'
key = 'your_api_key'
img_paths = ['image1.png', 'image2.png']
dm.upload_images(scenario_name, img_paths, key)

Upload images and attach them to an existing scenario.

Parameters:

Name	Type	Description	Default
`scenario_name`	`str`	Name of the scenario to attach images to	required
`img_paths`	`list[str]`	List of paths to image files	required
`key`	`str`	API authentication key	required

Returns:

Type	Description
`list[dict]`	List of image objects that were successfully uploaded and attached

RT Source¶

Upload ray tracing source files for a scenario.

import deepmimo as dm

# Upload RT source
scenario_name = 'my_scenario'
rt_zip_path = 'path/to/rt_source.zip'
key = 'your_api_key'
dm.upload_rt_source(scenario_name, rt_zip_path, key)

Upload a Ray Tracing (RT) source file to the database.

Parameters:

Name	Type	Description	Default
`scenario_name`	`str`	The name of the corresponding scenario already uploaded. The RT source will be stored under `<scenario_name>.zip`.	required
`rt_zip_path`	`str`	Path to the zipped RT source file to upload.	required
`key`	`str`	API authentication key.	required

Returns:

Type	Description
`bool`	True if the upload was successful, False otherwise.