surfacecode

A surface code environment aimed at facilitating the development of decoding agents for fault tolerant quantum computing.

The environment provided here was previously used for the development of deepQ decoders . To get started conceptually, and for an introduction to fault-tolerant quantum computing, and particularly the surface code, we highly suggest reading the associated manuscript Reinforcement Learning Decoders for Fault-Tolerant Quantum Computation.

Additionally, if you use this environment, or any of the code provided here, please cite the above mentioned work as follows:

R. Sweke, M.S. Kesselring, E.P.L. van Nieuwenburg, J. Eisert,
Reinforcement Learning Decoders for Fault-Tolerant Quantum Computation,
arXiv:1810.07207 [quant-ph], 2018. 

Finally, if you use this environment to develop a decoder which outperforms the deepQ decoders described in the above work then please let us know! And have fun :)

---

0) Installation and Getting Started

This environment requires python 3, along with the additional packages:

1. gym
2. keras

To install the package first clone this repository, and then from the root directory run

python setup.py install

Alternatively, this package can be installed via pip or pipenv (which is recommended).

---

1) Documentation

The environment provided here inherits directly from the openAI gym base class gym.env - as such, we recommend starting with the openAI gym documentation to familiarize yourself with the openAI gym API format.

As the environment has various free attributes which should be specified, an instance of the environment is instantiated as follows:

from gym_surfacecode.envs import SurfaceCodeEnv
my_env = SurfaceCodeEnv(p_phys=0.01, p_meas=0.01, error_model="DP", use_Y=True, volume_depth=3)

The attributes which need to be specified are as follows:

1. p_phys and p_meas: The physical and measurement error probabilities respectively.
2. error_model: A string in ["DP","X"] specifying whether a depolarizing or bit flip channel should be simulated.
3. use_Y: A boolean indicating whether Pauli Y flips are valid actions.
4. volume_depth: A positive integer specifying the number of syndrome measurements performed sequentially in each syndrome extraction.

For more details, we again highly suggest starting by reading Reinforcement Learning Decoders for Fault-Tolerant Quantum Computation. In particular, please note that at the moment the distance of the surface code is fixed to distance-5 - we are working at removing this restriction!

The actions which are allowed depend on the setting of the attributes:

1. If the error model is "X" then any integer in the set [0,25] is a valid action. The integers [0,24] each represent a bit flip on a particular data qubit (labelled sequentially row wise), while the action 25 is the request new syndrome action. In this case num_action_layers = 1.
2. If the error model is "DP" and use_Y is True, then any integer in the set [0,75] is a valid action, with actions in [0,24], [25,49], [50,74] indicating X,Y, or Z flips on the specified qubit respectively, with 75 being the request new syndrome action. In this case num_action_layers = 3.
3. If the error model is "DP" and use_Y is False, then any integer in the set [0,50] is a valid action, with actions in [0,24], [25,49] indicating X or Z flips on the specified qubit respectively, with 50 being the request new syndrome action. In this case num_action_layers = 2.

At any given instant the state of the environment is a [volume_depth + num_action_layers,11,11] boolean array, where:

1. The first volume_depth slices of the tensor encode the most recently obtained syndromes.
2. The final num_action_layers slices of the tensor encode the history of actions taken since the most recent syndrome was obtained.

As an example, for depolarizing noise (i.e. error_model = "DP"), with use_Y=False and volume_depth = 3, the state of the environment would be as follows:

with the syndrome layers utilizing the following encoding:

and the action-history layers utilizing this encoding.

2) To-Do and Future Development

At the moment the most obvious restriction of this environment is that it is restricted to distance-5 surface codes. This restriction is purely because of the feed-forward homology class predicting referee decoders that have been used. This restriction could be lifted by using minimum-weight perfect matching decoders as referees, which is in the process of being implemented.

If you have good results for environment provided here, and we haven't yet removed the restriction to d=5, please contact us! We are very interested in developing scalable decoders!!