We want to make it as easy as possible to contribute to qtcodes. This issue is to implement installation tooling to improve the developer experience.

As @amirebrahimi brought up, we can use the -e pip flag to create editable installs.

So, let's:

• update the README to reflect this method of installing qtcodes for development
• remove the sys.path.append from our notebooks, as we can just use editable installs instead
• add a dev extra that installs generally unnecessary dependencies (like Jupyter Lab) to set up an environment with all the dependencies needed by developers

Retworkx is apparently faster and preferred by Qiskit: https://github.com/Qiskit/retworkx

The transition should be smooth!

one mkdocs dependency requires 3.7

Let's allow users to create topological circuits composed of logical qubits of different types and sizes.

Here are some steps to guide you in this task:

1. Create a new branch on this repo named "feature/49/generalize-tcirc-qubit-type". Please regularly merge changes from master into this branch as you work on this task to keep the branch up to date.
2. Start by reading circ.py to see how TopologicalRegister and TopologicalCircuit stores and manipulates a set of topological qubits.
3. Begin by allowing TopologicalRegister to store logical qubits of different types, and then test that single logical qubit gates work as expected on circuits composed of logical qubits of different types.
4. Then, get the parity measurement based cx gate (already implemented for same type qubits) to work between logical qubits of different types.
5. Track/demonstrate your changes in a Jupyter Notebook stored under tutorials/.
6. Add unittests to tests/.
7. Once you have completed the above steps and there are no obvious bugs/broken code, please make a PR to merge your branch changes into master.
8. After getting reviewed and undergoing changes, the PR will be merged into master.

(Very Rough) Estimated Time: 2-3 weeks

Other things to keep in mind:

1. Please use the black python formatter (tutorial using vscode).
2. Please add typing hints and docstrings to any new code you write and wherever you find these missing.

In the tutorial https://github.com/yaleqc/qtcodes/blob/master/tutorials/xxzz/2-fitters.ipynb, the code
decoder = RotatedDecoder({"d":(9,7),"T":1})
tried to add rectangular lattice.
But, it is actually not supported, if you look at rotated_surface.py - it is not able to get a tuple in the loop that creates the lattice:
for j in range(0, self.params["d"], 2):
Where params["d"] is the tuple

As detailed in #65 (which aims to close #60 ), it should be relatively straight forward to enable the creation of repetition code qubits that are protected against Z flips, instead of the usual X (bit) flip protection.

We were briefly chatting about a (phase-flip-protected) repetition qubit protected against Z flips. On a related note, we could allow users to pass in "d": (1,3), "phase-flip-protected": True to RepetitionQubit when they want to create a phase-flip-protected repetition qubit. And, in the case where a user just sends in "d": (1,3) without setting "phase-flip-protected": True, we can raise a warning stating that the user is creating a phase-flip-protected repetition qubit instead of a possibly desired bit-flip-protected repetition qubit.
To enable this phase-flip-protected functionality, I believe we will just need to modify this parameter validation and add some tests.

Steps:

• Modify the parameter validation in circuits/repetition.py
• Modify the parameter validation in fitters/repetition.py
• Add tests to tests/rep.py

Other approaches to error-chain matching (e.g. neural networks or tensor networks).

As done in:
https://github.com/Qiskit/qiskit-ignis/blob/master/qiskit/ignis/verification/topological_codes/fitters.py#L220

If you search for int( you'll find casts throughout a lot of the codebase. This might be left-over from before _params_validation() was added. The task is to remove these redundant casts and add a few assertions/additional tests as needed.

Here's a nice guide: https://betterscientificsoftware.github.io/python-for-hpc/tutorials/python-pypi-packaging/

Use string constants for tcirc types (e.g. "XZZX"). Also add params validation and default values method to override.

Let's add some basic unit, integration, and E2E tests for fitters and circuits.

Unit Test: is a type of software testing where individual units or components of a software are tested. The purpose is to validate that each unit of the software code performs as expected.

Integration Test: is the phase in software testing in which individual software modules are combined and tested as a group

E2E Test: End-to-end testing verifies that your software works correctly from the beginning to the end of a particular user flow. It replicates expected user behavior and various usage scenarios to ensure that your software works as whole.

Resources:

• https://docs.python.org/3/library/unittest.html
• https://docs.python.org/3/library/unittest.mock.html (for unit tests)

Implement the basic Repetition Code MWPM Decoder.

Let's generalize the square rotated surface code encoder to a rectangular rotated surface code encoder.

Here are some steps to guide you in this task:

1. Create a new branch on this repo named "feature/28/rectangular-surface-code". Please regularly merge changes from master into this branch as you work on this task to keep the branch up to date.
2. Start by reading through rotated_surface.py, xxzz.py and xzzx.py and notice where self.params["d"] is used and relied upon. In this task, you will primarily change these files.
3. Update the call-sites of XXZZQubit and XZZXQubit to use XXZZSquareQubit and XZZXSquareQubit, which can be subclasses of the now more general XXZZQubit and XZZXQubit rectangular rotated surface code classes.
4. It may be possible to have RepetitionQubit extend from XXZZQubit (or at least RotatedQubit), as the Repetition code can be thought of as a very slim surface code. (Moved to #60)
5. Track/demonstrate your changes in a Jupyter Notebook stored under tutorials/.
6. Add unittests to tests/.
7. Once you have completed the above steps and there are no obvious bugs/broken code, please make a PR to merge your branch changes into master.
8. After getting reviewed and undergoing changes, the PR will be merged into master.

(Very Rough) Estimated Time: 2-3 weeks

Other things to keep in mind:

1. Please use the black python formatter (tutorial using vscode).
2. Please add typing hints and docstrings to any new code you write and wherever you find these missing.

The physics error rate below which larger surface codes become better is called the threshold.
We hope to show this crossing of logical error rates of different sized surface codes in simulation.

I'm making this issue because this project is part of the Qiskit ecosystem.

As of June 2024, we're introducing a requirement that all projects are compatible with Qiskit 1.0. New users will be using Qiskit 1.0 and we want to make sure any projects we guide them to work straight away.

See our migration guide. and let me know if you need any support (such as answering questions about Qiskit or code review). With Qiskit's new stability policy, this should be the last change needed for a while.

In June, we will test out your project and remove it if it doesn't work with Qiskit 1.0. This includes cases in which we can't get the project working because the documentation is lacking. We do value your project so let me know if you need any help migrating or have any other concerns.

Background

If an error occurs after the final round of stabilization and before the logical readout, then we can incur a logical error. To combat this issue, we have introduced the concept of lattice readout, where we readout every single data qubit, each along a particular readout axis. Then, we can extract a single set of syndrome measurements and logical readout from that lattice readout. For example, if we wish to perform logical Z readout, then we use lattice readout to extract Z syndrome measurements and logical Z readout from lattice readout.

Task

We want to add tests, similar to those in tests/rotated_surface.py but using lattice_readout_z in place of:

qubit.stabilize()
qubit.readout_z() 

Stretch

We can also add tests to address logical X readout paths for both lattice readout (lattice_readout_x) and normal logical readout (readout_x).

We leverage the parity measurement to implement a CNOT between surface code qubits, as shown below.

While we use a surface code ancilla, our parity measurements are not topologically protected. For example, we use CNOTs conditioned by data (physical) qubits in the top rows of two surface code qubits and targeting a single external physical qubit. Then, we measure the external physical qubit to perform a logical ZZ parity measurement between two surface code qubits. This external physical qubit is not topologically protected and could, however, undergo bit flip errors.

Instead, let's follow Ref. [1] and implement a parity measurement of the form:

Here are some concrete steps towards completing this task:

• Implement a ZZ parity measurement between two RotatedQubit qubits of the same type and same size using the top rows of each qubit.
  • This may involve defining an abstract method ToplogicalQubit.zz and implementing at the level of XXZZQubit (circuits/xxzz.py) and XZZXQubit (circuits/xzzx.py). Since the repetition code extends XXZZQubit, it does not need to be changed.
• Do the same as above for a XX parity measurement, using the left-most columns of each qubit.
• Deprecate the TopologicalQubit.cx method and all of its implementations, as this unprotected CNOT uses a single external qubit as a control (target) on a surface code target (control) qubit. With the new protected CNOT gates, we should not need this method at all.
• Update the tcirc notebook(s) accordingly to demo your changes.

Refs:
[1] https://arxiv.org/pdf/1709.02318.pdf

We cross-match X and Z errors to produce an overall Y error. However, this doesn't exactly match a depolarizing channel, so ideally the weights would be re-adjusted with conditional probabilities.

Hi,
I am trying to debug to understand why, but, when running https://github.com/yaleqc/qtcodes/blob/master/tutorials/xxzz/3-benchmarking.ipynb as is, it is not showing the same results - actually, it is not finding any logical errors.

We can set up automatic tests using GitHub Actions.

Ref: https://coderefinery.github.io/testing/continuous-integration/

I tried to run the code in the tutorial https://github.com/yaleqc/qtcodes/blob/master/tutorials/xxzz/2-fitters.ipynb
In the decoder.draw(G) Command - it is using Graphviz, which seems to make trouble with python 3.6.
I get this error:
FileNotFoundError: [WinError 2] "fdp" not found in path.
Which is tried to be solved in https://stackoverflow.com/questions/22698227/python-installation-issues-with-pygraphviz-and-graphviz
They y mention the fact that it is making troubles with python 3.5 and above

To realized fault-tolerant universal quantum computation using topological QEC, we must implement a non-Clifford gate. Here, we aim to implement the T gate and initialization for the magic state needed for the T gate.

• Add a reset_magic_T abstract method to circuits/rotated_surface.py , similar to reset_x. Then, implement this for the XZZX and XXZZ surface codes.
• Add a T abstract method to circuits/rotated_surface.py, similar to the x method. Then, implement this for the XZZX and XXZZ surface codes.

Note. We want these implementations to be fault-tolerant, meaning that this state initialization and gate are not vulnerable to single qubit errors on any qubit involved. However, this doesn't seem possible as of now. In practice, this is why people propose magic state distillation.

Once #18 is closed, we can use the same techniques used to build the XXZZ Decoder towards the XZZX Decoder.

This is great work, and I'm testing it for integration with other projects within qiskit. When noise models of significant amplitude are used, for example using the test harness (3_testing_and_noise_models), the decoder returns an error. Here is an example:

for i in range(10):
    print("====Run", i, "====")
    full_loop(code, decoder1, decoder2, noise_model=get_noise(0.1))
    print("=============", "\n")

returns different errors each time it is executed, but they all point to the same point in fitters.py:

====Run 0 ====
Raw readout: {'111101110 01001011 01010010 01011000': 1}
Parsed X: [(2, 2.5, 1.5)]
Parsed Z: [(0, 0.5, 0.5), (0, 0.5, 2.5), (0, 1.5, -0.5), (1, 1.5, -0.5), (1, 1.5, 1.5), (2, 0.5, 2.5), (2, 1.5, -0.5)]
---------------------------------------------------------------------------
KeyError                                  Traceback (most recent call last)
<ipython-input-10-1dab31d2f569> in <module>
      1 for i in range(10):
      2     print("====Run", i, "====")
----> 3     full_loop(code, decoder1, decoder2, noise_model=get_noise(0.1))
      4     print("=============", "\n")

<ipython-input-5-e58737e1f698> in full_loop(code, decoder1, decoder2, noise_model)
     26             matching_graph = decoder.matching_graph(error_graph,'Z')
     27             matches = decoder.matching(matching_graph,'Z')
---> 28             _, paths = decoder.make_error_graph(X_errors, "Z")
     29             flips_z = decoder.calculate_qubit_flips(matches, paths,'Z')
     30         else:

~/code/qiskit_surface_codes/surface_code/fitters.py in make_error_graph(self, nodes, error_key, err_prob)
    320                 error_graph.add_node(
    321                     node,
--> 322                     virtual=virtual_dict[node],
    323                     pos=(node[2], -node[1]),
    324                     time=time_dict[node],

KeyError: (2, 2.5, 1.5)

The code in this instance had d, T = 3, 3 and that location is valid (it is the bottom-most X-syndrome qubit).

This error doesn't show up when noise models are disabled.

The code is a bit messy right now, let's refactor the XXZZ decoder in an attempt to debug it and achieve threshold as detailed in #17 .

Refactoring includes:

• docstrings
• satisfy pylint
• simplification of methods
• potential speed-ups

Currently, barriers are created even after gates that should technically occur in the same 'moment', as shown below. Research if barriers actually affect the compiling and running of the circuit and consider removing the possibly superfluous barriers.

Include other decoding techniques, as done in:
https://github.com/Qiskit/qiskit-ignis/blob/master/qiskit/ignis/verification/topological_codes/fitters.py

Instead of having to specify TopologicalRegister(ctypes=[REPETITION, REPETITION], params=[{"d" : 3}, {"d" : 3}]), one could instead be able to use TopologicalRegister(2, ctype=REPETITION, params={"d": 3}).

• Add overloaded TopologicalRegister constructor in circ.py

Pydot is an additional dependency that doesn't work well on Windows (see pydot/pydot#278). As of retworkx 0.9.0 visualization was added, so let's make use of that.

Let's start by implementing a multi qubit gate for surface code based qubits.

These initial gates will be implemented between surface codes of the same size and type.

Later, we can generalize with more advanced concepts from Ref [1].

[1] https://arxiv.org/pdf/1709.02318.pdf

There are several potential ways to speed up benchmarking simulations.

• Currently, we are inserting identity gates where we want errors, which forces us to use an optimization level of 0 thus preventing additional optimizations in the rest of the circuit. Instead, we can insert the Krauss error operators directly.
• It may be faster to use density matrix simulation and then use that to measure the average value of the desired measurement operator (say logical Z readout) as follows, Tr(rho * measurement_operator).
• We should look into why adding single qubit gates on the same qubit drastically increases simulation time. This may be because circuit depth is increasing with each addition gate on the same qubit.

Start writing wiki pages.

It would help with visualization I think if we encapsulate logical X, Y, Z and stabilize with custom gates, so that circuit visualizations are more reasonable. Then, if a user wants to decompose the circuit further they can to see the same circuit visualizations that we currently have.

The simulation tutorials/rep/2-fitters-lookup.ipynb requires errors being inserted between the stabilizer measurements to produce a lookup table of possible results. This works on elementary OS, but not on OSx.

Expected Result (elementary OS):

Incorrect Result (Mac OSx):

This is probably an issue with the aer_simulator.

Update the readme to reflect new direction of more general topological qubits, registers and circuits.

Qiskit has a transpiler, which can transform and optimize circuits via various passes. Passes can be run individually if instantiated as such or can be included in different PassManagers as a default.

The idea here is that we can create a PassManager to make use of qtcodes to take a standard Qiskit circuit and transpile it to a qtcode circuit. Ideally, qtcodes could inject the Pass into Qiskit upon initialization, but if that is not possible, then perhaps we can define a custom PassManager on the qtcodes side that can be used when one wants to transpile a standard circuit to an error-correcting one.

One of the unique features of a pass is that it can consider the actual hardware when performing the pass operation. This feature can be used to transpile a standard circuit into a qtcode circuit that can run on actual hardware. An error could be thrown if that is not possible based on the coupling map or the number of qubits available.

There may be some overlap between this task and #63 or perhaps one can be used by the other.

Add support to run Rep Code on real IBM Quantum Computers

Some infra we might want to provide:

• coupling map support
• transpiling
• base class for other codes to use as well

Refs:

• https://qiskit.org/textbook/ch-quantum-hardware/error-correction-repetition-code.html#Running-a-repetition-code-benchmarking-procedure

It would be awesome to demonstrate threshold for the repetition code run on a real quantum computer!

Retworkx is adding a num_shortest_paths esque method: Qiskit/rustworkx#355

Let's use this internal retworkx method rather than num_shortest_paths from https://github.com/yaleqc/qiskit_surface_codes/blob/master/topological_codes/fitters/graph_utils.py

This can be implemented after retworkx 0.10.0 is released.

Hi all,

I am new to to qec code and I apologize for any inconvenience .

I was running the tutorial of XXZZ benchmark, but what I got was different than the figures showed in the tutorial.
surface_perf1.pdf
surface_perf2.pdf

I have checked the d_3_T_1.npz and make sure it is loaded by TopologicalBenchmark. The results remain the same.

Thanks for the help!

Implement look-up table benchmarking tool, and generate similar graphs. Also, it would be interesting to compare both the efficiency and efficacy of look-up table vs graph decoding.

We need a way to uniquely represent tcirc components (e.g. single/multi qubit gates, readout, etc).

Among other use cases, this is essential for properly decoding the a tcirc readout string.

Some potential resources include:

• https://qiskit.github.io/openqasm/language/index.html
• https://devblogs.microsoft.com/qsharp/introducing-quantum-intermediate-representation-qir/

Extend RepetitionQubit from XXZZQubit (or at least RotatedQubit), as the Repetition code can be thought of as a very slim surface code. This would follow the work from #27 and #28.

Add a RepetitionPhaseQubit as well as a "row" repetition code.

Some relative README links on https://pypi.org/project/qtcodes/ are broken. We need to fix this by the next release.

Let's generalize the square rotated surface code decoder to a rectangular rotated surface code decoder.