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.

Platform	Wheel tag	Requires
Linux x86_64	`manylinux_2_35_x86_64`	glibc 2.35 or newer (Ubuntu 22.04+, Debian 12+)
Linux x86_64	`manylinux_2_34_x86_64`	glibc 2.34 (RHEL 9 and its rebuilds)
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 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, and the default usemkl=False then finds no OpenBLAS engine, 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. Open it offline with:

tensorweaver docs

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¶

Concepts for bond dimension, fidelity, and execution modes.
Circuit Execution for every execute() keyword.
Examples for runnable scripts bundled with the package.
API Reference for the low-level MPS and MPO classes.

The examples ship inside the installed package:

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