nexqus-sdk 1.0.0__tar.gz

nexqus_sdk-1.0.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,21 @@
+name: Bug report
+description: Report a reproducible SDK problem
+body:
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: SDK, Python, NumPy, Torch/CUDA versions, OS and GPU (if used)
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal reproduction
+      description: Small complete circuit, simulator options, random seed, expected and actual results. Remove credentials and private data.
+    validations:
+      required: true
+  - type: textarea
+    id: output
+    attributes:
+      label: Error or validation output

nexqus_sdk-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,130 @@
+name: SDK validation
+
+on: [push, pull_request, workflow_dispatch, workflow_call]
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.head_ref || github.ref_name }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+env:
+  PYTHONUTF8: '1'
+  OMP_NUM_THREADS: '1'
+  OPENBLAS_NUM_THREADS: '1'
+  MKL_NUM_THREADS: '1'
+  MPLBACKEND: Agg
+
+jobs:
+  core:
+    name: NumPy ${{ matrix.os }} Python ${{ matrix.python }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python: ['3.10', '3.11', '3.12', '3.13', '3.14']
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v7.0.0
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install .
+      - run: python scripts/check_release.py --public
+
+  minimum-numpy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v7.0.0
+        with:
+          python-version: '3.10'
+      - run: python -m pip install numpy==1.24.4 .
+      - run: python scripts/check_release.py --public
+
+  torch-cpu:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v7.0.0
+        with:
+          python-version: '3.12'
+      - run: python -m pip install "torch>=2.2,<3" --index-url https://download.pytorch.org/whl/cpu
+      - run: python -m pip install .
+      - run: python scripts/check_release.py --public --require-torch
+      - uses: actions/upload-artifact@v7.0.2
+        if: always()
+        with:
+          include-hidden-files: true
+          name: torch-cpu-validation
+          path: .release-artifacts/release_validation.json
+
+  notebooks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v7.0.0
+        with:
+          python-version: '3.12'
+      - run: python -m pip install ".[tutorial]"
+      - run: python -m ipykernel install --user --name nexqus --display-name "Python (NexQus)"
+      - run: python scripts/run_notebooks.py --engine jupyter --kernel nexqus
+      - uses: actions/upload-artifact@v7.0.2
+        if: always()
+        with:
+          include-hidden-files: true
+          name: jupyter-validation
+          path: |
+            .release-artifacts/notebook_execution.json
+            notebooks/*.ipynb
+
+  distribution:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v7.0.0
+        with:
+          python-version: '3.12'
+      - run: python -m pip install ".[release]"
+      - run: python -m build
+      - run: python -m twine check --strict dist/*
+      - run: python scripts/check_distribution.py
+      - uses: actions/upload-artifact@v7.0.2
+        if: always()
+        with:
+          include-hidden-files: true
+          name: candidate-distributions
+          path: |
+            dist/*
+            .release-artifacts/distribution_validation.json
+
+  core-dependency-audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v7.0.0
+        with:
+          python-version: '3.12'
+      - run: python -m pip install . pip-audit
+      - run: python -c "import numpy; print('numpy==' + numpy.__version__)" > core-audit-requirements.txt
+      - run: python -c "from pathlib import Path; Path('.release-artifacts').mkdir(exist_ok=True)"
+      - run: python -m pip_audit --strict --disable-pip --no-deps -r core-audit-requirements.txt -f json -o .release-artifacts/dependency_audit_core.json
+      - uses: actions/upload-artifact@v7.0.2
+        if: always()
+        with:
+          include-hidden-files: true
+          name: core-dependency-audit
+          path: .release-artifacts/dependency_audit_core.json

nexqus_sdk-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,77 @@
+name: Publish reviewed distribution
+
+on:
+  workflow_dispatch:
+    inputs:
+      repository:
+        description: Package index
+        type: choice
+        options: [testpypi, pypi]
+        default: testpypi
+        required: true
+      version:
+        description: Exact source version, for example 1.0.0
+        type: string
+        required: true
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    uses: ./.github/workflows/ci.yml
+
+  build:
+    needs: verify
+    runs-on: ubuntu-latest
+    env:
+      REQUESTED_VERSION: ${{ inputs.version }}
+      TARGET_INDEX: ${{ inputs.repository }}
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v7.0.0
+        with:
+          python-version: '3.12'
+      - run: python -m pip install ".[release]"
+      - name: Check version and production status
+        run: |
+          python - <<'PY'
+          import os
+          from packaging.version import Version
+          from nexqus import __version__
+          assert os.environ['REQUESTED_VERSION'] == __version__, 'Requested version differs from source'
+          if os.environ['TARGET_INDEX'] == 'pypi':
+              assert not Version(__version__).is_prerelease, 'Use TestPyPI for this release candidate'
+          PY
+      - run: python scripts/check_release.py --public
+      - run: python -m build
+      - run: python -m twine check --strict dist/*
+      - run: python scripts/check_distribution.py
+      - uses: actions/upload-artifact@v7.0.2
+        with:
+          name: release-dist
+          path: dist/*
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: ${{ inputs.repository }}
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: release-dist
+          path: dist
+      - name: Publish to TestPyPI
+        if: inputs.repository == 'testpypi'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+      - name: Publish stable version to PyPI
+        if: inputs.repository == 'pypi'
+        uses: pypa/gh-action-pypi-publish@release/v1

nexqus_sdk-1.0.0/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+## 1.0.0 — 2026-10-16
+
+First stable public release under the MIT license.
+
+### Features
+
+- NumPy CPU and optional PyTorch CPU/NVIDIA CUDA simulation.
+- Noiseless statevectors, exact density matrices and batched noisy trajectories.
+- Circuit functions, symbolic parameters, sweeps, prepared execution and built-in algorithms.
+- Parameter-shift gradients, Adam/SGD, small learning models and VQE examples.
+- Mid-circuit measurement, reset, classical feed-forward and teleportation.
+- Seven English/Burmese notebooks, current feature guides and the public 1.x API policy.
+
+### Correctness and packaging
+
+- Reject non-finite or malformed validation results and invalid state/diagonal inputs.
+- Preserve single precision in NumPy damping and bound dynamic shot scheduling memory.
+- Reject complex learning data; isolate training callbacks and keep Adam failures atomic.
+- Keep validation reports and internal audit notes out of public guides and package archives.
+- Validate wheel/source contents, clean installations and notebook execution in CI.
+
+## Development history
+
+## 0.6.0
+
+Seven tested English/Burmese notebooks and a notebook execution runner. Runtime
+features unchanged from v0.5 except version identifier.
+
+## 0.5.0
+
+Mid-circuit measurement, reset, single-bit feed-forward, exact classical/density
+branching, sampled dynamic histories, joint counts and teleportation.
+
+## 0.4.0
+
+Parameters, gate-local analytic gradients, Adam/SGD, regression, binary
+classification and VQE demonstrations.
+
+## 0.3.0
+
+Device-local RNG and noise branch sampling, Pauli/damping specializations, local
+gate kernels, CPU threading controls and stricter numerical parity checks.
+
+## 0.2.0
+
+Parameters/sweeps, prepared execution, bounded gate cache and batched trajectories.
+
+## 0.1.0
+
+Own circuit engine, NumPy/optional Torch backends, statevector/density/trajectory
+simulation, single-qubit channels, reusable algorithms and examples.

nexqus_sdk-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Contributing to NexQus
+
+NexQus SDK is released under the MIT License. Report reproducible bugs and propose
+changes through https://github.com/Inn0m1n4te030/NexQus-SDK. By contributing code,
+you agree that your contribution is provided under the project's MIT License.
+
+Install in a fresh environment with `python -m pip install -e .`. Run
+`python scripts/check_release.py`. CPU-only installations may skip optional
+Torch/CUDA tests, and reports must retain those skips. If Torch CPU is available,
+run `python scripts/check_release.py --require-torch`. CUDA maintainers use
+`--require-gpu`, which requires zero skips.
+
+Changes to evolution, tensor ordering, stochastic sampling, precision, memory
+guards or gradients need a regression based on a known answer or independent
+reference. Include seeds, precision, method and batch size. An agreement between
+two implementations sharing a kernel is not sufficient evidence on its own.
+
+Update the API documentation and changelog when observable behavior changes.
+Write clear English docstrings and preserve Burmese explanations. New notebooks
+should be generated from scripts/build_notebooks.py and executed using a real
+Jupyter kernel before release. Keep optional-device skips explicit.
+
+The source distribution includes tests and teaching material. Before proposing a
+release, run `python -m build`, `python -m twine check --strict dist/*`, and
+`python scripts/check_distribution.py` from a clean dist directory.
+
+For bug reports include a minimal complete circuit, Python/NumPy/Torch versions,
+OS/device, expected result, actual result and simulator metadata. Remove private
+data and credentials. Use https://github.com/Inn0m1n4te030/NexQus-SDK/issues.
+
+The public API policy is in docs/API_STABILITY.md. Avoid depending on
+private helpers, direct Operation construction or mutable implementation internals.

nexqus_sdk-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NexQus
+
+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.

nexqus_sdk-1.0.0/MANIFEST.in

@@ -0,0 +1,15 @@
+include README.md LICENSE CHANGELOG.md CONTRIBUTING.md SECURITY.md
+recursive-include src *.py
+recursive-include tests *.py
+recursive-include examples *.py
+recursive-include scripts *.py *.sh
+recursive-include docs *.md
+recursive-include notebooks *.md *.ipynb
+recursive-include .github *.yml *.yaml
+prune .release-artifacts
+global-exclude *.py[cod]
+global-exclude .DS_Store
+prune build
+prune dist
+prune .venv
+prune .ipynb_checkpoints

nexqus_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: nexqus-sdk
+Version: 1.0.0
+Summary: Quantum circuit, noise, dynamic protocol and learning simulation on NumPy or PyTorch
+Author: NexQus
+License-Expression: MIT
+Project-URL: Homepage, https://nexqus.com
+Project-URL: Source, https://github.com/Inn0m1n4te030/NexQus-SDK
+Project-URL: Issues, https://github.com/Inn0m1n4te030/NexQus-SDK/issues
+Project-URL: Documentation, https://github.com/Inn0m1n4te030/NexQus-SDK#readme
+Keywords: quantum,simulator,statevector,noise,qml,cuda,burmese
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Education
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<3,>=1.24
+Provides-Extra: gpu
+Requires-Dist: torch<3,>=2.2; extra == "gpu"
+Provides-Extra: benchmark
+Requires-Dist: threadpoolctl>=3.1; extra == "benchmark"
+Provides-Extra: tutorial
+Requires-Dist: matplotlib>=3.7; extra == "tutorial"
+Requires-Dist: nbformat>=5.9; extra == "tutorial"
+Requires-Dist: nbclient>=0.10; extra == "tutorial"
+Requires-Dist: ipykernel>=6; extra == "tutorial"
+Requires-Dist: jupyterlab>=4; extra == "tutorial"
+Provides-Extra: release
+Requires-Dist: build>=1.2.2; extra == "release"
+Requires-Dist: twine>=6.1; extra == "release"
+Dynamic: license-file
+
+# NexQus SDK
+
+Quantum circuit simulation on NumPy CPU and optional PyTorch CPU/NVIDIA CUDA,
+with noise channels, reusable algorithms, analytic gradients and Burmese/English
+tutorials. NexQus implements its own circuit representation and evolution kernels;
+other quantum SDKs are not execution dependencies.
+
+**Version 1.0.0 · MIT license.**
+[Source and issue tracking](https://github.com/Inn0m1n4te030/NexQus-SDK).
+
+## Install
+
+In an activated Python 3.10+ virtual environment:
+
+```bash
+python -m pip install nexqus-sdk==1.0.0
+```
+
+The distribution name is **nexqus-sdk**; the Python import is **nexqus**.
+For editable development from a source checkout, use `python -m pip install -e .`.
+Examples and notebooks are available in the source repository and source archive.
+
+## Your first circuit
+
+```python
+from nexqus import Circuit, Simulator
+
+q = Circuit(2).h(0).cx(0, 1)
+result = Simulator().run(q, shots=1000, seed=42)
+print(result.probabilities)       # [0.5, 0, 0, 0.5], up to roundoff
+print(result.counts)              # samples of 00 and 11
+print(result.expectation('ZZ'))   # approximately 1
+```
+
+**Bit order:** q0 is the leftmost, most significant bit. `Circuit(2).x(0)` prepares
+`10`. Angles use radians. `shots=0` returns probabilities without sampling counts.
+
+## Functions, parameters and learning
+
+```python
+from nexqus import circuit, Parameter, QuantumFunction, Simulator
+
+@circuit(2)
+def block(q, theta):
+    # ပထမ qubit ကို rotate လုပ်ပြီး ဒုတိယ qubit နှင့် ချိတ်ဆက်ပါ။
+    q.ry(theta, 0).cx(0, 1)
+
+theta = Parameter('theta')
+template = block(theta)
+function = QuantumFunction(template, 'ZI')
+value, gradient = function.value_and_grad({'theta': 0.4})
+
+sim = Simulator()
+results = sim.run_sweep(template, [{'theta': 0.0}, {'theta': 1.0}], shots=0, seed=42)
+prepared = sim.compile(template.bind({'theta': 0.4}))
+result = prepared.run(shots=1000, seed=42)
+```
+
+Parameter-shift differentiation supports RX, RY, RZ, P and CP with shared
+parameters and arithmetic chain rules. `QuantumRegressor`,
+`QuantumBinaryClassifier`, Adam and SGD support small explicit learning loops.
+Gradients require static noiseless or exact-density circuits. They do not expose
+Torch autograd, sampled trajectory gradients or dynamic-circuit gradients.
+
+## Noisy simulation
+
+```python
+from nexqus import Noise, NoiseModel, Simulator, algorithms
+
+noise = NoiseModel(Noise.depolarizing(0.02), Noise.amplitude_damping(0.01))
+exact = Simulator().run(algorithms.bell(), noise=noise, shots=0)
+sampled = Simulator(method='trajectory').run(
+    algorithms.ghz(10), noise=noise, trajectories=1000,
+    batch_size=32, shots=1000, seed=7,
+)
+```
+
+| Method | Behavior | Main state storage |
+|---|---|---|
+| `auto` | Static statevector without noise; density with noise; exact density branches for dynamic circuits | Depends on selected mode |
+| `statevector` | Pure static circuits; rejects quantum noise and dynamic controls | O(2^n) |
+| `density_matrix` | Exact channels, or classical/density branching for dynamic circuits | O(4^n) per branch |
+| `trajectory` | A finite ensemble of sampled pure-state histories | O(B × 2^n), batch size B |
+
+Built-in channels: bit flip, phase flip, depolarizing, amplitude damping and phase
+damping; custom one-qubit CPTP Kraus channels are validated. Global noise is
+applied after each gate to each touched wire, in channel insertion order.
+Depolarizing means `(1-p)rho + p I/2`; phase damping multiplies coherences by
+`sqrt(1-gamma)`. Output `readout_error` affects reported quantum bit probabilities
+and counts, not the retained quantum state or intermediate classical control.
+
+Trajectory probabilities remain Monte Carlo estimates even at `shots=0`.
+Increasing shots does not increase the number of simulated histories.
+
+## Measurement, reset and feed-forward
+
+```python
+from nexqus import Circuit, Simulator
+
+q = Circuit(1).h(0).measure(0, 'm').x(0).c_if('m', 1)
+result = Simulator().run(q, shots=1000, seed=42)
+print(result.counts)              # {'0': 1000}
+print(result.classical_counts)    # intermediate measurement results
+```
+
+Single-bit conditions, overwritable classical keys, reset, joint
+classical/quantum counts and reduced density matrices are supported.
+`algorithms.teleportation()` supplies a complete feed-forward protocol.
+Exact branching is limited by `max_branches` and estimated memory.
+
+## CPU and CUDA
+
+```python
+from nexqus import Simulator
+
+cpu = Simulator()
+torch_cpu = Simulator(backend='torch')
+gpu = Simulator(backend='torch', device='cuda:0', precision='single')
+```
+
+Install a compatible PyTorch build using the official
+[PyTorch installation guide](https://pytorch.org/get-started/locally/).
+The `gpu` extra declares optional PyTorch; it cannot guarantee a CUDA-enabled
+build for your machine. Unsupported CUDA execution raises an error.
+There is no silent CPU fallback. Results use NumPy arrays on the host.
+Only CPU and NVIDIA CUDA are supported; CPU can be faster for small circuits.
+
+## Qubit and memory limits
+
+There is no universal fixed qubit capacity. Statevector storage doubles per
+added qubit; density storage quadruples. A double-precision 20-qubit vector uses
+16 MiB for the main state. One double-precision 12-qubit density uses 256 MiB.
+
+`max_memory_mb=1024` checks an estimated six-state workspace, multiplied by
+effective trajectory batch size; exact dynamic branches add further storage.
+This estimate is not an allocator cap. Circuit data, cached gates, retained host
+states and output-shot storage need additional memory. With the default estimate,
+a static complex128 vector can reach 23 qubits and a density 11 qubits; these are
+guard thresholds, not measured performance or hardware guarantees.
+
+Benchmark your intended circuit, method and device to determine practical limits.
+See the [performance guide](https://github.com/Inn0m1n4te030/NexQus-SDK/blob/main/docs/PERFORMANCE.md)
+for memory, batching and CPU/GPU comparison commands.
+
+## Learn and validate
+
+```bash
+python -m pip install '.[tutorial]'
+python -m ipykernel install --user --name nexqus --display-name "Python (NexQus)"
+jupyter lab notebooks
+python scripts/run_notebooks.py --engine jupyter --kernel nexqus
+python scripts/check_release.py
+```
+
+Seven bilingual notebooks cover circuits, algorithms, noise, devices, gradients,
+learning, measurement/reset and an end-to-end experiment. Start with
+`notebooks/00_start_here.ipynb`; the learning map is in `notebooks/README.md`.
+The source distribution includes tutorials, tests, examples and documentation;
+the small runtime wheel contains the importable SDK and package metadata.
+
+CUDA release validation, on a compatible machine:
+
+```bash
+python scripts/check_release.py --require-gpu
+python scripts/run_notebooks.py --engine jupyter --kernel nexqus --require-gpu
+```
+
+`--require-gpu` fails on missing CUDA or skipped tests. Generated reports are
+written to `.release-artifacts/` and excluded from distributed packages.
+
+## Documentation and scope
+
+- [API reference](https://github.com/Inn0m1n4te030/NexQus-SDK/blob/main/docs/API.md)
+  and [1.x compatibility policy](https://github.com/Inn0m1n4te030/NexQus-SDK/blob/main/docs/API_STABILITY.md).
+- [Burmese quick start](https://github.com/Inn0m1n4te030/NexQus-SDK/blob/main/docs/BURMESE_QUICKSTART.md).
+- [Performance](https://github.com/Inn0m1n4te030/NexQus-SDK/blob/main/docs/PERFORMANCE.md),
+  [learning](https://github.com/Inn0m1n4te030/NexQus-SDK/blob/main/docs/LEARNING.md)
+  and [dynamic circuits](https://github.com/Inn0m1n4te030/NexQus-SDK/blob/main/docs/DYNAMIC_CIRCUITS.md).
+- [Release notes](https://github.com/Inn0m1n4te030/NexQus-SDK/blob/main/docs/RELEASE_NOTES.md),
+  [contributing](https://github.com/Inn0m1n4te030/NexQus-SDK/blob/main/CONTRIBUTING.md)
+  and [security](https://github.com/Inn0m1n4te030/NexQus-SDK/blob/main/SECURITY.md).
+
+This SDK targets education and small research experiments. It does not include
+distributed execution, fused CUDA kernels, hardware services, pulse simulation,
+hardware-calibrated noise or a quantum advantage claim. Treat circuit and notebook
+code like other Python code: run code from sources you trust.
+
+Homepage: [nexqus.com](https://nexqus.com).
+Licensed under the [MIT License](https://github.com/Inn0m1n4te030/NexQus-SDK/blob/main/LICENSE).