cuda/nsight_compute/python_report_interface/Opcode_instanced_metrics.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Opcode-Instanced Metrics"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this notebook you will learn how to:\n",
    "\n",
    "* Find opcode-instanced metrics in an NVIDIA Nsight Compute report\n",
    "* Traverse the individual instances of such a metric along with their SASS opcode"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Setup"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First, import NVIDIA Nsight Compute's Python Report Interface (PRI) as `ncu_report`\n",
    "and load an `ncu-rep` report file with `load_report`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import ncu_report\n",
    "\n",
    "report_file_path = \"../sample_reports/mergeSort.ncu-rep\"\n",
    "report = ncu_report.load_report(report_file_path)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For later use, unpack the profiling results of the first kernel and create a list of all metrics it contains:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "kernel = report[0][0]\n",
    "metrics = (kernel[name] for name in kernel)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Identifying Opcode-Instanced Metrics"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Opcode-instanced metrics are metrics that contain multiple values (so-called _instances_),\n",
    "each of which is associated with a SASS operation code, or _opcode_.\n",
    "They may, for example, help you understand the fraction of a particular type of SASS\n",
    "instruction relative to the whole instruction mixture executed in your code.\n",
    "\n",
    "They always carry the substring \"opcode\" in their metric name and are thus easy to find:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "for metric in metrics:\n",
    "    if \"opcode\" in str(metric):\n",
    "        print(\n",
    "            f\"{metric} contains instance values for \"\n",
    "            f\"{metric.num_instances()} opcodes\"\n",
    "        )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also find a list of all opcode-instanced metrics together with a description in the\n",
    "[Metric Reference](https://docs.nvidia.com/nsight-compute/ProfilingGuide/index.html#metrics-reference)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Traversing Opcode-Instanced Metrics along with their Opcodes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In order to traverse opcode-instanced metrics you simple need to call the member function\n",
    "`value(index)` of an `IMetric` object for each of its instances, where `index` runs from `0`\n",
    "to `num_instances()-1`.\n",
    "\n",
    "To obtain the corresponding opcode of each instances, you first need to call `correlation_ids()`\n",
    "for the opcode-instanced metric. This will create a new `IMetric` object which has\n",
    "instance values of type `str`, each representing the opcode of the original metrics instance\n",
    "with the same index.\n",
    "\n",
    "You can use the opcodes as keys in a `dict` with the instances of the original metric\n",
    "as values. Here's a helper function to construct such a `dict`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def values_per_opcode(metric: ncu_report.IMetric) -> dict[str, int]:\n",
    "    values = dict()\n",
    "    opcodes = metric.correlation_ids()\n",
    "    num_values = metric.num_instances()\n",
    "\n",
    "    for index in range(num_values):\n",
    "        opcode = opcodes.value(index)\n",
    "        values[opcode] = metric.value(index)\n",
    "\n",
    "    return values"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, you can look at all SASS instructions executed at thread-level within the `kernel`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "metric_name = \"sass__thread_inst_executed_true_per_opcode_with_modifier_all\"\n",
    "metric = kernel[metric_name]\n",
    "all_instructions = metric.value()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Using `values_per_opcode(metric)` it is now very simple to traverse all instance values\n",
    "along with their respective opcodes. You can also calculate the percentage of each\n",
    "instruction type with respect to all instructions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(\n",
    "    f\"All instructions executed at thread-level: {all_instructions:,.0f}, \"\n",
    "    f\"number of opcodes: {metric.num_instances()}\"\n",
    ")\n",
    "\n",
    "for opcode, value in values_per_opcode(metric).items():\n",
    "    fraction = value / all_instructions * 100\n",
    "    print(f\"   \\033[1m{opcode}:\\033[0m {value:,} ({fraction:.3f}%)\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Analyzing instruction compositions like this and comparing them against your expectations might help you discover performance\n",
    "bugs in your kernels.\n",
    "\n",
    "As a next step, you can have a look into `Source_correlated_metrics.ipynb` to learn how to obtain the disassembled SASS\n",
    "instructions (which include the opcodes) or learn about the\n",
    "[`IAction.sass_by_pc` API](https://docs.nvidia.com/nsight-compute/2022.3/NvRulesAPI/annotated.html#classNV_1_1Rules_1_1IAction_1a1fc608333aefe67f0559ab03094acb4)."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "base",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.13"
  },
  "orig_nbformat": 4,
  "vscode": {
   "interpreter": {
    "hash": "980371efc09d79af10597fc0541da4320ce4f3e067752c6a7ec257bcdc2f4996"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}