High-level interface for generating MIMO channel matrices using Sionna RT. More...

#include "sionna-rt-channel-model.h"

Inheritance diagram for ns3::SionnaRtChannelModel:

Collaboration diagram for ns3::SionnaRtChannelModel:

Classes
struct	RtPathSolverConfig
	Configuration for the Sionna RT PathSolver. More...
struct	RtSceneConfig
	Scene high-level configuration. More...
struct	SionnaRtChannelParams
	ChannelParams extension to carry Sionna-specific metadata. More...

Public Member Functions
	SionnaRtChannelModel ()
	Constructor.
	~SionnaRtChannelModel () override
	Destructor.
bool	AntennaSetupChanged (Ptr< const PhasedArrayModel > aAntenna, Ptr< const PhasedArrayModel > bAntenna, Ptr< const ChannelMatrix > channelMatrix) const
	Check whether antenna configuration changes require regenerating the channel matrix.
int64_t	AssignStreams (int64_t stream)
	Assign stream indices to any random variables used internally.
bool	ChannelMatrixNeedsUpdate (Ptr< const ChannelMatrix > channelMatrix) const
	Determine whether an existing ChannelMatrix must be updated.
Ptr< MatrixBasedChannelModel::ChannelMatrix >	CreateNewMatrixChannel (const Complex3DVector hUsn, const Ptr< const MobilityModel > sMob, const Ptr< const MobilityModel > uMob, Ptr< const PhasedArrayModel > sAntenna, Ptr< const PhasedArrayModel > uAntenna) const
	Create a new ChannelMatrix object wrapping a precomputed CIR tensor.
py::object	CreateScene (const py::module_ rt, const Ptr< const MobilityModel > sMob, const Ptr< const MobilityModel > uMob, Ptr< const PhasedArrayModel > sAntenna, Ptr< const PhasedArrayModel > uAntenna) const
	Create a sionna.rt scene object for the provided endpoints and antennas.
void	DoDispose () override
	Release references and perform cleanup.
std::string	GetAntennaElementPattern (Ptr< const AntennaModel > element) const
	Return a string describing the antenna element pattern for Sionna.
Ptr< const ChannelMatrix >	GetChannel (Ptr< const MobilityModel > aMob, Ptr< const MobilityModel > bMob, Ptr< const PhasedArrayModel > aAntenna, Ptr< const PhasedArrayModel > bAntenna) override
	Retrieve or generate the channel matrix for the node pair.
double	GetFrequency () const
	Get the configured center frequency.
double	GetMaxNumberOfPaths () const
	Get the configured maximum number of propagation paths.
virtual Ptr< ChannelMatrix >	GetNewChannel (py::object paths, const Ptr< const MobilityModel > sMob, const Ptr< const MobilityModel > uMob, Ptr< const PhasedArrayModel > sAntenna, Ptr< const PhasedArrayModel > uAntenna) const
	Compute a new channel matrix for the given node pair using Sionna RT.
bool	GetNormalizeDelays () const
	Query whether path delay normalization is enabled.
Ptr< const ChannelParams >	GetParams (Ptr< const MobilityModel > aMob, Ptr< const MobilityModel > bMob) const override
	Get channel parameters (path info) for a node pair if available.
RtPathSolverConfig	GetRtPathSolverConfig () const
	Retrieve the current path solver configuration.
std::string	GetScenario () const
	Return the configured propagation scenario name.
py::object	MakePlannarArray (const py::module_ rt, Ptr< const PhasedArrayModel > antenna) const
	Build a Sionna PlanarArray description from an ns-3 PhasedArrayModel.
void	SetFrequency (double f)
	Set the center frequency used by the model and scene factories.
void	SetMaxNumberOfPaths (double p)
	Set the maximum number of propagation paths to retain.
void	SetMergeShapeEnable (bool cond)
	Enable or disable shape merging when loading scenes from sionna.rt.
void	SetNormalizeDelays (bool cond)
	Enable or disable normalization of path delays in Sionna RT.
void	SetRtPathSolverConfig (RtPathSolverConfig configs)
	Configure the Sionna RT path solver behavior.
void	SetScenario (const std::string &scenario)
	Set the propagation scenario name used by sionna.rt scene factories.
Public Member Functions inherited from ns3::MatrixBasedChannelModel
	~MatrixBasedChannelModel () override
	Destructor for MatrixBasedChannelModel.
Public Member Functions inherited from ns3::Object
	Object ()
	Caller graph was not generated because of its size.
	~Object () override
	Destructor.
void	AggregateObject (Ptr< Object > other)
	Aggregate two Objects together.
void	Dispose ()
	Dispose of this Object.
AggregateIterator	GetAggregateIterator () const
	Get an iterator to the Objects aggregated to this one.
TypeId	GetInstanceTypeId () const final
	Get the most derived TypeId for this Object.
template<>
Ptr< Object >	GetObject () const
	Specialization of () for objects of type ns3::Object.
template<typename T>
Ptr< T >	GetObject () const
	Get a pointer to the requested aggregated Object.
template<>
Ptr< Object >	GetObject (TypeId tid) const
	Specialization of (TypeId tid) for objects of type ns3::Object.
template<typename T>
Ptr< T >	GetObject (TypeId tid) const
	Get a pointer to the requested aggregated Object by TypeId.
void	Initialize ()
	Invoke DoInitialize on all Objects aggregated to this one.
bool	IsInitialized () const
	Check if the object has been initialized.
void	UnidirectionalAggregateObject (Ptr< Object > other)
	Aggregate an Object to another Object.
Public Member Functions inherited from ns3::SimpleRefCount< Object, ObjectBase, ObjectDeleter >
	SimpleRefCount ()
	Default constructor.
uint32_t	GetReferenceCount () const
	Get the reference count of the object.
SimpleRefCount &	operator= (const SimpleRefCount &o)
	Assignment operator.
void	Ref () const
	Increment the reference count.
void	Unref () const
	Decrement the reference count.
Public Member Functions inherited from ns3::ObjectBase
virtual	~ObjectBase ()
	Virtual destructor.
void	GetAttribute (std::string name, AttributeValue &value, bool permissive=false) const
	Get the value of an attribute, raising fatal errors if unsuccessful.
bool	GetAttributeFailSafe (std::string name, AttributeValue &value) const
	Get the value of an attribute without raising errors.
void	SetAttribute (std::string name, const AttributeValue &value)
	Set a single attribute, raising fatal errors if unsuccessful.
bool	SetAttributeFailSafe (std::string name, const AttributeValue &value)
	Set a single attribute without raising errors.
bool	TraceConnect (std::string name, std::string context, const CallbackBase &cb)
	Connect a TraceSource to a Callback with a context.
bool	TraceConnectWithoutContext (std::string name, const CallbackBase &cb)
	Connect a TraceSource to a Callback without a context.
bool	TraceDisconnect (std::string name, std::string context, const CallbackBase &cb)
	Disconnect from a TraceSource a Callback previously connected with a context.
bool	TraceDisconnectWithoutContext (std::string name, const CallbackBase &cb)
	Disconnect from a TraceSource a Callback previously connected without a context.

Static Public Member Functions
static TypeId	GetTypeId ()
	Get the ns-3 TypeId for this class.
Static Public Member Functions inherited from ns3::MatrixBasedChannelModel
static uint64_t	GetKey (uint32_t a, uint32_t b)
	Generate a unique value for the pair of unsigned integer of 32 bits, where the order does not matter, i.e., the same value will be returned for (a,b) and (b,a).
Static Public Member Functions inherited from ns3::Object
static TypeId	GetTypeId ()
	Register this type.
Static Public Member Functions inherited from ns3::ObjectBase
static TypeId	GetTypeId ()
	Get the type ID.

Protected Member Functions
MatrixBasedChannelModel::DoubleVector	CalculateAnglesFromPaths (const py::module_ np, py::object paths, std::string Angle) const
	Extract angular measurements (AOD/AOA/ZOA/ZOD) from the paths.
Ptr< SionnaRtChannelParams >	CalculateChannelParamsFromPaths (const py::object paths, Ptr< const MobilityModel > aMob, Ptr< const MobilityModel > bMob) const
	Build ChannelParams metadata from Sionna RT paths object.
Complex3DVector	CalculateCirFromPaths (const py::object paths) const
	Convert calculated paths into channel impulse responses (CIRs).
std::vector< double >	CalculateDopplerFromPaths (const py::module_ np, py::object paths) const
	Extract Doppler shifts per path from the Python paths object.
py::object	CalculatePaths (const py::module_ rt, const py::object scene)
	Compute propagation paths between transmitter and receiver.
MatrixBasedChannelModel::DoubleVector	CalculateTauFromPaths (const py::module_ np, py::object paths) const
	Extract delays (tau) per path from RS paths object.
bool	DoesNumberOfPathsExceedMaximum (size_t numPaths) const
	Determine if the path count exceeds the configured maximum threshold.
size_t	GetNumberOfPathsFromCir (const py::object paths) const
	Extract the number of propagation paths from the CIR tensor.
std::string	GetPolarizationFromPolSlantAngle (const double polSlantAngle, const uint8_t numpol) const
	Convert a polarization slant angle into Sionna RT string representation.
py::object	LoadScene (const py::module_ rt) const
	Load a Sionna RT scene using the configured scenario name.
void	SceneRenderImageToFile (const py::module_ rt, const py::object paths, const py::object scene) const
	Render a visualization of the scene and paths to a PNG image file.
Protected Member Functions inherited from ns3::Object
	Object (const Object &o)
	Copy an Object.
virtual void	DoInitialize ()
	Initialize() implementation.
virtual void	NotifyNewAggregate ()
	Notify all Objects aggregated to this one of a new Object being aggregated.
Protected Member Functions inherited from ns3::ObjectBase
void	ConstructSelf (const AttributeConstructionList &attributes)
	Complete construction of ObjectBase; invoked by derived classes.
virtual void	NotifyConstructionCompleted ()
	Notifier called once the ObjectBase is fully constructed.

Protected Attributes
Vector	m_cameraLookAt
	Camera look-at point for scene rendering.
Vector	m_cameraPosition
	Camera position/look-at used by the scene rendering pipeline.
std::unordered_map< uint64_t, Ptr< ChannelMatrix > >	m_channelMatrixMap
	map containing the channel realizations per pair of PhasedAntennaArray instances, the key of this map is reciprocal uniquely identifies a pair of PhasedAntennaArrays
std::unordered_map< uint64_t, Ptr< SionnaRtChannelParams > >	m_channelParamsMap
	map containing the common channel parameters per pair of nodes, the key of this map is reciprocal and uniquely identifies a pair of nodes
bool	m_isImageRendered
	Control for whether we should render a scene image.
double	m_maxNumberOfPaths
	Maximum number of paths to be generated by the path solver.
bool	m_normalizeDelays
	Whether Sionna RT should normalize path delays in CIR output.
std::string	m_outputImageDirectory
	Output directory.
std::string	m_outputImageName
	Output image rendering options (file name/directory).
RtPathSolverConfig	m_RtPathSolverConfig
	Path solver configuration used when computing paths.
RtSceneConfig	m_sceneConfigs
	High-level scene configuration.
Time	m_updatePeriod
	Channel update period used to decide whether to re-run path computations.

Additional Inherited Members
Public Types inherited from ns3::MatrixBasedChannelModel
using	Complex2DVector = ComplexMatrixArray
	Create an alias for 2D complex vectors.
using	Complex3DVector = ComplexMatrixArray
	Create an alias for 3D complex vectors.
using	Double2DVector = std::vector<DoubleVector>
	Type definition for matrices of doubles.
using	Double3DVector = std::vector<Double2DVector>
	Type definition for 3D matrices of doubles.
using	DoubleVector = std::vector<double>
	Type definition for vectors of doubles.
Static Public Attributes inherited from ns3::MatrixBasedChannelModel
static const uint8_t	AOA_INDEX = 0
	index of the AOA value in the m_angle array
static const uint8_t	AOD_INDEX = 2
	index of the AOD value in the m_angle array
static const uint8_t	ZOA_INDEX = 1
	index of the ZOA value in the m_angle array
static const uint8_t	ZOD_INDEX = 3
	index of the ZOD value in the m_angle array
Related Symbols inherited from ns3::ObjectBase
static TypeId	GetObjectIid ()
	Ensure the TypeId for ObjectBase gets fully configured to anchor the inheritance tree properly.

Detailed Description

High-level interface for generating MIMO channel matrices using Sionna RT.

This class bridges ns-3's MatrixBasedChannelModel framework and the Sionna RT Python library (sionna.rt) to generate realistic, geometry-based MIMO channels. It embeds a Python interpreter (via pybind11), constructs scenes (terrain/building geometry), computes propagation paths (LOS, specular/diffuse reflections, refraction, diffraction, synthetic arrays), and converts the resulting paths into ns-3 ChannelMatrix and ChannelParams objects for use by spectrum and wireless modules like nr, wifi, lte, etc

Design highlights:

Scenes and path computations are performed with sionna.rt through pybind11.
Computed CIRs are represented using Complex3DVector (rx x tx x taps).
Caching: channel matrices and parameters are stored per-Node pair using a reciprocal uint64_t key derived from antenna/mobility instances.
The class exposes solver configuration options (RtPathSolverConfig) and scene configuration (RtSceneConfig).
Supported Sionna RT versions: 1.1.0, 1.2.2, 2.0.1.

Threading/Concurrency:

The Python interpreter is created via pybind11::embed, which must be used carefully when ns-3 is executed in multi-threaded contexts. The current implementation assumes single-threaded execution (typical for ns-3).

Definition at line 69 of file sionna-rt-channel-model.h.

Constructor & Destructor Documentation

◆ SionnaRtChannelModel()

ns3::SionnaRtChannelModel::SionnaRtChannelModel ( )

Constructor.

Definition at line 38 of file sionna-rt-channel-model.cc.

References NS_LOG_FUNCTION.

◆ ~SionnaRtChannelModel()

ns3::SionnaRtChannelModel::~SionnaRtChannelModel ( )

override

Destructor.

Definition at line 43 of file sionna-rt-channel-model.cc.

References NS_LOG_FUNCTION.

Member Function Documentation

◆ AntennaSetupChanged()

bool ns3::SionnaRtChannelModel::AntennaSetupChanged	(	Ptr< const PhasedArrayModel >	aAntenna,
		Ptr< const PhasedArrayModel >	bAntenna,
		Ptr< const ChannelMatrix >	channelMatrix ) const

Check whether antenna configuration changes require regenerating the channel matrix.

This compares the provided antenna arrays with the stored ChannelMatrix metadata to decide if the matrix is stale (for example if number of ports, element locations, or element types changed).

Parameters

aAntenna	Antenna array of node A
bAntenna	Antenna array of node B
channelMatrix	The existing channel matrix to compare against

Returns: true if the channel matrix must be updated; false otherwise

Definition at line 183 of file sionna-rt-channel-model.cc.

References NS_LOG_DEBUG, and NS_LOG_INFO.

Referenced by GetChannel().

Here is the caller graph for this function:

◆ AssignStreams()

int64_t ns3::SionnaRtChannelModel::AssignStreams ( int64_t stream )

Assign stream indices to any random variables used internally.

This is used to make simulations reproducible by assigning deterministic RNG stream indices.

Parameters

stream First stream index to use.

Returns: Number of stream indices assigned.

◆ CalculateAnglesFromPaths()

MatrixBasedChannelModel::DoubleVector ns3::SionnaRtChannelModel::CalculateAnglesFromPaths	(	const py::module_	np,
		py::object	paths,
		std::string	Angle ) const

protected

Extract angular measurements (AOD/AOA/ZOA/ZOD) from the paths.

Returns the requested angle measure for each path in radians. The Angle parameter is case-sensitive and should be one of:

"theta_r" (Zenith angles of arrival, ZOA)
"theta_t" (Zenith angles of departure, ZOD)
"phi_t" (Azimuth angles of departure, AOD)
"phi_r" (Azimuth angles of arrival, AOA)

Parameters

np	The numpy_python module reference (py::module_)
paths	Python paths object computed by Sionna RT
Angle	String indicating the desired angle type

Returns: Vector of angle values (radians) per path/tap

Definition at line 773 of file sionna-rt-channel-model.cc.

References data, m_RtPathSolverConfig, NS_LOG_DEBUG, and NS_LOG_ERROR.

Referenced by CalculateChannelParamsFromPaths().

Here is the caller graph for this function:

◆ CalculateChannelParamsFromPaths()

Ptr< SionnaRtChannelModel::SionnaRtChannelParams > ns3::SionnaRtChannelModel::CalculateChannelParamsFromPaths	(	const py::object	paths,
		Ptr< const MobilityModel >	aMob,
		Ptr< const MobilityModel >	bMob ) const

protected

Build ChannelParams metadata from Sionna RT paths object.

Produces an instance of SionnaRtChannelParams, populated with per-path doppler terms (m_doppler) and any other per-channel metadata extracted from the paths object.

Parameters

paths	Python paths object returned by CalculatePaths
aMob	Mobility model of node A
bMob	Mobility model of node B

Returns: Ptr to an allocated SionnaRtChannelParams instance

Definition at line 493 of file sionna-rt-channel-model.cc.

References CalculateAnglesFromPaths(), CalculateDopplerFromPaths(), CalculateTauFromPaths(), ns3::Create(), ns3::DEG2RAD, ns3::Node::GetId(), ns3::Simulator::Now(), NS_LOG_DEBUG, and NS_LOG_FUNCTION.

Referenced by GetChannel().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ CalculateCirFromPaths()

MatrixBasedChannelModel::Complex3DVector ns3::SionnaRtChannelModel::CalculateCirFromPaths ( const py::object paths ) const

protected

Convert calculated paths into channel impulse responses (CIRs).

The returned Complex3DVector is shaped as: [numRxPorts][numTxPorts][path] where each path is the complex channel coefficient for a given delay tap. Delay and power normalization are handled according to the scene and solver semantics. The function uses internal utilities to extract angles, Doppler and delays from the paths object.

Parameters

paths Python object representing computed paths

Returns: Complex3DVector containing CIRs for Rx/Tx element pairs

Definition at line 688 of file sionna-rt-channel-model.cc.

References data, m_normalizeDelays, NS_LOG_DEBUG, and NS_LOG_FUNCTION.

Referenced by GetNewChannel().

Here is the caller graph for this function:

◆ CalculateDopplerFromPaths()

std::vector< double > ns3::SionnaRtChannelModel::CalculateDopplerFromPaths	(	const py::module_	np,
		py::object	paths ) const

protected

Extract Doppler shifts per path from the Python paths object.

The Doppler shifts are returned in a PhasedArrayModel::ComplexVector where each entry is e^{j*2*pi*fd*t} or similar, depending on the calling convention.

Parameters

np	The numpy_python module reference (py::module_)
paths	Python paths object computed by Sionna RT

Returns: Complex vector of per-path Doppler shifts (one per path)

Definition at line 748 of file sionna-rt-channel-model.cc.

References data, m_RtPathSolverConfig, and NS_LOG_FUNCTION.

Referenced by CalculateChannelParamsFromPaths().

Here is the caller graph for this function:

◆ CalculatePaths()

py::object ns3::SionnaRtChannelModel::CalculatePaths	(	const py::module_	rt,
		const py::object	scene )

protected

Compute propagation paths between transmitter and receiver.

Invokes the Sionna RT PathSolver with the configured RtPathSolverConfig options (max_depth, los, specular_reflection, etc.). The solver recursively traces rays through the scene to identify all significant paths up to the configured maximum depth. If the number of paths exceeds the configured maximum (m_maxNumberOfPaths), this method automatically adjusts the solver depth and retries until the path count is acceptable.

Parameters

rt	The imported sionna.rt Python module
scene	A Python Scene object (from CreateScene or LoadScene)

Returns: A Python Paths object containing delays, angles, powers, and other per-path metadata

See also: SetRtPathSolverConfig, GetNumberOfPathsFromCir

Definition at line 598 of file sionna-rt-channel-model.cc.

References CalculatePaths(), DoesNumberOfPathsExceedMaximum(), GetNumberOfPathsFromCir(), m_isImageRendered, m_maxNumberOfPaths, m_RtPathSolverConfig, NS_LOG_DEBUG, NS_LOG_FUNCTION, NS_LOG_INFO, NS_LOG_WARN, and SceneRenderImageToFile().

Referenced by CalculatePaths(), and GetChannel().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ CalculateTauFromPaths()

MatrixBasedChannelModel::DoubleVector ns3::SionnaRtChannelModel::CalculateTauFromPaths	(	const py::module_	np,
		py::object	paths ) const

protected

Extract delays (tau) per path from RS paths object.

Returns a vector of delay values for each path aligned with the CIR.

Parameters

np	The numpy_python module reference (py::module_)
paths	Python paths object computed by Sionna RT

Returns: Vector of delays [s], ordered to match CIR taps

Definition at line 726 of file sionna-rt-channel-model.cc.

References data, m_normalizeDelays, m_RtPathSolverConfig, and NS_LOG_FUNCTION.

Referenced by CalculateChannelParamsFromPaths().

Here is the caller graph for this function:

◆ ChannelMatrixNeedsUpdate()

bool ns3::SionnaRtChannelModel::ChannelMatrixNeedsUpdate ( Ptr< const ChannelMatrix > channelMatrix ) const

Determine whether an existing ChannelMatrix must be updated.

Checks if the cached ChannelMatrix is stale because of configuration changes (update period expired or mobility changed). If the update period has passed or the ChannelMatrix metadata differs from the provided inputs, it will report that regeneration is required.

Parameters

channelMatrix The existing channel matrix to check

Returns: true if the matrix must be updated; false otherwise

Definition at line 214 of file sionna-rt-channel-model.cc.

References m_updatePeriod, ns3::Now(), ns3::Simulator::Now(), ns3::Time::NS, NS_LOG_DEBUG, and NS_LOG_FUNCTION.

Referenced by GetChannel().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ CreateNewMatrixChannel()

Ptr< MatrixBasedChannelModel::ChannelMatrix > ns3::SionnaRtChannelModel::CreateNewMatrixChannel	(	const Complex3DVector	hUsn,
		const Ptr< const MobilityModel >	sMob,
		const Ptr< const MobilityModel >	uMob,
		Ptr< const PhasedArrayModel >	sAntenna,
		Ptr< const PhasedArrayModel >	uAntenna ) const

Create a new ChannelMatrix object wrapping a precomputed CIR tensor.

This function converts a 3D array of complex samples into an ns-3 MatrixBasedChannelModel::ChannelMatrix instance. The expected format of hUsn is a Complex3DVector shaped as: [numRxPorts][numTxPorts][numTaps], where each complex entry represents a channel tap (CIR sample) for the corresponding Rx/Tx element pair for a given delay tap index.

The function will populate the ChannelMatrix's internal metadata (ports, tap delays, samplerate assumptions) and will return a Ptr to the created wrapper object. The mobility and antenna pointers are provided primarily to capture metadata and orientation for consistent caching and book-keeping.

Parameters

hUsn	3D complex CIR vector (rx ports x tx ports x taps)
sMob	Mobility model of the transmitter endpoint
uMob	Mobility model of the receiver endpoint
sAntenna	Transmitter PhasedArrayModel
uAntenna	Receiver PhasedArrayModel

Returns: A pointer to the created ChannelMatrix instance

Definition at line 315 of file sionna-rt-channel-model.cc.

References ns3::Create(), ns3::Node::GetId(), and ns3::Simulator::Now().

Referenced by GetNewChannel().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ CreateScene()

py::object ns3::SionnaRtChannelModel::CreateScene	(	const py::module_	rt,
		const Ptr< const MobilityModel >	sMob,
		const Ptr< const MobilityModel >	uMob,
		Ptr< const PhasedArrayModel >	sAntenna,
		Ptr< const PhasedArrayModel >	uAntenna ) const

Create a sionna.rt scene object for the provided endpoints and antennas.

The returned py::object is the Python scene instance and ownership is managed by pybind11. The method uses the RtSceneConfig and frequency set in this class to configure the scene creation.

Parameters

rt	sionna.rt module used to construct Python objects
sMob	Mobility model of the transmitter
uMob	Mobility model of the receiver
sAntenna	Transmitter phased array model
uAntenna	Receiver phased array model

Returns: A Python scene object (py::object)

Definition at line 535 of file sionna-rt-channel-model.cc.

References ns3::DynamicCast(), LoadScene(), m_sceneConfigs, MakePlannarArray(), NS_LOG_DEBUG, NS_LOG_FUNCTION, NS_LOG_INFO, and v.

Referenced by GetChannel().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ DoDispose()

void ns3::SionnaRtChannelModel::DoDispose ( )

overridevirtual

Release references and perform cleanup.

Reimplemented from ns3::Object.

Definition at line 49 of file sionna-rt-channel-model.cc.

References m_channelMatrixMap, m_channelParamsMap, and NS_LOG_FUNCTION.

◆ DoesNumberOfPathsExceedMaximum()

bool ns3::SionnaRtChannelModel::DoesNumberOfPathsExceedMaximum ( size_t numPaths ) const

protected

Determine if the path count exceeds the configured maximum threshold.

Compares a given path count against the m_maxNumberOfPaths attribute to decide whether the channel matrix computation should be rejected or recursively recomputed with reduced solver depth.

Parameters

numPaths Number of paths to check against the threshold

Returns: true if numPaths > m_maxNumberOfPaths; false otherwise

Definition at line 838 of file sionna-rt-channel-model.cc.

References m_maxNumberOfPaths, and NS_LOG_FUNCTION.

Referenced by CalculatePaths().

Here is the caller graph for this function:

◆ GetAntennaElementPattern()

std::string ns3::SionnaRtChannelModel::GetAntennaElementPattern ( Ptr< const AntennaModel > element ) const

Return a string describing the antenna element pattern for Sionna.

This method inspects the ns-3 AntennaModel instance and returns a string that represents the Sionna element pattern (e.g., "isotropic", "3gpp_antenna"). Sionna expects the element description when creating PlanarArray objects for element-level responses.

Parameters

element Pointer to the ns-3 AntennaModel for a single element

Returns: A string representation of the element pattern suitable for Sionna

Definition at line 401 of file sionna-rt-channel-model.cc.

References ns3::DynamicCast(), NS_LOG_DEBUG, and NS_LOG_FUNCTION.

Referenced by MakePlannarArray().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GetChannel()

Ptr< const MatrixBasedChannelModel::ChannelMatrix > ns3::SionnaRtChannelModel::GetChannel	(	Ptr< const MobilityModel >	aMob,
		Ptr< const MobilityModel >	bMob,
		Ptr< const PhasedArrayModel >	aAntenna,
		Ptr< const PhasedArrayModel >	bAntenna )

overridevirtual

Retrieve or generate the channel matrix for the node pair.

Given mobility and antenna pointers for endpoints A/B, this method returns a cached ChannelMatrix if available and up-to-date; otherwise it invokes GetNewChannel to compute a new one using Sionna RT. The cache key is a reciprocal uint64_t encoding of endpoint identifiers.

Parameters

aMob	Mobility model of node A (transmitter or one endpoint).
bMob	Mobility model of node B (receiver or the other endpoint).
aAntenna	Antenna array of node A.
bAntenna	Antenna array of node B.

Returns: A pointer to a const ChannelMatrix instance representing the channel.

Implements ns3::MatrixBasedChannelModel.

Definition at line 233 of file sionna-rt-channel-model.cc.

References AntennaSetupChanged(), CalculateChannelParamsFromPaths(), CalculatePaths(), ChannelMatrixNeedsUpdate(), CreateScene(), ns3::Node::GetId(), ns3::MatrixBasedChannelModel::GetKey(), GetNewChannel(), m_channelMatrixMap, m_channelParamsMap, NS_LOG_DEBUG, NS_LOG_FUNCTION, and NS_LOG_INFO.

Here is the call graph for this function:

◆ GetFrequency()

double ns3::SionnaRtChannelModel::GetFrequency ( ) const

Get the configured center frequency.

Returns: Center frequency in Hz.

Definition at line 176 of file sionna-rt-channel-model.cc.

References m_sceneConfigs, and NS_LOG_FUNCTION.

Referenced by GetTypeId().

Here is the caller graph for this function:

◆ GetMaxNumberOfPaths()

double ns3::SionnaRtChannelModel::GetMaxNumberOfPaths ( ) const

Get the configured maximum number of propagation paths.

Returns: Maximum number of paths allowed in computed channel matrices

See also: SetMaxNumberOfPaths

Definition at line 168 of file sionna-rt-channel-model.cc.

References m_maxNumberOfPaths, NS_LOG_FUNCTION, and NS_LOG_INFO.

Referenced by GetTypeId().

Here is the caller graph for this function:

◆ GetNewChannel()

Ptr< MatrixBasedChannelModel::ChannelMatrix > ns3::SionnaRtChannelModel::GetNewChannel	(	py::object	paths,
		const Ptr< const MobilityModel >	sMob,
		const Ptr< const MobilityModel >	uMob,
		Ptr< const PhasedArrayModel >	sAntenna,
		Ptr< const PhasedArrayModel >	uAntenna ) const

virtual

Compute a new channel matrix for the given node pair using Sionna RT.

This method performs the entire flow:

Create or load an sionna.rt scene
Run the path solver to compute propagation paths
Compute CIRs (per Rx/Tx element and path delays)
Package CIRs into a ChannelMatrix instance and return it

The function accepts the 'paths' object returned by CalculatePaths rather than the Python scene directly to allow callers to separate scene and path computation if desired.

Parameters

paths	Python object describing the computed paths (from CalculatePaths)
sMob	Mobility model of the transmitter endpoint
uMob	Mobility model of the receiver endpoint
sAntenna	Transmitter PhasedArrayModel
uAntenna	Receiver PhasedArrayModel

Returns: A pointer to the newly created ChannelMatrix instance

Definition at line 299 of file sionna-rt-channel-model.cc.

References CalculateCirFromPaths(), CreateNewMatrixChannel(), NS_LOG_DEBUG, and NS_LOG_FUNCTION.

Referenced by GetChannel().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GetNormalizeDelays()

bool ns3::SionnaRtChannelModel::GetNormalizeDelays ( ) const

Query whether path delay normalization is enabled.

Returns: true if Sionna RT delay normalization is enabled.

Definition at line 161 of file sionna-rt-channel-model.cc.

References m_normalizeDelays, and NS_LOG_FUNCTION.

Referenced by GetTypeId().

Here is the caller graph for this function:

◆ GetNumberOfPathsFromCir()

size_t ns3::SionnaRtChannelModel::GetNumberOfPathsFromCir ( const py::object paths ) const

protected

Extract the number of propagation paths from the CIR tensor.

Retrieves the channel impulse response (CIR) data from the Sionna RT paths object and extracts the total number of propagation paths. The CIR is organized as a 6-D numpy array with shape: [num_rx, num_rx_ant, num_tx, num_tx_ant, num_paths, num_time_steps]

This method works identically for both synthetic array and standard array configurations, always reading from dimension 4 (num_paths).

Parameters

paths Python Paths object computed by Sionna RT PathSolver

Returns: Number of propagation paths in the CIR; returns 0 if the array has unexpected dimensionality or is malformed

See also: DoesNumberOfPathsExceedMaximum

Definition at line 822 of file sionna-rt-channel-model.cc.

References m_RtPathSolverConfig, and NS_LOG_FUNCTION.

Referenced by CalculatePaths().

Here is the caller graph for this function:

◆ GetParams()

Ptr< const MatrixBasedChannelModel::ChannelParams > ns3::SionnaRtChannelModel::GetParams	(	Ptr< const MobilityModel >	aMob,
		Ptr< const MobilityModel >	bMob ) const

overridevirtual

Get channel parameters (path info) for a node pair if available.

If the pair has associated ChannelParams in m_channelParamsMap this returns it; otherwise a null pointer is returned.

Parameters

aMob	Mobility model of node A.
bMob	Mobility model of node B.

Returns: A pointer to const ChannelParams or nullptr when not available.

Implements ns3::MatrixBasedChannelModel.

Definition at line 475 of file sionna-rt-channel-model.cc.

References ns3::Node::GetId(), ns3::MatrixBasedChannelModel::GetKey(), m_channelParamsMap, NS_LOG_FUNCTION, and NS_LOG_WARN.

Here is the call graph for this function:

◆ GetPolarizationFromPolSlantAngle()

std::string ns3::SionnaRtChannelModel::GetPolarizationFromPolSlantAngle	(	const double	polSlantAngle,
		const uint8_t	numpol ) const

protected

Convert a polarization slant angle into Sionna RT string representation.

Maps the polarization configuration (defined by slant angle and element count) into one of Sionna's standard polarization strings: "V" (vertical), "H" (horizontal), "VH" (dual polarization), or "cross" (cross-polarization).

Parameters

polSlantAngle	Polarization slant angle in radians (typically 0 or pi/2)
numpol	Number of polarizations per element (1 = single-pol, 2 = dual-pol)

Returns: Sionna polarization string suitable for PlanarArray configuration

Definition at line 419 of file sionna-rt-channel-model.cc.

References NS_LOG_FUNCTION.

Referenced by MakePlannarArray().

Here is the caller graph for this function:

◆ GetRtPathSolverConfig()

SionnaRtChannelModel::RtPathSolverConfig ns3::SionnaRtChannelModel::GetRtPathSolverConfig ( ) const

Retrieve the current path solver configuration.

Returns: A copy of the RtPathSolverConfig currently in use

See also: SetRtPathSolverConfig

Definition at line 592 of file sionna-rt-channel-model.cc.

References m_RtPathSolverConfig.

◆ GetScenario()

std::string ns3::SionnaRtChannelModel::GetScenario ( ) const

Return the configured propagation scenario name.

Returns: the current propagation scenario name

Definition at line 358 of file sionna-rt-channel-model.cc.

References m_sceneConfigs, and NS_LOG_FUNCTION.

Referenced by GetTypeId().

Here is the caller graph for this function:

◆ GetTypeId()

TypeId ns3::SionnaRtChannelModel::GetTypeId ( )

static

Get the ns-3 TypeId for this class.

Returns: the object TypeId

Definition at line 57 of file sionna-rt-channel-model.cc.

References GetFrequency(), GetMaxNumberOfPaths(), GetNormalizeDelays(), GetScenario(), m_cameraLookAt, m_cameraPosition, m_isImageRendered, m_outputImageDirectory, m_outputImageName, m_updatePeriod, ns3::MakeBooleanAccessor(), ns3::MakeBooleanChecker(), ns3::MakeDoubleAccessor(), ns3::MakeDoubleChecker(), ns3::MakeStringAccessor(), ns3::MakeStringChecker(), ns3::MakeTimeAccessor(), ns3::MakeTimeChecker(), ns3::MakeVectorAccessor(), ns3::MakeVectorChecker(), ns3::MilliSeconds(), SetFrequency(), ns3::TypeId::SetGroupName(), SetMaxNumberOfPaths(), SetMergeShapeEnable(), SetNormalizeDelays(), ns3::TypeId::SetParent(), and SetScenario().

Here is the call graph for this function:

◆ LoadScene()

py::object ns3::SionnaRtChannelModel::LoadScene ( const py::module_ rt ) const

protected

Load a Sionna RT scene using the configured scenario name.

Instantiates the scene factory selected by m_sceneConfigs.sceneName. The method detects whether the scenario is:

A built-in Sionna scenario name (e.g., "munich", "simple_street_canyon"), in which case rt.load_scene() is invoked with the scenario name; or
A custom XML file path (filename ending with ".xml"), in which case rt.Scene(filename=...) is called to load from file.

The merge_shapes parameter from m_sceneConfigs is forwarded to control whether the scene loader should merge individual shapes.

Parameters

rt	The imported sionna.rt Python module for scene creation

Returns: A Python Scene object (py::object) ready for transmitter/receiver and path solver configuration

See also: SetScenario, RtSceneConfig

Definition at line 365 of file sionna-rt-channel-model.cc.

References m_sceneConfigs, NS_LOG_DEBUG, NS_LOG_FUNCTION, and NS_LOG_INFO.

Referenced by CreateScene().

Here is the caller graph for this function:

◆ MakePlannarArray()

py::object ns3::SionnaRtChannelModel::MakePlannarArray	(	const py::module_	rt,
		Ptr< const PhasedArrayModel >	antenna ) const

Build a Sionna PlanarArray description from an ns-3 PhasedArrayModel.

This converts antenna element locations, patterns and polarization into a Python PlanarArray object suitable for installation into an sionna.rt scene.

Parameters

rt	sionna.rt module used to construct Python objects
Antenna module	The ns-3 PhasedArrayModel to convert

Returns: A Python PlanarArray object (py::object)

Definition at line 450 of file sionna-rt-channel-model.cc.

References ns3::DynamicCast(), GetAntennaElementPattern(), GetPolarizationFromPolSlantAngle(), NS_LOG_FUNCTION, and NS_LOG_WARN.

Referenced by CreateScene().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ SceneRenderImageToFile()

void ns3::SionnaRtChannelModel::SceneRenderImageToFile	(	const py::module_	rt,
		const py::object	paths,
		const py::object	scene ) const

protected

Render a visualization of the scene and paths to a PNG image file.

If m_isImageRendered is true, this method invokes the Sionna RT rendering pipeline using the specified camera parameters and writes the output image to the file specified by m_outputImageDirectory and m_outputImageName.

The image provides visual debugging of scene geometry and path interactions, which can be useful for validating scenario definitions and understanding propagation mechanisms.

Parameters

rt	The sionna.rt module providing rendering functionality
paths	The Python Paths object containing computed propagation paths
scene	The Python Scene object describing the simulation environment

Definition at line 662 of file sionna-rt-channel-model.cc.

References m_cameraLookAt, m_cameraPosition, m_outputImageDirectory, m_outputImageName, and NS_LOG_INFO.

Referenced by CalculatePaths().

Here is the caller graph for this function:

◆ SetFrequency()

void ns3::SionnaRtChannelModel::SetFrequency ( double f )

Set the center frequency used by the model and scene factories.

The frequency affects antenna patterns, wavelength-dependent computations, and where applicable, factory-specific scene generation (e.g., building materials that might be frequency-specific).

Parameters

f	Center frequency in Hz

Definition at line 135 of file sionna-rt-channel-model.cc.

References m_sceneConfigs, NS_ASSERT_MSG, NS_LOG_FUNCTION, and NS_LOG_INFO.

Referenced by GetTypeId().

Here is the caller graph for this function:

◆ SetMaxNumberOfPaths()

void ns3::SionnaRtChannelModel::SetMaxNumberOfPaths ( double p )

Set the maximum number of propagation paths to retain.

Controls the upper limit on the number of paths that will be accepted from the Sionna RT path solver. If the solver generates more paths than this threshold, the CalculatePaths() method will recursively reduce the solver's max_depth and recompute until the path count falls within bounds. This mechanism ensures that channel matrix complexity remains tractable.

Parameters

p	Maximum number of paths (typically 1 to 1000 depending on antenna arrays and simulation requirements)

See also: GetMaxNumberOfPaths, DoesNumberOfPathsExceedMaximum

Definition at line 145 of file sionna-rt-channel-model.cc.

References m_maxNumberOfPaths, NS_LOG_FUNCTION, and NS_LOG_INFO.

Referenced by GetTypeId().

Here is the caller graph for this function:

◆ SetMergeShapeEnable()

void ns3::SionnaRtChannelModel::SetMergeShapeEnable ( bool cond )

Enable or disable shape merging when loading scenes from sionna.rt.

Controls whether the scene geometry loader merges individual mesh shapes into larger primitives during scene creation. Merging reduces the complexity of geometric primitives passed to the path solver and can improve performance and memory usage for complex scenes at the potential cost of small geometric inaccuracies.

Important notes:

Default behaviour is defined by RtSceneConfig::mergeShapes (default true).
Changing this setting only affects future scene loads / creations; it does not retroactively modify already-loaded scenes or cached channel matrices. To apply this change immediately, existing cached scenes and channel matrices must be invalidated or regenerated.
The setting is forwarded to sionna.rt via the "merge_shapes" argument when calling rt.load_scene(sceneFactory, merge_shapes=...).

Parameters

cond	True to enable shape merging (reduce geometry complexity), false to preserve original, detailed shapes.

Definition at line 128 of file sionna-rt-channel-model.cc.

References m_sceneConfigs, and NS_LOG_FUNCTION.

Referenced by GetTypeId().

Here is the caller graph for this function:

◆ SetNormalizeDelays()

void ns3::SionnaRtChannelModel::SetNormalizeDelays ( bool cond )

Enable or disable normalization of path delays in Sionna RT.

When true, Sionna RT normalizes delays so the first path is at zero delay. When false, raw path delays are returned.

Parameters

cond	True to normalize delays, false to preserve raw delays.

Definition at line 153 of file sionna-rt-channel-model.cc.

References m_normalizeDelays, NS_LOG_FUNCTION, and NS_LOG_INFO.

Referenced by GetTypeId().

Here is the caller graph for this function:

◆ SetRtPathSolverConfig()

void ns3::SionnaRtChannelModel::SetRtPathSolverConfig ( SionnaRtChannelModel::RtPathSolverConfig configs )

Configure the Sionna RT path solver behavior.

Sets all options that control how the path solver traces rays through the scene, including maximum interaction depth, which phenomena to model (LOS, reflections, diffractions, etc.), and whether to use synthetic array processing. These settings remain in effect for all subsequent path computations until changed again.

Parameters

configs RtPathSolverConfig structure containing solver options

See also: GetRtPathSolverConfig, RtPathSolverConfig

Definition at line 580 of file sionna-rt-channel-model.cc.

◆ SetScenario()

void ns3::SionnaRtChannelModel::SetScenario ( const std::string & scenario )

Set the propagation scenario name used by sionna.rt scene factories.

The scenario string selects a pre-defined scene factory within sionna.rt (for example "munich", "simple_street_canyon_with_cars", etc.). The scene name is used by LoadScene/CreateScene to instantiate the geometry.

Parameters

scenario The scene factory name to call in sionna.rt.scene

Definition at line 333 of file sionna-rt-channel-model.cc.

References builtInSceneSionna, m_sceneConfigs, NS_FATAL_ERROR, NS_LOG_FUNCTION, and NS_LOG_INFO.

Referenced by GetTypeId().

Here is the caller graph for this function:

Member Data Documentation

◆ m_cameraLookAt

Vector ns3::SionnaRtChannelModel::m_cameraLookAt

protected

Camera look-at point for scene rendering.

Definition at line 676 of file sionna-rt-channel-model.h.

Referenced by GetTypeId(), and SceneRenderImageToFile().

◆ m_cameraPosition

Vector ns3::SionnaRtChannelModel::m_cameraPosition

protected

Camera position/look-at used by the scene rendering pipeline.

Camera position for scene rendering

Definition at line 675 of file sionna-rt-channel-model.h.

Referenced by GetTypeId(), and SceneRenderImageToFile().

◆ m_channelMatrixMap

std::unordered_map<uint64_t, Ptr<ChannelMatrix> > ns3::SionnaRtChannelModel::m_channelMatrixMap

protected

map containing the channel realizations per pair of PhasedAntennaArray instances, the key of this map is reciprocal uniquely identifies a pair of PhasedAntennaArrays

Definition at line 649 of file sionna-rt-channel-model.h.

Referenced by DoDispose(), and GetChannel().

◆ m_channelParamsMap

std::unordered_map<uint64_t, Ptr<SionnaRtChannelParams> > ns3::SionnaRtChannelModel::m_channelParamsMap

protected

map containing the common channel parameters per pair of nodes, the key of this map is reciprocal and uniquely identifies a pair of nodes

Definition at line 653 of file sionna-rt-channel-model.h.

Referenced by DoDispose(), GetChannel(), and GetParams().

◆ m_isImageRendered

bool ns3::SionnaRtChannelModel::m_isImageRendered

protected

Control for whether we should render a scene image.

Definition at line 670 of file sionna-rt-channel-model.h.

Referenced by CalculatePaths(), and GetTypeId().

◆ m_maxNumberOfPaths

double ns3::SionnaRtChannelModel::m_maxNumberOfPaths

protected

Maximum number of paths to be generated by the path solver.

Definition at line 673 of file sionna-rt-channel-model.h.

Referenced by CalculatePaths(), DoesNumberOfPathsExceedMaximum(), GetMaxNumberOfPaths(), and SetMaxNumberOfPaths().

◆ m_normalizeDelays

bool ns3::SionnaRtChannelModel::m_normalizeDelays

protected

Whether Sionna RT should normalize path delays in CIR output.

Definition at line 672 of file sionna-rt-channel-model.h.

Referenced by CalculateCirFromPaths(), CalculateTauFromPaths(), GetNormalizeDelays(), and SetNormalizeDelays().

◆ m_outputImageDirectory

std::string ns3::SionnaRtChannelModel::m_outputImageDirectory

protected

Output directory.

Definition at line 667 of file sionna-rt-channel-model.h.

Referenced by GetTypeId(), and SceneRenderImageToFile().

◆ m_outputImageName

std::string ns3::SionnaRtChannelModel::m_outputImageName

protected

Output image rendering options (file name/directory).

Output file name

Definition at line 666 of file sionna-rt-channel-model.h.

Referenced by GetTypeId(), and SceneRenderImageToFile().

◆ m_RtPathSolverConfig

RtPathSolverConfig ns3::SionnaRtChannelModel::m_RtPathSolverConfig

protected

Path solver configuration used when computing paths.

Definition at line 660 of file sionna-rt-channel-model.h.

Referenced by CalculateAnglesFromPaths(), CalculateDopplerFromPaths(), CalculatePaths(), CalculateTauFromPaths(), GetNumberOfPathsFromCir(), GetRtPathSolverConfig(), and SetRtPathSolverConfig().

◆ m_sceneConfigs

RtSceneConfig ns3::SionnaRtChannelModel::m_sceneConfigs

protected

High-level scene configuration.

Definition at line 663 of file sionna-rt-channel-model.h.

Referenced by CreateScene(), GetFrequency(), GetScenario(), LoadScene(), SetFrequency(), SetMergeShapeEnable(), and SetScenario().

◆ m_updatePeriod

Time ns3::SionnaRtChannelModel::m_updatePeriod

protected

Channel update period used to decide whether to re-run path computations.

Definition at line 657 of file sionna-rt-channel-model.h.

Referenced by ChannelMatrixNeedsUpdate(), and GetTypeId().

The documentation for this class was generated from the following files:

src/spectrum/model/sionna-rt-channel-model.h
src/spectrum/model/sionna-rt-channel-model.cc

Classes

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ SionnaRtChannelModel()

◆ ~SionnaRtChannelModel()

Member Function Documentation

◆ AntennaSetupChanged()

◆ AssignStreams()

◆ CalculateAnglesFromPaths()

◆ CalculateChannelParamsFromPaths()

◆ CalculateCirFromPaths()

◆ CalculateDopplerFromPaths()

◆ CalculatePaths()

◆ CalculateTauFromPaths()

◆ ChannelMatrixNeedsUpdate()

◆ CreateNewMatrixChannel()

◆ CreateScene()

◆ DoDispose()

◆ DoesNumberOfPathsExceedMaximum()

◆ GetAntennaElementPattern()

◆ GetChannel()

◆ GetFrequency()

◆ GetMaxNumberOfPaths()

◆ GetNewChannel()

◆ GetNormalizeDelays()

◆ GetNumberOfPathsFromCir()

◆ GetParams()

◆ GetPolarizationFromPolSlantAngle()

◆ GetRtPathSolverConfig()

◆ GetScenario()

◆ GetTypeId()

◆ LoadScene()

◆ MakePlannarArray()

◆ SceneRenderImageToFile()

◆ SetFrequency()

◆ SetMaxNumberOfPaths()

◆ SetMergeShapeEnable()

◆ SetNormalizeDelays()

◆ SetRtPathSolverConfig()

◆ SetScenario()

Member Data Documentation

◆ m_cameraLookAt

◆ m_cameraPosition

◆ m_channelMatrixMap

◆ m_channelParamsMap

◆ m_isImageRendered

◆ m_maxNumberOfPaths

◆ m_normalizeDelays

◆ m_outputImageDirectory

◆ m_outputImageName

◆ m_RtPathSolverConfig

◆ m_sceneConfigs

◆ m_updatePeriod