Module stopping 

When a condition has run enough trials.

A Stop rule is evaluated after every batch of trials of a condition, on the merged metrics. The usual rules of error-rate estimation:

• Stop::max_trials: a fixed budget of trials (the default is 100);
• Stop::min_errors: at least k errors of an error rate, the classical rule of BER simulations (with k = 100 the relative standard deviation of the estimate is about 10 %); it needs an error rate (a mean has no errors: use Stop::precision);
• Stop::precision: the half-width of the confidence interval of a metric below a fraction of its value;
• Stop::min_trials: a lower bound on the trials, to combine with the others;
• Stop::max_time: a wall-time budget per condition (the only rule that depends on the machine, and therefore breaks the thread-count independence of the results).

Rules combine with Stop::or (any of them) and Stop::and (all of them): a typical BER rule is min_errors("ber", 200).or(max_trials(10⁵)), which stops at 200 errors or after 10⁵ trials when the BER is too low to reach them.

The runner checks the rule against the metrics of the first batch of every condition (Stop::check_metrics): a target on a metric that the scenario does not record, or min_errors on a mean, would never be met and is an error. It also ends the last batch at the bound of the rule on the trials (Stop::trial_limit), so that max_trials(1000) runs 1000 trials whatever the batch size.

Examples

use comnum_sim::stopping::{Stop, Progress};
use comnum_sim::scenario::Record;
use std::time::Duration;
let rule = Stop::min_errors("ber", 100).or(Stop::max_trials(1000)).and(Stop::min_trials(10));
let mut rec = Record::new();
rec.errors("ber", 150, 10_000);
let p = Progress { condition: 0, trials: 5, record: &rec, elapsed: Duration::ZERO };
assert!(!rule.is_met(&p));            // enough errors but fewer than 10 trials
let p = Progress { trials: 12, ..p };
assert!(rule.is_met(&p));
assert_eq!(rule.to_string(), "((errors(ber) ≥ 100 or max_trials(1000)) and min_trials(10))");

Structs

Progress

The state of a condition seen by the stopping rule and the callbacks.

Enums

Stop

A stopping rule.

Functions

check_confidence

Check a confidence level: a probability strictly between 0 and 1 (0.95, not 95), what naming where it was given.