# scope_profiler.h5reader

*module*

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.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/h5reader.py#L1-L1)

## scope_profiler.h5reader.CorruptProfileError

*class*

```python
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.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/h5reader.py#L29-L36)

## scope_profiler.h5reader.SummaryDataUnavailable

*class*

```python
class SummaryDataUnavailable(ValueError)
```

Bases: `ValueError`

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

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/h5reader.py#L25-L26)

## scope_profiler.h5reader.load_h5

*function*

```python
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.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/h5reader.py#L449-L624)

## scope_profiler.h5reader.load_h5_summary

*function*

```python
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.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/h5reader.py#L627-L840)

## scope_profiler.h5reader.read_h5

*function*

```python
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.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/h5reader.py#L843-L877)

## scope_profiler.h5reader.read_h5_summary

*function*

```python
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.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/h5reader.py#L880-L952)