Advanced Features

Branch Optimization

We optimize the conditional branching statements using the following techniques:

Branch Elimination: We evaluate the outcome of the branch condition, if it is known at compile time and does not contain measurement results of qubits. We remove the branch statement and if it evaluates to a true value, attach the corresponding block of code to the main program.

Elimination

import pyqasm

qasm_code = """
OPENQASM 3.0;
include "stdgates.inc";
qubit[1] q;
bit[1] c;
int[32] a = 0;
if(a > 0){
h q[0];
}
if(a < 0){
x q[0];
}
if(a == 0){
y q[0];
measure q -> c;
}
"""
module = pyqasm.loads(qasm_code)
module.unroll()

print(pyqasm.dumps(module))

Output

OPENQASM 3.0;
include "stdgates.inc";
qubit[1] q;
bit[1] c;
y q[0];
c[0] = measure q[0];

Branch Unfolding: If the branch condition contains measurement results of qubits, we unfold the classical registers into individual bits and insert equivalent conditional statements for each bit. This method is particularly useful for systems which do not support multi-bit classical registers in conditional statements.

Unfolding

import pyqasm

qasm_code = """OPENQASM 3.0;
include "stdgates.inc";
qubit[1] q;
bit[4] c;
if(c == 3){
h q[0];
}
if(c >= 3){
h q[0];
} else {
x q[0];
}
if(c <= 3){
h q[0];
} else {
x q[0];
}
if(c < 4){
h q[0];
} else {
x q[0];
}
"""
module = pyqasm.loads(qasm_code)
module.unroll()

print(pyqasm.dumps(module))

Output

OPENQASM 3.0;
include "stdgates.inc";
qubit[1] q;
bit[4] c;
if (c[0] == false) {
  if (c[1] == false) {
    if (c[2] == true) {
      if (c[3] == true) {
        h q[0];
      }
    }
  }
}
if (c[2] == true) {
  if (c[3] == true) {
    h q[0];
  } else {
    x q[0];
  }
} else {
  x q[0];
}
if (c[0] == false) {
  if (c[1] == false) {
    h q[0];
  } else {
    x q[0];
  }
} else {
  x q[0];
}
if (c[0] == false) {
  if (c[1] == false) {
    h q[0];
  } else {
    x q[0];
  }
} else {
  x q[0];
}

Switch Case Optimization

The openqasm reference enforces the switch targets to be of type int and the cases to be unique integer literals or constant integer expressions. This implies that the switch case statements can be optimized at compile time as long as the target variable is not dependent on a measurement result.

Once the target variable is evaluated at compile time, the switch statement is removed and the corresponding switch case code block is attached to the main program.

Switch Case

import pyqasm

qasm_code = """
OPENQASM 3.0;
include "stdgates.inc";

    const int i = 1;
    qubit q;

    switch(i) {
    case 1,3,5,7 {
        int j = 4; // definition inside scope
        switch(j) {
            case 1,3,5,7 {
                x q;
            }
            case 2,4,6,8 {
                j = 5; // assignment inside scope
                y q; // this will be executed
            }
            default {
                z q;
            }
        }
    }
    case 2,4,6,8 {
        y q;
    }
    default {
        z q;
    }
    }

"""
module = pyqasm.loads(qasm_code)
module.unroll()

print(pyqasm.dumps(module))

Output

OPENQASM 3.0;
include "stdgates.inc";
qubit[1] q;
y q[0];

Subroutine Inlining

Subroutine inlining is the process of replacing a subroutine call with the actual code of the subroutine. Since quantum devices do not support subroutines, it is essential to inline the subroutine code against the call to the subroutine. Here, the formal parameters of the subroutine are replaced with the actual parameters used in the subroutine call. Moreover, the subroutine code is inserted at the location of the subroutine call with careful consideration of the scope of the variables used in the subroutine.

Inlining

import pyqasm

qasm_code = """OPENQASM 3.0;
include "stdgates.inc";

    gate my_gate(a) q2 {
        rx(a) q2;
    }

    def my_function(qubit a, float[32] b) {
        float[64] c = 2*b;
        my_gate(b) a;
        my_gate(c) a;
        return;
    }
    qubit q;
    float[32] r = 3.14;
    my_function(q, r);

"""
module = pyqasm.loads(qasm_code)
module.unroll()

print(pyqasm.dumps(module))

Output

OPENQASM 3.0;
include "stdgates.inc";
qubit[1] q;
rx(3.14) q[0];
rx(6.28) q[0];

Loop Unrolling

Loop unrolling is the process of unfolding a loop with a list of equivalent instructions. This is particularly important for quantum programs as quantum computers do not support direct execution of loops. We provide support for unrolling while and for loops -

while Loop
- We evaluate the loop conditions at compile time and visit the loop body till the condition becomes false.

Unroll while

import pyqasm

qasm_code = """
OPENQASM 3.0;
qubit[4] q;
int i = 0;
while (i < 3) {
h q[i];
cx q[i], q[i+1];
i += 1;
}

"""
module = pyqasm.loads(qasm_code)
module.unroll()

print(pyqasm.dumps(module))

Output

OPENQASM 3.0;
qubit[4] q;
h q[0];
cx q[0], q[1];
h q[1];
cx q[1], q[2];
h q[2];
cx q[2], q[3];

To ensure that the unrolling process does not go into an infinite loop, we have introduced a max_loop_iters parameter. It has a default value of 1e9 and allows the user to control the max number of loop iterations -

Max Loop Iterations

import pyqasm

qasm_code = """
OPENQASM 3.0;
qubit[100] q;
int i = 0;
while (i < 50) {
h q[i];
cx q[i], q[i+1];
i += 1;
}

"""
module = pyqasm.loads(qasm_code)

# set max loop iterations to 10

module.unroll(max_loop_iters=10)

print(pyqasm.dumps(module))

Output

ERROR:pyqasm: Error at line 5, column 0 in QASM file

 >>>>>> while (i < 50) {
    h q[i];
    cx q[i], q[i + 1];
    i += 1;
}

...

LoopLimitExceededError: Loop exceeded max allowed iterations

This unrolling process is not applicable in a case when the while condition is dependent on a quantum measurement result. Since the truth value of the condition can only be known at runtime, an exception is raised while unrolling such loops -

Unroll while

import pyqasm

qasm_code = """
OPENQASM 3.0;
qubit q;
bit c;
c = measure q;
while (c) {
h q;
c = measure q;
}

"""
module = pyqasm.loads(qasm_code)
module.unroll()

print(pyqasm.dumps(module))

Output

ERROR:pyqasm: Error at line 6, column 4 in QASM file

 >>>>>> while (c) {
    h q;
    c = measure q;
}

....

ValidationError: Cannot unroll while-loop with condition depending on quantum measurement
result.

Unrolling while loops which contain quantum measurements is, in fact, an active area of development. Some researchers have proposed to identify such loops and convert them into a native while loop instructions which can be executed during runtime. However, this approach has not been fully implemented yet.

for Loop
- The process is similar to the while loop unrolling process, but the loop counter is chosen from the range provided by the user. The loop body is executed as many times as the range value -

Unroll for

import pyqasm

qasm_code = """
OPENQASM 3.0;
include "stdgates.inc";

qubit[4] q;
bit[4] c;

h q;
for int i in [0:2]{
cx q[i], q[i+1];
}
c = measure q;
"""
module = pyqasm.loads(qasm_code)
module.unroll()

print(pyqasm.dumps(module))

Output

OPENQASM 3.0;
include "stdgates.inc";
qubit[4] q;
bit[4] c;
h q[0];
h q[1];
h q[2];
h q[3];
cx q[0], q[1];
cx q[1], q[2];
cx q[2], q[3];
c[0] = measure q[0];
c[1] = measure q[1];
c[2] = measure q[2];
c[3] = measure q[3];

Qubit Register Consolidation

This feature enables the transformation of multiple named qubit registers into a single unified register named __PYQASM_QUBITS__. This simplifies register management and prepares the circuit for hardware-specific or simulator-specific backends that expect a flat register structure.

Usage

qc = pyqasm.loads(qasm_file)
qc.unroll(consolidate_qubits = True)

Key Features:

If device_qubits is provided while loading the QASM file, enforces a qubit limit and validates register size.
```
pyqasm.loads(qasm_file, device_qubits = 10)
```
If not provided, the unified register size equals the total number of qubits across all original registers.
Updates all qubit references in the code to align with the new unified register.

Examples:

QASM-Code

import pyqasm
qasm_code = """
OPENQASM 3.0;
qubit[2] q1;
qubit[3] q2;
cx q1[0], q2[2];
"""
module = pyqasm.loads(qasm_code)
module.unroll(consolidate_qubits=True)

print(pyqasm.dumps(module))

output

OPENQASM 3.0;
qubit[5] __PYQASM_QUBITS__;
cx __PYQASM_QUBITS__[0], __PYQASM_QUBITS__[4];

QASM-Code

import pyqasm
qasm_code = """
OPENQASM 3.0;
qubit[2] q1;
qubit[2] q2;
cx q1[1], q2[0];
"""
module = pyqasm.loads(qasm_code, device_qubits = 5)
module.unroll(consolidate_qubits=True)

print(pyqasm.dumps(module))

output

OPENQASM 3.0;
qubit[5] __PYQASM_QUBITS__;
cx __PYQASM_QUBITS__[1], __PYQASM_QUBITS__[2];

Circuit Timing Operations

In OpenQASM 3, circuit execution is not only determined by gate order but also by explicit timing primitives that define time and duration of operations. PyQASM now supports the following timing operations:

Operations:

duration - A typed literal or variable representing an explicit length of time, expressed in units such as ns, us, ms, or hardware clock cycles (dt).
stretch - A symbolic non-negative duration that is resolved at compile time into a concrete value chosen to satisfy timing constraints.
delay - An identity operation applied to one or more qubits for a given duration, used to pin timing and prevent unintended commutation.
box - A timing context that groups statements together with an enforced total duration, ensuring well-defined scheduling boundaries.
angle - A fixed-width representation of phase values, useful for encoding rotations and phase shifts in hardware-specific bitstring formats.
extern - User or backend defined functions that can be declared in QASM and validated in PyQASM for tasks such as cycle alignment or calibration.
complex - Support for complex literals and standard functions (abs, real, imag, sin, cos, etc.) to describe calibrated amplitudes, phases, or control laws.

Example:

QASM-Code

import pyqasm
qasm_code = """
OPENQASM 3.0;
include "stdgates.inc";

// Duration examples
duration t1 = 100ns;
const duration t2 = 50us;
const duration t3 = 200dt;

// Stretch examples
const stretch s1 = 75ns;
const stretch s2 = t2 + t3;

// Delay examples
qubit[2] q;
delay[t1] q[0];
delay[s1] q[1];
delay[25ns] q[0], q[1];

// Box examples
box[150ns] {
    delay[50ns] q[0];
    h q[1];
    delay[50ns] q[0];
    cx q[0], q[1];
    delay[50ns] q[1];
}

box[t1] {
    delay[25ns] q[0];
    x q[1];
    delay[25ns] q[0];
    y q[1];
    delay[50ns] q[0], q[1];
}

// Angle examples
angle[8] ang1 = pi/2;
angle[4] ang2 = "1010";
const angle[8] ang3 = 3*pi/4;

// Extern examples
extern calibrate(angle, duration) -> complex;
extern measure_fidelity(int, complex) -> float[64];

complex[float[64]] result;
float[64] fidelity;

result = calibrate(ang1, t1);
fidelity = measure_fidelity(2, 1.0 + 2.0im);

// Complex examples
complex c1 = 1.0 + 2.0im;
complex c2 = -3.5 - 1.5im;
complex[float[64]] c3 = 2.5 + 3.7im;

complex c4 = c1 + c2;
complex c5 = c1 * c2;
float mag = abs(c1);
complex c6 = sqrt(c1);
"""
module = pyqasm.loads(qasm_code)
module.validate()

print(pyqasm.dumps(module))

output

OPENQASM 3.0;
include "stdgates.inc";
duration t1 = 100.0ns;
const duration t2 = 50.0us;
const duration t3 = 200.0dt;
const stretch s1 = 75.0ns;
const stretch s2 = t2 + t3;
qubit[2] q;
delay[100.0ns] q[0];
delay[75.0ns] q[1];
delay[25.0ns] q[0], q[1];
box[150.0ns] {
  delay[50.0ns] q[0];
  h q[1];
  delay[50.0ns] q[0];
  cx q[0], q[1];
  delay[50.0ns] q[1];
}
box[100.0ns] {
  delay[25.0ns] q[0];
  x q[1];
  delay[25.0ns] q[0];
  y q[1];
  delay[50.0ns] q[0], q[1];
}
angle[8] ang1 = pi / 2;
angle[4] ang2 = "1010";
const angle[8] ang3 = 3 * pi / 4;
extern calibrate(angle, duration) -> complex;
extern measure_fidelity(int, complex) -> float[64];
complex[float[64]] result;
float[64] fidelity;
result = calibrate(1.5707963267948966, 100.0ns);
fidelity = measure_fidelity(2, 1.0 + 2.0im);
complex c1 = 1.0 + 2.0im;
complex c2 = -3.5 - 1.5im;
complex[float[64]] c3 = 2.5 + 3.7im;
complex c4 = -2.5 + 0.5im;
complex c5 = -0.5 - 8.5im;
float mag = 2.23606797749979;
complex c6 = 1.272019649514069 + 0.7861513777574233im;