3. NvRules API — NsightCompute 13.2 documentation
Description: Nsight Compute NvRules API.
Keywords: Profiler Report NvRules Rules

# 3. NvRules API

class NvRules.IAction

  Bases: `object`

  The `IAction` represents a profile result such as a CUDA kernel in a single range or a range itself in range-based profiling, for which zero or more metrics were collected.

  NameBase_DEMANGLED

    Name base for demangled names.

    Type

      `int`

  NameBase_FUNCTION

    Name base for function signature names.

    Type

      `int`

  NameBase_MANGLED

    Name base for mangled names.

    Type

      `int`

  WorkloadType_CMDLIST

    Workload type for CBL command lists.

    Type

      `int`

  WorkloadType_GRAPH

    Workload type for CUDA graphs.

    Type

      `int`

  WorkloadType_KERNEL

    Workload type for CUDA kernels or CUDA graph kernel nodes.

    Type

      `int`

  WorkloadType_RANGE

    Workload type for result ranges.

    Type

      `int`

  __getitem__(key)

    Get an `IMetric` object contained in this `IAction` by its name.

    Parameters

      key (`str`) – The name of the `IMetric` object to retrieve.

    Returns

      An `IMetric` object.

    Return type

      `IMetric`

    Raises

      - TypeError – If `key` is not of type `str`.

      - KeyError – If `key` is not the name of any `IMetric` object.

  __iter__()

    Get an iterator over the metric names of this `IAction`.

    Returns

      An iterator over the metric names.

    Return type

      iterator of `str`

  __len__()

    Get the number of `IMetric` objects of this `IAction`.

    Returns

      The number of `IMetric` objects.

    Return type

      `int`

  __str__()

    Get a human-readable representation of this `IAction`.

    Returns

      The name of the kernel the `IAction` object represents.

    Return type

      `str`

  metric_by_name(metric_name)

    Get a single `IMetric` by name.

    Parameters

      metric_name (`str`) – The name of the `IMetric` to retrieve.

    Returns

      The `IMetric` object or `None` if no such metric exists.

    Return type

      `IMetric` | `None`

  metric_names()

    Get the names of all metrics of this `IAction`.

    Returns

      The names of all metrics.

    Return type

      `tuple` of `str`

  name(*args)

    Get the name of the result the `IAction` object represents.

    Parameters

      name_base (`int`, optional) – The desired name base. Defaults to `NameBase_FUNCTION`.

    Returns

      The name of the result (potentially in a specific name base).

    Return type

      `str`

  nvtx_state()

    Get the NVTX state associated with this action.

    Returns

      The associated `INvtxState` or `None` if no state is associated.

    Return type

      `INvtxState` | `None`

  ptx_by_pc(address)

    Get the PTX associated with an address.

    Parameters

      address (`int`) – The address to get PTX for.

    Returns

      The PTX associated with the given address. If no PTX is available, the empty string will be returned.

    Return type

      `str`

  sass_by_pc(address)

    Get the SASS associated with an address.

    Parameters

      address (`int`) – The address to get SASS for.

    Returns

      The SASS associated with the given address. If no SASS is available, the empty string will be returned.

    Return type

      `str`

  source_files()

    Get the source files associated with this action along with their content.

    If content is not available for a file (e.g. because it hadn’t been imported into the report), the file name will map to an empty string.

    Returns

      A dictionary mapping source files to their content.

    Return type

      `dict` of `str` to `str`

  source_info(address)

    Get the source info for a function address within this action.

    Addresses are commonly obtained as correlation IDs of source-correlated metrics.

    Parameters

      address (`int`) – The address to get source info for.

    Returns

      The `ISourceInfo` associated to the given address. If no source info is available, `None` is returned.

    Return type

      `ISourceInfo` | `None`

  workload_type()

    Get the workload type of the action.

    Returns

      The workload type.

    Return type

      `int`

class NvRules.IContext

  Bases: `NvRules.IBaseContext`

  The `IContext` class is the top-level object representing an open report.

  It can be created by calling the `load_report` function.

  __getitem__(key)

    Get one or more `IRange` objects by index or by slice.

    Parameters

      key (`int` | `slice`) – The index or slice to retrieve.

    Returns: `IRange` | `tuple` of `IRange`: An `IRange` object or a `tuple` of `IRange` objects.

    Raises

      - TypeError – If `key` is not of type `int` or `slice`.

      - IndexError – If `key` is out of range for the `IContext`.

  __iter__()

    Get an iterator over the `IRange` objects of this `IContext`.

    Returns

      An iterator over the `IRange` objects.

    Return type

      iterator of `IRange`

  __len__()

    Get the number of `IRange` objects in this `IContext`.

    Returns

      The number of `IRange` objects.

    Return type

      `int`

  controller()

    Get the controller object.

    Returns

      The controller object.

    Return type

      `IController`

  frontend()

    Get the frontend object.

    Returns

      The frontend object.

    Return type

      `IFrontend`

  num_ranges()

    Get the number of `IRange` objects in this `IContext`.

    Returns

      The number of `IRange` objects.

    Return type

      `int`

  range_by_idx(idx)

    Get an `IRange` object by index.

    Parameters

      key (`int`) – The index to retrieve.

    Returns

      An `IRange` object or `None` if the index is out of range.

    Return type

      `IRange` | `None`

class NvRules.IController

  Bases: `object`

  Controller interface.

  The controller can be used to interact with the tool runtime, e.g., to signal the tools to propose a follow-up rule.

  get_message_vault()

    Get an `IMessageVault` object that can be used for message passing between rules.

    Returns

      `IMessageVault`

  propose_rule(rule)

    Propose the specified rule in the current context.

    Parameters

      rule (`str`) – The proposed rule identifier.

class NvRules.IEvaluator

  Bases: `NvRules.IBaseContext`

  Evaluator interface.

  The evaluator is used during rule setup to pass information about rule dependencies to the tool. For most cases, its Python wrapper functions `require_metrics` and `require_rules` should be used instead for convenience.

  require_metric(metric)

    Define that the specified metric must have been collected in order for the calling rule to be applied.

    Parameters

      metric (`str`) – The metric name to require.

  require_rule(rule)

    Define that the specified rule must be available and ready to be applied in order for the calling rule to be applied itself.

    Parameters

      rule (`str`) – The rule identifier to require.

class NvRules.IFrontend

  Bases: `object`

  The frontend is responsible for relaying messages and results to the caller via user interfaces, logs or output files.

  Deprecated Attributes and Their Replacement:

    MarkerKind_SASS - `MarkerKind.SASS`

    MarkerKind_SOURCE - `MarkerKind.SOURCE`

    MsgType_MSG_NONE - `MsgType.NONE`

    MsgType_MSG_OK - `MsgType.OK`

    MsgType_MSG_OPTIMIZATION - `MsgType.OPTIMIZATION`

    MsgType_MSG_WARNING - `MsgType.WARNING`

    MsgType_MSG_ERROR - `MsgType.ERROR`

  Severity_SEVERITY_DEFAULT

    The default severity.

    Type

      `int`

  Severity_SEVERITY_LOW

    Severity if low.

    Type

      `int`

  Severity_SEVERITY_HIGH

    Severity if high.

    Type

      `int`

  SpeedupType_LOCAL

    The proportional increase in efficiency of the hardware usage when viewing the performance problem in isolation.

    Type

      `int`

  SpeedupType_GLOBAL

    The proportional reduction in runtime of the entire workload.

    Type

      `int`

  focus_metric(message_id, metric_name, metric_value, severity, info)

    Create a rule focus metric message.

    Issues a focus metric message to the frontend, e.g. to indicate a key metric that triggered the rule output.

    Parameters

      - message_id (`int`) – The prior message to associate with.

      - metric_name (`str`) – Name of the focus metric.

      - metric_value (`float`) – Value of the focus metric.

      - severity (`int`) – Indicates the impact orseverity on the result.

      - info (`str`) – Descriptive string for further information, e.g., the calculation leading to this metric being focused.

    Returns

      `True` if the focus metric could be set successfully,

        `False` otherwise.

    Return type

      `bool`

  generate_table(message_id, header, data, config=None)

    Generate a table in the frontend.

    This function attaches a table to the pre-existing rule message given by message_id. It can be called multiple times to attach multiple tables to the same message.

    The table can be customized by passing a dict to the config parameter. The table can contain a title, description, a column to sort by, and a global styling. Additionally, the table can have per-column configurations, which can specify a header tooltip, relative column width, and styling for the header and data cells.

    This is an example of a valid config dict:

        config = {
            "title": "My table title",
            "description": "Short description of the table",
            "sort_by": {
                "column": "MyColumn",  # specify column by name or index
                "order": "ascending",  # in ascending order (default)
            },
            "per_column_configs": {  # overwrites global styling for individual columns
                "MyColumn": {  # can use column name or index
                    "tooltip": "Explanation of MyColumn",  # tooltip for the header
                    "relative_width": 0.5,  # relative width of the column
                    "style": {
                        "header": {"bold": True},
                        "data": {"italic": True},
                    }
                },
            },
        }

    Parameters

      - message_id (int) – The message to which to attach the table to.

      - header (list[str]) – The column labels of the table.

      - data (list[list[int | float | str | Any]]) –

        The table data in row-major format. Any refers to any type that implements __str__. Each column must only have elements of the same type, and all columns must have the same length.

        class:str values may contain substrings with the following special link formats

          - @url:<hypertext>:<external link>@ - To add a external link for a hypertext.

          - @sass:<address>:<hypertext>@ - To add a link to the hypertext to open the SASS address line on the Source page.

          - @source:<file name>:<line number>:<hypertext>@ - To add a link to the hypertext to open the source file at the specified line number on the Source page.

          - @section:<section identifier>:<hypertext>@ - To add a link to the hypertext to jump to the respective section.

      - config (dict[str, Any] | None) – Configuration options for the table. Defaults to None.

    Raises

      - TypeError – If types of elements within a column are mixed.

      - ValueError – If columns have different lengths, or len(header) does not match the number of columns in data.

  load_chart_from_file(filename)

    Load a ProfilerSection google protocol buffer chart from a file.

    Parameters

      filename (`str`) – The file name.

  message(*args)

    Issues a message to the frontend.

    Parameters

      - type (`int`, optional) – The message type.

      - str (`str`) –

        The message content.

        The message may contain substrings with the following special link formats:

          - @url:<hypertext>:<external link>@ - To add a external link for a hypertext.

          - @sass:<address>:<text>@ - To add a SASS address to the cell.

          - @source:<file name>:<line number>:<hypertext>@ - To add a link to the hypertext to open the source file at the specified line number on the Source page.

          - @section:<section identifier>:<hypertext>@ - To add a link to the hypertext to jump to the respective section.

      - name (`str`, optional) – The name of the message.

    Returns

      A message ID that is unique in this rule invocation.

    Return type

      `int`

  receive_dict_from_parent(parent_id)

    Receive a dictionary from a parent rule.

    Receive a dictionary of type dict[str,float] sent using `IFrontend.send_dict_to_children`. If the parent id does not represent a pre-specified parent rule of this rule, or in case the parent rule has not been executed, an empty dict will be returned.

    Parameters

      parent_id (`str`) – ID of the pre-specified parent rule.

    Returns

      The received dictionary.

        An empty dict if the parent rule has not been executed.

    Return type

      `dict`

  send_dict_to_children(dict)

    Send a dictionary to all child rules.

    Sends a Python dictionary of type dict[str,float] to all rules that specify this rule as a parent rule. Child rules can retrieve the message using `IFrontend.receive_dict_from_parent`. In case this function is called repeatedly, the dict is updated accordingly, thereby adding new key-value pairs, and overwriting values of pre-existing keys.

    Parameters

      dict (`dict`) – The dictionary to send.

  source_marker(*args)

    Create a rule source marker.

    Parameters

      - str (`str`) – The source marker message.

      - address_or_line (`int`) – The source location in the appropriate kind of source.

      - kind (`int`) – The the kind of source.

      - file_name (`str`, optional) – The file name.

      - type (`int`, optional) – The urgency associated with this marker. By default `MsgType.NONE`.

  speedup(message_id, type, estimated_speedup)

    Rule estimated speedup message.

    Issues an estimated speedup associated with a message to the frontend.

    Parameters

      - message_id (`int`) – ID of the existing message.

      - type (`int`) – The SpeedupType. If GLOBAL, it indicates what proportional decrease in workload runtime could potentially be achieved, when following the guidelines of the rule. If LOCAL, it indicates what increase in the efficiency of the hardware usage within the context of the performance problem could be achieved.

    Returns

      `True` if the speedup could be set successfully,

        `False` otherwise.

    Return type

      `bool`

class NvRules.IMessageVault

  Bases: `object`

  Passes messages between rules.

  Get(ruleId)

    Retrieve the message associated with a rule from the vault.

    In case the rule is unknown, an empty message is returned.

    Parameters

      ruleId (`str`) – The identifier of the rule.

    Returns

      The message associated with the rule.

    Return type

      `dict`

  Put(ruleId, message)

    Commit a message associated with a rule to the vault.

    In case multiple messages associated with the same rule are committed, the messages are merged, in such a way that new key-value pairs are added, and values of pre-existing keys are updated.

    Parameters

      - ruleId (`str`) – The identifier of the rule.

      - message (`dict`) – The message to commit.

class NvRules.IMetric

  Bases: `object`

  Represents a single, named metric. An `IMetric` can carry one value or multiple ones if it is an instanced metric.

  MetricType_OTHER

    Metric type for metrics that do not fit in any other category.

    Type

      `int`

  MetricType_COUNTER

    Metric type for counter metrics.

    Type

      `int`

  MetricType_RATIO

    Metric type for ratio metrics.

    Type

      `int`

  MetricType_THROUGHPUT

    Metric type for throughput metrics.

    Type

      `int`

  MetricSubtype_NONE

    Metric subtype for metrics that do not have a subtype.

    Type

      `int`

  MetricSubtype_PEAK_SUSTAINED

    Metric subtype for peak sustained metrics.

    Type

      `int`

  MetricSubtype_PEAK_SUSTAINED_ACTIVE

    Metric subtype for peak sustained active metrics.

    Type

      `int`

  MetricSubtype_PEAK_SUSTAINED_ACTIVE_PER_SECOND

    Metric subtype for peak sustained active per-second metrics.

    Type

      `int`

  MetricSubtype_PEAK_SUSTAINED_ELAPSED

    Metric subtype for peak sustained elapsed metrics.

    Type

      `int`

  MetricSubtype_PEAK_SUSTAINED_ELAPSED_PER_SECOND

    Metric subtype for peak sustained elapsed per-second metrics.

    Type

      `int`

  MetricSubtype_PER_CYCLE_ACTIVE

    Metric subtype for per-cycle active metrics.

    Type

      `int`

  MetricSubtype_PER_CYCLE_ELAPSED

    Metric subtype for per-cycle elapsed metrics.

    Type

      `int`

  MetricSubtype_PER_SECOND

    Metric subtype for per-second metrics.

    Type

      `int`

  MetricSubtype_PCT_OF_PEAK_SUSTAINED_ACTIVE

    Metric subtype for percentage of peak sustained active metrics.

    Type

      `int`

  MetricSubtype_PCT_OF_PEAK_SUSTAINED_ELAPSED

    Metric subtype for percentage of peak sustained elapsed metrics.

    Type

      `int`

  MetricSubtype_MAX_RATE

    Metric subtype for max rate metrics.

    Type

      `int`

  MetricSubtype_PCT

    Metric subtype for percentage metrics.

    Type

      `int`

  MetricSubtype_RATIO

    Metric subtype for ratio metrics.

    Type

      `int`

  RollupOperation_NONE

    No rollup operation.

    Type

      `int`

  RollupOperation_AVG

    Average rollup operation.

    Type

      `int`

  RollupOperation_MAX

    Maximum rollup operation.

    Type

      `int`

  RollupOperation_MIN

    Minimum rollup operation.

    Type

      `int`

  RollupOperation_SUM

    Sum rollup operation.

    Type

      `int`

  ValueKind_UNKNOWN

    Unknown value kind.

    Type

      `int`

  ValueKind_ANY

    Undefined value kind.

    Type

      `int`

  ValueKind_STRING

    String value kind.

    Type

      `int`

  ValueKind_FLOAT

    Float value kind.

    Type

      `int`

  ValueKind_DOUBLE

    Double value kind.

    Type

      `int`

  ValueKind_UINT32

    Unsigned 32-bit integer value kind.

    Type

      `int`

  ValueKind_UINT64

    Unsigned 64-bit integer value kind.

    Type

      `int`

  __str__()

    Get a human-readable representation of this `IMetric`.

    Returns

      The name of the `IMetric`.

    Return type

      `str`

  as_double(*args)

    Get the metric value or metric instance value as a `float`.

    Parameters

      instance (`int`, optional) – If provided, the index of the instance value to retrieve instead a metric value.

    Returns

      The metric value or metric instance value requested. If the value cannot be casted to a `float`, this function will return `0.`.

    Return type

      `float`

  as_string(*args)

    Get the metric value or metric instance value as a `str`.

    Parameters

      instance (`int`, optional) – If provided, the index of the instance value to retrieve instead a metric value.

    Returns

      The metric value or metric instance value requested. If the value cannot be casted to a `str`, this function will return `None`.

    Return type

      `str` | `None`

  as_uint64(*args)

    Get the metric value or metric instance value as an `int`.

    Parameters

      instance (`int`, optional) – If provided, the index of the instance value to retrieve instead a metric value.

    Returns

      The metric value or metric instance value requested. If the value cannot be casted to a `int`, this function will return `0`.

    Return type

      `int`

  correlation_ids()

    Get a metric object for this metric’s instance value’s correlation IDs.

    Returns a new `IMetric` representing the correlation IDs for the metric’s instance values. Use `IMetric.has_correlation_ids` to check if this metric has correlation IDs for its instance values. Correlation IDs are used to associate instance values with the instance their value represents. In the returned new metric object, the correlation IDs are that object’s instance values.

    If the metric does not have any correlation IDs, this function will return `None`.

    Returns

      The new `IMetric` object representing the correlation IDs for this metric’s instance values or `None` if the metric has no correlation IDs.

    Return type

      `IMetric` | `None`

  description()

    Get the metric description.

    Returns

      The description of the metric.

    Return type

      `str`

  has_correlation_ids()

    Check if the metric has correlation IDs.

    Returns

      `True` if the metric has correlation IDs matching its instance values, `False` otherwise.

    Return type

      `bool`

  has_value(*args)

    Check if the metric or metric instance has a value.

    Parameters

      instance (`int`, optional) – If provided, the index of the instance metric to check.

    Returns

      `True` if the metric or metric instance has a value, `False`` otherwise.

    Return type

      `bool`

  kind(*args)

    Get the metric or metric instance value kind.

    Parameters

      instance (`int`, optional) – If provided, the index of the instance metric to get the value kind for.

    Returns

      The metric or metric instance value kind.

    Return type

      `int`

  metric_subtype()

    Get the metric subtype.

    Returns

      The metric subtype.

    Return type

      `int`

  metric_type()

    Get the metric type.

    Returns

      The metric type.

    Return type

      `int`

  name()

    Get the metric name.

    Returns

      The metric name.

    Return type

      `str`

  num_instances()

    Get the number of instance values for this metric.

    Not all metrics have instance values. If a metric has instance values, it may also have `IMetric.correlation_ids` matching these instance values.

    Returns

      The number of instances for this metric.

    Return type

      `int`

  rollup_operation()

    Get the type of rollup operation for this metric.

    Returns

      The rollup operation type.

    Return type

      `int`

  unit()

    Get the metric unit.

    Returns

      The metric unit.

    Return type

      `str`

  value(idx=None)

    Get the value of this `IMetric`.

    This is a convenience function that will wrap the logic of invoking the correct `IMetric.as_*` method based on the value kind of this `IMetric`.

    Parameters

      idx (`int`, optional) – The index of the value to get.

    Returns

      The value of this `IMetric` as `str`, `int` or `float`. If no value is available, this will return `None`.

    Return type

      `str` | `int` | `float` | `None`

class NvRules.IMutableMetric

  Bases: `NvRules.IMetric`

  Represents a single, named mutable metric. An `IMutableMetric` can carry one value or multiple ones if it is an instanced metric. In comparison to `IMetric`, `IMutableMetric` can be modified by assigning it a new value and/or instance values. The metric kind is determined by the assigned value(s).

  mutable_correlation_ids()

    Get a mutable metric object for this metric’s instance value’s correlation IDs.

    Returns a new `IMutableMetric` representing the correlation IDs for the metric’s instance values. Correlation IDs are used to associate instance values with the instance their value represents. In the returned new metric object, the correlation IDs are that object’s instance values.

    Returns

      The new `IMutableMetric` object representing the correlation IDs for this metric’s instance values.

    Return type

      `IMutableMetric`

  set_double(*args)

    Assign the metric an instance `float` value.

    Parameters

      - instance (`int`, optional) – The instance to assign the value to.

      - value_kind (`int`) – Acceptable kinds are FLOAT, DOUBLE or ANY (for which the implementation chooses the kind internally)

      - value (`float`) – The value to assign.

    Returns

      `True` if the instance value was set, `False` otherwise.

    Return type

      `bool`

  set_string(*args)

    Assign the metric an instance `str` value.

    Parameters

      - instance (`int`, optional) – The instance to assign the value to.

      - value_kind (`int`) – Acceptable kinds are STRING or ANY (for which the implementation chooses the kind internally)

      - value (`str`) – The value to assign.

    Returns

      `True` if the instance value was set, `False` otherwise.

    Return type

      `bool`

  set_uint64(*args)

    Assign the metric a `int` value.

    Parameters

      - instance (`int`, optional) – The instance to assign the value to.

      - value_kind (`int`) – Acceptable kinds are UINT32, UINT64 or ANY (for which the implementation chooses the kind internally)

      - value (`int`) – The value to assign.

    Returns

      `True` if the value was set, `False` otherwise.

    Return type

      `bool`

class NvRules.INvtxDomainInfo

  Bases: `object`

  Represents a single NVTX domain of the NVTX state, including all ranges associated with this domain.

  __str__()

    Get a human-readable representation of this `INvtxDomainInfo`.

    Returns

      The name of the `INvtxDomainInfo`.

    Return type

      `str`

  name()

    Get a human-readable representation of this `INvtxDomainInfo`.

    Returns

      The name of the `INvtxDomainInfo`.

    Return type

      `str`

  push_pop_range(idx)

    Get a push/pop range object by index.

    The index is identical to the range’s order on the call stack.

    Returns

      The requested `INvtxRange` or `None` if the index is out of range.

    Return type

      `INvtxRange` | `None`

  push_pop_ranges()

    Get a sorted list of push/pop range names.

    Get the sorted list of stacked push/pop range names in this domain, associated with the current `INvtxState`.

    Returns

      The sorted names of all push/pop ranges.

    Return type

      `tuple` of `str`

  start_end_range(idx)

    Get a start/end range object by index.

    Returns

      The requested `INvtxRange` or `None` if the index is out of range.

    Return type

      `INvtxRange` | `None`

  start_end_ranges()

    Get a sorted list of start/end range names.

    Get the sorted list of start/end range names in this domain, associated with the current `INvtxState`.

    Returns

      The sorted names of all start/end ranges.

    Return type

      `tuple` of `str`

class NvRules.INvtxRange

  Bases: `object`

  Represents a single NVTX Push/Pop or Start/End range.

  PayloadType_PAYLOAD_UNKNOWN

    Payload type for ranges of unknown type.

    Type

      `int`

  PayloadType_PAYLOAD_INT32

    Payload type for ranges of INT32 type.

    Type

      `int`

  PayloadType_PAYLOAD_INT64

    Payload type for ranges of INT64 type.

    Type

      `int`

  PayloadType_PAYLOAD_UINT32

    Payload type for ranges of UINT32 type.

    Type

      `int`

  PayloadType_PAYLOAD_UINT64

    Payload type for ranges of UINT64 type.

    Type

      `int`

  PayloadType_PAYLOAD_FLOAT

    Payload type for ranges of float type.

    Type

      `int`

  PayloadType_PAYLOAD_DOUBLE

    Payload type for ranges of double type .

    Type

      `int`

  PayloadType_PAYLOAD_JSON

    Payload type for ranges of JSON type.

    Type

      `int`

  category()

    Get the category attribute value.

    Returns

      The category attribute value. If `INvtxRange.has_attributes` returns `False`, this will return `0`.

    Return type

      `int`

  color()

    Get the color attribute value.

    Returns

      The color attribute value. If `INvtxRange.has_attributes` returns `False`, this will return `0`.

    Return type

      `int`

  has_attributes()

    Check if range has event attributes.

    Returns

      `True` if the range has event attributes, `False` otherwise.

    Return type

      `bool`

  message()

    Get the message attribute value.

    Returns

      The message attribute value. If `INvtxRange.has_attributes` returns `False`, this will return the empty string.

    Return type

      `str`

  name()

    Get the range’s name.

    Returns

      The range’s name.

    Return type

      `str`

  payload_as_double()

    Get the payload attribute value as a `float`.

    Returns

      The payload attribute’s value as a `float`. If the value cannot be casted to a `float`, this function will return `0.`.

    Return type

      `float`

  payload_as_string()

    Get the payload attribute value as a `str`.

    Returns

      The payload attribute’s value as a `str`. If the value cannot be casted to a `str`, this function will return the empty string.

    Return type

      `str`

  payload_as_uint64()

    Get the payload attribute value as an `int`.

    Returns

      The payload attribute’s value as a `int`. If the value cannot be casted to a `int`, this function will return `0`.

    Return type

      `int`

  payload_type()

    Get the payload type as an `int`.

    Returns

      The payload type.

    Return type

      `int`

class NvRules.INvtxState

  Bases: `object`

  Represents the NVTX (Nvidia Tools Extensions) state associated with a single `IAction`.

  __getitem__(key)

    Get an `INvtxDomainInfo` object by ID.

    Parameters

      key (`int`) – The ID of the `INvtxDomainInfo` object.

    Returns

      An `INvtxDomainInfo` object.

    Return type

      `INvtxDomainInfo`

    Raises

      - TypeError – If `key` is not of type `int`.

      - KeyError – If `key` is not a valid ID.

  __iter__()

    Get an iterator over the `INvtxDomainInfo` objects of this `INvtxState`.

    Returns

      An iterator over the `INvtxDomainInfo` objects.

    Return type

      iterator

  __len__()

    Get the number of `INvtxDomainInfo` objects of this `INvtxState`.

    Returns

      The number of `INvtxDomainInfo` objects.

    Return type

      `int`

  domain_by_id(id)

    Get a `INvtxDomainInfo` object by ID.

    Use `INvtxState.domains` to retrieve the list of valid domain IDs.

    Parameters

      id (`int`) – The ID of the request domain.

    Returns

      The requested `INvtxDomainInfo` object.

    Return type

      `INvtxDomainInfo` | `None`

  domains()

    Get the list of domain IDs in this state.

    Returns

      The tuple of valid domain IDs.

    Return type

      `tuple` of `int`

class NvRules.IRange

  Bases: `object`

  Represents a serial, ordered stream of execution, such as a CUDA stream. It holds one or more actions that were logically executing in this range.

  __getitem__(key)

    Get one or more `IAction` objects by index or by `slice`.

    Parameters

      key (`int` | `slice`) – The index or `slice` to retrieve.

    Returns

      An `IAction` object or a `tuple` of `IAction` objects.

    Return type

      `IAction` | `tuple` of `IAction`

    Raises

      - TypeError – If `key` is not of type `int` or `slice`.

      - IndexError – If `key` is out of range for the `IRange`.

  __iter__()

    Get an iterator over the `IAction` objects of this class:IRange.

    Returns

      An iterator over the `IAction` objects.

    Return type

      iterator of `IAction`

  __len__()

    Get the number of `IAction` objects in this `IRange`.

    Returns

      The number of class:IAction objects.

    Return type

      `int`

  action_by_idx(idx)

    Get an `IAction` objects by index.

    Parameters

      key (`int`) – The index to retrieve.

    Returns

      An `IAction` object or `None` if the index is out of range.

    Return type

      `IAction` | `None`

  actions_by_nvtx(includes, excludes)

    Get a set of indices to IAction objects by their NVTX state. The state is defined using a series of includes and excludes.

    Parameters

      - includes (iterable of `str`) – The NVTX states the result should be part of.

      - excludes (iterable of `str`) – The NVTX states the result should not be part of.

    Returns

      A `tuple` of indices to `IAction` matching the desired NVTX state.

    Return type

      `tuple` of `int`

  num_actions()

    Get the number of `IAction` objects in this `IRange`.

    Returns

      The number of class:IAction objects.

    Return type

      `int`

class NvRules.MarkerKind

  Bases: `enum.IntEnum`

  Enum representing the kind of a source marker.

  SASS

    The marker will be associated with a SASS instruction.

  SOURCE

    The marker will be associated with a Source line.

  NONE

    No specific kind of marker.

class NvRules.MsgType

  Bases: `enum.IntEnum`

  Enum representing the type of the message.

  NONE

    No specific type for this message.

  OK

    The message is informative.

  OPTIMIZATION

    The message represents a suggestion for performance optimization.

  WARNING

    The message represents a warning or fixable issue.

  ERROR

    The message represents an error, potentially in executing the rule.

NvRules.get_context(h)

  Return the `IContext` object from the context handle.

  Parameters

    h (`int`) – The context handle.

  Returns

    The evaluator object.

  Return type

    `IContext`

NvRules.get_evaluator(h)

  Return the `IEvaluator` object from the context handle.

  Parameters

    h (`int`) – The context handle.

  Returns

    The evaluator object.

  Return type

    `IEvaluator`

NvRules.get_version(h)

  Get version number of this interface.

  Parameters

    h (`int`) – The context handle.

  Returns

    Returns the version number of this interface as a string of the form <year>.<major>.<minor>. It matches the Nsight Compute version this interface originates from.

  Return type

    `str`

NvRules.require_metrics(handle, metrics)

  Convenience wrapper for `NvRules.IEvaluator.require_metric`.

  Parameters

    - handle (`int`) – The context handle, obtained from `get_context`.

    - metrics (`list`) – List of metric names.

NvRules.require_rules(handle, rules)

  Convenience wrapper for `NvRules.IEvaluator.require_rule`.

  Parameters

    - handle (`int`) – The context handle, obtained from `get_context`.

    - rules (`list`) – List of rule identifiers.

Notices

Notices

ALL NVIDIA DESIGN SPECIFICATIONS, REFERENCE BOARDS, FILES, DRAWINGS, DIAGNOSTICS, LISTS, AND OTHER DOCUMENTS (TOGETHER AND SEPARATELY, “MATERIALS”) ARE BEING PROVIDED “AS IS.” NVIDIA MAKES NO WARRANTIES, EXPRESSED, IMPLIED, STATUTORY, OR OTHERWISE WITH RESPECT TO THE MATERIALS, AND EXPRESSLY DISCLAIMS ALL IMPLIED WARRANTIES OF NONINFRINGEMENT, MERCHANTABILITY, AND FITNESS FOR A PARTICULAR PURPOSE.

Information furnished is believed to be accurate and reliable. However, NVIDIA Corporation assumes no responsibility for the consequences of use of such information or for any infringement of patents or other rights of third parties that may result from its use. No license is granted by implication of otherwise under any patent rights of NVIDIA Corporation. Specifications mentioned in this publication are subject to change without notice. This publication supersedes and replaces all other information previously supplied. NVIDIA Corporation products are not authorized as critical components in life support devices or systems without express written approval of NVIDIA Corporation.

Trademarks

NVIDIA and the NVIDIA logo are trademarks or registered trademarks of NVIDIA Corporation in the U.S. and other countries. Other company and product names may be trademarks of the respective companies with which they are associated.