scope-profiler

scope-profiler#

A lightweight, low-overhead profiling framework for Python and HPC applications.

scope-profiler lets you instrument code regions with decorators or context managers, collect nanosecond-resolution timing traces, and optionally integrate LIKWID hardware performance counters or line_profiler line-by-line analysis — all through a single, unified API.

Key features#

  • Two instrumentation styles — @ProfileManager.profile decorator and with ProfileManager.region() context manager.

  • Near-zero overhead — the default timing mode adds ~700 ns per call; profiling can be toggled off at startup with no code changes.

  • HDF5 time traces — start/end timestamps are flushed to disk and merged automatically, ready for post-hoc analysis and Gantt charts.

  • MPI-aware — per-rank data is collected and merged transparently via mpi4py.

  • LIKWID integration — hardware counter regions are opened/closed alongside timing, with no extra boilerplate, and every marker region’s raw events and derived metrics land in the same HDF5 file.

  • Line profiler integration — enable line_profiler per-line stats on any decorated function with a single flag.

  • CLI post-processing — scope-profiler plot reads HDF5 output and generates Gantt charts and exports region statistics JSON with region/rank filtering.

  • MCP server — scope-profiler-mcp exposes structured profiling data to AI coding agents such as Claude Code, so an agent can inspect a run, benchmark a script and compare before/after profiles as part of its own workflow. See MCP server for AI coding agents.

  • Jupyter/IPython magics — %%scope, %%scope_line and %%scope_recursive profile a cell (the last with nothing instrumented at all), while %scope_compare, %scope_df, %scope_load and %scope_export compare, analyse and export runs — including one from an MPI job — without leaving the notebook. See Jupyter/IPython magics.

Quick example#

from scope_profiler import ProfileManager

with ProfileManager.session():
    @ProfileManager.profile("compute")
    def compute():
        return sum(i * i for i in range(100_000))

    compute()

Documentation#

Getting started

User guide

Interactive Jupyter tutorials

Reference

Examples & workflows

Contents