0
# NVTX
1

2
Python code annotation library for NVIDIA Tools Extension that enables developers to add custom annotations, ranges, and markers to their Python code for profiling and performance analysis with NVIDIA Nsight Systems. The library provides decorators, context managers, and manual functions for easy integration with NVIDIA's profiling ecosystem.
3

4
## Package Information
5

6
- **Package Name**: nvtx
7
- **Language**: Python
8
- **Installation**: `pip install nvtx` or `conda install -c conda-forge nvtx`
9

10
## Core Imports
11

12
```python
13
import nvtx
14
```
15

16
For direct access to specific functions:
17

18
```python
19
from nvtx import annotate, enabled, mark, push_range, pop_range, start_range, end_range, get_domain, Domain, Profile
20
```
21

22
For type annotations:
23

24
```python
25
from typing import Union, Optional, Tuple, Any
26
```
27

28
## Basic Usage
29

30
```python
31
import nvtx
32
import time
33

34
# Using as a decorator
35
@nvtx.annotate(color="blue")
36
def my_function():
37
    for i in range(5):
38
        with nvtx.annotate("my_loop", color="red"):
39
            time.sleep(0.1)
40

41
# Using context manager
42
with nvtx.annotate("initialization", color="green"):
43
    data = initialize_data()
44

45
# Manual range control
46
nvtx.push_range("processing", color="yellow")
47
process_data(data)
48
nvtx.pop_range()
49

50
# Instantaneous markers
51
nvtx.mark("checkpoint", color="purple")
52

53
my_function()
54
```
55

56
## Architecture
57

58
NVTX provides multiple annotation approaches optimized for different use cases:
59

60
- **High-level API**: Global functions (`nvtx.annotate`, `nvtx.mark`) for simple usage with automatic domain management
61
- **Domain-specific API**: Domain objects for better performance and organization when creating many annotations
62
- **Automatic profiling**: Profile-based annotation of all function calls with configurable detail levels
63
- **Cython bindings**: Low-level C extension interface for optimal performance in performance-critical code
64

65
The library automatically handles NVTX_DISABLE environment variable and gracefully falls back to no-op implementations for zero overhead when profiling is disabled.
66

67
## Capabilities
68

69
### Code Range Annotation
70

71
Annotate code sections with decorators, context managers, or manual push/pop functions. Supports custom messages, colors, domains, categories, and payloads for detailed profiling visualization.
72

73
```python { .api }
74
@nvtx.annotate(message: str = None, color: Union[str, int] = None, 
75
               domain: str = None, category: Union[str, int] = None, 
76
               payload: Union[int, float] = None)
77
def function(): ...
78

79
with nvtx.annotate(message: str = None, color: Union[str, int] = None,
80
                   domain: str = None, category: Union[str, int] = None,
81
                   payload: Union[int, float] = None): ...
82

83
def push_range(message: str = None, color: Union[str, int] = "blue",
84
               domain: str = None, category: Union[str, int] = None,
85
               payload: Union[int, float] = None): ...
86

87
def pop_range(domain: str = None): ...
88
```
89

90
[Code Range Annotation](./annotation.md)
91

92
### Instantaneous Events and Process Ranges
93

94
Mark specific points in execution and create cross-process or cross-thread ranges that can span multiple function calls.
95

96
```python { .api }
97
def mark(message: str = None, color: Union[str, int] = "blue",
98
         domain: str = None, category: Union[str, int] = None,
99
         payload: Union[int, float] = None): ...
100

101
def start_range(message: str = None, color: Union[str, int] = None,
102
                domain: str = None, category: Union[str, int] = None,
103
                payload: Union[int, float] = None) -> Optional[Tuple[int, int]]: ...
104

105
def end_range(range_id: Optional[Tuple[int, int]]): ...
106
```
107

108
[Events and Process Ranges](./events-ranges.md)
109

110
### Domain Management
111

112
Create and manage custom domains for organizing annotations and achieving better performance through domain-specific API usage.
113

114
```python { .api }
115
def get_domain(name: str = None) -> Union[Domain, DummyDomain]: ...
116

117
class Domain:
118
    def get_registered_string(self, string: str) -> RegisteredString: ...
119
    def get_category_id(self, name: str) -> int: ...
120
    def get_event_attributes(self, message: str = None, color: Union[str, int] = None,
121
                           category: Union[str, int] = None, 
122
                           payload: Union[int, float] = None) -> EventAttributes: ...
123
    def mark(self, attributes: EventAttributes): ...
124
    def push_range(self, attributes: EventAttributes): ...
125
    def pop_range(self): ...
126
    def start_range(self, attributes: EventAttributes) -> int: ...
127
    def end_range(self, range_id: int): ...
128
```
129

130
[Domain Management](./domains.md)
131

132
### Automatic Profiling
133

134
Automatically annotate all function calls in your program with configurable detail levels, including line numbers and C function support.
135

136
```python { .api }
137
class Profile:
138
    def __init__(self, linenos: bool = True, annotate_cfuncs: bool = True): ...
139
    def enable(self): ...
140
    def disable(self): ...
141
```
142

143
[Automatic Profiling](./profiling.md)
144

145
## Utility Functions
146

147
### Status and Color Support
148

149
```python { .api }
150
def enabled() -> bool: ...
151
```
152

153
The library includes built-in color support for common colors and matplotlib integration:
154

155
- Built-in colors: "green", "blue", "yellow", "purple", "rapids", "cyan", "red", "white", "darkgreen", "orange"
156
- Matplotlib colors: Any matplotlib color name when matplotlib is installed
157
- Hex colors: Direct integer color values in ARGB format (e.g., 0xFF0000FF for blue, 0xFFFF0000 for red)
158

159
## Types
160

161
```python { .api }
162
class EventAttributes:
163
    """Event attributes for NVTX annotations."""
164
    message: RegisteredString
165
    color: Union[str, int]
166
    category: int
167
    payload: Union[int, float]
168

169
class RegisteredString:
170
    """Registered string handle for efficient reuse."""
171
    string: str
172
    domain: Domain
173
    handle: StringHandle
174

175
class StringHandle:
176
    """Low-level string handle for C API interaction."""
177
    c_obj: Any  # C object handle
178

179
class DummyDomain:
180
    """No-op domain replacement when NVTX is disabled."""
181
    def get_registered_string(self, string: str): ...
182
    def get_category_id(self, name: str): ...
183
    def get_event_attributes(self, message: str = None, color: Union[str, int] = None,
184
                           category: Union[str, int] = None, 
185
                           payload: Union[int, float] = None): ...
186
    def mark(self, attributes: EventAttributes): ...
187
    def push_range(self, attributes: EventAttributes): ...
188
    def pop_range(self): ...
189
    def start_range(self, attributes: EventAttributes) -> int: ...
190
    def end_range(self, range_id: int): ...
191
```