Repository navigation
Define the public API and qualify seed reproducibility for 1.0.0 - #268
Merged
Merged
Conversation
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
Contributor
|
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Removing the base-class reference entry leaves inherited encoder operations undocumented because inherited-member rendering is not enabled, including methods used by the distillation tutorial.
1 open issue
What changed in this PR
This PR defines Tsim’s stable API for 1.0.0 and clarifies seed reproducibility guarantees, while separating experimental helpers from the semantic-versioning contract.
Changes:
- Declares three stable public objects and adds experimental re-exports with API tests.
- Limits the generated reference to public and experimental objects and updates tutorial imports.
- Documents that seeded samples may differ across Tsim versions and CPU/GPU backends.
| File | Description |
|---|---|
test/unit/test_public_api.py |
Tests public exports and experimental aliases. |
src/tsim/sampler.py |
Qualifies seed reproducibility in sampler docstrings. |
src/tsim/experimental.py |
Re-exports three experimental helpers. |
src/tsim/circuit.py |
Updates compilation-method seed documentation. |
src/tsim/__init__.py |
Declares stable exports and API boundaries. |
README.md |
Documents stability guarantees and migration guidance. |
docs/scripts/gen_ref_nav.py |
Generates public and experimental reference pages. |
docs/index.md |
Adds API stability and seed guarantees. |
docs/demos/overview.ipynb |
Uses the experimental probability-sampler import. |
docs/demos/magic_state_distillation.ipynb |
Uses and labels the experimental encoder. |
CHANGELOG.md |
Records API boundaries and reproducibility guarantees. |
Review effort: Balanced
Contributor
☂️ Code Coverage
Overall Coverage
New Files
Modified Files
|
The public API is tsim.Circuit, tsim.CompiledMeasurementSampler and tsim.CompiledDetectorSampler (tsim.__all__). CompiledStateProbs, SteaneEncoder and ColorEncoder5 are re-exported from tsim.experimental, which may change in any release; every other module is internal. The API reference documents only these objects, and the tutorials import from tsim.experimental. Seed docstrings say a seed reproduces its samples only with the same Tsim version and backend (CPU or GPU). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
rafaelha
force-pushed
the
public-api-1.0
branch
from
November 4, 2026 12:16
fdefd59 to
ec8c0ec
Compare
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Seed docs name dependency versions and, for stabilizer-rank strategies, an explicit batch_size (the default depends on the free memory). - The API reference shows inherited members and hides bases and inheritance diagrams, so the encoders list their methods and no internal class shows. - docs/index.md links to the API reference; the public API test checks that every name in `tsim.__all__` resolves. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Only strategy="active_statevector" is stable; "cat5", "bss" and "cutting" may change or be removed in any release. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
They may be removed in a minor release, after at least one minor release in which they emit a DeprecationWarning. Docstrings say only that they are provisional; docs/index.md and the changelog state the policy. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Defines what tsim 1.0.0 commits to under semantic versioning.
Public API
tsim.__all__ = ["Circuit", "CompiledDetectorSampler", "CompiledMeasurementSampler"]. These are the only objects semver covers.tsim.__init__'s docstring and the docs index ("API stability") say that every other module is internal, even where it is importable.tsim.experimentalre-exportsCompiledStateProbs,SteaneEncoderandColorEncoder5, which the tutorials use. They may change in any release. The old import paths still work.docs/scripts/gen_ref_nav.pyno longer generates a page per module. The API reference has two pages, "Tsim API" (the three public objects) and "Experimental".overview.ipynbandmagic_state_distillation.ipynbimport fromtsim.experimental.Sampling strategies
Only
strategy="active_statevector"is fully stable. The stabilizer rank strategies ("cat5","bss","cutting") are provisional: they may be removed in a minor release, after at least one minor release in which they emit aDeprecationWarning. The docstrings say only "provisional"; the policy is in the "API stability" section ofdocs/index.mdand in the CHANGELOG.Seed reproducibility
The
seeddocstrings ofcompile_sampler,compile_detector_sampler, the sampler classes andCompiledStateProbsnow say that a seed reproduces its samples only with the same Tsim version and backend (CPU or GPU). Without this, changing a random stream (as #263 did), or adding a float32 GPU executor (#219), would technically be a breaking change.Test plan
uv run pytest test/unit: 2072 passed. Includes a newtest/unit/test_public_api.py.mkdocs buildfrom a clean checkout. The tutorials run, and the reference contains onlytsim.Circuit, the two samplers and thetsim.experimentalobjects.🤖 Generated with Claude Code