0
# Code Range Annotation
1

2
Annotate code sections with decorators, context managers, or manual push/pop functions to create hierarchical performance traces in NVIDIA Nsight Systems. Supports custom messages, colors, domains, categories, and payloads for detailed profiling visualization.
3

4
## Capabilities
5

6
### Decorator Annotation
7

8
Use `@nvtx.annotate` to automatically annotate entire functions with NVTX ranges. The decorator handles range lifecycle automatically and provides exception safety.
9

10
```python { .api }
11
@nvtx.annotate(message: str = None, color: Union[str, int] = None,
12
               domain: str = None, category: Union[str, int] = None,
13
               payload: Union[int, float] = None)
14
def function():
15
    """
16
    Decorator for automatic function annotation.
17
    
18
    Parameters:
19
    - message: Function name used if None
20
    - color: Color for visualization (default varies by usage)
21
    - domain: Domain name (default "NVTX")
22
    - category: Category name or ID for grouping
23
    - payload: Numeric value associated with annotation
24
    """
25
```
26

27
**Usage Example:**
28

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

33
@nvtx.annotate(color="blue", domain="my_app")
34
def process_data():
35
    # Function name "process_data" used as message
36
    time.sleep(0.1)
37

38
@nvtx.annotate("custom_name", color="red", category="processing")
39
def compute():
40
    time.sleep(0.2)
41
```
42

43
### Context Manager Annotation
44

45
Use `nvtx.annotate` as a context manager to annotate specific code blocks with automatic range management and exception safety.
46

47
```python { .api }
48
with nvtx.annotate(message: str = None, color: Union[str, int] = None,
49
                   domain: str = None, category: Union[str, int] = None,
50
                   payload: Union[int, float] = None):
51
    """
52
    Context manager for code block annotation.
53
    
54
    Parameters:
55
    - message: Description of annotated code block (default empty string)
56
    - color: Color for visualization (default varies by usage)
57
    - domain: Domain name (default "NVTX")
58
    - category: Category name or ID for grouping
59
    - payload: Numeric value associated with annotation
60
    """
61
```
62

63
**Usage Example:**
64

65
```python
66
import nvtx
67
import time
68

69
# Annotate initialization phase
70
with nvtx.annotate("initialization", color="green", domain="startup"):
71
    config = load_config()
72
    setup_logging()
73

74
# Nested annotations for detailed profiling
75
with nvtx.annotate("data_processing", color="blue"):
76
    for i in range(100):
77
        with nvtx.annotate("process_item", color="yellow", payload=i):
78
            process_item(data[i])
79
```
80

81
### Manual Range Control
82

83
Use `push_range` and `pop_range` for explicit control over annotation ranges when decorators or context managers are not suitable.
84

85
```python { .api }
86
def push_range(message: str = None, color: Union[str, int] = "blue",
87
               domain: str = None, category: Union[str, int] = None,
88
               payload: Union[int, float] = None):
89
    """
90
    Mark the beginning of a code range.
91
    
92
    Parameters:
93
    - message: Description of the code range
94
    - color: Color for visualization (default "blue")
95
    - domain: Domain name (default "NVTX")
96
    - category: Category name or ID for grouping
97
    - payload: Numeric value associated with range
98
    """
99

100
def pop_range(domain: str = None):
101
    """
102
    Mark the end of a code range started with push_range.
103
    
104
    Parameters:
105
    - domain: Domain name (default "NVTX", must match push_range call)
106
    """
107
```
108

109
**Usage Example:**
110

111
```python
112
import nvtx
113
import time
114

115
# Manual range control for complex logic
116
def complex_algorithm():
117
    nvtx.push_range("setup_phase", color="green")
118
    setup_data()
119
    nvtx.pop_range()
120
    
121
    for iteration in range(10):
122
        nvtx.push_range("iteration", color="blue", payload=iteration)
123
        if should_break():
124
            nvtx.pop_range()  # Important: always pop before breaking
125
            break
126
        process_iteration()
127
        nvtx.pop_range()
128
    
129
    nvtx.push_range("cleanup", color="red")
130
    cleanup_resources()
131
    nvtx.pop_range()
132
```
133

134
## Parameter Details
135

136
### Message Parameter
137

138
- **Type**: `Optional[str]`
139
- **Decorator**: Defaults to decorated function name
140
- **Context Manager**: Defaults to empty string
141
- **Manual**: Defaults to None
142
- **Caching**: Messages are cached as Registered Strings for performance
143
- **Memory**: Caching very large numbers of unique messages may increase memory usage
144

145
### Color Parameter
146

147
- **Type**: `Optional[Union[str, int]]`
148
- **Built-in Colors**: "green", "blue", "yellow", "purple", "rapids", "cyan", "red", "white", "darkgreen", "orange"
149
- **Matplotlib Colors**: Any matplotlib color name (requires matplotlib installation)
150
- **Hex Colors**: Integer values in ARGB format (e.g., 0xFF0000 for red)
151
- **Default**: Varies by function (typically "blue" for manual functions)
152

153
### Domain Parameter
154

155
- **Type**: `Optional[str]`
156
- **Default**: "NVTX"
157
- **Purpose**: Groups annotations for organization and performance
158
- **Performance**: Domain-specific API provides better performance for high-frequency annotations
159

160
### Category Parameter
161

162
- **Type**: `Optional[Union[str, int]]`
163
- **String**: Automatically assigned numeric ID on first use
164
- **Integer**: Direct category ID
165
- **Purpose**: Further sub-grouping within domains
166
- **Default**: No category association
167

168
### Payload Parameter
169

170
- **Type**: `Optional[Union[int, float]]`
171
- **Purpose**: Associate numeric data with annotations for analysis
172
- **Types**: Supports both integer and floating-point values
173
- **Usage**: Iteration counts, sizes, timing values, etc.
174

175
## Error Handling
176

177
The annotation functions provide robust error handling:
178

179
- **Exception Safety**: Decorator and context manager automatically clean up ranges even when exceptions occur
180
- **NVTX Disabled**: All functions become no-ops when `NVTX_DISABLE` environment variable is set
181
- **Invalid Colors**: Raises `TypeError` for unsupported colors when matplotlib is not available
182
- **Domain Mismatch**: `pop_range` domain parameter must match corresponding `push_range` call
183

184
## Performance Considerations
185

186
- **Message Caching**: Repeated messages are cached as Registered Strings for efficiency
187
- **Domain API**: Use domain-specific API (`Domain.push_range`, `Domain.pop_range`) for better performance in high-frequency scenarios
188
- **Overhead**: Zero overhead when NVTX is disabled via environment variable
189
- **Nesting**: Deep annotation nesting is supported but may impact profiler visualization