Position

Groups together common classes and functions for randomly sampling physical device positions in environments.

Position dataclass

A concrete instantiation of a device's position in the environment.

Parameters:

Name	Type	Description	Default
x	float	x coordinate	required
y	float	y coordinate	required
z	float	z coordinate	required

SpatialDistribution

Bases: Protocol

All devices are required to include a SpatialDistribution.

A SpatialDistribution is any Callable returns a randomly sampled Position each time it is invoked.

__call__()

Randomly sample a Position from an underlying distribution.

Returns A randomly sampled Position.

get_null_distribution(x=0, y=0, z=0)

Get a trivial or (null) SpatialDistribution that always samples the same Position.

Parameters:

Name	Type	Description	Default
x	float	x coordinate	0
y	float	y coordinate	0
z	float	z coordinate	0

Returns:

Type	Description
SpatialDistribution	A SpatialDistribution that always returns the same Position as described by x, y and z.

Example

>>> distribution = get_null_distribution(1, 2)
>>> distribution()
Position(x=1, y=2, z=0)

get_uniform_distribution(x_bounds, y_bounds, z_bounds)

Get a SpatialDistribution that samples uniformly from some 3D bounds.

Parameters:

Name	Type	Description	Default
x_bounds	tuple[float, float]	Desired interval for the x coordinate	required
y_bounds	tuple[float, float]	Desired interval for the y coordinate	required
z_bounds	tuple[float, float]	Desired interval for the z coordinate	required

Returns:

Type	Description
SpatialDistribution	A SpatialDistribution that returns a uniformly-sampled Position according to the provided bounds.

Example

>>> distribution = get_uniform_distribution((0, 10), (0, 10), (0, 5))
>>> distribution()
Position(x=9.82526, y=1.6853619, z=1.1326883)

Raises:

Type	Description
ValueError	If bounds[1] < bounds[0].