# stimcirq
Tools for interop between the quantum python package `cirq` and the stabilizer simulator `stim`.
Includes:
- `stimcirq.StimSampler`
- `stimcirq.cirq_circuit_to_stim_circuit`
- `stimcirq.stim_circuit_to_cirq_circuit`
# Examples
Sampling with `stimcirq.Sampler`:
```python
import cirq
a, b = cirq.LineQubit.range(2)
c = cirq.Circuit(
cirq.H(a),
cirq.CNOT(a, b),
cirq.measure(a, key="a"),
cirq.measure(b, key="b"),
)
import stimcirq
sampler = stimcirq.StimSampler()
result = sampler.run(c, repetitions=30)
print(result)
# prints something like:
# a=000010100101000011001100110011
# b=000010100101000011001100110011
```
# API Reference
## `stimcirq.StimSampler`
```
A `cirq.Sampler` backed by `stim`.
Supports circuits that contain Clifford operations, measurement operations, reset operations, and noise operations
that can be decomposed into probabilistic Pauli operations. Unknown operations are supported as long as they provide
a decomposition into supported operations via `cirq.decompose` (i.e. via a `_decompose_` method).
Note that batch sampling is significantly faster (as in potentially thousands of times faster) than individual
sampling, because it amortizes the cost of parsing and analyzing the circuit.
```
## `stimcirq.stim_circuit_to_cirq_circuit(circuit: stim.Circuit) -> cirq.Circuit`
```
Converts a stim circuit into an equivalent cirq circuit.
Qubit indices are turned into cirq.LineQubit instances. Measurements are
keyed by their ordering (e.g. the first measurement is keyed "0", the second
is keyed "1", etc).
Not all circuits can be converted:
- ELSE_CORRELATED_ERROR instructions are not supported.
Not all circuits can be converted with perfect 1:1 fidelity:
- DETECTOR annotations are discarded.
- OBSERVABLE_INCLUDE annotations are discarded.
Args:
circuit: The stim circuit to convert into a cirq circuit.
Returns:
The converted circuit.
Examples:
>>> import stimcirq
>>> import stim
>>> print(stimcirq.stim_circuit_to_cirq_circuit(stim.Circuit('''
... H 0
... CNOT 0 1
... X_ERROR(0.25) 0
... TICK
... M !1 0
... ''')))
0: ───H───@───X[prob=0.25]───M('1')────
│
1: ───────X──────────────────!M('0')───
```
## `def cirq_circuit_to_stim_circuit(circuit: cirq.Circuit, *, qubit_to_index_dict: Optional[Dict[cirq.Qid, int]] = None) -> stim.Circuit`
```
Converts a cirq circuit into an equivalent stim circuit.
Not all circuits can be converted. In order for a circuit to be convertible, all of its operations must be
convertible.
An operation is convertible if:
- It is a stabilizer gate or probabilistic Pauli gate from cirq
- cirq.H
- cirq.S
- cirq.X
- cirq.X**0.5
- cirq.CNOT
- cirq.ResetChannel()
- cirq.X.with_probability(p)
- cirq.DepolarizingChannel(p, n_qubits=1 or 2)
- etc
- Or it has a _decompose_ method that yields convertible operations.
- Or it has a correctly implemented _stim_conversion_ method.
Args:
circuit: The circuit to convert.
qubit_to_index_dict: Optional. Which integer each qubit should get mapped to. If not specified, defaults to
indexing qubits in the circuit in sorted order.
Returns:
The converted circuit.
Examples:
>>> import cirq, stimcirq
>>> a = cirq.NamedQubit("zero")
>>> b = cirq.NamedQubit("two")
>>> stimcirq.cirq_circuit_to_stim_circuit(cirq.Circuit(
... cirq.Moment(cirq.H(a)),
... cirq.Moment(cirq.CNOT(a, b)),
... cirq.Moment(
... cirq.X(a).with_probability(0.25),
... cirq.Z(b).with_probability(0.25),
... ),
... cirq.Moment(),
... cirq.Moment(),
... cirq.Moment(cirq.DepolarizingChannel(0.125, n_qubits=2).on(b, a)),
... cirq.Moment(cirq.measure(a, b)),
... ), qubit_to_index_dict={a: 0, b: 2})
stim.Circuit('''
H 0
TICK
CX 0 2
TICK
X_ERROR(0.25) 0
Z_ERROR(0.25) 2
TICK
TICK
TICK
DEPOLARIZE2(0.125) 2 0
TICK
M 0 2
TICK
''')
Here is an example of a _stim_conversion_ method:
def _stim_conversion_(
self,
# The stim circuit being built. Add onto it.
edit_circuit: stim.Circuit,
# Metadata about measurement groupings needed by stimcirq.StimSampler.
# If your gate contains a measurement, it has to append how many qubits
# that measurement measures (and its key) into this list.
edit_measurement_key_lengths: List[Tuple[str, int]],
# The indices of qubits the gate is operating on.
targets: List[int],
# Forward compatibility with future arguments.
**kwargs):
edit_circuit.append_operation("H", targets)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/quantumlib/stim",
"name": "stimcirq",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6.0",
"maintainer_email": null,
"keywords": null,
"author": "Craig Gidney",
"author_email": "craig.gidney@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/5c/03/7427d34986b643bdccd13faaa0bd20499d30fe484dd01a8cb640d2a09428/stimcirq-1.14.0.tar.gz",
"platform": null,
"description": "# stimcirq\n\nTools for interop between the quantum python package `cirq` and the stabilizer simulator `stim`.\n\nIncludes:\n\n- `stimcirq.StimSampler`\n- `stimcirq.cirq_circuit_to_stim_circuit`\n- `stimcirq.stim_circuit_to_cirq_circuit`\n\n# Examples\n\nSampling with `stimcirq.Sampler`:\n\n```python\nimport cirq\na, b = cirq.LineQubit.range(2)\nc = cirq.Circuit(\n cirq.H(a),\n cirq.CNOT(a, b),\n cirq.measure(a, key=\"a\"),\n cirq.measure(b, key=\"b\"),\n)\n\nimport stimcirq\nsampler = stimcirq.StimSampler()\nresult = sampler.run(c, repetitions=30)\n\nprint(result)\n# prints something like:\n# a=000010100101000011001100110011\n# b=000010100101000011001100110011\n```\n\n# API Reference\n\n## `stimcirq.StimSampler`\n\n```\nA `cirq.Sampler` backed by `stim`.\n\nSupports circuits that contain Clifford operations, measurement operations, reset operations, and noise operations\nthat can be decomposed into probabilistic Pauli operations. Unknown operations are supported as long as they provide\na decomposition into supported operations via `cirq.decompose` (i.e. via a `_decompose_` method).\n\nNote that batch sampling is significantly faster (as in potentially thousands of times faster) than individual\nsampling, because it amortizes the cost of parsing and analyzing the circuit.\n```\n\n## `stimcirq.stim_circuit_to_cirq_circuit(circuit: stim.Circuit) -> cirq.Circuit`\n\n```\nConverts a stim circuit into an equivalent cirq circuit.\n\nQubit indices are turned into cirq.LineQubit instances. Measurements are\nkeyed by their ordering (e.g. the first measurement is keyed \"0\", the second\nis keyed \"1\", etc).\n\nNot all circuits can be converted:\n - ELSE_CORRELATED_ERROR instructions are not supported.\n\nNot all circuits can be converted with perfect 1:1 fidelity:\n - DETECTOR annotations are discarded.\n - OBSERVABLE_INCLUDE annotations are discarded.\n\nArgs:\n circuit: The stim circuit to convert into a cirq circuit.\n\nReturns:\n The converted circuit.\n\nExamples:\n\n >>> import stimcirq\n >>> import stim\n >>> print(stimcirq.stim_circuit_to_cirq_circuit(stim.Circuit('''\n ... H 0\n ... CNOT 0 1\n ... X_ERROR(0.25) 0\n ... TICK\n ... M !1 0\n ... ''')))\n 0: \u2500\u2500\u2500H\u2500\u2500\u2500@\u2500\u2500\u2500X[prob=0.25]\u2500\u2500\u2500M('1')\u2500\u2500\u2500\u2500\n \u2502\n 1: \u2500\u2500\u2500\u2500\u2500\u2500\u2500X\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500!M('0')\u2500\u2500\u2500\n```\n\n## `def cirq_circuit_to_stim_circuit(circuit: cirq.Circuit, *, qubit_to_index_dict: Optional[Dict[cirq.Qid, int]] = None) -> stim.Circuit`\n\n```\nConverts a cirq circuit into an equivalent stim circuit.\n\nNot all circuits can be converted. In order for a circuit to be convertible, all of its operations must be\nconvertible.\n\nAn operation is convertible if:\n - It is a stabilizer gate or probabilistic Pauli gate from cirq\n - cirq.H\n - cirq.S\n - cirq.X\n - cirq.X**0.5\n - cirq.CNOT\n - cirq.ResetChannel()\n - cirq.X.with_probability(p)\n - cirq.DepolarizingChannel(p, n_qubits=1 or 2)\n - etc\n - Or it has a _decompose_ method that yields convertible operations.\n - Or it has a correctly implemented _stim_conversion_ method.\n\nArgs:\n circuit: The circuit to convert.\n qubit_to_index_dict: Optional. Which integer each qubit should get mapped to. If not specified, defaults to\n indexing qubits in the circuit in sorted order.\n\nReturns:\n The converted circuit.\n\nExamples:\n >>> import cirq, stimcirq\n >>> a = cirq.NamedQubit(\"zero\")\n >>> b = cirq.NamedQubit(\"two\")\n >>> stimcirq.cirq_circuit_to_stim_circuit(cirq.Circuit(\n ... cirq.Moment(cirq.H(a)),\n ... cirq.Moment(cirq.CNOT(a, b)),\n ... cirq.Moment(\n ... cirq.X(a).with_probability(0.25),\n ... cirq.Z(b).with_probability(0.25),\n ... ),\n ... cirq.Moment(),\n ... cirq.Moment(),\n ... cirq.Moment(cirq.DepolarizingChannel(0.125, n_qubits=2).on(b, a)),\n ... cirq.Moment(cirq.measure(a, b)),\n ... ), qubit_to_index_dict={a: 0, b: 2})\n stim.Circuit('''\n H 0\n TICK\n CX 0 2\n TICK\n X_ERROR(0.25) 0\n Z_ERROR(0.25) 2\n TICK\n TICK\n TICK\n DEPOLARIZE2(0.125) 2 0\n TICK\n M 0 2\n TICK\n ''')\n\nHere is an example of a _stim_conversion_ method:\n\n def _stim_conversion_(\n self,\n\n # The stim circuit being built. Add onto it.\n edit_circuit: stim.Circuit,\n\n # Metadata about measurement groupings needed by stimcirq.StimSampler.\n # If your gate contains a measurement, it has to append how many qubits\n # that measurement measures (and its key) into this list.\n edit_measurement_key_lengths: List[Tuple[str, int]],\n\n # The indices of qubits the gate is operating on.\n targets: List[int],\n\n # Forward compatibility with future arguments.\n **kwargs):\n\n edit_circuit.append_operation(\"H\", targets)\n```\n",
"bugtrack_url": null,
"license": "Apache 2",
"summary": "Implements a cirq.Sampler backed by stim.",
"version": "1.14.0",
"project_urls": {
"Homepage": "https://github.com/quantumlib/stim"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5c037427d34986b643bdccd13faaa0bd20499d30fe484dd01a8cb640d2a09428",
"md5": "b2dec2b65bbae03bbf46c3346ff31b8a",
"sha256": "97f62be14f04b0c1c30a8916bc5bfca8bb63873a3ef4699082b87c842b2f010f"
},
"downloads": -1,
"filename": "stimcirq-1.14.0.tar.gz",
"has_sig": false,
"md5_digest": "b2dec2b65bbae03bbf46c3346ff31b8a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6.0",
"size": 29566,
"upload_time": "2024-09-24T08:40:23",
"upload_time_iso_8601": "2024-09-24T08:40:23.281063Z",
"url": "https://files.pythonhosted.org/packages/5c/03/7427d34986b643bdccd13faaa0bd20499d30fe484dd01a8cb640d2a09428/stimcirq-1.14.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-24 08:40:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "quantumlib",
"github_project": "stim",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "stimcirq"
}
JSON
