uniqc.circuit_builder.translate_qasm2_oir module

Translation utilities between OpenQASM 2.0 and OriginIR.

This module provides bidirectional translation between OpenQASM 2.0 and OriginIR quantum circuit representations. It includes direct mapping dictionaries, opcode conversion functions, and multi-controlled gate decomposition.

Key exports:

OriginIR_QASM2_dict: Mapping from OriginIR to QASM2 operations. QASM2_OriginIR_dict: Mapping from QASM2 to OriginIR operations. direct_mapping_qasm2_to_oir: Function for direct QASM2 to OriginIR lookup. get_opcode_from_QASM2: Convert QASM2 operation to OriginIR opcode. get_QASM2_from_opcode: Convert OriginIR opcode to QASM2 operation. decompose_mcx_qasm_text: Decompose multi-controlled X gates for QASM2. decompose_mcu_qasm_text: Decompose multi-controlled single-qubit gates for QASM2.

uniqc.circuit_builder.translate_qasm2_oir.collect_qasm2_custom_gates(opcode_list)

Return the deterministic list of custom gate names this opcode list needs.

Used by Circuit to prepend only the required gate definitions to QASM 2.0 output (rather than always emitting all of them). When xy or uu15 are present we additionally emit ryy first because their definitions reference it and qelib1.inc does not.

Return type:

list[str]

uniqc.circuit_builder.translate_qasm2_oir.decompose_mcu_qasm_text(controls, target, qubit_num, gate_qasm, params)

Decompose an n-control single-qubit gate into QASM 2.0 statements.

Uses two strategies:

• Tier 1 (conjugation, 1 MCX): For gates where G = U·X·U†. Supported: X, Z, Y, S, Sdg, RZ, RX, U1.

• Tier 2 (ABC method, 2 MCX): For gates requiring the general Barenco decomposition A·MCX·B·MCX·C. Supported: U3, RY, SX, H.

Parameters:

• controls (list[int]) – Ordered list of n ≥ 4 control qubit indices.

• target (int) – Target qubit index.

• qubit_num (int) – Total number of qubits declared in the circuit.

• gate_qasm (str) – QASM 2.0 gate name (already dagger-adjusted).

• params (float | list[float] | None) – Gate parameter(s), already dagger-adjusted if applicable.

Returns:

Multi-line QASM 2.0 string.

Raises:

NotImplementedError – Gate is not supported for decomposition.

Return type:

str

uniqc.circuit_builder.translate_qasm2_oir.decompose_mcx_qasm_text(controls, target, qubit_num)

Decompose an n-control X (MCX) gate into QASM 2.0 Toffoli-ladder statements.

Uses a clean-ancilla ladder (Barenco et al. 1995, adapted): n-2 workspace qubits are borrowed from existing circuit qubits not involved in the gate. The workspace qubits must be in state |0⟩ at the call site; they are restored to |0⟩ after the decomposition.

Parameters:

• controls (list[int]) – Ordered list of n ≥ 4 control qubit indices.

• target (int) – Target qubit index.

• qubit_num (int) – Total number of qubits declared in the circuit (qreg q[N]).

Returns:

Multi-line QASM 2.0 string (Toffoli gates only; no semicolon-separated single line — the returned string may contain \n).

Raises:

NotImplementedError – Not enough workspace qubits are available in the circuit. Use OriginIR export (which supports arbitrary-width controlled gates natively) or add workspace qubits to the circuit.

Return type:

str

uniqc.circuit_builder.translate_qasm2_oir.direct_mapping_qasm2_to_oir(qasm2_operation)

Return the corresponding OriginIR by given QASM2 operation. Return None when there is no direct-mapping.

Note: There are also operations that do not sastify “direct mapping” from QASM -> OIR or OIR -> QASM.

uniqc.circuit_builder.translate_qasm2_oir.get_QASM2_from_opcode(opcode)

Return the corresponding QASM2 operation by given OriginIR operation.

Note: Only a subset of QASM2 operations are supported in UnifiedQuantum.

Return type:

tuple[str, int | list[int], int | list[int], float | list[float]]

uniqc.circuit_builder.translate_qasm2_oir.get_opcode_from_QASM2(operation, qubits, cbits, parameters)

Here list all supported operations of OpenQASM2.0 and its corresponding operation in OriginIR in UnifiedQuantum.

Opcode Definition: opcodes = (operation,qubits,cbit,parameter,dagger_flag,control_qubits_set)