{"id":28165,"library":"samplomatic","title":"Samplomatic","description":"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.","status":"active","version":"0.18.0","language":"python","source_language":"en","source_url":"https://github.com/Qiskit/samplomatic","tags":["circuit-sampling","noise","qiskit","quantum"],"install":[{"cmd":"pip install samplomatic","lang":"bash","label":"default"}],"dependencies":[{"reason":"Core dependency for quantum circuit operations","package":"qiskit","optional":false}],"imports":[{"note":null,"wrong":null,"symbol":"Samplex","correct":"from samplomatic import Samplex"},{"note":null,"wrong":null,"symbol":"build","correct":"from samplomatic import build"},{"note":null,"wrong":null,"symbol":"generate_boxing_pass_manager","correct":"from samplomatic.transpiler import generate_boxing_pass_manager"},{"note":"GroupLiteral replaced by GroupMode in v0.17.0","wrong":"from samplomatic import GroupLiteral, from samplomatic.annotations import GroupLiteral","symbol":"GroupMode","correct":"from samplomatic.annotations import GroupMode"},{"note":null,"wrong":null,"symbol":"Tag","correct":"from samplomatic.annotations import Tag"}],"quickstart":{"code":"from samplomatic import Samplex, build\nfrom qiskit.circuit import QuantumCircuit, Parameter\n\nqc = QuantumCircuit(2)\ntheta = Parameter('theta')\nqc.rz(theta, 0)\nqc.cx(0, 1)\nqc.measure_all()\n\nsamplex = Samplex(qc, {theta: 0.5})\n\nwith build(samplex) as bld:\n    bld.add_gate(\"easy\", qc)\n    bld.add_gate(\"hard\", qc)\n\nresults = samplex.sample(shots=1000)\nprint(results)","lang":"python","description":"Basic example: define a quantum circuit, create a Samplex, build a template, and sample."},"warnings":[{"fix":"Update code that expects `parameter_values` to always be present in the output.","message":"In v0.13.0, `build` always returns `parameter_values` with shape (num_randomizations, 0) if no parameter values are generated. Previously it was omitted.","severity":"breaking","affected_versions":">=0.13.0"},{"fix":"Upgrade to Python >=3.10.","message":"Python 3.9 support removed in v0.14.0.","severity":"breaking","affected_versions":">=0.14.0"},{"fix":"Replace `GroupLiteral` with `GroupMode` and update imports accordingly.","message":"`TWIRLING_GROUPS` and `GroupLiteral` removed in v0.17.0. Use `GroupMode` instead.","severity":"deprecated","affected_versions":">=0.17.0"},{"fix":"Ensure serialized data is deserialized with the same SSV or compatible version.","message":"Serialization version (SSV) is decoupled from package version (since v0.12.0). Backward compatibility is not guaranteed across SSV changes.","severity":"gotcha","affected_versions":">=0.12.0"}],"env_vars":null,"last_verified":"2026-05-09T00:00:00.000Z","next_check":"2026-08-07T00:00:00.000Z","problems":[{"fix":"Run `pip install samplomatic` in your target environment.","cause":"Samplomatic is not installed or installed in a different environment.","error":"ModuleNotFoundError: No module named 'samplomatic'"},{"fix":"Use `from samplomatic.annotations import GroupMode` and replace `GroupLiteral.XX` with `GroupMode.XX`.","cause":"`GroupLiteral` was removed in v0.17.0 and replaced with `GroupMode`.","error":"AttributeError: module 'samplomatic.annotations' has no attribute 'GroupLiteral'"},{"fix":"Use `samplex.inputs` or `samplex.outputs` attributes instead of subscripting.","cause":"Older code may have tried to access samplex as a dictionary (e.g., samplex['key']). The API changed in earlier versions.","error":"TypeError: 'Samplex' object is not subscriptable"},{"fix":"Upgrade to v0.16.1 or later, or ensure the BoxOp body qubits match the circuit.","cause":"BoxOp appended directly to a QuantumCircuit with mismatched qubit order (common before v0.16.1 fix).","error":"ValueError: Invalid qubit ordering in BoxOp body"},{"fix":"Provide all parameter bindings as a dictionary via the `parameter_values` argument or bind before passing.","cause":"When creating a Samplex with a QuantumCircuit that has unbound parameters.","error":"QiskitError: 'circuit' is not a valid parameter"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}