synthesizer.utils.operation_timers

Helpers for interacting with accumulated operation timings.

Functions

synthesizer.utils.operation_timers.build_timing_analysis_rows(timing_data, total_elapsed)

Build sorted timing rows including overhead and total entries.

Parameters:

• timing_data (dict) – A timing dictionary keyed by operation name with seconds, count, and source entries for each operation.

• total_elapsed (float) – The total elapsed wall-clock time represented by the analysis.

Returns:

A list of row dictionaries sorted by descending operation time, with trailing Overhead and Total summary rows appended.

Return type:

list

synthesizer.utils.operation_timers.print_timing_analysis_table(rows, print_func=<built-in function print>)

Print a timing analysis table to stdout.

Parameters:

• rows (list) – The timing rows produced by build_timing_analysis_rows.

• print_func (callable) – The function used to emit each formatted line.

Returns:

None

synthesizer.utils.operation_timers.timed(operation_name=None)

Return a decorator that accumulates timing for a wrapped function.

The decorator records timing using the existing tic/toc machinery and guarantees that the matching toc call happens even if the wrapped function raises an exception.

Parameters:

operation_name (str, optional) – The operation name to use for the timing entry. If omitted, the wrapped function’s __qualname__ will be used.

Returns:

A decorator that wraps a function in the timing machinery.

Return type:

callable

synthesizer.utils.operation_timers.timer(operation_name)

Context manager that accumulates timing for a block of code.

The context manager records timing using the existing tic/toc machinery and guarantees that the matching toc call happens even if the wrapped block raises an exception.

Parameters:

operation_name (str) – The operation name to use for the timing entry.

Returns:

A context manager that wraps a code block in the timing machinery.

Return type:

Iterator[None]

Classes

class synthesizer.utils.operation_timers.OperationTimers

Dictionary-like interface to accumulated operation timings.

This class provides access to timing data accumulated by C++ and Python toc() calls. It behaves like a dictionary where keys are operation names and values are tuples of (cumulative_time, call_count, source).

The underlying timing data is stored in C++ using atomic operations for thread-safe accumulation. This class simply provides a Pythonic interface to access that data.

Example

>>> timers = OperationTimers()
>>> timers.reset()
>>> # ... run some operations that call tic()/toc() ...
>>> print(timers.keys())
['Finding particle grid indices', 'Creating Sed', ...]
>>> cumulative_time, count, source = timers['Creating Sed']
>>> print(f"Total: {cumulative_time}s over {count} calls")
Total: 0.00035s over 3 calls
>>> print(timers.get_source('Creating Sed'))
'Python'
>>> OperationTimers.print_table()

classmethod build_rows(total_elapsed=None)

Build sorted timing rows matching the pipeline timing report.

Parameters:

total_elapsed (float, optional) – The total elapsed wall-clock time represented by the timings. If omitted, the sum of all accumulated timed operations is used, which yields a zero-overhead summary.

Returns:

The timing rows produced by build_timing_analysis_rows().

Return type:

list

get_source(key)

Get source (‘C’ or ‘Python’) for an operation.

This is used to determine linestyle in plots (solid for C, dashed for Python).

Parameters:

key (str) – Operation name.

Returns:

‘C’ or ‘Python’.

Return type:

str

Raises:

KeyError – If operation name doesn’t exist.

items()

Iterate over (operation, timing_data) pairs.

Yields:

tuple – (operation_name, (cumulative_time, call_count, source)).

keys()

Return list of operation names.

Returns:

List of operation names (str) that have accumulated timing

data.

Return type:

list

classmethod print_table(total_elapsed=None, print_func=<built-in function print>)

Print a pipeline-style timing breakdown table.

Parameters:

• total_elapsed (float, optional) – The total elapsed wall-clock time represented by the timings. If omitted, the sum of all accumulated timed operations is used, so the printed table shows no overhead row contribution.

• print_func (callable) – The function used to emit the table lines. Defaults to print().

Returns:

The rows that were printed.

Return type:

list

reset()

Clear all accumulated timings.

This should be called before each profiling run to ensure fresh timing data is collected.

classmethod snapshot()

Return the accumulated timings as a plain dictionary.

Returns:

A dictionary keyed by operation name containing seconds, count, and source entries for each accumulated timing.

Return type:

dict