scope-profiler

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 startedInstallation, the quickstart and the profiling modes.

User guideConfiguration, regions, output, plotting, MPI, LIKWID, C and Fortran.

Interactive Jupyter tutorialsSeven notebooks, from the first region to custom plots.

ReferenceThe Python API and the command line.

Examples & workflowsReady-to-run scripts and agent workflows.