Stim

Flagship changes:

- Added support for representing and verifying stabilizer flows (`stim.Flow`, `stim.Circuit.has_flow`, `stim.Circuit.detecting_regions`)

Notable changes:

- New top-level methods/types:
- Added `stim.Flow` class for representing stabilizer flows
- Added `stim.target_pauli`
- Added `stim.target_combined_paulis`
- Added `stim.PauliStringIterator`
- New `stim.Circuit` methods:
- Added `stim.Circuit.decomposed`
- Added `stim.Circuit.detecting_regions`
- Added `stim.Circuit.to_qasm`
- Added `stim.Circuit.has_flow`
- Added `stim.Circuit.has_all_flows`
- Added `stim.Circuit.shortest_error_sat_problem`
- Added `stim.Circuit.likeliest_error_sat_problem`
- New `stim.GateData` methods:
- Added `stim.GateData.{__eq__,__ne__,__repr__,__init__,__str__}`
- Added `stim.GateData.flows`
- Added `stim.GateData.generalized_inverse`
- Added `stim.GateData.inverse`
- New `stim.PauliString` methods:
- `stim.PauliString.__init__` now allows sparse syntax (like `stim.PauliString("-X50*Z99")`)
- Added `stim.PauliString.iter_all`
- Added `stim.PauliString.pauli_indices`
- Added `stim.PauliString.weight`
- Sped up `stim.PauliString.{after,before}` by over 10x
- New `stim.Tableau` methods:
- Added `stim.Tableau.to_circuit("graph_state")`
- Added `stim.Tableau.to_circuit("mpp_state")`
- Added `stim.Tableau.to_circuit("mpp_state_unsigned")`
- Added `stim.Tableau.to_stabilizers`
- Sped up `stim.Tableau.from_stabilizers` by over 200x
- New `stim.FlipSimulator` methods:
- Added `stim.FlipSimulator.broadcast_pauli_errors`
- New gates:
- Added `CZSWAP` gate (with alias `SWAPCZ`)
- Added `SPP` gate (generalized S gate that applies to Pauli products)
- Added `SPP_DAG` (inverse of `SPP`)
- Added `sinter.FusionBlossomCompiledDecoder`, speeding up decoding with fusion blossom
- Added `sinter plot --ymax` command line argument
- stimcirq now converts `PAULI_CHANNEL_2` into cirq's native asymmetric channel
- Added `Bloch Rotation (Euler angles)` to gate documentation
- Added prebuilt wheels for python 3.12
- Tweaked `sinter plot`'s marker/color ordering to increase how many curves are needed to get two curves that look similar

Notable bug fixes:

- Fixed `sinter plot --xaxis` only applying to one subplot, instead of all subplots
- Fixed build-from-source not working on IBM PowerPC
- Fixed `HERALDED_PAULI_CHANNEL_1` targeting the wrong qubits (this fix was also backported to 1.12.1)
- Fixed `stim.Circuit.explain_dem_errors` not supporting all gates
- Fixed crumble not allowing `e` and `q` to repeatedly move between layers when held down
- Fixed crumble not falling back to an emulated clipboard when clipboard permissions weren't granted

Special thanks to this release's contributors:

fdmalone
markturner289
mmcewen-g
nickdgardner
noajshu
tomirendo

Notable changes:

- Add python 3.12 to the versions with prebuilt wheels

Bug fixes:

- Fixed `HERALDED_PAULI_CHANNEL_1` targeting fixed indices instead of the given qubits
- For example, `HERALDED_PAULI_CHANNEL_1(0.1) 2 5 3` was behaving like `HERALDED_PAULI_CHANNEL_1(0.1) 0 1 2`

Flagship changes:

- Added support for heralded erasures
- Added `stim.FlipSimulator` for tracking batches of Pauli flips through circuits
- Doubled sinter's sample throughput on high core count machines

Notable changes to stim:

- Added gates: `HERALDED_ERASE`, `HERALDED_PAULI_CHANNEL_1`, `MXX`, `MYY`, `MZZ`, `MPAD`
- Added top-level method `stim.gate_data`
- Added class `stim.GateData`
- Properties: `aliases`, `is_noisy_gate`, `is_reset`, `is_single_qubit_gate`, `is_two_qubit_gate`, `is_unitary`, `name`, `num_parens_arguments_range`, `produces_measurements`, `tableau`, `takes_measurement_record_targets`, `takes_pauli_targets`, `unitary_matrix`
- Added class `stim.FlipSimulator`
- Methods: `__init__`, `do`, `get_detector_flips`, `get_measurement_flips`, `get_observable_flips`, `peek_pauli_flips`, `set_pauli_flip`
- Properties: `batch_size`, `num_detectors`, `num_measurements`, `num_observables`, `num_qubits`
- Added `stim.Circuit.count_determined_measurements`
- Added `stim.Circuit.num_ticks`
- Added `stim.Circuit.reference_sample`
- Added `stim.CircuitRepeatBlock.name` (for duck typing vs `stim.CircuitInstruction`)
- Added `stim.DemRepeatBlock.type` (for duck typing vs `stim.DemInstruction`)
- Added `stim.GateTarget.pauli_type`
- Added `stim.GateTarget.qubit_value`
- Added `stim.TableauSimulator.postselect_observable`
- Added optional `reference_sample` argument to `stim.Circuit.compile_sampler`
- Made `stim.PauliString.{after,before}` much less picky
- Improved performance of `stim.CompiledDetectorSampler` by ~30% under repetitive usage by caching more internal objects
- Circuit-to-dem conversion now adds the probabilities of indistinguishable cases within a disjoint error channel, instead of Bernoulli-adding them
- Added the `stim convert` command for converting between shot file formats

Notable changes to sinter:

- sinter now has an [API reference](https://github.com/quantumlib/Stim/blob/main/doc/sinter_api.md)
- sinter now has a [command line reference](https://github.com/quantumlib/Stim/blob/main/doc/sinter_command_line.md)
- Added `sinter.Decoder.compile_decoder_for_dem` method for custom decoders to implement
- Improves performance ~2x on high core count machines by avoiding disk usage
- Added a shorthand to `sinter plot`: use `m.key` instead of `metadata.get("key", None)` in `*_func` arguments
- Added square root scales to `sinter plot` (example: `--xaxis "[sqrt]qubit count"`)
- Added an optional `custom_counts` column to sinter's CSV format
- Added `auto` option to use all processes (`sinter collect --processes=auto`)
- Added `sinter plot --line_fits`
- Added `sinter plot --xmax`
- Added `sinter plot --xmin`
- Added `sinter plot --failure_values_func`
- Added `sinter plot --subtitle` with `{common}` macro
- Added `sinter collect --count_detection_events`
- Added `sinter collect --count_observable_error_combos`
- Added `sinter collect --allowed_cpu_affinity_ids`
- Added `sinter combine --strip_custom_counts`
- Added `sinter plot --custom_error_count_keys`
- Added `sinter.log_binomial`
- Added `sinter.log_factorial`
- Added `sinter.read_stats_from_csv_files`
- Added `sinter.{AnonTaskStats,TaskStats}.custom_counts`
- Added `sinter.Task.circuit_path` field for specifying circuits by filepath
- Added arguments `count_observable_error_combos=False` and `count_detection_events=False` to `sinter.{iter_collect,collect}`

Notable changes to crumble:

- Added support for MPP operations
- Added example circuits

Notable bug fixes

- Fixed `stimcirq.__version__` and `sinter.__version__` not existing
- Fixed `stimcirq.cirq_circuit_to_stim_circuit` choking on tagged operations
- Fixed `stimcirq.cirq_circuit_to_stim_circuit` not putting repeat blocks in their own moment
- Fixed triggering numpy `bool8` deprecation warnings
- Fixed documentation not mentioning how to do pauli feedback
- Fixed a failure in `stim m2d` related to appending observables crossing a simd boundary when `--obs_out` was used
- Fixed some corner cases where `sinter.better_sorted_str_terms` produced incomparable values
- Fixed `cmake install` doing nothing
- Fixed some `sinter plot` crashes on degenerate data
- Fixed several sinter classes not having evaluatable reprs
- Fixed `stim.Tableau.inverse` returning invalid results when the tableau's representation included size padding
- Fixed HTML diagrams not being isolated from each other in notebooks (wrapped them all in iframes)
- Fixed `stimzx` example project discarding sign information of external stabilizers
- Fixed `stim.Circuit.shortest_graphlike_error` and friends not working if there were more than 64 observables

Special thanks to this release's contributors:

AlexBourassa
fdmalone
markturner289
oon3m0oo
viathor
justinledford

Major changes:

- Added prototype `interactivate` diagrams for circuits. See [the crumble README](https://github.com/quantumlib/Stim/blob/main/glue/crumble/README.md).

Breaking changes:

- `stim.DetectorErrorModel.shortest_graphlike_error` now defaults `ignore_ungraphlike_errors` to True instead of False. Also, it now actually ignores all ungraphlike errors when set to True.

General additions and improvements:

- Added a new gate: `CXSWAP` (and `SWAPCX`). This gate is KAK-equivalent to the ISWAP, but avoids mixing X and Z terms, which is useful when creating/debugging circuits intended to use ISWAP-like interactions.
- Added a new diagram type `"interactive"`. Interactive diagrams are a HTML pages containing "crumble".
- Added `stim.Circuit.inverse`
- Added `stim.Circuit.with_inlined_feedback`
- Added `stim.TableauSimulator.measure_pauli_string`
- Gave the project a logo
- Simplified the names of diagram types (the old names still work but are no longer listed in documentation)
- Added `separate_observables=False` argument to `stim.read_shot_data_file`
- Added `unsigned=False` argument to `stim.PauliString.from_unitary_matrix`
- Added `stim.Tableau.x_sign`, `stim.Tableau.y_sign`, `stim.Tableau.z_sign` helper methods
- Added `stim.TableauSimulator.depolarize1`, `stim.TableauSimulator.depolarize2`, `stim.TableauSimulator.x_error`, `stim.TableauSimulator.y_error`, `stim.TableauSimulator.z_error`
- Added a `--ran_without_feedback` command line option to `stim m2d`
- Added `stim.PauliString.before`, `stim.PauliString.after`

Diagram improvements:

- Detector slice diagrams now use colors that are more color-blind friendly
- Added new diagram type `detslice-with-ops-svg` which overlays operations over the detector slice diagram
- The `type` argument for `.diagram` methods is no longer keyword-only
- The `tick` argument for `.diagram` methods can now be set to a `range(start, end)`, producing a diagram containing each tick in the range as a sub-diagram
- Detector slice diagrams now prefer shapes that have mirror symmetry, when choosing how to draw a stabilizer
- Detector slice diagrams now switch to using bezier curves when stroking between colinear points, to disambiguate which points are vertices and which points are skipped
- Increased the initial size used for the 3d model viewer and the svg viewer
- Improved the initial camera position used by the 3d model viewer to better frame the model
- Increased the font sizes used for gates in SVG diagrams, so they better fill their boxes
- Detector slice diagrams can now be filtered by `stim.DemTarget` (to slice observables in addition to detectors, include observable targets in the filter)
- SVG diagrams now group elements, making them easier to touch up afterwards in image editors

Sinter improvements:

- Added `--postselected_detectors_predicate` to `sinter collect`, generalizing `--postselect_detectors_with_non_zero_4th_coord`
- It's now possible to specify custom decoders
- Added `sinter.Decoder` class
- Added a `custom_decoders` arg to `sinter.collect`, `sinter.iter_ollect`, `sinter.predict_on_disk`, `sinter.predict_observables_bit_packed`
- Added a `--customer_decoders_module_function` command line argument to `sinter collect`
- `sinter predict` can now be given `--metadata_func auto` instead of `--metadata_func "sinter.comma_separated_key_values(path)"`
- Added command line arguments to `sinter plot`:
- `--y_func`
- `--y_axis`
- The expression given to `--plot_args_func` now has access to several more values: `stat`, `stats`, `decoder`, metadata`, and `strong_id`.
- The `plot_args_func` argument of `sinter.plot` methods can now take a third argument, `stats`, the list of stats in the curve
- Discard rate diagrams now include more Y axis indicators
- `sinter combine` now sorts its output
- Added `--order preserve|metadata|error` option to `sinter combine`

Bug fixes:

- Due to a [mysterious crash in collab](https://github.com/quantumlib/Stim/issues/432), the AVX build has been temporarily disabled.
- Fixed generating degenerate diagrams when circuits had no coordinate data
- Fixed `stimcirq.StimSampler` not working on cirq circuits containing repeated keys
- Fixed `stimcirq.SweepPauli._resolve_parameters_` failing to resolve strings, and not specifying `_parameter_names_`
- Fixed a typo in `stim.PauliString`'s documentation. The allowable signs are [1, -1, 1j, -1j].
- Fixed a quadratic overhead caused by iteratively growing the tableau simulator's state
- Fixed sinter crashing on shutdown on windows, due to not waiting for workers to die before deleting their files
- Fixed sinter ignoring error codes returned from pymatching.
- Fixed `stim.Tableau.from_stabilizers` not verifying that the given stabilizers actually commute
- Related: pymatching fixed a bug where it was linking an older version of stim that opened binary files in text mode, causing sinter to fail when using pymatching on windows.

Flagship changes:

- Use open source decoders that are 100x to 1000x faster than before! ([pymatching v2](https://github.com/oscarhiggott/PyMatching) and [fusion_blossom](https://github.com/yuewuo/fusion-blossom))
- Produce 2d and 3d diagrams of circuits and detector error models, with built-in viewers for Jupyter notebooks!
- Sample directly from detector error models. Record the errors that occurred, edit them, and play them back!

Notable changes:

- Added `stim.Circuit.diagram`
- Added diagram type `"detector-slice-text"`
- Added diagram type `"detector-slice-svg"`
- Added diagram type `"match-graph-svg"`
- Added diagram type `"match-graph-3d"`
- Added diagram type `"match-graph-3d-html"`
- Added diagram type `"timeline-text"`
- Added diagram type `"timeline-svg"`
- Added diagram type `"timeline-3d"`
- Added diagram type `"timeline-3d-html"`
- Added `stim.DetectorErrorModel.diagram`
- Added diagram type `"match-graph-svg"`
- Added diagram type `"match-graph-3d"`
- Added diagram type `"match-graph-3d-html"`
- Added methods to `stim.PauliString`:
- `stim.PauliString.from_numpy`
- `stim.PauliString.from_unitary_matrix`
- `stim.PauliString.to_numpy`
- `stim.PauliString.to_tableau`
- `stim.PauliString.to_unitary_matrix`
- Added methods to `stim.TableauSimulator`:
- `stim.TableauSimulator.__init__` now has an optional `seed` argument
- `stim.TableauSimulator.set_state_from_stabilizers`
- `stim.TableauSimulator.set_state_from_state_vector`
- `stim.TableauSimulator.do` now accepts `stim.CircuitInstruction` and `stim.CircuitRepeatBlock`
- Added methods to `stim.Tableau`:
- `stim.Tableau.iter_all`
- `stim.Tableau.from_circuit`
- `stim.Tableau.from_numpy`
- `stim.Tableau.from_stabilizers`
- `stim.Tableau.from_state_vector`
- `stim.Tableau.from_unitary_matrix`
- `stim.Tableau.to_circuit`
- `stim.Tableau.to_numpy`
- `stim.Tableau.to_pauli_string`
- `stim.Tableau.to_state_vector`
- Added methods to `stim.DetectorErrorModel`:
- `stim.DetectorErrorModel.flattened`
- `stim.DetectorErrorModel.rounded`
- `stim.DetectorErrorModel.compile_sampler`
- Added `stim.CompiledDemSampler` class with methods:
- `stim.CompiledDemSampler.sample`
- `stim.CompiledDemSampler.sample_write`
- Improvements to `sinter`
- Added support for [pymatching v2](https://github.com/oscarhiggott/PyMatching)
- Added support for [fusion_blossom decoder](https://github.com/yuewuo/fusion-blossom)
- Added flag `--title` to `sinter plot`
- Added flag `--miny` to `sinter plot`
- Added flag `--plot_args_func` to `sinter plot`
- Added flag `--failure_units_per_shot_func` to `sinter plot`
- Added flag `--failure_unit_name` argument to `sinter plot`
- Added grid lines to the plots made by `sinter plot`
- Added `filter_func`, `failure_units_per_shot_func`, and `failure_unit_name` arguments to `sinter.plot_error_rate` and `sinter.plot_discard_rate`
- Added `sinter.predict_observables` method
- Added ability to discard shots based on observables being mispredicted
- Added `--postselected_observables_predicate` flag to `sinter collect`
- Added `sinter.Task.postselected_observables_mask` field
- Added `postselected_observable_mask` argument to `sinter.sample_decode`
- Added `stim diagram` command for producing diagrams, with flags `--in`, `--type`, `--out`, `--tick`, `--remove_noise`, `--filter_coords`.
- Added `stim sample_dem` command for directly sampling from detector error model files, with flags `--err_out`, `--err_out_format`, `--in`, `--obs_out`, `--obs_out_format`, `--out`, `--out_format`, `--replay_err_in`, `--replay_err_in_format`, `--seed`, `--shots`, `--err_out`, `--err_out_format`, `--replay_err_in`, `--replay_err_in_format`.
- Added `separate_observables=False` argument to `stim.CompiledDetectorSampler.sample`
- Added `bit_packed=False` argument to `stim.CompiledDetectorSampler.sample`
- Added `bit_packed=False` argument to `stim.CompiledMeasurementSampler.sample`
- Deprecated `stim.CompiledDetectorSampler.sample_bit_packed`
- Deprecated `stim.CompiledMeasurementSampler.sample_bit_packed`

Notable bug fixes:

- Fixed `stim.Circuit.flattened` not fusing all operations
- Fixed `stim.Circuit.without_noise` not fusing all operations
- Fixed `PAULI_CHANNEL_2` not being marked as targeting pairs of qubits
- Fixed sinter's internal python files not being marked as private, so they don't appear as autocomplete suggestions
- Fixed `stim.Circuit.detector_error_model` failing when errors affected more than 15 detectors (unless decompose_errors=True)
- Fixed `stim.Circuit.without_noise` not making independent copies of the operations (!)
- Fixed sinter only sampling using the first decoder given to it, instead of all decoders, when given multiple decoders
- Fixed not redirecting stdout and stderr to python's when calling `stim.main`
- Fixed unnecessary overhead in the conversion to/from numpy arrays (10x faster for small arrays)
- Fixed a segfault and bad parsing logic in `stim.read_shot_data_file` (!). Fuzz tested the read/write methods against the python reference methods to avoid this happening again.

Notable dev changes:

- Fixed files being opened in text mode instead of binary mode, resulting in bad parsing/serialization on Windows due to \n bytes being turned into \r\n and vice versa.
- Templatized classes like `simd_word` so AVX and SSE code can coexist in the same binary
- Added `stim_python_bindings` cmake target
- The cmake build now uses file lists which can be regenerated using a script
- Added `dev/` directory for scripts
- File lists used by cmake are now generated automatically instead of maintained manually
- The polyfill simd_word that uses 64 bit words now only uses one word instead of two (reducing padding overhead)
- To allow supporting a larger variety of decoders, sinter no longer includes each decoder in its requirements. Decoders need to be installed separately to use them.
- Added `-fPIC` to `libstim` cmake target
- Sinter now passes most information via the disk instead of through the multiprocessing API. This reduced the workload on the manager and the startup costs of batches, but made it much more disk limited on high core count machines.
- The API reference no longer shows deprecated methods (these methods are still listed in the .pyi stubs file)
- All doc strings now wrap at 80 characters, and this is enforced by continuous integration.
- The command line reference documentation has been substantially improved (e.g. flag information now grouped with the command instead of separate)
- Added python 3.11 support and OSX ARM support to the set of prebuilt wheels

Flagship changes:

- Released [`sinter`](https://github.com/quantumlib/Stim/tree/main/glue/sample), which uses stim and pymatching to perform multicore Monte Carlo sampling of error correction circuits.
- Added a python stub file (`stim/__init__.pyi`) to improve autocompletion in IDEs.

Breaking changes:

- The `"ptb64"` format now requires the shot count to be a multiple of 64, both when reading and when writing. (Previously, missing shots resulted in padding with zero'd data, which created a very easy way to get bad data when reading if the number of shots was not known.)
- The default value of `stim.Circuit.shortest_graphlike_error`'s argument `ignore_ungraphlike_errors` has changed from from `False` to `True`. (Setting it to `False` can use "remnant edges" that only appear as components of decomposed errors, and so do not correspond to a single physical error mechanism.)

Notable changes:

- New global methods:
- `stim.main`
- `stim.read_shot_data_file`
- `stim.write_shot_data_file`
- New `stim.DetectorErrorModel` methods:
- `stim.DetectorErrorModel.to_file`
- `stim.DetectorErrorModel.from_file`
- New `stim.Circuit` methods:
- `stim.Circuit.without_noise`
- `stim.Circuit.flattened`
- `stim.Circuit.search_for_undetectable_logical_errors`
- `stim.Circuit.to_file`
- `stim.Circuit.from_file`
- New `stim.TableauSimulator` methods:
- `stim.TableauSimulator.c_xyz`
- `stim.TableauSimulator.c_zyx`
- `stim.TableauSimulator.cx`
- `stim.TableauSimulator.do_circuit`
- `stim.TableauSimulator.do_pauli_string`
- `stim.TableauSimulator.do_tableau`
- `stim.TableauSimulator.h_xz`
- `stim.TableauSimulator.num_qubits`
- `stim.TableauSimulator.peek_x`
- `stim.TableauSimulator.peek_y`
- `stim.TableauSimulator.peek_z`
- `stim.TableauSimulator.postselect_x`
- `stim.TableauSimulator.postselect_y`
- `stim.TableauSimulator.postselect_z`
- `stim.TableauSimulator.reset_x`
- `stim.TableauSimulator.reset_y`
- `stim.TableauSimulator.reset_z`
- `stim.TableauSimulator.zcx`
- `stim.TableauSimulator.zcy`
- `stim.TableauSimulator.zcz`
- New `stim.Tableau` methods:
- `stim.Tableau.to_unitary_matrix`
- New method options:
- `obs_path=None` and `obs_format` for `stim.CompiledDetectorSampler.sample_file`
- `obs_path=None` and `obs_format` for `stim.CompiledMeasurementsToDetectionEventsConverter.convert_file`
- `ignore_decomposition_failures=False` for `stim.Circuit.detector_error_model`
- `block_decompose_from_introducing_remnant_edges=False` option for the `stim.Circuit.detector_error_model`
- `bit_pack_result=False` for `stim.CompiledMeasurementsToDetectionEventsConverter.convert`
- Functional changes:
- Error analysis now attempts to avoid introducing remnant edges unless absolutely necessary (improves detector error models)
- Error analysis now supports `ELSE_CORRELATED_ERROR` instructions as long they occur in contiguous blocks started by a `CORRELATED_ERROR`
- The stim python package now includes the stim command line tool. Much easier than building it for yourself.
- The floating point accuracy of `stim.TableauSimulator.state_vector` has been substantially improved (e.g. all zeros are now exact)
- The method signatures shown in the API reference are now more accurate, matching the ones in `__init__.pyi`

Bug fixes:

- Worked around the pseudo random number generator state being duplicated when using multiprocessing with start method `"fork"`. Samplers now seed from external entropy when constructed, instead of using entropy acquired at startup.
- Fixed various reported build failures related to MacOS and Apple M chips.
- Fixed `setup.py` not forcing UTF8 encoding when loading `README.md`, causing crashes on systems configured to use other encodings by default.
- Fixed `stimcirq` not understanding probabilistic `cirq.DensePauliString` gates.
- Worked around an issue where pytest gives useless failure messages for asserts involving stim objects.
- Fixed an infinite loop in `stim.Circuit.get_detector_coords`.
- Fixed complex indices like `stim.Circuit()[1j]` crashing the python interpreter (by switching to latest version of pybind11).
- Fix loop folding during error analysis incorrectly folding loops with observables including measurements from only the last few iterations
- Fixed a segfault in measurement-to-detection-event conversion related to failing to ignore noise channels
- Fixed a bug in measurement-to-detection-event conversion where some OBSERVABLE_INCLUDE instructions were being forgotten