nsight-python 0.9.6__py3-none-any.whl → 1.0.0__py3-none-any.whl

nsight/__init__.py

@@ -5,8 +5,12 @@ from importlib.metadata import version
 
 from nsight import analyze
 from nsight.annotation import annotate
-from nsight.utils import col_panel, row_panel
+from nsight.collection.ncu import try_init_injection
+from nsight.utils import VerbosityLevel, col_panel, row_panel
+
+# Load injection library and symbols for NCU attach (if available)
+try_init_injection()
 
 __version__ = version("nsight-python")
 
-__all__ = ["analyze", "annotate"]
+__all__ = ["analyze", "annotate", "VerbosityLevel"]

nsight/analyze.py

@@ -7,7 +7,7 @@ import os
 import tempfile
 import warnings
 from collections.abc import Callable, Iterable, Sequence
-from typing import Any, Literal, overload
+from typing import Any, Literal, Mapping, overload
 
 import matplotlib
 import matplotlib.figure
@@ -16,6 +16,7 @@ from numpy.typing import NDArray
 
 import nsight.collection as collection
 import nsight.visualization as visualization
+from nsight.utils import VerbosityLevel
 
 
 # Overload 1: When used without parentheses: @kernel
@@ -32,9 +33,14 @@ def kernel(
     *,
     configs: Iterable[Any] | None = None,
     runs: int = 1,
-    derive_metric: Callable[..., float | dict[str, float]] | None = None,
+    derive_metric: (
+        Callable[
+            ..., float | tuple[float, str] | Mapping[str, float | tuple[float, str]]
+        ]
+        | None
+    ) = None,
     normalize_against: str | None = None,
-    output: Literal["quiet", "progress", "verbose"] = "progress",
+    verbosity: VerbosityLevel = VerbosityLevel.INFO,
     metrics: Sequence[str] = ["gpu__time_duration.sum"],
     ignore_kernel_list: Sequence[str] | None = None,
     clock_control: Literal["base", "none"] = "none",
@@ -44,6 +50,7 @@ def kernel(
     thermal_wait: int | None = None,
     thermal_cont: int | None = None,
     thermal_timeout: int | None = None,
+    thermal_device: int | None = None,
     combine_kernel_metrics: Callable[[float, float], float] | None = None,
     output_prefix: str | None = None,
     output_csv: bool = False,
@@ -56,9 +63,14 @@ def kernel(
     *,
     configs: Iterable[Any] | None = None,
     runs: int = 1,
-    derive_metric: Callable[..., float | dict[str, float]] | None = None,
+    derive_metric: (
+        Callable[
+            ..., float | tuple[float, str] | Mapping[str, float | tuple[float, str]]
+        ]
+        | None
+    ) = None,
     normalize_against: str | None = None,
-    output: Literal["quiet", "progress", "verbose"] = "progress",
+    verbosity: VerbosityLevel = VerbosityLevel.INFO,
     metrics: Sequence[str] = ["gpu__time_duration.sum"],
     ignore_kernel_list: Sequence[str] | None = None,
     clock_control: Literal["base", "none"] = "none",
@@ -68,6 +80,7 @@ def kernel(
     thermal_wait: int | None = None,
     thermal_cont: int | None = None,
     thermal_timeout: int | None = None,
+    thermal_device: int | None = None,
     combine_kernel_metrics: Callable[[float, float], float] | None = None,
     output_prefix: str | None = None,
     output_csv: bool = False,
@@ -93,6 +106,13 @@ def kernel(
         - ``**kwargs``: Original function keyword arguments
         - Returns ``ProfileResults`` object containing profiling data
 
+    .. note::
+        Configs are passed to the decorated function as positional arguments.
+        Both positional and keyword-only parameters are supported in the function
+        signature. If the function has ``*args`` or ``**kwargs``, they are tolerated
+        but will always be empty during profiling. Parameters with default values
+        may be omitted from configs — missing values will be filled from the defaults.
+
 
     Parameters:
         configs: An iterable of configurations to run the function with. Each configuration can be either:
@@ -105,6 +125,10 @@ def kernel(
 
                    configs = [1, 2, 3, 4]
 
+            If configs provide fewer values than the function has parameters,
+            the remaining parameters must have default values, which will be used
+            automatically.
+
             If the configs are not provided at decoration time, they must be provided when calling the decorated function.
         runs:  Number of times each configuration should be executed.
         derive_metric:
@@ -115,13 +139,18 @@ def kernel(
             metrics. Return value can be either:
 
             - A single value (float/int): Will be added as a new metric with the function name as the metric name. For lambda functions, the metric name will be ``"<lambda>"``.
-            - A dictionary: Keys will be used as metric names, values as metric values.
+            - A tuple (value, unit): A single metric value with its unit specified. The value will be added with the function name as the metric name, and the unit will be stored in the ``Unit`` column of the dataframe. Example: ``(tflops_value, "TFLOPS")``.
+            - A dictionary: Keys will be used as metric names, values can be either:
+                - Scalar values (float/int): Metric values without units. ``np.nan`` will be added to the ``Unit`` column and a warning will be issued.
+                - Tuples (value, unit): Metric values with units specified. The unit will be stored in the ``Unit`` column of the dataframe. Example: ``{"TFLOPS": (tflops_value, "TFLOPS"), "ArithIntensity": (intensity_value, "FLOP/byte")}``.
 
             The parameter order requirements for the custom function:
 
             - First several arguments: Must exactly match the order of metrics declared in the @kernel decorator. These arguments will receive the actual measured values of those metrics.
             - Remaining arguments: Must exactly match the signature of the decorated function. In other words, the original function's parameters are passed in order.
 
+            **Note on units**: When units are not provided (returning scalar values instead of tuples), ``np.nan`` will be added to the ``Unit`` column in the dataframe and a warning will be issued. To avoid warnings and ensure proper unit tracking, return tuples ``(value, unit)`` for all derived metrics.
+
             See the examples for concrete use cases.
         normalize_against:
             Annotation name to normalize metrics against (computes current / baseline).
@@ -193,11 +222,22 @@ def kernel(
         thermal_timeout: Maximum wait time in seconds for GPU to cool down.
             Default: 180 seconds
 
-        output: Controls the verbosity level of the output.
+        thermal_device: CUDA device ordinal to monitor for thermal throttling.
+
+            If set, monitor that CUDA device. If ``None``, monitor the current
+            CUDA device context. Device numbering follows CUDA runtime ordinals and
+            honors ``CUDA_VISIBLE_DEVICES``.
+
+            Default: ``None``
 
-            - ``"quiet"``: Suppresses all output.
-            - ``"progress"``: Shows a progress bar along with details about profiling and data extraction progress.
-            - ``"verbose"``: Displays the progress bar, configuration-specific logs, and profiler logs.
+        verbosity: Controls the verbosity level of the output. Selecting level N
+            enables output at all levels with value <= N. Default: ``VerbosityLevel.INFO``.
+
+            - ``VerbosityLevel.SILENT``: Suppresses all output.
+            - ``VerbosityLevel.INFO``: Shows a progress bar, profiling completion messages,
+              and report file paths.
+            - ``VerbosityLevel.DEBUG``: Adds configuration-specific logs, the full NCU CLI
+              command, and enables NCU verbose output.
 
         output_prefix: When specified, all intermediate profiler files are created with this prefix.
             For example, if `output_prefix="/home/user/run1_"`, the profiler will generate:
@@ -221,6 +261,7 @@ def kernel(
                 - ``Annotation``: Name of the annotated region being profiled
                 - ``Value``: Raw metric values collected by the profiler
                 - ``Metric``: The metrics being collected (e.g., ``gpu__time_duration.sum``) and the metrics being derived
+                - ``Unit``: Unit of measurement for the metric value (e.g., ``ns`` for nanoseconds)
                 - ``Kernel``: Name of the GPU kernel(s) launched
                 - ``GPU``: GPU device name
                 - ``Host``: Host machine name
@@ -242,6 +283,7 @@ def kernel(
                 - ``RelativeStdDevPct``: Standard deviation as a percentage of the mean
                 - ``StableMeasurement``: Boolean indicating if the measurement is stable (low variance). The measurement is stable if ``RelativeStdDevPct`` < 2 % .
                 - ``Metric``: The metrics being collected and the metrics being derived
+                - ``Unit``: Unit of measurement for the metric value (e.g., ``ns`` for nanoseconds)
                 - ``Kernel``: Name of the GPU kernel(s) launched
                 - ``GPU``: GPU device name
                 - ``Host``: Host machine name
@@ -263,34 +305,25 @@ def kernel(
 
     def _create_profiler() -> collection.core.NsightProfiler:
         """Helper to create the profiler with the given settings."""
-        if output not in ("quiet", "progress", "verbose"):
-            raise ValueError("output must be 'quiet', 'progress' or 'verbose'")
-
-        output_progress = output == "progress" or output == "verbose"
-        output_detailed = output == "verbose"
-
         # Create the output paths needed for the ncu report, ncu logs and the CSVs
         prefix = output_prefix
-        if "NSPY_NCU_PROFILE" not in os.environ:
-            if prefix is None:
-                prefix = tempfile.mkdtemp(prefix="nspy_")
-                prefix = os.path.join(
-                    prefix, ""
-                )  # Adds a trailing forward/backward slash
-            else:
-                os.makedirs(os.path.dirname(prefix) or ".", exist_ok=True)
+        if prefix is None:
+            prefix = tempfile.mkdtemp(prefix="nspy_")
+            prefix = os.path.join(prefix, "")  # Adds a trailing forward/backward slash
+        else:
+            os.makedirs(os.path.dirname(prefix) or ".", exist_ok=True)
 
         settings = collection.core.ProfileSettings(
             configs=configs,
             runs=runs,
-            output_progress=output_progress,
-            output_detailed=output_detailed,
+            verbosity=verbosity,
             derive_metric=derive_metric,
             normalize_against=normalize_against,
             thermal_mode=thermal_mode,
             thermal_wait=thermal_wait,
             thermal_cont=thermal_cont,
             thermal_timeout=thermal_timeout,
+            thermal_device=thermal_device,
             output_prefix=prefix,
             output_csv=output_csv,
         )
@@ -451,30 +484,29 @@ def plot(
         def wrapper(*args: Any, **kwargs: Any) -> Any:
             result = func(*args, **kwargs)
 
-            if "NSPY_NCU_PROFILE" not in os.environ:
-                # Legalize the user-provided metric for plotting
-                legalized_metric = _legalize_metric(result, metric)
-
-                visualization.visualize(
-                    result.to_dataframe(),
-                    metric=legalized_metric,
-                    row_panels=row_panels,
-                    col_panels=col_panels,
-                    x_keys=x_keys,
-                    print_data=print_data,
-                    title=title,
-                    filename=filename,
-                    ylabel=ylabel or "",
-                    annotate_points=annotate_points,
-                    show_avg=show_avg,
-                    show_geomean=show_geomean,
-                    plot_type=plot_type,
-                    plot_width=plot_width,
-                    plot_height=plot_height,
-                    variant_fields=variant_fields,
-                    variant_annotations=variant_annotations,
-                    plot_callback=plot_callback,
-                )
+            # Legalize the user-provided metric for plotting
+            legalized_metric = _legalize_metric(result, metric)
+
+            visualization.visualize(
+                result.to_dataframe(),
+                metric=legalized_metric,
+                row_panels=row_panels,
+                col_panels=col_panels,
+                x_keys=x_keys,
+                print_data=print_data,
+                title=title,
+                filename=filename,
+                ylabel=ylabel or "",
+                annotate_points=annotate_points,
+                show_avg=show_avg,
+                show_geomean=show_geomean,
+                plot_type=plot_type,
+                plot_width=plot_width,
+                plot_height=plot_height,
+                variant_fields=variant_fields,
+                variant_annotations=variant_annotations,
+                plot_callback=plot_callback,
+            )
             return result
 
         return wrapper

nsight/annotation.py

@@ -129,6 +129,10 @@ class annotate(nvtx.annotate):  # type: ignore[misc]
         Nested annotations are currently not supported. However, since each
         annotation is expected to contain a single kernel launch by default,
         nested annotations should not be necessary in typical usage scenarios.
+        Entering and exiting the annotation context pushes and pops an NVTX
+        range, so calling ``nvtx.pop_range()`` inside the annotation context
+        without a corresponding push would pop the annotation context's own
+        range instead, resulting in incorrect profiling results.
 
     """
 

nsight/collection/core.py

@@ -11,12 +11,99 @@ import threading
 import time
 import warnings
 from collections.abc import Callable, Collection, Iterable, Sequence
-from typing import Any, List, Literal
+from typing import Any, List, Literal, Mapping
 
 import numpy as np
 import pandas as pd
 
 from nsight import annotation, exceptions, thermovision, transformation, utils
+from nsight.utils import VerbosityLevel
+
+
+def _get_regular_params(
+    sig: inspect.Signature,
+) -> list[inspect.Parameter]:
+    """Return the list of regular (non-variadic) parameters from a signature."""
+    return [
+        p
+        for p in sig.parameters.values()
+        if p.kind
+        not in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD)
+    ]
+
+
+def _count_params(
+    sig: inspect.Signature,
+) -> tuple[int, int]:
+    """Count (required, total) regular parameters in a signature.
+
+    Returns:
+        A (required_count, total_count) tuple. required_count excludes
+        parameters with defaults, total_count includes them.
+    """
+    params = _get_regular_params(sig)
+    required = sum(1 for p in params if p.default is inspect.Parameter.empty)
+    return required, len(params)
+
+
+def _pad_config_with_defaults(
+    sig: inspect.Signature, config: Sequence[Any]
+) -> tuple[Any, ...]:
+    """Pad a config tuple with default values for any missing trailing parameters.
+
+    If the config provides fewer values than the function has parameters, the
+    remaining parameters must have defaults, which are appended to the config.
+    This ensures the rest of the pipeline always sees full-length configs.
+
+    Args:
+        sig: The function's inspect.Signature.
+        config: The (possibly short) config tuple.
+
+    Returns:
+        A full-length config tuple with defaults filled in.
+    """
+    params = _get_regular_params(sig)
+    if len(config) == len(params):
+        return tuple(config)
+    padded = list(config)
+    for param in params[len(config) :]:
+        padded.append(param.default)
+    return tuple(padded)
+
+
+def _bind_config_to_signature(
+    sig: inspect.Signature, config: Sequence[Any]
+) -> tuple[list[Any], dict[str, Any]]:
+    """Split a config tuple into positional args and keyword-only kwargs.
+
+    Maps config values to function parameters in declaration order, separating
+    them into positional arguments (for POSITIONAL_OR_KEYWORD params) and
+    keyword arguments (for KEYWORD_ONLY params). VAR_POSITIONAL and VAR_KEYWORD
+    parameters are skipped. Parameters with defaults that are not covered by
+    the config are left for the function to fill in.
+
+    Args:
+        sig: The function's inspect.Signature.
+        config: The config tuple to bind.
+
+    Returns:
+        A (positional_args, keyword_args) tuple ready for func(*pos, **kw).
+    """
+    positional: list[Any] = []
+    keyword: dict[str, Any] = {}
+    config_iter = iter(config)
+    for param in sig.parameters.values():
+        if param.kind in (
+            inspect.Parameter.VAR_POSITIONAL,
+            inspect.Parameter.VAR_KEYWORD,
+        ):
+            continue
+        val = next(config_iter)
+        if param.kind == inspect.Parameter.KEYWORD_ONLY:
+            keyword[param.name] = val
+        else:
+            positional.append(val)
+    return positional, keyword
 
 
 def _sanitize_configs(
@@ -60,6 +147,10 @@ def _sanitize_configs(
         - For functions with no parameters, an empty config [()] is created automatically.
         - The function combines `args` and `kwargs` into a single list if `args` are provided.
         - The function assumes that `kwargs` keys are in the expected order when combining.
+        - Config values are mapped to parameters in declaration order. Both
+          regular and keyword-only parameters are supported. Parameters with
+          defaults may be omitted from configs. ``*args`` and ``**kwargs``
+          are tolerated but ignored.
     """
     if len(args) > 0:
         # We do not expect any configs in this case
@@ -76,8 +167,8 @@ def _sanitize_configs(
         if decorator_configs is None:
             # Check if function takes no arguments
             sig = inspect.signature(func)
-            expected_arg_count = len(sig.parameters)
-            if expected_arg_count == 0:
+            required_count, total_count = _count_params(sig)
+            if required_count == 0:
                 # For functions with no arguments, create a single empty config
                 # This allows calling the function without requiring explicit configs
                 configs = [()]
@@ -105,8 +196,8 @@ def _sanitize_configs(
 
         # If function takes exactly one argument, allow scalar configs
         sig = inspect.signature(func)
-        expected_arg_count = len(sig.parameters)
-        if expected_arg_count == 1:
+        required_count, total_count = _count_params(sig)
+        if total_count == 1:
             normalized_configs: list[Sequence[Any]] = []
             for config in configs:
                 if utils.is_scalar(config):
@@ -122,11 +213,21 @@ def _sanitize_configs(
             )
         first_config_arg_count = config_lengths[0]
 
-        # Validate that the number of args matches the number of function parameters
-        if first_config_arg_count != expected_arg_count:
-            raise exceptions.ProfilerException(
-                f"Configs have {first_config_arg_count} arguments, but function expects {expected_arg_count}"
-            )
+        # Validate that the number of args is between required and total parameters
+        if not (required_count <= first_config_arg_count <= total_count):
+            if required_count == total_count:
+                raise exceptions.ProfilerException(
+                    f"Configs have {first_config_arg_count} arguments, but function expects {total_count}"
+                )
+            else:
+                raise exceptions.ProfilerException(
+                    f"Configs have {first_config_arg_count} arguments, but function expects "
+                    f"between {required_count} and {total_count}"
+                )
+
+        # Pad configs with default values for any missing trailing parameters
+        if first_config_arg_count < total_count:
+            configs = [_pad_config_with_defaults(sig, config) for config in configs]
 
     return configs  # type: ignore[return-value]
 
@@ -135,15 +236,15 @@ def run_profile_session(
     func: Callable[..., None],
     configs: List[Sequence[Any]],
     runs: int,
-    output_progress: bool,
-    output_detailed: bool,
+    verbosity: VerbosityLevel,
     thermal_mode: Literal["auto", "manual", "off"],
     thermal_wait: int | None = None,
     thermal_cont: int | None = None,
     thermal_timeout: int | None = None,
+    thermal_device: int | None = None,
 ) -> None:
 
-    if output_progress:
+    if verbosity >= VerbosityLevel.INFO:
         print("")
         print("")
 
@@ -155,7 +256,8 @@ def run_profile_session(
             thermal_wait=thermal_wait,
             thermal_cont=thermal_cont,
             thermal_timeout=thermal_timeout,
-            verbose=output_detailed,
+            thermal_device=thermal_device,
+            verbose=verbosity >= VerbosityLevel.DEBUG,
         )
         thermovision_initialized = thermal_controller.init()
         if not thermovision_initialized:
@@ -170,21 +272,22 @@ def run_profile_session(
     bar_length = 100
     progress_time: float = 0
 
-    # overwrite flag: we do not overwrite when output mode is detailed
-    overwrite_output = not output_detailed
+    # overwrite flag: we do not overwrite when output mode is debug
+    overwrite_output = verbosity < VerbosityLevel.DEBUG
     show_return_type_warning = False
     config_lengths: list[int] = list()
 
     for c in configs:
-        expected_arg_count = len(inspect.signature(func).parameters)
+        sig = inspect.signature(func)
+        required_count, total_count = _count_params(sig)
 
         # Handle scalar values
-        if expected_arg_count == 1:
+        if total_count == 1:
             if utils.is_scalar(c):
                 c = (c,)
 
         # Check if func supports the input configs
-        if expected_arg_count != len(c):
+        if not (required_count <= len(c) <= total_count):
             raise exceptions.ProfilerException(
                 f"Function '{func.__name__}' does not support the input configuration"
             )
@@ -199,7 +302,7 @@ def run_profile_session(
 
         curr_config += 1
 
-        if output_progress:
+        if verbosity >= VerbosityLevel.INFO:
             utils.print_config(total_configs, curr_config, c, overwrite_output)
 
         for i in range(runs):
@@ -211,8 +314,10 @@ def run_profile_session(
             # Clear active annotations before each run
             annotation.clear_active_annotations()
 
-            # Run the function with the config
-            result = func(*c)  # type: ignore[func-returns-value]
+            # Run the function with the config, splitting into positional
+            # and keyword-only args based on the function signature
+            pos_args, kw_args = _bind_config_to_signature(sig, c)
+            result = func(*pos_args, **kw_args)  # type: ignore[func-returns-value]
             if result is not None:
                 show_return_type_warning = True
 
@@ -225,7 +330,7 @@ def run_profile_session(
 
             # Update time estimates every half second
             if time.time() - progress_time > 0.5:
-                if output_progress:
+                if verbosity >= VerbosityLevel.INFO:
                     utils.print_progress_bar(
                         total_runs,
                         curr_run,
@@ -236,7 +341,7 @@ def run_profile_session(
                 progress_time = time.time()
 
     # Update progress bar at end so it shows 100%
-    if output_progress:
+    if verbosity >= VerbosityLevel.INFO:
         utils.print_progress_bar(
             total_runs,
             curr_run,
@@ -274,17 +379,18 @@ class ProfileSettings:
     runs: int
     """Number of times each configuration should be executed."""
 
-    output_progress: bool
-    """
-    Will display a progress bar on stdout during profiling
-    """
-
-    output_detailed: bool
+    verbosity: VerbosityLevel
     """
-    Will display a progress bar, detailed output for each config along with the profiler logs
+    Controls verbosity of output. SILENT suppresses all output, INFO shows progress bar,
+    DEBUG shows progress bar plus per-config logs and profiler output.
     """
 
-    derive_metric: Callable[..., float | dict[str, float]] | None
+    derive_metric: (
+        Callable[
+            ..., float | tuple[float, str] | Mapping[str, float | tuple[float, str]]
+        ]
+        | None
+    )
     """
     A function to transform the collected metrics.
     This can be used to compute derived metrics like TFLOPs that cannot
@@ -350,6 +456,16 @@ class ProfileSettings:
     If None, uses default value (180 seconds).
     """
 
+    thermal_device: int | None
+    """
+    CUDA device ordinal to monitor for thermal throttling.
+
+    If set, monitor that CUDA device. If None, monitor the current CUDA device
+    context.
+    Device numbering follows CUDA runtime ordinals and honors
+    ``CUDA_VISIBLE_DEVICES``.
+    """
+
     output_prefix: str | None
     """
     All intermediate profiler files are created with this prefix
@@ -399,6 +515,7 @@ class ProfileResults:
                 - ``RelativeStdDevPct``: Standard deviation as a percentage of the mean
                 - ``StableMeasurement``: Boolean indicating if the measurement is stable (low variance). The measurement is stable if ``RelativeStdDevPct`` < 2 % .
                 - ``Metric``: The metrics being collected and the metrics being derived
+                - ``Unit``: Unit of measurement for the metric value (e.g., ``ns`` for nanoseconds)
                 - ``Kernel``: Name of the GPU kernel(s) launched
                 - ``GPU``: GPU device name
                 - ``Host``: Host machine name
@@ -487,7 +604,7 @@ class NsightProfiler:
                     raw_df,
                     func,
                     self.settings.normalize_against,
-                    self.settings.output_progress,
+                    self.settings.verbosity,
                 )
 
                 # Save to CSV if enabled
@@ -508,7 +625,7 @@ class NsightProfiler:
                         index=False,
                     )
 
-                    if self.settings.output_progress:
+                    if self.settings.verbosity >= VerbosityLevel.INFO:
                         print(
                             f"[NSIGHT-PYTHON] Refer to {raw_csv_path} for the raw profiling data"
                         )