Import/export circuits

View on QuantumAI

Run in Google Colab

View source on GitHub

Download notebook

try:
    import cirq
except ImportError:
    print("installing cirq...")
    # Cirq 1.6 needed for OpenQASM 3.0 support    !pip install --quiet cirq~=1.0.dev
    print("installed cirq.")

Cirq has several features that allow the user to import/export from other quantum languages.Note: this notebook relies on unreleased Cirq features. If you want to try these features, make sure you install cirq via pip install cirq~=1.0.dev.

Exporting and importing to JSON

For storing circuits or for transferring 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:')
print(json_string)
print()

# 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)}:')
print(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. However, both OpenQASM 2.0 and 3.0 have this limited support. 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

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 "qelib1.inc";
    qreg q[3];
    creg meas[3];
    h q;
    measure q -> meas;
    """)
print(circuit)

q_0: ───H───M('meas_0')───

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

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

OpenQASM 3.0 also has limited support, which can be seen by the following code:

from cirq.contrib.qasm_import import circuit_from_qasm
circuit = circuit_from_qasm("""
OPENQASM 3.0;
include "stdgates.inc";

// Qubits: [q0]
qubit[2] q;
bit[2] m_mmm;

x q;
m_mmm = measure q;
""")
print(circuit)

q_0: ───X───M('m_mmm_0')───

q_1: ───X───M('m_mmm_1')───

Supported control statements

Gate conversion rules

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

Exporting cirq.Circuit to QASM format

Cirq also has the ability to export circuits in OpenQASM format using either OpenQasm 2.0 or 3.0 formats. This can be done using the circuit.to_qasm() function, such as circuit.to_qasm(version="3.0") or by using the cirq.qasm protocol, as follows:

q0 = cirq.NamedQubit('q0')
circuit = cirq.Circuit(cirq.X(q0), cirq.measure(q0, key='mmm'))
qasm_str = cirq.qasm(circuit, args=cirq.QasmArgs(version="3.0"))
print(qasm_str)

// Generated from Cirq v1.5.0.dev20241221000556

OPENQASM 3.0;
include "stdgates.inc";


// Qubits: [q0]
qubit[1] q;
bit[1] m_mmm;


x q[0];
m_mmm[0] = measure q[0];

Currently supported version strings are "2.0" and "3.0".

By default, if no version is specified, circuits are currently exported in OpenQasm 2.0 format. This default behavior may change in the future so be sure to specify the argument if a specific version of OpenQASM is desired.

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 = "https://algassert.com/quirk#circuit=%7B%22cols%22:[[%22H%22,%22H%22],[%22%E2%80%A2%22,%22X%22],[%22H%22,%22H%22]]}"
c= cirq.quirk_url_to_circuit(quirk_url)

print(c)

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

quirk_str="""{
  "cols": [
    [
      "H",
      "H"
    ],
    [
      "•",
      "X"
    ],
    [
      "H",
      "H"
    ]
  ]
}"""
quirk_json=json.loads(quirk_str)
c= cirq.quirk_json_to_circuit(quirk_json)

print(c)

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