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:
a str (TraceDir) that points to parent path of the trace files.
a Trace object that contains the trace records and metadata.
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:
a str (TraceDir) that points to parent path of the trace files.
a Trace object that contains the trace records and metadata.
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