comnum.run_spec#

comnum.run_spec(spec, *, threads=None, batch=None, fast_dev_run=False, progress=False, profile=None, csv_path=None, json_path=None, base_dir=None)#

Run a declarative campaign with the Rust runner (parallel, reproducible).

The specification describes the grid of conditions, the link as a list of blocks, the metrics and the stopping rule (see comnum.spec_blocks() for the blocks and the documentation of the Rust crate comnum-spec for the format).

Parameters:

  • spec (str | os.PathLike | dict) – a YAML, JSON or TOML file, a YAML text, or the specification as a dict.

  • threads (int, optional) – worker threads (default: the specification, 0 = all).

  • batch (int, optional) – trials between two checks of the stopping rule.

  • fast_dev_run (bool) – one batch per condition, to check a specification.

  • progress (bool) – print one line per condition on the standard error.

  • profile (bool, optional) – time every block, reported as the metrics <label>.time_ms and link.time_ms (Results.profile tabulates them).

  • csv_path (str | os.PathLike, optional) – CSV report (default: the specification’s).

  • json_path (str | os.PathLike, optional) – JSON report (default: the specification’s).

  • base_dir (str | os.PathLike, optional) – the directory the relative paths of the blocks are resolved against (default: the directory of the specification file, else the working directory).

Returns:

one dict per condition with index, condition, status, trials, wall_s and metrics ({name: {value, lo, hi, kind, count, total}}), in a comnum.Results (a list) that keeps the specification.

Return type:

Results

Raises:

ValueError – for an invalid specification; ArithmeticError for a failed trial.

Examples

>>> import comnum
>>> res = comnum.run_spec('''
... name: doc
... grid: {ebn0_db: [4]}
... link: [{type: source, constellation: QPSK, n_symbols: 1000},
...        {type: awgn_ebn0, ebn0_db: $ebn0_db}]
... metrics: {report: [ber]}
... stop: {max_trials: 50}
... ''')
>>> res[0]["trials"], res[0]["metrics"]["ber"]["kind"]
(50, 'rate')