Build, edit, and inspect quantum circuits


The steps to build your quantum circuits are:

1. Open Circuit Composer

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

  1. (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.

  2. Open Circuit Composer by clicking the Circuit Composer icon circ-comp-icon on the left-hand navigation bar. The workspace will display an untitled empty circuit.

  3. 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.

  4. (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.

  5. 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.

  • To delete or modify an operation from a register, select the operation and click the x or pencil icon as appropriate.

  • 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.

Build your circuit with OpenQASM code

  • 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.

OpenQASM language statements (version 2.0)





Denotes a file in OpenQASM format[a]


qreg name[size];

Declare a named register of qubits

qreg q[5];

creg name[size];

Declare a named register of bits

creg c[5];

include “filename”;

Open and parse another source file

include “”;

gate name(params) qargs

Declare a unitary gate

(see text of paper)

opaque name(params) qargs;

Declare an opaque gate

(see text of paper)

// comment text

Comment a line of text

// oops!

U(theta,phi,lambda) qubit\|qreg;

Apply built-in single-qubit gate(s)[b]

U(pi/2,2\*pi/3,0) q[0];

CX qubit\|qreg,qubit\|qreg;

Apply built-in CNOT gate(s)

CX q[0],q[1];

measure qubit\|qreg -> bit\|creg;

Make measurement(s) in Z basis

measure q -> c;

reset qubit\|qreg;

Prepare qubit(s) in |0\rangle

reset q[0];

gatename(params) qargs;

Apply a user-defined unitary gate

crz(pi/2) q[1],q[0];

if(creg==int) qop;

Conditionally apply quantum operation

if(c==5) CX q[0],q[1];

barrier qargs;

Prevent transformations across this source line

barrier q[0],q[1];

[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 gates and other operations in the code editor. Custom operations are defined as unitary subroutines (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, it will instruct you to do the same.

Once you have defined your custom operation, drag it onto the graphical editor and use the edit icon to fine-tune the parameters.

a) cust-icon-explod b) cust-qasm c) cust-icon

Example of a custom operation, nG0. Image a) shows the gates to be included in the custom operation. Image b) is the code for the new operation. Image c) is 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.

Circuit Inspector.
  • 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.

    Controls to step forward and backward, and to jump to a circuit's beginning or end.

    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

Each time you open the Circuit Inspector, 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. Because the seed is fixed during your Circuit Inspector session, your results will be repeatable. However, when you close the Inspector and re-open it, the seed will have a new value, so you may see a different result.

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.