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.

  • Use the contextual (right-click) menu to copy and paste a selected operation. You can also use a keyboard shortcut (cmd-c or crtl-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 or crtl-c to copy the group.

    Right-click menu options.

    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.

    Create a custom operation by grouping.
  • 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 control 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.

control modifier.

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 |0\rangle 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


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.

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

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

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.