API reference

ProfileManager

The main entry point for all profiling operations. All methods are class methods on a singleton — there is no need to instantiate the class.

class scope_profiler.profile_manager.ProfileManager

Singleton class to manage and track all ProfileRegion instances.

classmethod profile_region(region_name, functions=None)

Get an existing ProfileRegion by name, or create a new one if it doesn’t exist.

Parameters:

• region_name (str) – The name of the profiling region.

• functions (list of callable, optional) –

  Functions to register for line-by-line profiling. Only has an effect when use_line_profiler=True. Useful when using the context manager form, since the decorator form (wrap) registers functions automatically:

  with ProfileManager.profile_region("my_region", functions=[my_func]):
      my_func()
  

Returns:

ProfileRegion

Return type:

The ProfileRegion instance.

classmethod profile(region_name=None)

Decorator factory for profiling a function.

Parameters:

region_name (str, optional) – Name for the profiling region. If not provided, uses the decorated function’s name. Supports being used with or without parentheses.

Returns:

Decorated function wrapped with profiling instrumentation.

Return type:

Callable

Notes

The decorated function is registered so that calling ProfileManager.setup() after decoration re-binds the wrapper to the new region class at zero per-call cost. This means @ProfileManager.profile can be applied at class-definition time even when setup() is called later.

classmethod finalize(verbose=True)

Finalize profiling and merge results from all MPI ranks.

Flushes buffered profiling data to disk, synchronizes across MPI ranks, and merges per-rank profiling files into a single output file. Optionally prints profiling statistics for each region.

Parameters:

verbose (bool, optional) – If True, prints profiling statistics for each region (default: True).

Return type:

None

classmethod get_region(region_name)

Get a registered ProfileRegion by name.

Parameters:

region_name (str) – The name of the profiling region.

Returns:

ProfileRegion or None

Return type:

The registered ProfileRegion instance or None if not found.

classmethod get_all_regions()

Get all registered ProfileRegion instances.

Returns:

dict

Return type:

Dictionary of all registered ProfileRegion instances.

classmethod setup(profiling_activated=True, use_likwid=False, use_line_profiler=False, time_trace=True, flush_to_disk=True, buffer_limit=100000, file_path='profiling_data.h5')

Initialize and configure the profiling system.

Parameters:

• profiling_activated (bool, optional) – Enable or disable profiling (default: True).

• use_likwid (bool, optional) – Enable LIKWID hardware counter collection (default: False).

• use_line_profiler (bool, optional) – Enable line-by-line profiling via line_profiler (default: False).

• time_trace (bool, optional) – Enable timing trace collection (default: True).

• flush_to_disk (bool, optional) – Enable flushing profiling data to disk (default: True).

• buffer_limit (int, optional) – Maximum number of profiling events per buffer before flushing (default: 100_000).

• file_path (str, optional) – Path to the output profiling data file (default: “profiling_data.h5”).

classmethod set_config(config)

Set a new profiling configuration and update the region class.

Parameters:

config (ProfilingConfig) – The new profiling configuration to apply.

Return type:

None

classmethod get_config()

Get the current profiling configuration.

Returns:

The current profiling configuration.

Return type:

ProfilingConfig

ProfilingConfig

Singleton that holds the global profiling configuration. Normally you interact with it through ProfileManager.setup(), but you can also construct one directly for advanced use cases.

class scope_profiler.profile_config.ProfilingConfig(*args, **kwargs)

Singleton class for managing global profiling settings.

This class centralizes configuration for time tracing, LIKWID performance counters, buffer limits, and file paths. It ensures consistent profiling state across MPI ranks and creates per-rank temporary storage for profiling output.

get_local_filepath(rank)

Return the per-rank local profiling file path.

Parameters:

rank (int) – MPI rank identifier.

Returns:

The path to the per-rank HDF5 file.

Return type:

str

classmethod reset()

Reset the singleton so it can be reinitialized.

pylikwid_markerinit()

Initialize LIKWID markers if LIKWID is enabled.

pylikwid_markerclose()

Close LIKWID markers to finalize measurement regions.

property comm: Intercomm | None

MPI communicator or None if MPI is unavailable.

property profiling_activated: bool

Return whether profiling is globally enabled.

property buffer_limit: int

Maximum number of buffered profiling records.

property file_path: str

Global output file path for combined profiling data.

property use_likwid: bool

Return whether LIKWID profiling is enabled.

property use_line_profiler: bool

Return whether line_profiler profiling is enabled.

property flush_to_disk: bool

Return whether profiling buffers should flush to disk.

property time_trace: bool

Return whether time trace profiling is enabled.

property config_creation_time: int

Timestamp (ns) when the configuration was created.

Region classes

BaseProfileRegion

class scope_profiler.region_profiler.BaseProfileRegion(region_name, config)

Base class providing shared profiling logic.

Handles start/end time buffering, call counting, lazy HDF5 dataset initialization, and flushing data to disk when buffers fill.

Parameters:

• region_name (str)

• config (ProfilingConfig)

region_name

config

num_calls

ptr

buffer_limit

start_times

end_times

group_path

local_file_path

hdf5_initialized

wrap(func)

Wrap a function for profiling.

Subclasses must override this method to implement the appropriate profiling behavior.

append(start, end)

Append a start/end time pair to the buffer.

Automatically triggers a flush if the buffer becomes full.

Parameters:

• start (float)

• end (float)

Return type:

None

flush()

Flush buffered start/end times to the HDF5 file.

Lazily initializes datasets on the first flush. Subsequent flushes append to the existing datasets.

get_durations_numpy()

Return durations (end - start) for buffered entries as a NumPy array.

Return type:

ndarray

get_end_times_numpy()

Return end times offset by config creation time.

Return type:

ndarray

get_start_times_numpy()

Return start times offset by config creation time.

Return type:

ndarray

add_function(func)

Register a function for profiling. No-op except in LineProfilerRegion.

Return type:

None

DisabledProfileRegion

class scope_profiler.region_profiler.DisabledProfileRegion(region_name, config)

Profiling region that performs no measurements.

Used when profiling is disabled but code paths must remain valid.

Parameters:

• region_name (str)

• config (ProfilingConfig)

wrap(func)

Return the original function unchanged — no wrapper, no overhead.

append(start, end)

Ignored: no data recorded.

flush()

Ignored: no data recorded.

get_durations_numpy()

Return an empty array since nothing is recorded.

region_name

config

start_times

end_times

num_calls

ptr

buffer_limit

group_path

local_file_path

hdf5_initialized

NCallsOnlyProfileRegion

class scope_profiler.region_profiler.NCallsOnlyProfileRegion(region_name, config)

Region that records only the number of calls, not timing.

Parameters:

• region_name (str)

• config (ProfilingConfig)

wrap(func)

Wrap a function and increment the call counter for each invocation.

append(start, end)

Ignored: timing information is not stored.

flush()

Ignored: no data to flush.

get_durations_numpy()

Return an empty array because no timing data is collected.

region_name

config

start_times

end_times

num_calls

ptr

buffer_limit

group_path

local_file_path

hdf5_initialized

TimeOnlyProfileRegion

class scope_profiler.region_profiler.TimeOnlyProfileRegion(region_name, config)

Region that records timing and flushes to disk when buffers fill.

Parameters:

• region_name (str)

• config (ProfilingConfig)

wrap(func)

Wrap a function to measure execution time and flush when needed.

region_name

config

start_times

end_times

num_calls

ptr

buffer_limit

group_path

local_file_path

hdf5_initialized

TimeOnlyProfileRegionNoFlush

class scope_profiler.region_profiler.TimeOnlyProfileRegionNoFlush(region_name, config)

Region that records timing but never flushes to disk.

Used for lightweight profiling where in-memory results are sufficient.

Parameters:

• region_name (str)

• config (ProfilingConfig)

wrap(func)

Wrap a function to measure start and end time without flushing.

region_name

config

start_times

end_times

num_calls

ptr

buffer_limit

group_path

local_file_path

hdf5_initialized

LikwidOnlyProfileRegion

class scope_profiler.region_profiler.LikwidOnlyProfileRegion(region_name, config)

Region that wraps a LIKWID marker region without recording timing.

This region enables hardware performance counter collection using LIKWID, but does not store timing or write data to HDF5. Useful when the user only wants LIKWID metrics while still using the unified region API.

Parameters:

• region_name (str)

• config (ProfilingConfig)

likwid_marker_start

likwid_marker_stop

wrap(func)

Wrap a function to enclose it in a LIKWID marker region.

FullProfileRegion

class scope_profiler.region_profiler.FullProfileRegion(region_name, config)

Region that records both timing and LIKWID metrics, and flushes to HDF5.

This is the most complete profiling mode: users obtain LIKWID markers, nanosecond-resolution timing, and persistent on-disk storage.

Parameters:

• region_name (str)

• config (ProfilingConfig)

likwid_marker_start

likwid_marker_stop

wrap(func)

Wrap a function to measure time, collect LIKWID metrics, and flush when needed.

FullProfileRegionNoFlush

class scope_profiler.region_profiler.FullProfileRegionNoFlush(region_name, config)

Region that records both timing and LIKWID metrics, without flushing.

Useful for high-frequency profiling where the user retrieves metrics only from in-memory buffers. No HDF5 writes occur.

Parameters:

• region_name (str)

• config (ProfilingConfig)

likwid_marker_start

likwid_marker_stop

wrap(func)

Wrap a function to measure time and collect LIKWID metrics without flushing.

LineProfilerRegion

class scope_profiler.region_profiler.LineProfilerRegion(region_name, config)

Region that records timing and line-by-line profiling via line_profiler.

Uses line_profiler to collect per-line execution statistics for decorated functions. Also records nanosecond timestamps and flushes to HDF5.

Line-by-line profiling is most useful with the decorator (wrap) path, which automatically registers the function with the line profiler. When used as a context manager, the profiler is enabled/disabled around the block - any functions previously added via the decorator path will be profiled while the context is active.

Parameters:

• region_name (str)

• config (ProfilingConfig)

wrap(func)

Wrap a function to measure execution time and collect line-by-line stats.

add_function(func)

Register a function for line-by-line profiling.

Return type:

None

print_stats()

Print line-by-line profiling statistics.

get_stats()

Return the line_profiler stats object.

Post-processing

ProfilingH5Reader

class scope_profiler.h5reader.ProfilingH5Reader(file_path, verbose=False)

Reads profiling data stored by ProfileRegion in an HDF5 file.

Parameters:

• file_path (str | Path)

• verbose (bool)

get_region(region_name)

Retrieve profiling data for a specific region.

Parameters:

region_name (str) – Name of the region to retrieve.

Returns:

Region object containing profiling data for all ranks.

Return type:

Region

Raises:

KeyError – If the specified region name does not exist.

property file_path: Path

Get the path to the HDF5 file.

Returns:

The file path as a pathlib.Path object.

Return type:

Path

property num_ranks: int

Get the number of ranks recorded in the profiling data.

Returns:

Number of ranks.

Return type:

int

property minimum_start_time: float

Get the minimum start time across all regions and ranks.

Returns:

Minimum start time in seconds.

Return type:

float

get_regions(include=None, exclude=None)

Get a list of all regions in order of appearance.

Returns:

List of Region objects.

Return type:

List[Region]

Parameters:

• include (list[str] | str | None)

• exclude (list[str] | str | None)

Region

class scope_profiler.region.Region(start_times, end_times)

Parameters:

• start_times (ndarray)

• end_times (ndarray)

get_summary()

Return a summary of the region’s statistics as a dictionary.

Returns:

Dictionary containing statistics: num_calls, total_duration, average_duration, min_duration, max_duration, and std_duration.

Return type:

Dict[str, Any]

property start_times: ndarray

Start times of all calls in seconds.

property first_start_time: float

First start time in seconds.

property end_times: ndarray

End times of all calls in seconds.

property durations: ndarray

Duration of all calls in seconds.

property num_calls: int

Number of recorded calls.

property total_duration: float

Total time spent in this region (sum of all durations).

property average_duration: float

Average duration per call.

property min_duration: float

Minimum duration among all calls.

property max_duration: float

Maximum duration among all calls.

property std_duration: float

Standard deviation of durations.

MPIRegion

class scope_profiler.mpi_region.MPIRegion(name, regions)

Parameters:

• name (str)

• regions (Dict[int, Region])

property name: str

Name of the region.

property regions: Dict[int, Region]

Dictionary of rank IDs to their corresponding Region objects.

average_durations()

Get the average duration for each rank.

Returns:

Dictionary mapping rank IDs to their average durations.

Return type:

Dict[int, float]

min_durations()

Get the minimum duration for each rank.

Returns:

Dictionary mapping rank IDs to their minimum durations.

Return type:

Dict[int, float]

max_durations()

Get the maximum duration for each rank.

Returns:

Dictionary mapping rank IDs to their maximum durations.

Return type:

Dict[int, float]

property min_duration: float

Get the minimum duration across all ranks.

Returns:

The minimum duration among all ranks.

Return type:

float

property max_duration: float

Get the maximum duration across all ranks.

Returns:

The maximum duration among all ranks.

Return type:

float

property first_start_time: float

Get the earliest start time across all ranks.

Returns:

The earliest start time among all ranks.

Return type:

float

plot_gantt