Sampling#
Generic samplers#
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, they 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
All generic 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.
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
sampler:
const: choice
values:
items:
$dynamicRef: '#T'
minItems: 1
type: array
required:
- sampler
- values
type: object
Example#
sampler: choice
values: [1.0, 2.0, 2.0, 1.0]
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
Note
Restricted to numeric types and vectors
Example#
sampler: regular
from: 0.1
step: 0.1
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
Note
Restricted to numeric types and vectors
Example#
sampler: grid
from: [0, 0]
to: [1, 1]
number: [2, 2]
Random 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
Note
Restricted to numeric types.
Example#
sampler: uniform
from: 0.1
to: 0.2
Random 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
Note
Restricted to numeric types.
Example#
sampler: normal
mean: 0.2
std_dev: 0.1
min: 0.0
max: 1.0
Samplers collections#
Some generic schema works on any type, others are restricted to a subset of types, like uniform 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
vectors:
$id: http://navground/vector_sampler $schema: https://json-schema.org/draft/2020-12/schema anyOf: - $ref: const - $ref: sequence - $ref: choice - $ref: grid - $ref: regular
other types:
$id: http://navground/sampler $schema: https://json-schema.org/draft/2020-12/schema anyOf: - $ref: const - $ref: sequence - $ref: choice
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"