Skip to content

Getting Started

Install the package, run a circuit, read the results. If Matrix Product State, bond dimension, or truncation are new to you, read Concepts first: this page assumes them.

Installation

Wheels are published on tagged releases to the QPerfect GitLab package registry, which requires authentication:

pip install mimiq-tensorweaver \
  --index-url https://__token__:<your-access-token>@gitlab.qperfect.io/api/v4/projects/29/packages/pypi/simple

To avoid repeating the index URL, configure it in ~/.pip/pip.conf:

[global]
extra-index-url = https://__token__:<your-access-token>@gitlab.qperfect.io/api/v4/projects/29/packages/pypi/simple

then pip install mimiq-tensorweaver.

The Qiskit integration is an optional extra:

pip install 'mimiq-tensorweaver[qiskit]'

Supported platforms

Wheels target Python's stable ABI, so one wheel per platform serves Python 3.11 and later. The free-threaded interpreter is served by a wheel of its own, since it has no stable ABI to target; see Free-threaded Python.

Platform Wheel tag Requires
Linux x86_64 manylinux_2_35_x86_64 glibc 2.35 or newer (Ubuntu 22.04+, Debian 12+); pulls the mkl runtime (~224 MB)
Linux x86_64 manylinux_2_34_x86_64 glibc 2.34 (RHEL 9 and its rebuilds); pulls the mkl runtime (~224 MB)
macOS arm64 macosx_26_0_arm64 macOS 26 or later, Apple Silicon
Windows x86_64 win_amd64 Windows 10/11 x64; pulls the mkl runtime (~180 MB)
Linux x86_64, python3.14t cp314-cp314t-manylinux_2_35_x86_64 glibc 2.35 or newer; free-threaded 3.14 only
Linux x86_64, python3.14t cp314-cp314t-manylinux_2_34_x86_64 glibc 2.34 (RHEL 9 and its rebuilds); free-threaded 3.14 only

The mkl dependency is what makes usemkl=True work out of the box. MKL cannot be bundled into a wheel, so the wheels that have an MKL engine depend on it instead; see BLAS engine selection. The Linux default engine is the vendored OpenBLAS and needs nothing.

Linux has two wheels, for glibc 2.35 and for glibc 2.34, because RHEL 9 ships 2.34. pip selects the one matching your host automatically. Check your version with ldd --version. Hosts below 2.34, such as RHEL 8 and Ubuntu 20.04, are not covered.

There are no wheels for Intel macOS or Linux aarch64. If pip reports no matching distribution, check this table first.

Licensing

The published wheel is licensed, and one binary serves both models. The license file decides at runtime which applies.

Model How it validates
Node-locked Checks ~/.mimiq/license.key against the machine fingerprint, fully offline
Floating Leases a short-lived seat from $TENSORWEAVER_LICENSE_SERVER

Activate with the bundled mimiq-license CLI, also reachable as tensorweaver license:

tensorweaver license activate              # node-locked
tensorweaver license activate --floating   # floating

From source

Source builds need the Rust core cloned alongside the Python package, and a Rust toolchain, OpenBLAS + LAPACKE development packages, and protoc:

git clone git@gitlab.qperfect.io:development/tensorweaver/tensorweaver-rs.git
git clone git@gitlab.qperfect.io:development/tensorweaver/tensorweaver-python.git
cd tensorweaver-python
scripts/dev-build.sh        # builds both BLAS engines into an editable install

maturin develop on its own builds only the MKL engine. That still runs, since the default engine follows the build, but it needs the MKL runtime on the system and gives you nothing to compare against, which is why dev-build.sh exists. See BLAS engine selection for the runtime switch, and the repository README for build variants.

Verify the install

python -c "import tensorweaver; print(tensorweaver.library_info())"

The documentation ships inside the wheel, with nothing loaded from the network, so it works on a machine that has none. Read it with:

tensorweaver docs

That serves the site on a free loopback port and opens a browser on it, and keeps running until you interrupt it. Pass --port to pin the port, or --print-path to print where the files live instead of serving them.

Your first circuit

Build the circuit with mimiqcircuits, run it with execute().

from mimiqcircuits import Circuit, GateH, GateCX, Measure
from tensorweaver import execute

# A Bell pair: H on qubit 0, then CX from 0 to 1.
c = Circuit()
c.push(GateH(), 0)
c.push(GateCX(), 0, 1)
c.push(Measure(), 0, 0)
c.push(Measure(), 1, 1)

results = execute(c, nsamples=1000, bonddim=64, seed=42)

Two keywords carry most of the meaning:

  • nsamples is how many shots you want.
  • bonddim caps the bond dimension, which is the accuracy/cost dial. 64 is ample for a Bell pair; see Concepts for how to choose it, and Circuit Execution for every other keyword.

Reading the results

execute() returns a MIMIQ QCSResults.

print(results.histogram())
# {bs"00": 511, bs"11": 489}

print(results.fidelities[0])
# 1.0 -- nothing was discarded to truncation

print(results.timings)
# {'compile': ..., 'apply': ..., 'sample': ..., 'total': ...}
  • histogram() counts each measured classical state. Roughly half 00 and half 11, with no 01 or 10, is the Bell correlation.
  • fidelities reports how much weight truncation discarded, one entry per evolution. 1.0 means none. Treat it as a screen rather than a certificate: reading the reported fidelity explains what it does and does not cover.
  • timings breaks wall-clock seconds into compile, apply, sample, and total.

Individual shots are in results.cstates:

for bs in results.cstates[:5]:
    print(list(bs))     # [0, 0] or [1, 1]

Asking for amplitudes

Pass the bitstrings you want and read them back from results.amplitudes:

from mimiqcircuits import BitString

bs00, bs11 = BitString([0, 0]), BitString([1, 1])
results = execute(c, nsamples=1, bonddim=64, bitstrings=[bs00, bs11])

print(results.amplitudes[bs00])   # ~0.7071+0j
print(results.amplitudes[bs11])   # ~0.7071+0j

Qiskit users

TensorWeaver is little-endian by qubit index: bitstring position i is qubit i, so bs[0] is qubit 0. Qiskit puts the highest-indexed qubit on the left, so bitstrings from results.cstates, results.histogram(), and mps.sample_bitstring() appear reversed compared to Qiskit output. The same convention applies to any BitString you pass in.

Where to go next

The examples ship inside the installed package:

import tensorweaver as tw
print(tw.examples_dir())