Samplomatic

0.18.0 verified Sat May 09 auth: no python

A Qiskit-based library for circuit sampling and noise characterization. It provides tools for building samplex circuits, transpilation passes (boxing, twirling, noise injection), and serialization. Current version: 0.18.0, requires Python >=3.10. Release cadence is approximately biweekly.

pip install samplomatic

Common errors

error ModuleNotFoundError: No module named 'samplomatic' ↓

cause Samplomatic is not installed or installed in a different environment.

fix

Run pip install samplomatic in your target environment.

error AttributeError: module 'samplomatic.annotations' has no attribute 'GroupLiteral' ↓

cause `GroupLiteral` was removed in v0.17.0 and replaced with `GroupMode`.

fix

Use from samplomatic.annotations import GroupMode and replace GroupLiteral.XX with GroupMode.XX.

error TypeError: 'Samplex' object is not subscriptable ↓

cause Older code may have tried to access samplex as a dictionary (e.g., samplex['key']). The API changed in earlier versions.

fix

Use samplex.inputs or samplex.outputs attributes instead of subscripting.

error ValueError: Invalid qubit ordering in BoxOp body ↓

cause BoxOp appended directly to a QuantumCircuit with mismatched qubit order (common before v0.16.1 fix).

fix

Upgrade to v0.16.1 or later, or ensure the BoxOp body qubits match the circuit.

error QiskitError: 'circuit' is not a valid parameter ↓

cause When creating a Samplex with a QuantumCircuit that has unbound parameters.

fix

Provide all parameter bindings as a dictionary via the parameter_values argument or bind before passing.

Warnings

breaking In v0.13.0, `build` always returns `parameter_values` with shape (num_randomizations, 0) if no parameter values are generated. Previously it was omitted. ↓

fix Update code that expects `parameter_values` to always be present in the output.

breaking Python 3.9 support removed in v0.14.0. ↓

fix Upgrade to Python >=3.10.

deprecated `TWIRLING_GROUPS` and `GroupLiteral` removed in v0.17.0. Use `GroupMode` instead. ↓

fix Replace `GroupLiteral` with `GroupMode` and update imports accordingly.

gotcha Serialization version (SSV) is decoupled from package version (since v0.12.0). Backward compatibility is not guaranteed across SSV changes. ↓

fix Ensure serialized data is deserialized with the same SSV or compatible version.

Imports

Samplex
```
from samplomatic import Samplex
```
build
```
from samplomatic import build
```

generate_boxing_pass_manager

from samplomatic.transpiler import generate_boxing_pass_manager

GroupMode

wrong

from samplomatic import GroupLiteral, from samplomatic.annotations import GroupLiteral

correct

from samplomatic.annotations import GroupMode

GroupLiteral replaced by GroupMode in v0.17.0

Tag
```
from samplomatic.annotations import Tag
```

Quickstart

Basic example: define a quantum circuit, create a Samplex, build a template, and sample.

from samplomatic import Samplex, build
from qiskit.circuit import QuantumCircuit, Parameter

qc = QuantumCircuit(2)
theta = Parameter('theta')
qc.rz(theta, 0)
qc.cx(0, 1)
qc.measure_all()

samplex = Samplex(qc, {theta: 0.5})

with build(samplex) as bld:
    bld.add_gate("easy", qc)
    bld.add_gate("hard", qc)

results = samplex.sample(shots=1000)
print(results)