# scope_profiler.speedscope_export

*module*

Export merged HDF5 profiling data to the speedscope JSON format.

A speedscope file is a single JSON document holding a table of frames and one
or more profiles referring to it. The profiles written here are *evented*: each
call contributes an open (``O``) and a close (``C``) event carrying a timestamp,
which preserves every individual call rather than the aggregate a ``.prof``
file keeps. Drop the file on https://www.speedscope.app to view it.

Regions carry no call graph of their own, so the caller/callee relations are
reconstructed from timestamp containment - the same reconstruction the flame
chart and the ``.prof`` export use
(:func:`~scope_profiler.call_stack.build_call_arrays`).

An evented profile is two events per call, so the output is inherently
proportional to the run. The reconstruction feeding it is not: it arrives as
columns, and only the events themselves are ever built as dicts.

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

## scope_profiler.speedscope_export.NS_PER_SECOND

*attribute* · *module attribute*

```python
NS_PER_SECOND = 1000000000.0
```

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

## scope_profiler.speedscope_export.SCHEMA_URL

*attribute* · *module attribute*

```python
SCHEMA_URL = 'https://www.speedscope.app/file-format-schema.json'
```

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

## scope_profiler.speedscope_export.TIME_UNIT

*attribute* · *module attribute*

```python
TIME_UNIT = 'seconds'
```

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

## scope_profiler.speedscope_export.build_speedscope_document

*function*

```python
def build_speedscope_document(named_calls: Sequence[tuple[str, CallArrays]], name: str) -> dict
```

Build a full speedscope document holding one profile per entry.

Parameters
----------
named_calls : sequence of (str, CallArrays)
    Profile name and calls for each profile to include, e.g. one per rank.
name : str
    Name of the document, shown in speedscope's title bar.

Returns
-------
dict
    The document, ready to be serialized as JSON.

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

## scope_profiler.speedscope_export.build_speedscope_profile

*function*

```python
def build_speedscope_profile(calls: CallArrays, name: str, frame_indices: dict[str, int], frames: list[dict], origin: float = 0.0) -> dict
```

Build one evented speedscope profile from reconstructed calls.

Parameters
----------
calls : CallArrays
    Calls as returned by
    :func:`~scope_profiler.call_stack.build_call_arrays`. Their intervals
    are properly nested, which is exactly what an evented profile needs:
    a frame can only close while it is on top of the stack.
name : str
    Name of the profile, shown in speedscope's profile selector.
frame_indices, frames : dict, list
    The document-wide frame table, extended in place: speedscope shares one
    table across all profiles in a file, so profiles of the same run refer
    to the same frames.
origin : float, optional
    Subtracted from every timestamp. Timestamps come from
    ``perf_counter_ns`` and are large in absolute terms; rebasing them on a
    common origin keeps the values readable (and precise) without shifting
    profiles relative to each other.

Returns
-------
dict
    A profile object as described by the speedscope file format schema.

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

## scope_profiler.speedscope_export.export_speedscope

*function*

```python
def export_speedscope(profiling_data: ProfilingResults | Sequence[ProfilingResults], filepath: str | Path, ranks: list[int] | int | None = None, include: list[str] | str | None = None, exclude: list[str] | str | None = None, verbose: bool = True) -> list[Path]
```

Write speedscope JSON files for the selected ranks.

One file is written per input HDF5 file, holding one profile per rank ---
or, for a run profiled with ``track_threads``, one per thread and task.
Unlike ``.prof``, the format carries several profiles per file, and
speedscope switches between them from its profile selector.

Parameters
----------
profiling_data : ProfilingResults | Sequence[ProfilingResults]
    The run(s) to export: file runs, in-memory results from
    ``ProfileManager.finalize(return_results=True)``, or a mix.
filepath : str | Path
    Base output path, e.g. ``figures/profile.speedscope.json``. The input
    file's stem is appended when more than one file is exported.
ranks : list[int] | int, optional
    Ranks to export (default: rank 0 only).
include, exclude : list[str] | str, optional
    Region name filters, as for the plotting functions.

Returns
-------
list[Path]
    The files written, in the order they were written.

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

## scope_profiler.speedscope_export.write_speedscope_file

*function*

```python
def write_speedscope_file(filepath: str | Path, document: dict) -> Path
```

Write a speedscope document to ``filepath`` as JSON.

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