experiment.progress¶

The progress and the timings of a run of simulation experiments.

A run of ExperimentRunner.run_experiments shows its progress on the console of the package, see RunProgress: a bar over the experiments and a row per running experiment with what it does, e.g. its simulations or its figures, and how far it got. The run ends with a table of the seconds every experiment took in every phase, see timings_table.

The phases (Phase) are measured where they happen, by a PhaseClock: the runner measures the loading of the models and the initialization of an experiment, SimulationExperiment.run its simulations, data, figures and outputs. The seconds of every phase are the timings of its ExperimentResult, also of an experiment which ran in a worker process: the worker measures them and sends them back with the result.

While a phase runs, its clock reports it as an Event to the listener of the context, see reporting: the display of the run, or in a worker a queue which the parent forwards to its display. Outside of a run of the runner, e.g. an experiment run by SimulationExperiment.run directly, the phases are measured and nothing is reported.

Phase ¶

Bases: StrEnum

A phase of the run of an experiment, the keys of its timings.

Event `dataclass` ¶

Event(sid, phase, activity, completed, total)

What an experiment does, which its clock reports to the listener.

Attributes:

Name	Type	Description
`sid`	`str`	the experiment.
`phase`	`Phase`	the phase it is in.
`activity`	`str`	what it does in the phase, e.g. `"writing figures"`.
`completed`	`int`	the steps of the activity which are done.
`total`	`int`	the steps of the activity, e.g. its figures, at least 1.

PhaseClock ¶

PhaseClock(sid)

Measure the phases of an experiment and report them to the listener.

The listener is the one of the context the clock is created in, see reporting. Phases do not nest; a phase which runs twice, e.g. the figures which are drawn and then written, adds up.

Attributes:

Name	Type	Description
`sid`		the experiment.
`timings`	`dict[str, float]`	the seconds of every phase, by the value of the phase.

Create the clock of an experiment, without any time.

phase ¶

phase(phase, activity, total=1)

Measure an activity of a phase, also when it raises.

Parameters:

Name	Type	Description	Default
`phase`	`Phase`	the phase whose time the activity adds to.	required
`activity`	`str`	what the experiment does, shown in the progress.	required
`total`	`int`	the steps of the activity, see `advance`.	`1`

add ¶

add(phase, seconds)

Add seconds to a phase, e.g. which were measured before the clock.

advance ¶

advance(steps=1)

Advance the activity which runs, see advance.

RunProgress ¶

RunProgress(n_experiments, workers, console=None)

The progress of a run of experiments on the console.

A bar over the experiments, which counts an experiment when it is done, and a row per running experiment with its activity and how far it got, which is removed when the experiment is done. An experiment in a worker reports its events through a queue, so the rows of a pool are the experiments the workers run.

The display is safe to update from several threads: the events of the workers arrive in a thread of their own and the finished experiments of a pool in the thread of the pool.

Create the display of a run, it starts with start.

Parameters:

Name	Type	Description	Default
`n_experiments`	`int`	the experiments of the run.	required
`workers`	`int`	the processes which run them, for the overall row.	required
`console`	`Console \| None`	the console of the output, the one of the package by default.	`None`

start ¶

start()

Show the display.

stop ¶

stop()

End the display, its overall row stays on the console.

note ¶

note(sid, activity)

Show a note in the row of an experiment, e.g. that its worker died.

finished ¶

finished(sid, failed=False)

Count an experiment as done, once.

Parameters:

Name	Type	Description	Default
`sid`	`str`	the experiment.	required
`failed`	`bool`	whether it or one of its figures failed.	`False`

Glyphs `dataclass` ¶

Glyphs(done, failed, bar, icon, ellipsis, lines)

The characters of the marks and the bars of the output.

A console whose encoding is no UTF, e.g. a redirected output on windows in cp1252, cannot write the check marks and the bars; it gets ASCII characters instead, as rich draws the lines of its tables in ASCII there.

reporting ¶

reporting(listener, *, shown=None)

Report the phases of the experiments which run in the context.

A run of the runner without a display of its own reports to the listener of an enclosing context, see current_listener, e.g. the run layer, which records the events of the experiments.

Parameters:

Name	Type	Description	Default
`listener`	`Listener \| None`	what receives the events, `None` for a run which shows no progress; the scans of its tasks then show none either, see `scan_progress`.	required
`shown`	`bool \| None`	whether the run shows its progress on the console; by default a run with a listener does. A listener which shows nothing, e.g. one which records the events, is not shown, and the scans of the tasks show no progress either.	`None`

current_listener ¶

current_listener()

Get the listener of the reporting of the context, None outside of one.

scan_progress ¶

scan_progress()

Get the progress of Simulator.run for a task of an experiment.

A run of the runner which shows no progress shows no progress bar of a scan either; otherwise the simulator decides, see Simulator.run, and in a run with progress a bar of a scan is shown below the rows of the run.

Returns:

Type	Description
`bool \| None`	`False` in a run of the runner without progress, `None` otherwise.

advance ¶

advance(steps=1)

Advance the activity of the phase which runs, nothing outside of one.

Parameters:

Name	Type	Description	Default
`steps`	`int`	the steps which are done, e.g. one figure.	`1`

total_seconds ¶

total_seconds(timings)

Get the seconds of all phases of an experiment.

show_progress ¶

show_progress(progress, console=None)

Decide whether a run shows its progress and timings.

Parameters:

Name	Type	Description	Default
`progress`	`bool \| None`	`True` or `False` as given; `None` shows them on an interactive terminal and in a notebook, and not when the output is redirected, e.g. into a file or a pipe, which would collect the frames of the bars, nor on a dumb terminal (`TERM=dumb`); rich reads `FORCE_COLOR`, `TTY_COMPATIBLE` and `TTY_INTERACTIVE` to override what it detects.	required
`console`	`Console \| None`	the console of the output, the one of the package by default.	`None`

Returns:

Type	Description
`bool`	Whether the progress and the timings are shown.

glyphs ¶

glyphs(console=None)

Get the glyphs a console can write, see Glyphs.

Parameters:

Name	Type	Description	Default
`console`	`Console \| None`	the console of the output, the one of the package by default.	`None`

Returns:

Type	Description
`Glyphs`	`ASCII_GLYPHS` for a console whose encoding is no UTF, else
`Glyphs`	`UNICODE_GLYPHS`.

timings_table ¶

timings_table(results, bars=True, marks=UNICODE_GLYPHS)

Get the table of the seconds every experiment took in every phase.

A row per experiment with its seconds per phase, its total and a bar of its phases in their colours, the bars of all experiments at one scale; then the total of every phase over the experiments with the bar of the whole run, and the share of every phase. The headers of the phases have the colours of their parts of the bars. A phase which no experiment ran has no column, nor has other when it took no measurable time.

In a run in a pool the experiments run at the same time, so the total over the experiments is more than the time of the run.

Parameters:

Name	Type	Description	Default
`results`	`Sequence[ExperimentResult]`	the results of the experiments, see `ExperimentResult.timings`.	required
`bars`	`bool`	show the bars, e.g. not on a console too narrow for them.	`True`
`marks`	`Glyphs`	the characters of the marks and the bars, see `glyphs`.	`UNICODE_GLYPHS`

Returns:

Type	Description
`Table`	The table.

narrow_timings_tables ¶

narrow_timings_tables(results, marks=UNICODE_GLYPHS)

Get the timings for a console too narrow for timings_table.

The total of every experiment, and the seconds and the share of every phase over the experiments, as two tables of two and three columns.

Parameters:

Name	Type	Description	Default
`results`	`Sequence[ExperimentResult]`	the results of the experiments, see `ExperimentResult.timings`.	required
`marks`	`Glyphs`	the characters of the marks, see `glyphs`.	`UNICODE_GLYPHS`

Returns:

Type	Description
`tuple[Table, Table]`	The table of the experiments and the table of the phases.

show_timings ¶

show_timings(
    results, initialized, elapsed, where, console=None
)

Print the timings of a run below a section, see timings_table.

The numbers are what matters: the names give way to the bars down to MIN_NAME_WIDTH, then the bars give way, and a console too narrow for the seconds of every phase of every experiment gets the totals of the experiments and of the phases, see narrow_timings_tables.

Parameters:

Name	Type	Description	Default
`results`	`Sequence[ExperimentResult]`	the results of the experiments of the run.	required
`initialized`	`float \| None`	the seconds of the initialization of the experiments before the run, when the runner was created, `None` for none, e.g. in a second run of a runner.	required
`elapsed`	`float`	the seconds of the run.	required
`where`	`str`	where the experiments ran, e.g. `"on 4 workers"`.	required
`console`	`Console \| None`	the console of the output, the one of the package by default.	`None`

experiment.progress¶

Phase ¶

Event dataclass ¶

PhaseClock ¶

phase ¶

add ¶

advance ¶

RunProgress ¶

start ¶

stop ¶

note ¶

finished ¶

Glyphs dataclass ¶

reporting ¶

current_listener ¶

scan_progress ¶

advance ¶

total_seconds ¶

show_progress ¶

glyphs ¶

timings_table ¶

narrow_timings_tables ¶

show_timings ¶

Event `dataclass` ¶

Glyphs `dataclass` ¶