credibility.battery¶

The battery of the checks of a model: its variants, not its predictions.

The verification of the predictions (sbmlsim.credibility.verification) asks whether the numbers a context of use is decided on are the solution of the model. The battery asks whether the model itself is sound, independent of any data: every variant of the project (sbmlsim.project.Project.variants) is simulated with roadrunner from its initial state, without a change and with the cases of the battery hook of the project, and the results are checked against what every model must fulfil (BATTERY_CHECKS):

• non_negativity: no species becomes negative beyond the floor of the integrator in any simulation.
• steady_state: without a change every state but the accumulating ones (accumulating_states, the sinks which nothing drains) stays at its start (BatterySettings.steady_limit): the model starts at its steady state. A model which is not meant to, e.g. a decay or an oscillator, does not; the check runs only when the settings say the model starts at its steady state (BatterySettings.steady_state, off by default) and is not applicable otherwise.
• cross_simulator: a second engine of sbmlsim (BatterySettings.engines, AMICI and COPASI, each one which is installed) gives the results of roadrunner without a change and with every case of the hook which it repeats (BatteryCase.cross_simulator), within LIMIT; both run through sbmlsim.simulator.Simulator on the same simulation, roadrunner compiled at O0. What an engine does not simulate as roadrunner (sbmlsim.engine.UnsupportedModelError, e.g. an algebraic rule in COPASI) is no failure: the statement names it as not compared, and a check which compared nothing is not applicable. AMICI compiles a variant in a worker of a pool of its own (sbmlsim.parallel.start_pool) which is stopped after BatterySettings.compile_timeout, so a compilation which takes too long is not compared either.
• plausibility: the initial state has finite values and positive compartments, and no value of an adopted fit lies at a bound of its fit (BatterySettings.bound_margin).
• rebuild: the factory of the project builds the models again (sbmlsim.project.Project.create_models into a temporary directory), equal to the package but for the dates of the model history (sbmlsim.project.Project.changed_outputs).

A domain adds its simulations and checks with a BatteryHook, which the project registers (sbmlsim.project.CredibilitySettings.battery): what it reads from a variant (BatteryHook.read), the SBML the battery simulates instead of the file (BatteryHook.sbml, e.g. with parameters which integrate the flows of the reactions), further selections, the cases of its changes, e.g. a dose of every route (BatteryCase), and further checks on the simulations of every variant (BatteryHook.contribute, BatteryRun), which it registers (sbmlsim.credibility.verification.register_check), with sections of plain data in the record of the battery (Battery.sections) which the report shows (BatteryHook.report_html, BatteryHook.report_tables). The settings are the ones of the hook (BatteryHook.settings), else the defaults, with the settings of the project over them (sbmlsim.project.CredibilitySettings.battery_settings, see battery_settings_of), so a project without a hook sets its engines, its horizon or its tolerances as well. A check without what it needs is not applicable and assesses nothing. A hook also says which generic check does not apply to which variant (BatteryHook.not_applicable, e.g. no steady state for a model of another kind than the others): the check runs on the other variants and its statement names the variants left out with their reason, and when it leaves out every variant the check is not applicable and its statement gives the reasons per variant. The tables of the hook are written whether or not the battery ran (BatteryHook.report_tables).

BatteryResult(
    *,
    check,
    status,
    cases,
    largest,
    at,
    problems,
    statement,
)

passed

to_dict()

from_dict(data)

Battery(*, results, sections, settings)

failed

result(check)

to_dict()

from_dict(data)

BatterySettings(
    *,
    horizon=HORIZON,
    steps=STEPS,
    relative_tolerance=RELATIVE_TOLERANCE,
    absolute_tolerance=ABSOLUTE_TOLERANCE,
    steady_limit=STEADY_LIMIT,
    bound_margin=BOUND_MARGIN,
    steady_state=False,
    cross_simulator=True,
    engines=("amici", "copasi"),
    compile_timeout=COMPILE_TIMEOUT,
)

times

BatteryCase(
    *,
    name,
    changes,
    added=frozenset(),
    cross_simulator=True,
)

BatteryBuild(
    *,
    variant,
    path,
    sbml,
    species,
    states,
    accumulating,
    selections=(),
    cases=(),
    data=None,
)

columns

BatteryRun(build, settings)

run(case)

column(result, sid)

results()

scales(ids)

BatteryCollector(
    cases=0, largest=nan, at="", problems=list()
)

deviation(value, at)

result(check, statement)

BatteryContribution(*, results=(), sections=dict())

settings()

read(variant, path)

sbml(data)

selections(data)

cases(data)

contribute(runs)

not_applicable(check, data)

describe()

report_html(sections)

report_tables(sections)

battery_settings_of(project, hook)

math_names(ast)

accumulating_states(model)

read_build(variant, path, hook=None)

not_applicable_result(check, reason)

battery_settings(settings, hook)

with_deadline(function, args, timeout)

run_battery(
    project,
    *,
    rebuild=True,
    cross_simulator=True,
    hook=None,
)