Sampling#
Generic JSON-Schema#
C++ samplers generates samples of a generic types T. To define the corresponding JSON-schema, we follow https://json-schema.org/blog/posts/dynamicref-and-generics, using $dynamicref and $dynamicanchor to mark the data type T as generic:
<sampler>:
$id: <sampler>
$defs:
of:
$dynamicAnchor: T
not: true
# uses $dynamicRef: "#T"
# ...
Other schemas, when referring to the sampler schema, should define T
$id: <id>
$ref: <sampler>
$defs:
of:
$dynamicAnchor: T
# define schema of T
like, for example, to sample positive integers:
$id: <id>
$ref: <sampler>
$defs:
of:
$dynamicAnchor: T
type: integer
minimum: 0
Once#
All samplers share a common parameter navground::sim::Sampler::once that freezes the sampler once the first sample has been drawn. For example, when in the following scenario
groups:
- number: 10
radius: [1.0, 2.0, 3.0]
once: true
all ten agents will be assigned radius: 1.0 in the first run, radius: 2.0 in the second, and so on. Instead, for once: false, the first agent will get radius: 1.0, the second radius: 2.0, and so on, in any run.
Generic samplers#
The following samplers works with any type.
Constant#
$defs:
of:
$dynamicAnchor: T
not: true
$id: http://navground/const
$schema: https://json-schema.org/draft/2020-12/schema
anyOf:
- $dynamicRef: '#T'
- additionalProperties: false
properties:
once:
type: boolean
sampler:
const: const
value:
$dynamicRef: '#T'
required:
- sampler
- value
type: object
Example#
Constant samplers are specified by a value, like 0.5, or by an object, like
sampler: constant
value: 0.5
Sequence#
$defs:
of:
$dynamicAnchor: T
not: true
$id: http://navground/sequence
$schema: https://json-schema.org/draft/2020-12/schema
anyOf:
- items:
$dynamicRef: '#T'
minItems: 1
type: array
- additionalProperties: false
properties:
once:
type: boolean
sampler:
const: sequence
values:
items:
$dynamicRef: '#T'
minItems: 1
type: array
wrap:
enum:
- terminate
- repeat
- loop
required:
- sampler
- values
type: object
Example#
Sequences are specified by an array, like [0.5, 1.0], or by an object, like
sampler: sequence
values: [1.0, 2.0, 2.0, 1.0]
Choice#
$defs:
of:
$dynamicAnchor: T
not: true
$id: http://navground/choice
$schema: https://json-schema.org/draft/2020-12/schema
additionalProperties: false
properties:
once:
type: boolean
probabilities:
items:
minimum: 0
type: number
type: array
sampler:
const: choice
values:
items:
$dynamicRef: '#T'
minItems: 1
type: array
required:
- sampler
- values
type: object
Example#
sampler: choice
values: [1.0, 2.0, 4.0]
probabilities: [0.25, 0.5, 0.25]
Numbers#
The following samplers are restricted to numbers.
Normal#
$defs:
of:
$dynamicAnchor: T
not: true
$id: http://navground/normal
$schema: https://json-schema.org/draft/2020-12/schema
additionalProperties: false
properties:
clamp:
type: boolean
max:
$dynamicRef: '#T'
mean:
type: number
min:
$dynamicRef: '#T'
once:
type: boolean
sampler:
const: normal
std_dev:
minimum: 0
type: number
required:
- sampler
- mean
- std_dev
type: object
Example#
sampler: normal
mean: 0.2
std_dev: 0.1
min: 0.0
max: 1.0
2D vectors#
The following samplers are restricted to 2D vectors.
Grid#
$id: http://navground/grid
$schema: https://json-schema.org/draft/2020-12/schema
additionalProperties: false
properties:
from:
$ref: vector2
numbers:
items:
minimum: 0
type: integer
maxItems: 2
minItems: 2
type: array
once:
type: boolean
sampler:
const: grid
step:
$ref: vector2
to:
$ref: vector2
wrap:
enum:
- terminate
- repeat
- loop
required:
- sampler
- from
- to
- numbers
type: object
Example#
sampler: grid
from: [0, 0]
to: [1, 1]
number: [2, 2]
Normal 2D#
$id: http://navground/normal2d
$schema: https://json-schema.org/draft/2020-12/schema
additionalProperties: false
properties:
mean:
$ref: vector2
once:
type: boolean
sampler:
const: normal
std_dev:
items:
minimum: 0
type: number
maxItems: 2
minItems: 2
type: array
required:
- sampler
- mean
- std_dev
type: object
Example#
sampler: normal
mean: [0.0, 1.0]
std_dev: [1.0, 4.0]
angle: 0.7853981634
Numbers and 2D vectors#
The following samplers are restricted to numeric types and 2D vectors.
Regular#
$defs:
of:
$dynamicAnchor: T
not: true
$id: http://navground/regular
$schema: https://json-schema.org/draft/2020-12/schema
additionalProperties: false
properties:
from:
$dynamicRef: '#T'
number:
minimum: 0
type: integer
once:
type: boolean
sampler:
const: regular
step:
$dynamicRef: '#T'
to:
$dynamicRef: '#T'
wrap:
enum:
- terminate
- repeat
- loop
required:
- sampler
- from
- to
type: object
Example#
sampler: regular
from: 0.1
step: 0.1
Uniform#
$defs:
of:
$dynamicAnchor: T
not: true
$id: http://navground/uniform
$schema: https://json-schema.org/draft/2020-12/schema
additionalProperties: false
properties:
from:
$dynamicRef: '#T'
once:
type: boolean
sampler:
const: uniform
to:
$dynamicRef: '#T'
required:
- sampler
- from
- to
type: object
Example#
sampler: uniform
from: 0.1
to: 0.2
Numbers and booleans#
Binary#
$defs:
of:
$dynamicAnchor: T
not: true
$id: http://navground/binary
$schema: https://json-schema.org/draft/2020-12/schema
additionalProperties: false
properties:
once:
type: boolean
probability:
minimum: 0
type: number
sampler:
const: binary
required:
- sampler
type: object
Example#
sampler: binary
probability: 0.2
Lists#
The following samplers are restricted to list of scalars.
Warning
These schemas do not fully specify the scalar type, as it would result in a (very) complex JSON-schema.
UniformSize#
$id: http://navground/uniform_size
$schema: https://json-schema.org/draft/2020-12/schema
additionalProperties: false
properties:
max_size:
minimum: 0
type: integer
min_size:
minimum: 0
type: integer
once:
type: boolean
sampler:
const: uniform_size
value:
type:
- number
- boolean
- string
- array
- object
required:
- sampler
- max_size
- value
type: object
Example#
sampler: uniform_size
min_size: 10
max_size: 20
# the scalar iid sampler
value:
sampler: normal
mean: 0.0
std_dev: 1.0
Permutation#
$id: http://navground/permutation
$schema: https://json-schema.org/draft/2020-12/schema
additionalProperties: false
properties:
forward:
type: boolean
once:
type: boolean
random:
type: boolean
sampler:
const: permutation
value:
minItems: 1
type: array
required:
- sampler
- value
type: object
Example#
sampler: permutations
random: true
values: [a, b, c, d]
Samplers collections#
Some generic schema works on any type, others are restricted to a subset of types, like normal samplers that are restricted to numeric types. Therefore, other schemas do not actually refer to the generic schemas directly, but to the allowed set of schemas depending on the type.
numbers:
$id: http://navground/number_sampler $schema: https://json-schema.org/draft/2020-12/schema anyOf: - $ref: const - $ref: sequence - $ref: choice - $ref: regular - $ref: uniform - $ref: normal - $ref: binary
booleans:
$id: http://navground/boolean_sampler $schema: https://json-schema.org/draft/2020-12/schema anyOf: - $ref: const - $ref: sequence - $ref: choice - $ref: binary
strings:
$id: http://navground/string_sampler $schema: https://json-schema.org/draft/2020-12/schema anyOf: - $ref: const - $ref: sequence - $ref: choice
2D vectors:
$id: http://navground/vector2_sampler $schema: https://json-schema.org/draft/2020-12/schema anyOf: - $ref: const - $ref: sequence - $ref: choice - $ref: grid - $ref: regular - $ref: uniform - $ref: normal2d
list of scalar types:
$id: http://navground/list_sampler $schema: https://json-schema.org/draft/2020-12/schema anyOf: - $ref: const - $ref: sequence - $ref: choice - $ref: uniform_size - $ref: permutation
Example#
For a scenario that has string property “name”, the corresponding scheme will contain
# ...
properties:
name:
$id: name
$ref: sampler
$defs:
of:
$dynamicRef: T
type: string
#...
and will accept any of the following instances
# constant works on strings name: "apple"
# sequence works on strings name: ["apple", "pear"]
# choice works on strings name: sampler: choice values: ["apple", "your name"]
but none of these instances
# wrong type name: 1
# uniform does not work on strings name: sampler: uniform from: "apple" to: "pear"