Base Environment

Defines the BaseEnvironment that all Torchradio environments are expected to inherit from.

`BaseEnvironment`

Bases: ABC

Abstract base class for Torchradio environments.

The core concept behind Torchradio is the use of a common simulation environment that enables backpropagation from the loss function back to the transmitters. It is assumed that all environments used with Torchradio are child classes of BaseEnvironment. The BaseEnvironment automates many common operations, such as device placement, noise simulation and signal aggregation.

All child classes of BaseEnvironment are expected to implement the abstract methods: _compute_propagation_parameters, _in_bounds, _propagate and _get_background_noise.

`devices: dict[str, dict[str, Position]]` `property`

Get a dictionary that summarizes the environment's devices with their current positions.

Returns Two maps. One that maps transmitter names to positions and one that maps receiver names to positions.

`n_devices: int` `property`

Get current number of devices.

Returns The number of devices placed in the environment.

`n_receivers: int` `property`

Get current number of receivers.

Returns The number of receivers placed in the environment.

`n_transmitters: int` `property`

Get current number of transmitters.

Returns The number of transmitters placed in the environment.

`receivers: dict[str, Position]` `property`

Get current receivers and their positions.

Returns A map from receiver names to positions

`transmitters: dict[str, Position]` `property`

Get current transmitters and their positions.

Returns A map from transmitter names to positions

`init(*, disable_differentiability_check=False)`

Create a clean environment that can be populated with devices.

`is_differentiable()`

Check the environment is differentiable.

Gotcha: The differentiability check assumes that devices can be placed at Position(x=0, y=0, z=0). If this is impossible, you must either write your own differentiability check, or alter your environment to allow placements at the origin.

Gotcha: As part of the differentiability check, the environment will be reset. If you have devices placed in the environment before calling this function, they will need to be re-placed afterwards.

Returns:

Type	Description
`bool`	True if the environment passes a basic differentiability test, where the output magnitude of a simple transmitter is driven to zero. If your environment is incorrectly classified as non-differentiable, please raise an issue at the repository issue tracker.

Example

>>> env = torchradio.env.null.NullEnvironment()
>>> env.is_differentiable()
True

`place(transmitters, receivers)`

Place devices in the environment.

Child classes must specify whether a device is in or out-of-bounds via the _in_bounds method. After the devices have been placed, self._compute_propagation_parameters() is called to determine simulation parameters. These simulation parameters do not need to be recomputed until the devices have been re-placed.

Parameters:

Name	Type	Description	Default
`transmitters`	`dict[str, Transmitter]`	Maps device names to `Transmitter`s.	required
`receivers`	`dict[str, Receiver]`	Maps device names to `Receivers`s.	required

Example

>>> transmitter_1 = torchradio.algorithm.null.get_constant_transmitter(1 + 1j)
>>> transmitter_2 = torchradio.algorithm.null.get_constant_transmitter(1 + 0j)
>>> transmitter_3 = torchradio.algorithm.null.get_null_transmitter()
>>> receiver = torchradio.algorithm.null.get_null_receiver()
>>> some_transmitters = {"tx1": transmitter_1, "tx2": transmitter_2}
>>> other_transmitters = {"tx3": transmitter_3}
>>> all_transmitters = {**some_transmitters, **other_transmitters}
>>> receivers = {"rx": receiver}
>>> env = torchradio.env.null.NullEnvironment()
>>> env.place(some_transmitters, receivers)
>>> env.n_devices
3
>>> env.place(all_transmitters, receivers)
>>> env.n_devices
4

Raises:

Type	Description
`ValueError`	No receivers provided.
`TypeError`	A non-`Transmitter` was found in `transmitters` or a non-`Receiver` was found in `receivers`.

`reset()`

Remove all devices from the environment.

Example

>>> env.place(...)
>>> env.n_devices
8
>>> env.reset()
>>> env.n_devices
0

`simulate(n_timesteps, batch_size=1)`

Run the simulation for n_timesteps with batch_size.

Parameters:

Name	Type	Description	Default
`n_timesteps`	`int`	How many timesteps to simulate. Must be positive.	required
`batch_size`	`int`	How many batches to simulate. Must be positive.	`1`

Returns:

Type	Description
`DeviceLogs`	Device logs for benchmarking performance and computing gradients.

Example

>>> transmitter = torchradio.algorithm.null.get_null_transmitter()
>>> receiver = torchradio.algorithm.null.get_null_receiver()
>>> env = torchradio.env.null.NullEnvironment()
>>> env.place({"tx": transmitter}, {"rx": receiver})
>>> env.simulate(20, 3)

Raises:

Type	Description
`ValueError`	If a provided `SpatialDistribution` is incompatible with the environment according to the child class `_in_bounds` methods.
`RuntimeError`	If child classes don't correctly implement `_propagate` or `_get_background_noise` to account for all devices.

`visualize(*, show=True, save_path=None)`

Visualize the environment with the currently placed devices.

It is not mandatory for child classes to override this method. However, it may make it easier for users to interact with the environment if they are provided with a convenient visualization method to see where devices are currently placed.

Parameters:

Name	Type	Description	Default
`show`	`bool`	Show an interactive plot within the Python process.	`True`
`save_path`	`PathLike \| None`	Path to save the visualization to.	`None`

Base Environment