mqt.bench.output

Output functions for the MQT Bench module.

Module Contents

class OutputFormat[source]

Bases: enum.StrEnum

Enumeration of supported output formats for circuit export.

QASM2 = 'qasm2'
QASM3 = 'qasm3'
QPY = 'qpy'
extension() → str[source]

Return the canonical filename extension for this format.

exception MQTBenchExporterError[source]

Bases: Exception

Custom exception for errors arising during MQT Bench exporting operations.

generate_header(fmt: OutputFormat, level: BenchmarkLevel, target: Target | None = None) → str[source]

Generate a standardized header for MQT Bench outputs.

Parameters:

  • fmt – The chosen output format enum member

  • level – The level of the circuit (e.g., “nativegates”, “mapped”)

  • target – The transpilation target, if any.

Returns:

A string containing the formatted header.

write_circuit(qc: QuantumCircuit, destination: Path, level: BenchmarkLevel, fmt: OutputFormat = OutputFormat.QASM3, target: Target | None = None) → None[source]
write_circuit(qc: QuantumCircuit, destination: TextIOBase | BinaryIO, level: BenchmarkLevel, fmt: OutputFormat = OutputFormat.QASM3, target: Target | None = None) → None

Write the given quantum circuit to disk in the specified format, preceded by an MQT Bench header.

Parameters:

  • qc – The QuantumCircuit to export

  • destination – Destination file path or stream (including extension)

  • level – The level of the circuit (e.g., BenchmarkLevel.MAPPED)

  • fmt – Desired output format

  • target – The target circuit to be transpiled, if any.

Raises:

MQTBenchExporterError – On unsupported format or I/O errors.

save_circuit(qc: QuantumCircuit, filename: str, level: BenchmarkLevel, output_format: OutputFormat = OutputFormat.QASM3, target: Target | None = None, target_directory: str = '') → bool[source]

Public API to save a quantum circuit in various formats with MQT Bench header.

Parameters:

  • qc – Circuit to export

  • filename – Base filename without extension

  • level – Level of the circuit (e.g., BenchmarkLevel.MAPPED)

  • output_format – One of the supported format values, as defined in OutputFormat

  • target – Target circuit to be transpiled, if any

  • target_directory – Directory to place the output file

Returns:

True on success, False otherwise.

generate_filename(benchmark_name: str, level: BenchmarkLevel, num_qubits: int | None, target: Target | None = None, opt_level: int | None = None, generate_mirror_circuit: bool = False) → str[source]

Generate a benchmark filename based on the abstraction level and context.

Parameters:

  • benchmark_name – name of the quantum circuit

  • level – abstraction level

  • num_qubits – number of qubits in the benchmark circuit

  • target – target device (e.g., BenchmarkLevel.MAPPED)

  • opt_level – optional optimization level (used for ‘nativegates’ and ‘mapped’)

  • generate_mirror_circuit – whether this is a mirror circuit

Returns:

A string representing a filename (excluding extension) that encodes all relevant metadata for reproducibility and clarity.