API Reference#

Annotate code ranges using a context manager or a decorator.

Parameters:

message – A message associated with the annotated code range. When used as a decorator, defaults to the decorated function name. When used as a context manager, defaults to the empty string. Messages are cached and are registered as Registered Strings in NVTX. Caching a very large number of messages may lead to increased memory usage.
color – A color associated with the annotated code range. Supports matplotlib colors if it is available.
domain – A string specifying the domain under which the code range is scoped. The default domain is named “NVTX”.
category – A string or an integer specifying the category within the domain under which the code range is scoped. If unspecified, the code range is not associated with a category.
payload –
A value associated with this event. Using payloads provides a separation between the message and the data of the event, which is often useful for analysis.

Note

payloads of type other than int or float requires NumPy to be installed (not installed with nvtx package).

Examples

>>> import nvtx
>>> import time

Using a decorator:

>>> @nvtx.annotate(color="red", domain="my_domain"):    # `message` defaults to "func"
... def func():
...     time.sleep(0.1)

Using a context manager:

>>> with nvtx.annotate("my_code_range", color="blue"):
...    time.sleep(10)

Mark the beginning of a code range.

Parameters:

message – A message associated with the annotated code range. Messages are cached and are registered as Registered Strings in NVTX. Caching a very large number of messages may lead to increased memory usage.
color – A color associated with the annotated code range. Supports matplotlib colors if it is available.
domain – Name of a domain under which the code range is scoped. The default domain name is “NVTX”.
category – A string or an integer specifying the category within the domain under which the code range is scoped. If unspecified, the code range is not associated with a category.
payload –
A value associated with this event. Using payloads provides a separation between the message and the data of the event, which is often useful for analysis.

Note

payloads of type other than int or float requires NumPy to be installed (not installed with nvtx package).

Notes

When applicable, prefer to use annotate. Otherwise, for best performance, use Domain.push_range() and Domain.pop_range().

Examples

>>> import time
>>> import nvtx
>>> nvtx.push_range("my_code_range", domain="my_domain")
>>> time.sleep(1)
>>> nvtx.pop_range(domain="my_domain")

nvtx.pop_range(domain: str | None = None)#

Mark the end of a code range that was started with push_range().

Parameters:: domain – The domain under which the code range is scoped. The default domain is “NVTX”.

Mark the beginning of a process range.

Parameters:

message – A message associated with the range. Messages are cached and are registered as Registered Strings in NVTX. Caching a very large number of messages may lead to increased memory usage.
color – A color associated with the range. Supports matplotlib colors if it is available.
domain – Name of a domain under which the range is scoped. The default domain name is “NVTX”.
category – A string or an integer specifying the category within the domain under which the range is scoped. If unspecified, the range is not associated with a category.
payload –
A value associated with this event. Using payloads provides a separation between the message and the data of the event, which is often useful for analysis.

Note

payloads of type other than int or float requires NumPy to be installed (not installed with nvtx package).

Return type:

A tuple of the form (range_id, domain_handle) that must be passed to end_range().

Notes

For best performance, use Domain.start_range() and Domain.end_range().

Examples

>>> import time
>>> import nvtx
>>> range_id = nvtx.start_range("my_code_range", domain="my_domain")
>>> time.sleep(1)
>>> nvtx.end_range(range_id)

nvtx.end_range(range_id: Tuple[int, int])#

Mark the end of a code range that was started with start_range().

Parameters:: range_id – The tuple object returned by start_range().

Mark an instantaneous event.

Parameters:

message – A message associated with the event. Messages are cached and are registered as Registered Strings in NVTX. Caching a very large number of messages may lead to increased memory usage.
color – Color associated with the event. Supports matplotlib colors if it is available.
domain – A string specifying the domain under which the event is scoped. The default domain is named “NVTX”.
category – A string or an integer specifying the category within the domain under which the event is scoped. If unspecified, the event is not associated with a category.
payload –
A value associated with this event. Using payloads provides a separation between the message and the data of the event, which is often useful for analysis.

Note

payloads of type other than int or float requires NumPy to be installed (not installed with nvtx package).

Notes

For best performance, use Domain.mark().

Examples

>>> import nvtx
>>> nvtx.mark("my_marker", domain="my_domain")

nvtx.get_domain( name: str | None = None, ) → Domain | DummyDomain#: Get or create a Domain object for a domain name.

class nvtx.Domain(name: str | None = None)#

A class that provides an interface to NVTX API per domain, and produces less overhead than using the global functions from nvtx module.

Notes

Use nvtx.get_domain() to create an instance.
If the domain is disabled (e.g., when no tool is attached), the instance returned is a nvtx._lib.lib.DummyDomain.

mark(self, EventAttributes attributes)#

Mark an instantaneous event.

Parameters:: attributes (EventAttributes) – The event attributes to be associated with the event.

Examples

>>> import nvtx
>>> domain = nvtx.Domain('my_domain')
>>> attributes = domain.get_event_attributes(message='my_marker')
>>> domain.mark(attributes)

push_range(self, EventAttributes attributes)#

Mark the beginning of a code range.

Parameters:: attributes (EventAttributes) – The event attributes to be associated with the range.

Notes

When applicable, prefer to use annotate.

Examples

>>> import time
>>> import nvtx
>>> domain = nvtx.Domain('my_domain')
>>> attributes = domain.get_event_attributes(message='my_code_range')
>>> domain.push_range(attributes)
>>> time.sleep(1)
>>> domain.pop_range()

pop_range(self)#: Mark the end of a code range that was started with Domain.push_range().

start_range(self, EventAttributes attributes) → int#

Mark the beginning of a process range.

Parameters:: attributes (EventAttributes) – The event attributes to be associated with the range.
Return type:: A numeric value that must be passed to Domain.end_range().

Examples

>>> import time
>>> import nvtx
>>> domain = nvtx.Domain('my_domain')
>>> attributes = domain.get_event_attributes(message='my_code_range')
>>> range_id = domain.start_range(attributes)
>>> time.sleep(1)
>>> domain.end_range(range_id)

end_range(self, nvtxRangeId_t range_id)#

Mark the end of a process range that was started with Domain.start_range().

Parameters:: range_id (int) – The value returned by Domain.start_range().

get_event_attributes( self, message=None, color=None, category=None, payload=None, ) → EventAttributes#

Create an nvtx._lib.lib.EventAttributes object.

Parameters:

message (str) – A message associated with the event. If the given message is not registered, it is registered under this domain.
color (str, int, optional) – A color associated with the event. Supports matplotlib colors if it is available.
category (str, int, optional) – A string or an integer specifying the category within the domain under which the event is scoped. If unspecified, the event is not associated with a category.
payload (int, float, optional) – A numeric value to be associated with this event.

get_registered_string(self, string) → RegisteredString#

Parameters:: string (str) – The string to be registered.

get_category_id(self, name) → int#

Returns the category ID corresponding to the category name. On first use with a specific name, a new ID is assigned with the given name.

Parameters:: name (str) – The name of the category.

class nvtx._lib.lib.EventAttributes( domain, message=None, color=None, category=None, payload=None, )#

A wrapper class for nvtxEventAttributes_t C struct. Use nvtx.Domain.get_event_attributes() to create an instance.

message#

A message associated with the event. Retrieved by nvtx.Domain.get_registered_string().

Type:: RegisteredString

color#

A color associated with the event. Supports matplotlib colors if it is available.

Type:: str or int

category#

An integer specifying the category within the domain under which the event is scoped. If not set, the event is not associated with a category. Retrieved by nvtx.Domain.get_category_id().

Type:: int

payload#

A value associated with this event. Using payload for large data is more efficient than embedding data in messages. It also produces richer information for analysis by profiling tools.

Note

payloads of type other than int or float requires NumPy to be installed (not installed with nvtx package).

Type:: int, float, numpy.ndarray, list, tuple, range, or bytes

class nvtx._lib.lib.RegisteredString(domain, string=None)#: A wrapper class for nvtxStringHandle_t C struct. Use nvtx.Domain.get_registered_string() to create an instance.

class nvtx._lib.lib.DummyDomain#: A replacement for nvtx.Domain when the domain is disabled. (e.g., when no tool is attached).

class nvtx.Profile(linenos: bool = True, annotate_cfuncs: bool = True)#

Class for programmatically controlling NVTX automatic annotations.

Parameters:

linenos – Include file and line number information in annotations.
annotate_cfuncs – Also annotate C-extensions and builtin functions.

Examples

>>> import nvtx
>>> import time
>>> pr = nvtx.Profile()
>>> pr.enable()
>>> time.sleep(1) # this call to `sleep` is captured by nvtx.
>>> pr.disable()
>>> time.sleep(1) # this one is not.