Welcome to quantumcircuit_gym’s documentation!

Gym Environment for Quantum Circuit Synthesis (using qiskit and qutip)

A custom gym environment for the generation of optimal quantum circuits which perform a given computational task, using IBMQ’s Qiskit library for Python. Options include:

  1. Defining size of the circuit in terms of number of qubits

  2. Choosing whether to use unitary matrices or statevectors

  3. Choosing a set of gates to use, predefined or custom

  4. Choosing the physical connectivity of the qubits, predefined or custom

  5. Choosing initial goal states or unitaries

A step in the environment is defined as applying one single gate from the defined gate group to a specific qubit, with all possible combinations of gate/qubit pairs (or triplets in case of a two qubit gate) being generated based on the defined connectivity.

The reward is sparse, and inversely proportional to the amount of gates needed to get to the goal - incentivising smaller circuits. Experimentation with custom reward functions is encouraged.

Qiskit Integration

Qiskit is central to this environment, providing the QuantumCircuit class that allows the sequential application of gates to construct a circuit representation of a unitary process. This facilitates the simulation of a given circuit using the Aer backend in order to obtain the resultant quantum state. The library also provides a tool to visualise the current circuit using standard literature conventions.


First clone/download the repo. Then (preferably in a fresh virtual environment):

cd quantumcircuit-gym
conda install -c conda-forge qutip
while read requirement; do conda install --yes $requirement; done < conda_reqs.txt
pip install -r requirements.txt
pip install -e .

In progress: better installation automation

Example use

Most methods displayed in tutorial notebook.


class gym_quantcircuit.envs.QuantCircuitEnv

A quantum circuit implementation using the Qiskit library, containing methods to construct and simulate quantum circuits designed to perform specific operations. Mainly for use in Reinforcement Learning with an agent choosing and learning actions for a specific goal.

c_s_gate(target, control)

Creates custom composite gate from defined qiskit gates that is contained in the IQP group

  • target (int) – index of the target qubit

  • control (int) – index of the control qubit



define_connectivity(connectivity, custom_matrix=None)

Creates a binary matrix that describes the connections between qubits

  • connectivity (str) – string representation of connectivity format

  • custom_matrix (np.array) – binary array with index pairs denoting a connection between those two qubits i.e. (i,j) = 1 if qubit i is connected to qubit j. This is a one way mapping, if two way connectivity is desired the array must be symmetric about the diagonal.




Defines goal statevector or unitary matrix for the circuit.


goal_state (list) – flattened statevector or unitary matrix




Calculates fidelity of current and goal state/unitary.


fidelity measure

Return type

fid (float)

make_curriculum(num_gates, loop_list=None)

Designs curriculum for agent which gradually increases goal difficulty.

  • num_gates (int) – max number of gates for a circuit in the curriculum

  • loop_list (list) – A list of times you want to loop each curriculum stage


list of goal unitaries/statevectors for the agent to target tracker (array): array of how many goals found in each section

Return type

curriculum (list)


Draws a graph of nodes and edges that represents the physical connectivity of the qubits. Graph will not be completely symmetric and will not be an exact replica of the framework, but will provide an accurate visual representation of the connections between qubits.




text drawing of the current circuit represented by the QuantumCircuit object


Resets the circuit to empty and any relevant variables to their initial state


real and imaginary parts of the current reset quantum state/unitary

Return type

diff (list)


a specific action in the circuit environment action space

Return type

action (int)

set_gate_group(gate_group, custom_gates=None)

Defines the gate group to be used within the enviroment

  • gate_group (str) – name of the gate group used

  • custom_gates (dict) – A set of custom gates may be defined using a dictionary, the form looks like{“gate_name”:gate_function}




Takes a single step (action) inside the environment


action (int) – index of the action in self.gate_list generated by self._create_gates - containing all combinations of legal qubit/gate combinations


difference between current and goal state reward (float): reward gained from taking the specified action done (bool): True if agent has reached the goal, False otherwise measures (dict): dictionary containing the measure used to determine reward

Return type

diff (np.array)


Calculates trace norms of density state of matrix - to use this as a metric, take the difference (p_0 - p_1) and return the value of the trace distance


trace distance of difference between density matrices

Return type

dist (float)

var_init(num_qubits, unitary=False, gate_group='pauli', connectivity='nearest_neighbour', goal_state=None, goal_unitary=None, custom_gates=None, custom_connectivity=None)

Initialises the Quantum Circuit Environment object with arguments since gym.make can’t do so.

  • num_qubits (int) – number of qubits in the desired circuit

  • unitary (bool) – if True sets environment to use unitary matrices, otherwise uses statevectors

  • gate_group (str) – string to define the gate group used, options include ‘pauli’,’clifford’ and ‘IQP’

  • goal_state (list) – list of complex values defining goal statevector, must have 2**num_qubits values

  • goal_unitary (np.array) – goal unitary matrix, must have shape (2**num_qubits, 2**num_qubits)

  • custom_gates (list) – list of gate functions to use in the circuit

  • custom_connectivity (np.array) – a NxN binary matrix where N is the number of qubits, with entry [i,j] = 1 when qubit i is physically connected to qubit j.