# qairt.api.common.backends.common.tuner

- *class* qairt.api.common.backends.common.tuner.Criteria(*value*)

    - Bases: `str`, `Enum`

Enum representing criteria types.

- BANDWIDTH *= 'bandwidth'*

    - 

- LATENCY *= 'latency'*

    - 

- *static* is\_valid\_criteria(*criteria\_str: str*) → bool

    -

- qairt.api.common.backends.common.tuner.get\_context\_size\_info(*model: [CompiledModel](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-core-api.html#qairt.CompiledModel)*) → Dict[str, Any]

    - Get both ROM and RAM size info from a compiled context binary in a single utility call.

Reads the `qnn-context-binary-utility` output once and returns both the ROM size
(`contextBlobSize`) and the per-field RAM breakdown, summed across all graphs. Use this when
sweeping for both metrics at once so the (relatively cheap) utility call is not duplicated.

- Parameters

    - **model** ([*CompiledModel*](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-core-api.html#qairt.CompiledModel)) – Compiled model backed by a context binary.

- Returns

    - `{"rom": int, "ram": {field: bytes, ..., "total": int}}`.

- Return type

    - dict

- Raises

    - **CompilationError** – If the size info cannot be determined.

- qairt.api.common.backends.common.tuner.get\_graph\_names(*model: [Model](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-core-api.html#qairt.Model)*) → List[str]

    - Get graph names to update graph\_custom\_config.

- Parameters

    - **model** ([*Model*](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-core-api.html#qairt.Model)) – Model or compiled model exposing `module.info`.

- Returns

    - List of graph names.

- Return type

    - list

- qairt.api.common.backends.common.tuner.get\_report\_details(*profiler: [Profiler](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-core-api.html#qairt.Profiler)*, *criteria: [Criteria](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-api-common-backends-common.html#qairt.api.common.backends.common.tuner.Criteria)*) → Tuple[int, [OpTraceReport](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-api-profiler.html#qairt.api.profiler.report.OpTraceReport)]

    - Generate report and extract criteria value.

- Parameters

    - - **profiler** ([*Profiler*](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-core-api.html#qairt.Profiler)) – Profiler object.
- **criteria** ([*Criteria*](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-api-common-backends-common.html#qairt.api.common.backends.common.tuner.Criteria)) – Criteria for optimization.

- Returns

    - Criteria value and report data.

- Return type

    - tuple

- qairt.api.common.backends.common.tuner.optimize(*model: [Model](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-core-api.html#qairt.Model)*, *criteria: str*, *compile\_args: dict*, *execution\_args: dict*) → Tuple[[CompiledModel](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-core-api.html#qairt.CompiledModel), [OpTraceReport](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-api-profiler.html#qairt.api.profiler.report.OpTraceReport)]

    - Optimize the given model based on the specified criteria.

- Parameters

    - - **model** ([*Model*](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-core-api.html#qairt.Model)) – The model to be optimized.
- **criteria** (*str*) – The optimization criteria (options: latency, bandwidth).
- **compile\_args** (*dict*) – A dictionary of arguments for the compilation process.
See [`qairt.compile()`](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-core-api.html#qairt.compile) for the full list of compile\_args.
- **execution\_args** (*dict*) – A dictionary of arguments for the execution process.
See `qairt.api.compiled_model.CompiledModel.__call__()` for the full list
of execution\_args. Note that an instance of [`qairt.api.configs.device.Device`](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-api-configs.html#qairt.api.configs.device.Device)
must be provided.

Example

from qairt import Model, CompileConfig, ExecutionConfig, Device, DevicePlatformType
    from qairt.api.common.backends.common import tuner
    
    model = qairt.load("model.dlc")
    device = qairt.Device(type=DevicePlatformType.ANDROID, identifier="abcd123")
    compile_args = {"config": CompileConfig(backend="HTP")}  # Replace with your compile arguments
    execution_args={"inputs": {"input1": input_data}, "device": device}  # Replace with your execution arguments
    optimized_model, report = tuner.optimize(model, "latency", compile_args, execution_args)
    Copy to clipboard

- Returns

    - The optimized model and corresponding op trace report.

- Return type

    - tuple

- qairt.api.common.backends.common.tuner.optimizeROMandRAM(*model\_path: str*, *config\_path: str*, *output\_path: str = 'size\_optimized'*, *max\_workers: int = 1*, *k: int = 1*) → str

    - Sweep all P-values once and report both ROM and RAM, selecting the best config for each.

Each P-value is compiled offline (no device required) in a **separate OS process**, and for
each compiled binary both the ROM size (`contextBlobSize`) and the RAM footprint
(opData/const/io/ddr/spillFill) are read in one `qnn-context-binary-utility` call. The
smallest ROM and the smallest RAM are tracked independently (the winning P-value may differ
between them) and the optimized binaries, their configs, and a combined report are written to
`output_path`.

Compilation dominates runtime, so measuring both metrics from the same binary avoids a second
full sweep. Running each compile in a child process (even at `max_workers=1`) keeps the sweep
interruptible: the prepare itself is uninterruptible native code, but Ctrl+C / kill on the
parent terminates the child processes promptly.

- Parameters

    - - **model\_path** (*str*) – Path to the input DLC (`.dlc`, typically quantized).
- **config\_path** (*str*) – Path to a backend-extension JSON config file (the same format consumed
by `qnn-context-binary-generator --config_file`). Base settings such as `vtcm_mb`
and the device `dsp_arch`/`soc_model` are honored; `O` and `finalize_config`
are overridden per P-value during the sweep.
- **output\_path** (*str*) – Directory to write the outputs to. Created if it does not exist. Any
`rom_optimized*` / `ram_optimized*` files left over from a previous run into this
same directory are removed before the sweep starts.
- **max\_workers** (*int*) – Number of P-value compilations to run concurrently. Default 1. Each
compile is itself heavily multi-threaded and memory-hungry, so keep this small (2-4);
large values oversubscribe CPU/RAM and can be slower or run out of memory.
- **k** (*int*) – Number of best models to keep for each of ROM and RAM, ranked best-first. Default
1. Ranks 2..K are written with a `_rank<r>` suffix.

Example

from qairt.api.common.backends.common import tuner
    
    tuner.optimizeROMandRAM("encode_quantized.dlc", "config.json", max_workers=4, k=3)
    Copy to clipboard

- Returns

    - - The `output_path` directory containing:
    - - `rom_optimized_context_binary.bin` + `rom_optimized_config.json`: smallest ROM
(ranks 2..K as `rom_optimized_rank<r>_context_binary.bin` / `..._config.json`),
- `ram_optimized_context_binary.bin` + `ram_optimized_config.json`: smallest RAM
(ranks 2..K as `ram_optimized_rank<r>_context_binary.bin` / `..._config.json`),
- `size_report.json`: per-P ROM and RAM sizes, baselines, the `top_k_rom` /
`top_k_ram` rankings, the RAM per-field breakdown for the baseline and each winner,
and `per_p_errors` with the failure reason for any P-value that failed to compile.

- Return type

    - str

- qairt.api.common.backends.common.tuner.update\_graph\_configs(*config: [CompileConfig](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-api-compiler.html#qairt.api.compiler.config.CompileConfig)*, *p\_value: int*, *graph\_names: List[str]*) → [CompileConfig](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-api-compiler.html#qairt.api.compiler.config.CompileConfig)

    - Set optimization\_type and add finalize\_config to graph\_custom\_configs.

- Parameters

    - - **config** ([*CompileConfig*](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-api-compiler.html#qairt.api.compiler.config.CompileConfig)) – Compilation configuration.
- **p\_value** (*int*) – P value for optimization.
- **graph\_names** (*list*) – List of graph names.

- Returns

    - Updated compilation configuration.

- Return type

    - [CompileConfig](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-api-compiler.html#qairt.api.compiler.config.CompileConfig)

- qairt.api.common.backends.common.tuner.validate\_backend\_type(*value: str*)

    - Validate backend type.

- Parameters

    - **value** – Backend type value.

- Raises

    - **ValueError** – If the backend type is not supported.

Last Published: Sep 17, 2026

[Previous Topic
qairt.api.common.backends.htp\_mcp](https://docs.qualcomm.com/bundle/publicresource/80-87189-2/topics/qairt-api-common-backends-htp_mcp.md) [Next Topic
qairt.api.compiler](https://docs.qualcomm.com/bundle/publicresource/80-87189-2/topics/qairt-api-compiler.md)