Crate comnum_spec

Expand description

Declarative simulation specifications.

A specification describes a whole Monte Carlo campaign in a YAML, JSON or TOML file: the grid of conditions, the link as a list of blocks, the metrics, the stopping rule and the outputs. Every number of a study then comes from a file that can be read, versioned and rerun (comnum run spec.yaml, run in Rust, comnum.run_spec in Python), and a simulation that cannot be written as a specification shows that a block is missing from the registry.

§Format

name: qam16_awgn                 # the name of the campaign (it enters the seeds)
description: BER of 16-QAM over AWGN
seed: 1                          # base seed (default 0)
batch: 64                        # trials between two checks of the stopping rule
threads: 0                       # worker threads (0: all cores)
confidence: 0.95                 # level of the reported intervals

grid:                            # axes, the last one varying fastest
  ebn0_db: {from: 0, to: 12, step: 2}   # also: a list, or {linspace: [a, b, n]}
cases:                           # optional explicit conditions, crossed with the axes
  - {m: 4}
  - {m: 16}

fiber: {n_spans: 10}             # defaults of every fibre block (FiberParams)

link:                            # blocks, in order; `$name` is a grid variable
  - {type: source, constellation: {kind: qam, m: $m}, n_symbols: 4096}
  - {type: awgn_ebn0, ebn0_db: $ebn0_db}

metrics: {report: [ber, ser, snr_db]}

stop:                            # (targets and min_trials) or max_trials or max_time_s
  min_errors: {ber: 200}
  precision: {snr_db: 0.01}      # relative half-width of the interval
  min_trials: 8
  max_trials: 10000
  max_time_s: 600

callbacks:
  progress: true
  skip_below: {metric: ber, threshold: 1e-6, along: ebn0_db}

profile: true                    # the time of every block, as the metrics <label>.time_ms
output: {csv: results/qam16_awgn.csv, json: results/qam16_awgn.json}

search:                          # instead of the sweep: the operating point
  {along: ebn0_db, range: [4, 16], metric: ber, target: 1.0e-3}

expect:                          # expected results, checked by `comnum verify`
  - {metric: ber, theory: {function: ber, kind: qam, m: $m, ebn0_db: $ebn0_db}, rtol: 0.05}

The variables of the grid are substituted in the link and the metrics before the blocks are built: a string $name (or ${name}) becomes the value with its type, and ${name} inside a longer string is replaced by its text.
The stopping rule is (all targets and min_trials) or max_trials or max_time_s; without any field it is max_trials: 100, and a rule with targets but no cap is rejected (it could run forever). A target on a metric that the link does not record, or min_errors on a mean (snr_db: use precision), is an error at the first batch (comnum check reports it); max_time_s is a finite number of seconds at least 0, a precision a positive number. A run of max_trials runs exactly that many trials, whatever the batch.
The accepted values of a parameter (reference: signal, kind: rrc) are compared without case, and the block receives the declared spelling.
The blocks are listed with their parameters by blocks::registry (and comnum blocks); the metrics are those of metrics.
search replaces the sweep by the search of the value of a variable at which a metric reaches a target, for every combination of the other axes (search).
expect lists results that the campaign must reproduce (closed forms, published curves), with their sources and tolerances; see verify.
A block trained once per condition (Block::needs_training, a learned receiver of another crate, say) is trained on an independent block drawn from the stream "<name>/train" before the trials.
Blocks defined in other crates join the registry by blocks::register.

§Modules

Module	Content
`blocks`	the blocks of a link, the frame they act on, their registry and its extension point
`metrics`	the metrics of a declarative link
`verify`	the expected results of a specification and their checks
`search`	the search of operating points
`io`	recordings: SigMF, raw IQ files, NPY arrays
`cli`	the command line `comnum` (`run`, `check`, `verify`, `conditions`, `blocks`, `schema`)

The specification itself (Spec), the link (Link) and the runs (run, profile) are at the root.

§Examples

use comnum_spec::{run, RunOptions, Spec};
let spec = Spec::from_yaml(r#"
name: qpsk_doc
seed: 3
grid: {ebn0_db: [2, 4]}
link:
  - {type: source, constellation: QPSK, n_symbols: 2000}
  - {type: awgn_ebn0, ebn0_db: $ebn0_db}
metrics: {report: [ber]}
stop: {min_errors: {ber: 300}, max_trials: 500}
"#).unwrap();
let results = run(&spec, &RunOptions::default()).unwrap();
let ber = results[1].metric("ber").unwrap();
let theory = comnum_metrics::theory_ber(comnum_mapping::constellation::ConstellationKind::Qam, 4, 4.0).unwrap();
let (lo, hi) = ber.interval(0.999);
assert!(lo < theory && theory < hi);

Modules§

blocks: The blocks of a declarative link and their registry.
cli: The command-line tool comnum: run declarative Monte Carlo campaigns.
io: Reading and writing sampled signals: measured captures and reference sequences.
metrics: The metrics of a declarative link.
search: Search of the operating point: the value of a variable at which a metric reaches a target, with its confidence interval.
verify: Expected results: a specification that checks itself against the literature.

Macros§

block_info: The documentation of a block (BlockInfo) from its parameters, declared with block_params!, and its ports.
block_params: Declare the parameters of a block: the structure, its Params parser and its documentation (see the module documentation).

Structs§

Link: The link of one condition: its blocks and its metrics.
ProfileRow: One block of a profile: its mean time per trial and its share of the link.
RunOptions: Options of run that override the specification.
Spec: A parsed specification (see the module documentation for the format).
SpecScenario: A specification as a Scenario of the runner.

Enums§

Format: The format of a specification text.

Functions§

grid_conditions: The conditions of a grid as a specification writes it: the Cartesian product of its axes, the last one varying fastest. An axis is a list of values, {from, to, step}, {linspace: [start, stop, count]} or one scalar.
link_labels: The labels of the blocks of a link, as the profile names them (and the Python chains their blocks): the label of a block, else its type, numbered by number_labels.
number_labels: Unique labels: a repeated label takes the position of its block, counted from 1 ([source, awgn, awgn] gives [source, awgn_2, awgn_3]).
profile: Where the time goes: the blocks of a campaign run with profile, in the order of the link, from the metrics <label>.time_ms of the results (an empty list when the campaign was not profiled). labels gives the order, Link::labels; the last row is the whole link.
profile_of: The profile of a specification’s results: the labels of its blocks come from its first condition (link_labels, without building the link).
run: Run a specification: its runner (Spec::runner) on its scenario (SpecScenario).
stop_mapping: The stop mapping of a specification of confidence level confidence whose rule is stop: the inverse of the parser, for a rule the format can write. A specification stops when all its targets (min_errors, precision, with min_trials) are met, or any of its caps (max_trials, max_time_s).
substitute: Replace the variables of the condition in a JSON tree.
variable: The variable that a string of a specification is exactly, name for $name or ${name} (letters, digits, _ and ., not starting with a digit), None for any other string.