Import/export circuits

View on QuantumAI Run in Google Colab View source on GitHub Download notebook
    import cirq
except ImportError:
    print("installing cirq...")
    !pip install --quiet cirq
    print("installed cirq.")

Cirq has several features that allow the user to import/export from other quantum languages.

Exporting and importing to JSON

For storing circuits or for transfering them between collaborators, JSON can be a good choice. Many objects in cirq can be serialized as JSON and then stored as a text file for transfer, storage, or for posterity.

Any object that can be serialized, which includes circuits, moments, gates, operations, and many other cirq constructs, can be turned into JSON with the protocol cirq.to_json(obj). This will return a string that contains the serialized JSON.

To take JSON and turn it back into a cirq object, the protocol cirq.read_json can be used. This can take a python file or string filename as the first argument (file_or_fn) or can take a named json_text parameter to accept a string input.

The following shows how to serialize and de-serialize a circuit.

import cirq

# Example circuit
circuit = cirq.Circuit(cirq.Z(cirq.GridQubit(1,1)))

# Serialize to a JSON string
json_string = cirq.to_json(circuit)
print('JSON string:')

# Now, read back the string into a cirq object
# cirq.read_json can also read from a file
new_circuit = cirq.read_json(json_text=json_string)

print(f'Deserialized object of type: {type(new_circuit)}:')
JSON string:
  "cirq_type": "Circuit",
  "moments": [
      "cirq_type": "Moment",
      "operations": [
          "cirq_type": "SingleQubitPauliStringGateOperation",
          "pauli": {
            "cirq_type": "_PauliZ",
            "exponent": 1.0,
            "global_shift": 0.0
          "qubit": {
            "cirq_type": "GridQubit",
            "row": 1,
            "col": 1
  "device": {
    "cirq_type": "_UnconstrainedDevice"

Deserialized object of type: <class 'cirq.circuits.circuit.Circuit'>:
(1, 1): ───Z───

Advanced: Adding JSON compatibility for custom objects in cirq

Most cirq objects come with serialization functionality added already. If you are adding a custom object (such as a custom gate), you can still serialize the object, but you will need to add the magic functions _json_dict_ and _from_json_dict to your object to do so.

When de-serializing, in order to instantiate the correct object, you will also have to pass in a custom resolver. This is a function that will take as input the serialized cirq_type string and output a constructable class. See cirq.protocols.json_serialization for more details.

Importing from OpenQASM

The QASM importer is in an experimental state and currently only supports a subset of the full OpenQASM spec. Amongst others, classical control, arbitrary gate definitions, and even some of the gates that don't have a one-to-one representation in Cirq, are not yet supported. The functionality should be sufficient to import interesting quantum circuits. Error handling is very simple - on any lexical or syntactical error, a QasmException is raised.

Importing cirq.Circuit from QASM format

Requirements: ply

pip install --quiet cirq
pip install --quiet ply==3.4

The following call will create a circuit defined by the input QASM string:

from cirq.contrib.qasm_import import circuit_from_qasm
circuit = circuit_from_qasm("""
    OPENQASM 2.0;
    include "";
    qreg q[3];
    creg meas[3];
    h q;
    measure q -> meas;
q_0: ───H───M('meas_0')───

q_1: ───H───M('meas_1')───

q_2: ───H───M('meas_2')───

Supported control statements

Statement Cirq support Description Example
OPENQASM 2.0; supported Denotes a file in Open QASM format OPENQASM 2.0;
qreg name[size]; supported (see mapping qubits) Declare a named register of qubits qreg q[5];
creg name[size]; supported (see mapping classical register to measurement keys) Declare a named register of bits creg c[5];
include "filename"; supported ONLY to include the standard "" lib for compatibility Open and parse another source file include "";
gate name(params) qargs; NOT supported Declare a unitary gate
opaque name(params) qargs; NOT supported Declare an opaque gate
// comment text supported Comment a line of text // supported!
U(θ,φ,λ) qubit/qreg; supported Apply built-in single qubit gate(s) U(pi/2,2*pi/3,0) q[0];
CX qubit/qreg,qubit/qreg; supported Apply built-in CNOT gate(s) CX q[0],q[1];
measure qubit/qreg supported Make measurements in Z basis
reset qubit/qreg; NOT supported Prepare qubit(s) in |0> reset q[0];
gatename(params) qargs; supported for ONLY the supported subset of standard gates defined in "" Apply a user-defined unitary gate rz(pi/2) q[0];
if(creg==int) qop; NOT supported Conditionally apply quantum operation if(c==5) CX q[0],q[1];
barrier qargs; NOT supported Prevent transformations across this source line barrier q[0],q[1];

Gate conversion rules

QE gates Cirq translation Notes
U(θ,φ,λ) QasmUGate(θ,φ,λ)
CX cirq.CX
u3(θ,φ,λ) QasmUGate(θ,φ,λ)
u2(φ,λ) = u3(π/2,φ,λ) QasmUGate(π/2,φ,λ)
u1 (λ) = u3(0,0,λ) NOT supported
id cirq.Identity one single-qubit Identity gate is created for each qubit if applied on a register
u0(γ) NOT supported this is the "WAIT gate" for length γ in QE
x cirq.X
y cirq.Y
z cirq.Z
h cirq.H
s cirq.S
sdg cirq.S**-1
t cirq.T
tdg cirq.T**-1
rx(θ) cirq.Rx(θ)
ry(θ) cirq.Ry(θ)
rz(θ) cirq.Rz(θ)
cx cirq.CX
cy cirq.ControlledGate(cirq.Y)
cz cirq.CZ
ch cirq.ControlledGate(cirq.H)
swap cirq.SWAP
ccx cirq.CCX
cswap cirq.CSWAP
crz NOT supported
cu1 NOT supported
cu3 NOT supported
rzz NOT supported

Mapping quantum registers to qubits

For a quantum register qreg qfoo[n]; the QASM importer will create cirq.NamedQubits named qfoo_0..qfoo_<n-1>.

Mapping classical registers to measurement keys

For a classical register creg cbar[n]; the QASM importer will create measurement keys named cbar_0..cbar_<n-1>.

Importing from Quirk

Quirk is a drag-and-drop quantum circuit simulator, great for manipulating and exploring small quantum circuits. Quirk's visual style gives a reasonably intuitive feel of what is happening, state displays update in real time as you change the circuit, and the general experience is fast and interactive.

After constructing a circuit in Quirk, you can easily convert it to cirq using the URL generated. Note that not all gates in Quirk are currently convertible.

quirk_url = "[[%22H%22,%22H%22],[%22%E2%80%A2%22,%22X%22],[%22H%22,%22H%22]]}"
c= cirq.quirk_url_to_circuit(quirk_url)

0: ───H───@───H───
1: ───H───X───H───

You can also convert the JSON from the "export" button on the top bar of Quirk. Note that you must parse the JSON string into a dictionary before passing it to the function:

import json

  "cols": [
c= cirq.quirk_json_to_circuit(quirk_json)

0: ───H───@───H───
1: ───H───X───H───