Datasets¶

The datasets module handles dataset loading, generation, manipulation, and visualization.

deepmimo/datasets/
  ├── dataset.py (Dataset classes: Dataset, MacroDataset, DynamicDataset)
  ├── load.py (Load datasets from scenarios)
  ├── generate.py (Generate datasets with channel computation)
  ├── array_wrapper.py (DeepMIMOArray for array manipulation)
  ├── visualization.py (Plotting functions)
  ├── summary.py (Dataset summary functions)
  └── sampling.py (User sampling utilities)

Load Dataset¶

import deepmimo as dm

# Load a scenario
dataset = dm.load('asu_campus_3p5')

Detailed load examples

See the Detailed Load section of the DeepMIMO Manual for more examples.

Load a DeepMIMO scenario.

This function loads raytracing data and creates a Dataset or MacroDataset instance.

Parameters:

Name	Type	Description	Default
`scen_name`	`str`	Name of the scenario to load	required
`**load_params`	`Any`	Additional parameters for loading the scenario. Can be passed as a dictionary or as keyword arguments. Available parameters are: max_paths (int, optional): Maximum number of paths to load. Defaults to 10. tx_sets (dict or list or str, optional): Transmitter sets to load. Defaults to 'all'. Can be: dict: Mapping of set IDs to lists of indices or 'all' list: List of set IDs to load all indices from str: 'all' to load all sets and indices rx_sets (dict or list or str, optional): Receiver sets to load. Same format as tx_sets. Defaults to 'all'. matrices (list of str or str, optional): List of matrix names to load. Defaults to 'all'. Can be: list: List of matrix names to load str: 'all' to load all available matrices	`{}`

Returns:

Type	Description
`Dataset \| MacroDataset`	Dataset or MacroDataset: Loaded dataset(s)

Raises:

Type	Description
`ValueError`	If scenario files cannot be loaded

Generate Dataset¶

The generate() function combines loading and channel computation in a single step.

import deepmimo as dm

# Generate dataset with custom parameters
dataset = dm.generate(
    'asu_campus_3p5',
    load_params={'tx_sets': [0], 'rx_sets': [0]},
    ch_params={'bs_antenna': {'shape': [8, 1]}}
)

Generate a DeepMIMO dataset for a given scenario.

This function wraps loading scenario data, computing channels, and organizing results.

Parameters:

Name	Type	Description	Default
`scen_name`	`str`	Name of the scenario to generate data for	required
`load_params`	`dict`	Parameters for loading the scenario. Defaults to {}.	`None`
`trim_params`	`dict`	Parameters for dataset trimming. Supports: - idxs (array-like): UE indices to keep (applied first) - idxs_mode (str): One of 'active'\|'linear'\|'uniform'\|'row'\|'col'\|'limits' - idxs_kwargs (dict): Keyword args for the idxs mode - bs_fov (list\|tuple [h_deg, v_deg]) - ue_fov (list\|tuple [h_deg, v_deg]) - path_depth (int) - path_types (list[str])	`None`
`ch_params`	`dict`	Parameters for channel generation. Defaults to {}.	`None`

Returns:

Name	Type	Description
`Dataset`	`Dataset \| MacroDataset \| DynamicDataset`	Generated DeepMIMO dataset containing channel matrices and metadata

Raises:

Type	Description
`ValueError`	If scenario name is invalid or required files are missing

Dataset¶

The Dataset class represents a single dataset within DeepMIMO, containing transmitter, receiver, and channel information for a specific scenario configuration.

import deepmimo as dm

# Load a dataset
dataset = dm.load('scenario_name')

# Access transmitter data
tx_locations = dataset.tx_locations
n_tx = len(dataset.tx_locations)

# Access receiver data
rx_locations = dataset.rx_locations
n_rx = len(dataset.rx_locations)

# Access channel data
channels = dataset.channels  # If already computed

Core Properties¶

Property	Description	Dimensions
`rx_pos`	Receiver locations	N x 3
`tx_pos`	Transmitter locations	1 x 3
`power`	Path powers in dBm	N x P
`phase`	Path phases in degrees	N x P
`delay`	Path delays in seconds	N x P
`aoa_az/aoa_el`	Angles of arrival (azimuth/elevation)	N x P
`aod_az/aod_el`	Angles of departure (azimuth/elevation)	N x P
`inter`	Path interaction indicators	N x P
`inter_pos`	Path interaction positions	N x P x I x 3

N: number of receivers in the receiver set
P: maximum number of paths
I: maximum number of interactions along any path

Sampling & Trimming¶

Unified index selection (dispatcher):

# Uniform sampling on the grid
uniform_idxs = dataset.get_idxs('uniform', steps=[2, 2])

# Active users (paths > 0)
active_idxs = dataset.get_idxs('active')

# Users along a line
linear_idxs = dataset.get_idxs('linear', start_pos=[0,0,0], end_pos=[100,0,0], n_steps=50)

Create trimmed datasets (physical trimming):

# Subset by indices
dataset2 = dataset.trim(idxs=uniform_idxs)

# Apply FoV trimming (uses rotated angles)
dataset_fov = dataset.trim(bs_fov=[90, 90])  # optional: ue_fov=[...]

# Combine trims efficiently (order: idxs -> FoV -> path depth -> path type)
dataset_t = dataset.trim(
    idxs=active_idxs,
    bs_fov=[90, 90],
    path_depth=1,
    path_types=['LoS', 'R']
)

User sampling and subsets

See the User Sampling section of the DeepMIMO Manual for examples of sampling users and creating subsets.

Plotting¶

# Plot coverage
plot_coverage = dataset.plot_coverage()

# Plot rays
plot_rays = dataset.plot_rays()

Visualization details

For visualization examples, see the Visualization section of the manual and the Visualization API.

Dataset Class¶

Bases: DotDict

Class for managing DeepMIMO datasets.

This class provides an interface for accessing dataset attributes including: - Channel matrices - Path information (angles, powers, delays) - Position information - TX/RX configuration information - Metadata

Attributes can be accessed using both dot notation (dataset.channel) and dictionary notation (dataset['channel']).

Primary (Static) Attributes: power: Path powers in dBW phase: Path phases in degrees delay: Path delays in seconds (i.e. propagation time) aoa_az/aoa_el: Angles of arrival (azimuth/elevation) aod_az/aod_el: Angles of departure (azimuth/elevation) rx_pos: Receiver positions tx_pos: Transmitter position inter: Path interaction indicators inter_pos: Path interaction positions

Secondary (Computed) Attributes: power_linear: Path powers in linear scale channel: MIMO channel matrices num_paths: Number of paths per user pathloss: Path loss in dB distances: Distances between TX and RXs los: Line of sight status for each receiver pwr_ant_gain: Powers with antenna patterns applied aoa_az_rot/aoa_el_rot: Rotated angles of arrival based on antenna orientation aod_az_rot/aod_el_rot: Rotated angles of departure based on antenna orientation aoa_az_rot_fov/aoa_el_rot_fov: Field of view filtered angles of arrival aod_az_rot_fov/aod_el_rot_fov: Field of view filtered angles of departure fov_mask: Field of view mask inter_vec: Vectorized interaction codes (n_users, n_paths, max_n_interactions) path_ids: Unique IDs for paths based on interaction signatures path_hash: Hash for each user's multipath mix (for MPLM visualization)

TX/RX Information: - tx_set_id: ID of the transmitter set - rx_set_id: ID of the receiver set - tx_idx: Index of the transmitter within its set - rx_idxs: List of receiver indices used

Common Aliases

ch, pwr, rx_loc, pl, dist, n_paths, etc. (See aliases dictionary for complete mapping)

Initialize dataset with optional data.

Parameters:

Name	Type	Description	Default
`data`	`dict[str, Any] \| None`	Initial dataset dictionary. If None, creates empty dataset.	`None`

WRAPPABLE_ARRAYS `class-attribute` ¶

WRAPPABLE_ARRAYS = [
    "power",
    "phase",
    "delay",
    "aoa_az",
    "aoa_el",
    "aod_az",
    "aod_el",
    "inter",
    "los",
    "channel",
    "power_linear",
    "pathloss",
    "distance",
    "num_paths",
    "inter_str",
    "doppler",
    "inter_obj",
    "inter_int",
    "inter_vec",
    "path_ids",
    "path_hash",
]

tx_ori `property` ¶

tx_ori

Compute the orientation of the transmitter.

Returns:

Type	Description
`ndarray`	Array of transmitter orientation

bs_ori `property` ¶

bs_ori

Alias for tx_ori - computes the orientation of the transmitter/basestation.

Returns:

Type	Description
`ndarray`	Array of transmitter orientation

rx_ori `property` ¶

rx_ori

Compute the orientation of the receivers.

Returns:

Type	Description
`ndarray`	Array of receiver orientation

ue_ori `property` ¶

ue_ori

Alias for rx_ori - computes the orientation of the receivers/users.

Returns:

Type	Description
`ndarray`	Array of receiver orientation

rx_vel `property` `writable` ¶

rx_vel

Get the velocities of the users.

Returns:

Type	Description
`ndarray`	np.ndarray: The velocities of the users in cartesian coordinates. (n_ue, 3) `m/s`

tx_vel `property` `writable` ¶

tx_vel

Get the velocities of the base stations.

Returns:

Type	Description
`ndarray`	np.ndarray: The velocities of the base stations in cartesian coordinates. (3,) `m/s`

set_channel_params ¶

set_channel_params(params=None)

Set channel generation parameters.

Parameters:

Name	Type	Description	Default
`params`	`ChannelParameters \| None`	Channel generation parameters. If None, uses default parameters.	`None`

compute_channels ¶

compute_channels(
    params=None,
    *,
    times=None,
    num_timestamps=None,
    **kwargs,
)

Compute MIMO channel matrices with Doppler over an explicit time axis.

If times is None and num_timestamps is None -> single snapshot at t=0 (squeezed 4-D). If times is a scalar or 1D array -> uses it directly (seconds). If num_timestamps is provided (and times is None) -> builds times from OFDM symbol spacing.

Returns:

Name	Type	Description
	`ndarray`	If freq_domain:
	`ndarray`	[n_users, n_rx_ant, n_tx_ant, n_subcarriers] (single t) or
	`ndarray`	[n_users, n_rx_ant, n_tx_ant, n_subcarriers, N_t] (multi t)
`Else`	`ndarray`
	`ndarray`	[n_users, n_rx_ant, n_tx_ant, n_paths] (single t) or
	`ndarray`	[n_users, n_rx_ant, n_tx_ant, n_paths, N_t] (multi t)

bs_look_at ¶

bs_look_at(look_pos)

Set the orientation of the basestation to look at a given position in 3D.

Similar to Sionna RT's Camera.look_at() function, this method automatically calculates and sets the antenna rotation parameters so that the basestation points toward the specified target position.

Parameters:

Name	Type	Description	Default
`look_pos`	`ndarray \| list \| tuple`	The position to look at (x, y, z) in meters. Can be a numpy array, list, or tuple. If 2D coordinates are provided, z=0 is assumed.	required

Example

Point BS toward a specific UE¶

dataset.bs_look_at(dataset.rx_pos[0])

Point BS toward coordinates¶

dataset.bs_look_at([100, 200, 10])

ue_look_at ¶

ue_look_at(look_pos)

Set the orientation of user equipment antennas to look at given position(s) in 3D.

Similar to bs_look_at() function, this method automatically calculates and sets the UE antenna rotation parameters so that user equipment point toward the specified target position(s).

Parameters:

Name	Type	Description	Default
`look_pos`	`ndarray \| list \| tuple`	The position(s) to look at in meters. Can be: - 1D array/list/tuple (x, y, z): All UEs look at the same position - 2D array with shape (3,) or (2,): Same as 1D case - 2D array with shape (n_users, 3): Each UE looks at different position - 2D array with shape (n_users, 2): Each UE looks at different position (z=0) If 2D coordinates are provided, z=0 is assumed.	required

Example

All UEs look at the base station¶

dataset.ue_look_at(dataset.tx_pos)

All UEs look at a specific coordinate¶

dataset.ue_look_at([100, 200, 10])

Each UE looks at different positions (must match number of UEs)¶

look_positions = np.array([[100, 200, 10], [150, 250, 15], ...]) dataset.ue_look_at(look_positions)

clear_cache_rotated_angles ¶

clear_cache_rotated_angles()

Public wrapper around _clear_cache_rotated_angles.

compute_pathloss ¶

compute_pathloss(*, coherent=True)

Compute path loss in dB, assuming 0 dBm transmitted power.

Parameters:

Name	Type	Description	Default
`coherent`	`bool`	Whether to use coherent sum. Defaults to True	`True`

Returns:

Type	Description
`ndarray`	numpy.ndarray: Path loss in dB

compute_num_interactions ¶

compute_num_interactions()

Public wrapper around _compute_num_interactions.

compute_grid_info ¶

compute_grid_info()

Public wrapper around _compute_grid_info.

has_valid_grid ¶

has_valid_grid()

Check if the dataset has a valid grid structure.

A valid grid means that: 1. The total number of points in the grid matches the number of receivers 2. The receivers are arranged in a regular grid pattern

Returns:

Name	Type	Description
`bool`	`bool`	True if dataset has valid grid structure, False otherwise

get_idxs ¶

get_idxs(mode, **kwargs)

Unified dispatcher for user index selection.

Modes

'active': indices of active users (paths > 0)
'linear': indices along line: requires start_pos, end_pos, n_steps [, filter_repeated]
'uniform': grid sampling: requires steps=[x_step, y_step]
'row': row selection: requires row_idxs
'col': column selection: requires col_idxs
'limits': position bounds: requires x_min, x_max, y_min, y_max, z_min, z_max
'id': user IDs selection: requires user_ids

Returns:

Type	Description
`ndarray`	np.ndarray of selected indices

trim_by_fov ¶

trim_by_fov(bs_fov=None, ue_fov=None)

Public wrapper around _trim_by_fov.

trim_by_path_depth ¶

trim_by_path_depth(path_depth)

Public wrapper around _trim_by_path_depth.

trim_by_path_type ¶

trim_by_path_type(allowed_types)

Public wrapper around _trim_by_path_type.

trim ¶

trim(
    *,
    idxs=None,
    bs_fov=None,
    ue_fov=None,
    path_depth=None,
    path_types=None,
)

Return a new dataset after applying multiple trims in optimal order.

Order applied (to minimize work for complex trims): 1) Index subset 2) FoV trimming 3) Path depth trimming 4) Path type trimming

Parameters:

Name	Type	Description	Default
`idxs`	`ndarray \| None`	UE indices to keep. If None, skip.	`None`
`bs_fov`	`ndarray \| list \| tuple \| None`	Base-station FoV [h_deg, v_deg]. None => full FoV (no trimming).	`None`
`ue_fov`	`ndarray \| list \| tuple \| None`	User-equipment FoV [h_deg, v_deg]. None => full FoV (no trimming).	`None`
`path_depth`	`int \| None`	Keep only paths with a number of interactions <= path_depth.	`None`
`path_types`	`list[str] \| None`	Keep only paths comprised of allowed interaction types.	`None`

Returns:

Type	Description
`Dataset`	A new Dataset with all requested trims applied.

plot_coverage ¶

plot_coverage(cov_map, **kwargs)

Plot the coverage of the dataset.

Parameters:

Name	Type	Description	Default
`cov_map`	`Any`	The coverage map to plot.	required
`**kwargs`	`Any`	Additional keyword arguments to pass to the plot_coverage function.	`{}`

plot_rays ¶

plot_rays(idx, color_strat='none', **kwargs)

Plot the rays of the dataset.

Parameters:

Name	Type	Description	Default
`idx`	`int`	Index of the user to plot rays for	required
`color_strat`	`str`	Strategy for coloring rays by power. Can be: - 'none': Don't color by power (default) - 'relative': Color by power relative to min/max of this user's paths - 'absolute': Color by power using absolute limits from all users	`'none'`
`**kwargs`	`Any`	Additional keyword arguments to pass to the plot_rays function.	`{}`

plot_mplm ¶

plot_mplm(**kwargs)

Plot the Multipath Lifetime Map (MPLM).

This visualization colors each receiver location based on its unique multipath signature (combination of paths). Receivers with the same multipath characteristics will have the same color.

Parameters:

Name	Type	Description	Default
`**kwargs`	`Any`	Additional keyword arguments to pass to plot_coverage. Common options include: - dpi: Resolution of the figure (default: 100) - figsize: Size of the figure (default: (6, 4)) - title: Title of the plot (default: "Multipath Lifetime Map") - cbar_title: Title for the colorbar (default: "Path Hash")	`{}`

Returns:

Type	Description
`Any`	The matplotlib figure and axes objects.

plot_multipath_lifetime_map ¶

plot_multipath_lifetime_map(**kwargs)

Alias for plot_mplm(). Plot the Multipath Lifetime Map (MPLM).

This visualization colors each receiver location based on its unique multipath signature (combination of paths). Receivers with the same multipath characteristics will have the same color.

Parameters:

Name	Type	Description	Default
`**kwargs`	`Any`	Additional keyword arguments to pass to plot_coverage. Common options include: - dpi: Resolution of the figure (default: 100) - figsize: Size of the figure (default: (6, 4)) - title: Title of the plot (default: "Multipath Lifetime Map") - cbar_title: Title for the colorbar (default: "Path Hash")	`{}`

Returns:

Type	Description
`Any`	The matplotlib figure and axes objects.

plot_summary ¶

plot_summary(**kwargs)

Plot the summary of the dataset.

print_rx ¶

print_rx(idx, path_idxs=None)

Print detailed information about a specific user.

Parameters:

Name	Type	Description	Default
`idx`	`int`	Index of the user to print information for	required
`path_idxs`	`ndarray \| list[int] \| None`	Optional array of path indices to print. If None, prints all paths.	`None`

Raises:

Type	Description
`IndexError`	If idx is out of range or if any path index is out of range

set_doppler ¶

set_doppler(doppler)

Set the doppler frequency shifts.

Parameters:

Name	Type	Description	Default
`doppler`	`float \| list[float] \| ndarray`	The doppler frequency shifts. (n_ue, max_paths) `Hz` There are 3 options for the shape of the doppler array: 1. 1 value for all paths and users. (1,) `Hz` 2. a value for each user. (n_ue,) `Hz` 3. a value for each user and each path. (n_ue, max_paths) `Hz`	required

set_obj_vel ¶

set_obj_vel(obj_idx, vel)

Update the velocity of an object.

Parameters:

Name	Type	Description	Default
`obj_idx`	`int \| list[int]`	The index of the object to update.	required
`vel`	`list[float] \| list[list[float]] \| ndarray`	The velocity of the object in 3D cartesian coordinates. `m/s`	required

Returns:

Type	Description
`None`	None

clear_all_caches ¶

clear_all_caches()

Clear all caches exposed via public API.

info ¶

info(param_name=None)

Display help information about DeepMIMO dataset parameters.

Parameters:

Name	Type	Description	Default
`param_name`	`str \| None`	Name of the parameter to get info about. If None or 'all', displays information for all parameters. If the parameter name is an alias, shows info for the resolved parameter.	`None`

to_binary ¶

to_binary(output_dir='./datasets')

Export dataset to binary format for web visualizer.

This method exports the dataset to a binary format suitable for the DeepMIMO web visualizer. It creates binary files with proper naming convention and metadata information.

Parameters:

Name	Type	Description	Default
`output_dir`	`str`	Output directory for binary files (default: "./datasets")	`'./datasets'`

update ¶

update(other)

Update the dictionary with elements from another dictionary.

keys ¶

keys()

Return dictionary keys.

values ¶

values()

Return dictionary values.

items ¶

items()

Return dictionary items as (key, value) pairs.

get ¶

get(key, default=None)

Get value for key, returning default if key doesn't exist.

hasattr ¶

hasattr(key)

Safely check if a key exists in the dictionary.

This method provides a safe way to check for attribute existence without raising KeyError, similar to Python's built-in hasattr().

Parameters:

Name	Type	Description	Default
`key`	`str`	The key to check for	required

Returns:

Name	Type	Description
`bool`	`bool`	True if the key exists, False otherwise

to_dict ¶

to_dict()

Convert DotDict back to a regular dictionary.

Returns:

Name	Type	Description
`dict`	`dict`	Regular dictionary representation

deepcopy ¶

deepcopy()

Create a deep copy of the DotDict instance.

This method creates a completely independent copy of the DotDict, including nested dictionaries and numpy arrays. This ensures that modifications to the copy won't affect the original.

Returns:

Name	Type	Description
`DotDict`	`DotDict`	A deep copy of this instance

MacroDataset¶

The MacroDataset class is a container for managing multiple datasets, providing unified access to their data. This is the default output of the dm.load() if there are multiple txrx pairs.

# Access individual datasets
dataset = macro_dataset[0]  # First dataset
datasets = macro_dataset[1:3]  # Slice of datasets

# Iterate over datasets
for dataset in macro_dataset:
    print(f"Dataset has {len(dataset)} users")

# Batch operations
channels = macro_dataset.compute_channels()

Container holding multiple datasets and propagating operations to each.

Acts as a wrapper around a list of Dataset objects; attribute/method access is propagated to all children. When there is only one child, single values are returned instead of single-element lists.

Initialize with optional list of Dataset instances.

Parameters:

Name	Type	Description	Default
`datasets`	`list[Dataset] \| None`	List of Dataset instances. If None, creates empty list.	`None`

SINGLE_ACCESS_METHODS `class-attribute` ¶

SINGLE_ACCESS_METHODS = ['info']

PROPAGATE_METHODS `class-attribute` ¶

PROPAGATE_METHODS = {
    name
    for name, _ in (
        getmembers(Dataset, predicate=isfunction)
    )
    if not startswith("__")
}

datasets `instance-attribute` ¶

datasets = datasets if datasets is not None else []

append ¶

append(dataset)

Add a dataset to the collection.

Parameters:

Name	Type	Description	Default
`dataset`	`Dataset \| MacroDataset`	Dataset instance to add	required

to_binary ¶

to_binary(output_dir='./datasets')

Export all datasets to binary format for web visualizer.

This method exports all contained datasets to binary format suitable for the DeepMIMO web visualizer with proper TX/RX set naming.

Parameters:

Name	Type	Description	Default
`output_dir`	`str`	Output directory for binary files (default: "./datasets")	`'./datasets'`

DynamicDataset¶

The DynamicDataset class extends MacroDataset to handle multiple time snapshots of a scenario. Each snapshot is represented by a MacroDataset instance, allowing you to track changes in the environment over time.

# Convert a dynamic dataset
dm.convert(rt_folder) # rt_folder must contain individual folders of ray tracing results

# Load a dynamic dataset
dynamic_dataset = dm.load('scenario_name')  # Returns DynamicDataset if multiple time snapshots exist

# Access individual time snapshots
snapshot = dynamic_dataset[0]  # First time snapshot
snapshots = dynamic_dataset[1:3]  # Slice of time snapshots

# Access basic properties
print(f"Number of scenes: {len(dynamic_dataset)}")  # or dynamic_dataset.n_scenes
print(f"Scene names: {dynamic_dataset.names}")

Bases: MacroDataset

Dataset composed of multiple (macro)datasets, each a time snapshot.

Initialize a dynamic dataset.

Parameters:

Name	Type	Description	Default
`datasets`	`list[MacroDataset]`	List of MacroDataset instances, each representing a time snapshot	required
`name`	`str`	Base name of the scenario (without time suffix)	required

name `instance-attribute` ¶

name = name

names `instance-attribute` ¶

names = [(name) for dataset in datasets]

n_scenes `instance-attribute` ¶

n_scenes = len(datasets)

SINGLE_ACCESS_METHODS `class-attribute` ¶

SINGLE_ACCESS_METHODS = ['info']

PROPAGATE_METHODS `class-attribute` ¶

PROPAGATE_METHODS = {
    name
    for name, _ in (
        getmembers(Dataset, predicate=isfunction)
    )
    if not startswith("__")
}

datasets `instance-attribute` ¶

datasets = datasets if datasets is not None else []

set_timestamps ¶

set_timestamps(timestamps)

Set the timestamps for the dataset.

Parameters:

Name	Type	Description	Default
`timestamps`	`int \| float \| list[int \| float] \| ndarray`	Timestamps for each scene in the dataset. Can be: - Single value: Creates evenly spaced timestamps - List/array: Custom timestamps for each scene	required

append ¶

append(dataset)

Add a dataset to the collection.

Parameters:

Name	Type	Description	Default
`dataset`	`Dataset \| MacroDataset`	Dataset instance to add	required

to_binary ¶

to_binary(output_dir='./datasets')

Export all datasets to binary format for web visualizer.

This method exports all contained datasets to binary format suitable for the DeepMIMO web visualizer with proper TX/RX set naming.

Parameters:

Name	Type	Description	Default
`output_dir`	`str`	Output directory for binary files (default: "./datasets")	`'./datasets'`

DeepMIMOArray¶

The DeepMIMOArray class provides convenient array manipulation for dataset properties.

Bases: ndarray

A wrapper around numpy.ndarray that adds plotting functionality.

This class wraps arrays in the DeepMIMO dataset where num_rx is the first dimension. It adds a plot() method that uses plot_coverage to visualize the data.

The plot() method handles different array shapes: - 1D arrays [num_rx]: Plots directly - 2D arrays [num_rx, num_paths]: Plots specified path index - 3D arrays [num_rx, num_paths, max_interactions]: Plots specified path and interaction indices

plot ¶

plot(path_idx=0, interaction_idx=0, **kwargs)

Plot the array using plot_coverage.

Parameters:

Name	Type	Description	Default
`path_idx`	`int`	Index of the path to plot for 2D/3D arrays. Ignored for 1D arrays.	`0`
`interaction_idx`	`int`	Interaction index for 3D arrays. Ignored for 1D/2D arrays.	`0`
`**kwargs`	`Any`	Additional arguments to pass to plot_coverage	`{}`

Raises:

Type	Description
`ValueError`	If array has unsupported number of dimensions. Only 1D [num_rx], 2D [num_rx, num_paths], and 3D [num_rx, num_paths, max_interactions] arrays are supported.

Summary Functions¶

Get dataset summary statistics:

import deepmimo as dm

# Get summary as a string
summary_str = dm.summary('scenario_name', print_summary=False)

# Get detailed stats for selected TX/RX sets
stats_str = dm.stats('scenario_name', tx_sets=[4], print_summary=False)

# Plot summary
dm.plot_summary('scenario_name')

Print a summary of the dataset.

Calculate descriptive statistics for selected TX/RX pairs in a scenario.

The function loads only the matrices required for statistics, resolves the selected scenario into one or more TX/RX datasets, computes channel- and scene-level metrics, and formats the result as a plain-text report.

Reported sections include path, power, delay, coverage, spatial, scene, and object/building/terrain statistics when the corresponding data is available.

Parameters:

Name	Type	Description	Default
`scen_name`	`str`	Scenario name passed to :func:`deepmimo.datasets.load.load`.	required
`tx_sets`	`dict[int, list[int] \| str] \| list[int] \| str \| None`	Optional transmitter-set selector passed through to the loader. Accepted forms match :func:`deepmimo.datasets.load.load`: `None` to use the loader default, a list of TX set IDs, a dict mapping TX set IDs to transmitter indices (or `"all"`), or a string selector understood by the loader such as `"all"`.	`None`
`rx_sets`	`dict[int, list[int] \| str] \| list[int] \| str \| None`	Optional receiver-set selector passed through to the loader. Accepted forms match :func:`deepmimo.datasets.load.load`: `None` to preserve the loader default (currently `"rx_only"`), a list of RX set IDs, a dict mapping RX set IDs to receiver indices (or `"all"`), or a string selector understood by the loader.	`None`
`print_summary`	`bool`	If `True`, print the formatted report and return `None`. If `False`, return the formatted report as a string.	`True`

Returns:

Type	Description
`str \| None`	The formatted statistics report when `print_summary` is `False`;
`str \| None`	otherwise `None` after printing the report.

Raises:

Type	Description
`ValueError`	If `tx_sets` or `rx_sets` is provided as an empty list/dict, if the scenario cannot be loaded with the requested selectors, or if the requested selectors do not match any resolved TX/RX datasets.

Notes

Dynamic scenarios are summarized using the first snapshot only. When the selection resolves to multiple TX/RX pairs, the returned report includes a header for each pair.

Make images for the scenario.

Parameters:

Name	Type	Description	Default
`scenario_name`	`str \| None`	Scenario name	`None`
`dataset`	`Any`	Dataset, MacroDataset, or DynamicDataset. If provided, scenario_name is ignored.	`None`
`save_imgs`	`bool`	Whether to save the images to the figures directory	`False`
`plot_idx`	`int \| list[int] \| None`	Index or list of indices of summaries to plot. If None, all summaries are plotted.	`None`

Returns:

Type	Description
`list[str]`	List of paths to generated images

Sampling Functions¶

Utilities for selecting user indices:

# Uniform sampling
idxs = dm.get_uniform_idxs(n_ue=1000, grid_size=[10, 10], steps=[2, 2])

# Linear sampling
idxs = dm.get_linear_idxs(rx_pos, start_pos=[0,0,0], end_pos=[100,0,0], n_steps=50)

# Grid sampling
idxs = dm.get_grid_idxs(grid_size=[10, 10], rows=[0, 1, 2], cols=[0, 1, 2])

# Position limits
idxs = dm.get_idxs_with_limits(rx_pos, x_min=0, x_max=100, y_min=0, y_max=100)

Return indices of users at uniform intervals.

Parameters:

Name	Type	Description	Default
`n_ue`	`int`	Number of users	required
`grid_size`	`ndarray`	Grid size [x_size, y_size]	required
`steps`	`list[int]`	List of sampling steps for each dimension [x_step, y_step]	required

Returns:

Type	Description
`ndarray`	Array of indices for uniformly sampled users

Raises:

Type	Description
`ValueError`	If dataset does not have a valid grid structure

Return indices of users along a linear path between two points.

Parameters:

Name	Type	Description	Default
`rx_pos`	`ndarray`	Positions of dataset points	required
`start_pos`	`ndarray`	Starting position coordinates (2D or 3D)	required
`end_pos`	`ndarray`	Ending position coordinates (2D or 3D)	required
`n_steps`	`int`	Number of steps along the path (default: 100)	required
`filter_repeated`	`bool`	Whether to filter repeated positions (default: True)	`True`

Returns:

Type	Description
`ndarray`	Array of indices of users along the linear path

Return indices of users in the specified rows or columns, assuming a grid structure.

Parameters:

Name	Type	Description	Default
`grid_size`	`ndarray`	Grid size as [x_size, y_size] where x_size is number of columns and y_size is number of rows	required
`axis`	`str`	Either 'row' or 'col' to specify which indices to get	required
`idxs`	`int \| list[int] \| ndarray`	Array of row or column indices to include	required

Returns:

Type	Description
`ndarray`	Array of indices of receivers in the specified rows or columns

Raises:

Type	Description
`ValueError`	If axis is not 'row' or 'col'

Return indices of users within specified coordinate limits.

Parameters:

Name	Type	Description	Default
`data_pos`	`ndarray`	User positions array [n_users, 3]	required
`**limits`	`float`	Coordinate limits as keyword arguments: x_min, x_max: X coordinate limits y_min, y_max: Y coordinate limits z_min, z_max: Z coordinate limits	`{}`

Returns:

Type	Description
`ndarray`	Array of indices for users within limits

Convert power from dBW to Watts.

This function performs the standard conversion from decibel-watts (dBW) to linear power in Watts.

Parameters:

Name	Type	Description	Default
`val`	`float \| ndarray`	Power value(s) in dBW	required

Returns:

Type	Description
`float \| ndarray`	Power value(s) in Watts

Datasets¶

Load Dataset¶

Generate Dataset¶

Dataset¶

Core Properties¶

Sampling & Trimming¶

Plotting¶

Dataset Class¶

WRAPPABLE_ARRAYS class-attribute ¶

tx_ori property ¶

bs_ori property ¶

rx_ori property ¶

ue_ori property ¶

rx_vel property writable ¶

tx_vel property writable ¶

set_channel_params ¶

compute_channels ¶

bs_look_at ¶

Point BS toward a specific UE¶

Point BS toward coordinates¶

ue_look_at ¶

All UEs look at the base station¶

All UEs look at a specific coordinate¶

Each UE looks at different positions (must match number of UEs)¶

clear_cache_rotated_angles ¶

compute_pathloss ¶

compute_num_interactions ¶

compute_grid_info ¶

has_valid_grid ¶

get_idxs ¶

trim_by_fov ¶

trim_by_path_depth ¶

trim_by_path_type ¶

trim ¶

plot_coverage ¶

plot_rays ¶

plot_mplm ¶

plot_multipath_lifetime_map ¶

plot_summary ¶

print_rx ¶

set_doppler ¶

set_obj_vel ¶

clear_all_caches ¶

info ¶

to_binary ¶

update ¶

keys ¶

values ¶

items ¶

get ¶

hasattr ¶

to_dict ¶

deepcopy ¶

MacroDataset¶

SINGLE_ACCESS_METHODS class-attribute ¶

PROPAGATE_METHODS class-attribute ¶

datasets instance-attribute ¶

append ¶

to_binary ¶

DynamicDataset¶

name instance-attribute ¶

names instance-attribute ¶

n_scenes instance-attribute ¶

SINGLE_ACCESS_METHODS class-attribute ¶

PROPAGATE_METHODS class-attribute ¶

datasets instance-attribute ¶

set_timestamps ¶

append ¶

to_binary ¶

DeepMIMOArray¶

plot ¶

Summary Functions¶

Sampling Functions¶

WRAPPABLE_ARRAYS `class-attribute` ¶

tx_ori `property` ¶

bs_ori `property` ¶

rx_ori `property` ¶

ue_ori `property` ¶

rx_vel `property` `writable` ¶

tx_vel `property` `writable` ¶

SINGLE_ACCESS_METHODS `class-attribute` ¶

PROPAGATE_METHODS `class-attribute` ¶

datasets `instance-attribute` ¶

name `instance-attribute` ¶

names `instance-attribute` ¶

n_scenes `instance-attribute` ¶

SINGLE_ACCESS_METHODS `class-attribute` ¶

PROPAGATE_METHODS `class-attribute` ¶

datasets `instance-attribute` ¶