Add documentation for the nsight.activate, nsight.deactivate APIs and

multiple profiling backends

Signed-off-by: Alok Joshi <aljoshi@nvidia.com>

Author: Alok-Joshi

docs/source/index.rst

@@ -47,6 +47,7 @@ Welcome to the Nsight Python documentation!
 
    analyze
    annotation
+   tools
 
 .. toctree::
    :hidden:

docs/source/installation/installation_from_pypi.rst

@@ -35,7 +35,12 @@ For CUDA Toolkit 13:
 
     pip install nsight-python[cu13]
 
-.. note::
-   The ``[cu12]`` and ``[cu13]`` extras install the ``cuda-core`` package, which is only required if you plan to use ``ignore_failures=True`` in ``nsight.annotate``. 
-   All other features of Nsight Python work without this dependency.
+Optional: Installing with CUPTI Support
+----------------------------------------
 
+If you want to use the experimental CUPTI backend with ``nsight.analyze.kernel``, you need to install the ``cupti-python`` package.
+This is an optional dependency that enables low-overhead collection of kernel time durations.
+
+.. code-block:: bash
+
+    pip install nsight-python[cupti]

docs/source/installation/runtime_requirements.rst

@@ -6,6 +6,8 @@ Runtime Requirements
 
 * **NVIDIA Nsight Compute from CUDA Toolkit 13.3 Update 1 or later**: nsight-python uses the NVIDIA Nsight Compute CLI (ncu 2026.2.1+). Ensure ``ncu`` is installed and available on the system path.
 
+* **NVIDIA CUPTI**: The :ref:`CUPTI backend <tools-cupti>` requires the CUPTI Library from CUDA 13.4 or greater. Installing Nsight Python with the ``cupti`` extra (see :doc:`installation_from_pypi`) installs ``nvidia-cuda-cupti``, which provides this library. See `CUPTI Compatibility and Requirements <https://docs.nvidia.com/cupti/main/main.html#cupti-compatibility-and-requirements>`_ for driver compatibility and other setup requirements.
+
 Import Ordering
 ---------------
 
@@ -15,4 +17,6 @@ Import Ordering
 
   **Recommendation**: Place ``import nsight`` at the top of your script, before all CUDA-related imports and calls.
 
+  This ordering matters because ``import nsight`` activates NVIDIA Nsight Compute; see :doc:`/tools`.
+
 * **Any NVTX API calls**: nsight-python updates ``NVTX_INJECTION64_PATH`` at import time. Any NVTX usage before ``import nsight`` will cause NVTX annotation ranges to be missed and profiling results to be incomplete.

docs/source/tools.rst

@@ -0,0 +1,129 @@
+.. SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+.. SPDX-License-Identifier: Apache-2.0
+
+Tools
+=====
+
+Nsight Python collects its data through an underlying NVIDIA tool. Only one tool
+can be active at a time, and :func:`nsight.activate` selects and loads it.
+
+.. autofunction:: nsight.activate
+
+.. autofunction:: nsight.deactivate
+
+.. autofunction:: nsight.get_active_tool
+
+.. autoclass:: nsight.Tool
+
+Supported tools
+---------------
+
+NVIDIA Nsight Compute
+^^^^^^^^^^^^^^^^^^^^^
+
+:attr:`nsight.Tool.NCU` profiles individual kernels with the NVIDIA Nsight
+Compute CLI. It is the default tool for ``@nsight.analyze.kernel``.
+
+Activation
+""""""""""
+
+NVIDIA Nsight Compute's injection library has to be loaded before CUDA is
+initialized. It is loaded in one of three ways.
+
+* **At import, by default.** ``import nsight`` activates NCU.
+* **Explicitly, for control over the timing.** Ensure the environment variable
+  ``NSPY_NCU_INIT_AT_IMPORT`` is set to ``0`` before ``nsight`` is imported,
+  then activate NCU where it suits you. Explicit activation also surfaces setup
+  errors at that point.
+
+  .. code-block:: python
+
+     import os
+
+     os.environ["NSPY_NCU_INIT_AT_IMPORT"] = "0"
+
+     import nsight
+
+     nsight.activate(nsight.Tool.NCU)
+
+* **Lazily, on first use.** Under ``NSPY_NCU_INIT_AT_IMPORT=0``, the first call
+  to a function decorated with ``@nsight.analyze.kernel`` loads the library.
+  Ensure the first decorated call comes before any code that initializes CUDA.
+
+Limitations
+"""""""""""
+
+**Deactivation.** :func:`~nsight.deactivate` is not supported. The injection
+library cannot be unloaded, so NCU stays loaded for the lifetime of the process
+and remains the active tool once activated.
+
+.. _tools-cupti:
+
+NVIDIA CUPTI (experimental)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:attr:`nsight.Tool.CUPTI` is an opt-in, low-overhead alternative for collecting
+kernel time durations, measured using CUPTI's Activity API.
+
+Activation
+""""""""""
+
+To activate CUPTI, ensure the environment variable
+``NSPY_NCU_INIT_AT_IMPORT`` is set to ``0`` before ``nsight`` is imported:
+
+.. code-block:: python
+
+   import os
+
+   os.environ["NSPY_NCU_INIT_AT_IMPORT"] = "0"
+
+   import torch
+
+   import nsight
+
+   nsight.activate(nsight.Tool.CUPTI)
+
+
+   @nsight.analyze.kernel
+   def benchmark_matmul(n):
+       a = torch.randn(n, n, device="cuda")
+       b = torch.randn(n, n, device="cuda")
+
+       with nsight.annotate("matmul"):
+           c = a @ b
+
+
+   if __name__ == "__main__":
+       result = benchmark_matmul(1024)
+       print(result.to_dataframe())
+
+       nsight.deactivate()
+
+Activating CUPTI updates ``NVTX_INJECTION64_PATH``. Any NVTX usage before
+``nsight.activate(nsight.Tool.CUPTI)`` will cause NVTX annotation ranges to be
+missed and profiling results to be incomplete.
+
+CUPTI may be activated either before or after CUDA is initialized.
+
+Limitations
+"""""""""""
+
+**Platform.** Linux only for now.
+
+**Metrics.** Only ``"gpu__time_duration.sum"`` is supported. CUPTI measures it
+by recording kernel start and end timestamps from CUPTI activity records
+(``CONCURRENT_KERNEL``) and computing ``end - start`` per kernel launch.
+
+**Replay mode.** Neither kernel replay nor range replay is supported. CUPTI
+activity records capture one execution of each kernel in a single pass, so no
+replay mechanism is engaged and ``replay_mode`` is ignored.
+
+**Clock and cache control.** ``clock_control`` and ``cache_control`` are
+ignored. Clocks are not locked and caches are not flushed between runs, which
+may affect measurement stability.
+
+**Device synchronization.** The whole device is synchronized once after the
+profiling session, before the activity buffers are flushed, because a kernel's
+activity record is only written when the kernel completes. Work that the
+profiled function left running asynchronously is therefore waited for before
+profiling returns.

nsight/analyze.py

@@ -109,22 +109,6 @@ def kernel(
     """
     A decorator that collects profiling data from GPU kernels.
 
-    **Tool selection**
-
-    By default, ``@nsight.analyze.kernel`` profiles using NVIDIA Nsight Compute
-    (NCU). NCU's injection library is loaded automatically on the first call to
-    a decorated function, but it **must** be loaded before CUDA is initialized.
-    This means the first decorated function call must occur before any CUDA-initializing code.
-    To guarantee early loading and avoid this constraint, call  ``nsight.activate(nsight.Tool.NCU)``
-    explicitly at the very top of your script, before any CUDA imports.
-
-    CUPTI is also supported *(experimental)* for lightweight collection of
-    ``"gpu__time_duration.sum"`` using kernel timestamps, without launching
-    ``ncu``. To enable it, call ``nsight.activate(nsight.Tool.CUPTI)`` before
-    profiling. CUPTI does not have the CUDA initialization ordering constraint.
-    See :class:`~nsight.collection.cupti.CUPTICollector` for supported metrics
-    and limitations.
-
     Can be used with or without parentheses:
         - ``@nsight.analyze.kernel`` (no parentheses)
         - ``@nsight.analyze.kernel()`` (empty parentheses)
@@ -155,6 +139,14 @@ def wrapped_function(*args, configs=None, **kwargs) -> ProfileResults
         but will always be empty during profiling. Parameters with default values
         may be omitted from configs — missing values will be filled from the defaults.
 
+    Profiling uses NVIDIA Nsight Compute by default. Activating it is automatic
+    -- it happens during ``import nsight`` -- and needs no attention from you.
+    For more control over when NVIDIA Nsight Compute is loaded, see the
+    :doc:`/tools` page.
+
+    ``@nsight.analyze.kernel`` supports collection of
+    ``"gpu__time_duration.sum"`` via the low-overhead, experimental CUPTI
+    backend. See the :doc:`/tools` page for how to enable it.
 
     Parameters:
         configs: An iterable of configurations to run the function with. Each configuration can be either:
@@ -218,20 +210,26 @@ def wrapped_function(*args, configs=None, **kwargs) -> ProfileResults
             Default: ``"none"``
 
             Refer the `NVIDIA Nsight Compute documentation on Clock Control <https://docs.nvidia.com/nsight-compute/ProfilingGuide/index.html#clock-control>`_ for more details.
+
+            Ignored when the CUPTI backend is active.
         cache_control: Control the behavior of the GPU caches during profiling. Allowed values:
 
             - ``"all"``: All GPU caches are flushed before each kernel replay iteration during profiling. While metric values in the execution environment of the application might be slightly different without invalidating the caches, this mode offers the most reproducible metric results across the replay passes and also across multiple runs of the target application.
             - ``"none"``: No GPU caches are flushed during profiling. This can improve performance and better replicates the application behavior if only a single kernel replay pass is necessary for metric collection. However, some metric results will vary depending on prior GPU work, and between replay iterations. This can lead to inconsistent and out-of-bounds metric values.
 
             Default: ``"all"``
 
+            Ignored when the CUPTI backend is active.
+
         replay_mode: Mechanism used for replaying a kernel launch multiple times to collect selected metrics. Allowed values:
 
             - ``"kernel"``:  Replay individual kernel launches  during the execution of the application.
             - ``"range"``: Replay range of  kernel launches during the execution of the application. Ranges are defined using nsight.annotate.
 
             Default: ``"kernel"``
 
+            Ignored when the CUPTI backend is active.
+
         thermal_mode: Controls GPU thermal management mode. Default: ``"auto"``
 
             Monitors GPU thermal headroom (T.Limit) and pauses profiling when GPU gets

nsight/collection/cupti.py

@@ -214,28 +214,9 @@ class CUPTICollector(core.NsightCollector):
     Experimental CUPTI-based collector for Nsight Python.
 
     Uses CUPTI activity records to measure kernel durations directly, without
-    launching ``ncu``. This makes it lower-overhead than the NCU collector but
-    comes with the following limitations:
-
-    **Supported metrics:** Only ``"gpu__time_duration.sum"`` is supported. CUPTI
-    measures this by recording kernel start and end timestamps from CUPTI activity
-    records (``CONCURRENT_KERNEL``), computing ``end - start`` per kernel launch.
-
-    **Replay mode:** Neither kernel replay nor range replay is supported. CUPTI
-    activity records capture one execution of each kernel in a single pass; no
-    replay mechanism is engaged.
-
-    **Clock and cache control:** ``clock_control`` and ``cache_control`` are not
-    supported. Clocks are not locked and caches are not flushed between runs,
-    which may affect measurement stability. Use :attr:`ProfileSettings.runs` with
-    a sufficient number of repetitions and check ``StableMeasurement`` in the
-    output to detect high variance.
-
-    .. note::
-        The whole device is synchronized once after the profiling session, before
-        the activity buffers are flushed, because a kernel's activity record is
-        only written when the kernel completes. Work the profiled function left
-        running asynchronously is therefore waited for before profiling returns.
+    launching ``ncu``. This makes it lower-overhead than the NCU collector, at
+    the cost of supporting fewer metrics and settings. See the :doc:`/tools`
+    page for the supported metrics and limitations.
 
     Args:
         metrics: Must be ``["gpu__time_duration.sum"]``.

nsight/thermovision.py

@@ -210,15 +210,19 @@ def throttle_guard(self) -> None:
         Thermal headroom = temperature margin before GPU starts throttling.
 
         Operates in two modes:
+
         - Auto mode: Automatically adjusts thermal_cont based on workload
         - Manual mode: Uses user-provided thresholds without adaptation
 
         Adaptive Algorithm (in auto mode):
+
         1. When thermal headroom reaches thermal_cont after cooling, start counting iterations
         2. Run kernel as headroom drops from thermal_cont toward thermal_wait
         3. When headroom drops below thermal_wait, analyze iteration count:
+
            - Few iterations (<TARGET_MIN_ITERATIONS): GPU heats quickly → increase thermal_cont (cool more)
            - Many iterations (>TARGET_MAX_ITERATIONS): GPU heats slowly → decrease thermal_cont (cool less)
+
         4. Wait until GPU cools back to thermal_cont, then repeat
         """
         self._refresh_device_for_current_cuda_context()

nsight/tools_manager.py

@@ -20,30 +20,22 @@ class Tool(str, enum.Enum):
 def activate(tool: Tool) -> None:
     """Select and load ``tool`` as the active tool for this process.
 
-    Only one tool is active at a time. The first call loads the tool; calling
+    Only one tool can be active at a time. The first call loads the tool; calling
     again with the *same* tool is a no-op. Calling with a *different* tool while
     one is already active raises, because the tools are mutually exclusive.
 
-    For :attr:`Tool.NCU` in particular, this **must** be called before CUDA is
-    initialized otherwise the NVIDIA Nsight Compute injection cannot attach.
+    Each tool has its own prerequisites and its own constraints on when it may
+    be activated. See the :doc:`/tools` page for the tool you are selecting.
 
     Args:
-        tool: The tool to activate. See :class:`Tool`.
+        tool: The tool to activate.
 
     Raises:
         ValueError: If ``tool`` is not a :class:`Tool`.
         RuntimeError: If a different, incompatible tool is already active.
-        NCUNotAvailableError: If :attr:`Tool.NCU` was selected but the ``ncu``
-            CLI is not on ``$PATH``.
         ProfilerException: If the selected tool fails to load (wrong version,
-            injection library missing, etc.).
-
-    Example:
-        >>> import nsight
-        >>> nsight.activate(nsight.Tool.NCU)   # before any CUDA use
-        >>> @nsight.analyze.kernel
-        ... def matmul(n: int) -> None:
-        ...     ...
+            injection library missing, etc.). A tool whose prerequisites are
+            missing may raise its own exception type instead.
     """
     global _active_tool
     if not isinstance(tool, Tool):
@@ -70,10 +62,11 @@ def deactivate() -> None:
     Stops and tears down the tool :func:`activate` last activated. It is a
     no-op if no tool is active.
 
-    Not every tool can be torn down. NVIDIA Nsight Compute cannot: it stays
-    loaded for the lifetime of the process, so it also stays the active tool and
-    this call is a no-op that warns rather than clearing the selection. A
-    different tool therefore cannot be activated afterwards.
+    Not every tool can be torn down. A tool that cannot be stopped stays loaded
+    for the lifetime of the process, so it also stays the active tool and this
+    call is a no-op that warns rather than clearing the selection; no other tool
+    can be activated afterwards. See the :doc:`/tools` page for which tools this
+    applies to.
 
     Raises:
         ProfilerException: If tearing down the active tool fails.