Skip to content

release.build

The build of a release repository.

The build runs the analyses of the model package inside the release repository (uv run, in the environment of its locked, released dependencies) through the run layer of sbmlsim, python -m sbmlsim.run <kind> specs/<step>.json --out results/<step>, and copies the generated models, figures, simulation reports, fit reports and the assessment of the credibility to their places in the repository. The specs of the steps (BuildStep, build_steps) are files of the release, so a user of the release runs the same analyses with the same commands. The exported package is never imported: the project of the source package only gives the paths of the model relative to its package folder, its analyses and the adopted fits.

BuildPaths

The folders of the release repository, relative to its root.

BuildStep dataclass 

BuildStep(name, kind, spec, title)

A step of the build: an analysis of the run layer of sbmlsim.

Attributes:

Name Type Description
name str

the name of the step, the name of its spec file specs/<name>.json and of its output results/<name>.
kind str

the kind of the run layer, e.g. simulate.
spec dict[str, Any]

the settings of the spec.
title str

what the step does, the line of its stage.

spec_file property 

spec_file

The spec file of the step, relative to the release repository.

out property 

out

The output of the step, relative to the release repository.

command 

command(workers=None)

Get the command of the step in the release repository.

Parameters:

Name Type Description Default
workers int | None

the number of workers of a step which simulates, the default of the run layer without.

 None

Returns:

Type Description
list[str]

The command, with POSIX paths relative to the release repository.

BuildResult dataclass 

BuildResult(written, steps, changed, skipped)

What the build of a release wrote and ran.

Attributes:

Name Type Description
written list[Path]

the written paths, relative to the release repository.
steps list[BuildStep]

the steps which ran, see build_steps.
changed list[str]

the outputs of the factory which differ from the ones of the source package, as the kind factory names them; the build copies them over the exported package, so they are part of the release.
skipped list[dict[str, str]]

the steps which were skipped with the reason, see skipped_steps.

is_experiment_folder 

is_experiment_folder(name)

Check that a folder of the simulation report is an experiment.

The folders _figures and the hidden ones are no experiments.

build_steps 

build_steps(
    project, reference, source_commit=None, *, root=None
)

Get the steps of the build of a release of a project, in their order.

  • factory: the models, with the factory of the project, which the build runs first and copies over the exported package; a project without one releases the models of its package.
  • simulate: the experiments of a project with experiments.
  • uncertainty: the experiments over the draws of the fitted parameters, with the defaults of sbmlsim.experiment.draws.UncertaintySettings, for a project with experiments and adopted fits whose default variant has the distributions of its fitted parameters (has_distributions, else the step is skipped, see skipped_steps).
  • report: the reports of the adopted fits, one folder per fit id.
  • credibility: the assessment of the contexts of use of a project with a declaration, with the commit of the source repository in its provenance.

Parameters:

Name Type Description Default
project Project

the project.

 required
reference str

the project as module:attribute, which the release repository imports.

 required
source_commit str | None

the commit of the source repository.

 None
root Path | None

the package whose default variant has_distributions reads, e.g. the exported package with the models of the factory; the root of the project without.

 None

Returns:

Type Description
list[BuildStep]

The steps.

Raises:

Type Description
ReleaseError

if the adopted fits are not read.

has_distributions 

has_distributions(project, root=None)

Tell whether the default variant of a project has distributions.

The experiments run over the draws of the fitted parameters from the distributions which the adopted fits give the parameters of the model (sbmlsim.simulation.sampling.parameter_distributions).

Parameters:

Name Type Description Default
project Project

the project.

 required
root Path | None

the package of the variant, e.g. the exported package of a release; the root of the project without.

 None

Returns:

Type Description
bool

Whether the SBML of the default variant exists and a parameter of it
bool

has a distribution.

Raises:

Type Description
ReleaseError

if a distribution of the model is not read.

skipped_steps 

skipped_steps(project, root=None)

Get the steps of the build which a project skips, with the reason.

Parameters:

Name Type Description Default
project Project

the project.

 required
root Path | None

the package of the default variant, see has_distributions.

 None

Returns:

Type Description
list[dict[str, str]]

{"step": name, "reason": text} of every skipped step: uncertainty
list[dict[str, str]]

for a project with experiments and adopted fits whose default variant
list[dict[str, str]]

has no distributions.

Raises:

Type Description
ReleaseError

if the adopted fits are not read.

build 

build(
    project,
    reference,
    release_path,
    runner=run,
    workers=None,
    *,
    source_commit=None,
)

Build the models, simulations, fit reports and the credibility in the release.

All commands run with release_path as working directory: uv lock, uv sync --locked and the steps of build_steps, each an analysis of the run layer of sbmlsim with its spec file in specs/ into results/<step> (ignored by git, removed before the steps). The factory runs first and its rebuild is copied over the exported package (_apply_factory), so the package of the release, its models, its archive and every analysis agree; then the steps are decided on that package (build_steps, skipped_steps) and run. The outputs are copied to the tracked folders models, figures, simulations and simulations_uncertainty (each with the static figures of the experiments in _figures, sbmlsim.project.collect_figure_files), fit/<fit id> and credibility; every one of them is replaced, so the reports of fits which are no longer adopted disappear, and the folder of a step which does not run is removed.

A declared output is required, an undeclared one is optional: the models must have at least one SBML file and, if the settings name an archive, the factory must create it; the licenses and the figures folder are copied if the factory creates them. A project without a factory releases the models of its package, from its factory_dir.

Parameters:

Name Type Description Default
project Project

the project of the source package.

 required
reference str

the project as module:attribute.

 required
release_path Path

the release repository, with the package already exported.

 required
runner Runner

runs the commands.

 run
workers int | None

the number of workers of the simulations, the CPUs of the quota without.

 None
source_commit str | None

the commit of the source repository the release is built from, recorded by the assessment of the contexts of use.

 None

Returns:

Type Description
BuildResult

What the build wrote (with the new uv.lock and the specs of the
BuildResult

steps), the steps, the outputs the factory changed and the skipped
BuildResult

steps.

Raises:

Type Description
ReleaseError

if a step fails; the message names the step.