Sampling

We partially expose to Python the class navground::sim::PropertySampler, which generates values of type navground.core.PropertyField: booleans, integers, floating-point numbers, strings, 2D vectors, and list of these scalar types.

class Sampler

This class wraps a typed Sampler to generate values of type PropertyField

count() → int

Counts the number of sampled values since reset.

If once is set, only the first call to sample() counts, until it is reset().

Returns:

The number of sampled values

done() → bool

Returns whether the generator is exhausted. In this case, sample() will raise an error.

Returns:

True if the generator is exhausted.

dump() → str

Dumps the object to a YAML-string.

Returns:

The YAML representation

Return type:

str

static load(value: str, type_name: str) → navground.sim.Sampler

Load a Sampler from a YAML string.

Parameters:

• value – The YAML string.

• type_name – The samples type name.

Returns:

The loaded Sampler or None if loading fails.

Return type:

Sampler| None

reset(index: int | None = None, keep: bool = False) → None

Resets the generator.

The index is used by deterministic samplers: they will generates the same sequence if reset to the same index, without using the (pseudo) random-number generator in sample().

Argument keep and configuration once impact how generators reset their index and counter: if neither keep nor once are set, the sampler sets both index and counter to 0; else the index is set to the provided value if not null, and the counter is left unchanged.

Argument keep also impacts the behavior of samplers configured with once set: if keep is set, the sampler will keep returning the same value as before resetting; else, it will return a new value (associate to the new index, if deterministic).

Parameters:

• index – The next sample index (for deterministic samplers).

• keep – Whether to avoid resetting index to 0 when once is not set.

sample(world: navground.sim.NativeWorld) → bool | int | float | str | Vector2 | list[bool] | list[int] | list[float] | list[str] | list[Vector2]

Draws a sample using the world’s random generator.

Parameters:

world – The world.

Raises:

RuntimeError – When the generator is exhausted (i.e., when done() returns true)

Returns:

The new sample

property once

Type:

bool

Whenever to sample only once and than output the same constant value until reset.

property type_name

Type:

str

The samples type name

load_sampler(value: str, type_name: str) → Sampler | None

load(value: str, type_name: str) -> navground.sim.Sampler

Load a Sampler from a YAML string.

Parameters:

• value – The YAML string.

• type_name – The samples type name.

Returns:

The loaded Sampler or None if loading fails.

Return type:

Sampler| None

Samplers cannot be introspected and modified from Python but can be loaded from YAML:

>>> from navground import sim

>>> sampler = sim.load_sampler("{sampler: uniform, from: 1, to: 10}", type_name="int")
>>> sampler
<Sampler: int>

Note

It requires the samples type name, i.e., one of "bool", "int", "float", "vector", "str", "[bool]", "[int]", "[float]", "[vector]", "[str]".

Samples can then be generated by passing a world, whose random generator is need to generate random numbers:

>>> world = sim.World()
>>> world.seed = 123
>>> sampler.sample(w)
2

Note

navground::sim::PropertySampler is used internally to implement navground::sim::Scenario::init_world(), which samples a world from a YAML representation containing such samplers.

The main utility of navground.sim.Sampler is instead for testing. Although it could be used to implement navground.sim.Scenario.init_world() for new scenarios, in Python there are alternative random generators. In particular, numpy.random.Generator is also exposed in navground. For example, the uniform sampling in the example above could be implemented using numpy as

>>> world = sim.World()
>>> world.seed = 123
>>> world.random_generator.integers(low=0, high=10)
0

Agents

class AgentSampler

add_to_world(world: navground.sim.NativeWorld, seed: int | None = None) → None

Generate and add agents to the world.

Parameters:

• world – The world

• seed – An optional random seed

count() → int

Counts the number of sampled values since reset.

If once is set, only the first call to sample() counts, until it is reset().

Returns:

The number of sampled values

done() → bool

Returns whether the generator is exhausted. In this case, sample() will raise an error.

Returns:

True if the generator is exhausted.

dump() → str

Dumps the object to a YAML-string.

Returns:

The YAML representation

Return type:

str

static load(value: str) → object

Load a group from a YAML string.

Parameters:

value – the YAML string.

Returns:

The loaded group or None if loading fails.

Return type:

AgentSampler| None

reset(index: int | None = None, keep: bool = False) → None

sample(world: navground.sim.NativeWorld) → object

Draws a sample using the world’s random generator.

Parameters:

world – The world.

Raises:

RuntimeError – When the generator is exhausted (i.e., when done() returns true)

Returns:

The new sample

property once

Type:

bool

Whenever to sample only once and than output the same constant value until reset.

load_group(value: str) → Group | None

load(value: str) -> object

Load a group from a YAML string.

Parameters:

value – the YAML string.

Returns:

The loaded group or None if loading fails.

Return type:

AgentSampler| None