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:
Defining size of the circuit in terms of number of qubits
Choosing whether to use unitary matrices or statevectors
Choosing a set of gates to use, predefined or custom
Choosing the physical connectivity of the qubits, predefined or custom
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.
Installation¶
First clone/download the repo. Then (preferably in a fresh virtual environment):
cd quantumcircuitgym
conda install c condaforge 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.
Documentation¶

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
 Parameters
target (int) – index of the target qubit
control (int) – index of the control qubit
 Returns
None

define_connectivity
(connectivity, custom_matrix=None)¶ Creates a binary matrix that describes the connections between qubits
 Parameters
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.
 Returns
None

define_goal
(goal_state)¶ Defines goal statevector or unitary matrix for the circuit.
 Parameters
goal_state (list) – flattened statevector or unitary matrix
 Returns
None

fidelity
()¶ Calculates fidelity of current and goal state/unitary.
 Returns
fidelity measure
 Return type
fid (float)

make_curriculum
(num_gates, loop_list=None)¶ Designs curriculum for agent which gradually increases goal difficulty.
 Parameters
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
 Returns
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)

plot_connectivity_graph
()¶ 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.
 Returns
None

render
()¶  Returns
text drawing of the current circuit represented by the QuantumCircuit object

reset
()¶ Resets the circuit to empty and any relevant variables to their initial state
 Returns
real and imaginary parts of the current reset quantum state/unitary
 Return type
diff (list)

sample
()¶  Returns
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
 Parameters
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}
 Returns
None

step
(action)¶ Takes a single step (action) inside the environment
 Parameters
action (int) – index of the action in self.gate_list generated by self._create_gates  containing all combinations of legal qubit/gate combinations
 Returns
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)

trace_norm
()¶ 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
 Returns
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.
 Parameters
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.
 Returns
None
