v0.3.0: Refactor API, type hierarchy, and documentation #141

GiggleLiu · 2026-01-24T10:42:14Z

Summary

Major refactor for v0.3.0 release:

Type hierarchy: Migrated QuantumCode/CSSQuantumCode to QECCore's AbstractQECC/AbstractCSSCode, enabling cross-package interop
New API entry point: DecodingProblem(code, error_model) → compile(decoder, problem) → decode(compiled, syndrome)
QECCore interface: All codes now implement parity_matrix, code_n, code_s, code_k
Export cleanup: Reduced public API from ~90 symbols to ~60, internalizing implementation details
Naming fixes: check_linear_indepent → check_linear_independent, TrainningData → TrainingData, qc2enisum → qc2einsum
Documentation: User guide, organized API reference, comprehensive docstrings
Removed v2.x deprecations: Clean slate for v0.3

Breaking Changes

Code types now subtype AbstractQECC/AbstractCSSCode instead of removed QuantumCode/CSSQuantumCode
~30 internal symbols removed from exports (still accessible via TensorQEC.name or explicit import)
Old deprecation aliases (PauliGroup, densitymatrix2sumofpaulis, etc.) removed
Version bumped to 0.3.0

Test plan

All existing tests pass
New type hierarchy tests
New QECCore interface tests
New DecodingProblem pipeline tests (72 tests covering multiple codes × decoders)
Deprecation alias tests
Coverage analysis (deferred - Coverage.jl install issue)

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 4.5 <[email protected]>

…e_k) for all codes Add parity_matrix, code_k, parity_matrix_x, and parity_matrix_z implementations for all TensorQEC code types, enabling them to fully conform to the QECCore interface. This creates a bidirectional bridge: QECCore codes can be converted to PauliStrings (existing fallback), and TensorQEC codes can now produce parity matrices for QECCore consumers. Co-Authored-By: Claude Opus 4.5 <[email protected]>

Provides a simplified entry point to the decoding pipeline by constructing the appropriate DecodingProblem directly from a code and error model, without requiring the user to build a Tanner graph. Co-Authored-By: Claude Opus 4.5 <[email protected]>

…ingData, qc2einsum) Rename misspelled public API names: - check_linear_indepent -> check_linear_independent - TrainningData -> TrainingData - qc2enisum -> qc2einsum Add deprecation aliases in src/deprecate.jl for backward compatibility. Co-Authored-By: Claude Opus 4.5 <[email protected]>

Reduce exported symbols to only the public API. Internal implementation details are no longer exported but remain accessible via TensorQEC.name. Test files updated with explicit imports for previously-exported internals. Co-Authored-By: Claude Opus 4.5 <[email protected]>

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Group include statements by logical subsystem with section comments for improved readability. The dependency order is verified to compile and pass all tests. Sections: Mod2, Pauli/Clifford, Codes, Tensor Network Core, Error Models, DEM, Decoding Framework, Decoders, Measurement, Tensor Network Simulation, Inference, Yao Extensions, STIM Parser, Multiprocessing, Deprecations. Co-Authored-By: Claude Opus 4.5 <[email protected]>

These deprecations have been around since v2.x and have had sufficient time for users to migrate. The v0.3 typo-fix deprecations are retained. Co-Authored-By: Claude Opus 4.5 <[email protected]>

Co-Authored-By: Claude Opus 4.5 <[email protected]>

… interop Co-Authored-By: Claude Opus 4.5 <[email protected]>

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Extend the pipeline test file with multi-decoder tests (BPDecoder, IPDecoder, MatchingDecoder, TNMAP, TNMMAP), logical error checking with zero syndromes, classical decoding problems, and round-trip error simulation across multiple code types (SteaneCode, SurfaceCode, ShorCode, ToricCode). Co-Authored-By: Claude Opus 4.5 <[email protected]>

Copilot

Pull request overview

Major v0.3.0 refactor to align TensorQEC with QECCore’s type hierarchy and introduce a new decoding pipeline API, alongside export cleanup and expanded documentation/tests.

Changes:

Migrates code types to QECCore AbstractQECC / AbstractCSSCode and implements QECCore interface methods (e.g., parity_matrix, code_k).
Introduces/standardizes the decoding pipeline entrypoint (DecodingProblem → compile → decode) and adds an end-to-end pipeline test suite.
Reorganizes exports and significantly expands/structures docs (new “Getting Started” guide + API reference).

Reviewed changes

Copilot reviewed 40 out of 41 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
Project.toml	Bumps package version for the release.
src/TensorQEC.jl	Reorganizes exports and include order around the new public API surface.
src/codes/codes.jl	Migrates code type hierarchy to QECCore + adds QECCore interface implementations.
src/codes/ldpc.jl	Updates `CSSTannerGraph` constructor to accept QECCore CSS abstract type.
src/codes/gaussian_elimination.jl	Renames linear-independence helpers to corrected spelling.
src/codes/code_distance.jl	Improves/updates docstring for `code_distance`.
src/decoding/interfaces.jl	Adds `DecodingProblem` entrypoints and expands `compile`/`decode` docs.
src/decoding/error_model.jl	Adds docstrings for syndrome types (`SimpleSyndrome`, `CSSSyndrome`).
src/decoding/bposd.jl	Updates BP decoder docs and renames linear-independence call site.
src/decoding/ipdecoder.jl	Expands IP decoder documentation with the new pipeline framing.
src/decoding/matching.jl	Updates Matching decoder documentation and API description.
src/decoding/tndecoder.jl	Expands TN decoder documentation with the new pipeline framing.
src/decoding/measurement.jl	Adds documentation for measurement circuit helper.
src/decoding/threshold.jl	Adds documentation for multi-round QEC simulation helper.
src/decoding/dem.jl	Adds documentation for detector error model types/functions.
src/nonclifford/simulation.jl	Renames `qc2enisum` → `qc2einsum` and adds docstrings.
src/nonclifford/error_learning.jl	Renames `TrainningData` → `TrainingData` and updates call sites.
src/stim_parser/stim_parser.jl	Expands Stim parser docstring and clarifies return type/coverage.
src/deprecate.jl	Replaces old deprecations with v0.3 typo-fix deprecations/aliases and notes removed exports.
src/clifford/tableaux.jl	Adds documentation for `Tableau` and tableau simulation helpers.
src/clifford/cliffordgroup.jl	Adds documentation for `compile_clifford_circuit`.
docs/make.jl	Adds “Getting Started” to docs navigation.
docs/src/guide.md	New user-facing guide for v0.3 workflows (simulation, analysis, STIM interop).
docs/src/man.md	Replaces generic index/autodocs with a curated API reference layout.
test/runtests.jl	Adds decoding pipeline tests to the test runner.
test/decoding/decoding_pipeline.jl	New end-to-end tests for `DecodingProblem`/`compile`/`decode` across codes/decoders.
test/decoding/bposd.jl	Updates tests to the corrected `check_linear_independent` name and imports.
test/decoding/matching.jl	Adjusts imports to reflect export cleanup for matching solver types.
test/decoding/measurement.jl	Adjusts imports to reflect export cleanup.
test/decoding/truthtable.jl	Adjusts imports to reflect export cleanup.
test/decoding/general_decoding.jl	Adjusts imports to reflect export cleanup.
test/decoding/inferenceswithencoder.jl	Adjusts imports to reflect export cleanup.
test/codes/codes.jl	Adds tests for QECCore type hierarchy + QECCore interface conformance.
test/codes/ldpc.jl	Adjusts imports to reflect export cleanup.
test/clifford/tableaux.jl	Adjusts imports to reflect export cleanup.
test/clifford/cliffordgroup.jl	Adjusts imports to reflect export cleanup.
test/deprecate.jl	Replaces removed v2-era deprecation tests with v0.3 typo-alias coverage.
test/nonclifford/simulation.jl	Updates test names and imports to reflect renamed/hidden APIs.
test/nonclifford/error_learning.jl	Updates tests for `TrainingData` rename and export cleanup.
test/nonclifford/tensornetwork.jl	Adjusts imports to reflect export cleanup.
test/nonclifford/correction.jl	Adjusts imports to reflect export cleanup.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

docs/src/guide.md

test/decoding/decoding_pipeline.jl

src/decoding/interfaces.jl

src/decoding/matching.jl

docs/src/guide.md

codecov · 2026-01-24T10:55:58Z

Codecov Report

❌ Patch coverage is 95.69892% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 94.87%. Comparing base (4ca1dfb) to head (b286780).

Files with missing lines	Patch %	Lines
src/codes/codes.jl	97.26%	2 Missing ⚠️
src/nonclifford/error_learning.jl	75.00%	1 Missing ⚠️
src/yaoblocks.jl	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #141      +/-   ##
==========================================
+ Coverage   94.84%   94.87%   +0.02%     
==========================================
  Files          29       29              
  Lines        2869     2944      +75     
==========================================
+ Hits         2721     2793      +72     
- Misses        148      151       +3

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

- Remove Aqua from [deps] (test-only dependency) - Add test/Project.toml with all test dependencies - Fix method ambiguity in chsubblocks(::NumberedMeasure, ::AbstractBlock) - Fix cross-reference errors in docs (@P_str, CliffordSimulateResult) - Export code_n, code_s, code_k - Fix bare `using Yao` in test files to use TensorQEC.Yao - Add parity matrix tests for codes - Move compile() outside loop in decoding pipeline test - Fix docstring for MatchingDecoder 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>

nzy1997 · 2026-01-25T09:53:48Z

src/decoding/interfaces.jl

+function DecodingProblem(code::AbstractCSSCode, error_model::IndependentFlipError)
+    tanner = CSSTannerGraph(code)
+    return ClassicalDecodingProblem(tanner.stgx, error_model)
+end


IndependentFlipError usually models bit-flip (X) errors whose syndrome is given by Z stabilizers. Using tanner.stgx here seems inverted relative to syndrome_extraction; should this be stgz, or clarify if this is meant to model phase flips?

src/decoding/dem.jl

nzy1997 · 2026-01-25T10:09:27Z

Project.toml

 uuid = "0500ac79-7fb5-4262-aaea-37bb1845d1ef"
+version = "0.3.0"
 authors = ["Zhongyi Ni"]
-version = "2.2.1"


Version number looks wrong here. Should this be 3.0.0?

GiggleLiu and others added 13 commits January 24, 2026 15:33

refactor: migrate code types to QECCore AbstractQECC hierarchy

22ae952

Co-Authored-By: Claude Opus 4.5 <[email protected]>

docs: document removed exports with migration hints in deprecate.jl

5b53a11

Co-Authored-By: Claude Opus 4.5 <[email protected]>

refactor: remove v2.x deprecation aliases

f86a58b

These deprecations have been around since v2.x and have had sufficient time for users to migrate. The v0.3 typo-fix deprecations are retained. Co-Authored-By: Claude Opus 4.5 <[email protected]>

docs: add comprehensive docstrings to public API functions

98b060a

Co-Authored-By: Claude Opus 4.5 <[email protected]>

docs: add user guide covering QEC simulation, code analysis, and STIM…

7f0dba0

… interop Co-Authored-By: Claude Opus 4.5 <[email protected]>

docs: reorganize API reference by functional category

41e0534

Co-Authored-By: Claude Opus 4.5 <[email protected]>

chore: bump version to 0.3.0

063cc16

Co-Authored-By: Claude Opus 4.5 <[email protected]>

GiggleLiu requested a review from Copilot January 24, 2026 10:43

Copilot started reviewing on behalf of GiggleLiu January 24, 2026 10:43 View session

Copilot AI reviewed Jan 24, 2026

View reviewed changes

GiggleLiu requested a review from nzy1997 January 24, 2026 16:41

nzy1997 reviewed Jan 25, 2026

View reviewed changes

src/decoding/dem.jl Show resolved Hide resolved

nzy1997 reviewed Jan 25, 2026

View reviewed changes

src/decoding/dem.jl Show resolved Hide resolved

nzy1997 reviewed Jan 25, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

v0.3.0: Refactor API, type hierarchy, and documentation #141

v0.3.0: Refactor API, type hierarchy, and documentation #141

Uh oh!

GiggleLiu commented Jan 24, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov bot commented Jan 24, 2026 •

edited

Loading

Uh oh!

nzy1997 Jan 25, 2026

Uh oh!

Uh oh!

Uh oh!

nzy1997 Jan 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

v0.3.0: Refactor API, type hierarchy, and documentation #141

Are you sure you want to change the base?

v0.3.0: Refactor API, type hierarchy, and documentation #141

Uh oh!

Conversation

GiggleLiu commented Jan 24, 2026

Summary

Breaking Changes

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov bot commented Jan 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

nzy1997 Jan 25, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

nzy1997 Jan 25, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

codecov bot commented Jan 24, 2026 •

edited

Loading