stimflow 0.1.0__tar.gz

stimflow-0.1.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: stimflow
+Version: 0.1.0
+Summary: A library for creating quantum error correction circuits.
+Home-page: https://github.com/quantumlib/stim
+Author: Craig Gidney
+Author-email: craig.gidney@gmail.com
+License: Apache 2
+Requires-Python: >=3.6.0
+Description-Content-Type: text/markdown
+Requires-Dist: pygltflib
+Requires-Dist: stim
+Dynamic: author
+Dynamic: author-email
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+stimflow: annealed utilities for creating QEC circuits
+=================================================
+
+stimflow is a library for creating quantum error correction circuits.
+
+stimflow's design philosophy is to be a tool box, not a black box.
+For example, stimflow does *not* include a `make_surface_code` method.
+Instead it provides tools that can be used to more easily create a surface code circuit from scratch.
+The hope is that these tools then make it easier to create as-yet-unknown constructions in the future.
+
+stimflow decomposes the circuit creation problem into making and combining *chunks*.
+A *Chunk* is a circuit combined with stabilizer flow assertions that the circuit is supposed to satisfy.
+stimflow provides tools for making chunks (`stimflow.ChunkBuilder`), verifying chunks (`stimflow.Chunk.verify`), debugging chunks (`stimflow.Chunk.to_html_viewer`), and compiling sequences of chunks into a complete final circuit (`stimflow.ChunkCompiler`).
+
+stimflow also includes functionality for:
+
+- Transpiling (`stimflow.transpile_to_z_basis_interaction_circuit(...)`)
+- Adding Noise (`stimflow.NoiseModel.uniform_depolarizing(p).noisy_circuit(...)`)
+- Visualizing (`stimflow.make_3d_model`, `stimflow.stim_circuit_html_viewer`)
+
+# Documentation
+
+See stimflow's [getting started notebook](doc/getting_started.ipynb).
+
+See stimflow's [API reference](doc/api.md).
+
+# Backwards Compatibility Warning
+
+Stimflow does not currently guarantee backwards compatibility.
+There are parts of the library that do not yet feel like they have converged on the "right" way to do it,
+and I want to maintain the freedom to fix them later.
+
+# Example Usage: Surface Code Circuit
+
+stimflow is not yet provided as a pypi package, so you cannot install it with pip.
+The installation can be done manually by copying the contents of this directory somewhere into your python path.
+
+The following is python code that emits a surface code circuit.
+
+```python
+import stimflow as sf
+
+
+def make_surface_code(d: int) -> sf.StabilizerCode:
+    """Defines the stabilizers and observables of a surface code."""
+    tiles = []
+    ds = [0, 1, 1j, 1 + 1j]
+    for x in range(-1, d):
+        for y in range(-1, d):
+            m = x + 1j * y
+            qs = [m + d for d in ds]
+            qs = [q for q in qs
+                  if 0 <= q.real < d and 0 <= q.imag < d]
+            b = 'XZ'[(x + y) % 2]
+            if b == 'X' and x in [-1, d - 1]:
+                continue
+            if b == 'Z' and y in [-1, d - 1]:
+                continue
+            tiles.append(sf.Tile(
+                data_qubits=qs,
+                bases=b,
+                measure_qubit=m + 0.5 + 0.5j,
+            ))
+
+    patch = sf.Patch(tiles)
+    obs_x = sf.PauliMap.from_xs([q for q in patch.data_set if q.real == 0]).with_obs_name('X')
+    obs_z = sf.PauliMap.from_zs([q for q in patch.data_set if q.imag == 0]).with_obs_name('Z')
+    return sf.StabilizerCode(patch, logicals=[(obs_x, obs_z)])
+
+
+def make_idle_round(d: int) -> sf.Chunk:
+    """Creates a circuit that performs one round of surface code stabilizer measurement."""
+    code = make_surface_code(d=d)
+    builder = sf.ChunkBuilder(allowed_qubits=code.used_set)
+    mxs = [tile.measure_qubit for tile in code.tiles if tile.basis == 'X']
+    mzs = [tile.measure_qubit for tile in code.tiles if tile.basis == 'Z']
+
+    # Prepare measure qubits.
+    builder.append("RX", mxs)
+    builder.append("RZ", mzs)
+    builder.append("TICK")
+
+    # Perform entangling gates.
+    dxs = [-0.5 - 0.5j, 0.5 - 0.5j, -0.5 + 0.5j, 0.5 + 0.5j]
+    dzs = [dxs[0], dxs[2], dxs[1], dxs[3]]
+    for k in range(4):
+        builder.append(
+            'CX',
+            [(m, m + dxs[k]) for m in mxs] + [(m + dzs[k], m) for m in mzs],
+            unknown_qubit_append_mode='skip',
+        )
+        builder.append("TICK")
+
+    # Measure the measure qubits.
+    builder.append("MX", mxs)
+    builder.append("MZ", mzs)
+
+    # Assert the circuit should be preparing and measuring the stabilizers.
+    for tile in code.tiles:
+        builder.add_flow(start=tile, measurements=[tile.measure_qubit])
+        builder.add_flow(end=tile, measurements=[tile.measure_qubit])
+    # Assert the circuit should be preserving the logical operators.
+    for obs in code.flat_logicals:
+        builder.add_flow(start=obs, end=obs)
+
+    return builder.finish_chunk()
+
+
+def main():
+    # Create the code, verify its commutation relationships, and save a picture of it.
+    code = make_surface_code(d=7)
+    code.verify()
+    code.to_svg().write_to('tmp.svg')
+
+    # Create the circuit cycle, verify its operation, and create an interactive viewer.
+    chunk = make_idle_round(d=7)
+    chunk.to_html_viewer(background=code).write_to('tmp.html')
+    chunk.verify()
+
+    # Compile a physical memory experiment with alternating cycle orderings.
+    compiler = sf.ChunkCompiler()
+    compiler.append(code.transversal_init_chunk(basis='X'))
+    compiler.append(sf.ChunkLoop(
+        [chunk, chunk.time_reversed()],
+        repetitions=5,
+    ))
+    compiler.append(code.transversal_measure_chunk(basis='X'))
+    circuit = compiler.finish_circuit()
+
+    # Add noise to the circuit, check its distance, and make another viewer.
+    noisy_circuit = sf.NoiseModel.uniform_depolarizing(1e-3).noisy_circuit(circuit)
+    distance = len(noisy_circuit.shortest_graphlike_error())
+    assert distance == 7
+    sf.stim_circuit_html_viewer(noisy_circuit, background=code).write_to('tmp2.html')
+
+
+if __name__ == "__main__":
+    main()
+```

stimflow-0.1.0/README.md

@@ -0,0 +1,139 @@
+stimflow: annealed utilities for creating QEC circuits
+=================================================
+
+stimflow is a library for creating quantum error correction circuits.
+
+stimflow's design philosophy is to be a tool box, not a black box.
+For example, stimflow does *not* include a `make_surface_code` method.
+Instead it provides tools that can be used to more easily create a surface code circuit from scratch.
+The hope is that these tools then make it easier to create as-yet-unknown constructions in the future.
+
+stimflow decomposes the circuit creation problem into making and combining *chunks*.
+A *Chunk* is a circuit combined with stabilizer flow assertions that the circuit is supposed to satisfy.
+stimflow provides tools for making chunks (`stimflow.ChunkBuilder`), verifying chunks (`stimflow.Chunk.verify`), debugging chunks (`stimflow.Chunk.to_html_viewer`), and compiling sequences of chunks into a complete final circuit (`stimflow.ChunkCompiler`).
+
+stimflow also includes functionality for:
+
+- Transpiling (`stimflow.transpile_to_z_basis_interaction_circuit(...)`)
+- Adding Noise (`stimflow.NoiseModel.uniform_depolarizing(p).noisy_circuit(...)`)
+- Visualizing (`stimflow.make_3d_model`, `stimflow.stim_circuit_html_viewer`)
+
+# Documentation
+
+See stimflow's [getting started notebook](doc/getting_started.ipynb).
+
+See stimflow's [API reference](doc/api.md).
+
+# Backwards Compatibility Warning
+
+Stimflow does not currently guarantee backwards compatibility.
+There are parts of the library that do not yet feel like they have converged on the "right" way to do it,
+and I want to maintain the freedom to fix them later.
+
+# Example Usage: Surface Code Circuit
+
+stimflow is not yet provided as a pypi package, so you cannot install it with pip.
+The installation can be done manually by copying the contents of this directory somewhere into your python path.
+
+The following is python code that emits a surface code circuit.
+
+```python
+import stimflow as sf
+
+
+def make_surface_code(d: int) -> sf.StabilizerCode:
+    """Defines the stabilizers and observables of a surface code."""
+    tiles = []
+    ds = [0, 1, 1j, 1 + 1j]
+    for x in range(-1, d):
+        for y in range(-1, d):
+            m = x + 1j * y
+            qs = [m + d for d in ds]
+            qs = [q for q in qs
+                  if 0 <= q.real < d and 0 <= q.imag < d]
+            b = 'XZ'[(x + y) % 2]
+            if b == 'X' and x in [-1, d - 1]:
+                continue
+            if b == 'Z' and y in [-1, d - 1]:
+                continue
+            tiles.append(sf.Tile(
+                data_qubits=qs,
+                bases=b,
+                measure_qubit=m + 0.5 + 0.5j,
+            ))
+
+    patch = sf.Patch(tiles)
+    obs_x = sf.PauliMap.from_xs([q for q in patch.data_set if q.real == 0]).with_obs_name('X')
+    obs_z = sf.PauliMap.from_zs([q for q in patch.data_set if q.imag == 0]).with_obs_name('Z')
+    return sf.StabilizerCode(patch, logicals=[(obs_x, obs_z)])
+
+
+def make_idle_round(d: int) -> sf.Chunk:
+    """Creates a circuit that performs one round of surface code stabilizer measurement."""
+    code = make_surface_code(d=d)
+    builder = sf.ChunkBuilder(allowed_qubits=code.used_set)
+    mxs = [tile.measure_qubit for tile in code.tiles if tile.basis == 'X']
+    mzs = [tile.measure_qubit for tile in code.tiles if tile.basis == 'Z']
+
+    # Prepare measure qubits.
+    builder.append("RX", mxs)
+    builder.append("RZ", mzs)
+    builder.append("TICK")
+
+    # Perform entangling gates.
+    dxs = [-0.5 - 0.5j, 0.5 - 0.5j, -0.5 + 0.5j, 0.5 + 0.5j]
+    dzs = [dxs[0], dxs[2], dxs[1], dxs[3]]
+    for k in range(4):
+        builder.append(
+            'CX',
+            [(m, m + dxs[k]) for m in mxs] + [(m + dzs[k], m) for m in mzs],
+            unknown_qubit_append_mode='skip',
+        )
+        builder.append("TICK")
+
+    # Measure the measure qubits.
+    builder.append("MX", mxs)
+    builder.append("MZ", mzs)
+
+    # Assert the circuit should be preparing and measuring the stabilizers.
+    for tile in code.tiles:
+        builder.add_flow(start=tile, measurements=[tile.measure_qubit])
+        builder.add_flow(end=tile, measurements=[tile.measure_qubit])
+    # Assert the circuit should be preserving the logical operators.
+    for obs in code.flat_logicals:
+        builder.add_flow(start=obs, end=obs)
+
+    return builder.finish_chunk()
+
+
+def main():
+    # Create the code, verify its commutation relationships, and save a picture of it.
+    code = make_surface_code(d=7)
+    code.verify()
+    code.to_svg().write_to('tmp.svg')
+
+    # Create the circuit cycle, verify its operation, and create an interactive viewer.
+    chunk = make_idle_round(d=7)
+    chunk.to_html_viewer(background=code).write_to('tmp.html')
+    chunk.verify()
+
+    # Compile a physical memory experiment with alternating cycle orderings.
+    compiler = sf.ChunkCompiler()
+    compiler.append(code.transversal_init_chunk(basis='X'))
+    compiler.append(sf.ChunkLoop(
+        [chunk, chunk.time_reversed()],
+        repetitions=5,
+    ))
+    compiler.append(code.transversal_measure_chunk(basis='X'))
+    circuit = compiler.finish_circuit()
+
+    # Add noise to the circuit, check its distance, and make another viewer.
+    noisy_circuit = sf.NoiseModel.uniform_depolarizing(1e-3).noisy_circuit(circuit)
+    distance = len(noisy_circuit.shortest_graphlike_error())
+    assert distance == 7
+    sf.stim_circuit_html_viewer(noisy_circuit, background=code).write_to('tmp2.html')
+
+
+if __name__ == "__main__":
+    main()
+```

stimflow-0.1.0/requirements.txt

@@ -0,0 +1,2 @@
+pygltflib
+stim

stimflow-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

stimflow-0.1.0/setup.py

@@ -0,0 +1,40 @@
+# Copyright 2021 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from setuptools import setup
+
+with open('README.md', encoding='UTF-8') as f:
+    long_description = f.read()
+with open('requirements.txt', encoding='UTF-8') as f:
+    requirements = f.read().splitlines()
+
+__version__ = '0.1.0'
+
+setup(
+    name='stimflow',
+    version=__version__,
+    author='Craig Gidney',
+    author_email='craig.gidney@gmail.com',
+    url='https://github.com/quantumlib/stim',
+    license='Apache 2',
+    packages=['stimflow', 'stimflow._chunk', 'stimflow._core', 'stimflow._layers', 'stimflow._viz'],
+    package_dir={'': 'src'},
+    description='A library for creating quantum error correction circuits.',
+    long_description=long_description,
+    long_description_content_type='text/markdown',
+    python_requires='>=3.6.0',
+    data_files=['README.md', 'requirements.txt'],
+    install_requires=requirements,
+    tests_require=['pytest', 'python3-distutils'],
+)

stimflow-0.1.0/src/stimflow/__init__.py

@@ -0,0 +1,52 @@
+__version__ = "0.1.0"
+
+from stimflow._chunk import (
+    Chunk,
+    ChunkBuilder,
+    ChunkCompiler,
+    ChunkInterface,
+    ChunkLoop,
+    ChunkReflow,
+    find_d1_error,
+    find_d2_error,
+    FlowMetadata,
+    Patch,
+    StabilizerCode,
+    StimCircuitLoom,
+    transversal_code_transition_chunks,
+    verify_distance_is_at_least,
+)
+from stimflow._core import (
+    append_reindexed_content_to_circuit,
+    circuit_to_dem_target_measurement_records_map,
+    circuit_with_xz_flipped,
+    count_measurement_layers,
+    Flow,
+    gate_counts_for_circuit,
+    gates_used_by_circuit,
+    min_max_complex,
+    NoiseModel,
+    NoiseRule,
+    PauliMap,
+    sorted_complex,
+    stim_circuit_with_transformed_coords,
+    stim_circuit_with_transformed_moments,
+    str_html,
+    str_svg,
+    Tile,
+    xor_sorted,
+)
+from stimflow._layers import (
+    LayerCircuit,
+    transpile_to_z_basis_interaction_circuit,
+)
+from stimflow._viz import (
+    LineDataFor3DModel,
+    TriangleDataFor3DModel,
+    Viewable3dModelGLTF,
+    html_viewer_for_gltf_model,
+    make_3d_model,
+    stim_circuit_html_viewer,
+    svg,
+    TextDataFor3DModel,
+)

stimflow-0.1.0/src/stimflow/_chunk/__init__.py

@@ -0,0 +1,18 @@
+"""Utilities for building/combining pieces of quantum error correction circuits."""
+
+from stimflow._chunk._chunk import Chunk
+from stimflow._chunk._chunk_builder import ChunkBuilder
+from stimflow._chunk._chunk_compiler import ChunkCompiler
+from stimflow._chunk._chunk_interface import ChunkInterface
+from stimflow._chunk._chunk_loop import ChunkLoop
+from stimflow._chunk._chunk_reflow import ChunkReflow
+from stimflow._chunk._code_util import (
+    find_d1_error,
+    find_d2_error,
+    transversal_code_transition_chunks,
+    verify_distance_is_at_least,
+)
+from stimflow._chunk._flow_metadata import FlowMetadata
+from stimflow._chunk._patch import Patch
+from stimflow._chunk._stabilizer_code import StabilizerCode
+from stimflow._chunk._weave import StimCircuitLoom