uncertainty.propagation¶

The propagation of uncertain values through simulations.

propagate runs the variables of an UncertaintyModel through one simulation or several scenarios: the draws of the variables (correlated, quasi-random, see sbmlsim.uncertainty.draws) are one dimension draw of a Scan, which Simulator.run simulates, so a model is compiled once and the points run in the pool. The result does not depend on the number of workers.

Scenarios with common random numbers. Several simulations, e.g. a control and a treatment, are run with the same draws, so a difference or a ratio of an output between them is paired and its Monte Carlo variance is much smaller than with independent draws (Glasserman 2003). An input variable is applied to the scenarios which declare it, at the same quantile of the distribution of every scenario, a parameter to every scenario.

Adaptive number of draws. Without n the propagation draws batches of quasi-random points, doubling their number (powers of two keep the balance of the Sobol points), until the half widths of the 95 % intervals of the mean, the standard deviation and the 5 % and 95 % quantiles of every output are at most rel_tol times the standard deviation of the output (0.1 by default, which takes about 2000 draws of a normal output and more of a skewed one, whose tail quantiles are less precise), after the adaptive Monte Carlo procedure of the GUM (JCGM 101:2008, 7.9), with the errors of sbmlsim.uncertainty.statistics, which are conservative for quasi-random draws; with hypotheses it draws until every hypothesis is decided after the adjustment for their multiplicity, which the anytime-valid statements of sbmlsim.uncertainty.testing allow (more draws never reverse a decision). At n_max (the last batch is cut to it) a warning says that the tolerance was not reached or which hypotheses are undecided. The history of the batches is recorded, and the result of the batches is the one of a single scan of all the draws: the same draws of Sobol or random points, the labels, the values and the errors of every batch.

Blocks and checkpoints. A Propagation of a given number of draws runs in blocks of draws (block_size), which run separately, e.g. as units on several machines, and merge to the result of the whole propagation: every block takes its rows of the points of the design of all the draws, so a Latin hypercube stays one hypercube. With a checkpoint directory every block, and every batch of the adaptive number of draws, is written as netCDF (<checkpoint>/<scenario>/draws-<start>-<stop>.nc, the name of the scenario percent-encoded) and read instead of simulated when it exists, so the blocks of separate instances merge and an interrupted propagation resumes with the same result; a block of another propagation (another model, engine, integrator settings, observables, kept timecourses, grid of times or draws) is refused. A ragged timecourse is padded to the longest block, as a run pads it to its longest point. Consecutive blocks of one instance run in spans of a block per worker of its simulator (Propagation.run_blocks), whose result is cut into the results of the blocks, each the one a block run alone gives.

The UncertaintyResult has the results of the scenarios, the variables and the record (seed, design, number of draws, history, covariances), and gives the summaries with their Monte Carlo errors, the values of an output over the draws and the contrasts between scenarios.

Glasserman P (2003). Monte Carlo Methods in Financial Engineering. Springer. JCGM 101:2008. Evaluation of measurement data, Supplement 1 to the Guide to the expression of uncertainty in measurement: propagation of distributions using a Monte Carlo method.

UncertaintyResult(results, variables=list(), record=dict())

scenarios

values(output, scenario=None)

contrast(output, a, b, kind='ratio')

probability(output, *, scenario=None, **kwargs)

hypothesis_values(hypothesis)

test(hypotheses, adjust='bonferroni')

outputs()

summary(outputs=None, quantiles=QUANTILES, level=0.95)

contributions(output, scenario=None)

to_netcdf(path)

from_netcdf(path)

Propagation(
    model,
    simulation,
    uq,
    observables=(),
    *,
    outputs=None,
    hypotheses=(),
    adjust="bonferroni",
    n=None,
    rel_tol=0.1,
    n_start=256,
    n_max=16384,
    design=None,
    seed=None,
    simulator=None,
    keep=None,
    time=None,
    on_error="flag",
    checkpoint=None,
    block_size=None,
)

blocks()

checkpointed(block)

run_block(block)

run_blocks(blocks)

run()

propagate(
    model,
    simulation,
    uq,
    observables=(),
    *,
    outputs=None,
    hypotheses=(),
    adjust="bonferroni",
    n=None,
    rel_tol=0.1,
    n_start=256,
    n_max=16384,
    design=None,
    seed=None,
    simulator=None,
    keep=None,
    time=None,
    on_error="flag",
    checkpoint=None,
    block_size=None,
)