Scene

Scene, Transmitter, Receiver, and ReceiverGrid API reference

Overview #

The scene API is the entry point for all WiTwin Channel simulations. A Scene holds geometry, materials, transmitters, and receivers. All solver calls take a Scene as their first argument.

import witwin.channel as wc
 
scene = wc.Scene(
    structures=[...],
    transmitters=[...],
    receivers=[...],
    frequency=3.5e9,
    device="cuda",
)

Scene #

Constructor #

Parameter	Type	Default	Description
`structures`	`list[Structure]`	`[]`	List of geometry and material objects
`transmitters`	`list[Transmitter]`	`[]`	List of transmitter endpoints
`receivers`	`list[Receiver \| ReceiverGrid]`	`[]`	List of receiver endpoints
`frequency`	`float \| None`	`None`	Carrier frequency in Hz
`device`	`str`	`"cuda"`	PyTorch device string
`tx_array`	`AntennaArray \| None`	`None`	Default transmit antenna array
`rx_array`	`AntennaArray \| None`	`None`	Default receive antenna array
`verbose`	`bool`	`False`	Enable verbose build logging

Methods #

scene.add(obj) — Add a Structure, Transmitter, Receiver, or ReceiverGrid to the scene after construction.

scene.add(wc.Structure(name="wall", geometry=wc.Box(...), material=wc.Material(...)))
scene.add(wc.Transmitter("tx", (0.0, 0.0, 1.5)))

scene.structure(name) — Get a handle to a named structure for runtime mutation.

scene.structure("wall").set_material_parameters(eps_r=wc.Float(4.0))

scene.transmitter(name) — Get a named transmitter endpoint.

scene.receiver(name) — Get a named receiver endpoint.

scene.clone(**overrides) — Return a copy of the scene with selected fields replaced.

scene.sync() — Sync the RayD BVH after mesh vertex updates.

Scene.load_mitsuba(filename, **kwargs) — Load a scene from a Mitsuba XML file. See Import 3D Models.

Scene.from_sionna(sionna_scene, **kwargs) — Import a sionna.rt.Scene object.

scene.to_sionna(**kwargs) — Export the scene to Sionna RT format.

Properties #

Property	Description
`scene.frequency`	Carrier frequency in Hz. Can be set after construction
`scene.transmitters`	List of transmitter endpoints
`scene.receivers`	List of receiver endpoints
`scene.structures`	List of structures
`scene.vertices`	Merged scene vertex positions
`scene.faces`	Merged scene face indices
`scene.n_diffraction_edges`	Number of active diffraction edges

Transmitter #

A radio source placed at a fixed position in the scene.

wc.Transmitter(
    name="tx",
    position=(0.0, 0.0, 1.5),
    polarization=(1.0, 0.0, 0.0),
    power=1.0,
)

Parameter	Type	Default	Description
`name`	`str`	required	Unique name used to reference this transmitter in solver calls
`position`	`tuple[float, float, float]`	required	3D position in world coordinates
`polarization`	`tuple[float, float, float]`	`(1.0, 0.0, 0.0)`	Polarization direction vector
`power`	`float`	`1.0`	Transmit power. Must be > 0
`orientation`	`tuple[float, float, float] \| None`	`None`	Orientation vector
`array`	`AntennaArray \| None`	`None`	Per-transmitter antenna array override

Receiver #

A single-point receiver that captures the signal at a fixed position.

wc.Receiver(
    name="rx",
    position=(2.0, 0.0, 1.5),
)

Parameter	Type	Default	Description
`name`	`str`	required	Unique name used to reference this receiver in solver calls
`position`	`tuple[float, float, float]`	required	3D position in world coordinates
`polarization`	`tuple[float, float, float] \| None`	`None`	Receive polarization direction
`orientation`	`tuple[float, float, float] \| None`	`None`	Orientation vector
`array`	`AntennaArray \| None`	`None`	Per-receiver antenna array override

ReceiverGrid #

An axis-aligned 2D grid of receivers for computing coverage maps.

wc.ReceiverGrid(
    name="rm",
    axis="z",
    position=1.5,
    bounds=((-5.0, 5.0), (-5.0, 5.0)),
    grid_shape=(32, 32),
)

Parameter	Type	Default	Description
`name`	`str`	required	Unique name used to reference this grid in solver calls
`axis`	`"x" \| "y" \| "z"`	required	Normal axis of the receiver plane
`position`	`float`	required	Position along the normal axis
`bounds`	`((min0, max0), (min1, max1))`	required	Extent of the grid in the two tangential directions
`grid_shape`	`tuple[int, int] \| None`	`None`	Fixed grid resolution as `(nx, ny)`
`cell_size`	`float \| tuple[float, float] \| None`	`None`	Cell size in meters. Used if `grid_shape` is not set
`polarization`	`tuple[float, float, float] \| None`	`None`	Receive polarization direction
`orientation`	`tuple[float, float, float] \| None`	`None`	Orientation vector
`array`	`AntennaArray \| None`	`None`	Per-grid antenna array override

Note

Either grid_shape or cell_size must be provided.

Next Steps #

Geometry — Box, Structure, Material reference
Solvers — solver configuration reference