scope-profiler 0.2.3__tar.gz → 0.2.4__tar.gz

{scope_profiler-0.2.3 → scope_profiler-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scope-profiler
-Version: 0.2.3
+Version: 0.2.4
 Summary: Profile code regions in python, optionally with LIKWID markers.
 Author: Max
 Project-URL: Source, https://github.com/max-models/scope-profiler
@@ -445,3 +445,18 @@ Regions become "functions": `cumtime` is a region's total wall time and
 `tottime` is that minus the time spent in its nested regions. One file is
 written per exported rank, since `.prof` has no notion of ranks — see
 [the CLI docs](docs/source/cli.md) for the caveats of the reconstruction.
+
+### Viewing a run in speedscope
+
+`--export-speedscope` writes the run as a
+[speedscope](https://www.speedscope.app) JSON file. Unlike `.prof`, it keeps
+every individual call, so the timeline shows the run as it happened:
+
+```bash
+scope-profiler pproc profiling_data.h5 -o figures --export-speedscope --skip-plot-images
+npx speedscope figures/profile.speedscope.json  # or drop the file on speedscope.app
+```
+
+One file is written per input, holding one profile per exported rank, all
+sharing a time origin so ranks stay aligned. See
+[the CLI docs](docs/source/cli.md) for details.

{scope_profiler-0.2.3 → scope_profiler-0.2.4}/README.md

@@ -398,3 +398,18 @@ Regions become "functions": `cumtime` is a region's total wall time and
 `tottime` is that minus the time spent in its nested regions. One file is
 written per exported rank, since `.prof` has no notion of ranks — see
 [the CLI docs](docs/source/cli.md) for the caveats of the reconstruction.
+
+### Viewing a run in speedscope
+
+`--export-speedscope` writes the run as a
+[speedscope](https://www.speedscope.app) JSON file. Unlike `.prof`, it keeps
+every individual call, so the timeline shows the run as it happened:
+
+```bash
+scope-profiler pproc profiling_data.h5 -o figures --export-speedscope --skip-plot-images
+npx speedscope figures/profile.speedscope.json  # or drop the file on speedscope.app
+```
+
+One file is written per input, holding one profile per exported rank, all
+sharing a time origin so ranks stay aligned. See
+[the CLI docs](docs/source/cli.md) for details.

{scope_profiler-0.2.3 → scope_profiler-0.2.4}/pyproject.toml

@@ -5,7 +5,7 @@ requires = [ "setuptools", "wheel" ]
 
 [project]
 name = "scope-profiler"
-version = "0.2.3"
+version = "0.2.4"
 description = "Profile code regions in python, optionally with LIKWID markers."
 readme = "README.md"
 keywords = [ "python" ]

scope_profiler-0.2.4/src/scope_profiler/mpi_launch.py

@@ -0,0 +1,119 @@
+"""Detection of whether the process was launched by an MPI launcher.
+
+Importing ``mpi4py.MPI`` calls ``MPI_Init``, and any collective (``bcast``,
+``Barrier``, ...) issued afterwards costs something even on a single process.
+A plain ``python script.py`` run should therefore never touch MPI at all, even
+when mpi4py happens to be installed. This module answers the only question
+that decides it: was this process started by ``mpirun``/``mpiexec``/``srun``
+(or an equivalent launcher)?
+
+The answer is read from the environment the launcher sets up, so it is
+available before mpi4py is imported.
+"""
+
+import os
+import sys
+
+# Per-process variables exported by the process managers behind the common
+# launchers. Each is set only for processes started *by* the launcher, so the
+# presence of any one of them means "this rank belongs to an MPI job".
+# SLURM_PROCID is deliberately absent: it is also set for the script of a
+# plain `sbatch` job, which is not an MPI launch. `srun` is covered by the
+# PMI/PMIX variables its MPI plugin exports.
+_LAUNCHER_ENV_VARS = (
+    "OMPI_COMM_WORLD_RANK",  # Open MPI (and derivatives: Spectrum, ...)
+    "PMI_RANK",  # MPICH, Intel MPI, MS-MPI, Cray, srun (pmi2)
+    "PMIX_RANK",  # PMIx, used by srun --mpi=pmix and Open MPI 5
+    "MV2_COMM_WORLD_RANK",  # MVAPICH2
+    "MPI_LOCALRANKID",  # Hydra (mpiexec.hydra)
+    "ALPS_APP_PE",  # Cray ALPS aprun
+    "PALS_RANKID",  # Cray PALS palsrun
+)
+
+# Escape hatch: force the decision either way without touching code, e.g. for
+# a launcher whose variables are not listed above.
+_OVERRIDE_ENV_VAR = "SCOPE_PROFILER_MPI"
+
+_TRUE_VALUES = ("1", "true", "yes", "on")
+_FALSE_VALUES = ("0", "false", "no", "off")
+
+
+def _override() -> bool | None:
+    """Value of ``SCOPE_PROFILER_MPI``, or None if unset/unrecognized."""
+    value = os.environ.get(_OVERRIDE_ENV_VAR)
+    if value is None:
+        return None
+    value = value.strip().lower()
+    if value in _TRUE_VALUES:
+        return True
+    if value in _FALSE_VALUES:
+        return False
+    return None
+
+
+def launched_under_mpi() -> bool:
+    """Whether this process was started by an MPI launcher.
+
+    Returns
+    -------
+    bool
+        True if a launcher's per-rank environment variable is present, or if
+        the application itself already initialized MPI (in which case using
+        the communicator is free). ``SCOPE_PROFILER_MPI=0``/``1`` overrides
+        the detection.
+    """
+    override = _override()
+    if override is not None:
+        return override
+
+    if any(var in os.environ for var in _LAUNCHER_ENV_VARS):
+        return True
+
+    # The application may have initialized MPI itself (embedded interpreter,
+    # or an explicit `from mpi4py import MPI`). Only inspect mpi4py if it is
+    # already imported: importing it here is exactly what must be avoided.
+    mpi_module = sys.modules.get("mpi4py.MPI")
+    if mpi_module is not None:
+        try:
+            return bool(mpi_module.Is_initialized())
+        except AttributeError:
+            return False
+
+    return False
+
+
+def get_comm(use_mpi: bool | None = None):
+    """Return ``MPI.COMM_WORLD``, or None when MPI must not be used.
+
+    Parameters
+    ----------
+    use_mpi : bool or None, optional
+        None (default) decides via :func:`launched_under_mpi`. True forces the
+        communicator (and fails loudly if mpi4py is missing); False disables
+        MPI unconditionally.
+
+    Returns
+    -------
+    mpi4py.MPI.Intracomm or None
+        The world communicator, or None if this is not an MPI run or mpi4py
+        is unavailable.
+    """
+    if use_mpi is False:
+        return None
+
+    if use_mpi is None and not launched_under_mpi():
+        return None
+
+    try:
+        from mpi4py import MPI
+    except ImportError:
+        if use_mpi:
+            raise ImportError(
+                "MPI profiling was requested (use_mpi=True) but mpi4py is not "
+                "installed."
+            )
+        # Launched by mpirun without mpi4py available: fall back to treating
+        # this rank as a standalone process rather than failing the run.
+        return None
+
+    return MPI.COMM_WORLD

{scope_profiler-0.2.3 → scope_profiler-0.2.4}/src/scope_profiler/post_processing.py

@@ -14,6 +14,7 @@ from scope_profiler.plotting_scripts import (
     write_region_statistics_json,
 )
 from scope_profiler.prof_export import export_prof
+from scope_profiler.speedscope_export import export_speedscope
 
 
 def parse_ranks(spec: str, verbose: bool = False) -> list[int]:
@@ -168,14 +169,27 @@ def build_parser() -> argparse.ArgumentParser:
             "-o/--output."
         ),
     )
+    parser.add_argument(
+        "--export-speedscope",
+        action="store_true",
+        help=(
+            "Also write a profile.speedscope.json file holding one profile per "
+            "exported rank, viewable at https://www.speedscope.app (or with "
+            "`npx speedscope profile.speedscope.json`). Unlike --export-prof "
+            "this keeps every individual call, so the timeline shows the run "
+            "as it happened. The call graph is reconstructed from region "
+            "nesting; only ranks selected with --ranks are exported (default: "
+            "rank 0). Requires -o/--output."
+        ),
+    )
     parser.add_argument(
         "--skip-plot-images",
         action="store_true",
         help=(
             "Do not render/save the PNG plot images, only the outputs from "
-            "--export-data/--export-prof. Useful when charts are rendered "
-            "entirely client-side (e.g. with Plotly) from the exported data. "
-            "Requires --export-data or --export-prof."
+            "--export-data/--export-prof/--export-speedscope. Useful when "
+            "charts are rendered entirely client-side (e.g. with Plotly) from "
+            "the exported data. Requires one of those export options."
         ),
     )
     return parser
@@ -219,8 +233,15 @@ def main(argv: list[str] | None = None):
     if args.export_prof and not args.output:
         parser.error("--export-prof requires -o/--output.")
 
-    if args.skip_plot_images and not (args.export_data or args.export_prof):
-        parser.error("--skip-plot-images requires --export-data or --export-prof.")
+    if args.export_speedscope and not args.output:
+        parser.error("--export-speedscope requires -o/--output.")
+
+    exports_requested = args.export_data or args.export_prof or args.export_speedscope
+    if args.skip_plot_images and not exports_requested:
+        parser.error(
+            "--skip-plot-images requires --export-data, --export-prof or "
+            "--export-speedscope."
+        )
 
     if args.ranks:
         ranks = []
@@ -261,6 +282,8 @@ def main(argv: list[str] | None = None):
     speedup_data_path = None
     prof_path = None
     prof_paths: list = []
+    speedscope_path = None
+    speedscope_paths: list = []
     durations_paths: list = []
     if args.output:
         os.makedirs(args.output, exist_ok=True)
@@ -287,10 +310,12 @@ def main(argv: list[str] | None = None):
                 )
         if args.export_prof:
             prof_path = os.path.join(args.output, "profile.prof")
+        if args.export_speedscope:
+            speedscope_path = os.path.join(args.output, "profile.speedscope.json")
 
     # --skip-plot-images still needs the plotting functions to produce the
-    # --export-data files, but a prof-only run should not touch the plotting
-    # backend at all.
+    # --export-data files, but an export-only run should not touch the
+    # plotting backend at all.
     render_plots = not args.skip_plot_images or args.export_data
 
     if args.export_prof:
@@ -303,6 +328,16 @@ def main(argv: list[str] | None = None):
             verbose=False,
         )
 
+    if args.export_speedscope:
+        speedscope_paths = export_speedscope(
+            profiling_data=readers,
+            filepath=speedscope_path,
+            ranks=args.ranks,
+            include=args.include,
+            exclude=args.exclude,
+            verbose=False,
+        )
+
     if render_plots:
         plot_gantt(
             profiling_data=readers,
@@ -382,12 +417,18 @@ def main(argv: list[str] | None = None):
                 durations_data_path,
                 speedup_data_path,
                 *prof_paths,
+                *speedscope_paths,
             )
             if path
         ]
         print("Outputs saved to:\n  " + "\n  ".join(saved))
         if prof_paths:
             print(f"\nView a .prof file with: snakeviz {prof_paths[0]}")
+        if speedscope_paths:
+            print(
+                f"\nView {speedscope_paths[0]} at https://www.speedscope.app "
+                "(or: npx speedscope <file>)"
+            )
 
 
 if __name__ == "__main__":

{scope_profiler-0.2.3 → scope_profiler-0.2.4}/src/scope_profiler/profile_config.py

@@ -6,18 +6,11 @@ from time import perf_counter_ns
 from typing import TYPE_CHECKING
 
 from scope_profiler.metadata import collect_metadata
+from scope_profiler.mpi_launch import get_comm
 
 if TYPE_CHECKING:
     from mpi4py.MPI import Intercomm
 
-try:
-    from mpi4py import MPI
-
-    _MPI_AVAILABLE = True
-except ImportError:
-    MPI = None
-    _MPI_AVAILABLE = False
-
 # try:
 # import pylikwid
 #     _PYLIKWID_AVAILABLE = True
@@ -72,6 +65,7 @@ class ProfilingConfig:
         flush_to_disk: bool = True,
         buffer_limit: int = 1024,
         file_path: str = "profiling_data.h5",
+        use_mpi: bool | None = None,
     ):
         """Initialize the profiling configuration.
 
@@ -94,6 +88,11 @@ class ProfilingConfig:
             The buffers grow on demand, so this is a starting size, not a cap.
         file_path : str
             Global output file path for combined profiling data.
+        use_mpi : bool or None
+            Whether to use MPI collectives. None (default) enables them only
+            when the process was started by an MPI launcher (mpirun/mpiexec/
+            srun/...); see :mod:`scope_profiler.mpi_launch`. True forces MPI
+            on, False forces it off.
         """
 
         if self._initialized:
@@ -101,10 +100,10 @@ class ProfilingConfig:
 
         self._config_creation_time = perf_counter_ns()
 
-        if _MPI_AVAILABLE:
-            self._comm = MPI.COMM_WORLD
-        else:
-            self._comm = None
+        # Serial runs must not import mpi4py (which would call MPI_Init) nor
+        # issue any collective, so the communicator stays None unless this
+        # process really is part of an MPI job.
+        self._comm = get_comm(use_mpi)
         self._profiling_activated = profiling_activated
         self._use_likwid = use_likwid
         self._use_line_profiler = use_line_profiler

{scope_profiler-0.2.3 → scope_profiler-0.2.4}/src/scope_profiler/profile_manager.py

@@ -485,6 +485,7 @@ class ProfileManager:
         flush_to_disk: bool = True,
         buffer_limit: int = 1024,
         file_path: str = "profiling_data.h5",
+        use_mpi: bool | None = None,
     ):
         """
         Initialize and configure the profiling system.
@@ -513,6 +514,12 @@ class ProfileManager:
             repeated reallocation.
         file_path : str, optional
             Path to the output profiling data file (default: "profiling_data.h5").
+        use_mpi : bool or None, optional
+            Whether to use MPI collectives (default: None). None auto-detects:
+            MPI is used only when the process was launched by mpirun/mpiexec/
+            srun or an equivalent launcher, so a plain ``python script.py``
+            run never imports mpi4py or calls into MPI. True forces MPI on,
+            False forces it off.
         """
         ProfilingConfig().reset()
         config = ProfilingConfig(
@@ -524,6 +531,7 @@ class ProfileManager:
             flush_to_disk=flush_to_disk,
             buffer_limit=buffer_limit,
             file_path=file_path,
+            use_mpi=use_mpi,
         )
         cls.set_config(config=config)
 

scope_profiler-0.2.4/src/scope_profiler/speedscope_export.py

@@ -0,0 +1,271 @@
+"""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.plotting_scripts._build_call_stack_intervals`).
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Sequence
+from pathlib import Path
+
+from scope_profiler.h5reader import ProfilingH5Reader
+from scope_profiler.plotting_scripts import (
+    _as_readers,
+    _build_call_stack_intervals,
+    _normalize_ranks,
+    _unique_labels,
+)
+
+SCHEMA_URL = "https://www.speedscope.app/file-format-schema.json"
+
+# Timestamps are seconds throughout the reader API, so the profiles say so
+# rather than converting back to the nanoseconds the HDF5 files store.
+TIME_UNIT = "seconds"
+
+
+def _exporter_name() -> str:
+    """Identify this package (and version) as the producer of the file."""
+    from scope_profiler import __version__
+
+    return f"scope-profiler@{__version__}"
+
+
+def _nested_intervals(calls: list[dict]) -> list[tuple[float, float]]:
+    """Return each call's interval, tightened to fit inside its parent's.
+
+    An evented profile is a stack machine: a frame can only close while it is
+    on top of the stack, so every call must lie entirely within its parent.
+    Reconstruction by containment does not guarantee that - a region that
+    starts inside another but ends after it is still recorded as its child -
+    so such an interval is clipped to the enclosing one. The clipping is
+    visible only where regions genuinely overlap, which no real call stack
+    does.
+    """
+    intervals: list[tuple[float, float]] = []
+    for call in calls:
+        start, end = call["start"], call["end"]
+        parent = call["parent"]
+        if parent is not None:
+            # Parents precede their children here, so the bound is final.
+            low, high = intervals[parent]
+            start = min(max(start, low), high)
+            end = min(max(end, start), high)
+        intervals.append((start, end))
+    return intervals
+
+
+def build_speedscope_profile(
+    calls: list[dict],
+    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 : list[dict]
+        Calls as returned by
+        :func:`~scope_profiler.plotting_scripts._build_call_stack_intervals`:
+        each entry has ``name``, ``start`` and ``end`` in seconds, and
+        ``parent`` (an index into this list, or ``None`` for a top-level call).
+    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.
+    """
+    intervals = _nested_intervals(calls)
+
+    children: dict[int | None, list[int]] = {}
+    for index, call in enumerate(calls):
+        children.setdefault(call["parent"], []).append(index)
+
+    events = []
+    # Depth-first over the reconstructed tree, siblings in start order (which
+    # is the order `calls` is already in). Emitting events this way makes them
+    # balanced by construction, instead of sorting timestamps and hoping.
+    stack: list[tuple[int, bool]] = [
+        (index, False) for index in reversed(children.get(None, []))
+    ]
+    while stack:
+        index, closing = stack.pop()
+        start, end = intervals[index]
+        frame_name = calls[index]["name"]
+        if closing:
+            events.append({"type": "C", "frame": frame_indices[frame_name], "at": end})
+            continue
+
+        if frame_name not in frame_indices:
+            frame_indices[frame_name] = len(frames)
+            frames.append({"name": frame_name})
+        events.append({"type": "O", "frame": frame_indices[frame_name], "at": start})
+        stack.append((index, True))
+        stack.extend((child, False) for child in reversed(children.get(index, [])))
+
+    for event in events:
+        event["at"] -= origin
+
+    return {
+        "type": "evented",
+        "name": name,
+        "unit": TIME_UNIT,
+        "startValue": events[0]["at"] if events else 0.0,
+        "endValue": events[-1]["at"] if events else 0.0,
+        "events": events,
+    }
+
+
+def build_speedscope_document(
+    named_calls: Sequence[tuple[str, list[dict]]],
+    name: str,
+) -> dict:
+    """Build a full speedscope document holding one profile per entry.
+
+    Parameters
+    ----------
+    named_calls : sequence of (str, list[dict])
+        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.
+    """
+    starts = [
+        calls[0]["start"] for _, calls in named_calls if calls
+    ]  # calls are start-ordered
+    origin = min(starts) if starts else 0.0
+
+    frames: list[dict] = []
+    frame_indices: dict[str, int] = {}
+    profiles = [
+        build_speedscope_profile(
+            calls,
+            profile_name,
+            frame_indices=frame_indices,
+            frames=frames,
+            origin=origin,
+        )
+        for profile_name, calls in named_calls
+    ]
+
+    return {
+        "$schema": SCHEMA_URL,
+        "exporter": _exporter_name(),
+        "name": name,
+        "activeProfileIndex": 0,
+        "shared": {"frames": frames},
+        "profiles": profiles,
+    }
+
+
+def write_speedscope_file(filepath: str | Path, document: dict) -> Path:
+    """Write a speedscope document to ``filepath`` as JSON."""
+    output_path = Path(filepath)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(output_path, "w", encoding="utf-8") as f:
+        json.dump(document, f)
+    return output_path
+
+
+def export_speedscope(
+    profiling_data: ProfilingH5Reader | Sequence[ProfilingH5Reader],
+    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:
+    unlike ``.prof``, the format carries several profiles per file, and
+    speedscope switches between them from its profile selector.
+
+    Parameters
+    ----------
+    profiling_data : ProfilingH5Reader | Sequence[ProfilingH5Reader]
+        Reader(s) for the merged HDF5 file(s) to export.
+    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.
+    """
+    readers = _as_readers(profiling_data)
+    if not readers:
+        raise ValueError("No profiling data provided.")
+
+    normalized_ranks = _normalize_ranks(ranks) if ranks is not None else [0]
+
+    labels = _unique_labels([reader.file_path.stem for reader in readers])
+
+    prepared = []
+    for label, reader in zip(labels, readers):
+        regions = reader.get_regions(include=include, exclude=exclude)
+        if not regions:
+            raise ValueError("No regions matched the selected filters.")
+        named_calls = []
+        for rank in normalized_ranks:
+            if rank < 0 or rank >= reader.num_ranks:
+                raise ValueError(f"Invalid rank requested: {rank}")
+            calls = _build_call_stack_intervals(regions, rank)
+            if calls:
+                named_calls.append((f"rank {rank}", calls))
+        if named_calls:
+            prepared.append((label, named_calls))
+
+    if not prepared:
+        raise ValueError("No calls recorded for the requested ranks.")
+
+    base_path = Path(filepath)
+    # ".speedscope.json" is the conventional extension, and Path.suffix only
+    # sees the ".json" half of it, so the whole tail is kept here.
+    stem, dot, extension = base_path.name.partition(".")
+    suffix = f".{extension}" if dot else ".speedscope.json"
+    multiple_files = len(readers) > 1
+
+    written = []
+    for label, named_calls in prepared:
+        parts = [stem]
+        if multiple_files:
+            parts.append(label)
+        out_path = base_path.with_name("_".join(parts) + suffix)
+        document = build_speedscope_document(named_calls, name=label)
+        written.append(write_speedscope_file(out_path, document))
+        if verbose:
+            print(f"Wrote {out_path} (view at https://www.speedscope.app)")
+
+    return written

scope_profiler-0.2.4/src/scope_profiler/tests/check_mpi_launch.py

@@ -0,0 +1,66 @@
+"""Assert that MPI is used if and only if the run was started by a launcher.
+
+Run twice from CI with mpi4py installed, so that the two outcomes differ only
+in how the process was started::
+
+    python3 check_mpi_launch.py serial
+    mpirun -n 2 python3 check_mpi_launch.py mpi 2
+
+``serial`` asserts that no MPI call happens at all -- in particular that
+``mpi4py.MPI`` is never imported, since importing it already calls
+``MPI_Init``. ``mpi`` asserts that the communicator is picked up and that all
+ranks end up in the merged output.
+
+This lives outside the pytest suite because the launcher is the thing under
+test; pytest itself is never started by mpirun.
+"""
+
+import sys
+
+import h5py
+
+from scope_profiler import ProfileManager
+
+OUTPUT_FILE = "mpi_launch_check.h5"
+
+
+def check(mode: str, expected_size: int) -> None:
+    """Profile a trivial region and verify the MPI behaviour for ``mode``."""
+    ProfileManager.setup(time_trace=True, flush_to_disk=True, file_path=OUTPUT_FILE)
+    config = ProfileManager.get_config()
+
+    with ProfileManager.profile_region("check"):
+        sum(range(1000))
+
+    if mode == "serial":
+        assert "mpi4py.MPI" not in sys.modules, (
+            "mpi4py.MPI was imported in a run that was not started by an MPI "
+            "launcher; importing it calls MPI_Init."
+        )
+        assert config.comm is None, f"expected no communicator, got {config.comm!r}"
+    else:
+        assert (
+            config.comm is not None
+        ), "no communicator, although the run was started by an MPI launcher"
+
+    assert (
+        config._size == expected_size
+    ), f"expected {expected_size} rank(s), got {config._size}"
+
+    ProfileManager.finalize(verbose=False)
+
+    if config._rank == 0:
+        with h5py.File(OUTPUT_FILE, "r") as f:
+            ranks = sorted(key for key in f if key.startswith("rank"))
+        expected_ranks = [f"rank{r}" for r in range(expected_size)]
+        assert ranks == expected_ranks, f"expected {expected_ranks}, got {ranks}"
+
+    print(f"[{mode}] OK: rank {config._rank} of {config._size}, comm={config.comm}")
+
+
+if __name__ == "__main__":
+    mode = sys.argv[1] if len(sys.argv) > 1 else "serial"
+    if mode not in ("serial", "mpi"):
+        sys.exit(f"usage: {sys.argv[0]} [serial|mpi] [expected_size]")
+    size = int(sys.argv[2]) if len(sys.argv) > 2 else 1
+    check(mode, size)

scope_profiler-0.2.4/src/scope_profiler/tests/test_speedscope_export.py

@@ -0,0 +1,227 @@
+import json
+
+import pytest
+
+from scope_profiler.h5reader import ProfilingH5Reader
+from scope_profiler.post_processing import main
+from scope_profiler.speedscope_export import (
+    build_speedscope_document,
+    export_speedscope,
+)
+from scope_profiler.tests.test_post_processing import _write_sample_h5
+
+MS = 1_000_000  # nanoseconds per millisecond, the unit stored in the HDF5 files
+
+
+def _nested_file_data():
+    """One rank whose regions nest: main > (setup, solve > assemble)."""
+    return {
+        0: {
+            "main": ([0], [100 * MS]),
+            "setup": ([0], [20 * MS]),
+            "solve": ([20 * MS], [90 * MS]),
+            "assemble": ([30 * MS], [60 * MS]),
+        }
+    }
+
+
+def _calls(*specs):
+    """Build the call list the document builder expects, in seconds."""
+    return [
+        {"name": name, "start": start, "end": end, "parent": parent}
+        for name, start, end, parent in specs
+    ]
+
+
+def _load(path):
+    with open(path, encoding="utf-8") as f:
+        return json.load(f)
+
+
+def _replay(profile, frames):
+    """Replay an evented profile, returning (frame name, start, end) per call.
+
+    Raises if the events are not a balanced, correctly ordered stack machine —
+    which is what speedscope requires and refuses to import without.
+    """
+    stack = []
+    closed = []
+    last_at = float("-inf")
+    for event in profile["events"]:
+        assert event["at"] >= last_at, "events must be ordered by timestamp"
+        last_at = event["at"]
+        if event["type"] == "O":
+            stack.append((frames[event["frame"]]["name"], event["at"]))
+        else:
+            assert stack, "close event with nothing open"
+            name, start = stack.pop()
+            assert (
+                frames[event["frame"]]["name"] == name
+            ), "closed a frame that was not on top of the stack"
+            closed.append((name, start, event["at"]))
+    assert not stack, "profile ended with frames still open"
+    return closed
+
+
+def test_document_events_replay_as_a_call_stack():
+    calls = _calls(
+        ("main", 10.0, 11.0, None),
+        ("setup", 10.0, 10.2, 0),
+        ("solve", 10.2, 10.9, 0),
+        ("assemble", 10.3, 10.6, 2),
+    )
+
+    document = build_speedscope_document([("rank 0", calls)], name="run")
+    (profile,) = document["profiles"]
+
+    # Timestamps are rebased on the first call, so the profile starts at zero.
+    assert profile["startValue"] == pytest.approx(0.0)
+    assert profile["endValue"] == pytest.approx(1.0)
+    assert profile["unit"] == "seconds"
+    assert profile["type"] == "evented"
+
+    replayed = _replay(profile, document["shared"]["frames"])
+    assert replayed == [
+        ("setup", pytest.approx(0.0), pytest.approx(0.2)),
+        ("assemble", pytest.approx(0.3), pytest.approx(0.6)),
+        ("solve", pytest.approx(0.2), pytest.approx(0.9)),
+        ("main", pytest.approx(0.0), pytest.approx(1.0)),
+    ]
+
+
+def test_document_clips_partial_overlap():
+    # "long" is reconstructed as a child of "short" because it starts inside
+    # it, even though it runs past its end: an evented profile cannot express
+    # that, so the child is clipped to its parent.
+    calls = _calls(("short", 0.0, 0.5, None), ("long", 0.1, 2.0, 0))
+
+    document = build_speedscope_document([("rank 0", calls)], name="run")
+    replayed = _replay(document["profiles"][0], document["shared"]["frames"])
+
+    assert replayed == [
+        ("long", pytest.approx(0.1), pytest.approx(0.5)),
+        ("short", pytest.approx(0.0), pytest.approx(0.5)),
+    ]
+
+
+def test_document_handles_recursion():
+    calls = _calls(("recurse", 0.0, 1.0, None), ("recurse", 0.2, 0.6, 0))
+
+    document = build_speedscope_document([("rank 0", calls)], name="run")
+
+    # The frame table is keyed by name, so recursion reuses one frame.
+    assert document["shared"]["frames"] == [{"name": "recurse"}]
+    assert len(_replay(document["profiles"][0], document["shared"]["frames"])) == 2
+
+
+def test_export_writes_one_profile_per_rank(tmp_path):
+    h5_file = tmp_path / "profiling_data.h5"
+    _write_sample_h5(h5_file, {rank: _nested_file_data()[0] for rank in (0, 1)})
+
+    written = export_speedscope(
+        ProfilingH5Reader(h5_file),
+        tmp_path / "profile.speedscope.json",
+        ranks=[0, 1],
+        verbose=False,
+    )
+
+    assert written == [tmp_path / "profile.speedscope.json"]
+
+    document = _load(written[0])
+    assert document["$schema"] == "https://www.speedscope.app/file-format-schema.json"
+    assert document["exporter"].startswith("scope-profiler@")
+    assert document["activeProfileIndex"] == 0
+    assert [profile["name"] for profile in document["profiles"]] == ["rank 0", "rank 1"]
+    assert {frame["name"] for frame in document["shared"]["frames"]} == {
+        "main",
+        "setup",
+        "solve",
+        "assemble",
+    }
+
+    for profile in document["profiles"]:
+        replayed = _replay(profile, document["shared"]["frames"])
+        assert len(replayed) == 4
+        main_call = next(call for call in replayed if call[0] == "main")
+        assert main_call[2] - main_call[1] == pytest.approx(0.1)
+
+
+def test_export_defaults_to_rank_zero_and_splits_per_file(tmp_path):
+    file_one = tmp_path / "run_one.h5"
+    file_two = tmp_path / "run_two.h5"
+    _write_sample_h5(file_one, {rank: _nested_file_data()[0] for rank in (0, 1)})
+    _write_sample_h5(file_two, {rank: _nested_file_data()[0] for rank in (0, 1)})
+
+    readers = [ProfilingH5Reader(file_one), ProfilingH5Reader(file_two)]
+    written = export_speedscope(
+        readers, tmp_path / "profile.speedscope.json", verbose=False
+    )
+
+    assert [path.name for path in written] == [
+        "profile_run_one.speedscope.json",
+        "profile_run_two.speedscope.json",
+    ]
+    for path in written:
+        document = _load(path)
+        assert [profile["name"] for profile in document["profiles"]] == ["rank 0"]
+
+
+def test_export_rejects_unknown_rank(tmp_path):
+    h5_file = tmp_path / "profiling_data.h5"
+    _write_sample_h5(h5_file, _nested_file_data())
+
+    with pytest.raises(ValueError, match="Invalid rank"):
+        export_speedscope(
+            ProfilingH5Reader(h5_file),
+            tmp_path / "profile.speedscope.json",
+            ranks=[3],
+            verbose=False,
+        )
+
+
+def test_cli_export_speedscope_without_plots(tmp_path, capsys):
+    h5_file = tmp_path / "profiling_data.h5"
+    _write_sample_h5(h5_file, _nested_file_data())
+    out_dir = tmp_path / "figures"
+
+    main(
+        [
+            str(h5_file),
+            "-o",
+            str(out_dir),
+            "--export-speedscope",
+            "--skip-plot-images",
+        ]
+    )
+
+    speedscope_file = out_dir / "profile.speedscope.json"
+    assert speedscope_file.exists()
+    assert not list(out_dir.glob("*.png"))
+    assert "speedscope.app" in capsys.readouterr().out
+
+    document = _load(speedscope_file)
+    assert {frame["name"] for frame in document["shared"]["frames"]} == {
+        "main",
+        "setup",
+        "solve",
+        "assemble",
+    }
+
+
+def test_cli_export_speedscope_alongside_plots(tmp_path):
+    h5_file = tmp_path / "profiling_data.h5"
+    _write_sample_h5(h5_file, _nested_file_data())
+    out_dir = tmp_path / "figures"
+
+    main([str(h5_file), "-o", str(out_dir), "--export-speedscope", "--ranks", "0"])
+
+    assert (out_dir / "profile.speedscope.json").exists()
+    assert (out_dir / "flame_plot.png").exists()
+
+
+def test_cli_export_speedscope_requires_output(tmp_path):
+    h5_file = tmp_path / "profiling_data.h5"
+    _write_sample_h5(h5_file, _nested_file_data())
+
+    with pytest.raises(SystemExit):
+        main([str(h5_file), "--export-speedscope"])

scope_profiler-0.2.4/src/scope_profiler/tests/unit/test_mpi_launch.py

@@ -0,0 +1,90 @@
+"""Tests for MPI-launcher detection (``scope_profiler.mpi_launch``)."""
+
+import sys
+
+import pytest
+
+from scope_profiler.mpi_launch import (
+    _LAUNCHER_ENV_VARS,
+    _OVERRIDE_ENV_VAR,
+    get_comm,
+    launched_under_mpi,
+)
+
+
+@pytest.fixture
+def clean_env(monkeypatch):
+    """An environment with no launcher variables and no override."""
+    for var in _LAUNCHER_ENV_VARS + (_OVERRIDE_ENV_VAR,):
+        monkeypatch.delenv(var, raising=False)
+    # A previous test (or the application) may have imported mpi4py; hide it
+    # so detection sees a genuinely serial process.
+    monkeypatch.delitem(sys.modules, "mpi4py.MPI", raising=False)
+    return monkeypatch
+
+
+def test_serial_run_is_not_mpi(clean_env):
+    assert launched_under_mpi() is False
+    assert get_comm() is None
+
+
+@pytest.mark.parametrize("var", _LAUNCHER_ENV_VARS)
+def test_launcher_variables_are_detected(clean_env, var):
+    clean_env.setenv(var, "0")
+    assert launched_under_mpi() is True
+
+
+def test_override_forces_mpi_on(clean_env):
+    clean_env.setenv(_OVERRIDE_ENV_VAR, "1")
+    assert launched_under_mpi() is True
+
+
+def test_override_forces_mpi_off(clean_env):
+    clean_env.setenv("OMPI_COMM_WORLD_RANK", "0")
+    clean_env.setenv(_OVERRIDE_ENV_VAR, "false")
+    assert launched_under_mpi() is False
+
+
+def test_unrecognized_override_falls_back_to_detection(clean_env):
+    clean_env.setenv(_OVERRIDE_ENV_VAR, "maybe")
+    assert launched_under_mpi() is False
+
+
+def test_already_initialized_mpi_is_used(clean_env):
+    class FakeMPI:
+        @staticmethod
+        def Is_initialized():
+            return True
+
+    clean_env.setitem(sys.modules, "mpi4py.MPI", FakeMPI)
+    assert launched_under_mpi() is True
+
+
+def test_imported_but_uninitialized_mpi_is_not_used(clean_env):
+    class FakeMPI:
+        @staticmethod
+        def Is_initialized():
+            return False
+
+    clean_env.setitem(sys.modules, "mpi4py.MPI", FakeMPI)
+    assert launched_under_mpi() is False
+
+
+def test_use_mpi_false_never_imports_mpi4py(clean_env):
+    clean_env.setenv("OMPI_COMM_WORLD_RANK", "0")
+    assert get_comm(use_mpi=False) is None
+
+
+def test_serial_setup_does_not_import_mpi4py(clean_env, tmp_path):
+    """A serial ProfileManager.setup() must leave mpi4py unimported."""
+    from scope_profiler import ProfileManager
+
+    clean_env.delitem(sys.modules, "mpi4py", raising=False)
+
+    ProfileManager.setup(file_path=str(tmp_path / "profiling_data.h5"))
+    config = ProfileManager.get_config()
+
+    assert config.comm is None
+    assert config._rank == 0
+    assert config._size == 1
+    assert "mpi4py.MPI" not in sys.modules

{scope_profiler-0.2.3 → scope_profiler-0.2.4}/src/scope_profiler.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scope-profiler
-Version: 0.2.3
+Version: 0.2.4
 Summary: Profile code regions in python, optionally with LIKWID markers.
 Author: Max
 Project-URL: Source, https://github.com/max-models/scope-profiler
@@ -445,3 +445,18 @@ Regions become "functions": `cumtime` is a region's total wall time and
 `tottime` is that minus the time spent in its nested regions. One file is
 written per exported rank, since `.prof` has no notion of ranks — see
 [the CLI docs](docs/source/cli.md) for the caveats of the reconstruction.
+
+### Viewing a run in speedscope
+
+`--export-speedscope` writes the run as a
+[speedscope](https://www.speedscope.app) JSON file. Unlike `.prof`, it keeps
+every individual call, so the timeline shows the run as it happened:
+
+```bash
+scope-profiler pproc profiling_data.h5 -o figures --export-speedscope --skip-plot-images
+npx speedscope figures/profile.speedscope.json  # or drop the file on speedscope.app
+```
+
+One file is written per input, holding one profile per exported rank, all
+sharing a time origin so ranks stay aligned. See
+[the CLI docs](docs/source/cli.md) for details.

{scope_profiler-0.2.3 → scope_profiler-0.2.4}/src/scope_profiler.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ src/scope_profiler/__main__.py
 src/scope_profiler/h5reader.py
 src/scope_profiler/inspection.py
 src/scope_profiler/metadata.py
+src/scope_profiler/mpi_launch.py
 src/scope_profiler/mpi_region.py
 src/scope_profiler/plotting_scripts.py
 src/scope_profiler/post_processing.py
@@ -13,6 +14,7 @@ src/scope_profiler/profile_config.py
 src/scope_profiler/profile_manager.py
 src/scope_profiler/region.py
 src/scope_profiler/region_profiler.py
+src/scope_profiler/speedscope_export.py
 src/scope_profiler/summary.py
 src/scope_profiler.egg-info/PKG-INFO
 src/scope_profiler.egg-info/SOURCES.txt
@@ -21,6 +23,7 @@ src/scope_profiler.egg-info/entry_points.txt
 src/scope_profiler.egg-info/requires.txt
 src/scope_profiler.egg-info/top_level.txt
 src/scope_profiler/tests/__init__.py
+src/scope_profiler/tests/check_mpi_launch.py
 src/scope_profiler/tests/examples.py
 src/scope_profiler/tests/examples_pylikwid.py
 src/scope_profiler/tests/pylikwid_readme.py
@@ -34,4 +37,7 @@ src/scope_profiler/tests/test_post_processing.py
 src/scope_profiler/tests/test_prof_export.py
 src/scope_profiler/tests/test_reader_api.py
 src/scope_profiler/tests/test_readme.py
-src/scope_profiler/tests/test_repeated_finalize.py
+src/scope_profiler/tests/test_repeated_finalize.py
+src/scope_profiler/tests/test_speedscope_export.py
+src/scope_profiler/tests/unit/__init__.py
+src/scope_profiler/tests/unit/test_mpi_launch.py