nsight-python 1.1.0__py3-none-any.whl → 1.1.1__py3-none-any.whl

nsight/annotation.py

@@ -3,6 +3,7 @@
 
 import functools
 import threading
+import warnings
 from collections.abc import Callable
 from typing import Any
 
@@ -112,7 +113,9 @@ class annotate:
         ignore_failures: Flag indicating whether to ignore
             failures in the annotate context. If set to ``True``, any exceptions
             raised within the context will be ignored, and the profiling will
-            continue. The measured metric for this run will be set to NaN.
+            continue. The measured metric for this run will be set to NaN, and
+            a ``RuntimeWarning`` naming the annotation and the ignored exception
+            is emitted.
             Default: ``False``
 
     Raises:
@@ -179,6 +182,16 @@ class annotate:
         if exc_type and not self.ignore_failures:
             return False  # propagate the exception
 
+        if exc_type:
+            # The failed run only shows up as NaN in the results, so report why
+            # it failed rather than discarding the exception.
+            warnings.warn(
+                f"Ignored failure in annotation '{self.name}': "
+                f"{exc_type.__name__}: {exc_value}",
+                category=RuntimeWarning,
+                stacklevel=2,
+            )
+
         return True
 
     def __call__(self, func: Callable[..., Any]) -> Callable[..., Any]:

nsight/collection/core.py

@@ -7,7 +7,6 @@ import functools
 import importlib.util
 import inspect
 import os
-import pickle
 import threading
 import time
 import warnings
@@ -235,112 +234,6 @@ def _sanitize_configs(
     return configs  # type: ignore[return-value]
 
 
-def _picklable_or_none(value: Any) -> Any:
-    """Return ``value`` if it can be pickled, otherwise None."""
-    try:
-        pickle.dumps(value)
-        return value
-    except Exception:
-        return None
-
-
-def _sanitize_for_pickle(runs: Sequence[Mapping[str, Any]]) -> list[dict[str, Any]]:
-    """Replace any non-picklable collected value with None, preserving structure.
-
-    Used as a fallback when serializing the full collected-info list fails
-    because a collector returned something unserializable (a CUDA stream, file
-    handle, lambda, ...). Degrading the offending value to None keeps the rest of
-    the run's data instead of losing everything.
-    """
-    sanitized: list[dict[str, Any]] = []
-    for run in runs:
-        new = dict(run)
-        new["config"] = _picklable_or_none(run.get("config"))
-        new["once_info"] = {
-            k: _picklable_or_none(v) for k, v in run.get("once_info", {}).items()
-        }
-        new["config_info"] = {
-            k: _picklable_or_none(v) for k, v in run.get("config_info", {}).items()
-        }
-        annotation_info = []
-        for entry in run.get("annotation_info", []):
-            new_entry = dict(entry)
-            new_entry["config"] = _picklable_or_none(entry.get("config"))
-            new_entry["data"] = {
-                k: _picklable_or_none(v) for k, v in entry.get("data", {}).items()
-            }
-            annotation_info.append(new_entry)
-        new["annotation_info"] = annotation_info
-        sanitized.append(new)
-    return sanitized
-
-
-def _serialize_collected_info(
-    runs: Sequence[Mapping[str, Any]],
-) -> tuple[bytes, bool] | None:
-    """Serialize collected info, replacing only non-picklable values.
-
-    Serialization is completed in memory before opening the output file. This
-    keeps collector-value failures separate from filesystem failures such as a
-    full disk or an unwritable output directory.
-
-    Returns:
-        The serialized payload and whether sanitization was required, or
-        ``None`` when the sanitized data still cannot be serialized.
-    """
-    try:
-        return pickle.dumps(runs), False
-    except Exception as exc:
-        sanitized = _sanitize_for_pickle(runs)
-        try:
-            payload = pickle.dumps(sanitized)
-        except Exception as fallback_exc:
-            warnings.warn(
-                "Failed to serialize custom info after replacing non-picklable "
-                f"values ({type(fallback_exc).__name__}: {fallback_exc}).",
-                category=RuntimeWarning,
-                stacklevel=2,
-            )
-            return None
-
-        warnings.warn(
-            f"Some collected info was not picklable ({type(exc).__name__}: {exc}); "
-            "non-picklable collector values have been replaced with None.",
-            category=RuntimeWarning,
-            stacklevel=2,
-        )
-        return payload, True
-
-
-def _save_collected_info(
-    info_file: str,
-    runs: Sequence[Mapping[str, Any]],
-    verbosity: VerbosityLevel,
-) -> bool:
-    """Serialize and save collected info without conflating failure causes."""
-    serialized = _serialize_collected_info(runs)
-    if serialized is None:
-        return False
-
-    payload, sanitized = serialized
-    try:
-        with open(info_file, "wb") as output_file:
-            output_file.write(payload)
-    except OSError as exc:
-        warnings.warn(
-            f"Failed to save custom info to {info_file} "
-            f"({type(exc).__name__}: {exc}).",
-            category=RuntimeWarning,
-            stacklevel=2,
-        )
-        return False
-
-    if verbosity >= VerbosityLevel.INFO:
-        suffix = " (sanitized)" if sanitized else ""
-        print(f"[NSIGHT-PYTHON] Saved collected info{suffix} to {info_file}")
-    return True
-
-
 def run_profile_session(
     func: Callable[..., None],
     configs: list[Sequence[Any]],
@@ -352,8 +245,13 @@ def run_profile_session(
     thermal_timeout: int | None = None,
     thermal_device: int | None = None,
     info_collectors_list: list[NormalizedInfoCollector] | None = None,
-    output_prefix: str | None = None,
-) -> None:
+) -> list[dict[str, Any]]:
+    """Run ``func`` for every config and run inside a profiling session.
+
+    Returns:
+        The custom info collected for each run, in run order, for the caller
+        to pass to extraction.
+    """
 
     if verbosity >= VerbosityLevel.INFO:
         print("")
@@ -385,8 +283,13 @@ def run_profile_session(
     bar_length = 100
     progress_time: float = 0
 
-    # overwrite flag: we do not overwrite when output mode is debug
-    overwrite_output = verbosity < VerbosityLevel.DEBUG
+    # overwrite flag: we do not overwrite when output mode is debug, or when
+    # stdout is not a terminal (overwriting relies on cursor-movement codes)
+    is_terminal = utils.stdout_is_terminal()
+    overwrite_output = verbosity < VerbosityLevel.DEBUG and is_terminal
+    # Without a terminal to overwrite in place, intermediate progress bars would
+    # each become a new line, so only the final one is printed (except in debug)
+    show_intermediate_progress = is_terminal or verbosity >= VerbosityLevel.DEBUG
     show_return_type_warning = False
     config_lengths: list[int] = list()
 
@@ -439,7 +342,7 @@ def run_profile_session(
                 )
 
     # Store collected info for each run
-    collected_info_per_run = []
+    collected_info_per_run: list[dict[str, Any]] = []
 
     for c in configs:
         sig = inspect.signature(func)
@@ -560,7 +463,7 @@ def run_profile_session(
 
             # Update time estimates every half second
             if time.time() - progress_time > 0.5:
-                if verbosity >= VerbosityLevel.INFO:
+                if verbosity >= VerbosityLevel.INFO and show_intermediate_progress:
                     utils.print_progress_bar(
                         total_runs,
                         curr_run,
@@ -594,10 +497,7 @@ def run_profile_session(
             stacklevel=external_stacklevel,
         )
 
-    # Save collected info to a file if we have collectors
-    if info_collectors_list and output_prefix:
-        info_file = f"{output_prefix}collected_info.pkl"
-        _save_collected_info(info_file, collected_info_per_run, verbosity)
+    return collected_info_per_run
 
 
 @dataclasses.dataclass

nsight/collection/cupti.py

@@ -365,7 +365,7 @@ class CUPTICollector(core.NsightCollector):
             for cbid in _LAUNCH_CBIDS:
                 cupti.activity_enable_driver_api(cbid, 1)
 
-            core.run_profile_session(
+            collected_info_per_run = core.run_profile_session(
                 func,
                 configs_list,
                 settings.runs,
@@ -376,7 +376,6 @@ class CUPTICollector(core.NsightCollector):
                 settings.thermal_timeout,
                 settings.thermal_device,
                 settings.info_collectors,
-                settings.output_prefix,
             )
 
             # A kernel's activity record only exists once it has finished, so
@@ -443,7 +442,7 @@ class CUPTICollector(core.NsightCollector):
             settings.info_collectors,
             config_scope_columns,
             annotation_scope_columns,
-            info_prefix=settings.output_prefix or "",
+            collected_info_per_run=collected_info_per_run,
         )
 
         return df

nsight/collection/ncu.py

@@ -492,7 +492,7 @@ class NCUCollector(core.NsightCollector):
                     f"{len(configs_list)} configurations, {settings.runs} runs each",
                 )
 
-            core.run_profile_session(
+            collected_info_per_run = core.run_profile_session(
                 func,
                 configs_list,
                 settings.runs,
@@ -503,7 +503,6 @@ class NCUCollector(core.NsightCollector):
                 settings.thermal_timeout,
                 settings.thermal_device,
                 settings.info_collectors,
-                settings.output_prefix,
             )
         finally:
             try:
@@ -557,7 +556,7 @@ class NCUCollector(core.NsightCollector):
             settings.info_collectors,
             config_scope_columns,
             annotation_scope_columns,
-            info_prefix=settings.output_prefix or "",
+            collected_info_per_run=collected_info_per_run,
         )
 
         return df

nsight/extraction.py

@@ -47,6 +47,14 @@ DERIVED_METRIC_MISSING_UNIT_WARNING = (
     "np.nan will be added to the 'Unit' column in the dataframe."
 )
 
+# Hint appended to kernel-count errors. Autotuning and other first-call work
+# launch extra kernels only on the first run.
+_WARMUP_HINT = (
+    "If the code in the annotation autotunes or does other work only on its "
+    "first call, run it once for every configuration before calling the "
+    "profiled function, so that every run launches the same kernels.\n"
+)
+
 
 def extract_ncu_action_data(action: Any, metrics: Sequence[str]) -> utils.ActionData:
     """
@@ -114,8 +122,13 @@ def extract_data_from_report(
         report: ncu_report.IContext = ncu_report.load_report(report_path)
     except FileNotFoundError:
         raise exceptions.ProfilerException(
-            "No NVIDIA Nsight Compute report found. Please run nsight-python with `@nsight.analyze.kernel(verbosity=nsight.VerbosityLevel.DEBUG)`"
-            "to identify the issue."
+            f"No NVIDIA Nsight Compute report found at {report_path}. NVIDIA Nsight "
+            "Compute writes a report only if it profiled at least one kernel, so "
+            "the most likely cause is that no kernel was launched inside any "
+            "nsight.annotate region (for example, the annotated code only creates "
+            "a view, is a no-op, or returns a cached result). Otherwise, run with "
+            "`@nsight.analyze.kernel(verbosity=nsight.VerbosityLevel.DEBUG)` and "
+            "check the NVIDIA Nsight Compute log to identify the issue."
         )
 
     # Extract all profiling data
@@ -158,7 +171,7 @@ def extract_df_from_data(
     info_collectors_list: List[Tuple[str, Callable[..., Any], str]] | None = None,
     config_scope_columns: List[str] | None = None,
     annotation_scope_columns: List[str] | None = None,
-    info_prefix: str | None = None,
+    collected_info_per_run: Sequence[Mapping[str, Any]] | None = None,
 ) -> pd.DataFrame:
     """
     Aggregates raw per-annotation measurements (from either tool) into a pandas
@@ -173,6 +186,11 @@ def extract_df_from_data(
         derive_metric: Function to transform the raw metric values with config values.
         verbosity: Controls display of extraction progress.
         combine_kernel_metrics: Function to merge multiple kernel metrics.
+        info_collectors_list: Custom info collectors as ``(name, callback, scope)``.
+        config_scope_columns: Collector columns that vary per config or run.
+        annotation_scope_columns: Collector columns that vary per annotation.
+        collected_info_per_run: Custom info collected for each run, in run order,
+            as returned by :func:`nsight.collection.core.run_profile_session`.
 
     Returns:
         A DataFrame containing the extracted and transformed performance data.
@@ -206,46 +224,28 @@ def extract_df_from_data(
         not in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD)
     }
 
-    # Load collected info from the pickle file if it exists
-    collected_info_per_run = []
     custom_info_names = set()
     if info_collectors_list:
-        # The caller supplies the prefix so the read path matches the
-        # collection-session write path exactly.
-        if info_prefix is None:
-            info_prefix = ""
-
         # Column names come from the collector metadata (authoritative), not from
         # the first run's collected data. Deriving from run 0 dropped any
         # annotation-scope collector whose annotation was not entered on run 0.
         custom_info_names = {name for name, _callback, _scope in info_collectors_list}
-
-        info_file = f"{info_prefix}collected_info.pkl"
-        if os.path.exists(info_file):
-            import pickle
-
-            with open(info_file, "rb") as f:
-                collected_info_per_run = pickle.load(f)
-            if not isinstance(collected_info_per_run, list):
-                warnings.warn(
-                    f"Collected info file {info_file} is malformed "
-                    f"(expected a list, got {type(collected_info_per_run).__name__}); "
-                    "ignoring custom info.",
-                    category=RuntimeWarning,
-                    stacklevel=2,
-                )
-                collected_info_per_run = []
-            elif verbosity >= VerbosityLevel.INFO:
-                print(f"[NSIGHT-PYTHON] Loaded collected info from {info_file}")
-        else:
-            if verbosity >= VerbosityLevel.INFO:
-                print(
-                    f"[NSIGHT-PYTHON] Warning: No collected info file found at {info_file}"
-                )
+    else:
+        collected_info_per_run = None
 
     # Create arrays for custom info collectors
     custom_info_arrays: dict[str, list[Any]] = {name: [] for name in custom_info_names}
 
+    # Without this check, a session in which no kernel could be attributed to
+    # any annotation would silently return an empty DataFrame.
+    if not profiling_data:
+        raise RuntimeError(
+            "No kernels were profiled: no kernel launch could be attributed to "
+            "any nsight.annotate region. Check that each annotated region "
+            "launches at least one kernel and that no kernel launched in it is "
+            "listed in ignore_kernel_list."
+        )
+
     for annotation, annotation_data in profiling_data.items():
         if verbosity >= VerbosityLevel.INFO:
             print(f"[NSIGHT-PYTHON] Extracting {annotation} profiling data")
@@ -261,7 +261,9 @@ def extract_df_from_data(
         if len(annotation_data) % len(configs_repeated) != 0:
             raise RuntimeError(
                 "Expect same number of kernels per run. "
-                f"Got average of {len(annotation_data) / len(configs_repeated)} per run"
+                f"Got average of {len(annotation_data) / len(configs_repeated)} per run "
+                f"in the {annotation} annotation.\n"
+                f"{_WARMUP_HINT}"
             )
         num_kernels = len(annotation_data) // len(configs_repeated)
 
@@ -269,12 +271,15 @@ def extract_df_from_data(
             if combine_kernel_metrics is None:
                 raise RuntimeError(
                     (
-                        f"More than one (total={num_kernels}) kernel is launched within the {annotation} annotation.\n"
+                        f"More than one ({len(annotation_data)} in {len(configs_repeated)} "
+                        f"runs, {num_kernels} per run on average) kernel is launched "
+                        f"within the {annotation} annotation.\n"
                         "We expect one kernel per annotation.\n"
                         "Try one of the following solutions:\n"
                         "  - Use `replay_mode='range'` to profile the entire annotated range instead of individual kernels\n"
                         "  - Use `combine_kernel_metrics = lambda x, y: ...` to combine the metrics of multiple kernels\n"
                         "  - Add some of the kernels to the ignore_kernel_list\n"
+                        f"{_WARMUP_HINT}"
                         "Kernels are:\n"
                         + "\n".join(sorted(set(x.name for x in annotation_data)))
                     )
@@ -395,13 +400,12 @@ def extract_df_from_data(
             if (
                 collected_info_per_run
                 and idx < len(collected_info_per_run)
-                and isinstance(collected_info_per_run[idx], dict)
+                and isinstance(collected_info_per_run[idx], Mapping)
             ):
                 run_info = collected_info_per_run[idx]
-                # Add once info. Guard against pickle keys that are not in the
-                # metadata-derived custom_info_names (e.g. a stale collected_info
-                # .pkl written by a different set of collectors); such keys have
-                # no column and are ignored rather than raising KeyError.
+                # Add once info. Guard against keys that are not in the
+                # metadata-derived custom_info_names; such keys have no column
+                # and are ignored rather than raising KeyError.
                 for name, value in run_info.get("once_info", {}).items():
                     if name in custom_info_arrays:
                         custom_info_arrays[name].append(value)
@@ -515,7 +519,7 @@ def extract_df_from_report(
     info_collectors_list: List[Tuple[str, Callable[..., Any], str]] | None = None,
     config_scope_columns: List[str] | None = None,
     annotation_scope_columns: List[str] | None = None,
-    info_prefix: str | None = None,
+    collected_info_per_run: Sequence[Mapping[str, Any]] | None = None,
 ) -> pd.DataFrame:
     """
     Extracts and aggregates profiling results from an NVIDIA Nsight Compute report.
@@ -529,6 +533,11 @@ def extract_df_from_report(
         derive_metric: Function to transform the raw metric values with config values.
         ignore_kernel_list: Kernel names to ignore in the analysis.
         combine_kernel_metrics: Function to merge multiple kernel metrics.
+        info_collectors_list: Custom info collectors as ``(name, callback, scope)``.
+        config_scope_columns: Collector columns that vary per config or run.
+        annotation_scope_columns: Collector columns that vary per annotation.
+        collected_info_per_run: Custom info collected for each run, in run order,
+            as returned by :func:`nsight.collection.core.run_profile_session`.
         verbosity: Controls display of extraction progress.
 
     Returns:
@@ -546,12 +555,6 @@ def extract_df_from_report(
         verbosity,
     )
 
-    # Fall back to reconstructing the info prefix from the report directory for
-    # direct callers that did not supply one.
-    if info_collectors_list and info_prefix is None:
-        report_dir = os.path.dirname(report_path)
-        info_prefix = os.path.join(report_dir, "") if report_dir else ""
-
     return extract_df_from_data(
         profiling_data,
         metrics,
@@ -564,5 +567,5 @@ def extract_df_from_report(
         info_collectors_list,
         config_scope_columns,
         annotation_scope_columns,
-        info_prefix,
+        collected_info_per_run,
     )

nsight/utils.py

@@ -78,8 +78,23 @@ class Colors:
     UNDERLINE = "\033[4m"
 
 
+def stdout_is_terminal() -> bool:
+    """
+    Returns whether stdout is an interactive terminal.
+
+    ANSI color and cursor-movement codes are only emitted when this is true, so
+    that output redirected to a file, a pipe, or a captured log stays plain text.
+    """
+    try:
+        return sys.stdout.isatty()
+    except (AttributeError, ValueError):
+        return False
+
+
 def purple(msg: str) -> str:  # pragma: no cover
     """Prints ``msg`` in purple."""
+    if not stdout_is_terminal():
+        return msg
     return Colors.PURPLE + msg + Colors.ENDC
 
 

{nsight_python-1.1.0.dist-info → nsight_python-1.1.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nsight-python
-Version: 1.1.0
+Version: 1.1.1
 Summary: Python GPU kernel profiling interface
 Project-URL: Repository, https://github.com/NVIDIA/nsight-python
 Project-URL: License, https://docs.nvidia.com/nsight-python/license.html

{nsight_python-1.1.0.dist-info → nsight_python-1.1.1.dist-info}/RECORD

@@ -1,20 +1,20 @@
 nsight/__init__.py,sha256=LrDF8j_emdbwNNsqSrABCRsDanTGzfRWfCjj8H2MbsI,1471
 nsight/analyze.py,sha256=91BFc7SdR9JXQER6hBK2USGP43Ile_d9l3nVFVOME2E,35548
-nsight/annotation.py,sha256=9untg0pRI3FR-gRQKCmHrbFgv1zEdooZgfGAzuocYAY,6730
+nsight/annotation.py,sha256=-dLOQS0wn54rKEmk-Mu3frINUDQqLkVNlxDaITV4CJo,7249
 nsight/exceptions.py,sha256=LhtCtaOBP6m9KVWv9RjEqx3pGP2trLObC2aqEvE4fuE,2634
 nsight/experimental.py,sha256=iE24Whb6Jo48f_tTNvZm8aLWyEabnB8xL8nUk2Ps9ik,2611
-nsight/extraction.py,sha256=Wp4tDwnu895U5zldhxoT_qpEpiC9325zMS6_get692A,24455
+nsight/extraction.py,sha256=kh-BZdNhngZZWmctPA7VcqOXWUvQ1y8jkTLQ4LGPzhs,25226
 nsight/info_collector.py,sha256=hGJgFoC--UKYvGeUm76j_g32CUNd-HpseGt4wE3YJxI,12871
 nsight/thermovision.py,sha256=z5_WvFbYLWb1jyuMPSfS1Ia58vdq3_tAtRPJzwg2sIc,14836
 nsight/tools_manager.py,sha256=ZT0MrzBZK1l6HAIwBmAv54veBWbo0ZOxxvD5xhY1Xx4,3353
 nsight/transformation.py,sha256=-Myr51srFaQzGAoFxFScQ7SsKrRpv4rVzW7Ob0yKH7k,8604
-nsight/utils.py,sha256=W_n5eKFAMzZiqB0hTku161zTJKoUfBuJ2ucsUO0qa6A,12080
+nsight/utils.py,sha256=MU2cVPsuA7sv-RuHECDvA3V9OS70duIFseNsU35NIcA,12508
 nsight/visualization.py,sha256=OJpFVGXQuTPD2Tl2EsEuOO4rj8L-F_0OZczADPBwknk,20341
 nsight/collection/__init__.py,sha256=a4C7kKg9WDdgmOwS-GpgLyXTwv2BVZNd1mjB3Ppax_g,335
-nsight/collection/core.py,sha256=pmINh39_CBhoMsm13psoawSfDXEjww4OjLZAeXQM57Y,34471
-nsight/collection/cupti.py,sha256=nK5PkWftictdMBHPDGuZchYmymwexZ6_iSQXNLqc3lQ,17446
-nsight/collection/ncu.py,sha256=dGLVaNGD9muRdTLskOS2SWrP2yrO7oh-aQYldrfIhmA,21671
-nsight_python-1.1.0.dist-info/METADATA,sha256=YHFoemld9oY7FPmmOdd4GudRLc5hJW1TgmLVPrCcoyU,15121
-nsight_python-1.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-nsight_python-1.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-nsight_python-1.1.0.dist-info/RECORD,,
+nsight/collection/core.py,sha256=ykUCwUERY3EAd0_vNCbXF9IaOANiKka_eIYB7q7kb9Y,31112
+nsight/collection/cupti.py,sha256=Sdq7_kjWa-vMVT2vZY5Bt5nuh9NB7SNQfnAuV4ylj6Q,17436
+nsight/collection/ncu.py,sha256=ZT3HjjBMLUnYz5XlxJAmVs_ZsoZ1NIj-3FOsYxz6pnw,21661
+nsight_python-1.1.1.dist-info/METADATA,sha256=UzuCstAbx72oaSYWoU8l0CXwUwWmiN8BvPm_7wcopkU,15121
+nsight_python-1.1.1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+nsight_python-1.1.1.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+nsight_python-1.1.1.dist-info/RECORD,,

{nsight_python-1.1.0.dist-info → nsight_python-1.1.1.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.32.4
+Generator: hatchling 1.33.0
 Root-Is-Purelib: true
 Tag: py3-none-any