API Reference

class nvtx.annotate(

message: str | None = None,

color: str | int | None = None,

domain: str | None = None,

category: str | int | None = None,

payload: int | float | None = None,

)

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 numeric value to be associated with this event.

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)

nvtx.push_range(

message: str | None = None,

color: str | int | None = 'blue',

domain: str | None = None,

category: str | int | None = None,

payload: int | float | None = None,

)

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 numeric value to be associated with this event

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”.

nvtx.start_range(

message: str | None = None,

color: str | int | None = None,

domain: str | None = None,

category: str | int | None = None,

payload: int | float | None = None,

) → tuple[int, int]

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 numeric value to be associated with this event

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().

nvtx.mark(

message: str | None = None,

color: str | int | None = 'blue',

domain: str | None = None,

category: str | int | None = None,

payload: int | float | None = None,

)

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 numeric value to be associated with this event

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

Get or create an nvtx._lib.lib.EventAttributes object. The results of this function are cached, i.e., the same object is returned for the same parameters.

Parameters:

• message (str) – A message associated with the event.

• 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

Register a given string under this domain (on first use), and return the handle.

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(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 numeric value to be associated with this event.

Type:

int

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.