The Qmod Workshop  Part 1: Introduction
The Classiq platform features a highlevel quantum modeling language called Qmod. Qmod is compiled into concrete gatelevel implementation using a powerful synthesis engine that optimizes and adapts the implementation to different target hardware/simulation environments.
In this workshop, we will learn how to write quantum models using Qmod. We will be using the Python embedding of Qmod, available as part of the Classiq Python SDK. We will learn basic concepts in the Qmod language, such as functions, operators, quantum variables, and quantum types. We will develop useful building blocks and small algorithms.
The QMOD language reference covers these concepts more systematically and includes more examples.
This workshop consists of stepbystep exercises. It is structured as follows:

Part 1: Language Fundamentals  Exercises 15

Part 2: HigherLevel Concepts  Exercises 610

Part 3: Execution Flows  Exercises 11, 12
The introduction and Part 1 are included in this notebook. Part 2 and 3 are each in its own separate notebook. For each exercise you will find the solution to the exercises at the bottom of the same notebook.
Preparations
Make sure you have a Python version of 3.8 through 3.12 installed.
Install Classiq’s Python SDK by following the instructions on this page: Getting Started  Classiq.
Python Qmod Exercises  General Instructions
In order to synthesize and execute your Qmod code, you should:
1. Make sure you define a main
function that calls functions you create.
2. Use create_model
by running qmod = create_model(main)
to construct a representation of your model.
3. You can synthesize the model (using qprog = synthesize(qmod)
) to obtain an implementation  a quantum program.
4. You can then visualize the quantum program (show(qprog)
) or execute it (using execute(qprog)
. See: Execution  Classiq ). You can also execute it with the IDE after visualizing the circuit.
Exercise 0: From Model to Execution
The following model defines a function that applies X and H gates on a single qubit, and subsequently calls it:
from classiq import *
# Define a quantum function using the @qfunc decorator
@qfunc
def foo(q: QBit) > None:
X(target=q)
H(target=q)
# Define a main function
@qfunc
def main(res: Output[QBit]) > None:
allocate(1, res)
foo(q=res)
Create a model from it, and synthesize, visualize, and execute it.
Use the General Instructions above to do so.
from classiq import *
# Your code here:
In Qmod QBit
is the simplest quantum type, and in this example, q
is a quantum variable of type QBit
. Quantum variables abstract away the mapping of quantum objects to qubits in the actual circuit.
See also Quantum Variables.
We will discuss other quantum types during the workshop.
The Qmod Workshop  Part 1: Language Fundamentals
Follow exercises 1 through 5 for the first session of the workshop.
Exercise 1  Bell Pair
Create a function that takes two singlequbit (QBit
) quantum arguments and prepares the bell state on them (Bell state) by applying H
on one variable and then using it as the control of a CX
function with the second variable as the target.
Create a main function that uses this function and has two singlequbit outputs, initialize them to the 0> state (using the allocate
function), and apply your function to them.
See also Functions
from classiq import *
# Your code here:
qmod = create_model(main)
qprog = synthesize(qmod)
show(qprog)
Opening: https://platform.classiq.io/circuit/b38a2903cc4a48a494d1bc5e54c8ff7c?version=0.41.0.dev39%2B79c8fd0855
Use qubit array subscript (the syntax  variable [ indexexpression ]) to change the function from subsection 1 to receive a single quantum variable, a qubit array (QArray
) of size 2.
Change your main function to declare a single output (also an array of size 2).
from classiq import *
# Your code here:
qmod = create_model(main)
qprog = synthesize(qmod)
show(qprog)
Opening: https://platform.classiq.io/circuit/6e199e067b424eeabe69e46486d4329b?version=0.41.0.dev39%2B79c8fd0855
Exercise 2  Repeat
Use the builtin repeat
operator to create your own Hadamard transform function (call it my_hadamard_transform
). The Hadamard transform function is a function that takes as argument a qubit array of an unspecified size and applies H
to each of its qubit.
See also Classical repeat.
Set your main function to have a quantum array output of unspecified size, allocate 10 qubits, and then apply your Hadamard transform function.
from classiq import *
# Your code here:
qmod = create_model(main)
qprog = synthesize(qmod)
show(qprog)
Opening: https://platform.classiq.io/circuit/ed23ad8c19e540a6944d836360d0b07d?version=0.41.0.dev39%2B79c8fd0855
Note: Quantum Variable Capture
The repeat
operator invokes a statement block multiple times. The statement block is specified using a Python callable, typically a lambda expression. Inside the block you can refer to variables declared in the outer function scope.
This concept is called quantum variable capture
, equivalent to capture in classical languages.
See also Capturing context variables and parameters.
Exercise 3  Power
Raising a quantum operation to a power appears in many known algorithms, for examples, in Grover search and Quantum Phase Estimation. For most operations, it simply means repeating the same circuit multiple times.
Sometimes, however, power can be simplified, thus saving computational resources. The most trivial example is a quantum operation expressed as a single explicit unitary matrix (i.e., all n*n matrix terms are given)  raising the operation can be done by raising the matrix to that power via classical programming.
See also Power operator.
Use the following code to generate a 2qubit (real) unitary matrix:
from typing import List
import numpy as np
from classiq import *
rng = np.random.default_rng(seed=0)
random_matrix = rng.random((4, 4))
qr_unitary, _ = np.linalg.qr(random_matrix)
unitary_matrix = QConstant("unitary_matrix", List[List[float]], qr_unitary.tolist())
In order to reuse some classical value we can define a QConstant
to store that value.
 Create a model that applies
unitary_matrix
on a 2 qubit variable.  Create another model that applies
unitary_matrix
raised to power 3 on a 2 qubit variable.  Compare the gate count via the Classiq’s IDE in both cases.
Note  the signature of function unitary
is:
def unitary(
elements: CArray[CArray[CReal]],
target: QArray[QBit],
) > None:
pass
from classiq import *
# Your code here:
qmod = create_model(main)
qprog = synthesize(qmod)
show(qprog)
Opening: https://platform.classiq.io/circuit/fc6fba17cf874902ac17f7354b58032c?version=0.41.0.dev39%2B79c8fd0855
Exercise 4  Userdefined Operators
Create a function that applies a given singlequbit operation to all qubits in its quantum argument (Call your function my_apply_to_all
). Such a function is also called an operator, i.e. a function that one of its arguments is another function (its operand).
See also Operators.
Follow these guidelines: 1. Your function should declare a quantum argument of type qubit array. It should also declare an argument of a function type with a single qubit argument. 2. The body should apply the operand to all qubits in the argument.
When you're done, reimplement my_hadamard_transform
from exercise 2 using this function instead of repeat
.
Use the same main function from exercise 2.
from classiq import *
# Your code here:
qmod = create_model(main)
qprog = synthesize(qmod)
show(qprog)
Opening: https://platform.classiq.io/circuit/70e0f2d0ca104850867d9d48223008e3?version=0.41.0.dev39%2B79c8fd0855
Exercise 5  Quantum Conditionals
Exercise 5a  Control Operator
Use the builtin control
operator to create a function that receives two single qubit variables and uses one of the variables to control an RY gate with a pi/2
angle acting on the other variable (without using the CRY
function).
See also Control.
from classiq import *
# Your code here:
qmod = create_model(main)
qprog = synthesize(qmod)
show(qprog)
Opening: https://platform.classiq.io/circuit/c67d0e6348c84ea1b2001206f783076f?version=0.41.0.dev39%2B79c8fd0855
Exercise 5b  Control Operator with Quantum Expressions
The control
operator is the conditional application of some operation, with the condition being that all control qubits are in the state 1>. This notion is generalized in QMOD to other control states, where the condition is specified as a comparison between a quantum numeric variable and a numeric value, similar to a classical if
statement. Quantum numeric variables are declared with class QNum
.
See also Numeric types.
 Declare a
QNum
output argument usingOutput[QNum]
and name itx
.  Use the
prepare_int
function to initialize it to9
. Note that you don't need to specify theQNum
attributes  size, sign, and fraction digits, as they are inferred at the point of initialization.  Execute the circuit and observe the results.
 Declare another output argument of type
QBit
and perform acontrol
such that under the condition thatx
is 9, the qubit is flipped. Execute the circuit and observe the results. Repeat for a different condition.
from classiq import *
# Your code here:
qmod = create_model(main)
qprog = synthesize(qmod)
show(qprog)
Opening: https://platform.classiq.io/circuit/92c2b325e16640428b300dfd1bab3b86?version=0.41.0.dev39%2B79c8fd0855
Solutions
Exercise 1
# Solution for Exercise 1 part 1:
from classiq import *
@qfunc
def bell(q0: QBit, q1: QBit) > None:
H(q0)
CX(q0, q1)
@qfunc
def main(qubit0: Output[QBit], qubit1: Output[QBit]) > None:
allocate(1, qubit0)
allocate(1, qubit1)
bell(qubit0, qubit1)
# Solution for Exercise 1 part 2:
from classiq import *
@qfunc
def bell(q: QArray[QBit, 2]) > None:
H(q[0])
CX(q[0], q[1])
@qfunc
def main(q: Output[QArray[QBit, 2]]) > None:
allocate(2, q)
bell(q)
Exercise 2
# Solution for Exercise 2:
from classiq import *
@qfunc
def my_hadamard_transform(q: QArray[QBit]) > None:
repeat(q.len, lambda i: H(q[i]))
@qfunc
def main(q: Output[QArray[QBit]]) > None:
allocate(10, q)
my_hadamard_transform(q)
Exercise 3
# Solution to exercise 3:
from typing import List
import numpy as np
from classiq import *
rng = np.random.default_rng(seed=0)
random_matrix = rng.random((4, 4))
qr_unitary, _ = np.linalg.qr(random_matrix)
unitary_matrix = QConstant("unitary_matrix", List[List[float]], qr_unitary.tolist())
@qfunc
def main(q: Output[QArray[QBit]]) > None:
allocate(2, q)
power(3, lambda: unitary(unitary_matrix, q))
model = create_model(main)
qprog = synthesize(model)
show(qprog)
Opening: https://platform.classiq.io/circuit/671b9800a1e840079561f12c9125cd8e?version=0.41.0.dev39%2B79c8fd0855
Exercise 4
# Solution for exercise 4:
from classiq import *
@qfunc
def my_apply_to_all(operand: QCallable[QBit], q: QArray[QBit]) > None:
repeat(q.len, lambda i: operand(q[i]))
@qfunc
def my_hadamard_transform(q: QArray[QBit]) > None:
my_apply_to_all(lambda t: H(t), q)
@qfunc
def main(q: Output[QArray[QBit]]) > None:
allocate(10, q)
my_hadamard_transform(q)
Exercise 5
# Solution for exercise 5a:
from classiq import *
from classiq.qmod.symbolic import pi
@qfunc
def my_controlled_ry(control_bit: QBit, target: QBit) > None:
control(control_bit, lambda: RY(pi / 2, target))
@qfunc
def main(control_bit: Output[QBit], target: Output[QBit]) > None:
allocate(1, control_bit)
allocate(1, target)
my_controlled_ry(control_bit, target)
model = create_model(main)
qprog = synthesize(model)
show(qprog)
Opening: https://platform.classiq.io/circuit/d46da5b5c12b4675be229410927edf6c?version=0.41.0.dev39%2B79c8fd0855
# Solution for exercise 5b:
from classiq import *
@qfunc
def main(x: Output[QNum], target: Output[QBit]) > None:
prepare_int(9, x)
allocate(1, target)
control(x == 9, lambda: X(target))
model = create_model(main)
qprog = synthesize(model)
show(qprog)
Opening: https://platform.classiq.io/circuit/974241f978b14490b0b46752735c0642?version=0.41.0.dev39%2B79c8fd0855