Core Models¶
The core module provides fundamental data model classes for representing wireless scenarios, including physical scenes, materials, ray tracing parameters, and transmitter/receiver configurations.
deepmimo/core/
├── scene.py (Physical environment representation)
├── materials.py (Material properties)
├── rt_params.py (Ray tracing parameters)
└── txrx.py (Transmitter/receiver configurations)
Scene¶
The Scene class represents a complete physical environment containing multiple objects.
import deepmimo as dm
# Create a new scene
scene = dm.Scene()
# Add objects
scene.add_object(building)
scene.add_objects([tree1, tree2])
# Get objects by category
buildings = scene.get_objects(label='buildings')
metal_objects = scene.get_objects(material=1) # material_id = 1
# 3D visualization
scene.plot(mode='faces')
For detailed information about Scene and related classes (BoundingBox, Face, PhysicalElement, PhysicalElementGroup), see the Scene API Reference.
Represents a physical scene with various objects affecting wireless propagation.
Initialize an empty scene.
DEFAULT_VISUALIZATION_SETTINGS
class-attribute
¶
DEFAULT_VISUALIZATION_SETTINGS = {
CAT_TERRAIN: {
"z_order": 1,
"alpha": 0.1,
"color": "black",
},
CAT_VEGETATION: {
"z_order": 2,
"alpha": 0.8,
"color": "green",
},
CAT_BUILDINGS: {
"z_order": 3,
"alpha": 0.6,
"color": None,
},
CAT_FLOORPLANS: {
"z_order": 4,
"alpha": 0.8,
"color": "blue",
},
CAT_OBJECTS: {
"z_order": 5,
"alpha": 0.8,
"color": "red",
},
}
set_visualization_settings ¶
set_visualization_settings(label, settings)
Set visualization settings for a specific label.
add_object ¶
add_object(obj)
Add a physical object to the scene.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
PhysicalElement
|
PhysicalElement to add |
required |
add_objects ¶
add_objects(objects)
Add multiple physical objects to the scene.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
objects
|
list[PhysicalElement]
|
List of PhysicalElement objects to add |
required |
get_objects ¶
get_objects(label=None, material=None)
Get objects filtered by label and/or material.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
label
|
str | None
|
Optional label to filter objects by |
None
|
material
|
int | None
|
Optional material index to filter objects by |
None
|
Returns:
| Type | Description |
|---|---|
PhysicalElementGroup
|
PhysicalElementGroup containing filtered objects |
export_data ¶
export_data(base_folder)
Export scene data to files and return metadata dictionary.
Creates matrix files for vertices, faces and materials in the base folder. Returns a dictionary containing metadata needed to reload the scene.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
base_folder
|
str
|
Base folder to store matrix files |
required |
Returns:
| Type | Description |
|---|---|
dict
|
Dict containing metadata needed to reload the scene |
from_data
classmethod
¶
from_data(base_folder)
Create scene from metadata dictionary and data files.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
base_folder
|
str
|
Base folder containing matrix files |
required |
plot ¶
plot(
*,
title=True,
mode="faces",
ax=None,
proj_3d=True,
figsize=(10, 10),
dpi=100,
legend=False,
**kwargs,
)
Create a visualization of the scene.
The scene can be visualized in either 2D (top-down view) or 3D mode:
3D Mode (proj_3d=True): Two representation options: 1. 'faces' (default) - Uses the primary convex hull representation - More efficient for visualization - Cleaner look for simple geometric shapes - Suitable for most visualization needs
2. 'tri_faces' - Uses the secondary triangular representation
- Shows detailed geometry
- Better for debugging geometric issues
- More accurate representation of complex shapes
2D Mode (proj_3d=False): Creates a top-down view showing object footprints: - Projects all objects onto x-y plane - Uses convex hulls for efficient visualization - Better for understanding spatial layout - More efficient for large scenes
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
title
|
bool
|
Whether to display the title (default: True) |
True
|
mode
|
Literal['faces', 'tri_faces']
|
Visualization mode for 3D - either 'faces' or 'tri_faces' (default: 'faces') |
'faces'
|
ax
|
Axes | None
|
Matplotlib axes to plot on (if None, creates new figure) |
None
|
proj_3d
|
bool
|
Whether to create 3D projection (default: True) |
True
|
**kwargs
|
Any
|
Additional keyword-only options; accepts |
{}
|
figsize
|
tuple
|
Figure dimensions (width, height) in inches (default: (10, 10)) |
(10, 10)
|
dpi
|
int
|
Plot resolution in dots per inch (default: 100) |
100
|
legend
|
bool
|
Whether to show legend for objects/materials (default: False) |
False
|
Returns:
| Type | Description |
|---|---|
Axes
|
matplotlib Axes object |
count_objects_by_label ¶
count_objects_by_label()
Count the number of objects for each label in the scene.
Returns:
| Type | Description |
|---|---|
dict[str, int]
|
dict[str, int]: Dictionary mapping labels to their counts |
Materials¶
The Material and MaterialList classes manage material properties for electromagnetic simulations.
import deepmimo as dm
# Create a material
material = dm.Material(
id=1,
name='Concrete',
permittivity=4.5,
conductivity=0.02,
scattering_coefficient=0.2
)
# Create material list
materials = dm.MaterialList()
materials.add_materials([concrete, glass, metal])
For detailed information about Materials, see the Materials API Reference.
Base material class for DeepMIMO.
This class represents materials in a standardized way across different ray tracers. It includes electromagnetic, scattering, and physical properties.
Attributes:
| Name | Type | Description |
|---|---|---|
id |
int
|
Material identifier |
name |
str
|
Material name/label |
permittivity |
float
|
Relative permittivity |
conductivity |
float
|
Conductivity in S/m |
scattering_model |
str
|
Type of scattering model |
scattering_coefficient |
float
|
Scattering coefficient (0-1) |
cross_polarization_coefficient |
float
|
Cross-polarization ratio |
alpha_r |
float
|
Real part of scattering exponent |
alpha_i |
float
|
Imaginary part of scattering exponent |
lambda_param |
float
|
Forward/backward ratio |
roughness |
float
|
Surface roughness in meters |
thickness |
float
|
Material thickness in meters |
vertical_attenuation |
float
|
Vertical attenuation in dB/m |
horizontal_attenuation |
float
|
Horizontal attenuation in dB/m |
itu_a |
float
|
Constant term in real part |
itu_b |
float
|
Coefficient of frequency-dependent term in real part |
itu_c |
float
|
Frequency exponent |
itu_d |
float
|
Coefficient of frequency-dependent imaginary part |
Notes
- Scattering modeling based on https://ieeexplore.ieee.org/document/4052607 (common approach to backscattering in ray tracing software)
- ITU-R P.2040 parameters are optional
cross_polarization_coefficient
class-attribute
instance-attribute
¶
cross_polarization_coefficient = 0.0
Container for managing a collection of materials.
Initialize an empty material list.
add_materials ¶
add_materials(materials)
Add materials to the collection.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
materials
|
list[Material]
|
List of Material objects to add |
required |
to_dict ¶
to_dict()
Get dictionary representation of all materials.
Returns:
| Type | Description |
|---|---|
dict
|
Dict mapping material IDs to their properties. Note that when saved |
dict
|
to .mat format, numeric keys will be converted to strings (e.g., '0', '1', etc.) |
from_dict
classmethod
¶
from_dict(materials_dict)
Create MaterialList from dictionary representation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
materials_dict
|
dict
|
Dictionary mapping material IDs to their properties |
required |
Returns:
| Type | Description |
|---|---|
MaterialList
|
MaterialList containing the materials from the dictionary |
Ray Tracing Parameters¶
The RayTracingParameters class configures ray tracing simulation settings.
import deepmimo as dm
# Create ray tracing parameters
rt_params = dm.RayTracingParameters(
max_num_paths=25,
max_num_interactions=5,
min_path_gain=-160.0
)
Base class for ray tracing parameters.
This class defines common parameters across different ray tracing engines. Each specific engine (Wireless Insite, Sionna, etc.) should extend this class with its own parameters and methods.
Note: All parameters are required to allow child classes to add their own required parameters. Default values can be set in post_init.
diffuse_final_interaction_only
class-attribute
instance-attribute
¶
diffuse_final_interaction_only = False
to_dict ¶
to_dict()
Convert parameters to dictionary format.
Returns:
| Type | Description |
|---|---|
dict
|
Dictionary containing all parameters |
from_dict
classmethod
¶
from_dict(params_dict, raw_params=None)
Create RayTracingParameters from a dictionary.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params_dict
|
dict
|
Dictionary containing parameter values |
required |
raw_params
|
dict | None
|
Optional dictionary containing original engine parameters |
None
|
Returns:
| Type | Description |
|---|---|
RayTracingParameters
|
RayTracingParameters object |
read_parameters
classmethod
¶
read_parameters(load_folder)
Read parameters from a folder.
This is an abstract method that should be implemented by each engine-specific subclass to read parameters in the appropriate format.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
load_folder
|
str | Path
|
Path to folder containing parameter files |
required |
Returns:
| Type | Description |
|---|---|
RayTracingParameters
|
RayTracingParameters object |
Raises:
| Type | Description |
|---|---|
NotImplementedError
|
If not implemented by subclass |
Transmitter/Receiver Configuration¶
Classes for managing transmitter and receiver configurations in scenarios.
import deepmimo as dm
# Get available TX/RX sets for a scenario
txrx_sets = dm.get_txrx_sets('scenario_name')
# Get available TX/RX pairs
pairs = dm.get_txrx_pairs('scenario_name')
# Print available pairs
dm.print_available_txrx_pair_ids('scenario_name')
Base TX/RX set class for DeepMIMO.
This class represents a set of transmitters or receivers in a ray tracing simulation. It is used by all ray tracing converters (Wireless Insite, Sionna, etc.) to store TX/RX configuration information during conversion.
Example
Wireless Insite IDs = [3, 7, 8] DeepMIMO (after conversion) TX/RX Sets: [0, 1, 2] DeepMIMO (after generation): only individual tx and rx indices
ant_rel_positions
class-attribute
instance-attribute
¶
ant_rel_positions = field(
default_factory=lambda: [[0, 0, 0]]
)
array_orientation
class-attribute
instance-attribute
¶
array_orientation = field(default_factory=lambda: [0, 0, 0])
to_dict ¶
to_dict()
Convert TxRxSet to a dictionary.
Returns:
| Type | Description |
|---|---|
dict
|
Dictionary containing all attributes of the TxRxSet. |
Represents a pair of transmitter and receiver in a ray tracing simulation.
This class is used to store the configuration of a transmitter and receiver pair, including their positions, antenna properties, and other relevant information.
Get all available transmitter-receiver sets for a given scenario.
This function reads the scenario parameters file and creates a list of TxRxSet objects based on the available transmitter and receiver sets.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scenario_name
|
str
|
Name of the DeepMIMO scenario |
required |
Returns:
| Type | Description |
|---|---|
list[TxRxSet]
|
List of TxRxSet objects representing all available transmitter-receiver sets |
Example
txrx_sets = dm.get_txrx_sets('O1_60') for txrx_set in txrx_sets: ... print(txrx_set) TxRxSet(name='tx_array', idx=1, points=2) TxRxSet(name='rx_array', idx=2, points=1)
Create all possible transmitter-receiver pairs from a list of TxRxSet objects.
This function pairs all transmitter sets with all receiver sets, decoupling individual transmitters from sets that have multiple transmitters.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
txrx_sets
|
list[TxRxSet]
|
List of TxRxSet objects to create pairs from |
required |
Returns:
| Type | Description |
|---|---|
list[TxRxPair]
|
List of TxRxPair objects representing all valid transmitter-receiver combinations |
Example
If we have: - TxRxSet1 with 2 TXs - TxRxSet2 with 1 TX - TxRxSet3 with only RXs
The function will create pairs: - TX1 from Set1 with all RXs from Set3 - TX2 from Set1 with all RXs from Set3 - TX from Set2 with all RXs from Set3