scope-profiler 0.1__tar.gz

scope_profiler-0.1/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: scope-profiler
+Version: 0.1
+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.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: h5py
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Provides-Extra: dev
+Requires-Dist: black[jupyter]; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: scope-profiler[docs,test]; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: ipykernel; extra == "docs"
+Requires-Dist: myst-parser; extra == "docs"
+Requires-Dist: nbconvert; extra == "docs"
+Requires-Dist: nbsphinx; extra == "docs"
+Requires-Dist: jupyterlab; 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"
+Provides-Extra: test
+Requires-Dist: coverage; extra == "test"
+Requires-Dist: pytest; extra == "test"
+
+# scope-profiler - Python Profiling System with Optional LIKWID Integration
+
+This module provides a unified profiling system for Python applications, with optional integration of [LIKWID](https://github.com/RRZE-HPC/likwid) markers using the [pylikwid](https://github.com/RRZE-HPC/pylikwid) marker API for hardware performance counters. It allows you to:
+- Configure profiling globally via a singleton ProfilingConfig.
+- Collect timing data via context-managed profiling regions.
+- Use a clean decorator syntax to profile functions.
+- Optionally record time traces in HDF5 files.
+- Automatically initialize and close LIKWID markers only when needed.
+- Print aggregated summaries of all profiling regions.
+
+Documentation: https://max-models.github.io/scope-profiler/
+
+## Install
+
+```
+pip install scope-profiler
+```
+
+## Usage
+
+```python
+from scope_profiler.profiling import (
+    ProfilingConfig,
+    ProfileManager,
+)
+
+config = ProfilingConfig(
+    use_likwid=False,
+    time_trace=True,
+    flush_to_disk=True,
+)
+
+@ProfileManager.profile("main")
+def main():
+    x = 0
+    for i in range(10):
+        with ProfileManager.profile_region(region_name="iteration"):
+            x += 1
+
+main()    
+
+ProfileManager.print_summary()
+
+ProfileManager.finalize()
+```
+
+Execution:
+
+```bash
+❯ python test.py
+Profiling Summary:
+========================================
+Region: main
+  Number of Calls: 1
+  Total Duration: 0.000315 seconds
+  Average Duration: 0.000315 seconds
+  Min Duration: 0.000315 seconds
+  Max Duration: 0.000315 seconds
+  Std Deviation: 0.000000 seconds
+----------------------------------------
+Region: iteration
+  Number of Calls: 10
+  Total Duration: 0.000007 seconds
+  Average Duration: 0.000001 seconds
+  Min Duration: 0.000000 seconds
+  Max Duration: 0.000003 seconds
+  Std Deviation: 0.000001 seconds
+----------------------------------------
+```

scope_profiler-0.1/README.md

@@ -0,0 +1,69 @@
+# scope-profiler - Python Profiling System with Optional LIKWID Integration
+
+This module provides a unified profiling system for Python applications, with optional integration of [LIKWID](https://github.com/RRZE-HPC/likwid) markers using the [pylikwid](https://github.com/RRZE-HPC/pylikwid) marker API for hardware performance counters. It allows you to:
+- Configure profiling globally via a singleton ProfilingConfig.
+- Collect timing data via context-managed profiling regions.
+- Use a clean decorator syntax to profile functions.
+- Optionally record time traces in HDF5 files.
+- Automatically initialize and close LIKWID markers only when needed.
+- Print aggregated summaries of all profiling regions.
+
+Documentation: https://max-models.github.io/scope-profiler/
+
+## Install
+
+```
+pip install scope-profiler
+```
+
+## Usage
+
+```python
+from scope_profiler.profiling import (
+    ProfilingConfig,
+    ProfileManager,
+)
+
+config = ProfilingConfig(
+    use_likwid=False,
+    time_trace=True,
+    flush_to_disk=True,
+)
+
+@ProfileManager.profile("main")
+def main():
+    x = 0
+    for i in range(10):
+        with ProfileManager.profile_region(region_name="iteration"):
+            x += 1
+
+main()    
+
+ProfileManager.print_summary()
+
+ProfileManager.finalize()
+```
+
+Execution:
+
+```bash
+❯ python test.py
+Profiling Summary:
+========================================
+Region: main
+  Number of Calls: 1
+  Total Duration: 0.000315 seconds
+  Average Duration: 0.000315 seconds
+  Min Duration: 0.000315 seconds
+  Max Duration: 0.000315 seconds
+  Std Deviation: 0.000000 seconds
+----------------------------------------
+Region: iteration
+  Number of Calls: 10
+  Total Duration: 0.000007 seconds
+  Average Duration: 0.000001 seconds
+  Min Duration: 0.000000 seconds
+  Max Duration: 0.000003 seconds
+  Std Deviation: 0.000001 seconds
+----------------------------------------
+```

scope_profiler-0.1/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+build-backend = "setuptools.build_meta"
+
+requires = [ "setuptools", "wheel" ]
+
+[project]
+name = "scope-profiler"
+version = "0.1"
+description = "Profile code regions in python, optionally with LIKWID markers."
+readme = "README.md"
+keywords = [ "python" ]
+license = { file = "LICENSE.txt" }
+authors = [ { name = "Max" } ]
+requires-python = ">=3.8"
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+  "h5py",
+  "numpy",
+  "matplotlib",
+]
+
+optional-dependencies.dev = [
+  "black[jupyter]",
+  "isort",
+  "ruff",
+  "scope-profiler[test,docs]",
+]
+# https://medium.com/@pratikdomadiya123/build-project-documentation-quickly-with-the-sphinx-python-2a9732b66594
+optional-dependencies.docs = [
+  "ipykernel",
+  "myst-parser",
+  "nbconvert",
+  "nbsphinx",
+  "jupyterlab",
+  "pre-commit",
+  "pyproject-fmt",
+  "sphinx",
+  "sphinx-book-theme",
+]
+optional-dependencies.test = [
+  "coverage",
+  "pytest"
+]
+urls."Source" = "https://github.com/max-models/scope_profiler"
+
+[project.scripts]
+scope-profiler-pproc = "scope_profiler.post_processing:main"
+
+[tool.setuptools.packages.find]
+where = [ "src" ]
+
+[tool.isort]
+profile = "black"

scope_profiler-0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

scope_profiler-0.1/src/scope_profiler/h5reader.py

@@ -0,0 +1,220 @@
+from pathlib import Path
+from typing import Any, Dict, List
+
+import h5py
+import matplotlib.pyplot as plt
+import numpy as np
+
+
+class Region:
+    def __init__(self, start_times: np.ndarray, end_times: np.ndarray) -> None:
+        self._start_times = start_times
+        self._end_times = end_times
+        self._durations = end_times - start_times
+
+    def get_summary(self) -> Dict[str, Any]:
+        """Return a summary of the region’s statistics as a dictionary."""
+        return {
+            "num_calls": self.num_calls,
+            "total_duration": self.total_duration,
+            "average_duration": self.average_duration,
+            "min_duration": self.min_duration,
+            "max_duration": self.max_duration,
+            "std_duration": self.std_duration,
+        }
+
+    def __repr__(self) -> str:
+        """Print summaries for all regions in the file."""
+        # print(f"\nProfiling data summary for: {self.file_path}")
+        _out = "-" * 60 + "\n"
+        stats = self.get_summary()
+        for key, value in stats.items():
+            _out += f"  {key:>18}: {value}\n"
+        _out += "-" * 60 + "\n\n"
+        return _out
+
+    @property
+    def start_times(self) -> np.ndarray:
+        return self._start_times
+
+    @property
+    def end_times(self) -> np.ndarray:
+        return self._end_times
+
+    @property
+    def durations(self) -> np.ndarray:
+        return self._durations
+
+    @property
+    def num_calls(self) -> int:
+        """Number of recorded calls."""
+        return len(self._durations)
+
+    @property
+    def total_duration(self) -> float:
+        """Total time spent in this region (sum of all durations)."""
+        return float(np.sum(self._durations)) if self.num_calls else 0.0
+
+    @property
+    def average_duration(self) -> float:
+        """Average duration per call."""
+        return float(np.mean(self._durations)) if self.num_calls else 0.0
+
+    @property
+    def min_duration(self) -> float:
+        """Minimum duration among all calls."""
+        return float(np.min(self._durations)) if self.num_calls else 0.0
+
+    @property
+    def max_duration(self) -> float:
+        """Maximum duration among all calls."""
+        return float(np.max(self._durations)) if self.num_calls else 0.0
+
+    @property
+    def std_duration(self) -> float:
+        """Standard deviation of durations."""
+        return float(np.std(self._durations)) if self.num_calls else 0.0
+
+
+class ProfilingH5Reader:
+    """
+    Reads profiling data stored by ProfileRegion in an HDF5 file.
+    """
+
+    def __init__(self, file_path: str | Path):
+        self._file_path = Path(file_path)
+        if not self.file_path.exists():
+            raise FileNotFoundError(f"HDF5 file not found: {self.file_path}")
+
+        # Verify it's an HDF5 file
+        try:
+            with h5py.File(self.file_path, "r") as f:
+                if "regions" not in f:
+                    raise ValueError("Invalid profiling file: missing 'regions' group.")
+        except OSError as e:
+            raise ValueError(f"Cannot open {self.file_path} as an HDF5 file") from e
+
+        # Read the file
+        self._region_dict = {}
+        with h5py.File(self.file_path, "r") as f:
+            # region_names = list(f["regions"].keys())
+
+            for region_name, region in f["regions"].items():
+                # grp = f[f"regions/{region_name}"]
+                self._region_dict[region_name] = Region(
+                    region["start_times"][()],
+                    region["end_times"][()],
+                )
+
+    def get_region(self, region_name: str) -> Region:
+        return self._region_dict[region_name]
+
+    def plot_gantt(
+        self,
+        regions: List[str] | str | None = None,
+        filepath: str | None = None,
+        show: bool = False,
+    ) -> None:
+        """
+        Plot a Gantt chart of all (or selected) regions.
+
+        Parameters
+        ----------
+        regions : list[str] | None
+            List of region names to plot. If None, plot all.
+        """
+        if regions is None:
+            regions = list(self._region_dict.keys())
+        elif isinstance(regions, str):
+            regions = [regions]
+
+        fig, ax = plt.subplots(figsize=(10, 0.7 * len(regions)))
+        colors = plt.cm.tab20(np.linspace(0, 1, len(regions)))
+
+        for i, region_name in enumerate(regions):
+            region = self._region_dict[region_name]
+            for start, end in zip(region.start_times, region.end_times):
+                ax.barh(
+                    y=i,
+                    width=end - start,
+                    left=start,
+                    height=0.4,
+                    color=colors[i],
+                    edgecolor="black",
+                    alpha=0.7,
+                )
+
+        ax.set_xlabel("Time (seconds)")
+        ax.set_yticks(range(len(regions)))
+        ax.set_yticklabels(regions)
+        ax.set_title("Profiling Gantt Chart")
+        ax.grid(True, axis="x", linestyle="--", alpha=0.5)
+        fig.tight_layout()
+        if filepath:
+            plt.savefig(filepath, dpi=300)
+        if show:
+            plt.show()
+
+    def plot_durations(
+        self,
+        regions: List[str] | str | None = None,
+        filepath: str | None = None,
+        show: bool = False,
+        bins: int = 30,
+    ) -> None:
+        """
+        Plot duration histograms for each region.
+
+        Parameters
+        ----------
+        regions : list[str] | None
+            List of region names to plot. If None, plot all.
+        bins : int
+            Number of histogram bins.
+        """
+        if regions is None:
+            regions = list(self._region_dict.keys())
+        elif isinstance(regions, str):
+            regions = [regions]
+
+        n = len(regions)
+        fig, axes = plt.subplots(nrows=n, ncols=1, figsize=(8, 3 * n))
+        if n == 1:
+            axes = [axes]
+
+        for ax, region_name in zip(axes, regions):
+            region = self._region_dict[region_name]
+            durations = region.durations
+            if len(durations) == 0:
+                ax.text(0.5, 0.5, "No data", ha="center", va="center")
+                continue
+
+            ax.hist(
+                durations, bins=bins, color="steelblue", alpha=0.7, edgecolor="black"
+            )
+            ax.set_title(f"Region: {region_name}")
+            ax.set_xlabel("Duration (s)")
+            ax.set_ylabel("Frequency")
+            ax.grid(True, alpha=0.4)
+
+        fig.suptitle("Region Duration Distributions", fontsize=14)
+        fig.tight_layout()
+        if filepath:
+            plt.savefig(filepath, dpi=300)
+        if show:
+            plt.show()
+
+    def __repr__(self) -> str:
+        _out = ""
+        for region_name, region in self._region_dict.items():
+            _out += f"Region: {region_name}\n"
+            _out += str(region)
+        return _out
+
+    @property
+    def file_path(self) -> Path:
+        return self._file_path
+
+    @property
+    def regions(self) -> List[Region]:
+        return self._regions

scope_profiler-0.1/src/scope_profiler/post_processing.py

@@ -0,0 +1,55 @@
+import argparse
+import os
+
+from scope_profiler.h5reader import ProfilingH5Reader
+
+
+def main():
+    """Main function for reading and summarizing profiling HDF5 data."""
+    parser = argparse.ArgumentParser(
+        description="Read and summarize profiling HDF5 data."
+    )
+    parser.add_argument("file", type=str, help="Path to the profiling_data.h5 file")
+    parser.add_argument("--region", type=str, help="Region name to inspect (optional)")
+    parser.add_argument(
+        "--show",
+        action="store_true",
+        help="Show plots interactively (default: do not show plots)",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        type=str,
+        help="Directory or file prefix to save plots instead of displaying them",
+    )
+    args = parser.parse_args()
+
+    reader = ProfilingH5Reader(args.file)
+
+    # Handle optional region selection
+    if args.region:
+        regions = [args.region]
+        print(f"\nRegion: {args.region}")
+        print(reader.get_region(args.region))
+    else:
+        regions = None
+        print(reader)
+
+    # Prepare output filepaths if requested
+    gantt_path = durations_path = None
+    if args.output:
+        os.makedirs(args.output, exist_ok=True)
+        gantt_path = os.path.join(args.output, "gantt_plot.png")
+        durations_path = os.path.join(args.output, "durations_plot.png")
+
+    # Call the plotting functions with the appropriate arguments
+    reader.plot_gantt(regions, filepath=gantt_path, show=args.show)
+    reader.plot_durations(regions, filepath=durations_path, show=args.show)
+
+    # If saving only (no show), print confirmation
+    if args.output and not args.show:
+        print(f"Plots saved to:\n  {gantt_path}\n  {durations_path}")
+
+
+if __name__ == "__main__":
+    main()

scope_profiler-0.1/src/scope_profiler/profiling.py

@@ -0,0 +1,422 @@
+"""
+profiling.py
+
+This module provides a centralized profiling configuration and management system
+using LIKWID markers. It includes:
+- A singleton class for managing profiling configuration.
+- A context manager for profiling specific code regions.
+- Initialization and cleanup functions for LIKWID markers.
+- Convenience functions for setting and getting the profiling configuration.
+
+LIKWID is imported only when profiling is enabled to avoid unnecessary overhead.
+"""
+
+import functools
+import inspect
+import time
+
+# Import the profiling configuration class and context manager
+from functools import lru_cache
+from typing import Callable, Dict
+
+import h5py
+import numpy as np
+
+
+@lru_cache(maxsize=None)  # Cache the import result to avoid repeated imports
+def _import_pylikwid():
+    import pylikwid
+
+    return pylikwid
+
+
+class ProfilingConfig:
+    """Singleton class for managing global profiling configuration."""
+
+    _instance = None
+    _initialized = False
+
+    def __new__(cls, *args, **kwargs):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            # Default values
+            cls._instance.profiling_activated = True
+            cls._instance.use_likwid = False
+            cls._instance.time_trace = False
+            cls._instance.flush_to_disk = False
+        return cls._instance
+
+    def __init__(
+        self,
+        profiling_activated: bool = True,
+        use_likwid: bool = False,
+        time_trace: bool = True,
+        flush_to_disk: bool = False,
+    ):
+
+        if self._initialized:
+            return
+
+        # Only update if value provided
+        self.profiling_activated = profiling_activated
+        self.use_likwid = use_likwid
+        self.time_trace = time_trace
+        self.flush_to_disk = flush_to_disk
+
+        self._pylikwid = None
+        if self.use_likwid:
+            try:
+                import pylikwid
+
+                self._pylikwid = pylikwid
+            except ImportError as e:
+                raise ImportError(
+                    "LIKWID profiling requested but pylikwid module not installed"
+                ) from e
+        self._initialized = True
+
+    @classmethod
+    def reset(cls):
+        """Reset the singleton so it can be reinitialized."""
+        cls._instance = None
+        cls._initialized = False
+
+    def pylikwid_markerinit(self):
+        """Initialize LIKWID profiling markers."""
+        if self.use_likwid and self._pylikwid:
+            self._pylikwid.markerinit()
+
+    def pylikwid_markerclose(self):
+        """Close LIKWID profiling markers."""
+        if self.use_likwid and self._pylikwid:
+            self._pylikwid.markerclose()
+
+    @property
+    def profiling_activated(self) -> bool:
+        return self._profiling_activated
+
+    @profiling_activated.setter
+    def profiling_activated(self, value: bool) -> None:
+        assert isinstance(value, bool)
+        self._profiling_activated = value
+
+    @property
+    def use_likwid(self) -> bool:
+        return self._likwid
+
+    @use_likwid.setter
+    def use_likwid(self, value: bool) -> None:
+        assert isinstance(value, bool)
+        self._likwid = value
+
+    @property
+    def time_trace(self) -> bool:
+        return self._time_trace
+
+    @property
+    def flush_to_disk(self) -> bool:
+        return self._flush_to_disk
+
+    @flush_to_disk.setter
+    def flush_to_disk(self, value) -> None:
+        if not isinstance(value, bool):
+            raise TypeError("flush_to_disk must be a bool")
+        self._flush_to_disk = value
+
+    @time_trace.setter
+    def time_trace(self, value: bool) -> None:
+        assert isinstance(value, bool)
+        self._time_trace = value
+
+
+class ProfileRegion:
+    """Context manager for profiling specific code regions using LIKWID markers."""
+
+    def __init__(
+        self,
+        region_name: str,
+        time_trace: bool = False,
+        buffer_limit: int = 100000,
+        file_path: str | None = None,
+        flush_to_disk: bool = False,
+        profiling_activated: bool = True,
+    ):
+        if hasattr(self, "_initialized") and self._initialized:
+            return
+        self._config = ProfilingConfig()
+        self._region_name = region_name
+        self._time_trace = time_trace
+        self._buffer_limit = buffer_limit
+        self._file_path = file_path or "profiling_data.h5"
+        self._flush_to_disk = flush_to_disk
+        self._profiling_activated = profiling_activated
+
+        # Timer data
+        self._ncalls = 0
+        self._start_times = []
+        self._end_times = []
+        self._duration = 0.0
+        self._started = False
+
+        # Create file and datasets if not existing
+        if self.flush_to_disk and self._time_trace:
+            with h5py.File(self._file_path, "a") as f:
+                grp = f.require_group(f"regions/{self._region_name}")
+                for name in ["start_times", "end_times", "durations"]:
+                    if name not in grp:
+                        grp.create_dataset(
+                            name,
+                            shape=(0,),
+                            maxshape=(None,),
+                            dtype="f8",
+                            chunks=True,
+                            compression="gzip",
+                        )
+
+    def __enter__(self):
+        if not self.profiling_activated:
+            return self
+        if self.config.use_likwid:
+            self._pylikwid().markerstartregion(self.region_name)
+
+        if self._time_trace:
+
+            self._start_time = time.perf_counter()
+            self._start_times.append(self._start_time)
+            self._started = True
+
+        self._ncalls += 1
+
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback) -> None:
+        if not self.profiling_activated:
+            return
+        if self.config.use_likwid:
+            self._pylikwid().markerstopregion(self.region_name)
+        if self._time_trace and self.started:
+            end_time = time.perf_counter()
+            self._end_times.append(end_time)
+            self._started = False
+
+            if self.flush_to_disk and len(self._start_times) >= self._buffer_limit:
+                self.flush()
+
+    def flush(self) -> None:
+        """Append buffered profiling data to the HDF5 file and clear memory."""
+        if not self._start_times:
+            return
+
+        starts = self.start_times  # np.array(self._start_times, dtype=np.float64)
+        ends = self.end_times  # np.array(self._end_times, dtype=np.float64)
+        durations = self.durations
+
+        with h5py.File(self._file_path, "a") as f:
+            grp = f.require_group(f"regions/{self._region_name}")
+            for name, data in [
+                ("start_times", starts),
+                ("end_times", ends),
+                ("durations", durations),
+            ]:
+                ds = grp[name]
+                old_size = ds.shape[0]
+                new_size = old_size + len(data)
+                ds.resize((new_size,))
+                ds[old_size:new_size] = data
+
+        self._start_times.clear()
+        self._end_times.clear()
+
+    def _pylikwid(self):
+        return _import_pylikwid()
+
+    @property
+    def profiling_activated(self) -> bool:
+        return self._profiling_activated
+
+    @property
+    def config(self) -> ProfilingConfig:
+        return self._config
+
+    @property
+    def durations(self) -> np.ndarray:
+        return self.end_times - self.start_times
+
+    @property
+    def end_times(self) -> np.ndarray:
+        return np.array(self._end_times)
+
+    @property
+    def flush_to_disk(self) -> bool:
+        return self._flush_to_disk
+
+    @property
+    def num_calls(self) -> int:
+        return self._ncalls
+
+    @property
+    def region_name(self) -> str:
+        return self._region_name
+
+    @property
+    def start_times(self) -> np.ndarray:
+        return np.array(self._start_times)
+
+    @property
+    def started(self) -> bool:
+        return self._started
+
+
+class ProfileManager:
+    """
+    Singleton class to manage and track all ProfileRegion instances.
+    """
+
+    _regions = {}
+
+    @classmethod
+    def reset(cls) -> None:
+        cls._regions = {}
+
+    @classmethod
+    def profile_region(cls, region_name) -> ProfileRegion:
+        """
+        Get an existing ProfileRegion by name, or create a new one if it doesn't exist.
+
+        Parameters
+        ----------
+        region_name: str
+            The name of the profiling region.
+
+        Returns
+        -------
+        ProfileRegion: The ProfileRegion instance.
+        """
+        if region_name in cls._regions:
+            # print(f"Using existing region '{region_name}'...")
+            return cls._regions[region_name]
+        else:
+            # print(f"Creating new region '{region_name}'...")
+            # Create and register a new ProfileRegion
+            cls._regions[region_name] = ProfileRegion(
+                region_name,
+                time_trace=ProfilingConfig().time_trace,
+                flush_to_disk=ProfilingConfig().flush_to_disk,
+                profiling_activated=ProfilingConfig().profiling_activated,
+            )
+            return cls._regions[region_name]
+
+    @classmethod
+    def profile(cls, region_name: str | None = None) -> Callable:
+        """
+        Decorator factory for profiling a function.
+
+        Usage:
+          @ProfileManager.profile               # region name defaults to function.__name__
+          def foo(...): ...
+
+          @ProfileManager.profile("myregion")
+          def bar(...): ...
+        """
+
+        def decorator(func: Callable) -> Callable:
+            # Default to function.__name__ if region_name is None
+            name = region_name or func.__name__
+            region = cls.profile_region(name)
+
+            if inspect.iscoroutinefunction(func):
+                # async function wrapper
+                @functools.wraps(func)
+                async def async_wrapper(*args, **kwargs):
+                    with region:
+                        return await func(*args, **kwargs)
+
+                return async_wrapper
+            else:
+
+                @functools.wraps(func)
+                def sync_wrapper(*args, **kwargs):
+                    with region:
+                        return func(*args, **kwargs)
+
+                return sync_wrapper
+
+        # If decorator used without parentheses: @ProfileManager.profile
+        # Python will pass the function directly to the decorator factory call,
+        # but because this is a factory we should allow that too:
+        if callable(region_name):
+            # invoked as @ProfileManager.profile with no args
+            func = region_name
+            region_name = None
+            return decorator(func)
+
+        return decorator
+
+    @classmethod
+    def finalize(cls) -> None:
+        if ProfilingConfig().flush_to_disk:
+            for name, region in cls.get_all_regions().items():
+                region.flush()
+
+    @classmethod
+    def get_region(cls, region_name) -> ProfileRegion:
+        """
+        Get a registered ProfileRegion by name.
+
+        Parameters
+        ----------
+        region_name: str
+            The name of the profiling region.
+
+        Returns
+        -------
+        ProfileRegion or None: The registered ProfileRegion instance or None if not found.
+        """
+        return cls._regions.get(region_name)
+
+    @classmethod
+    def get_all_regions(cls) -> Dict[str, "ProfileRegion"]:
+        """
+        Get all registered ProfileRegion instances.
+
+        Returns
+        -------
+        dict: Dictionary of all registered ProfileRegion instances.
+        """
+        return cls._regions
+
+    @classmethod
+    def print_summary(cls) -> None:
+        """
+        Print a summary of the profiling data for all regions.
+        """
+
+        _config = ProfilingConfig()
+        if not _config.time_trace:
+            print(
+                "time_trace is not set to True --> Time traces are not measured --> Skip printing summary...",
+            )
+            return
+
+        print("Profiling Summary:")
+        print("=" * 40)
+        for name, region in cls._regions.items():
+            if region.num_calls > 0:
+                total_duration = sum(region.durations)
+                average_duration = total_duration / region.num_calls
+                min_duration = min(region.durations)
+                max_duration = max(region.durations)
+                std_duration = np.std(region.durations)
+            else:
+                total_duration = average_duration = min_duration = max_duration = (
+                    std_duration
+                ) = 0
+
+            print(f"Region: {name}")
+            print(f"  Number of Calls: {region.num_calls}")
+            print(f"  Total Duration: {total_duration:.6f} seconds")
+            print(f"  Average Duration: {average_duration:.6f} seconds")
+            print(f"  Min Duration: {min_duration:.6f} seconds")
+            print(f"  Max Duration: {max_duration:.6f} seconds")
+            print(f"  Std Deviation: {std_duration:.6f} seconds")
+            print("-" * 40)

scope_profiler-0.1/src/scope_profiler/tests/examples.py

@@ -0,0 +1,40 @@
+from scope_profiler.profiling import ProfileManager
+
+
+def loop(
+    label,
+    num_loops: int = 100,
+):
+    s = 0
+    for i in range(num_loops):
+        with ProfileManager.profile_region(region_name=label):
+            s += 1
+
+
+if __name__ == "__main__":
+    from scope_profiler.profiling import (
+        ProfilingConfig,
+    )
+
+    config = ProfilingConfig(
+        use_likwid=False,
+        time_trace=True,
+        flush_to_disk=True,
+    )
+
+    ProfileManager.reset()
+    num_loops = 10
+
+    loop(
+        label="loop1",
+        num_loops=num_loops,
+    )
+
+    loop(
+        label="loop2",
+        num_loops=num_loops * 2,
+    )
+
+    ProfileManager.print_summary()
+
+    ProfileManager.finalize()

scope_profiler-0.1/src/scope_profiler/tests/test_app.py

@@ -0,0 +1,73 @@
+import pytest
+
+import scope_profiler.tests.examples as examples
+from scope_profiler.profiling import (
+    ProfileManager,
+    ProfilingConfig,
+)
+
+
+@pytest.mark.parametrize("time_trace", [True, False])
+@pytest.mark.parametrize("use_likwid", [False])
+@pytest.mark.parametrize("num_loops", [10, 50, 100])
+@pytest.mark.parametrize("profiling_activated", [True, False])
+def test_profile_manager(
+    time_trace: bool,
+    use_likwid: bool,
+    num_loops: int,
+    profiling_activated: bool,
+):
+
+    ProfilingConfig().reset()
+    config = ProfilingConfig(
+        use_likwid=use_likwid,
+        time_trace=time_trace,
+        profiling_activated=profiling_activated,
+    )
+    ProfileManager.reset()
+
+    examples.loop(
+        label="loop1",
+        num_loops=num_loops,
+    )
+
+    examples.loop(
+        label="loop2",
+        num_loops=num_loops * 2,
+    )
+
+    @ProfileManager.profile
+    def test_decorator():
+        return
+
+    for i in range(num_loops):
+        test_decorator()
+
+    with ProfileManager.profile_region("main"):
+        pass
+
+    if config.time_trace:
+        ProfileManager.print_summary()
+
+    ProfileManager.finalize()
+
+    regions = ProfileManager.get_all_regions()
+
+    if profiling_activated:
+        assert regions["loop1"].num_calls == num_loops
+        assert regions["loop2"].num_calls == num_loops * 2
+        assert regions["test_decorator"].num_calls == num_loops
+        assert regions["main"].num_calls == 1
+    else:
+        assert regions["loop1"].num_calls == 0
+        assert regions["loop2"].num_calls == 0
+        assert regions["test_decorator"].num_calls == 0
+        assert regions["main"].num_calls == 0
+
+
+if __name__ == "__main__":
+    test_profile_manager(
+        time_trace=True,
+        use_likwid=False,
+        num_loops=100,
+    )

scope_profiler-0.1/src/scope_profiler/tests/test_overhead.py

@@ -0,0 +1,75 @@
+import math
+import random
+import time
+
+import numpy as np
+
+import scope_profiler.tests.examples as examples
+from scope_profiler.profiling import (
+    ProfileManager,
+    ProfilingConfig,
+)
+
+
+def random_math(N=100_000):
+    s = 0.0
+    for _ in range(N):
+        x = random.random()
+        s += math.sin(x) * math.sqrt(x + 1.2345)
+    return s
+
+
+def test_overhead():
+
+    config = ProfilingConfig(
+        use_likwid=False,
+        time_trace=True,
+        flush_to_disk=True,
+    )
+
+    ProfileManager.reset()
+    num_computations = 1
+    num_tests = 10
+    N = 1_000_000
+
+    # Without ProfileManager
+    elapsed_no_manager = []
+    for _ in range(num_tests):
+        t0 = time.perf_counter()
+        for _ in range(num_computations):
+            # examples.axpy(N = 50)
+            random_math(N)
+        t1 = time.perf_counter()
+        elapsed_no_manager.append(t1 - t0)
+
+    # With ProfileManager
+    elapsed_with_manager = []
+    for _ in range(num_tests):
+        t0 = time.perf_counter()
+        for _ in range(num_computations):
+            with ProfileManager.profile_region("main"):
+                # examples.axpy(N = 50)
+                random_math(N)
+        t1 = time.perf_counter()
+        elapsed_with_manager.append(t1 - t0)
+
+    elapsed_no_manager = np.array(elapsed_no_manager)
+    elapsed_with_manager = np.array(elapsed_with_manager)
+
+    time_no_manager = np.min(elapsed_no_manager)
+    time_manager = np.min(elapsed_with_manager)
+    ratio = time_manager / time_no_manager
+    print(f"{time_no_manager = }")
+    print(f"{time_manager = }")
+    print(f"Overhead ratio = {ratio}")
+
+    # Very low bar, make sure the overhead is <3%
+    assert ratio < 1.03
+
+    ProfileManager.finalize()
+
+    # ProfileManager.print_summary()
+
+
+if __name__ == "__main__":
+    test_overhead()

scope_profiler-0.1/src/scope_profiler.egg-info/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: scope-profiler
+Version: 0.1
+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.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: h5py
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Provides-Extra: dev
+Requires-Dist: black[jupyter]; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: scope-profiler[docs,test]; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: ipykernel; extra == "docs"
+Requires-Dist: myst-parser; extra == "docs"
+Requires-Dist: nbconvert; extra == "docs"
+Requires-Dist: nbsphinx; extra == "docs"
+Requires-Dist: jupyterlab; 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"
+Provides-Extra: test
+Requires-Dist: coverage; extra == "test"
+Requires-Dist: pytest; extra == "test"
+
+# scope-profiler - Python Profiling System with Optional LIKWID Integration
+
+This module provides a unified profiling system for Python applications, with optional integration of [LIKWID](https://github.com/RRZE-HPC/likwid) markers using the [pylikwid](https://github.com/RRZE-HPC/pylikwid) marker API for hardware performance counters. It allows you to:
+- Configure profiling globally via a singleton ProfilingConfig.
+- Collect timing data via context-managed profiling regions.
+- Use a clean decorator syntax to profile functions.
+- Optionally record time traces in HDF5 files.
+- Automatically initialize and close LIKWID markers only when needed.
+- Print aggregated summaries of all profiling regions.
+
+Documentation: https://max-models.github.io/scope-profiler/
+
+## Install
+
+```
+pip install scope-profiler
+```
+
+## Usage
+
+```python
+from scope_profiler.profiling import (
+    ProfilingConfig,
+    ProfileManager,
+)
+
+config = ProfilingConfig(
+    use_likwid=False,
+    time_trace=True,
+    flush_to_disk=True,
+)
+
+@ProfileManager.profile("main")
+def main():
+    x = 0
+    for i in range(10):
+        with ProfileManager.profile_region(region_name="iteration"):
+            x += 1
+
+main()    
+
+ProfileManager.print_summary()
+
+ProfileManager.finalize()
+```
+
+Execution:
+
+```bash
+❯ python test.py
+Profiling Summary:
+========================================
+Region: main
+  Number of Calls: 1
+  Total Duration: 0.000315 seconds
+  Average Duration: 0.000315 seconds
+  Min Duration: 0.000315 seconds
+  Max Duration: 0.000315 seconds
+  Std Deviation: 0.000000 seconds
+----------------------------------------
+Region: iteration
+  Number of Calls: 10
+  Total Duration: 0.000007 seconds
+  Average Duration: 0.000001 seconds
+  Min Duration: 0.000000 seconds
+  Max Duration: 0.000003 seconds
+  Std Deviation: 0.000001 seconds
+----------------------------------------
+```

scope_profiler-0.1/src/scope_profiler.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+src/scope_profiler/h5reader.py
+src/scope_profiler/post_processing.py
+src/scope_profiler/profiling.py
+src/scope_profiler.egg-info/PKG-INFO
+src/scope_profiler.egg-info/SOURCES.txt
+src/scope_profiler.egg-info/dependency_links.txt
+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/examples.py
+src/scope_profiler/tests/test_app.py
+src/scope_profiler/tests/test_overhead.py

scope_profiler-0.1/src/scope_profiler.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

scope_profiler-0.1/src/scope_profiler.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+scope-profiler-pproc = scope_profiler.post_processing:main

scope_profiler-0.1/src/scope_profiler.egg-info/requires.txt

@@ -0,0 +1,24 @@
+h5py
+numpy
+matplotlib
+
+[dev]
+black[jupyter]
+isort
+ruff
+scope-profiler[docs,test]
+
+[docs]
+ipykernel
+myst-parser
+nbconvert
+nbsphinx
+jupyterlab
+pre-commit
+pyproject-fmt
+sphinx
+sphinx-book-theme
+
+[test]
+coverage
+pytest

scope_profiler-0.1/src/scope_profiler.egg-info/top_level.txt

@@ -0,0 +1 @@
+scope_profiler