compile

compile(input: Sequence[Circuit | UnitaryMatrix | StateVector | StateSystem], model: MachineModel | None = None, *, with_mapping: Literal[False] = False, optimization_level: int = 1, max_synthesis_size: int = 3, synthesis_epsilon: float = 1e-08, error_threshold: float | None = None, error_sim_size: int = 8, compiler: Compiler | None = None, seed: int | None = None, **compiler_kwargs: Any) → list[Circuit]

compile(input: Sequence[Circuit | UnitaryMatrix | StateVector | StateSystem], model: MachineModel | None = None, *, with_mapping: Literal[True], optimization_level: int = 1, max_synthesis_size: int = 3, synthesis_epsilon: float = 1e-08, error_threshold: float | None = None, error_sim_size: int = 8, compiler: Compiler | None = None, seed: int | None = None, **compiler_kwargs: Any) → list[tuple[Circuit, tuple[int, ...], tuple[int, ...]]]

compile(input: Sequence[Circuit | UnitaryMatrix | StateVector | StateSystem], model: MachineModel | None = None, *, with_mapping: bool, optimization_level: int = 1, max_synthesis_size: int = 3, synthesis_epsilon: float = 1e-08, error_threshold: float | None = None, error_sim_size: int = 8, compiler: Compiler | None = None, seed: int | None = None, **compiler_kwargs: Any) → list[Circuit] | list[tuple[Circuit, tuple[int, ...], tuple[int, ...]]]

Compile a circuit, unitary, or state with a standard workflow.

Parameters:

input (CompilationInputLike | Sequence[CompilationInput]) – The input or inputs to compile. If a single input is given, a single circuit will be returned. If an iterable of inputs is given, a list of circuits will be returned.
model (MachineModel | None) – A model of the target machine. Defaults to an all-to-all connected hardware with CNOTs and U3s as native gates. See MachineModel for information on loading a preset model or creating a custom one.
optimization_level (int) – The degree of optimization in the workflow. The workflow will produce better circuits at the cost of performance with a higher number. An optimization_level of 0 is not supported due to inherit optimization in any workflow containing synthesis. Valid inputs are 1, 2, 3, or 4. (Default: 1)
max_synthesis_size (int) – The maximum size of a unitary to synthesize or instantiate. Larger circuits will be partitioned. Increasing this will most likely lead to better results with an exponential time trade-off. (Default: 3)
synthesis_epsilon (float) – The maximum distance between target and circuit unitary during any instantiation or synthesis algorithms. (Default: 1e-8)
error_threshold (float | None) – This parameter controls the verification mechanism in this compile function. By default, it is set to None, so no verification is done. If you set this to a float, the upper bound on compilation error is calculated. If the upper bound is larger than this number, a warning will be logged. (Default: None)
error_sim_size (int) – If an error_threshold is set, the error upper bound is calculated by simulating blocks of this size. As you increase error_sim_size, the upper bound on error becomes more accurate. This setting is ignored with direct synthesis compilations, i.e., when a state, system, or unitary are given as input. (Default: 8)
compiler (Compiler | None) – Pass a Compiler to prevent creating one. Save on startup time by passing a compiler in when calling compile multiple times. (Default: None)
seed (int | None) – Set a seed for the compile function for better reproducibility. If left as None, will not set seed.
with_mapping (bool) – If True, three values will be returned instead of just the compiled circuit. The first value is the compiled circuit, the second value is the initial mapping, and the third value is the final mapping. The initial mapping is a tuple where initial_mapping[i] = j implies that logical qudit i in the input system starts on the physical qudit j in the output circuit. Likewise, the final mapping describes where the logical qudits are in the physical circuit at the end of execution. (Default: False)
compiler_kwargs (Any) – Passed directly to BQSKit compiler construction. Arguments for connecting to a cluster can go here. See Compiler for more info.

Returns:

The compiled circuit.

Return type:

(Circuit)

Examples

>>> from bqskit import Circuit, compile
>>> circuit = Circuit.from_file('input.qasm')
>>> compiled_circuit = compile(circuit)
>>> compiled_circuit.save('output.qasm')

>>> from bqskit import compile
>>> from bqskit.qis.state import StateVector
>>> state = StateVector.random(3)
>>> compiled_circuit = compile(state)
>>> compiled_circuit.save('output.qasm')

>>> from bqskit import compile
>>> from bqskit.qis.unitary import UnitaryMatrix
>>> utry = UnitaryMatrix.random(3)
>>> compiled_circuit = compile(utry)
>>> compiled_circuit.save('output.qasm')

>>> from bqskit import compile, Circuit
>>> circuits = [Circuit.from_file(f'input{i}.qasm') for i in range(5)]
>>> compiled_circuits = compile(circuits)
>>> for i, circuit in enumerate(compiled_circuits):
...     circuit.save(f'output{i}.qasm')

>>> from bqskit import compile, Circuit, MachineModel
>>> from bqskit.ir.gates import CZGate, RZGate, SqrtXGate
>>> target_gate_set = {CZGate(), RZGate(), SqrtXGate()}
>>> circuit = Circuit.from_file('input.qasm')
>>> model = MachineModel(circuit.num_qudits, gate_set=target_gate_set)
>>> compiled_circuit = compile(circuit, model, optimization_level=2)

You can also use pre-built models from the ext package for common hardware. For example, to compile to the H1-1 machine from Quantinuum:

>>> from bqskit import compile, Circuit
>>> from bqskit.ext import H1_1Model
>>> circuit = Circuit.from_file('input.qasm')
>>> compiled_circuit = compile(circuit, H1_1Model)

Raises:

ValueError – If the input is an empty iterable.
ValueError – If the input (or any input) is larger than the model.
ValueError – If either the input or the model has mixed radixes.
ValueError – If the model has a mismatched radix with the circuit.
ValueError – If the model doesn’t contain any entangling gates and the input (or any input) is larger than one-qudit.
ValueError – If the model does not contain any entangling gates that are less than or equal to the input size.
ValueError – If optimization_level is not 1, 2, 3, or 4.
ValueError – If the maximum synthesis size is less than the largest gate in the model.
ValueError – If the maximum synthesis size is less than 2.
ValueError – If the synthesis epsilon is not between 0 and 1.
ValueError – The error simulation size is less than the maximum synthesis size.