class_docstr: Helper class for measuring execution time of PyTorch statements.
  
  For a full tutorial on how to use this class, see:
  https://pytorch.org/tutorials/recipes/recipes/benchmark.html
  
  The PyTorch Timer is based on `timeit.Timer` (and in fact uses
  `timeit.Timer` internally), but with several key differences:
  
  1) Runtime aware:
      Timer will perform warmups (important as some elements of PyTorch are
      lazily initialized), set threadpool size so that comparisons are
      apples-to-apples, and synchronize asynchronous CUDA functions when
      necessary.
  
  2) Focus on replicates:
      When measuring code, and particularly complex kernels / models,
      run-to-run variation is a significant confounding factor. It is
      expected that all measurements should include replicates to quantify
      noise and allow median computation, which is more robust than mean.
      To that effect, this class deviates from the `timeit` API by
      conceptually merging `timeit.Timer.repeat` and `timeit.Timer.autorange`.
      (Exact algorithms are discussed in method docstrings.) The `timeit`
      method is replicated for cases where an adaptive strategy is not
      desired.
  
  3) Optional metadata:
      When defining a Timer, one can optionally specify `label`, `sub_label`,
      `description`, and `env`. (Defined later) These fields are included in
      the representation of result object and by the `Compare` class to group
      and display results for comparison.
  
  4) Instruction counts
      In addition to wall times, Timer can run a statement under Callgrind
      and report instructions executed.
  
  Directly analogous to `timeit.Timer` constructor arguments:
  
      `stmt`, `setup`, `timer`, `globals`
  
  PyTorch Timer specific constructor arguments:
  
      `label`, `sub_label`, `description`, `env`, `num_threads`
  
  Args:
      stmt: Code snippet to be run in a loop and timed.
  
      setup: Optional setup code. Used to define variables used in `stmt`
  
      global_setup: (C++ only)
          Code which is placed at the top level of the file for things like
          `#include` statements.
  
      timer:
          Callable which returns the current time. If PyTorch was built
          without CUDA or there is no GPU present, this defaults to
          `timeit.default_timer`; otherwise it will synchronize CUDA before
          measuring the time.
  
      globals:
          A dict which defines the global variables when `stmt` is being
          executed. This is the other method for providing variables which
          `stmt` needs.
  
      label:
          String which summarizes `stmt`. For instance, if `stmt` is
          "torch.nn.functional.relu(torch.add(x, 1, out=out))"
          one might set label to "ReLU(x + 1)" to improve readability.
  
      sub_label:
          Provide supplemental information to disambiguate measurements
          with identical stmt or label. For instance, in our example
          above sub_label might be "float" or "int", so that it is easy
          to differentiate:
          "ReLU(x + 1): (float)"
  
          "ReLU(x + 1): (int)"
          when printing Measurements or summarizing using `Compare`.
  
      description:
          String to distinguish measurements with identical label and
          sub_label. The principal use of `description` is to signal to
          `Compare` the columns of data. For instance one might set it
          based on the input size  to create a table of the form: ::
  
                                      | n=1 | n=4 | ...
                                      ------------- ...
              ReLU(x + 1): (float)    | ... | ... | ...
              ReLU(x + 1): (int)      | ... | ... | ...
  
  
          using `Compare`. It is also included when printing a Measurement.
  
      env:
          This tag indicates that otherwise identical tasks were run in
          different environments, and are therefore not equivalent, for
          instance when A/B testing a change to a kernel. `Compare` will
          treat Measurements with different `env` specification as distinct
          when merging replicate runs.
  
      num_threads:
          The size of the PyTorch threadpool when executing `stmt`. Single
          threaded performance is important as both a key inference workload
          and a good indicator of intrinsic algorithmic efficiency, so the
          default is set to one. This is in contrast to the default PyTorch
          threadpool size which tries to utilize all cores.
class_docstr_tok: ["Helper","class","for","measuring","execution","time","of","PyTorch","statements",".","For","a","full","tutorial","on","how","to","use","this","class",",","see",":","https",":","\/\/pytorch.org\/tutorials\/recipes\/recipes\/benchmark.html","The","PyTorch","Timer","is","based","on","`","timeit.Timer","`","(","and","in","fact","uses","`","timeit.Timer","`","internally",")",",","but","with","several","key","differences",":","1",")","Runtime","aware",":","Timer","will","perform","warmups","(","important","as","some","elements","of","PyTorch","are","lazily","initialized",")",",","set","threadpool","size","so","that","comparisons","are","apples-to-apples",",","and","synchronize","asynchronous","CUDA","functions","when","necessary",".","2",")","Focus","on","replicates",":","When","measuring","code",",","and","particularly","complex","kernels","\/","models",",","run-to-run","variation","is","a","significant","confounding","factor",".","It","is","expected","that","all","measurements","should","include","replicates","to","quantify","noise","and","allow","median","computation",",","which","is","more","robust","than","mean",".","To","that","effect",",","this","class","deviates","from","the","`","timeit","`","API","by","conceptually","merging","`","timeit.Timer.repeat","`","and","`","timeit.Timer.autorange","`",".","(","Exact","algorithms","are","discussed","in","method","docstrings",".",")","The","`","timeit","`","method","is","replicated","for","cases","where","an","adaptive","strategy","is","not","desired",".","3",")","Optional","metadata",":","When","defining","a","Timer",",","one","can","optionally","specify","`","label","`",",","`","sub_label","`",",","`","description","`",",","and","`","env","`",".","(","Defined","later",")","These","fields","are","included","in","the","representation","of","result","object","and","by","the","`","Compare","`","class","to","group","and","display","results","for","comparison",".","4",")","Instruction","counts","In","addition","to","wall","times",",","Timer","can","run","a","statement","under","Callgrind","and","report","instructions","executed",".","Directly","analogous","to","`","timeit.Timer","`","constructor","arguments",":","`","stmt","`",",","`","setup","`",",","`","timer","`",",","`","globals","`","PyTorch","Timer","specific","constructor","arguments",":","`","label","`",",","`","sub_label","`",",","`","description","`",",","`","env","`",",","`","num_threads","`","Args",":","stmt",":","Code","snippet","to","be","run","in","a","loop","and","timed",".","setup",":","Optional","setup","code",".","Used","to","define","variables","used","in","`","stmt","`","global_setup",":","(","C++","only",")","Code","which","is","placed","at","the","top","level","of","the","file","for","things","like","`","#","include","`","statements",".","timer",":","Callable","which","returns","the","current","time",".","If","PyTorch","was","built","without","CUDA","or","there","is","no","GPU","present",",","this","defaults","to","`","timeit.default_timer","`",";","otherwise","it","will","synchronize","CUDA","before","measuring","the","time",".","globals",":","A","dict","which","defines","the","global","variables","when","`","stmt","`","is","being","executed",".","This","is","the","other","method","for","providing","variables","which","`","stmt","`","needs",".","label",":","String","which","summarizes","`","stmt","`",".","For","instance",",","if","`","stmt","`","is","``","torch.nn.functional.relu","(","torch.add","(","x",",","1",",","out=out",")",")","''","one","might","set","label","to","``","ReLU","(","x","+","1",")","''","to","improve","readability",".","sub_label",":","Provide","supplemental","information","to","disambiguate","measurements","with","identical","stmt","or","label",".","For","instance",",","in","our","example","above","sub_label","might","be","``","float","''","or","``","int","''",",","so","that","it","is","easy","to","differentiate",":","``","ReLU","(","x","+","1",")",":","(","float",")","''","``","ReLU","(","x","+","1",")",":","(","int",")","''","when","printing","Measurements","or","summarizing","using","`","Compare","`",".","description",":","String","to","distinguish","measurements","with","identical","label","and","sub_label",".","The","principal","use","of","`","description","`","is","to","signal","to","`","Compare","`","the","columns","of","data",".","For","instance","one","might","set","it","based","on","the","input","size","to","create","a","table","of","the","form",":",":",":","|","n=1","|","n=4","|","...","--","--","--","--","--","--","-","...","ReLU","(","x","+","1",")",":","(","float",")","|","...","|","...","|","...","ReLU","(","x","+","1",")",":","(","int",")","|","...","|","...","|","...","using","`","Compare","`",".","It","is","also","included","when","printing","a","Measurement",".","env",":","This","tag","indicates","that","otherwise","identical","tasks","were","run","in","different","environments",",","and","are","therefore","not","equivalent",",","for","instance","when","A\/B","testing","a","change","to","a","kernel",".","`","Compare","`","will","treat","Measurements","with","different","`","env","`","specification","as","distinct","when","merging","replicate","runs",".","num_threads",":","The","size","of","the","PyTorch","threadpool","when","executing","`","stmt","`",".","Single","threaded","performance","is","important","as","both","a","key","inference","workload","and","a","good","indicator","of","intrinsic","algorithmic","efficiency",",","so","the","default","is","set","to","one",".","This","is","in","contrast","to","the","default","PyTorch","threadpool","size","which","tries","to","utilize","all","cores","."]
docstr: Collect instruction counts using Callgrind.
  
  Unlike wall times, instruction counts are deterministic
  (modulo non-determinism in the program itself and small amounts of
  jitter from the Python interpreter.) This makes them ideal for detailed
  performance analysis. This method runs `stmt` in a separate process
  so that Valgrind can instrument the program. Performance is severely
  degraded due to the instrumentation, however this is ameliorated by
  the fact that a small number of iterations is generally sufficient to
  obtain good measurements.
  
  In order to to use this method `valgrind`, `callgrind_control`, and
  `callgrind_annotate` must be installed.
  
  Because there is a process boundary between the caller (this process)
  and the `stmt` execution, `globals` cannot contain arbitrary in-memory
  data structures. (Unlike timing methods) Instead, globals are
  restricted to builtins, `nn.Modules`'s, and TorchScripted functions/modules
  to reduce the surprise factor from serialization and subsequent
  deserialization. The `GlobalsBridge` class provides more detail on this
  subject. Take particular care with nn.Modules: they rely on pickle and
  you may need to add an import to `setup` for them to transfer properly.
  
  By default, a profile for an empty statement will be collected and
  cached to indicate how many instructions are from the Python loop which
  drives `stmt`.
  
  Returns:
      A `CallgrindStats` object which provides instruction counts and
      some basic facilities for analyzing and manipulating results.
docstr_tok: ["Collect","instruction","counts","using","Callgrind",".","Unlike","wall","times",",","instruction","counts","are","deterministic","(","modulo","non-determinism","in","the","program","itself","and","small","amounts","of","jitter","from","the","Python","interpreter",".",")","This","makes","them","ideal","for","detailed","performance","analysis",".","This","method","runs","`","stmt","`","in","a","separate","process","so","that","Valgrind","can","instrument","the","program",".","Performance","is","severely","degraded","due","to","the","instrumentation",",","however","this","is","ameliorated","by","the","fact","that","a","small","number","of","iterations","is","generally","sufficient","to","obtain","good","measurements",".","In","order","to","to","use","this","method","`","valgrind","`",",","`","callgrind_control","`",",","and","`","callgrind_annotate","`","must","be","installed",".","Because","there","is","a","process","boundary","between","the","caller","(","this","process",")","and","the","`","stmt","`","execution",",","`","globals","`","can","not","contain","arbitrary","in-memory","data","structures",".","(","Unlike","timing","methods",")","Instead",",","globals","are","restricted","to","builtins",",","`","nn.Modules","`","'s",",","and","TorchScripted","functions\/modules","to","reduce","the","surprise","factor","from","serialization","and","subsequent","deserialization",".","The","`","GlobalsBridge","`","class","provides","more","detail","on","this","subject",".","Take","particular","care","with","nn.Modules",":","they","rely","on","pickle","and","you","may","need","to","add","an","import","to","`","setup","`","for","them","to","transfer","properly",".","By","default",",","a","profile","for","an","empty","statement","will","be","collected","and","cached","to","indicate","how","many","instructions","are","from","the","Python","loop","which","drives","`","stmt","`",".","Returns",":","A","`","CallgrindStats","`","object","which","provides","instruction","counts","and","some","basic","facilities","for","analyzing","and","manipulating","results","."]
code: def collect_callgrind(
      self,
      number: int = 100,
      *,
      repeats: Optional[int] = None,
      collect_baseline: bool = True,
      retain_out_file: bool = False,
  ) -> Any:
      """Collect instruction counts using Callgrind.
  
      Unlike wall times, instruction counts are deterministic
      (modulo non-determinism in the program itself and small amounts of
      jitter from the Python interpreter.) This makes them ideal for detailed
      performance analysis. This method runs `stmt` in a separate process
      so that Valgrind can instrument the program. Performance is severely
      degraded due to the instrumentation, however this is ameliorated by
      the fact that a small number of iterations is generally sufficient to
      obtain good measurements.
  
      In order to to use this method `valgrind`, `callgrind_control`, and
      `callgrind_annotate` must be installed.
  
      Because there is a process boundary between the caller (this process)
      and the `stmt` execution, `globals` cannot contain arbitrary in-memory
      data structures. (Unlike timing methods) Instead, globals are
      restricted to builtins, `nn.Modules`'s, and TorchScripted functions/modules
      to reduce the surprise factor from serialization and subsequent
      deserialization. The `GlobalsBridge` class provides more detail on this
      subject. Take particular care with nn.Modules: they rely on pickle and
      you may need to add an import to `setup` for them to transfer properly.
  
      By default, a profile for an empty statement will be collected and
      cached to indicate how many instructions are from the Python loop which
      drives `stmt`.
  
      Returns:
          A `CallgrindStats` object which provides instruction counts and
          some basic facilities for analyzing and manipulating results.
      """
      if not isinstance(self._task_spec.stmt, str):
          raise ValueError(
              "`collect_callgrind` currently only supports string `stmt`"
          )
  
      if repeats is not None and repeats < 1:
          raise ValueError("If specified, `repeats` must be >= 1")
  
      # Check that the statement is valid. It doesn't guarantee success, but it's much
      # simpler and quicker to raise an exception for a faulty `stmt` or `setup` in
      # the parent process rather than the valgrind subprocess.
      self._timeit(1)
      is_python = self._language == Language.PYTHON
      assert is_python or not self._globals
      result = valgrind_timer_interface.wrapper_singleton().collect_callgrind(
          task_spec=self._task_spec,
          globals=self._globals,
          number=number,
          repeats=repeats or 1,
          collect_baseline=collect_baseline and is_python,
          is_python=is_python,
          retain_out_file=retain_out_file,
      )
  
      return result[0] if repeats is None else result
  
imports: import enum
  import timeit
  import textwrap
  from typing import overload, Any, Callable, Dict, List, NoReturn, Optional, Tuple, Type, Union
  import torch
  from torch.utils.benchmark.utils import common, cpp_jit
  from torch.utils.benchmark.utils._stubs import TimerClass, TimeitModuleType
  from torch.utils.benchmark.utils.valgrind_wrapper import timer_interface
label_desc: Use image node_id 12 for calling the Timer obj's underlying member method code with example usage: obj.collect_callgrind(number) and returns: unknown