carm-roofline 1.0.2.dev0__tar.gz → 1.0.2.dev2__tar.gz

{carm_roofline-1.0.2.dev0 → carm_roofline-1.0.2.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: carm-roofline
-Version: 1.0.2.dev0
+Version: 1.0.2.dev2
 Summary: CARM: Cache-Aware Roofline Model benchmarking and visualization toolkit
 Author: CHaMP Team
 License:                                  Apache License
@@ -246,7 +246,6 @@ Dynamic: license-file
 
 # The CARM Tool
 
-
 Cache-Aware Roofline Model (CARM) toolkit - benchmark, visualize and profile Intel, AMD, ARM, RISC-V CPUs and NVIDIA, AMD GPUs.
 
 The package provides:
@@ -258,6 +257,10 @@ The package provides:
 > [!WARNING]
 > The development branch and associated python package are still experimental, and do not include all features yet. For a stable release, please refer to the main branch.
 
+## Documentation
+
+You can find the full documentation at [https://champ-hub.github.io/carm-roofline](https://champ-hub.github.io/carm-roofline/).
+
 ## Installation
 
 Install from PyPI:
@@ -279,10 +282,17 @@ source carm-env/bin/activate
 pip install carm-roofline[all]
 ```
 
+If cloning the repository directly (e.g. for development or access to example applications), use `--recurse-submodules` to also fetch the examples:
+
+```bash
+git clone --recurse-submodules https://github.com/champ-hub/carm-roofline
+```
+
 ## Requirements
 
 - Python 3.9+
-- GCC (for compiling benchmark binaries)
+- C compiler (e.g. gcc, clang)
+- Optional: [PAPI](https://github.com/icl-utk-edu/papi) headers and binaries for profiling
 
 ## Command-Line Interface
 
@@ -296,7 +306,7 @@ Available subcommands:
 
 - `benchmark` - run benchmark suites
 - `gui` - launch the results dashboard
-- `profile` - coming soon
+- `profile` - profile an application with PAPI or perf
 
 Show help:
 
@@ -304,6 +314,7 @@ Show help:
 carm --help
 carm benchmark --help
 carm gui --help
+carm profile --help
 ```
 
 ## Basic Usage

{carm_roofline-1.0.2.dev0 → carm_roofline-1.0.2.dev2}/README.md

@@ -1,7 +1,6 @@
 
 # The CARM Tool
 
-
 Cache-Aware Roofline Model (CARM) toolkit - benchmark, visualize and profile Intel, AMD, ARM, RISC-V CPUs and NVIDIA, AMD GPUs.
 
 The package provides:
@@ -13,6 +12,10 @@ The package provides:
 > [!WARNING]
 > The development branch and associated python package are still experimental, and do not include all features yet. For a stable release, please refer to the main branch.
 
+## Documentation
+
+You can find the full documentation at [https://champ-hub.github.io/carm-roofline](https://champ-hub.github.io/carm-roofline/).
+
 ## Installation
 
 Install from PyPI:
@@ -34,10 +37,17 @@ source carm-env/bin/activate
 pip install carm-roofline[all]
 ```
 
+If cloning the repository directly (e.g. for development or access to example applications), use `--recurse-submodules` to also fetch the examples:
+
+```bash
+git clone --recurse-submodules https://github.com/champ-hub/carm-roofline
+```
+
 ## Requirements
 
 - Python 3.9+
-- GCC (for compiling benchmark binaries)
+- C compiler (e.g. gcc, clang)
+- Optional: [PAPI](https://github.com/icl-utk-edu/papi) headers and binaries for profiling
 
 ## Command-Line Interface
 
@@ -51,7 +61,7 @@ Available subcommands:
 
 - `benchmark` - run benchmark suites
 - `gui` - launch the results dashboard
-- `profile` - coming soon
+- `profile` - profile an application with PAPI or perf
 
 Show help:
 
@@ -59,6 +69,7 @@ Show help:
 carm --help
 carm benchmark --help
 carm gui --help
+carm profile --help
 ```
 
 ## Basic Usage

{carm_roofline-1.0.2.dev0 → carm_roofline-1.0.2.dev2}/architecture/__init__.py

@@ -5,7 +5,13 @@ import contextvars
 from exec_interface import ExecutionInterface
 
 from .architecture import Architecture
-from .identity import MachineSignature, detect_machine_signature, generate_run_name, signature_from_architecture
+from .identity import (
+    MachineSignature,
+    detect_machine_signature,
+    generate_run_name,
+    signature_from_architecture,
+    write_machine_json,
+)
 from .memory import SimpleMemoryTopology
 
 # Context variable to hold the execution interface, for compatibility with simulation and native execution
@@ -31,4 +37,5 @@ __all__ = [
     "get_execution_interface",
     "set_execution_interface",
     "signature_from_architecture",
+    "write_machine_json",
 ]

{carm_roofline-1.0.2.dev0 → carm_roofline-1.0.2.dev2}/architecture/identity.py

@@ -11,6 +11,8 @@ machine yields the same name across runs.
 from __future__ import annotations
 
 import hashlib
+import json
+import os
 import platform
 import re
 from dataclasses import dataclass
@@ -22,6 +24,8 @@ from .memory import MemoryLevelInfo, MemoryTopology, MemoryTopologyLike
 if TYPE_CHECKING:
     from .architecture import Architecture
 
+_BYTES_PER_GIB = 1024**3
+
 
 @dataclass(frozen=True)
 class CpuInfo:
@@ -55,17 +59,52 @@ class MachineSignature:
     vendor: str
     memory_levels: tuple[MemoryLevelSignature, ...]
 
+    def _canonical_hash_string(self) -> str:
+        """Canonical string fed to SHA-256 for the config hash.
+
+        Format: ``arch=<arch>;vendor=<vendor>;levels=<levels>`` where
+        ``<levels>`` is a ``|``-separated list of
+        ``<name>:<size_bytes>:<instances>:<num_sharing_threads>``.
+        """
+        levels_str = "|".join(
+            f"{lvl.name}:{lvl.size_bytes}:{lvl.instances}:{lvl.num_sharing_threads}" for lvl in self.memory_levels
+        )
+        return f"arch={self.arch};vendor={self.vendor};levels={levels_str}"
+
     @property
     def config_hash(self) -> str:
         """Deterministic 8-char hex SHA256 of non-model-name fields.
 
         Hash inputs: arch, vendor, memory_levels (name, size, instances, sharing).
+
+        .. note::
+            DRAM ``size_bytes`` comes from ``/proc/zoneinfo`` ``present`` pages
+            (physical capacity, stable across reboots).  Falls back to a
+            rounded-``MemTotal`` value when zoneinfo is unavailable.
+            ``num_sharing_threads`` is set to 0 for DRAM (not a hardware
+            property; CPU online count may vary).  Cache-level fields are
+            used verbatim.
         """
-        levels_str = "|".join(
-            f"{lvl.name}:{lvl.size_bytes}:{lvl.instances}:{lvl.num_sharing_threads}" for lvl in self.memory_levels
-        )
-        canonical = f"arch={self.arch};vendor={self.vendor};levels={levels_str}"
-        return hashlib.sha256(canonical.encode("utf-8")).hexdigest()[:8]
+        return hashlib.sha256(self._canonical_hash_string().encode("utf-8")).hexdigest()[:8]
+
+    def to_dict(self) -> dict[str, object]:
+        """Serialize all fields for machine.json debugging output."""
+        return {
+            "model_name": self.model_name,
+            "arch": self.arch,
+            "vendor": self.vendor,
+            "config_hash": self.config_hash,
+            "hash_input": self._canonical_hash_string(),
+            "memory_levels": [
+                {
+                    "name": lvl.name,
+                    "size_bytes": lvl.size_bytes,
+                    "instances": lvl.instances,
+                    "num_sharing_threads": lvl.num_sharing_threads,
+                }
+                for lvl in self.memory_levels
+            ],
+        }
 
 
 def read_cpuinfo() -> CpuInfo:
@@ -102,21 +141,69 @@ def read_cpuinfo() -> CpuInfo:
     return CpuInfo(model_name=model_name, vendor=vendor)
 
 
+def _get_physical_ram_bytes() -> int | None:
+    """Total physical RAM (bytes) from ``/proc/zoneinfo``, or ``None``.
+
+    Sums the ``present`` field across all zones — this is the number of
+    physical pages present, derived from the firmware's e820/device-tree
+    memory map at boot.  It reflects hardware capacity and is stable across
+    reboots, unlike ``MemTotal`` which subtracts kernel runtime reservations.
+    """
+    try:
+        with open("/proc/zoneinfo") as f:
+            total_present = 0
+            for line in f:
+                parts = line.strip().split()
+                if len(parts) == 2 and parts[0] == "present":
+                    total_present += int(parts[1])
+        return total_present * os.sysconf("SC_PAGE_SIZE")
+    except (OSError, ValueError):
+        return None
+
+
 def _levels_from_topology(topology: MemoryTopologyLike | None) -> tuple[MemoryLevelSignature, ...]:
-    """Convert a memory topology to a tuple of deterministic level signatures."""
+    """Convert a memory topology to a tuple of deterministic level signatures.
+
+    DRAM levels use the ``present`` page count from ``/proc/zoneinfo`` (a
+    hardware-capacity value stable across reboots).  Falls back to rounding
+    the topology's ``MemTotal``-based size to the nearest GiB when zoneinfo
+    is unavailable (containers, odd kernels).
+
+    ``num_sharing_threads`` is set to 0 for DRAM (not a hardware property;
+    ``shared_cpu_list`` varies with CPU online count).
+
+    Cache levels (L1/L2/L3) are passed through unchanged.
+    """
+    # Read physical RAM once — stable firmware value
+    physical_ram = _get_physical_ram_bytes()
+
     if topology is None:
         return ()
     levels: list[MemoryLevelSignature] = []
     for lvl in topology:
         if isinstance(lvl, MemoryLevelInfo):
-            levels.append(
-                MemoryLevelSignature(
-                    name=lvl.name,
-                    size_bytes=int(lvl.size.value),
-                    instances=lvl.instances,
-                    num_sharing_threads=lvl.num_sharing_threads,
+            if lvl.name == "DRAM":
+                if physical_ram is not None:
+                    size_bytes = physical_ram
+                else:
+                    size_bytes = round(int(lvl.size) / _BYTES_PER_GIB) * _BYTES_PER_GIB
+                levels.append(
+                    MemoryLevelSignature(
+                        name=lvl.name,
+                        size_bytes=size_bytes,
+                        instances=lvl.instances,
+                        num_sharing_threads=0,
+                    )
+                )
+            else:
+                levels.append(
+                    MemoryLevelSignature(
+                        name=lvl.name,
+                        size_bytes=int(lvl.size),
+                        instances=lvl.instances,
+                        num_sharing_threads=lvl.num_sharing_threads,
+                    )
                 )
-            )
     return tuple(levels)
 
 
@@ -206,3 +293,18 @@ def _short_model_name(name: str) -> str:
 def generate_run_name(signature: MachineSignature) -> str:
     """Generate ``"<short_model>_<config_hash>"`` (e.g. ``"Ryzen-7-7735HS_59486dd1"``)."""
     return f"{_short_model_name(signature.model_name)}_{signature.config_hash}"
+
+
+def write_machine_json(signature: MachineSignature, directory: Path) -> None:
+    """Write machine.json to *directory* if it does not already exist.
+
+    The file contains the full MachineSignature serialized as JSON, including
+    all hash inputs and the computed hash, so future runs can debug why a
+    machine hash changed.
+    """
+    path = directory / "machine.json"
+    if path.exists():
+        return
+    directory.mkdir(parents=True, exist_ok=True)
+    with open(path, "x", encoding="utf-8") as f:
+        json.dump(signature.to_dict(), f, indent=2, sort_keys=True)

{carm_roofline-1.0.2.dev0 → carm_roofline-1.0.2.dev2}/benchmark/output/arithmetic.py

@@ -33,7 +33,7 @@ def _collect_gops_by_isa(isa_suites: dict[str, ISABenchmarkSuite]) -> dict[str,
             if not isinstance(bench.results, ArithmeticBenchmarkResult):
                 continue
 
-            gops_value = float(bench.results.performance.value) / 1e9
+            gops_value = float(bench.results.performance) / 1e9
             if not math.isfinite(gops_value):
                 warn(f"Skipping invalid GOPS value for ISA {isa}: {gops_value}")
                 continue
@@ -73,7 +73,7 @@ def _print_table(context: CARMContext, isa_suites: dict[str, ISABenchmarkSuite])
             )
 
             ops_per_inst = isa_instance.ops_per_inst(benchmark.params.data_type, benchmark.params.operation)
-            total_insts = (benchmark.params.num_ops.value // ops_per_inst) * res.num_repetitions if ops_per_inst else 0
+            total_insts = (int(benchmark.params.num_ops) // ops_per_inst) * res.num_repetitions if ops_per_inst else 0
             cycles = Cycles.from_time_and_frequency(res.time_taken, frequency)
             ipc = 0.0 if cycles.value == 0 else total_insts / cycles.value
             ops_per_cycle = ops_per_inst * ipc
@@ -84,17 +84,17 @@ def _print_table(context: CARMContext, isa_suites: dict[str, ISABenchmarkSuite])
                     "operation": benchmark.params.operation.name,
                     "benchmark": benchmark_name,
                     "threads": benchmark.params.num_threads,
-                    "gops": float(res.performance.value) / 1e9,
+                    "gops": float(res.performance) / 1e9,
                     "gops_display": str(res.performance),
                     "ipc": ipc,
-                    "frequency_hz": float(frequency.value),
+                    "frequency_hz": float(frequency),
                     "frequency_display": str(frequency),
                     "ops_per_instruction": ops_per_inst,
                     "ops_per_cycle": ops_per_cycle,
-                    "time_seconds": float(res.time_taken.value),
+                    "time_seconds": float(res.time_taken),
                     "time_display": str(res.time_taken),
                     "repetitions": int(res.num_repetitions),
-                    "cycles": float(cycles.value),
+                    "cycles": float(cycles),
                     "cycles_display": str(cycles),
                 }
             )

{carm_roofline-1.0.2.dev0 → carm_roofline-1.0.2.dev2}/benchmark/output/jsonl.py

@@ -40,7 +40,7 @@ def _serialize_arithmetic(
     assert isinstance(res, ArithmeticBenchmarkResult)
 
     ops_per_inst = isa_instance.ops_per_inst(bench.params.data_type, bench.params.operation)
-    total_insts = (bench.params.num_ops.value // ops_per_inst) * res.num_repetitions if ops_per_inst else 0
+    total_insts = (int(bench.params.num_ops) // ops_per_inst) * res.num_repetitions if ops_per_inst else 0
     cycles = Cycles.from_time_and_frequency(res.time_taken, frequency)
     ipc = 0.0 if cycles.value == 0 else total_insts / cycles.value
 
@@ -54,15 +54,15 @@ def _serialize_arithmetic(
         "timestamp": timestamp,
         "machine": machine,
         "operation": bench.params.operation.name,
-        "num_ops": int(bench.params.num_ops.value),
-        "performance_gops": res.performance.value / 1e9,
+        "num_ops": int(bench.params.num_ops),
+        "performance_gops": float(res.performance) / 1e9,
         "ipc": ipc,
-        "frequency_hz": frequency.value,
+        "frequency_hz": float(frequency),
         "ops_per_instruction": ops_per_inst,
         "ops_per_cycle": ops_per_inst * ipc,
-        "time_seconds": res.time_taken.value,
+        "time_seconds": float(res.time_taken),
         "repetitions": res.num_repetitions,
-        "cycles": cycles.value,
+        "cycles": int(cycles),
     }
 
 
@@ -81,7 +81,7 @@ def _serialize_memory(
     assert isinstance(res, MemoryBenchmarkResult)
 
     bpi = isa_instance.bytes_per_inst(bench.params.data_type)
-    total_insts = (bench.working_set_bytes.value // bpi) * res.num_repetitions
+    total_insts = (int(bench.working_set_bytes) // bpi) * res.num_repetitions
     cycles = Cycles.from_time_and_frequency(res.time_taken, frequency)
     ipc = 0.0 if cycles.value == 0 else total_insts / cycles.value
 
@@ -99,14 +99,14 @@ def _serialize_memory(
         "num_stores": bench.params.num_st,
         "cache_level": bench.cache_level,
         "memory_level_name": bench.params.memory_level_name,
-        "size_per_thread_bytes": bench.params.size_per_thread.value,
-        "working_set_bytes": bench.working_set_bytes.value,
+        "size_per_thread_bytes": int(bench.params.size_per_thread),
+        "working_set_bytes": int(bench.working_set_bytes),
         "layout_mode": bench.params.layout_mode.value,
-        "bandwidth_gbps": res.bandwidth.value / 1e9,
+        "bandwidth_gbps": float(res.bandwidth) / 1e9,
         "ipc": ipc,
-        "time_seconds": res.time_taken.value,
+        "time_seconds": float(res.time_taken),
         "repetitions": res.num_repetitions,
-        "cycles": cycles.value,
+        "cycles": int(cycles),
     }
 
 

{carm_roofline-1.0.2.dev0 → carm_roofline-1.0.2.dev2}/benchmark/output/memory.py

@@ -40,7 +40,7 @@ def _collect_bandwidth_by_label(isa_suites: dict[str, ISABenchmarkSuite]) -> dic
                 continue
 
             level = res.cache_level or "unknown"
-            bandwidth_value = float(res.bandwidth.value) / 1e9
+            bandwidth_value = float(res.bandwidth) / 1e9
             if not math.isfinite(bandwidth_value):
                 warn(f"Skipping invalid bandwidth value for {isa}/{name}: {bandwidth_value}")
                 continue
@@ -84,7 +84,7 @@ def _print_table(context: CARMContext, isa_suites: dict[str, ISABenchmarkSuite])
             assert bench.results is not None  # for type checker
             level = bench.results.cache_level or "unknown"
             bytes_per_inst = isa_instance.bytes_per_inst(bench.params.data_type)
-            total_insts = (bench.working_set_bytes.value // bytes_per_inst) * bench.results.num_repetitions
+            total_insts = (int(bench.working_set_bytes) // bytes_per_inst) * bench.results.num_repetitions
             cycles = Cycles.from_time_and_frequency(bench.results.time_taken, frequency)
 
             ipc = total_insts / cycles.value

{carm_roofline-1.0.2.dev0 → carm_roofline-1.0.2.dev2}/benchmark/output/memory_sweep.py

@@ -79,7 +79,7 @@ def _print_table(context: CARMContext, isa_suites: dict[str, ISABenchmarkSuite])
         for _name, bench in sorted(mem_benchmarks.items(), key=lambda kv: kv[0]):
             assert bench.results is not None  # for type checker
             bytes_per_inst = isa_instance.bytes_per_inst(bench.params.data_type)
-            total_insts = (bench.working_set_bytes.value // bytes_per_inst) * bench.results.num_repetitions
+            total_insts = (int(bench.working_set_bytes) // bytes_per_inst) * bench.results.num_repetitions
             cycles = Cycles.from_time_and_frequency(bench.results.time_taken, frequency)
             cache_level = bench.results.cache_level or "unknown"
             table.add_row(
@@ -114,22 +114,22 @@ def _collect_sweep_series(
             for ws_bytes, cache_level, bandwidth in suite.get_sweep_data():
                 if bandwidth is None:
                     continue
-                bw_val = float(bandwidth.value) / 1e9
+                bw_val = float(bandwidth) / 1e9
                 if not math.isfinite(bw_val):
                     continue
-                points.append((ws_bytes.value, cache_level, bw_val))
+                points.append((int(ws_bytes), cache_level, bw_val))
         else:
             mem_benchmarks = suite.get_memory_benchmarks()
             for _name, bench in sorted(mem_benchmarks.items(), key=lambda kv: kv[0]):
                 res = bench.results
                 if not isinstance(res, MemoryBenchmarkResult):
                     continue
-                bw_val = float(res.bandwidth.value) / 1e9
+                bw_val = float(res.bandwidth) / 1e9
                 if not math.isfinite(bw_val):
                     continue
                 ws = bench.working_set_bytes
                 cache_level = res.cache_level or "unknown"
-                points.append((ws.value, cache_level, bw_val))
+                points.append((int(ws), cache_level, bw_val))
 
         if points:
             points.sort(key=lambda t: t[0])

{carm_roofline-1.0.2.dev0 → carm_roofline-1.0.2.dev2}/benchmark/output/roofline.py

@@ -114,7 +114,7 @@ def _cache_sizes_kib(context: CARMContext) -> tuple[int, int, int]:
             size = getattr(level, "size", None)
             if size is None:
                 continue
-            kib = int(size.value // 1024)
+            kib = int(size) // 1024
             if name == "L1":
                 l1_kib = kib
             elif name == "L2":
@@ -131,7 +131,7 @@ def _cache_sizes_kib(context: CARMContext) -> tuple[int, int, int]:
 def _find_dram_working_set_bytes(suite: ISABenchmarkSuite) -> int:
     for bench in suite.get_memory_benchmarks().values():
         if bench.cache_level == "DRAM" and getattr(bench, "working_set_bytes", None) is not None:
-            return int(bench.working_set_bytes.value)
+            return int(bench.working_set_bytes)
     return 0
 
 
@@ -175,8 +175,8 @@ def _aggregate_level_metrics(
         level = bench.cache_level
         assert level is not None
         bytes_per_inst = isa_instance.bytes_per_inst(bench.params.data_type)
-        bandwidth_by_level[level] = float(bench.results.bandwidth.value) / 1e9
-        total_insts = (bench.working_set_bytes.value // bytes_per_inst) * bench.results.num_repetitions
+        bandwidth_by_level[level] = float(bench.results.bandwidth) / 1e9
+        total_insts = (int(bench.working_set_bytes) // bytes_per_inst) * bench.results.num_repetitions
         cycles = Cycles.from_time_and_frequency(bench.results.time_taken, frequency)
         ipc_by_level[level] = 0.0 if cycles.value == 0 else total_insts / cycles.value
 
@@ -208,12 +208,10 @@ def _pick_fp_for_combo(
         if bench.params.data_type != dt or bench.params.num_threads != nt:
             continue
         ops_per_inst = isa_instance.ops_per_inst(bench.params.data_type, bench.params.operation)
-        total_insts = (
-            (bench.params.num_ops.value // ops_per_inst) * bench.results.num_repetitions if ops_per_inst else 0
-        )
+        total_insts = (int(bench.params.num_ops) // ops_per_inst) * bench.results.num_repetitions if ops_per_inst else 0
         cycles = Cycles.from_time_and_frequency(bench.results.time_taken, frequency)
         ipc = 0.0 if cycles.value == 0 else total_insts / cycles.value
-        gflops = float(bench.results.performance.value) / 1e9
+        gflops = float(bench.results.performance) / 1e9
 
         if bench.params.operation == ArithmeticOperation.fma:
             fma_gflops = gflops

{carm_roofline-1.0.2.dev0 → carm_roofline-1.0.2.dev2}/benchmark/suites/memory_sweep.py

@@ -94,14 +94,14 @@ class MemorySweepBenchmarkSuite(ISABenchmarkSuite):
             # Step 2 - Determine sweep range.
             # ------------------------------------------------------------------
             _, _, l1_avail, _ = level_table[0]
-            min_size_bytes: float = 0.1 * float(l1_avail.value)
+            min_size_bytes: float = 0.1 * float(l1_avail)
 
             if len(level_table) >= 2:
                 _, _, last_cache_avail, _ = level_table[-2]
             else:
                 _, _, last_cache_avail, _ = level_table[-1]
 
-            max_size_bytes: float = 32.0 * float(last_cache_avail.value)
+            max_size_bytes: float = 32.0 * float(last_cache_avail)
 
             if max_size_bytes <= min_size_bytes:
                 raise ValueError(
@@ -200,5 +200,5 @@ class MemorySweepBenchmarkSuite(ISABenchmarkSuite):
             level = bench.cache_level if bench.cache_level is not None else "UNKNOWN"
             rows.append((bench.working_set_bytes, level, bw))
 
-        rows.sort(key=lambda t: t[0].value)
+        rows.sort(key=lambda t: t[0])
         return rows

{carm_roofline-1.0.2.dev0 → carm_roofline-1.0.2.dev2}/carm.py

@@ -17,6 +17,7 @@ from architecture import (
     generate_run_name,
     set_execution_interface,
     signature_from_architecture,
+    write_machine_json,
 )
 from arguments import InsertsArguments, TopLevelHelpFormatter
 from benchmark.interface import run_full_benchmark
@@ -58,8 +59,9 @@ def _handle_benchmark(args: argparse.Namespace) -> int:
     # Make exec_iface globally available for architecture feature detection
     set_execution_interface(exec_iface)
     architecture = Architecture(args)
+    signature = signature_from_architecture(architecture)
     if args.name is None:
-        args.name = generate_run_name(signature_from_architecture(architecture))
+        args.name = generate_run_name(signature)
     benchmarking = Benchmarking(args)
     run_config = RunConfig(args)
 
@@ -73,6 +75,7 @@ def _handle_benchmark(args: argparse.Namespace) -> int:
         detail("Dry run finished: benchmark code generated successfully.")
         return 0
 
+    write_machine_json(signature, run_config.output_dir / run_config.name)
     output_benchmark_results(context, benchmark_suites)
     return 0
 
@@ -126,7 +129,7 @@ SUBPARSERS = (
     ),
     SubParserInfo(
         name="profile",
-        help_short="Profile applications with PAPI",
+        help_short="Profile applications for CARM analysis",
         help_long="Profile instrumented applications to compute roofline metrics (AI, GFLOP/s, bandwidth). "
         "Supports MPI, threaded, and hybrid applications. "
         "Usage: carm profile [options] -- <command>",

{carm_roofline-1.0.2.dev0 → carm_roofline-1.0.2.dev2}/carm_roofline.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: carm-roofline
-Version: 1.0.2.dev0
+Version: 1.0.2.dev2
 Summary: CARM: Cache-Aware Roofline Model benchmarking and visualization toolkit
 Author: CHaMP Team
 License:                                  Apache License
@@ -246,7 +246,6 @@ Dynamic: license-file
 
 # The CARM Tool
 
-
 Cache-Aware Roofline Model (CARM) toolkit - benchmark, visualize and profile Intel, AMD, ARM, RISC-V CPUs and NVIDIA, AMD GPUs.
 
 The package provides:
@@ -258,6 +257,10 @@ The package provides:
 > [!WARNING]
 > The development branch and associated python package are still experimental, and do not include all features yet. For a stable release, please refer to the main branch.
 
+## Documentation
+
+You can find the full documentation at [https://champ-hub.github.io/carm-roofline](https://champ-hub.github.io/carm-roofline/).
+
 ## Installation
 
 Install from PyPI:
@@ -279,10 +282,17 @@ source carm-env/bin/activate
 pip install carm-roofline[all]
 ```
 
+If cloning the repository directly (e.g. for development or access to example applications), use `--recurse-submodules` to also fetch the examples:
+
+```bash
+git clone --recurse-submodules https://github.com/champ-hub/carm-roofline
+```
+
 ## Requirements
 
 - Python 3.9+
-- GCC (for compiling benchmark binaries)
+- C compiler (e.g. gcc, clang)
+- Optional: [PAPI](https://github.com/icl-utk-edu/papi) headers and binaries for profiling
 
 ## Command-Line Interface
 
@@ -296,7 +306,7 @@ Available subcommands:
 
 - `benchmark` - run benchmark suites
 - `gui` - launch the results dashboard
-- `profile` - coming soon
+- `profile` - profile an application with PAPI or perf
 
 Show help:
 
@@ -304,6 +314,7 @@ Show help:
 carm --help
 carm benchmark --help
 carm gui --help
+carm profile --help
 ```
 
 ## Basic Usage