QUA "Best Practice" Guide¶
This article showcases best practices when writing in QUA to optimize user readability and performance. However, in certain situations, there is a clear tradeoff between the two. These cases will be noted to optimize your QUA program.
QUA is a new language that keeps evolving, and as a result, we expect this guide to evolve as well. Therefore, we would be happy to receive any comments or suggestions.
Pulse amplitude and duration should be set in the configuration whenever possible. The reason being that modifying pulses in the program (i.e.,
duration) requires real-time computation, which can introduce time gaps in the program's execution. For example, If you require two different amplitudes, define two different operations. Ideally, real-time modification of pulses should only be used when sweeping parameters, either dynamically in QUA or manually.
Only define QUA variables for parameters you want to sweep or change in real-time. Otherwise, use Python variables.
Always simulate your program to make sure that you are getting the correct behavior. If added gaps are problematic, the simulator can also be used to check the exact timing of pulses.
There are issues that can occur in real time and produce unexpected output from the OPX, for example:
A division by zero
- An overflow of a QUA variable
- Trying to access an array out of bounds
- Trying to play a pulse (or wait) for a duration \< 4 cycles
Beware of fixed/floating point inaccuracies. In the following example, it is unclear whether 1.0 would be included in the sweep or not:
with for_(a, 0, a < 1.0, a + 0.1). Recommended practice to avoid that:
Define the sweep parameters and sweep array in advance:
When sweeping a fixed point number, use the same syntax
with for_(a, a_min, a < a_max + da/2, a + da).
When sweeping an integer, use
with for_(t, t_min, t <= t_max, t + dt)
Use macros the same way you would use functions in python - To allow reuse of code (DRY) and to simplify the main code readability.
QUA variables are always global. This means that you can use variables without passing them as an input and that any variable which is changed inside the macro, regardless of whether it was given as an input or not, will also be changed outside of the macro. This is sometimes known as
pass-by-referenceas opposed to
pass-by-value. In other words, QUA variables should be treated as pointers to the real, hidden, variables.
In order make it a bit more clear, we recommend the following:
If there are external QUA variables which are needed in the macro, they should be passed as variables to the macro.
- Any other QUA variable used by the macro should be declared inside the macro.
- If a QUA variable, given as an input to the macro, is to be changed and we do not want the change to happen externally, then the variable should be assigned to a local variable.
- Any QUA variable, which is declared/changed inside the macro, and is needed in the external program, should be returned by the macro.
def some_macro(qubit_state, var_for_calculation) # Two variables coming from the outside temp = declare(fixed) # Local variable only for this macro important_var = declare(bool, value=False) # Local variable declared inside, but then passed back outside ... assign(temp, temp * var_for_calculation) # Notice we do not change var_for_calculation, but declare a local variable "temp" with if_((temp > 0.1) & (qubit_state == 1)): ... assign(important_var, True) assign(qubit_state, 0) return qubit_state, important_var # We send back qubit_state and important_var with program() as example_prog: ... qubit1_state, b_happened = some_macro(qubit1_state, i) ...