Examples and workflows

Install for this page: pip install scope-profiler runs the core examples. pip install "scope-profiler[extras]" adds every broadly installable example dependency; LIKWID remains separate and needs a system LIKWID installation plus scope-profiler[likwid].

The repository includes small scripts for specific profiling tasks and a repeatable AI optimization workflow.

Profiling examples

• ex_cli_profiling.py — profile an unmodified script with the CLI.
• ex_line_profiling.py — collect line-by-line timings.
• ex_memory_profiling.py — capture allocations with Memray alongside region timings.
• ex_recursive_profiling.py — profile nested calls.
• ex_recursive_totals.py — check that a recursive region’s total never exceeds its caller’s time, and that its children are not marked recursive.
• ex_call_path_summary.py — show separate summary timings for a same-named region reached through different callers.
• ex_region_source.py — retain and inspect region source code.
• ex_html_report.py — profile a baseline and an optimized case into two files and compare them with scope-profiler report.
• ex_html_report_scaling.py — run a toy solver on 1, 2 and 4 MPI ranks and compare the runs, speedup and weak-scaling charts included, with scope-profiler report (--weak grows the problem with the ranks).
• ex_site.py — turn profiling files listed in a YAML manifest into the pages and chart data of an Astro catalogue website with scope-profiler site.
• ex_aggregation.py — record compact per-region aggregate statistics without storing an event timeline.
• ex_perf_events.py — collect Linux CPU-counter totals per profiled region.
• ex_mpi_wrappers.py — profile mpi4py point-to-point, collective, and wait calls with communication metadata.
• ex_mpi_numpy_wrappers.py — profile an unchanged mpi4py/NumPy program through scope-profiler run.
• ex_mpi_profiling_options.py — enable automatic MPI-call instrumentation from ProfilingOptions inside a normal session.
• ex_perf_event_plots.py — compare IPC and cache-miss pressure across regions.
• ex_threads_and_asyncio.py — profile concurrent threads, and split an asyncio task’s wall time into running and awaiting.
• ex_json_export.py — write the run as JSON instead of HDF5, and read it back into the same results.
• ex_prof_export.py — read a run with pstats/SnakeViz, in memory or as a .prof file.
• benchmark_overhead.py — measure instrumentation overhead.

Run an example with:

python examples/<script>.py

For large or high-frequency workloads, aggregation mode stores call counts, inclusive totals, minimums, maximums, and exclusive totals while keeping the profile small:

with ProfileManager.session(
    aggregation_mode=True,
    return_results=True,
) as run:
    with ProfileManager.region("solve"):
        solve()

run.results.print_summary(title="Aggregate profile")

See ex_aggregation.py for a complete runnable example. Individual events and timeline plots are not available in this mode.

Output formats

The extension of the output path picks the format, and HDF5 remains the default. A JSON profile holds exactly the same run — every call, in integer nanoseconds — and reads back into the same ProfilingResults:

scope-profiler run -o profile.json my_script.py          # or .json.gz, or .html
scope-profiler export json profiling_data.h5 -o exports  # convert an existing run

from scope_profiler import read_json, write_json

write_json(run.results, "profile.json.gz")
results = read_json("profile.json.gz")

See ex_json_export.py for a complete runnable example, and CLI reference for when to prefer which format.

AI optimization workflow

The agent workflow example demonstrates measure → edit → re-measure → correctness-check using the CLI or MCP tools. The runnable repository workload is configured in benchmarks/sensor.toml.

See AGENTS.md for the instructions used by Codex and other coding agents.