Core Classes API Reference

Fundamental classes that form the backbone of WiTwin

This section covers the fundamental classes that form the backbone of WiTwin.

Environment #

The Environment class represents the simulation environment where all wireless propagation takes place.

Constructor #

wt.Environment(
    frequency: float,
    bandwidth: float = 1e9,
    temperature: float = 293.15,
    resolution: Tuple[int, int] = (1024, 1024),
    bounds: Optional[Tuple[float, float, float, float, float, float]] = None
)

Parameters #

Parameter	Type	Default	Description
`frequency`	float	-	Operating frequency in Hz
`bandwidth`	float	1e9	Signal bandwidth in Hz
`temperature`	float	293.15	Ambient temperature in Kelvin
`resolution`	Tuple[int, int]	(1024, 1024)	Spatial resolution for ray tracing
`bounds`	Optional[Tuple]	None	Environment bounds [xmin, ymin, zmin, xmax, ymax, zmax]

Methods #

`add_device(device: Union[Transmitter, Receiver]) -> None`

Adds a wireless device to the environment.

env = wt.Environment(frequency=60e9)
tx = wt.Transmitter(position=[0, 0, 10])
env.add_device(tx)

`add_object(obj: Object) -> None`

Adds a physical object to the environment.

wall = wt.Object(shape='box', dimensions=[10, 0.3, 3])
env.add_object(wall)

`simulate(config: Optional[SimulationConfig] = None) -> SimulationResults`

Runs the ray tracing simulation.

results = env.simulate()
# or with custom config
config = wt.SimulationConfig(max_reflections=5)
results = env.simulate(config)

`compute_coverage(transmitter: Transmitter, height: float = 1.5) -> np.ndarray`

Computes coverage map at specified height.

coverage_map = env.compute_coverage(tx, height=2.0)

Transmitter #

Represents a wireless transmitter device.

Constructor #

wt.Transmitter(
    position: List[float],
    orientation: List[float] = [0, 0, 0],
    power_dbm: float = 30,
    antenna: Optional[Antenna] = None,
    frequency: Optional[float] = None
)

Parameters #

Parameter	Type	Default	Description
`position`	List[float]	-	3D position [x, y, z] in meters
`orientation`	List[float]	[0, 0, 0]	Euler angles [roll, pitch, yaw] in degrees
`power_dbm`	float	30	Transmit power in dBm
`antenna`	Optional[Antenna]	Isotropic	Antenna pattern object
`frequency`	Optional[float]	None	Override environment frequency

Properties #

position: Get/set transmitter position
orientation: Get/set transmitter orientation
power_dbm: Get/set transmit power
power_watts: Get transmit power in watts

Example #

# Create a directional transmitter
tx = wt.Transmitter(
    position=[0, 0, 5],
    orientation=[0, 0, 45],  # 45 degrees yaw
    power_dbm=23,
    antenna=wt.antennas.HornAntenna(gain_dbi=15)
)

Receiver #

Represents a wireless receiver device.

Constructor #

wt.Receiver(
    position: List[float],
    orientation: List[float] = [0, 0, 0],
    antenna: Optional[Antenna] = None,
    noise_figure: float = 3.0,
    frequency: Optional[float] = None
)

Parameters #

Parameter	Type	Default	Description
`position`	List[float]	-	3D position [x, y, z] in meters
`orientation`	List[float]	[0, 0, 0]	Euler angles [roll, pitch, yaw] in degrees
`antenna`	Optional[Antenna]	Isotropic	Antenna pattern object
`noise_figure`	float	3.0	Receiver noise figure in dB
`frequency`	Optional[float]	None	Override environment frequency

Methods #

`calculate_noise_power(bandwidth: float) -> float`

Calculates thermal noise power for given bandwidth.

rx = wt.Receiver(position=[10, 0, 1.5])
noise_power_dbm = rx.calculate_noise_power(bandwidth=100e6)

Object #

Represents physical objects in the environment.

Constructor #

wt.Object(
    shape: str,
    dimensions: List[float],
    position: List[float] = [0, 0, 0],
    orientation: List[float] = [0, 0, 0],
    material: Union[str, Material] = 'concrete',
    velocity: Optional[List[float]] = None
)

Parameters #

Parameter	Type	Default	Description
`shape`	str	-	Object shape: 'box', 'sphere', 'cylinder', 'mesh'
`dimensions`	List[float]	-	Shape-specific dimensions
`position`	List[float]	[0, 0, 0]	Center position [x, y, z]
`orientation`	List[float]	[0, 0, 0]	Euler angles [roll, pitch, yaw]
`material`	Union[str, Material]	'concrete'	Material properties
`velocity`	Optional[List[float]]	None	Velocity vector [vx, vy, vz] m/s

Shape Dimensions #

Shape	Dimensions
box	`[width, depth, height]`
sphere	`[radius]`
cylinder	`[radius, height]`
mesh	`[scale]` (requires `mesh_file` parameter)

Example #

# Create a moving metal sphere
sphere = wt.Object(
    shape='sphere',
    dimensions=[2.0],  # 2m radius
    position=[5, 5, 2],
    material='metal',
    velocity=[10, 0, 0]  # Moving at 10 m/s in x-direction
)

Material #

Defines electromagnetic properties of materials.

Constructor #

wt.Material(
    name: str,
    permittivity: complex,
    permeability: complex = 1.0,
    conductivity: float = 0.0,
    frequency_dependent: bool = False
)

Predefined Materials #

# Built-in materials
concrete = wt.materials.CONCRETE
metal = wt.materials.METAL
glass = wt.materials.GLASS
wood = wt.materials.WOOD

Custom Material #

# Create custom material
custom_material = wt.Material(
    name='special_absorber',
    permittivity=4.5 - 0.1j,
    conductivity=0.01
)

Antenna Patterns #

Isotropic #

antenna = wt.antennas.Isotropic()

Directional #

antenna = wt.antennas.DirectionalAntenna(
    gain_dbi=10,
    beamwidth_h=60,  # Horizontal beamwidth in degrees
    beamwidth_v=30   # Vertical beamwidth in degrees
)

Patch Antenna #

antenna = wt.antennas.PatchAntenna(
    gain_dbi=6,
    width=0.05,  # Physical dimensions
    height=0.05
)

Horn Antenna #

antenna = wt.antennas.HornAntenna(
    gain_dbi=15,
    aperture_width=0.1,
    aperture_height=0.08
)

Array Antenna #

antenna = wt.antennas.ArrayAntenna(
    element_pattern=wt.antennas.PatchAntenna(),
    n_elements=4,
    spacing=0.5,  # In wavelengths
    weights=np.array([1, 1, 1, 1])  # Complex weights for beamforming
)

Next Steps #

Learn about Simulation Engine for advanced simulation options
Explore Utilities for helper functions and tools
See Examples for practical implementations