scope_profiler.h5reader

Parsing of merged HDF5 profiling output files.

The public entry points are :meth:ProfilingResults.from_h5 <scope_profiler.results.ProfilingResults.from_h5> and its module-level twin :func:read_h5; both return a plain :class:~scope_profiler.results.ProfilingResults. This module holds only the HDF5 parsing that turns a merged file into that object’s constructor arguments.

Classes

Name	Description
CorruptProfileError	Raised when a profiling file cannot be opened as HDF5 at all.
SummaryDataUnavailable	Raised when a file predates fixed-size schema-2 summary columns.

Functions

Name	Description
load_h5	Parse a merged profiling file into :class:ProfilingResults arguments.
load_h5_summary	Parse fixed-size profile statistics without reading event datasets.
read_h5	Load a merged profiling file for post-processing.
read_h5_summary	Load fixed-size statistics, optionally falling back for older files.

CorruptProfileErrorclass#

View source

class CorruptProfileError(OSError)

Bases: OSError

Raised when a profiling file cannot be opened as HDF5 at all.

The common cause is a run that was killed while writing, leaving a truncated file behind. h5py reports that as a bare OSError naming neither the file nor what the caller was trying to do, so it is re-raised here with both. It stays an OSError so existing handlers keep working.

SummaryDataUnavailableclass#

View source

class SummaryDataUnavailable(ValueError)

Bases: ValueError

Raised when a file predates fixed-size schema-2 summary columns.

load_h5function#

View source

def load_h5(file_path: str | Path, verbose: bool = False) -> dict

Parse a merged profiling file into :class:ProfilingResults arguments.

This is the parsing half of :meth:~scope_profiler.results.ProfilingResults.from_h5, kept separate so the analysis layer does not depend on h5py. Call from_h5 or :func:read_h5 instead unless you are building a ProfilingResults subclass of your own.

Parameters

file_path : str | Path Path to the merged HDF5 file containing profiling data. verbose : bool, optional Print each rank group as it is read (default: False).

Returns

dict Keyword arguments for :class:~scope_profiler.results.ProfilingResults.

Raises

FileNotFoundError If the specified HDF5 file does not exist.

load_h5_summaryfunction#

View source

def load_h5_summary(file_path: str | Path, verbose: bool = False, *, include_likwid: bool = True, include_line_profile: bool = True, regions: str | list[str] | tuple[str, ...] | None = None, ranks: int | list[int] | tuple[int, ...] | None = None) -> dict

Parse fixed-size profile statistics without reading event datasets.

Summary columns were added compatibly within schema 2. Files that predate them raise :class:SummaryDataUnavailable; callers that require broad compatibility should use :func:read_h5_summary, which falls back to the normal eager reader by default.

read_h5function#

View source

def read_h5(file_path: str | Path, verbose: bool = False) -> ProfilingResults

Load a merged profiling file for post-processing.

The discoverable spelling of :meth:ProfilingResults.from_h5 <scope_profiler.results.ProfilingResults.from_h5>; the two are interchangeable::

from scope_profiler import read_h5

results = read_h5("profiling_data.h5")
results.print_summary()

solve = results["solve"]        # same as results.get_region("solve")
solve[0].average_duration       # rank 0, in seconds

Parameters

file_path : str | Path Path to the merged HDF5 file containing profiling data. verbose : bool, optional Print each rank group as it is read (default: False).

Returns

ProfilingResults The run’s profiling data. All durations are reported in seconds.

Raises

FileNotFoundError If the specified HDF5 file does not exist.

read_h5_summaryfunction#

View source

def read_h5_summary(file_path: str | Path, verbose: bool = False, *, fallback: bool = True, include_likwid: bool = True, include_line_profile: bool = True, regions: str | list[str] | tuple[str, ...] | None = None, ranks: int | list[int] | tuple[int, ...] | None = None) -> ProfilingResults

Load fixed-size statistics, optionally falling back for older files.

The returned object supports metadata and scalar region statistics. Event, timeline, call-stack and percentile APIs intentionally have no per-call data; use :func:read_h5 when those are required.