progress.core¶

The activities of a long run and what reports them.

A long operation of sbmlsim (a run of simulation experiments, the points of a scan, the runs of a fit, the scans of an identifiability, the figures of a report) opens an Activity: what it does, how many steps it has and how many are done. Activities nest, a fit over its jacobians, an identifiability over its scans, so a run is a tree of what is running, and a Reporter renders it: a bar on a terminal, a line in a log file, an event in progress.jsonl, see sbmlsim.progress.reporters.

The activity of the context is a ContextVar, so an activity which is opened inside another one nests under it without being handed its parent; an activity of a worker process or of a thread which does not copy the context is opened on its parent, see Activity.child.

The estimate of the time which is left is remaining, one for every kind of activity: the time of a batch of the workers times the batches which are left. A reporter which fails (a closed console, a full disk) never aborts the computation: it is logged once and dropped for the rest of the run.

Reporter ¶

Bases: Protocol

What renders the activities of a run.

Every method is called with the activity as it is, which changes while it runs: a reporter which keeps an activity keeps the object, not a copy.

started ¶

started(activity)

Report that the activity started.

advanced ¶

advanced(activity)

Report that the steps or the total of the activity changed.

finished ¶

finished(activity, error)

Report that the activity ended, by an exception if there is one.

Activity `dataclass` ¶

Activity(
    kind,
    label="",
    total=None,
    completed=0,
    workers=1,
    parent=None,
    started_at=(lambda: _now())(),
    uid=(lambda: next(_UIDS))(),
    reporter=None,
)

What a long operation does, and how far it got.

Attributes:

Name	Type	Description
`kind`	`str`	what kind of operation it is, e.g. `"fit"`, `"scan"`; the renderers group and colour by it.
`label`	`str`	what it runs on, e.g. the id of the experiment or the fit.
`total`	`int \| None`	the steps in total, `None` while they are not known.
`completed`	`int`	the steps which are done.
`workers`	`int`	the steps which are processed at once, for the estimate of the time which is left.
`parent`	`Activity \| None`	the activity this one runs in, `None` for the outermost one.
`started_at`	`float`	the monotonic time the activity started.
`uid`	`int`	the number which identifies the activity in a renderer.

depth `property` ¶

depth

Get the activities this one runs in, 0 for the outermost one.

elapsed `property` ¶

elapsed

Get the seconds since the activity started.

remaining ¶

remaining()

Estimate the seconds which are left, see remaining.

advance ¶

advance(steps=1)

Report that steps of the activity are done.

Parameters:

Name	Type	Description	Default
`steps`	`int`	the steps which are done, e.g. one point of a scan.	`1`

update ¶

update(
    *, completed=None, total=None, label=None, workers=None
)

Report what the activity is at now.

Parameters:

Name	Type	Description	Default
`completed`	`int \| None`	the steps which are done.	`None`
`total`	`int \| None`	the steps in total, e.g. once they are known.	`None`
`label`	`str \| None`	what it runs on.	`None`
`workers`	`int \| None`	the steps which are processed at once.	`None`

child ¶

child(kind, label='', *, total=None, workers=1)

Open an activity inside this one, also outside of its context.

A thread or a process which does not copy the context opens its activity on the one it belongs to, instead of relying on the activity of the context.

Parameters:

Name	Type	Description	Default
`kind`	`str`	what kind of operation it is.	required
`label`	`str`	what it runs on.	`''`
`total`	`int \| None`	the steps in total, `None` while they are not known.	`None`
`workers`	`int`	the steps which are processed at once.	`1`

Returns:

Type	Description
`AbstractContextManager[Activity]`	The context of the activity, which yields it.

remaining ¶

remaining(completed, total, elapsed, workers=1)

Estimate the seconds which are left of an activity.

The steps are handed to the workers in batches of workers, so the time of a batch is what the elapsed time measures: the estimate is the time per batch times the batches which are left. With a single worker this is the mean time per step times the steps which are left.

Parameters:

Name	Type	Description	Default
`completed`	`float`	the steps which are done.	required
`total`	`float`	the steps in total.	required
`elapsed`	`float`	the seconds since the activity started.	required
`workers`	`int`	the steps which are processed at once.	`1`

Returns:

Type	Description
`float \| None`	The seconds which are left, `0.0` for an activity which is done and
`float \| None`	`None` before the first step is done.

report ¶

report(target, method, activity_, error=None)

Call a reporter, which never aborts the computation.

The first exception of a reporter is logged and the reporter is dropped for the rest of the process.

Parameters:

Name	Type	Description	Default
`target`	`Reporter \| None`	the reporter, `None` if nothing reports.	required
`method`	`str`	`"started"`, `"advanced"` or `"finished"`.	required
`activity_`	`Activity`	the activity which is reported.	required
`error`	`BaseException \| None`	the exception an activity ended by, for `"finished"`.	`None`

reporter ¶

reporter(target)

Report the activities which run in the context to a reporter.

Parameters:

Name	Type	Description	Default
`target`	`Reporter \| None`	what renders the activities, `None` for a run which reports nothing.	required

current_reporter ¶

current_reporter()

Get the reporter of the context, None outside of a reporting.

current_activity ¶

current_activity()

Get the activity of the context, None outside of one.

activity ¶

activity(
    kind, label="", *, total=None, workers=1, parent=None
)

Report what a long operation does while it runs.

The activity is reported to the reporter of the context, see reporter, and nests under the activity of the context or under parent. Outside of a reporting the activity is kept and nothing is rendered.

Parameters:

Name	Type	Description	Default
`kind`	`str`	what kind of operation it is, e.g. `"fit"`, `"scan"`.	required
`label`	`str`	what it runs on, e.g. the id of the experiment.	`''`
`total`	`int \| None`	the steps in total, `None` while they are not known.	`None`
`workers`	`int`	the steps which are processed at once, for the estimate of the time which is left.	`1`
`parent`	`Activity \| None`	the activity this one runs in, by default the one of the context.	`None`

Yields:

Type	Description
`Generator[Activity]`	The activity, which the operation advances.

progress.core¶

Reporter ¶

started ¶

advanced ¶

finished ¶

Activity dataclass ¶

depth property ¶

elapsed property ¶

remaining ¶

advance ¶

update ¶

child ¶

remaining ¶

report ¶

reporter ¶

current_reporter ¶

current_activity ¶

activity ¶

Activity `dataclass` ¶

depth `property` ¶

elapsed `property` ¶