hpcflow.sdk.log.TimeIt#

class hpcflow.sdk.log.TimeIt(name=None)#

Bases: object

Method execution time instrumentation.

Methods

`decorator`	Decorator for a method that is to have its execution time monitored.
`get_command_overhead_time`	Return command time not classified as work or child orchestration.
`get_command_work_time`	Return reported user/application work within the command.
`get_orchestration_time`	Return orchestration time for this process, excluding child processes.
`get_total_orchestration_time`	Return orchestration time including child hpcflow processes.
`get_total_time`	Return total wall time for this hpcflow process.
`reset`
`summarise_string`	Produce a human-readable summary of execution timing statistics.

Attributes

`CLI_end`	`time.perf_counter` assigned at the CLI exit point if active.
`CLI_start`	`time.perf_counter` assigned at the CLI entry point if active.
`active`	Whether the instrumentation is active.
`app_launch_time`	Time spent to launch the app, if set, and if instrumentation is active.
`child_orchestration_time`	Time spent by child app processes on orchestration overhead.
`child_work_time`	Time spent by child app processes on doing work (i.e. script evaluation).
`file_mode`	File mode for when summarising to a file
`file_path`	Where to log to.
`file_preamble`	Preamble to write to the summary file, if requested.
`run_command_time`	Time spent executing the run command, assigned in `Workflow.execute_run` if active.
`timers`	The details be tracked.
`title`	Title to be printed with the summary.
`trace`	Traces of the stack.
`trace_idx`	Trace indices.
`trace_idx_prev`	Preceding trace indices.
`trace_prev`	Preceding traces.

Parameters:: name (str | None)

CLI_end: ClassVar[float | None] = None#: time.perf_counter assigned at the CLI exit point if active.

CLI_start: ClassVar[float | None] = None#: time.perf_counter assigned at the CLI entry point if active.

active: ClassVar = False#: Whether the instrumentation is active.

app_launch_time: ClassVar[float | None] = None#: Time spent to launch the app, if set, and if instrumentation is active. This is measured from just before the app CLI is invoked in a shell, to the top-level Click command call.

child_orchestration_time: ClassVar[float] = 0.0#: Time spent by child app processes on orchestration overhead.

child_work_time: ClassVar[float] = 0.0#: Time spent by child app processes on doing work (i.e. script evaluation)

classmethod decorator(func)#

Decorator for a method that is to have its execution time monitored.

Parameters:: func (Callable[[~P], T])
Return type:: Callable[[~P], T]

file_mode: ClassVar[Literal['w', 'a']] = 'w'#: File mode for when summarising to a file

file_path: ClassVar[str | Path | None] = None#: Where to log to.

file_preamble: ClassVar[str | None] = None#: Preamble to write to the summary file, if requested.

classmethod get_command_overhead_time()#: Return command time not classified as work or child orchestration.

classmethod get_command_work_time()#: Return reported user/application work within the command.

classmethod get_orchestration_time()#: Return orchestration time for this process, excluding child processes.

classmethod get_total_orchestration_time()#: Return orchestration time including child hpcflow processes.

classmethod get_total_time()#: Return total wall time for this hpcflow process.

classmethod reset()#

run_command_time: ClassVar[float | None] = None#: Time spent executing the run command, assigned in Workflow.execute_run if active.

classmethod summarise_string()#

Produce a human-readable summary of execution timing statistics.

The summary may contain two sections:

1. Overall process timings These describe the wall-clock time associated with launching and running the CLI command:

App launch time

Time elapsed before the CLI callback starts. This includes Python interpreter start-up, module imports, and other application initialisation performed before CLI_start is recorded.

CLI time

Time between entering the CLI callback and completion of the invoked command. This includes app orchestration as well as execution of the command itself.

Command time

Wall-clock time spent executing the external command launched by this process.

Command work time

Time explicitly reported by the child process as application/user work. For generated Python scripts this is the time spent executing the user-defined function, excluding framework setup, input preparation, output handling, and imports.

Command overhead time

The part of Command time not accounted for by reported user work or child orchestration:

Command overhead
= Command time - Child orchestration time - Command work time

This can include process and interpreter start-up, shell/environment activation, process shutdown, and other execution overhead outside the instrumented child process. For example, activation of a conda environment.

Orchestration time

App orchestration performed by this process, excluding the external command execution itself.

Child orchestration time

Framework/script orchestration explicitly reported by child processes. For generated Python scripts this includes imports, framework setup, input preparation, and output handling, but excludes the timed user work.

Total orchestration time

Orchestration performed by this process and its instrumented child processes:

Total orchestration
= Orchestration time + Child orchestration time

Total time

Total wall-clock time from application launch to completion of the CLI command:

Total time
= App launch time + CLI time

When child work timing is available, this can also be decomposed as:

Total time
= Total orchestration time + Command work time + Command overhead time

2. Instrumented timing tree The table reports timings collected by TimeIt decorators and context managers. sum is the accumulated inclusive time for a named timer; mean, stddev, min, and max describe its individual invocations, and N is the number of invocations.

Tree indentation represents dynamic nesting of timers. Parent timings are inclusive of their child timings, so values in the tree should not generally be added together. Time spent directly in a parent can be estimated by subtracting its child timings from the parent timing.

Some fields are omitted when the information required to calculate them is unavailable. In particular, command work and command overhead require timing information reported by an instrumented child process.

Return type:: None

timers: ClassVar[dict[tuple[str, ...], list[float]]] = {}#: The details be tracked.

title: ClassVar[str | None] = None#: Title to be printed with the summary.

trace: ClassVar[list[str]] = []#: Traces of the stack.

trace_idx: ClassVar[list[int]] = []#: Trace indices.

trace_idx_prev: ClassVar[list[int]] = []#: Preceding trace indices.

trace_prev: ClassVar[list[str]] = []#: Preceding traces.