Build, edit, and inspect quantum circuits¶
Overview¶
The steps to build your quantum circuits are:
2. Create your circuit: either drag-and-drop operations or enter OpenQASM code. Optionally, create a custom operation in OpenQASM
3. Inspect your circuit’s components using Circuit Inspector
Open Circuit Composer¶
(Optional) If you are not currently signed in to IBM Quantum Experience, select the Sign in button in the upper right corner. Then, you can either sign in or Create an IBMid account.
If you don’t sign in, the visualizations at the bottom of the page automatically show simulated results for up to four qubits. However, if you want to run your circuit on a simulator backend or on real quantum hardware, or if you want to visualize a circuit that has more than four qubits, you must sign in.
Open Circuit Composer by clicking the Circuit Composer icon
on the left-hand navigation bar. The workspace will display an untitled empty circuit.
Name your circuit by clicking on the words Untitled Circuit and typing in your own title. Save the name by pressing return, or by clicking the checkmark.
(Optional) Customize your workspace. Use the View menu to select which panels to include, then use the menu in the right corner of any window to access options for further customization. You can also choose either a dark or light workspace theme. Note that you can resize or close panels, and reset the workspace to the default set of panels from the View menu.
To build a circuit, you can either drag-and-drop operations, or you can enter OpenQASM code into the code editor. Your circuit is automatically saved every time you make a change.
Build your circuit with drag-and-drop¶
Drag and drop operations from the operations palette onto the quantum and classical registers.
Once operations are positioned on your circuit, you can continue to drag and drop them to new positions.
Use the contextual (right-click) menu to copy and paste a selected operation. You can also use a keyboard shortcut (
cmd-c
orcrtl-c
, depending on your operating system) to copy a selected operation.If you use the keyboard shortcut (
cmd-v
/ctrl-v
), the operation will be pasted to the same register as the copied operation.You can select several operations to copy and paste them, or group them into a custom unitary operation that displays in your list of operations and functions as a single gate. To select more than one operation, place your cursor just outside one of the operations, then click and drag across the area to select. A dashed line will show what operations you are selecting. You can also shift-click individual operations to select or unselect them.
Right-click inside the area within the dashed lines and select Copy from the menu, or use the keyboard shortcut
cmd-c
orcrtl-c
to copy the group.If you use the keyboard shortcut (
cmd-v
/ctrl-v
) to paste, the group will be pasted to the same registers as the copied group.To group several operations together as a custom operation, first group the operations by selecting them as described above, then right-click inside the area within the dashed lines and select Group from the menu. You can also use the keyboard shortcut
cmd-g
/crtl-g
to group the operations. Upon grouping the operations, you will be prompted to name the custom operation, or you can accept the default name. Click Create, and the custom operation will be represented by a single box, both in your circuit and in the list of operations. You can now drag and drop or copy and paste the new operation throughout your circuit. Note that your operation is saved to this circuit but will not appear in the operations list for other circuits.To ungroup the gates within your custom operation, right-click the custom operation on the Composer and select the ungroup option from the menu.
You can also build a custom operation directly in the OpenQASM code editor; see Create a custom operation in OpenQASM for more information.
To rename or delete a custom operation, right-click on the operation in the operations list or on the Composer, and select rename or delete from the menu. Note that deleting a custom operation from the operations list will also delete any instances of it from the Composer; however, deleting a custom operation from the Composer will not delete it from the operations list.
To add more quantum or classical registers, go to the Edit menu and select Manage registers. You can increase or decrease the number of qubits or bits in your circuit, as well as rename the registers. Click Save to apply the changes.
Control modifier
A control modifier yields a gate whose original operation is now contingent on the state of the control qubit. Find more details in the Control modifier definition of the operations glossary.
Drag the control modifier to a gate in order to add a control to it. Dots will appear on the qubits
that can be affected by that control; click on one or more dots to assign the control to one or more
qubits. You can also assign a control by right-clicking a gate.
To remove a control, right-click the gate and select the option to remove control.

Conditional reset
Several hardware backends can now perform conditional reset. If you have access to these backends, either through the IBM Q Network, or the Educators or Researchers programs, you can now initialize (or re-initialize) qubits in the state, through measurement followed by a conditional X gate. Conditional reset will be rolled out to more backends, including open-access systems, over time. Read these tutorials for more details:
Build your circuit with OpenQASM code¶
Note
IBM Quantum Experience currently supports OpenQASM 2.0.
To open the code editor, click the
</> Code
tab.See the Operations glossary for OpenQASM references to gates and other operations.
You can define your own custom operations; see Create a custom operation in OpenQASM.
For more information on using the OpenQASM language, including sample lines of code, see the original research paper, Open Quantum Assembly Language. The table of OpenQASM language statements from the paper is reproduced below. The OpenQASM grammar can be found in Appendix A of the paper.
Statement |
Description |
Example |
---|---|---|
|
Denotes a file in OpenQASM format[a] |
|
|
Declare a named register of qubits |
|
|
Declare a named register of bits |
|
|
Open and parse another source file |
|
|
Declare a unitary gate |
(see text of paper) |
|
Declare an opaque gate |
(see text of paper) |
|
Comment a line of text |
|
|
Apply built-in single-qubit gate(s)[b] |
|
|
Apply built-in CNOT gate(s) |
|
|
Make measurement(s) in basis |
|
|
Prepare qubit(s) in |
|
|
Apply a user-defined unitary gate |
|
|
Conditionally apply quantum operation |
|
|
Prevent transformations across this source line |
|
[a] This must appear as the first non-comment line of the file.
[b] The parameters theta, phi, and lambda are given by parameter expressions; for more information, see page 5 of the paper and Appendix A.
Create a custom operation in OpenQASM¶
You can define new unitary operations in the code editor (see the figure below for an example).
The operations are applied using the statement name(params) qargs;
just like the
built-in operations. The parentheses are optional if there are no parameters.
To define a custom operation, enter it in the OpenQASM code editor using this format: gatename(params) qargs;
.
If you click +Add in the operations list, you will be prompted to enter a name for your custom
operation, which you can then build in the code editor.
Once you have defined your custom operation, drag it onto the graphical editor and use the edit icon to fine-tune the parameters.
a) The gates to be included in the custom operation:
b) The code for the new operation:
c) The new operation in the graphical editor:
Inspect your circuit, step-by-step¶
The Circuit Inspector de-mystifies the inner workings of the circuits you create. It provides a customizable step-by-step view of a simulation of your circuit, so that you can see the state of the qubits as the computation evolves.

Click View and select the windows for the visualizations that you want to use.
Click Inspect in the menu bar. (Note that you cannot select Inspect until you have added at least one operation to Circuit Composer.) To move step-by-step through visualizations of your circuit’s components, control the movement of the Inspector using the forward and rewind buttons.
Inspector controls, in order: jump to the beginning of a circuit, step backward, play from one break point to the next, step forward, jump to the end of a circuit.¶
With breakpoints, you can define groups of operations to inspect by selecting one or more operations in your circuit to mark a breakpoint. A colored overlay on an operation indicates that a breakpoint is set. Once breakpoints are defined, you can select the play button to observe the steps in sequence. To remove a breakpoint, re-select the operations, and the colored overlay disappears.
To learn more about interpreting visualizations, see the Visualizations topic.
To close the Inspector and return to editing your circuit, click the x in the upper right corner of the Inspection bar.
Randomness in the simulator
The simulator creates randomness by generating results based on a seed. The seed is the initial value introduced into the algorithm that generates pseudorandom numbers. You can see the seed number in a box above the Composer. You can also set the seed yourself by changing the value in the box.
Run your circuit¶
When you are ready to run your circuit on a quantum backend and interpret the results, continue to this topic: Run circuits and view results.