Trace Diff API

class hta.trace_diff.TraceDiff[source]
classmethod compare_traces(control: Union[LabeledTrace, str], test: Union[LabeledTrace, str], control_rank: Optional[Union[int, List[int]]] = None, test_rank: Optional[Union[int, List[int]]] = None, control_iteration: Optional[Union[int, List[int]]] = None, test_iteration: Optional[Union[int, List[int]]] = None, device_type: DeviceType = DeviceType.ALL, use_short_name: bool = False) → DataFrame[source]

Compare the operators/kernels counts and total duration of two traces.

Parameters

  • control (Union[LabeledTrace, Trace, TraceDir]) –

    the control trace. A string or Trace object that defines the control trace. Possible values can be:

    1. a str (TraceDir) that points to parent path of the trace files.

    2. a Trace object that contains the trace records and metadata.

    3. a LabeledTrace object, which is a wrapper of the Trace object with a label to identify the trace.

  • test (Union[LabeledTrace, Trace, TraceDir]) – the test trace. Similar to the control trace except it defines the test trace.

  • control_rank (Optional[Union[int, List[int]]]) – Specify which ranks of the control trace to use. This argument can be either a single rank (an integer) or multiple ranks (a list of integers). Default: use the first rank of the control traces for comparison

  • test_rank (Optional[Union[int, List[int]]]) – Default: use the first rank of the test traces for comparison

  • control_iteration (Optional[Union[int, List[int]]]) – Specify which iteration(s) of the control trace to use for the comparison. Default: use the first iteration of the control trace.

  • test_iteration (Optional[Union[int, List[int]]]) – Specify which iteration(s) of the test trace to use for the comparison. Default: use the first iteration of the test trace.

  • device_type (DeviceType) – Specify whether to compare CPU operators or GPU kernels or both. + device_type = DeviceType.CPU compares CPU operators only. + device_type = DeviceType.GPU compares GPU kernels only. + device_type = DeviceType.ALL compares both CPU operators and GPU kernels. Default: DeviceType.ALL

  • use_short_name (bool) – should the comparison use a shorter name? The CPU operator and CUDA kernel name in the trace can be too long to comprehend. The use_short_name argument removes the functional arguments, template arguments, and return values so that the name is easy to follow. Default: False.

Returns

pd.DataFrame

A DataFrame that summarizes the difference between the two traces with the following columns:

  • name (or short_name): the operator or kernel name. If use_short_name = True, then short name will be used.

  • control_counts: the number of times an op occurs in the control trace.

  • test_counts: the number of times an op occurs in the test trace.

  • control_total_duration: the total duration of the ops in the control trace.

  • test_total_duration: the total duration of the ops in the test trace.

  • diff_counts: the difference in the counts, i.e. test_counts - control_counts.

  • diff_duration: the difference in total duration, i.e. test_total_duration - control_total_duration.

  • counts_change_categories: the type of changes. ‘=’ (no change); ‘+’ (more ops in test_trace); ‘-’ (fewer ops in test_trace).

Note

The unit for all the duration columns is microsecond (us).

classmethod ops_diff(control: Union[LabeledTrace, str], test: Union[LabeledTrace, str], control_rank: Optional[Union[int, List[int]]] = None, test_rank: Optional[Union[int, List[int]]] = None, control_iteration: Optional[Union[int, List[int]]] = None, test_iteration: Optional[Union[int, List[int]]] = None, device_type: DeviceType = DeviceType.ALL) → Dict[str, List[str]][source]

Get the operator difference between two traces.

Parameters

  • control (Union[LabeledTrace, Trace, TraceDir]) –

    The control trace. A string or Trace object that defines the control trace. A possible value can be:

    1. a str (TraceDir) that points to parent path of the trace files.

    2. a Trace object that contains the trace records and metadata.

    3. a LabeledTrace object, which is a wrapper of the Trace object with a label to identify the trace.

  • test (Union[LabeledTrace, Trace, TraceDir]) – The test trace. Similar to the control trace except it defines the test trace.

  • control_rank (Optional[Union[int, List[int]]]) – Specify which ranks of the control trace to use. This argument can be either a single rank (an integer) or multiple ranks (a list of integers). Default: use the first rank of the control traces for comparison

  • test_rank (Optional[Union[int, List[int]]]) – of the test trace to use. See control_rank for usage. Default: use the first rank of the test traces for comparison

  • control_iteration (Optional[Union[int, List[int]]]) – Specify which iteration(s) of the control trace to use for the comparison. Default: use the first iteration of the control trace.

  • test_iteration (Optional[Union[int, List[int]]]) – Specify which iteration(s) of the test trace to use for the comparison. Default: use the first iteration of the test trace.

  • device_type (DeviceType) – Specify whether to compare CPU operators or GPU kernels or both. DeviceType.CPU, DeviceType.GPU, DeviceType.ALL compares CPU operators only, GPU kernels only, both CPU operators and GPU kernels respectively. Default: DeviceType.ALL

Returns

Dict[str, List[str]]

The operator/kernel changes are divided into five types:

  • added: ops which are absent in control_trace but exist in test_trace.

  • deleted: ops which exist in control_trace but are absent in test_trace.

  • increased: ops which exist in both traces but occur more times in test_trace.

  • decreased: ops which exist in both traces but occur fewer times in test_trace.

  • unchanged: ops which exist in both traces and occur the same number of times.

classmethod visualize_counts_diff(df: DataFrame, show_image: bool = True, export_image_path: Optional[str] = None) → None[source]

Visualize the changes in trace ops count using the output from compare_traces.

Parameters

  • df (pd.DataFrame) – the result obtained from TraceDiff.compare_traces.

  • show_image (bool) – set to True to display the image. Default = True.

  • export_image_path (str) – location where the image is saved.

Returns

None

classmethod visualize_duration_diff(df: DataFrame, show_image: bool = True, export_image_path: Optional[str] = None) → None[source]

Visualize the changes in trace ops duration using the output from compare_traces.

Parameters

  • df (pd.DataFrame) – the result obtained from TraceDiff.compare_traces.

  • show_image (bool) – set to True to display the image. Default = True.

  • export_image_path (str) – location where the image is saved.

Returns

None