General Application Autotuning API

class ApproxApp(op_knobs, target_device=None)[source]

Generic approximable application with operator & knob enumeration, and measures its own QoS and cost given a configuration. (A configuration is a dictionary from operator name to a knob name.) To use this class, inherit from it and implement name and measure_qos_cost.

Parameters

  • op_knobs (Dict[str, List[ApproxKnob]]) – a mapping from each operator (identified by str) to a list of applicable knobs.

  • target_device (Optional[str]) – the target device that this application should be tuned on. Each knob has a number of devices it is supported on (see ApproxKnob.exists_on_device) and only knobs supported on target_device will be used for this application.

Variables

baseline_knob – The baseline knob of this application. This is derived by looking at all knobs defined in op_knobs and deciding which is the baseline.

add_baseline_to_knobs(approxes)[source]

For each operator not appearing in the keys of configuration approxes (a dictionary), map it to the baseline (see ApproxApp.baseline_knob).

measure_qos_cost should call this on the incoming config if you wish to be able to abbreviate the configuration (for example, you can write measure_qos_cost({}) to get the baseline QoS). This ensures all operators are present when the config is sent to tuner.

Parameters

approxes (Dict[str, str]) – the config to add baseline knobs to.

Return type

Dict[str, str]

get_tuner()[source]

Sets up an ApproxTuner instance which the user can directly call tune() on with opentuner parameters.

Return type

predtuner.approxapp.ApproxTuner

property knobs

A list of all unique knobs (see ApproxKnob) applicable to operators in this application.

Return type

List[ApproxKnob]

abstract measure_qos_cost(with_approxes, is_test)[source]

Measures the QoS and cost (time, energy, …) of a given configuration.

Parameters

  • with_approxes (Dict[str, str]) – The approximation configuration to measure QoS and cost for.

  • is_test (bool) – If True, uses a “test” dataset/mode that is held away from the tuner during tuning; otherwise use “tune” dataset. How the “tune” and “test” mode behave is up to the user to define.

Return type

Tuple[float, float]

abstract property name

The name of this application. Acts as an identifier in many places, so the user should try to make it unique.

Return type

str

property ops

A list of operators in this application.

Return type

List[str]

class ApproxTuner(app)[source]

Supports tuning and holds all tuning results. ApproxTuner.tune is the main method for tuning.

An instance of ApproxTuner can be obtained from ApproxApp.get_tuner.

Parameters

app – the application to tune.

dump_configs(filepath, best_only=True)[source]

Writes configuration to a JSON file.

Parameters

  • filepath (Union[pathlib.Path, str]) – The JSON file to write into.

  • best_only (bool) – If True, only writes the “best” configuration (filtered after running on test dataset, if required). Otherwise, writes all configurations within the given QoS threshold.

plot_configs(show_qos_loss=False, connect_best_points=False)[source]

Plots 1 or 2 QoS-vs-speedup scatter plot of configurations.

All kept configurations and all “best” configurations (before test-set filtering if any) are always plotted in the first subplot. If test-set filtering was used, the second subplot contains the “best” configurations plotted twice, with tune-set and test-set QoS loss respectively.

Parameters

  • show_qos_loss (bool) – If True, uses the loss of QoS (compared to the baseline) instead of the absolute QoS in the first graph. This does not apply to the second graph if it exists, which always use QoS loss for ease of comparison.

  • connect_best_points (bool) –

Return type

matplotlib.figure.Figure

tune(max_iter, qos_tuner_threshold, qos_keep_threshold=None, is_threshold_relative=False, take_best_n=None, test_configs=True, app_kwargs=None)[source]

Runs a tuning session.

Parameters

  • max_iter (int) – Number of iterations to use in tuning.

  • qos_tuner_threshold (float) – The QoS threshold that the tuner should aim for. QoS is assumed to be a higher-better quantity. This should be slightly tighter than qos_keep_threshold to account for extra error when running on test dataset.

  • qos_keep_threshold (Optional[float]) – The QoS threshold beyond which we will keep the configuration. By default it is equal to qos_keep_threshold.

  • is_threshold_relative (bool) – If True, the actual thresholds are considered to be baseline_qos - given_threshold. This applies to qos_tuner_threshold and qos_keep_threshold.

  • take_best_n (Optional[int]) – Take the best \(n\) configurations after tuning. “Best” is defined as the configurations closest to the pareto curve of the QoS-cost tradeoff space. If take_best_n is None, only the configurations strictly on the pareto curve are taken.

  • test_configs (bool) – If True, runs the configs on the test dataset, filter the taken configs by qos_keep_threshold, and fill the test_qos field of Config.

  • app_kwargs (Optional[dict]) – Additional arguments to pass to ApproxApp.measure_qos_cost during tuning.

Return type

List[T]

property tuned

Returns True if tune has been called at least once.

class ApproxKnob(name, devices=None, baseline_priority=None)[source]

Basic definition of an approximation knob. An approximation knob is an instance of a type of approximation; for example, Perforated Convolution is a type of approximation, while row-perforated convolution with stride 2 is a knob.

Parameters

  • name – The name of this approximation knob. Must be unique throughout.

  • devices – The devices this knob can be applied on. Default is None which means all devices are supported.

exists_on_device(device)[source]

Returns True if this knob can be applied to an ApproxApp on device device.

Parameters

device (str) – The device to check for.

Return type

bool

class Config(qos, cost, knobs, test_qos=None)[source]

An approximation configuration with its measurement results, including QoS and cost.

Parameters

  • qos – The QoS of this config (measured on tuning mode, see ApproxApp.measure_qos_cost).

  • cost – The relative cost (time, energy, etc.) of this config compared to the baseline config. This is essentially \(1 / speedup\).

  • knobs – The op-knob mapping in this configuration.

  • test_qos – The QoS of this config on test mode (see ApproxApp.measure_qos_cost). This is optional as it is filled in only after the config-testing phase (which can be opt out of). See ApproxTuner.tune.