Sampling

Contents

Sampling#

Samplers#

#include "navground/sim/sampling/sampler.h"

Base class#

template<typename T>
struct Sampler#

Abstract Sampler base class. that allows to sample values of type T using sample.

Template Parameters:

T – The sampled type

Param once:

[in] Whether to repeat the first sample (until reset)

Subclassed by navground::sim::BinarySampler< T >, navground::sim::ChoiceSampler< T >, navground::sim::ConstantSampler< T >, navground::sim::NormalSampler< T >, navground::sim::RegularSampler< T >, navground::sim::SequenceSampler< T >, navground::sim::UniformSampler< T >

Public Functions

inline T sample(RandomGenerator &rg)#

Sample values of type T.

Throws:

std::runtime_error – If the generator is exhausted (i.e., done returns true)

Parameters:

rg – [in] A random generator

Returns:

The sampled value.

inline virtual unsigned count() const#

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

inline virtual bool done() const#

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

Returns:

True if the generator is exhausted.

inline virtual void reset(std::optional<unsigned> index = std::nullopt, bool keep = false)#

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 – [in] The next sample index (for deterministic samplers).

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

Public Members

bool once#

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

enum class navground::sim::Wrap#

What should a generator do at the end of a sequence.

Values:

enumerator loop#

Start from scratch

enumerator repeat#

Repeat the last entry

enumerator terminate#

Terminate

Generic#

template<typename T>
struct ConstantSampler : public navground::sim::Sampler<T>#

An inexhaustible generator that always returns the same value.

Template Parameters:

T – The sampled type

Public Functions

inline explicit ConstantSampler(T value, bool once = false)#

Construct an instance.

Parameters:

  • value – [in] The constant value

  • once – [in] Whether to repeat the first sample (until reset)

template<typename T>
struct SequenceSampler : public navground::sim::Sampler<T>#

An generator that loops through a sequence of values.

If wrap is not set to Wrap::terminate, the generator is inexhaustible, else it will be exhausted after looping once through all values once.

Template Parameters:

T – The sampled type

Public Functions

inline explicit SequenceSampler(const std::vector<T> &values, Wrap wrap = Wrap::loop, bool once = false)#

Construct an instance.

Parameters:

  • values – [in] The values to be sampled in sequence

  • wrap – [in] How it should wrap at the end of the sequence

  • once – [in] Whether to repeat the first sample (until reset)

template<typename T>
struct ChoiceSampler : public navground::sim::Sampler<T>#

An inexhaustible generator that randomly draw from a collection of values with replacement.

Template Parameters:

T – The sampled type

Public Functions

inline explicit ChoiceSampler(const std::vector<T> &values, const std::vector<double> &probabilities = {}, bool once = false)#

Construct an instance.

For example, if there are 4 values and 2 weights {0.2, 0.6}, the weights will be completed as {0.2, 0.6, 0.1, 0.1}.

Passing an empty vector (the default) creates a discrete uniform distribution.

Parameters:

  • values – [in] The values. Should have at least length 1.

  • probabilities – [in] The probability weight for each value. Can but must not be normalized. Exceeding weights (with respect to the number of values) are ignored. Missing weights are assigned a uniform value, so that the total sum is 1.

  • once – [in] Whether to repeat the first sample (until reset)

Numbers#

template<typename T>
struct UniformSampler : public navground::sim::Sampler<T>#

Sample randomly from a uniform distribution.

Only defined if T is a number or a Vector2.

Template Parameters:

T – The sampled type

Param once:

[in] Whether to repeat the first sample (until reset)

template<typename T>
struct NormalSampler : public navground::sim::Sampler<T>#

Sample randomly from a normal distribution.

Values are optionally clamped when min and/or max are provided.

Only defined if T is a number.

Template Parameters:

T – The sampled type

Public Functions

inline NormalSampler(ng_float_t mean, ng_float_t std_dev, std::optional<T> min = std::nullopt, std::optional<T> max = std::nullopt, bool once = false, bool clamp = true)#

Construct an instance.

Parameters:

  • mean – [in] The mean

  • std_dev – [in] The standard deviation

  • min – [in] The minimum value

  • max – [in] The maximum value

  • once – [in] Whether to repeat the first sample (until reset)

  • clamp – [in] Whether to clamp the values in [min, max]

2D Vectors#

struct GridSampler : public navground::sim::Sampler<Vector2>#

RegularSamplerly sample from a grid of points.

If wrap is not set to Wrap::terminate, the generator is inexhaustible, else it will be exhausted after looping once through all values once.

Public Functions

inline explicit GridSampler(const Vector2 &from, const Vector2 &to, std::array<unsigned, 2> numbers, Wrap wrap = Wrap::loop, bool once = false)#

Construct an instance.

Parameters:

  • from – [in] One corner of the covered area

  • to – [in] The opposite corner of the covered area

  • numbers – [in] The size of the grid, i.e., the number of points along the x- and y-axis.

  • wrap – [in] How it should wrap at end of the covered area

  • once – [in] Whether to repeat the first sample (until reset)

struct NormalSampler2D : public navground::sim::Sampler<Vector2>#

Sample navground::core::Vector2 from a multivariate normal distribution.

Public Functions

inline NormalSampler2D(const Vector2 &mean, std::array<ng_float_t, 2> std_dev, ng_float_t angle = 0, bool once = false)#

Construct an instance.

Parameters:

  • mean – [in] The mean

  • std_dev – [in] The standard deviation eigenvalues.

  • angle – [in] The rotation of the eigenvectors

  • once – [in] Whether to repeat the first sample (until reset)

Numbers and 2D vectors#

template<typename T>
struct RegularSampler : public navground::sim::Sampler<T>#

An generator that sample regularly, adding a fixed step to the previous sample.

Only defined if T is an algebra.

If wrap is not set to Wrap::terminate, the generator is inexhaustible, else it will be exhausted after looping once through all values.

Template Parameters:

T – The sampled type

Public Static Functions

static inline RegularSampler make_with_interval(const T &from, const T &to, unsigned number, Wrap wrap = Wrap::loop, bool once = false)#

Construct a sampler that will samples number points between from and to.

For example, number=3, samples the following points: from, (from + to) / 2, to.

Parameters:

  • from – [in] The first value

  • to – [in] The target value to be reached after number samples.

  • number – [in] The number of samples to draw.

  • wrap – [in] How it should wrap at the end of the interval (i.e., after number samples have been drawn)

  • once – [in] Whether to repeat the first sample (until reset)

Returns:

The sampler.

static inline RegularSampler make_with_step(const T &from, const T &step, std::optional<unsigned> number = std::nullopt, Wrap wrap = Wrap::loop, bool once = false)#

Construct a sampler that will samples points, iteratively adding step.

For example, step=1, samples the following points: from, from + 1, `from + 2, …

Parameters:

  • from – [in] The first value

  • step – [in] The step

  • number – [in] The number of samples to draw

  • wrap – [in] How it should wrap at the end of the interval (i.e., after number samples have been drawn)

  • once – [in] Whether to repeat the first sample (until reset)

Numbers and booleans#

template<typename T>
struct BinarySampler : public navground::sim::Sampler<T>#

An inexhaustible generator of iid binary values sampled from a Bernoulli distribution.

Template Parameters:

T – The sampled type

Public Functions

inline explicit BinarySampler(const double &probability = 0.5, bool once = false)#

Construct an instance.

Parameters:

  • probability – [in] The probability of the positive value in [0, 1]

  • once – [in] Whether to repeat the first sample (until reset)

Lists of scalars#

template<typename T>
struct UniformSizeSampler : public navground::sim::Sampler<std::vector<T>>#

An generator of lists of scalars sampled iid from sampler.

The size of the lists (std::vector) is sampled uniformly.

Template Parameters:

T – The scalar type

Public Functions

inline explicit UniformSizeSampler(std::unique_ptr<Sampler<T>> &&sampler, size_t min_size, size_t max_size, bool once = false)#

Construct an instance.

Parameters:

  • sampler – [in] The scalar sampler

  • min_size – [in] The minimal vector size

  • max_size – [in] The maximal vector size

  • once – [in] Whether to repeat the first sample (until reset)

template<typename T>
struct PermutationSampler : public navground::sim::Sampler<std::vector<T>>#

An generator that permutates a lists, either randomly or in sequence.

Template Parameters:

T – The scalar type

Public Functions

inline explicit PermutationSampler(const std::vector<T> &values, bool random, bool forward, bool once = false)#

Construct an instance.

Parameters:

  • values – [in] The values

  • random – [in] Whether to perform random permutations

  • forward – [in] The permutation direction (only relevant if not random)

  • once – [in] Whether to repeat the first sample (until reset)

Properties#

struct PropertySampler : public navground::sim::Sampler<navground::core::Property::Field>#

This class wraps a typed Sampler to generate values of type navground::core::Property::Field.

Public Types

using Field = std::variant<bool, int, ng_float_t, std::string, Vector2, std::vector<bool>, std::vector<int>, std::vector<ng_float_t>, std::vector<std::string>, std::vector<Vector2>>#

The type of the value held by the property.

Public Functions

template<typename T, typename = std::enable_if_t<allowed<T>::value>>
inline PropertySampler(std::unique_ptr<Sampler<T>> value)#

Constructs an instance.

Parameters:

value – [in] A sampler

Template Parameters:

T – Needs to be one of the type of navground::core::Property::Field

template<typename S, typename = std::enable_if_t<allowed<ST<S>>::value>>
inline PropertySampler(S &&value)#

Constructs an instance.

Parameters:

value – A sampler

Template Parameters:

S – Needs to be one a subclass of Sampler<T>, with T as one of the types of navground::core::Property::Field

template<typename S, typename ...Targs, typename = std::enable_if_t<allowed<ST<S>>::value>>
inline PropertySampler(Targs... args)#

Create a new sampler.

Parameters:

args – [in] The arguments of the constructor of S

Template Parameters:

  • S – Needs to be one a subclass of Sampler<T>, with T as one of the types of navground::core::Property::Field

  • Targs – The type of the arguments of the constructor of S

inline bool valid() const#

Check if the sampler is valid.

Returns:

True if valid

Registered components#

Base class#

template<typename T>
struct SamplerFromRegister : public navground::sim::Sampler<T::C>#

An inexhaustible sampler of objects from a class that has register.

It creates objects of the sub-class identified by type.

The objects properties are sampled using the properties samplers stored in properties. Property that are not sampled, are assigned to their default value.

The created objects are wrapped in a container, which by default is a shared pointer.

Template Parameters:

T – The type of the root class

Subclassed by navground::sim::TaskSampler< T >

Public Functions

inline explicit SamplerFromRegister(const std::string &type = "")#

Constructs a new instance.

Parameters:

type – [in] The registered type name

Public Members

std::string type#

The registered name of the sub-class to be sampled

std::map<std::string, std::shared_ptr<PropertySampler>> properties#

A map of property samplers name -> sampler used configure the sampled object.

Registers#

template<typename T = Behavior, typename M = BehaviorModulation>
struct BehaviorSampler : public navground::sim::SamplerFromRegister<Behavior>#

Samples navground::core::Behavior.

Defines the same fields as navground::core::Behavior but as sampler of the respective type.

Template Parameters:

T – The type of the behavior root class. Used to generalize from C++ to Python.

Public Types

using Type = T#

Public Functions

inline explicit BehaviorSampler(const std::string &type = "")#

Constructs a new instance.

Parameters:

type – [in] The registered type name

Public Members

std::shared_ptr<Sampler<ng_float_t>> optimal_speed#
std::shared_ptr<Sampler<ng_float_t>> optimal_angular_speed#
std::shared_ptr<Sampler<ng_float_t>> rotation_tau#
std::shared_ptr<Sampler<ng_float_t>> safety_margin#
std::shared_ptr<Sampler<ng_float_t>> horizon#
std::shared_ptr<Sampler<ng_float_t>> path_tau#
std::shared_ptr<Sampler<ng_float_t>> path_look_ahead#
std::shared_ptr<Sampler<std::string>> heading#
std::vector<BehaviorModulationSampler<M>> modulations#
template<typename T = Kinematics>
struct KinematicsSampler : public navground::sim::SamplerFromRegister<Kinematics>#

Samples navground::core::Kinematics.

Defines the same fields as navground::core::Kinematics but as sampler of the respective type.

Template Parameters:

T – The type of the behavior root class. Used to generalize from C++ to Python.

Public Types

using Type = T#

Public Functions

inline explicit KinematicsSampler(const std::string &type = "")#

Constructs a new instance.

Parameters:

type – [in] The registered type name

Public Members

std::shared_ptr<Sampler<ng_float_t>> max_speed#
std::shared_ptr<Sampler<ng_float_t>> max_angular_speed#
template<typename T = BehaviorModulation>
struct BehaviorModulationSampler : public navground::sim::SamplerFromRegister<BehaviorModulation>#

Samples navground::core::BehaviorModulation

Template Parameters:

T – The type of the root class. Used to generalize from C++ to Python.

Public Functions

inline explicit BehaviorModulationSampler(const std::string &type = "")#

Constructs a new instance.

Parameters:

type – [in] The registered type name

Public Members

std::shared_ptr<Sampler<bool>> enabled#
template<typename T = Task>
struct TaskSampler : public navground::sim::SamplerFromRegister<Task>#

Samples Task

Template Parameters:

T – The type of the root class. Used to generalize from C++ to Python.

Public Types

using Type = T#
template<typename T = StateEstimation>
struct StateEstimationSampler : public navground::sim::SamplerFromRegister<StateEstimation>#

Samples StateEstimation

Template Parameters:

T – The type of the root class. Used to generalize from C++ to Python.

Public Types

using Type = T#

Agents#

template<typename W = World>
struct AgentSampler : public navground::sim::Sampler<World::A::C>, public navground::sim::Scenario::Group#

Implement an agent sample.

Defines the same fields as Agent but as sampler of the respective type.

Template Parameters:

W – The world type that the agents belong too. Used to generalize from C++ to Python.

Public Functions

inline explicit AgentSampler(const std::string &name = "")#

Constructs a new instance.

inline std::vector<StateEstimationSampler<S>> get_valid_state_estimations() const#

Public Members

std::string name#
BehaviorSampler<B, M> behavior#
KinematicsSampler<K> kinematics#
TaskSampler<T> task#
std::vector<StateEstimationSampler<S>> state_estimations#
std::shared_ptr<Sampler<Vector2>> position#
std::shared_ptr<Sampler<ng_float_t>> orientation#
std::shared_ptr<Sampler<ng_float_t>> radius#
std::shared_ptr<Sampler<ng_float_t>> control_period#
std::shared_ptr<Sampler<ng_float_t>> speed_tolerance#
std::shared_ptr<Sampler<ng_float_t>> angular_speed_tolerance#
std::shared_ptr<Sampler<int>> id#
std::shared_ptr<Sampler<std::string>> type#
std::shared_ptr<Sampler<std::string>> color#
std::shared_ptr<Sampler<unsigned>> number#
std::shared_ptr<Sampler<std::vector<std::string>>> tags#

Obstacles#

#include "navground/sim/sampling/geometry.h"
std::vector<core::Disc> navground::sim::sample_discs(RandomGenerator &rng, unsigned number, const BoundingBox &bounding_box, ng_float_t min_radius, ng_float_t max_radius, ng_float_t margin = 0.0, ng_float_t disc_margin = 0.0, const std::vector<core::Disc> &discs = {}, unsigned max_tries = 1000, std::vector<core::Vector2> lattice_grid = {})#

Sample discs.

Centers are sampled uniformly inside a bounding box and rejected if too near to any other disc, taking into account the lattice. The maximal number of rejection is bound by max_tries. The function exit when too many rejection are reached, even if not enough discs have been sampled.

Parameters:

  • rng – The random number generator

  • number – [in] The number of discs

  • bounding_box – [in] The bounding box inside of which to sample disc centers

  • min_radius – [in] The minimum value for disc radius

  • max_radius – [in] The maximum value for disc radius

  • margin – [in] The minimal distance between newly sampled discs

  • disc_margin – [in] The minimal distance between newly sampled discs and discs in discs

  • discs – [in] A list of discs already present.

  • max_tries – [in] The maximum sampling failures before exiting the function.

  • lattice_grid – [in] The lattice grid

Returns:

A list of valid disc

Contents