v1.0.0

QUITS v1.0.0

QUITS is a modular circuit-level simulator for QLDPC codes (code construction, circuit strategy, decoder, and noise model).

Highlights

• Modular architecture across codes, circuit construction, decoders, and noise models
• Added BB code, zxcoloration circuit of bring-your-own-code
• Documentation notebooks in doc/

Compatibility

• Python: >=3.10

Modular restructuring of the package

Refactor Plan (Updated with Completed Changes)

This plan captures the key refactors and API changes implemented so far.

Summary of Key Revisions

• Added modular circuit-construction strategies under qldpc_code/circuit_construction/.
• Introduced build_circuit(...) as the primary entrypoint, with build_graph(...) retained only as a deprecated wrapper.
• Added new code family: Lift-connected surface code (LscCode) and tests.
• Renamed QlpCode2 to QlpPolyCode and updated exports/usages.
• Updated tests and notebooks to use build_circuit instead of build_graph.
• Added canonical logical controls and verbose logging for HGP/BPC.
• Adjusted CSS logical verification criteria and pairing checks.

Current Target Layout

src/quits/
  __init__.py
  api.py
  circuit.py
  decoder/
    __init__.py
    base.py
    bposd.py
    bplsd.py
    sliding_window.py
  qldpc_code/
    __init__.py
    base.py
    hgp.py
    qlp.py
    bpc.py
    lsc.py
    circuit_construction/
      __init__.py
      base.py
      cardinal.py
      xzcoloration.py
      freeform.py
  gf2_util.py
  ldpc_util.py
  simulation.py

Implemented Changes (Details)

Circuit construction modularity

• Added qldpc_code/circuit_construction/ with a strategy registry and base interface.
• Implemented CardinalBuilder; added placeholders for XZColorationBuilder and FreeformBuilder.
• Moved cardinal graph-building helpers into CardinalBuilder.
• QldpcCode.build_circuit() delegates to the selected builder.
• build_graph() now warns via DeprecationWarning and calls build_circuit(strategy="cardinal", ...).

Code-family updates

• HgpCode, QlpCode, QlpPolyCode, and BpcCode override build_circuit(...) for the cardinal strategy.
• QlpCode2 renamed to QlpPolyCode (exports updated in qldpc_code/__init__.py and api.py).
• Added LscCode in qldpc_code/lsc.py, parameterized by lift_size (L) and length (l+1).

Canonical logicals + verbose mode

• HgpCode and BpcCode accept verbose; print when canonical logicals are used.
• HgpCode.get_logicals renamed to get_canonical_logicals.
• BpcCode.get_logicals renamed to get_canonical_logicals.
• BpcCode canonical logicals now:
  • Mix Z logicals (default) to enforce weight 2*q.
  • Re-pair LX/LZ to make pairing identity.
  • Optionally swap to make X logicals weight 2*q (canonical_weight="x").

CSS logical verification

• verify_css_logicals now computes pairing using overlap parity (mod 2).
• pairing_is_identity is required for report["ok"].
• Style updated to store pairing_is_identity in a local variable like other checks.

Tests and docs

• Tests now call build_circuit(...) (including tests/test_codes.py, tests/test_circuit.py, etc.).
• Added LscCode test inside tests/test_codes.py.
• Notebooks updated:
  • All build_graph → build_circuit in docs.
  • 01_codes_basics.ipynb includes canonical-logicals explanation + print cells for HGP/BPC.
  • old_intro.ipynb updated to QlpPolyCode.
• doc/circuit_distance_search.py updated to build_circuit.

Compatibility Strategy (Current)

• build_graph still exists as a deprecated wrapper to avoid immediate breakage.
• Public imports are maintained via qldpc_code/__init__.py and api.py.

Suggested Next Steps

• Implement XZColorationBuilder and FreeformBuilder.
• Optionally add a small helper to compute full pairing matrices for diagnostics.
• Consider deprecating/removing build_graph after a transition period.

Full Changelog: v0.4.0...v0.5.0

Canonical codeword bug fixed & gf2_util.py added

What's Changed

• HGP canonical codeword bug fixed (Please check the new version if you were using the HGP code)
• HGP codewords are set in cardinal form only when full-rank classical parity check matrices are given in #9
• BPC canonical codeword will be fixed soon.
• gf2_util.py (basic linear algebra funtions) added in #10
• Test function for logical codeword verify_css_logicals added.
• Tuple inputs for error rates (each element for each Pauli type) enabled in #6

Full Changelog: v0.3.0...v0.4.0

Canonical codewords for HGP and BPC codes

• For the HGP and BPC codes, the logical operators lz and lx are now written in the "canonical" form. get_logicals function is added to the HgpCode and BpcCode classes in src/quits/qldpc_code.py. See doc/intro.ipynb for example.

• A bug is fixed for the BPC code where $p_1$ and $p_2$ polynomials have different lengths. We also found that the convention by QUITS is different from arXiv:2411.03302 (although this does not significantly change the code performance for the examples we previously explored); to match the paper, the transpose of $p_2$ in arXiv:2411.03302 should be inputted to $p_2$ in QUITS. This is as simple as replacing each entry (representing the power of each term in the polynomial) with lift_size minus entry. Check doc/intro.ipynb for example.

Full Changelog : v0.2.0...v0.3.0

QLP code with polynomial entries & Circuit distance search

What's Changed

• QLP code with polynomial entries enabled by QlpCode2 class. For example, circuits for lift-connected surface codes can be generated. This example is added to doc/intro.ipynb.
• doc/circuit_distance_search.py added. This script gives an example of searching an upper bound to the circuit distance, using stim's search_for_undetectable_logical_errors function.

Full Changelog: v0.1.0...v0.2.0

Bug in indexing of coloration result fixed

In the previous version, for circuits of all QLDPC codes, there were several instances where CX gates in the same layer are applied on more than one qubits. This was due to a bug in how the indices of the keys (nodes in the rev_graph) are shuffled after networkx's greedy_color is applied. The coloration itself was done correctly, so the circuit depth (syndrome extraction depth) is correct; the part where colors are assigned to CX gates (edges of the Tanner graph) is done incorrectly.

The bug is now fixed, and now all CX gates in the same layer are applied to different qubits, as expected. We also added a check function check_overlapping_CX in src/quits/circuit.py (see doc/intro.ipynb for usage).

Full Changelog: https://github.com/mkangquantum/quits/commits/v0.1.0