Module search 

Search of the operating point: the value of a variable at which a metric reaches a target, with its confidence interval.

A sweep answers “what is the BER at 12 dB?”; a link budget asks the converse, “which SNR gives a BER of $10^{-3}$?”. The search section of a specification answers it directly:

search:
  along: ebn0_db          # the variable searched (a grid axis or not)
  range: [4, 16]          # the bracket of the search
  metric: ber
  target: 1.0e-3
  tolerance: 0.02         # stop when the bracket is narrower
  log: true               # interpolate log10 of the metric (default)

For every combination of the other grid axes, the metric is evaluated at both ends of the range (the target must lie between the two values), then the bracket is halved until it is narrower than tolerance (at most max_evaluations evaluations). Every evaluation is a run of one condition with the stopping rule of the specification; all of them use the same random streams (common random numbers), so the comparison of two values of the variable is not blurred by the draws, and the estimate is monotone wherever the link is.

The crossing is interpolated between the two ends of the final bracket (linearly in log10 of the metric, or in the metric). Its confidence interval comes from the confidence intervals of these two estimates: the crossings of the lower and of the upper bounds of the metric, interpolated the same way (and extrapolated when a bound does not cross the target inside the bracket).

Examples

use comnum_spec::{search::search, RunOptions, Spec};
let spec = Spec::from_yaml(r#"
name: qpsk_required
link:
  - {type: source, constellation: QPSK, n_symbols: 4000}
  - {type: awgn_ebn0, ebn0_db: $ebn0_db}
metrics: {report: [ber], scale: none}
stop: {min_errors: {ber: 400}, max_trials: 400}
search: {along: ebn0_db, range: [2, 10], metric: ber, target: 1.0e-3, tolerance: 0.05}
"#).unwrap();
let r = search(&spec, &RunOptions::default()).unwrap();
// Q(√(2 Eb/N0)) = 1e-3 at 6.79 dB
assert!((r[0].value - 6.79).abs() < 0.15, "{}", r[0].value);
assert!(r[0].lo <= r[0].value && r[0].value <= r[0].hi);

Structs

Evaluation

One evaluation of the metric during a search.

SearchResult

The operating point of one combination of the other axes.

SearchSpec

The search section of a specification.

Functions

search

Run the search of a specification.