project¶

The project of a model package: its models, analyses and settings.

A Project describes a model package once: its model variants and the factory which builds them, its simulation experiments, its fit problems and the records of its adopted fits, its scans with their sensitivity indices, its sensitivity analyses over the groups of its simulations, its uncertainty analyses and its actions (analyses of its own), the settings of the simulator and of the figures, the known exceptions of its checks (sbmlsim.project_checks) and its release metadata. It is a description, nothing of it runs when it is created.

A model package defines its project as an attribute of a module, e.g. examples.hctz_fitting.project:PROJECT, which load_project imports. The run layer, python -m sbmlsim.run, resolves a spec {project: "module:attribute", analysis: name} (or subset: name for a fit) against it and lists the analyses of a project with python -m sbmlsim.run list <project>, see Project.analyses.

The experiments, the fits, the factory, the credibility declaration, the sensitivity analyses and the functions of the actions of a project are objects or references "module:attribute" to them, which are resolved when they are used (resolve) and kept, so that importing the module of a project imports none of them: the experiments import the module of their project for its paths, so the project cannot import them, and a package of many models stays cheap to import. A module which starts with a dot is relative to Project.package. The scans, the observables and the uncertainty models are python callables which build their objects when an analysis runs, so every unit of a run builds the same objects from them, which is why every callable must build a deterministic object, e.g. a design with a fixed seed.

A relative path of a project (its model variants, the paths of its experiments, the directory of its fit records and the file of its adopted fits) is relative to its root, the directory of the model package; the outputs of a run are not: they go where the run is told, e.g. Project.run_experiments(..., out).

The adopted fits of a project are the fits whose parameters the package uses, one fit id per fit subset, kept in the file ADOPTED_FILE, by default in the directory of the records of the adopted fits (Project.fits_dir): {"fits": {"<subset>": "<fit id>"}}, written by write_adopted.

import sbmlsim does not import this module.

SimulatorSettings ¶

Bases: BaseModel

The settings of the simulator of the analyses of a project.

The processes are no setting of a project, they belong to a run, see simulator.

Attributes:

Name	Type	Description
`engine`	`Engine`	the engine which simulates the models.
`absolute_tolerance`	`float \| AbsoluteTolerance \| None`	the absolute tolerance of the integrator, one value or an `AbsoluteTolerance` per kind and state; `None` for the default of `Simulator`.
`relative_tolerance`	`float \| None`	the relative tolerance of the integrator; `None` for the default of `Simulator`.
`jit_optimization`	`JitOptimization \| None`	the optimization level LLJIT compiles the models of the experiments, the fits and the tests of the project with (`JitOptimization`, `"O0"` to `"O3"`), `None` for the level of `resolve_jit_optimization`. `"O0"` compiles a model with large initial assignments several times faster and simulates a little slower. The fits of the project carry it into their problems and workers, see `Project.load_fit_definitions`.
`integrator`	`dict[str, Any]`	the other settings of the integrator by their names in roadrunner, see `sbmlsim.simulator.Simulator`, e.g. `{"variable_step_size": False}`.

integrator_settings ¶

integrator_settings()

Get the settings of the integrator, the tolerances with the others.

Returns:

Type	Description
`dict[str, Any]`	The settings by their names in roadrunner.

simulator ¶

simulator(n_workers)

Create the simulator of the settings.

Parameters:

Name	Type	Description	Default
`n_workers`	`int \| None`	the workers of the simulator, see `Simulator`.	required

Returns:

Type	Description
`Simulator`	A new simulator.

FigureOutputs ¶

Bases: BaseModel

The files of the figures of the runs of a project.

The rendering of a figure (the resolution, the sizes of the panels, the fonts and the legends) is Project.figure_settings, the sbmlsim.plot.FigureSettings of every figure of a run; these are the formats of the files and the parameters of matplotlib while the figures of a run are drawn.

Attributes:

Name	Type	Description
`formats`	`tuple[str, ...]`	the formats of the figures, static images drawn by matplotlib (`svg`, `png`) and interactive pages drawn by plotly (`html`); SVG only by default. Stored in lower case.
`savefig_dpi`	`float \| None`	the resolution of the static images, the `savefig.dpi` of matplotlib, `None` keeps the one of matplotlib. An interactive page has 72 pixels per inch.
`rc`	`dict[str, Any]`	other parameters of matplotlib while the figures are drawn, e.g. `{"font.family": "serif"}`.

rc_params ¶

rc_params()

Get the parameters of matplotlib while the figures of a run are drawn.

Returns:

Type	Description
`dict[str, Any]`	`rc` with `savefig.dpi` of `savefig_dpi`.

CheckSettings ¶

Bases: BaseModel

The known exceptions of the checks of a model package, each with its reason.

The checks are the functions of sbmlsim.project_checks.

Attributes:

Name	Type	Description
`experiment_modules`	`str`	the module of the experiments relative to the package, a package whose modules define the experiment classes or a module which defines them, see `sbmlsim.project_checks.experiment_modules`.
`not_registered`	`Mapping[str, str]`	experiment classes which are defined but not in the group `all` of the experiments on purpose, by class name.
`not_importable`	`Mapping[str, str]`	modules below the package which do not import in the test environment (an optional dependency), by their name relative to the package, e.g. `experiments.zonation.plot_pyvista`.
`one_at_a_time`	`str \| None`	why the checks run the experiments one at a time (the memory a run of all of them needs), `None` to run them together.
`battery`	`Mapping[str, str]`	the checks of the battery of the model which fail, by the name of the check, e.g. `steady_state`; an assessment shows a known failure with its reason and still fails it.

CredibilitySettings ¶

Bases: BaseModel

The settings of the credibility of a project which belong to its domain.

The declaration of the contexts of use (Project.credibility) is checked and assessed with them, see sbmlsim.credibility.

Attributes:

Name	Type	Description
`metadata_type`	`Any`	the metadata of the fit mappings of the project, a dataclass derived from `sbmlsim.fit.objects.MappingMetaData`, or a reference to it; `MappingMetaData` without, which has no fields.
`domain_fields`	`tuple[str, ...] \| None`	the fields of the metadata a domain of a context of use can claim, every field whose type is an enum without, see `sbmlsim.credibility.metadata_fields`.
`extensions`	`tuple[Any, ...]`	the evidence extensions of the project, instances of `sbmlsim.credibility.extensions.EvidenceExtension` or references to them, see `Project.evidence_extensions`.
`battery`	`Any`	the battery hook of the project, which adds the simulations and checks of its domain to the battery of its variants, an instance of `sbmlsim.credibility.battery.BatteryHook` or a reference to it, see `Project.battery_hook`; `None` for the generic checks only.
`battery_settings`	`Mapping[str, Any]`	the settings of the battery over the ones of the hook (the defaults without one), by the names of the fields of `sbmlsim.credibility.battery.BatterySettings`, e.g. `{"engines": ["copasi"], "horizon": 60.0, "steady_state": True}`; checked when the battery runs.

ScanAnalysis ¶

Bases: BaseModel

A scan of a project, with its sensitivity indices if it has a design.

The fields are the arguments of Simulator.run.

Attributes:

Name	Type	Description
`model`	`Path \| str`	the model of the scan, a path or a source of `Simulator.load`; a relative path is relative to `Project.root`.
`scan`	`Callable[[], Scan \| Simulation]`	builds the scan or the simulation, deterministic: a design of `sbmlsim.simulation.sampling` with a fixed seed.
`observables`	`Callable[[], Sequence[Observable]] \| None`	builds the observables of the run.
`time`	`Sequence[float] \| None`	a grid of times in the time unit of the model the timecourses are interpolated onto; the output times of the simulations without.
`keep`	`Sequence[str] \| None`	the observables or selections the result keeps.
`on_error`	`Literal['raise', 'flag']`	`flag` or `raise`, see `Simulator.run`.
`indices`	`Literal['local', 'sobol', 'fast', 'morris'] \| None`	the sensitivity indices of the scan, a function of `sbmlsim.sensitivity` matching the design of the scan; a scan with indices is also a sensitivity analysis.
`index_options`	`dict[str, Any]`	the keyword arguments of the function of the indices.
`description`	`str`	what the scan analyses.

UncertaintyAnalysis ¶

Bases: BaseModel

An uncertainty analysis of a project.

The fields are the arguments of sbmlsim.uncertainty.propagate.

Attributes:

Name	Type	Description
`model`	`Path \| str`	the model, a path or a source, see `ScanAnalysis.model`.
`simulation`	`Callable[[], Simulation \| Mapping[str, Simulation]]`	builds the simulation or the scenarios by their name.
`uq`	`Callable[[], UncertaintyModel]`	builds what is uncertain.
`observables`	`Callable[[], Sequence[Observable]] \| None`	builds the observables of the runs, e.g. a `PK`.
`outputs`	`Sequence[str] \| None`	the outputs of the summary and the adaptive stopping.
`n`	`int \| None`	the number of draws; `None` for the adaptive number.
`rel_tol`	`float`	the tolerance of the adaptive stopping.
`n_start`	`int`	the draws of the first batch of the adaptive stopping.
`n_max`	`int`	the most draws of the adaptive stopping.
`design`	`Literal['sobol', 'lhs', 'random'] \| None`	`sobol`, `lhs` or `random`, the default of `propagate` without.
`seed`	`int \| None`	the seed of the draws.
`keep`	`Sequence[str] \| None`	the timecourses the results keep.
`time`	`Sequence[float] \| None`	a grid of times in the time unit of the model the timecourses are interpolated onto.
`on_error`	`Literal['raise', 'flag']`	`flag` or `raise`.
`description`	`str`	what the analysis answers.

ActionFunction ¶

Bases: Protocol

The function of an action of a project, see ProjectAction.

It is called with the project, the output directory of the run, which exists and which the action writes into, the number of processes the run may use and the arguments of the spec of the run as keywords, and returns the summary of the run, JSON values by name, or None.

ProjectAction ¶

Bases: BaseModel

An action of a project, an analysis of its own, e.g. a table of its studies.

The kind action of the run layer runs it into its output directory, python -m sbmlsim.run action <spec> with the spec {project, name, arguments}, see sbmlsim.run.project_kinds.

Attributes:

Name	Type	Description
`function`	`Callable[..., Any] \| str`	the function of the action, see `ActionFunction`, or a reference `"module:attribute"` to it.
`description`	`str`	what the action does, its entry in `Project.analyses`.

Project ¶

Bases: BaseModel

A model package: its models, analyses and settings, see the module.

Attributes:

Name	Type	Description
`name`	`str`	the name of the project.
`root`	`Path`	the directory of the model package; the relative paths of the project are relative to it.
`package`	`str \| None`	the dotted name of the model package, e.g. `__name__` in its `__init__.py`; relative references are relative to it.
`title`	`str`	the title of the model in its reports, e.g. the title of the report of a fit; the name without.
`description`	`str`	what the project is.
`variants`	`Mapping[str, Path]`	the SBML files of the model by the name of its variant, e.g. `{"default": ..., "renal": ...}`, the first the default, see `model_path`; every variant is a file of its own.
`factory`	`Callable[[Path], Any] \| str \| None`	builds the models, a function called with the directory it writes into, or a reference to it, see `create_models`.
`factory_dir`	`Path \| None`	the directory the factory writes into in the package, the directory of the first variant without; inside of `root`.
`factory_outputs`	`Sequence[Path]`	the files the factory writes, relative to `root`; the factory may write next to `factory_dir` as well, e.g. an archive into its parent, see `create_models`.
`experiments`	`Callable[[], _Experiments] \| _Experiments \| str \| None`	the simulation experiment classes, a sequence of them, groups of them by name (the group `all` has every experiment, the groups together without it), a callable which returns either, or a reference to one of these; see `load_experiments`.
`base_path`	`Path \| None`	the base path of the experiments, `root` without.
`data_path`	`Path \| Sequence[Path] \| None`	the path or paths of the datasets of the experiments.
`fits`	`Mapping[str, FitDefinition] \| str`	the fit problems by their subset, or a reference to them; see `load_fit_definitions`.
`fits_dir`	`Path \| None`	the directory of the records of the adopted fits, one directory per fit id, see `adopted_record`.
`adopted`	`Path \| None`	the file of the adopted fits, `ADOPTED_FILE` in `fits_dir` without, see `adopted_file`.
`credibility`	`Any`	the declaration of the contexts of use of the model, or a reference to it, see `load_credibility`.
`credibility_settings`	`CredibilitySettings`	the metadata of the fit mappings, the fields of it a domain can claim and the evidence extensions of the credibility of the project.
`scans`	`Mapping[str, ScanAnalysis]`	the scans by their name.
`uncertainties`	`Mapping[str, UncertaintyAnalysis]`	the uncertainty analyses by their name.
`sensitivities`	`Mapping[str, Any]`	the sensitivity analyses of the model over the groups of its simulations by their name, see `sbmlsim.sensitivity.runner`: a `SensitivityRunner`, the runners of the subfolders of a model with several simulations by the name of their subfolder, or a reference to either; a runner without a project is bound to this one, see `sensitivity`. A name is no name of a scan with indices, which is a sensitivity analysis as well.
`actions`	`Mapping[str, ProjectAction]`	the actions of the project by their name, analyses of its own which the kind `action` runs, see `ProjectAction`; a function or a reference is an action without a description.
`simulator`	`SimulatorSettings`	the settings of the simulator of the analyses.
`figure_settings`	`FigureSettings \| None`	the settings of the rendering of the figures of a run.
`figures`	`FigureOutputs`	the formats of the figures of a run and the parameters of matplotlib while they are drawn.
`checks`	`CheckSettings`	the known exceptions of the checks of the model.
`release`	`InstanceOf[ReleaseSettings] \| None`	the release metadata, `None` for a project which is not released.

model_path `property` ¶

model_path

Get the SBML file of the default variant of the model.

Returns:

Type	Description
`Path`	The path of the first variant.

Raises:

Type	Description
`ValueError`	if the project has no model variants.

adopted_file `property` ¶

adopted_file

The file of the adopted fits: adopted, else ADOPTED_FILE in fits_dir.

replace ¶

replace(**changes)

Get a copy of the project with other fields, validated again.

The copy is created by the constructor, so the references are checked and relative paths of the changes are relative to root, unlike model_copy(update=...), which validates nothing. The paths of the project are stored relative to its root, i.e. absolute: a change of root alone does not move them, and the directory of the factory which the project derived from its first variant stays unless it is changed as well.

Parameters:

Name	Type	Description	Default
`**changes`	`Any`	the fields and their new values.	`{}`

Returns:

Type	Description
`Self`	The new project.

Raises:

Type	Description
`ValidationError`	for invalid fields.

variant_path ¶

variant_path(variant=None)

Get the SBML file of a variant of the model.

Parameters:

Name	Type	Description	Default
`variant`	`str \| None`	the name of the variant, the first variant without.	`None`

Returns:

Type	Description
`Path`	The path of the SBML file.

Raises:

Type	Description
`ValueError`	if the project has no model variants.
`KeyError`	naming the variants, for an unknown variant.

load_roadrunner ¶

load_roadrunner(variant=None)

Load a variant of the model in roadrunner at the level of the project.

The model is compiled with LLJIT at SimulatorSettings.jit_optimization (sbmlsim.model.model_roadrunner.load_roadrunner), as the experiments of the project load it, and not with roadrunner's default MCJIT, which compiles a model with large initial assignments much slower: the loader of the tests of a model.

Parameters:

Name	Type	Description	Default
`variant`	`str \| None`	the name of the variant, the first variant without.	`None`

Returns:

Type	Description
`RoadRunner`	The roadrunner instance.

Raises:

Type	Description
`ValueError`	if the project has no model variants.
`KeyError`	for an unknown variant.

load_factory ¶

load_factory()

Get the function which builds the models.

Raises:

Type	Description
`ValueError`	if the project has no factory.
`TypeError`	if the factory is not callable.

create_models ¶

create_models(out=None)

Build the models with the factory, in place or into a rebuild.

By default the factory builds the models in place, into factory_dir. A rebuild into another directory out keeps the layout of the package: the factory writes into out / factory_dir.relative_to(root), so an output o of factory_outputs is out / o there and root / o in the package, see factory_paths and changed_outputs.

Parameters:

Name	Type	Description	Default
`out`	`Path \| None`	the root of a rebuild, the package (`root`) without; a relative directory is relative to the current directory.	`None`

Returns:

Type	Description
`Path`	The directory the factory wrote into.

Raises:

Type	Description
`ValueError`	if the project has no factory or no directory of it.

factory_paths ¶

factory_paths(out=None)

Get the files the factory writes, factory_outputs.

Parameters:

Name	Type	Description	Default
`out`	`Path \| None`	the root of a rebuild with the layout of the package, see `create_models`; the package (`root`) without.	`None`

Returns:

Type	Description
`list[Path]`	The paths of the outputs.

compared_outputs ¶

compared_outputs(out)

Get the outputs of the factory which a rebuild compares with the package.

These are the factory_outputs. A project which declares none compares what the rebuild wrote: the variants of the model and every file the factory wrote into its directory which the package has as well (a file the package does not have, e.g. an ignored one, is left out), so a rebuild is never compared on nothing.

Parameters:

Name	Type	Description	Default
`out`	`Path`	the root of a rebuild, see `create_models`.	required

Returns:

Type	Description
`list[Path]`	The outputs relative to the root, the declared ones in their
`list[Path]`	order, else sorted.

changed_outputs ¶

changed_outputs(out)

Get the outputs of the factory whose rebuild differs from the package.

Every output of compared_outputs is compared with the one of the package, the SBML of a model without the dates of its model history (same_sbml), its antimony (.ant) without the dates of its history (same_antimony), any other file by its bytes; an output which only one of them has differs.

Parameters:

Name	Type	Description	Default
`out`	`Path`	the root of a rebuild, see `create_models`.	required

Returns:

Type	Description
`list[Path]`	The outputs which differ, relative to the root, in the order of
`list[Path]`	`compared_outputs`.

load_credibility ¶

load_credibility()

Get the declaration of the contexts of use of the model.

A declaration of sbmlsim.credibility is checked against the credibility settings of the project: its domains against the fields of the metadata (domain_fields), the settings of the extensions of its contexts and the pairings of its ratio quantities against the evidence extensions (evidence_extensions, sbmlsim.credibility.Credibility.extension_problems); any other object is returned as it is.

Raises:

Type	Description
`ValueError`	if the project has no declaration, or its credibility settings are invalid (see `domain_fields`, `evidence_extensions`).
`DeclarationError`	with the problems of the domains, the settings and the pairings of a declaration.

metadata_type ¶

metadata_type()

Get the metadata of the fit mappings of the project.

Returns:

Type	Description
`type`	The class of `CredibilitySettings.metadata_type`,
`type`	`sbmlsim.fit.objects.MappingMetaData` without.

Raises:

Type	Description
`ValueError`	if a reference is no class.

domain_fields ¶

domain_fields()

Get the fields of the metadata a domain can claim with their enum.

Returns:

Type	Description
`dict[str, type[StrEnum]]`	The enum of every field, see `sbmlsim.credibility.metadata_fields`.

evidence_extensions ¶

evidence_extensions()

Get the evidence extensions of the credibility of the project.

Returns:

Type	Description
`list[Any]`	The extensions, the references resolved, in their order.

Raises:

Type	Description
`ValueError`	if an extension is no `sbmlsim.credibility.extensions.EvidenceExtension` or two have one name.

battery_hook ¶

battery_hook()

Get the battery hook of the credibility of the project.

Returns:

Type	Description
`BatteryHook \| None`	The hook, the reference resolved, `None` without one, see
`BatteryHook \| None`	`sbmlsim.credibility.battery.BatteryHook`.

Raises:

Type	Description
`ValueError`	if the hook is no `sbmlsim.credibility.battery.BatteryHook`.

release_hook ¶

release_hook()

Get the release hook of the project, see ReleaseSettings.hook.

Returns:

Type	Description
`ReleaseHook`	The hook, the reference resolved; the hook which adds nothing,
`ReleaseHook`	`sbmlsim.release.hooks.ReleaseHook`, without one.

Raises:

Type	Description
`ValueError`	if the hook is no `sbmlsim.release.hooks.ReleaseHook`.

action ¶

action(name)

Get an action of the project.

Parameters:

Name	Type	Description	Default
`name`	`str`	the name of the action.	required

Returns:

Type	Description
`ProjectAction`	The action.

Raises:

Type	Description
`KeyError`	naming the actions, for an unknown action.

load_action ¶

load_action(name)

Get the function of an action of the project, see ActionFunction.

Parameters:

Name	Type	Description	Default
`name`	`str`	the name of the action.	required

Returns:

Type	Description
`ActionFunction`	The function.

Raises:

Type	Description
`KeyError`	naming the actions, for an unknown action.
`TypeError`	if the function is not callable.

load_experiments ¶

load_experiments()

Get the groups of the simulation experiments by their name.

The group ALL_EXPERIMENTS (all) has every experiment of the project: the group of that name, else every experiment of the groups once in their order; experiments which are not grouped are the group all alone.

Returns:

Type	Description
`dict[str, list[type[SimulationExperiment]]]`	The experiment classes by group.

Raises:

Type	Description
`ValueError`	if the project has no experiments, or two experiment classes have one name.
`TypeError`	if an experiment is no `SimulationExperiment` class.

experiment_classes ¶

experiment_classes(names=None)

Get experiment classes by the names of their groups or classes.

Parameters:

Name	Type	Description	Default
`names`	`Sequence[str] \| None`	names of groups or of experiment classes, every experiment of the project (the group `all`) without.	`None`

Returns:

Type	Description
`list[type[SimulationExperiment]]`	The experiment classes, every class once in the order of the names.

Raises:

Type	Description
`ValueError`	if the project has no experiments, or two experiment classes have one name.
`KeyError`	naming the groups and the experiments, for a name which is neither.

experiment_runner ¶

experiment_runner(
    experiment_classes, *, simulator=None, on_error="log"
)

Initialize experiments of the project, as its runs do.

The experiments get the paths of the project (its base_path, else its root, and its data_path) and their models are compiled at its level (SimulatorSettings.jit_optimization).

Parameters:

Name	Type	Description	Default
`experiment_classes`	`Iterable[type[SimulationExperiment]]`	the classes of the experiments.	required
`simulator`	`Simulator \| None`	the simulator of the tasks, see `ExperimentRunner`.	`None`
`on_error`	`Literal['raise', 'log']`	whether an experiment which cannot be initialized raises or is logged, see `ExperimentRunner`.	`'log'`

Returns:

Type	Description
`ExperimentRunner`	The runner with the initialized experiments.

run_experiments ¶

run_experiments(
    experiments,
    out,
    *,
    n_workers=None,
    scan_workers=None,
    simulator=None,
    figure_formats=None,
    save_results=False,
    reduced_selections=True,
    show_report=False,
    progress=None,
    raise_on_failure=True,
    uncertainty=None,
    collect_figures=False,
)

Run simulation experiments of the project and write their report.

The experiments run with the settings of the simulator of the project, their figures with its figure settings and in its formats, see sbmlsim.experiment.runner.run_experiments. Every experiment runs, also after another one failed. The run layer (the kind simulate) calls this implementation as Project.run_experiments(project, ...), so a subclass may override the method with another signature and result without breaking it.

With uncertainty the experiments run over draws of the fitted parameters of the model: the parameters of the default variant which have a distribution are drawn once (UncertaintyRun.create), every experiment runs every simulation over the draws and draws the curves of the simulations as bands, see sbmlsim.experiment.draws.

Parameters:

Name	Type	Description	Default
`experiments`	`Sequence[str] \| Sequence[type[SimulationExperiment]] \| type[SimulationExperiment] \| None`	the experiment classes, or names of groups or classes (`experiment_classes`), every experiment without.	required
`out`	`Path \| str`	the directory of the results and the report; a relative directory is relative to the current directory.	required
`n_workers`	`int \| None`	the processes of the run, of the pool of the experiments and, without `scan_workers`, of the simulator, see `run_experiments`.	`None`
`scan_workers`	`int \| None`	the processes of the scans of the simulator, `n_workers` without; `n_workers=None, scan_workers=1` runs the experiments in a pool and the scans of each serially in its worker, which is faster than scans in a pool for many experiments of small scans.	`None`
`simulator`	`SimulatorSettings \| None`	the settings of the simulator, the ones of the project without.	`None`
`figure_formats`	`Sequence[str] \| None`	the formats of the figures, the ones of the project (`FigureOutputs.formats`) without or when empty.	`None`
`save_results`	`bool`	write the results of the tasks.	`False`
`reduced_selections`	`bool`	simulate only the selections an experiment uses.	`True`
`show_report`	`bool`	open the report in a web browser.	`False`
`progress`	`bool \| None`	show the progress and the timings on the console, see `ExperimentRunner.run_experiments`.	`None`
`raise_on_failure`	`bool`	raise when an experiment or a figure failed, after every experiment ran and the report was written (and the figures were collected).	`True`
`uncertainty`	`UncertaintySettings \| None`	run the experiments over draws of the fitted parameters, `None` runs them once.	`None`
`collect_figures`	`bool`	copy the static figures of every experiment (`COLLECTED_FORMATS`) into `FIGURES_DIR` of `out`.	`False`

Returns:

Type	Description
`list[ExperimentResult]`	The results of the experiments.

Raises:

Type	Description
`ValueError`	if the project has no experiments, or with `uncertainty` no parameter of its default variant has a distribution.
`KeyError`	for an unknown name of an experiment.
`TypeError`	if `figure_formats` is a single string.
`ExperimentRunError`	with `raise_on_failure`, if an experiment or a figure failed; its `failures` name them.

load_fit_definitions ¶

load_fit_definitions()

Get the fit problems by their subset, at the level of the project.

A definition without an optimization level gets the one of the simulator of the project (SimulatorSettings.jit_optimization), so its problems compile their models at it in every process.

Returns:

Type	Description
`dict[str, FitDefinition]`	The definitions by subset, empty for a project without fits.

Raises:

Type	Description
`TypeError`	if the fits are no fit definitions by subset.
`ValueError`	for a subset named `ALL_SUBSETS`, which names every adopted fit of a report.

fit ¶

fit(subset)

Get a fit problem.

Parameters:

Name	Type	Description	Default
`subset`	`str`	the subset of the fit.	required

Returns:

Type	Description
`FitDefinition`	The definition of the fit, see `load_fit_definitions`.

Raises:

Type	Description
`KeyError`	naming the subsets, for an unknown subset.
`TypeError`	if the fits are no fit definitions by subset.
`ValueError`	for a subset named `ALL_SUBSETS`.

adopted_fits ¶

adopted_fits()

Get the adopted fits.

Returns:

Type	Description
`dict[str, str]`	The fit id by subset; empty without the file of the adopted fits.

Raises:

Type	Description
`ValueError`	if the file is no file of adopted fits.

adopted_record ¶

adopted_record(fit_id)

Get the directory of the records of an adopted fit.

Parameters:

Name	Type	Description	Default
`fit_id`	`str`	the id of the fit, e.g. `PK_20261016_185018__3efe3`.	required

Returns:

Type	Description
`Path`	The directory `fits_dir/<fit id>`.

Raises:

Type	Description
`ValueError`	if the id is not the id of a fit (`sbmlsim.fit.result.fit_subset`), its subset is no fit subset of the project or the project has no `fits_dir`.
`FileNotFoundError`	if the record of the fit has no parameters.

fit_records ¶

fit_records()

Get the records of the adopted fits: the fitted values and their uncertainty.

A model file of the factory takes the value of a fitted parameter with its uncertainty from them, fit_records().parameter(pid, unit=...), see sbmlsim.fit.records.AdoptedRecords.

Returns:

Type	Description
`AdoptedRecords`	The records of the adopted fits of `adopted_fits`, in `fits_dir`;
`AdoptedRecords`	none for a project without adopted fits.

Raises:

Type	Description
`ValueError`	if the project has adopted fits and no `fits_dir`, or the file of the adopted fits is no such file.
`FileNotFoundError`	if the record of an adopted fit does not exist.

scan ¶

scan(name)

Get a scan.

Parameters:

Name	Type	Description	Default
`name`	`str`	the name of the scan.	required

Returns:

Type	Description
`ScanAnalysis`	The scan.

Raises:

Type	Description
`KeyError`	naming the scans, for an unknown scan.

uncertainty ¶

uncertainty(name)

Get an uncertainty analysis.

Parameters:

Name	Type	Description	Default
`name`	`str`	the name of the analysis.	required

Returns:

Type	Description
`UncertaintyAnalysis`	The uncertainty analysis.

Raises:

Type	Description
`KeyError`	naming the analyses, for an unknown analysis.

sensitivity ¶

sensitivity(name)

Get a sensitivity analysis over the groups of the simulations, resolved.

Parameters:

Name	Type	Description	Default
`name`	`str`	the name of the analysis, a key of `sensitivities`.	required

Returns:

Type	Description
`Any`	The `SensitivityRunner`, or the runners by subfolder, bound to the
`Any`	project (`sbmlsim.sensitivity.runner.bind`).

Raises:

Type	Description
`KeyError`	naming the analyses, for an unknown analysis.
`TypeError`	for a reference to neither runners nor a runner.
`ValueError`	for a runner of another project.

analyses ¶

analyses(experiments=False)

List the analyses of the project.

Resolves the fits of the project and, with experiments, its experiments.

Parameters:

Name	Type	Description	Default
`experiments`	`bool`	also list the groups of the simulation experiments and every experiment, which the kind `simulate` runs by these names; this imports the experiments.	`False`

Returns:

Type	Description
`list[dict[str, str]]`	One entry `{"kind", "name", "description"}` per analysis: the
`list[dict[str, str]]`	simulation experiments (`simulate`, `all`; with `experiments`
`list[dict[str, str]]`	every other group and every experiment class), the analyses of
`list[dict[str, str]]`	every fit subset (`fit`, `identifiability`, `fisher`, `report`,
`list[dict[str, str]]`	`petab`), every scan (`scan`) and, for a scan with indices, its
`list[dict[str, str]]`	sensitivity analysis (`sensitivity`), every sensitivity analysis
`list[dict[str, str]]`	over groups (`sensitivity`), every uncertainty analysis
`list[dict[str, str]]`	(`uncertainty`) and every action (`action`) and the factory
`list[dict[str, str]]`	(`factory`, `models`).

check_reference ¶

check_reference(reference)

Check that a reference has the form "module:attribute".

The module may start with dots (relative to a package), the attribute may be dotted (an attribute of an attribute).

Parameters:

Name	Type	Description	Default
`reference`	`str`	the reference to check.	required

Raises:

Type	Description
`ValueError`	if the reference does not have the form.

same_sbml ¶

same_sbml(a, b)

Compare the SBML of two models without the dates of their model history.

A factory writes the dates of its run into the model history, so a rebuild of an unchanged model differs from the model only in the lines of these dates.

Parameters:

Name	Type	Description	Default
`a`	`str`	the content of one file.	required
`b`	`str`	the content of the other.	required

Returns:

Type	Description
`bool`	Whether they are equal but for the lines with a date.

same_antimony ¶

same_antimony(a, b)

Compare the antimony of two models without the dates of their history.

A factory which writes the antimony of a model writes the dates of its run as model created "..." and model modified "...".

Parameters:

Name	Type	Description	Default
`a`	`str`	the content of one file.	required
`b`	`str`	the content of the other.	required

Returns:

Type	Description
`bool`	Whether they are equal but for the lines with a date.

resolve ¶

resolve(reference, package=None)

Resolve a reference "module:attribute" to the object it names.

Parameters:

Name	Type	Description	Default
`reference`	`str`	the reference; a module which starts with a dot is relative to `package`.	required
`package`	`str \| None`	the package of relative references.	`None`

Returns:

Type	Description
`Any`	The object.

Raises:

Type	Description
`ValueError`	if the reference is malformed or relative without a package.
`AttributeError`	if the module has no such attribute; the message names the reference.

normalize_formats ¶

normalize_formats(formats)

Get figure formats as a lower-case tuple.

Parameters:

Name	Type	Description	Default
`formats`	`Sequence[str]`	the formats, e.g. `["SVG", "png"]`.	required

Returns:

Type	Description
`tuple[str, ...]`	The formats in lower case, e.g. `("svg", "png")`.

Raises:

Type	Description
`TypeError`	if the formats are a single string, e.g. `"svg"` instead of `("svg",)`; a string is a sequence of characters.

load_project ¶

load_project(ref)

Load a project from its reference.

Parameters:

Name	Type	Description	Default
`ref`	`str`	`module:attribute`, e.g. `examples.hctz_fitting.project:PROJECT`.	required

Returns:

Type	Description
`Project`	The project.

Raises:

Type	Description
`ValueError`	for a reference without `:`, a module without the attribute or an attribute which is no `Project`.
`ImportError`	if the module is not imported.

collect_figure_files ¶

collect_figure_files(output_path, *, show=True)

Copy the static figures of a run of experiments into one directory.

Parameters:

Name	Type	Description	Default
`output_path`	`Path`	the output of the run.	required
`show`	`bool`	show the link of the directory on the console of the package; a command whose stdout carries its result, e.g. the build of a release, shows none.	`True`

Returns:

Type	Description
`Path`	The directory of the figures, `FIGURES_DIR` of the output, which has
`Path`	every figure of `COLLECTED_FORMATS` of the experiments.

write_adopted ¶

write_adopted(path, fits)

Write the adopted fits of a project, atomically.

Parameters:

Name	Type	Description	Default
`path`	`Path`	the file, see `ADOPTED_FILE`.	required
`fits`	`Mapping[str, str]`	the fit id by subset.	required

project¶

SimulatorSettings ¶

integrator_settings ¶

simulator ¶

FigureOutputs ¶

rc_params ¶

CheckSettings ¶

CredibilitySettings ¶

ScanAnalysis ¶

UncertaintyAnalysis ¶

ActionFunction ¶

ProjectAction ¶

Project ¶

model_path property ¶

adopted_file property ¶

replace ¶

variant_path ¶

load_roadrunner ¶

load_factory ¶

create_models ¶

factory_paths ¶

compared_outputs ¶

changed_outputs ¶

load_credibility ¶

metadata_type ¶

domain_fields ¶

evidence_extensions ¶

battery_hook ¶

release_hook ¶

action ¶

load_action ¶

load_experiments ¶

experiment_classes ¶

experiment_runner ¶

run_experiments ¶

load_fit_definitions ¶

fit ¶

adopted_fits ¶

adopted_record ¶

fit_records ¶

scan ¶

uncertainty ¶

sensitivity ¶

analyses ¶

check_reference ¶

same_sbml ¶

same_antimony ¶

resolve ¶

normalize_formats ¶

load_project ¶

collect_figure_files ¶

write_adopted ¶

model_path `property` ¶

adopted_file `property` ¶