scope-profiler 0.3.2__tar.gz → 0.3.4__tar.gz

scope_profiler-0.3.4/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: scope-profiler
+Version: 0.3.4
+Summary: Profile code regions in python, optionally with LIKWID markers.
+Author: Max
+Project-URL: Source, https://github.com/max-models/scope-profiler
+Keywords: python
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: h5py
+Requires-Dist: numpy
+Requires-Dist: tabulate
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Provides-Extra: fortran
+Requires-Dist: meson; extra == "fortran"
+Requires-Dist: ninja; extra == "fortran"
+Provides-Extra: compression
+Requires-Dist: hdf5plugin; extra == "compression"
+Provides-Extra: likwid
+Requires-Dist: pylikwid; extra == "likwid"
+Provides-Extra: line-profiler
+Requires-Dist: line-profiler; extra == "line-profiler"
+Provides-Extra: nvtx
+Requires-Dist: nvtx; extra == "nvtx"
+Provides-Extra: mcp
+Requires-Dist: mcp<2.0.0,>=1.6.0; extra == "mcp"
+Provides-Extra: mpi
+Requires-Dist: mpi4py; extra == "mpi"
+Provides-Extra: pproc
+Requires-Dist: ipykernel; extra == "pproc"
+Requires-Dist: jupyterlab; extra == "pproc"
+Requires-Dist: matplotlib; extra == "pproc"
+Requires-Dist: maxplotlibx>=0.1.8; extra == "pproc"
+Requires-Dist: pandas; extra == "pproc"
+Requires-Dist: plotly; extra == "pproc"
+Requires-Dist: snakeviz; extra == "pproc"
+Requires-Dist: tabulate; extra == "pproc"
+Requires-Dist: textual>=0.86; extra == "pproc"
+Provides-Extra: graph
+Requires-Dist: pyvis>=0.3.2; extra == "graph"
+Provides-Extra: dev
+Requires-Dist: black[jupyter]; extra == "dev"
+Requires-Dist: isort>=9.0.0; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: scope-profiler[docs,fortran,line-profiler,mcp,mpi,nvtx,pproc,test,tui]; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: myst-parser; extra == "docs"
+Requires-Dist: nbconvert; extra == "docs"
+Requires-Dist: nbsphinx; extra == "docs"
+Requires-Dist: pre-commit; extra == "docs"
+Requires-Dist: pyproject-fmt; extra == "docs"
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx-book-theme; extra == "docs"
+Requires-Dist: scope-profiler[line-profiler,pproc,tui]; extra == "docs"
+Provides-Extra: test
+Requires-Dist: coverage; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Provides-Extra: tui
+Requires-Dist: tabulate; extra == "tui"
+Requires-Dist: textual>=0.86; extra == "tui"
+
+
+
+<!-- Generated README.md is rendered from this file by docs/render_markdown.py. -->
+
+# scope-profiler
+
+Profile Python code regions—and optionally C, Fortran, MPI, NVTX, and
+[LIKWID](https://github.com/RRZE-HPC/likwid)—with one consistent API and
+HDF5 output format.
+
+``` bash
+pip install scope-profiler
+```
+
+## Quick start
+
+``` python
+from scope_profiler import ProfileManager
+
+with ProfileManager.session():
+    @ProfileManager.profile("main")
+    def main():
+        with ProfileManager.profile_region("work"):
+            sum(range(100))  # replace with the code you want to measure
+
+    main()
+# writes profiling_data.h5 and prints a summary
+```
+
+You can also profile a script without changing its source:
+
+``` bash
+scope-profiler run my_script.py
+scope-profiler inspect profiling_data.h5
+scope-profiler plot default profiling_data.h5 -o figures
+scope-profiler report profiling_data.h5 -o report.html
+```
+
+## Example output
+
+The plotting tools include duration summaries and timelines for finding
+expensive regions:
+
+![Duration
+summary](https://raw.githubusercontent.com/max-models/scope-profiler/refs/heads/devel/figures/durations_plot.png)
+
+![Gantt
+chart](https://raw.githubusercontent.com/max-models/scope-profiler/refs/heads/devel/figures/gantt_plot.png)
+
+The overhead benchmark measures the cost of each instrumentation mode:
+
+``` bash
+python examples/benchmark_overhead.py
+```
+
+![Profiling overhead by region
+type](https://raw.githubusercontent.com/max-models/scope-profiler/refs/heads/devel/figures/benchmark_overhead.png)
+
+## Documentation
+
+- [Installation](https://max-models.github.io/scope-profiler/installation.html)
+- [Quick
+  start](https://max-models.github.io/scope-profiler/quickstart.html)
+- [Python API and
+  post-processing](https://max-models.github.io/scope-profiler/guide/hdf5_and_python_api.html)
+- [CLI reference](https://max-models.github.io/scope-profiler/cli.html)
+- [Configuration and profiling
+  regions](https://max-models.github.io/scope-profiler/guide/configuration.html)
+- [MPI](https://max-models.github.io/scope-profiler/guide/mpi.html),
+  [C](https://max-models.github.io/scope-profiler/guide/c.html), and
+  [Fortran](https://max-models.github.io/scope-profiler/guide/fortran.html)
+- [LIKWID](https://max-models.github.io/scope-profiler/guide/likwid.html),
+  [line
+  profiling](https://max-models.github.io/scope-profiler/guide/line_profiler.html),
+  and [MCP](https://max-models.github.io/scope-profiler/guide/mcp.html)
+- [Tutorial
+  notebooks](https://max-models.github.io/scope-profiler/tutorials.html)
+- [Examples](https://github.com/max-models/scope-profiler/tree/devel/examples)
+
+## Development
+
+``` bash
+pip install -e '.[dev]'
+pytest
+```
+
+See
+[AGENTS.md](https://github.com/max-models/scope-profiler/blob/devel/AGENTS.md)
+for the measured benchmark workflow used when optimizing this project.

scope_profiler-0.3.4/README.md

@@ -0,0 +1,89 @@
+
+
+<!-- Generated README.md is rendered from this file by docs/render_markdown.py. -->
+
+# scope-profiler
+
+Profile Python code regions—and optionally C, Fortran, MPI, NVTX, and
+[LIKWID](https://github.com/RRZE-HPC/likwid)—with one consistent API and
+HDF5 output format.
+
+``` bash
+pip install scope-profiler
+```
+
+## Quick start
+
+``` python
+from scope_profiler import ProfileManager
+
+with ProfileManager.session():
+    @ProfileManager.profile("main")
+    def main():
+        with ProfileManager.profile_region("work"):
+            sum(range(100))  # replace with the code you want to measure
+
+    main()
+# writes profiling_data.h5 and prints a summary
+```
+
+You can also profile a script without changing its source:
+
+``` bash
+scope-profiler run my_script.py
+scope-profiler inspect profiling_data.h5
+scope-profiler plot default profiling_data.h5 -o figures
+scope-profiler report profiling_data.h5 -o report.html
+```
+
+## Example output
+
+The plotting tools include duration summaries and timelines for finding
+expensive regions:
+
+![Duration
+summary](https://raw.githubusercontent.com/max-models/scope-profiler/refs/heads/devel/figures/durations_plot.png)
+
+![Gantt
+chart](https://raw.githubusercontent.com/max-models/scope-profiler/refs/heads/devel/figures/gantt_plot.png)
+
+The overhead benchmark measures the cost of each instrumentation mode:
+
+``` bash
+python examples/benchmark_overhead.py
+```
+
+![Profiling overhead by region
+type](https://raw.githubusercontent.com/max-models/scope-profiler/refs/heads/devel/figures/benchmark_overhead.png)
+
+## Documentation
+
+- [Installation](https://max-models.github.io/scope-profiler/installation.html)
+- [Quick
+  start](https://max-models.github.io/scope-profiler/quickstart.html)
+- [Python API and
+  post-processing](https://max-models.github.io/scope-profiler/guide/hdf5_and_python_api.html)
+- [CLI reference](https://max-models.github.io/scope-profiler/cli.html)
+- [Configuration and profiling
+  regions](https://max-models.github.io/scope-profiler/guide/configuration.html)
+- [MPI](https://max-models.github.io/scope-profiler/guide/mpi.html),
+  [C](https://max-models.github.io/scope-profiler/guide/c.html), and
+  [Fortran](https://max-models.github.io/scope-profiler/guide/fortran.html)
+- [LIKWID](https://max-models.github.io/scope-profiler/guide/likwid.html),
+  [line
+  profiling](https://max-models.github.io/scope-profiler/guide/line_profiler.html),
+  and [MCP](https://max-models.github.io/scope-profiler/guide/mcp.html)
+- [Tutorial
+  notebooks](https://max-models.github.io/scope-profiler/tutorials.html)
+- [Examples](https://github.com/max-models/scope-profiler/tree/devel/examples)
+
+## Development
+
+``` bash
+pip install -e '.[dev]'
+pytest
+```
+
+See
+[AGENTS.md](https://github.com/max-models/scope-profiler/blob/devel/AGENTS.md)
+for the measured benchmark workflow used when optimizing this project.

{scope_profiler-0.3.2 → scope_profiler-0.3.4}/pyproject.toml

@@ -5,7 +5,7 @@ requires = [ "setuptools", "wheel" ]
 
 [project]
 name = "scope-profiler"
-version = "0.3.2"
+version = "0.3.4"
 description = "Profile code regions in python, optionally with LIKWID markers."
 readme = "README.md"
 keywords = [ "python" ]
@@ -24,6 +24,8 @@ classifiers = [
 dependencies = [
   "h5py",
   "numpy",
+  "tabulate",
+  "tomli>=2.0; python_version < '3.11'",
 ]
 
 optional-dependencies.fortran = [
@@ -33,6 +35,10 @@ optional-dependencies.fortran = [
   "ninja",
 ]
 
+optional-dependencies.compression = [
+  "hdf5plugin",
+]
+
 optional-dependencies.likwid = [
   "pylikwid",
 ]
@@ -57,16 +63,21 @@ optional-dependencies.pproc = [
   "ipykernel",
   "jupyterlab",
   "matplotlib",
-  "maxplotlibx >= 0.1.6",
+  "maxplotlibx >= 0.1.8",
   "pandas",
+  "plotly",
   "snakeviz",
   "tabulate",
   "textual>=0.86",
 ]
 
+optional-dependencies.graph = [
+  "pyvis >= 0.3.2",
+]
+
 optional-dependencies.dev = [
   "black[jupyter]",
-  "isort",
+  "isort >= 9.0.0",
   "ruff",
   "scope-profiler[docs,fortran,line-profiler,mcp,mpi,nvtx,pproc,test,tui]",
 ]

{scope_profiler-0.3.2 → scope_profiler-0.3.4}/src/scope_profiler/__init__.py

@@ -3,6 +3,9 @@
 from importlib.metadata import PackageNotFoundError, version
 
 from scope_profiler.call_stack import (
+    CallArrays,
+    NestingError,
+    build_call_arrays,
     build_call_stack,
     call_stack_children,
     call_stack_roots,
@@ -30,19 +33,26 @@ _LAZY_ATTRS = {
     "plot_flame": "plotting_scripts",
     "plot_gantt": "plotting_scripts",
     "plot_speedup": "plotting_scripts",
+    "plot_weak_scaling": "plotting_scripts",
+    "plot_rank_heatmap": "plotting_scripts",
+    "plot_scaling_efficiency": "plotting_scripts",
     "write_region_statistics_json": "plotting_scripts",
     "export_prof": "prof_export",
     "export_speedscope": "speedscope_export",
     "collect_file_metadata": "inspection",
     "inspect_file": "inspection",
+    "create_html_report": "html_report",
 }
 
 __all__ = [
+    "CallArrays",
     "LikwidRegionResult",
     "MPIRegion",
+    "NestingError",
     "ProfileManager",
     "ProfilingResults",
     "Region",
+    "build_call_arrays",
     "build_call_stack",
     "call_stack_children",
     "call_stack_roots",

{scope_profiler-0.3.2 → scope_profiler-0.3.4}/src/scope_profiler/__main__.py

@@ -18,6 +18,8 @@ Six subcommands:
   per-region statistics table (including LIKWID hardware counters, when the
   run recorded any) for merged HDF5 profiling output, without producing any
   plots. See ``scope_profiler.inspection``.
+- ``scope-profiler report file.h5 -o report.html`` -- writes a standalone HTML
+  summary with metadata and per-region timing statistics.
 - ``scope-profiler tui file.h5`` -- opens an interactive Textual browser for
   metadata, region statistics, per-rank calls, LIKWID counters and the raw
   HDF5 tree.
@@ -29,6 +31,10 @@ Six subcommands:
   ``scope_profiler.diff``.
 - ``scope-profiler check a.h5 b.h5`` -- applies a regression budget and
   returns a CI-friendly exit code.
+- ``scope-profiler benchmark run config.toml`` -- runs a repeatable benchmark
+  with a correctness gate and writes a JSON manifest.
+- ``scope-profiler benchmark compare baseline.json candidate.json`` -- makes a
+  median-based keep/reject decision for an AI agent or CI.
 - ``scope-profiler import-native traces/ -o out.h5`` -- converts the trace
   files written by the Fortran region API
   (``scope_profiler/fortran/scope_profiler.f90``)
@@ -52,9 +58,14 @@ def _parse_run_args(argv):
     parser.add_argument(
         "-o",
         "--outfile",
-        default="profiling_data.h5",
+        default=None,
         help="Path to the merged HDF5 output file (default: profiling_data.h5)",
     )
+    parser.add_argument(
+        "--config",
+        metavar="FILE",
+        help="TOML file containing profiling settings ([profiling] table)",
+    )
     parser.add_argument(
         "-q",
         "--quiet",
@@ -70,13 +81,14 @@ def _parse_run_args(argv):
     parser.add_argument(
         "--line-profile",
         action="store_true",
+        default=None,
         help="Also collect line-by-line timings via line_profiler "
         "(requires scope-profiler[line-profiler])",
     )
     parser.add_argument(
         "--buffer-limit",
         type=int,
-        default=1024,
+        default=None,
         help="Initial buffer capacity per region; grows as needed (default: 1024)",
     )
     parser.add_argument("script", help="Script to run and profile")
@@ -100,11 +112,14 @@ def _run(argv):
         raise SystemExit(1)
 
     ProfileManager.setup(
-        recursive_profile=True,
-        use_likwid=False,
+        # ``run`` historically enables recursive profiling.  A TOML file may
+        # override it, while the no-config path keeps that default.
+        recursive_profile=True if args.config is None else None,
+        use_likwid=None,
         use_line_profiler=args.line_profile,
         buffer_limit=args.buffer_limit,
         file_path=args.outfile,
+        config_path=args.config,
     )
 
     try:
@@ -138,6 +153,62 @@ def _inspect(argv):
     return inspect_main(argv)
 
 
+def _report(argv):
+    """Handle ``scope-profiler report``: write a standalone HTML summary."""
+    from scope_profiler.html_report import create_html_report
+    from scope_profiler.post_processing import expand_file_patterns, parse_ranks
+    from scope_profiler.summary import REGION_TABLE_COLUMNS, SORT_KEYS
+
+    parser = argparse.ArgumentParser(
+        prog="scope-profiler report",
+        description="Write a standalone HTML report from profiling HDF5 files.",
+    )
+    parser.add_argument(
+        "files", nargs="+", help="Profiling HDF5 files or glob patterns"
+    )
+    parser.add_argument(
+        "-o", "--output", required=True, metavar="PATH", help="HTML file to write"
+    )
+    parser.add_argument(
+        "--include", nargs="+", help="Only include matching region names"
+    )
+    parser.add_argument("--exclude", nargs="+", help="Exclude matching region names")
+    parser.add_argument("--ranks", nargs="+", help="Ranks to include, e.g. 0 2 or 0-3")
+    parser.add_argument(
+        "--sort",
+        choices=SORT_KEYS,
+        default="total",
+        help="Region ordering (default: total)",
+    )
+    parser.add_argument(
+        "--columns",
+        nargs="+",
+        choices=REGION_TABLE_COLUMNS,
+        help="Region table columns",
+    )
+    parser.add_argument(
+        "--no-charts",
+        action="store_true",
+        help="Omit embedded interactive charts",
+    )
+    args = parser.parse_args(argv)
+    ranks = None
+    if args.ranks:
+        ranks = sorted({rank for spec in args.ranks for rank in parse_ranks(spec)})
+    output = create_html_report(
+        expand_file_patterns(args.files, parser),
+        args.output,
+        include=args.include,
+        exclude=args.exclude,
+        ranks=ranks,
+        sort=args.sort,
+        columns=args.columns,
+        include_charts=not args.no_charts,
+    )
+    print(f"Report written to: {output}")
+    return 0
+
+
 def _tui(argv):
     """Handle ``scope-profiler tui``: open the interactive HDF5 browser."""
     from scope_profiler.tui import main as tui_main
@@ -166,6 +237,48 @@ def _check(argv):
     return check_main(argv)
 
 
+def _benchmark(argv):
+    """Run or compare declarative, repeated benchmark manifests."""
+    from scope_profiler.benchmark import (
+        BenchmarkError,
+        compare_benchmarks,
+        load_config,
+        run_benchmark,
+    )
+
+    parser = argparse.ArgumentParser(
+        prog="scope-profiler benchmark",
+        description="Run or compare repeatable AI/CI benchmark workflows.",
+    )
+    subparsers = parser.add_subparsers(dest="action", required=True)
+    run_parser = subparsers.add_parser("run", help="run a benchmark config")
+    run_parser.add_argument("config", help="benchmark TOML configuration")
+    run_parser.add_argument(
+        "--label", default="candidate", help="baseline or candidate label"
+    )
+    run_parser.add_argument("--json", action="store_true", help="print only JSON")
+    compare_parser = subparsers.add_parser(
+        "compare", help="compare two benchmark manifests"
+    )
+    compare_parser.add_argument("baseline")
+    compare_parser.add_argument("candidate")
+    compare_parser.add_argument("--json", action="store_true", help="print only JSON")
+    args = parser.parse_args(argv)
+    try:
+        if args.action == "run":
+            result = run_benchmark(load_config(args.config), label=args.label)
+            exit_code = 0 if result["correctness"]["passed"] else 1
+        else:
+            result = compare_benchmarks(args.baseline, args.candidate)
+            exit_code = 0 if result["decision"] == "keep" else 1
+    except BenchmarkError as exc:
+        parser.error(str(exc))
+    print(__import__("json").dumps(result, indent=None if args.json else 2))
+    if exit_code:
+        raise SystemExit(exit_code)
+    return 0
+
+
 def _import_fortran(argv):
     """Handle ``scope-profiler import-native``: Fortran traces -> HDF5."""
     from scope_profiler.native_trace import TRACE_SUFFIX, convert_traces
@@ -238,10 +351,12 @@ _COMMANDS = {
     "plot": _plot,
     "export": _export,
     "inspect": _inspect,
+    "report": _report,
     "tui": _tui,
     "line-profile": _line_profile,
     "diff": _diff,
     "check": _check,
+    "benchmark": _benchmark,
     "import-native": _import_fortran,
 }
 
@@ -283,6 +398,11 @@ def main(argv=None):
         help="Print metadata and region statistics of HDF5 profiling data "
         "(see `scope-profiler inspect --help`)",
     )
+    subparsers.add_parser(
+        "report",
+        add_help=False,
+        help="Write a standalone HTML report (see `scope-profiler report --help`)",
+    )
     subparsers.add_parser(
         "tui",
         add_help=False,
@@ -306,6 +426,11 @@ def main(argv=None):
         add_help=False,
         help="Fail on profiling regressions (see `scope-profiler check --help`)",
     )
+    subparsers.add_parser(
+        "benchmark",
+        add_help=False,
+        help="Run or compare repeatable benchmarks (see `scope-profiler benchmark --help`)",
+    )
     subparsers.add_parser(
         "import-native",
         add_help=False,
@@ -331,4 +456,4 @@ def main(argv=None):
 
 
 if __name__ == "__main__":
-    main()
+    raise SystemExit(main())