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.

Install

In an activated Python 3.10+ virtual environment:

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

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

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

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,
)

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

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

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. 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 for memory, batching and CPU/GPU comparison commands.

Learn and validate

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:

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 and 1.x compatibility policy.
• Burmese quick start.
• Performance, learning and dynamic circuits.
• Release notes, contributing and security.

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. Licensed under the MIT License.