rcc-refcert 0.1.0__tar.gz

rcc_refcert-0.1.0/.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,46 @@
+name: Bug report
+description: Report an unexpected numerical, interface, or documentation result.
+title: "[Bug] "
+body:
+  - type: textarea
+    id: observed
+    attributes:
+      label: Observed behavior
+      description: Include the command, API call, case, and complete outcome that differed from expectation.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: Explain the expected numerical, mathematical, or interface result.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Minimal reproduction
+      description: Provide a minimal model or the shortest sequence of commands that reproduces the issue.
+      render: shell
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Package version or commit
+      placeholder: rcc-refcert 0.1.0 or commit SHA
+    validations:
+      required: true
+  - type: input
+    id: environment
+    attributes:
+      label: Python, NumPy, and operating system
+      placeholder: Python 3.12, NumPy 2.x, Ubuntu
+    validations:
+      required: true
+  - type: textarea
+    id: diagnostics
+    attributes:
+      label: Relevant diagnostics
+      description: Add residuals, tolerances, support warnings, or JSON fields that help localize the issue. Remove private data before posting.
+

rcc_refcert-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,3 @@
+blank_issues_enabled: true
+contact_links: []
+

rcc_refcert-0.1.0/.github/ISSUE_TEMPLATE/documentation.yml

@@ -0,0 +1,34 @@
+name: Documentation improvement
+description: Improve a scientific explanation, example, or RCC paper-to-code connection.
+title: "[Docs] "
+body:
+  - type: input
+    id: location
+    attributes:
+      label: Location
+      description: Name the page, section, notebook cell, CLI output, or report passage.
+    validations:
+      required: true
+  - type: dropdown
+    id: audience
+    attributes:
+      label: Intended reader
+      options:
+        - First-time RCC paper reader
+        - Quantum-information researcher
+        - Model or certificate contributor
+        - Numerical or software contributor
+    validations:
+      required: true
+  - type: textarea
+    id: problem
+    attributes:
+      label: What is unclear or missing?
+      description: Identify the scientific distinction, workflow step, or project boundary that is difficult to understand.
+    validations:
+      required: true
+  - type: textarea
+    id: improvement
+    attributes:
+      label: Suggested improvement
+      description: A draft is welcome but not required.

rcc_refcert-0.1.0/.github/ISSUE_TEMPLATE/scientific-proposal.yml

@@ -0,0 +1,57 @@
+name: Scientific proposal
+description: Propose a model, certificate method, or structure-fair research extension.
+title: "[Research] "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this form for a concrete extension to the finite-control RCC research kernel. Proposals may introduce a model, certificate method, cost assignment, negative witness, or verification technique. The form keeps the scientific question distinct from the claims the current package can already verify.
+  - type: textarea
+    id: question
+    attributes:
+      label: Scientific question
+      description: What structural resource, model family, certificate problem, or boundary should this work clarify?
+      placeholder: State the research question and why it matters for structure-fair complexity.
+    validations:
+      required: true
+  - type: dropdown
+    id: area
+    attributes:
+      label: Primary area
+      options:
+        - Physical or finite-control model
+        - Bellman–Choi certificate
+        - Reference-potential certificate
+        - Reference gain–cost encoding
+        - Family-uniform or scaling analysis
+        - Numerical verification
+        - Interface or simulation backend
+        - Documentation or example
+    validations:
+      required: true
+  - type: textarea
+    id: construction
+    attributes:
+      label: Proposed construction
+      description: Describe the reference, controls, operations, certificate object, or algorithm at the level currently known.
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Expected executable evidence
+      description: Which finite-model outcome, invariant, negative witness, or regression should the package produce?
+    validations:
+      required: true
+  - type: textarea
+    id: claim_boundary
+    attributes:
+      label: Claim boundary
+      description: Identify the accompanying analytic or physical obligations, such as RCon, TC, family uniformity, or theorem-level interpretation.
+    validations:
+      required: true
+  - type: textarea
+    id: references
+    attributes:
+      label: RCC paper map and references
+      description: List the RCC sections, equations, or external results needed to evaluate the proposal.

rcc_refcert-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,160 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  RCC_REFCERT_SOURCE_REVISION: ${{ github.sha }}
+
+jobs:
+  source-tree:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.10"
+          cache: pip
+      - name: Install source-tree test dependencies
+        run: python -m pip install "numpy==1.26.4" "pytest>=8"
+      - name: Test without installed package metadata
+        run: PYTHONPATH=src python -W error -m pytest
+      - name: Reproduce frozen report from source
+        run: >-
+          PYTHONPATH=src python -m rcc_refcert reproduce --check
+          results/reference_report.md
+
+  test:
+    needs: source-tree
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - python-version: "3.10"
+            numpy-spec: "numpy==1.26.4"
+          - python-version: "3.11"
+            numpy-spec: "numpy>=1.26"
+          - python-version: "3.12"
+            numpy-spec: "numpy>=1.26"
+          - python-version: "3.13"
+            numpy-spec: "numpy>=1.26"
+          - python-version: "3.14"
+            numpy-spec: "numpy>=1.26"
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install
+        run: |
+          python -m pip install "${{ matrix.numpy-spec }}"
+          python -m pip install -e ".[dev]"
+      - name: Test
+        run: |
+          ruff check src tests examples quickstart.py RCC_Quickstart.ipynb
+          ruff format --check src tests examples quickstart.py RCC_Quickstart.ipynb
+          python -W error -m pytest
+      - name: Check installed version identity
+        run: |
+          python -c "from importlib.metadata import version; import rcc_refcert; assert rcc_refcert.__version__ == version('rcc-refcert')"
+      - name: Reproduce frozen report
+        run: rcc-refcert reproduce --check
+
+  distribution-smoke:
+    needs: source-tree
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Build wheel and source distribution
+        run: |
+          python -m pip install "build>=1.2"
+          python -m build
+      - name: Install and exercise each distribution outside the checkout
+        run: |
+          distribution_directory="$PWD/dist"
+          for artifact in "$distribution_directory"/*.whl "$distribution_directory"/*.tar.gz; do
+            installation_root="$(mktemp -d)"
+            environment="$installation_root/environment"
+            python -m venv "$environment"
+            "$environment/bin/python" -m pip install "$artifact"
+            mkdir "$installation_root/run"
+            cd "$installation_root/run"
+            "$environment/bin/rcc-refcert" reproduce --check
+            "$environment/bin/rcc-refcert" example dephase-or-halt --format json
+            "$environment/bin/python" -c "from importlib.metadata import version; import rcc_refcert; assert rcc_refcert.__version__ == version('rcc-refcert')"
+          done
+
+  public-entry-smoke:
+    needs: source-tree
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - windows-latest
+          - macos-latest
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Run the complete public quickstart entry point on Windows
+        if: runner.os == 'Windows'
+        run: python quickstart.py
+      - name: Run the reproduction entry point on macOS
+        if: runner.os == 'macOS'
+        run: python quickstart.py --reproduce-only
+
+  notebook:
+    needs: source-tree
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install Notebook environment
+        run: python -m pip install -e ".[notebook]"
+      - name: Register declared kernel
+        run: >-
+          python -m ipykernel install --user --name rcc-refcert
+          --display-name "Python (rcc-refcert)"
+      - name: Validate and execute Notebook
+        run: python tests/notebook_smoke.py
+
+  required:
+    if: ${{ always() }}
+    needs:
+      - source-tree
+      - test
+      - notebook
+      - distribution-smoke
+      - public-entry-smoke
+    runs-on: ubuntu-latest
+    steps:
+      - name: Verify required jobs
+        env:
+          SOURCE_TREE_RESULT: ${{ needs.source-tree.result }}
+          TEST_RESULT: ${{ needs.test.result }}
+          NOTEBOOK_RESULT: ${{ needs.notebook.result }}
+          DISTRIBUTION_SMOKE_RESULT: ${{ needs.distribution-smoke.result }}
+          PUBLIC_ENTRY_SMOKE_RESULT: ${{ needs.public-entry-smoke.result }}
+        run: |
+          test "$SOURCE_TREE_RESULT" = success
+          test "$TEST_RESULT" = success
+          test "$NOTEBOOK_RESULT" = success
+          test "$DISTRIBUTION_SMOKE_RESULT" = success
+          test "$PUBLIC_ENTRY_SMOKE_RESULT" = success

rcc_refcert-0.1.0/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+## 0.1.0 (2026-09-06)
+
+Initial release of `rcc-refcert`, a Python research toolkit for finite-control
+models and reference certificates in structure-fair quantum circuit complexity.
+The implementation follows manuscript version 4; see the
+[paper-to-code map](docs/PAPER_MAP.md) for its relation to the public paper.
+
+### Models and certificates
+
+- Define prefix-controlled quantum processes and compute their terminating
+  program semidensities, with explicit treatment of nonhalting sectors.
+- Check fixed-model reference domination, verify Bellman–Choi and
+  reference-potential certificates, and analyze reference gain–cost assignments
+  and sufficient prefix-code completions.
+- Construct and audit new finite-control models through the public Python API.
+
+### Examples and reproducibility
+
+- Three reference cases cover a closed-form construction, a multiblock model
+  with an intentional sufficient-route failure, and a recurrent nonhalting
+  boundary.
+- A complete paired-reset example connects a declared model and its reference
+  certificate to an RCC lower bound of one slot, attained by an explicit
+  one-slot preparation.
+- The `examples`, `example`, and `reproduce` commands provide readable reports
+  and versioned JSON. Packaged reference results support reproducibility checks
+  from both source checkouts and installed distributions.
+- A guided Jupyter notebook and model guide support a first run and the
+  construction of new research inputs.
+
+### Results and numerical conventions
+
+- Reports identify check outcomes, evidence levels, numerical tolerances, and
+  agreement with reference expectations.
+- Certificate reports separate candidate constants from usable upper bounds
+  that include numerical error corrections. Unresolved checks return
+  `inconclusive` with no usable constant; valid certificates can remain
+  unresolved for slowly halting dynamics.
+- Gain–cost checks account for numerical uncertainty at the Kraft boundary,
+  and suggested prefix codes use upper gain estimates. Unresolved linear
+  outputs retain finite-depth evidence and return no domination constant.
+- The [output contract](docs/OUTPUT_CONTRACT.md) and
+  [numerical conventions](docs/CONVENTIONS.md) describe result fields, support
+  diagnostics, and precision requirements.
+
+### Installation
+
+- Supports Python 3.10–3.14, with verified entry points on Linux, Windows, and
+  macOS.
+- A one-command quickstart creates an isolated environment with locked
+  verification dependencies, runs the test suite, and reproduces the reference
+  results. Fresh output is written separately from the reference files.
+- Wheel and source distributions include the reference evidence and CLI.

rcc_refcert-0.1.0/CITATION.cff

@@ -0,0 +1,52 @@
+cff-version: 1.2.0
+message: "If you use this software, cite the software and the associated RCC paper."
+title: "rcc-refcert: a Python research toolkit for structure-fair quantum circuit complexity"
+type: software
+version: 0.1.0
+date-released: 2026-09-06
+license: MIT
+repository-code: "https://github.com/yeruciwenrou-dotcom/rcc-refcert"
+abstract: >-
+  rcc-refcert is a Python research toolkit for structure-fair quantum circuit
+  complexity. It implements finite-control models and reference-certificate
+  methods of Reference-Contingent Complexity (RCC), making the supplied resources,
+  allowed quantum processes, and description and generation costs explicit.
+  Researchers can construct prefix-controlled quantum-process models, compute
+  terminating program semidensities, and check Bellman-Choi, reference-potential,
+  fixed-model domination, and reference gain-cost certificates. Three bundled
+  reference cases cover closed-form, multiblock, and nonhalting behavior. A worked
+  paired-reset model connects the physical declaration to a numerical RCC lower
+  bound of one slot, attained by an explicit one-slot preparation. The package
+  provides a Python API, command-line tools, a Jupyter quickstart, and versioned
+  numerical reports. Its checks provide reproducible evidence for declared
+  finite models, with explicit pass, fail, inconclusive, and not-applicable
+  outcomes. The accompanying paper supplies the physical and analytic premises
+  of the general RCC framework.
+keywords:
+  - quantum circuit complexity
+  - structure-fairness
+  - reference-contingent complexity
+  - quantum information
+  - finite-control quantum processes
+  - reference certificates
+  - reproducible research
+authors:
+  - family-names: Liu
+    given-names: HongZheng
+  - family-names: Tian
+    given-names: YiNuo
+  - family-names: Wu
+    given-names: Zhiyue
+preferred-citation:
+  type: article
+  title: "Structure-Fair Quantum Circuit Complexity: An Auditable Information-Theoretic Lower Bound"
+  authors:
+    - family-names: Liu
+      given-names: HongZheng
+    - family-names: Tian
+      given-names: YiNuo
+    - family-names: Wu
+      given-names: Zhiyue
+  year: 2025
+  journal: "arXiv preprint arXiv:2509.18205"
+  doi: "10.48550/arXiv.2509.18205"

rcc_refcert-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,99 @@
+# Contributing
+
+RCC studies quantum circuit complexity under an explicit physical generation
+model. Its structure-fairness principle accounts for the structure supplied by
+the reference background, available dynamics, and program description, together
+with the resources spent on generation.
+
+`rcc-refcert` makes finite models and certificate methods available for
+researchers to test and extend. Contributions can bring new physical models
+into the framework, compare certificate constructions, improve numerical
+reliability, or help readers reproduce and understand the results.
+
+Contributions can address one layer at a time:
+
+- **physical models:** new finite-control examples, resource assignments,
+  nonhalting mechanisms, or controlled counterexamples;
+- **certificate methods:** Bellman–Choi or reference-potential construction,
+  gain–cost encodings, negative witnesses, or family-scaling diagnostics;
+- **numerical reliability:** interval bounds, exact arithmetic, conditioning
+  diagnostics, solver integrations, or independent realizations;
+- **interfaces:** model serialization, larger simulation backends, and stable
+  machine-readable outputs;
+- **explanation and reproduction:** clearer derivations, examples, notebooks,
+  tests, and RCC paper-to-code maps.
+
+For a substantial scientific change, open a **Scientific proposal** describing
+the model or certificate object, the RCC result it affects, and the evidence
+needed to assess it. Use the bug or documentation issue form for a specific
+problem, with a reproducible input or a link to the affected passage.
+
+## Scientific contract
+
+Read [`docs/SCIENTIFIC_SCOPE.md`](docs/SCIENTIFIC_SCOPE.md) and
+[`docs/CONVENTIONS.md`](docs/CONVENTIONS.md) before changing the mathematical
+core. Changes to code weighting, Kraus composition, direct-sum order,
+vectorization, Choi tensor order, support handling, or fixed-point gates must
+explain their mathematical effect and include a focused regression.
+
+A convention or certificate change normally needs both:
+
+- a positive example that exercises the intended path;
+- a controlled negative or boundary example that catches the likely wrong
+  convention.
+
+Keep the claim layers visible in code, tests, and prose:
+
+1. a floating-point outcome for one finite input;
+2. a fixed-model semidensity, domination, or certificate statement;
+3. a model-family statement requiring a uniform argument;
+4. the RCC theorem under its complete physical and transcription hypotheses.
+
+The package directly produces the first two layers. A family-level or
+theorem-level claim also needs its uniform analytic, physical, and transcription
+arguments.
+
+## Adding a model or certificate
+
+A bundled model should expose a distinct physical mechanism, formula,
+convention risk, or mathematical boundary. Document:
+
+- the reference state, control spaces, actions, codewords, and intended
+  physical interpretation;
+- the Appendix F/H objects it exercises;
+- the expected outcomes, including designed route failures or boundaries;
+- the test that would fail under the most plausible incorrect implementation.
+
+An expected H.70 failure records a code-length shortfall along that sufficient
+route. An `inconclusive` result records an unresolved numerical condition. Check
+the other certificate routes for the original model; adopting suggested
+codewords changes its program weights and defines a re-encoded model.
+Family-uniform reference admissibility needs the corresponding uniform analytic
+argument.
+
+Keep dependencies few and tied to a clear package responsibility. Add parameter
+sweeps or user interfaces when they support a defined scientific use case and
+preserve the minimal kernel.
+
+## Local verification
+
+Install the development environment and run the core checks:
+
+```bash
+python -m pip install -e ".[dev]"
+ruff check src tests examples quickstart.py RCC_Quickstart.ipynb
+ruff format --check src tests examples quickstart.py RCC_Quickstart.ipynb
+python -W error -m pytest
+rcc-refcert reproduce --check
+python -m build
+```
+
+CI also executes the Notebook in its declared kernel, installs both distribution
+formats outside the checkout, and checks the public entry points on Windows
+and macOS. Certificate changes must preserve the distinction between a supplied
+candidate and the returned upper constant, including near-critical and
+nonhalting boundary regressions.
+
+If the scientific output intentionally changes, explain why, update the
+declared expectations, and regenerate both frozen reference files from the same
+verified run.

rcc_refcert-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HongZheng Liu, YiNuo Tian, and Zhiyue Wu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rcc_refcert-0.1.0/MANIFEST.in

@@ -0,0 +1,14 @@
+include CHANGELOG.md
+include CITATION.cff
+include CONTRIBUTING.md
+include RCC_Quickstart.ipynb
+include quickstart.py
+include requirements-quickstart.txt
+recursive-include .github *.yml
+recursive-include docs *.md
+recursive-include examples *.py
+recursive-include results *.md
+recursive-include results *.json
+recursive-include tests *.py
+recursive-include src/rcc_refcert/reference_data *.md
+recursive-include src/rcc_refcert/reference_data *.json

rcc_refcert-0.1.0/NOTICE.md

@@ -0,0 +1,5 @@
+# Notice
+
+The source code in this repository is released under the MIT License. Citation
+metadata for the software and associated RCC paper are provided in
+[`CITATION.cff`](CITATION.cff).