From b9f333e67908a4d6f7ae8fb4b780b2473af103c4 Mon Sep 17 00:00:00 2001 From: Craig Gidney Date: Thu, 30 Jan 2025 18:11:40 -0800 Subject: [PATCH] all missing example warnings --- doc/python_api_reference_vDev.md | 644 +++++++++++++++++- doc/stim.pyi | 644 +++++++++++++++++- glue/python/src/stim/__init__.pyi | 644 +++++++++++++++++- src/stim/circuit/gate_target.pybind.cc | 22 +- src/stim/simulators/matched_error.pybind.cc | 209 +++++- .../simulators/tableau_simulator.pybind.cc | 80 ++- 6 files changed, 2210 insertions(+), 33 deletions(-) diff --git a/doc/python_api_reference_vDev.md b/doc/python_api_reference_vDev.md index 913af79e..6816f348 100644 --- a/doc/python_api_reference_vDev.md +++ b/doc/python_api_reference_vDev.md @@ -4520,6 +4520,16 @@ def __init__( targets_in_range: List[stim.GateTargetWithCoords], ) -> None: """Creates a stim.CircuitTargetsInsideInstruction. + + Examples: + >>> import stim + >>> val = stim.CircuitTargetsInsideInstruction( + ... gate='X_ERROR', + ... args=[0.25], + ... target_range_start=0, + ... target_range_end=1, + ... targets_in_range=[stim.GateTargetWithCoords(0, [])], + ... ) """ ``` @@ -4533,6 +4543,19 @@ def args( self, ) -> List[float]: """Returns parens arguments of the gate / instruction that was being executed. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... R 0 1 + ... X_ERROR(0.25) 0 1 + ... M 0 1 + ... DETECTOR(2, 3) rec[-1] rec[-2] + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> loc: stim.CircuitErrorLocation = err[0].circuit_error_locations[0] + >>> loc.instruction_targets.args + [0.25] """ ``` @@ -4546,6 +4569,19 @@ def gate( self, ) -> Optional[str]: """Returns the name of the gate / instruction that was being executed. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... R 0 1 + ... X_ERROR(0.25) 0 1 + ... M 0 1 + ... DETECTOR(2, 3) rec[-1] rec[-2] + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> loc: stim.CircuitErrorLocation = err[0].circuit_error_locations[0] + >>> loc.instruction_targets.gate + 'X_ERROR' """ ``` @@ -4560,6 +4596,21 @@ def target_range_end( ) -> int: """Returns the exclusive end of the range of targets that were executing within the gate / instruction. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... R 0 1 + ... X_ERROR(0.25) 0 1 + ... M 0 1 + ... DETECTOR(2, 3) rec[-1] rec[-2] + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> loc: stim.CircuitErrorLocation = err[0].circuit_error_locations[0] + >>> loc.instruction_targets.target_range_start + 0 + >>> loc.instruction_targets.target_range_end + 1 """ ``` @@ -4574,6 +4625,21 @@ def target_range_start( ) -> int: """Returns the inclusive start of the range of targets that were executing within the gate / instruction. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... R 0 1 + ... X_ERROR(0.25) 0 1 + ... M 0 1 + ... DETECTOR(2, 3) rec[-1] rec[-2] + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> loc: stim.CircuitErrorLocation = err[0].circuit_error_locations[0] + >>> loc.instruction_targets.target_range_start + 0 + >>> loc.instruction_targets.target_range_end + 1 """ ``` @@ -4589,6 +4655,19 @@ def targets_in_range( """Returns the subset of targets of the gate/instruction that were being executed. Includes coordinate data with the targets. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... R 0 1 + ... X_ERROR(0.25) 0 1 + ... M 0 1 + ... DETECTOR(2, 3) rec[-1] rec[-2] + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> loc: stim.CircuitErrorLocation = err[0].circuit_error_locations[0] + >>> loc.instruction_targets.targets_in_range + [stim.GateTargetWithCoords(0, [])] """ ``` @@ -6222,6 +6301,14 @@ class DemTargetWithCoords: problem in a circuit, instead of having to constantly manually look up the coordinates of a detector index in order to understand what is happening. + + Examples: + >>> import stim + >>> t = stim.DemTargetWithCoords(stim.DemTarget("D1"), [1.5, 2.0]) + >>> t.dem_target + stim.DemTarget('D1') + >>> t.coords + [1.5, 2.0] """ ``` @@ -6232,7 +6319,6 @@ class DemTargetWithCoords: # (in class stim.DemTargetWithCoords) def __init__( self, - *, dem_target: stim.DemTarget, coords: List[float], ) -> None: @@ -7413,6 +7499,28 @@ def to_file( # (at top-level in the stim module) class ExplainedError: """Describes the location of an error mechanism from a stim circuit. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... R 0 + ... TICK + ... Y_ERROR(0.125) 0 + ... M 0 + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> print(err[0]) + ExplainedError { + dem_error_terms: L0 + CircuitErrorLocation { + flipped_pauli_product: Y0 + Circuit location stack trace: + (after 1 TICKs) + at instruction #3 (Y_ERROR) in the circuit + at target #1 of the instruction + resolving to Y_ERROR(0.125) 0 + } + } """ ``` @@ -7428,6 +7536,28 @@ def __init__( circuit_error_locations: List[stim.CircuitErrorLocation], ) -> None: """Creates a stim.ExplainedError. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... R 0 + ... TICK + ... Y_ERROR(0.125) 0 + ... M 0 + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> print(err[0]) + ExplainedError { + dem_error_terms: L0 + CircuitErrorLocation { + flipped_pauli_product: Y0 + Circuit location stack trace: + (after 1 TICKs) + at instruction #3 (Y_ERROR) in the circuit + at target #1 of the instruction + resolving to Y_ERROR(0.125) 0 + } + } """ ``` @@ -7449,6 +7579,25 @@ def circuit_error_locations( Note: if this list is empty, it may be because there was a DEM error decomposed into parts where one of the parts is impossible to make on its own from a single circuit error. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... R 0 + ... TICK + ... Y_ERROR(0.125) 0 + ... M 0 + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> print(err[0].circuit_error_locations[0]) + CircuitErrorLocation { + flipped_pauli_product: Y0 + Circuit location stack trace: + (after 1 TICKs) + at instruction #3 (Y_ERROR) in the circuit + at target #1 of the instruction + resolving to Y_ERROR(0.125) 0 + } """ ``` @@ -8365,6 +8514,7 @@ def to_numpy( Examples: >>> import stim + >>> import numpy as np >>> sim = stim.FlipSimulator(batch_size=9) >>> sim.do(stim.Circuit('M(1) 0 1 2')) @@ -8372,12 +8522,11 @@ def to_numpy( >>> xs, zs, ms, ds, os = sim.to_numpy( ... transpose=True, ... bit_packed=True, - ... output_zs=True, + ... output_xs=True, ... output_measure_flips=ms_buf, ... ) >>> assert ms is ms_buf >>> xs - >>> zs array([[0], [0], [0], @@ -8387,6 +8536,7 @@ def to_numpy( [0], [0], [0]], dtype=uint8) + >>> zs >>> ms array([[7], [7], @@ -8412,6 +8562,18 @@ class FlippedMeasurement: Gives the measurement's index in the measurement record, and also the observable of the measurement. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... M(0.25) 1 10 + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> err[0].circuit_error_locations[0].flipped_measurement + stim.FlippedMeasurement( + record_index=1, + observable=(stim.GateTargetWithCoords(stim.target_z(10), []),), + ) """ ``` @@ -8452,6 +8614,15 @@ def observable( """Returns the observable of the flipped measurement. For example, an `MX 5` measurement will have the observable X5. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... M(0.25) 1 10 + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> err[0].circuit_error_locations[0].flipped_measurement.observable + [stim.GateTargetWithCoords(stim.target_z(10), [])] """ ``` @@ -8467,6 +8638,15 @@ def record_index( """The measurement record index of the flipped measurement. For example, the fifth measurement in a circuit has a measurement record index of 4. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... M(0.25) 1 10 + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> err[0].circuit_error_locations[0].flipped_measurement.record_index + 1 """ ``` @@ -9561,7 +9741,21 @@ def __init__( """Initializes a `stim.GateTarget`. Args: - value: A target like `5` or `stim.target_rec(-1)`. + value: A value to convert into a gate target, like an integer + to interpret as a qubit target or a string to parse. + + Examples: + >>> import stim + >>> stim.GateTarget(stim.GateTarget(5)) + stim.GateTarget(5) + >>> stim.GateTarget("X7") + stim.target_x(7) + >>> stim.GateTarget("rec[-3]") + stim.target_rec(-3) + >>> stim.GateTarget("!Z7") + stim.target_z(7, invert=True) + >>> stim.GateTarget("*") + stim.GateTarget.combiner() """ ``` @@ -9725,7 +9919,6 @@ def is_sweep_bit_target( ) -> bool: """Returns whether or not this is a sweep bit target like `sweep[4]`. - Examples: >>> import stim >>> stim.GateTarget(6).is_sweep_bit_target @@ -9946,6 +10139,14 @@ class GateTargetWithCoords: problem in a circuit, instead of having to constantly manually look up the coordinates of a qubit index in order to understand what is happening. + + Examples: + >>> import stim + >>> t = stim.GateTargetWithCoords(0, [1.5, 2.0]) + >>> t.gate_target + stim.GateTarget(0) + >>> t.coords + [1.5, 2.0] """ ``` @@ -9960,6 +10161,14 @@ def __init__( coords: List[float], ) -> None: """Creates a stim.GateTargetWithCoords. + + Examples: + >>> import stim + >>> t = stim.GateTargetWithCoords(0, [1.5, 2.0]) + >>> t.gate_target + stim.GateTarget(0) + >>> t.coords + [1.5, 2.0] """ ``` @@ -9975,6 +10184,12 @@ def coords( """Returns the associated coordinate information as a list of floats. If there is no coordinate information, returns an empty list. + + Examples: + >>> import stim + >>> t = stim.GateTargetWithCoords(0, [1.5, 2.0]) + >>> t.coords + [1.5, 2.0] """ ``` @@ -9988,6 +10203,12 @@ def gate_target( self, ) -> stim.GateTarget: """Returns the actual gate target as a `stim.GateTarget`. + + Examples: + >>> import stim + >>> t = stim.GateTargetWithCoords(0, [1.5, 2.0]) + >>> t.gate_target + stim.GateTarget(0) """ ``` @@ -13460,6 +13681,18 @@ def c_xyz( Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.c_xyz(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +Y +Z +X """ ``` @@ -13476,6 +13709,18 @@ def c_zyx( Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.c_zyx(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +Z +X +Y """ ``` @@ -13550,6 +13795,18 @@ def cnot( *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.cnot(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +_ +_ +Z +X """ ``` @@ -13722,6 +13979,18 @@ def cx( *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.cx(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +_ +_ +Z +X """ ``` @@ -13740,6 +14009,18 @@ def cy( *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.cy(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X """ ``` @@ -13758,6 +14039,18 @@ def cz( *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.cz(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +_ +_ +Z +X """ ``` @@ -13777,6 +14070,11 @@ def depolarize1( *targets: The indices of the qubits to target with the noise. p: The chance of the error being applied, independently, to each qubit. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.depolarize1(0, 1, 2, p=0.01) """ ``` @@ -13798,6 +14096,11 @@ def depolarize2( zip(targets[::1], targets[1::2]). p: The chance of the error being applied, independently, to each qubit pair. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.depolarize1(0, 1, 4, 5, p=0.01) """ ``` @@ -13945,6 +14248,18 @@ def h( Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.h(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +Z -Y +X """ ``` @@ -13961,6 +14276,18 @@ def h_xy( Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.h_xy(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +Y +X -Z """ ``` @@ -13977,6 +14304,18 @@ def h_xz( Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.h_xz(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +Z -Y +X """ ``` @@ -13993,6 +14332,18 @@ def h_yz( Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.h_yz(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + -X +Z +Y """ ``` @@ -14011,6 +14362,18 @@ def iswap( *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.iswap(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +_ +_ +Y +Z """ ``` @@ -14029,6 +14392,18 @@ def iswap_dag( *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.iswap_dag(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +_ +_ -Y +Z """ ``` @@ -14054,6 +14429,15 @@ def measure( Returns: The measurement result as a bool. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.x(1) + >>> s.measure(0) + False + >>> s.measure(1) + True """ ``` @@ -14135,6 +14519,13 @@ def measure_many( Returns: The measurement results as a list of bools. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.x(1) + >>> s.measure_many(0, 1) + [False, True] """ ``` @@ -14720,6 +15111,18 @@ def s( Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.s(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +Y -X +Z """ ``` @@ -14736,6 +15139,18 @@ def s_dag( Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.s_dag(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + -Y +X +Z """ ``` @@ -14997,6 +15412,18 @@ def sqrt_x( Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.sqrt_x(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Z -Y """ ``` @@ -15013,6 +15440,18 @@ def sqrt_x_dag( Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.sqrt_x_dag(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X -Z +Y """ ``` @@ -15029,6 +15468,18 @@ def sqrt_y( Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.sqrt_y(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + -Z +Y +X """ ``` @@ -15045,6 +15496,18 @@ def sqrt_y_dag( Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.sqrt_y_dag(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +Z +Y -X """ ``` @@ -15121,6 +15584,18 @@ def swap( *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.swap(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +Y +X +X +Z """ ``` @@ -15137,6 +15612,18 @@ def x( Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.x(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X -Y -Z """ ``` @@ -15156,6 +15643,11 @@ def x_error( *targets: The indices of the qubits to target with the noise. p: The chance of the X error being applied, independently, to each qubit. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.x_error(0, 1, 2, p=0.01) """ ``` @@ -15174,6 +15666,18 @@ def xcx( *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.xcx(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X """ ``` @@ -15192,6 +15696,18 @@ def xcy( *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.xcy(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +_ +_ """ ``` @@ -15210,6 +15726,18 @@ def xcz( *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.xcz(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +_ +_ """ ``` @@ -15226,6 +15754,18 @@ def y( Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.y(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + -X +Y -Z """ ``` @@ -15245,6 +15785,11 @@ def y_error( *targets: The indices of the qubits to target with the noise. p: The chance of the Y error being applied, independently, to each qubit. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.y_error(0, 1, 2, p=0.01) """ ``` @@ -15263,6 +15808,18 @@ def ycx( *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.ycx(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +_ +_ +Z +X """ ``` @@ -15281,6 +15838,18 @@ def ycy( *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.ycy(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +_ +_ """ ``` @@ -15299,6 +15868,18 @@ def ycz( *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.ycz(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +_ +_ +_ +_ """ ``` @@ -15315,6 +15896,18 @@ def z( Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.z(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + -X -Y +Z """ ``` @@ -15334,6 +15927,11 @@ def y_error( *targets: The indices of the qubits to target with the noise. p: The chance of the Z error being applied, independently, to each qubit. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.z_error(0, 1, 2, p=0.01) """ ``` @@ -15352,6 +15950,18 @@ def zcx( *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.zcx(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +_ +_ +Z +X """ ``` @@ -15370,6 +15980,18 @@ def zcy( *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.zcy(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X """ ``` @@ -15388,6 +16010,18 @@ def zcz( *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.zcz(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +_ +_ +Z +X """ ``` diff --git a/doc/stim.pyi b/doc/stim.pyi index f144d39c..e9a4dc18 100644 --- a/doc/stim.pyi +++ b/doc/stim.pyi @@ -3473,18 +3473,54 @@ class CircuitTargetsInsideInstruction: targets_in_range: List[stim.GateTargetWithCoords], ) -> None: """Creates a stim.CircuitTargetsInsideInstruction. + + Examples: + >>> import stim + >>> val = stim.CircuitTargetsInsideInstruction( + ... gate='X_ERROR', + ... args=[0.25], + ... target_range_start=0, + ... target_range_end=1, + ... targets_in_range=[stim.GateTargetWithCoords(0, [])], + ... ) """ @property def args( self, ) -> List[float]: """Returns parens arguments of the gate / instruction that was being executed. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... R 0 1 + ... X_ERROR(0.25) 0 1 + ... M 0 1 + ... DETECTOR(2, 3) rec[-1] rec[-2] + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> loc: stim.CircuitErrorLocation = err[0].circuit_error_locations[0] + >>> loc.instruction_targets.args + [0.25] """ @property def gate( self, ) -> Optional[str]: """Returns the name of the gate / instruction that was being executed. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... R 0 1 + ... X_ERROR(0.25) 0 1 + ... M 0 1 + ... DETECTOR(2, 3) rec[-1] rec[-2] + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> loc: stim.CircuitErrorLocation = err[0].circuit_error_locations[0] + >>> loc.instruction_targets.gate + 'X_ERROR' """ @property def target_range_end( @@ -3492,6 +3528,21 @@ class CircuitTargetsInsideInstruction: ) -> int: """Returns the exclusive end of the range of targets that were executing within the gate / instruction. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... R 0 1 + ... X_ERROR(0.25) 0 1 + ... M 0 1 + ... DETECTOR(2, 3) rec[-1] rec[-2] + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> loc: stim.CircuitErrorLocation = err[0].circuit_error_locations[0] + >>> loc.instruction_targets.target_range_start + 0 + >>> loc.instruction_targets.target_range_end + 1 """ @property def target_range_start( @@ -3499,6 +3550,21 @@ class CircuitTargetsInsideInstruction: ) -> int: """Returns the inclusive start of the range of targets that were executing within the gate / instruction. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... R 0 1 + ... X_ERROR(0.25) 0 1 + ... M 0 1 + ... DETECTOR(2, 3) rec[-1] rec[-2] + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> loc: stim.CircuitErrorLocation = err[0].circuit_error_locations[0] + >>> loc.instruction_targets.target_range_start + 0 + >>> loc.instruction_targets.target_range_end + 1 """ @property def targets_in_range( @@ -3507,6 +3573,19 @@ class CircuitTargetsInsideInstruction: """Returns the subset of targets of the gate/instruction that were being executed. Includes coordinate data with the targets. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... R 0 1 + ... X_ERROR(0.25) 0 1 + ... M 0 1 + ... DETECTOR(2, 3) rec[-1] rec[-2] + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> loc: stim.CircuitErrorLocation = err[0].circuit_error_locations[0] + >>> loc.instruction_targets.targets_in_range + [stim.GateTargetWithCoords(0, [])] """ class CompiledDemSampler: """A helper class for efficiently sampler from a detector error model. @@ -4846,10 +4925,17 @@ class DemTargetWithCoords: problem in a circuit, instead of having to constantly manually look up the coordinates of a detector index in order to understand what is happening. + + Examples: + >>> import stim + >>> t = stim.DemTargetWithCoords(stim.DemTarget("D1"), [1.5, 2.0]) + >>> t.dem_target + stim.DemTarget('D1') + >>> t.coords + [1.5, 2.0] """ def __init__( self, - *, dem_target: stim.DemTarget, coords: List[float], ) -> None: @@ -5813,6 +5899,28 @@ class DetectorErrorModel: """ class ExplainedError: """Describes the location of an error mechanism from a stim circuit. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... R 0 + ... TICK + ... Y_ERROR(0.125) 0 + ... M 0 + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> print(err[0]) + ExplainedError { + dem_error_terms: L0 + CircuitErrorLocation { + flipped_pauli_product: Y0 + Circuit location stack trace: + (after 1 TICKs) + at instruction #3 (Y_ERROR) in the circuit + at target #1 of the instruction + resolving to Y_ERROR(0.125) 0 + } + } """ def __init__( self, @@ -5821,6 +5929,28 @@ class ExplainedError: circuit_error_locations: List[stim.CircuitErrorLocation], ) -> None: """Creates a stim.ExplainedError. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... R 0 + ... TICK + ... Y_ERROR(0.125) 0 + ... M 0 + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> print(err[0]) + ExplainedError { + dem_error_terms: L0 + CircuitErrorLocation { + flipped_pauli_product: Y0 + Circuit location stack trace: + (after 1 TICKs) + at instruction #3 (Y_ERROR) in the circuit + at target #1 of the instruction + resolving to Y_ERROR(0.125) 0 + } + } """ @property def circuit_error_locations( @@ -5835,6 +5965,25 @@ class ExplainedError: Note: if this list is empty, it may be because there was a DEM error decomposed into parts where one of the parts is impossible to make on its own from a single circuit error. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... R 0 + ... TICK + ... Y_ERROR(0.125) 0 + ... M 0 + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> print(err[0].circuit_error_locations[0]) + CircuitErrorLocation { + flipped_pauli_product: Y0 + Circuit location stack trace: + (after 1 TICKs) + at instruction #3 (Y_ERROR) in the circuit + at target #1 of the instruction + resolving to Y_ERROR(0.125) 0 + } """ @property def dem_error_terms( @@ -6625,6 +6774,7 @@ class FlipSimulator: Examples: >>> import stim + >>> import numpy as np >>> sim = stim.FlipSimulator(batch_size=9) >>> sim.do(stim.Circuit('M(1) 0 1 2')) @@ -6632,12 +6782,11 @@ class FlipSimulator: >>> xs, zs, ms, ds, os = sim.to_numpy( ... transpose=True, ... bit_packed=True, - ... output_zs=True, + ... output_xs=True, ... output_measure_flips=ms_buf, ... ) >>> assert ms is ms_buf >>> xs - >>> zs array([[0], [0], [0], @@ -6647,6 +6796,7 @@ class FlipSimulator: [0], [0], [0]], dtype=uint8) + >>> zs >>> ms array([[7], [7], @@ -6665,6 +6815,18 @@ class FlippedMeasurement: Gives the measurement's index in the measurement record, and also the observable of the measurement. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... M(0.25) 1 10 + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> err[0].circuit_error_locations[0].flipped_measurement + stim.FlippedMeasurement( + record_index=1, + observable=(stim.GateTargetWithCoords(stim.target_z(10), []),), + ) """ def __init__( self, @@ -6691,6 +6853,15 @@ class FlippedMeasurement: """Returns the observable of the flipped measurement. For example, an `MX 5` measurement will have the observable X5. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... M(0.25) 1 10 + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> err[0].circuit_error_locations[0].flipped_measurement.observable + [stim.GateTargetWithCoords(stim.target_z(10), [])] """ @property def record_index( @@ -6699,6 +6870,15 @@ class FlippedMeasurement: """The measurement record index of the flipped measurement. For example, the fifth measurement in a circuit has a measurement record index of 4. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... M(0.25) 1 10 + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> err[0].circuit_error_locations[0].flipped_measurement.record_index + 1 """ class Flow: """A stabilizer flow (e.g. "XI -> XX xor rec[-1]"). @@ -7541,7 +7721,21 @@ class GateTarget: """Initializes a `stim.GateTarget`. Args: - value: A target like `5` or `stim.target_rec(-1)`. + value: A value to convert into a gate target, like an integer + to interpret as a qubit target or a string to parse. + + Examples: + >>> import stim + >>> stim.GateTarget(stim.GateTarget(5)) + stim.GateTarget(5) + >>> stim.GateTarget("X7") + stim.target_x(7) + >>> stim.GateTarget("rec[-3]") + stim.target_rec(-3) + >>> stim.GateTarget("!Z7") + stim.target_z(7, invert=True) + >>> stim.GateTarget("*") + stim.GateTarget.combiner() """ def __ne__( self, @@ -7656,7 +7850,6 @@ class GateTarget: ) -> bool: """Returns whether or not this is a sweep bit target like `sweep[4]`. - Examples: >>> import stim >>> stim.GateTarget(6).is_sweep_bit_target @@ -7828,6 +8021,14 @@ class GateTargetWithCoords: problem in a circuit, instead of having to constantly manually look up the coordinates of a qubit index in order to understand what is happening. + + Examples: + >>> import stim + >>> t = stim.GateTargetWithCoords(0, [1.5, 2.0]) + >>> t.gate_target + stim.GateTarget(0) + >>> t.coords + [1.5, 2.0] """ def __init__( self, @@ -7835,6 +8036,14 @@ class GateTargetWithCoords: coords: List[float], ) -> None: """Creates a stim.GateTargetWithCoords. + + Examples: + >>> import stim + >>> t = stim.GateTargetWithCoords(0, [1.5, 2.0]) + >>> t.gate_target + stim.GateTarget(0) + >>> t.coords + [1.5, 2.0] """ @property def coords( @@ -7843,12 +8052,24 @@ class GateTargetWithCoords: """Returns the associated coordinate information as a list of floats. If there is no coordinate information, returns an empty list. + + Examples: + >>> import stim + >>> t = stim.GateTargetWithCoords(0, [1.5, 2.0]) + >>> t.coords + [1.5, 2.0] """ @property def gate_target( self, ) -> stim.GateTarget: """Returns the actual gate target as a `stim.GateTarget`. + + Examples: + >>> import stim + >>> t = stim.GateTargetWithCoords(0, [1.5, 2.0]) + >>> t.gate_target + stim.GateTarget(0) """ class PauliString: """A signed Pauli tensor product (e.g. "+X \u2297 X \u2297 X" or "-Y \u2297 Z". @@ -10711,6 +10932,18 @@ class TableauSimulator: Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.c_xyz(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +Y +Z +X """ def c_zyx( self, @@ -10720,6 +10953,18 @@ class TableauSimulator: Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.c_zyx(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +Z +X +Y """ def canonical_stabilizers( self, @@ -10780,6 +11025,18 @@ class TableauSimulator: *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.cnot(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +_ +_ +Z +X """ def copy( self, @@ -10924,6 +11181,18 @@ class TableauSimulator: *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.cx(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +_ +_ +Z +X """ def cy( self, @@ -10935,6 +11204,18 @@ class TableauSimulator: *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.cy(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X """ def cz( self, @@ -10946,6 +11227,18 @@ class TableauSimulator: *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.cz(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +_ +_ +Z +X """ def depolarize1( self, @@ -10958,6 +11251,11 @@ class TableauSimulator: *targets: The indices of the qubits to target with the noise. p: The chance of the error being applied, independently, to each qubit. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.depolarize1(0, 1, 2, p=0.01) """ def depolarize2( self, @@ -10972,6 +11270,11 @@ class TableauSimulator: zip(targets[::1], targets[1::2]). p: The chance of the error being applied, independently, to each qubit pair. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.depolarize1(0, 1, 4, 5, p=0.01) """ def do( self, @@ -11084,6 +11387,18 @@ class TableauSimulator: Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.h(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +Z -Y +X """ def h_xy( self, @@ -11093,6 +11408,18 @@ class TableauSimulator: Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.h_xy(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +Y +X -Z """ def h_xz( self, @@ -11102,6 +11429,18 @@ class TableauSimulator: Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.h_xz(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +Z -Y +X """ def h_yz( self, @@ -11111,6 +11450,18 @@ class TableauSimulator: Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.h_yz(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + -X +Z +Y """ def iswap( self, @@ -11122,6 +11473,18 @@ class TableauSimulator: *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.iswap(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +_ +_ +Y +Z """ def iswap_dag( self, @@ -11133,6 +11496,18 @@ class TableauSimulator: *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.iswap_dag(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +_ +_ -Y +Z """ def measure( self, @@ -11151,6 +11526,15 @@ class TableauSimulator: Returns: The measurement result as a bool. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.x(1) + >>> s.measure(0) + False + >>> s.measure(1) + True """ def measure_kickback( self, @@ -11218,6 +11602,13 @@ class TableauSimulator: Returns: The measurement results as a list of bools. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.x(1) + >>> s.measure_many(0, 1) + [False, True] """ def measure_observable( self, @@ -11691,6 +12082,18 @@ class TableauSimulator: Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.s(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +Y -X +Z """ def s_dag( self, @@ -11700,6 +12103,18 @@ class TableauSimulator: Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.s_dag(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + -Y +X +Z """ def set_inverse_tableau( self, @@ -11926,6 +12341,18 @@ class TableauSimulator: Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.sqrt_x(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Z -Y """ def sqrt_x_dag( self, @@ -11935,6 +12362,18 @@ class TableauSimulator: Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.sqrt_x_dag(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X -Z +Y """ def sqrt_y( self, @@ -11944,6 +12383,18 @@ class TableauSimulator: Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.sqrt_y(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + -Z +Y +X """ def sqrt_y_dag( self, @@ -11953,6 +12404,18 @@ class TableauSimulator: Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.sqrt_y_dag(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +Z +Y -X """ def state_vector( self, @@ -12015,6 +12478,18 @@ class TableauSimulator: *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.swap(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +Y +X +X +Z """ def x( self, @@ -12024,6 +12499,18 @@ class TableauSimulator: Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.x(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X -Y -Z """ def x_error( self, @@ -12036,6 +12523,11 @@ class TableauSimulator: *targets: The indices of the qubits to target with the noise. p: The chance of the X error being applied, independently, to each qubit. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.x_error(0, 1, 2, p=0.01) """ def xcx( self, @@ -12047,6 +12539,18 @@ class TableauSimulator: *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.xcx(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X """ def xcy( self, @@ -12058,6 +12562,18 @@ class TableauSimulator: *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.xcy(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +_ +_ """ def xcz( self, @@ -12069,6 +12585,18 @@ class TableauSimulator: *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.xcz(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +_ +_ """ def y( self, @@ -12078,6 +12606,18 @@ class TableauSimulator: Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.y(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + -X +Y -Z """ def y_error( self, @@ -12090,6 +12630,11 @@ class TableauSimulator: *targets: The indices of the qubits to target with the noise. p: The chance of the Y error being applied, independently, to each qubit. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.y_error(0, 1, 2, p=0.01) """ def ycx( self, @@ -12101,6 +12646,18 @@ class TableauSimulator: *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.ycx(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +_ +_ +Z +X """ def ycy( self, @@ -12112,6 +12669,18 @@ class TableauSimulator: *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.ycy(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +_ +_ """ def ycz( self, @@ -12123,6 +12692,18 @@ class TableauSimulator: *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.ycz(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +_ +_ +_ +_ """ def z( self, @@ -12132,6 +12713,18 @@ class TableauSimulator: Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.z(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + -X -Y +Z """ def y_error( self, @@ -12144,6 +12737,11 @@ class TableauSimulator: *targets: The indices of the qubits to target with the noise. p: The chance of the Z error being applied, independently, to each qubit. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.z_error(0, 1, 2, p=0.01) """ def zcx( self, @@ -12155,6 +12753,18 @@ class TableauSimulator: *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.zcx(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +_ +_ +Z +X """ def zcy( self, @@ -12166,6 +12776,18 @@ class TableauSimulator: *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.zcy(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X """ def zcz( self, @@ -12177,6 +12799,18 @@ class TableauSimulator: *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.zcz(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +_ +_ +Z +X """ @overload def gate_data( diff --git a/glue/python/src/stim/__init__.pyi b/glue/python/src/stim/__init__.pyi index f144d39c..e9a4dc18 100644 --- a/glue/python/src/stim/__init__.pyi +++ b/glue/python/src/stim/__init__.pyi @@ -3473,18 +3473,54 @@ class CircuitTargetsInsideInstruction: targets_in_range: List[stim.GateTargetWithCoords], ) -> None: """Creates a stim.CircuitTargetsInsideInstruction. + + Examples: + >>> import stim + >>> val = stim.CircuitTargetsInsideInstruction( + ... gate='X_ERROR', + ... args=[0.25], + ... target_range_start=0, + ... target_range_end=1, + ... targets_in_range=[stim.GateTargetWithCoords(0, [])], + ... ) """ @property def args( self, ) -> List[float]: """Returns parens arguments of the gate / instruction that was being executed. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... R 0 1 + ... X_ERROR(0.25) 0 1 + ... M 0 1 + ... DETECTOR(2, 3) rec[-1] rec[-2] + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> loc: stim.CircuitErrorLocation = err[0].circuit_error_locations[0] + >>> loc.instruction_targets.args + [0.25] """ @property def gate( self, ) -> Optional[str]: """Returns the name of the gate / instruction that was being executed. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... R 0 1 + ... X_ERROR(0.25) 0 1 + ... M 0 1 + ... DETECTOR(2, 3) rec[-1] rec[-2] + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> loc: stim.CircuitErrorLocation = err[0].circuit_error_locations[0] + >>> loc.instruction_targets.gate + 'X_ERROR' """ @property def target_range_end( @@ -3492,6 +3528,21 @@ class CircuitTargetsInsideInstruction: ) -> int: """Returns the exclusive end of the range of targets that were executing within the gate / instruction. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... R 0 1 + ... X_ERROR(0.25) 0 1 + ... M 0 1 + ... DETECTOR(2, 3) rec[-1] rec[-2] + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> loc: stim.CircuitErrorLocation = err[0].circuit_error_locations[0] + >>> loc.instruction_targets.target_range_start + 0 + >>> loc.instruction_targets.target_range_end + 1 """ @property def target_range_start( @@ -3499,6 +3550,21 @@ class CircuitTargetsInsideInstruction: ) -> int: """Returns the inclusive start of the range of targets that were executing within the gate / instruction. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... R 0 1 + ... X_ERROR(0.25) 0 1 + ... M 0 1 + ... DETECTOR(2, 3) rec[-1] rec[-2] + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> loc: stim.CircuitErrorLocation = err[0].circuit_error_locations[0] + >>> loc.instruction_targets.target_range_start + 0 + >>> loc.instruction_targets.target_range_end + 1 """ @property def targets_in_range( @@ -3507,6 +3573,19 @@ class CircuitTargetsInsideInstruction: """Returns the subset of targets of the gate/instruction that were being executed. Includes coordinate data with the targets. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... R 0 1 + ... X_ERROR(0.25) 0 1 + ... M 0 1 + ... DETECTOR(2, 3) rec[-1] rec[-2] + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> loc: stim.CircuitErrorLocation = err[0].circuit_error_locations[0] + >>> loc.instruction_targets.targets_in_range + [stim.GateTargetWithCoords(0, [])] """ class CompiledDemSampler: """A helper class for efficiently sampler from a detector error model. @@ -4846,10 +4925,17 @@ class DemTargetWithCoords: problem in a circuit, instead of having to constantly manually look up the coordinates of a detector index in order to understand what is happening. + + Examples: + >>> import stim + >>> t = stim.DemTargetWithCoords(stim.DemTarget("D1"), [1.5, 2.0]) + >>> t.dem_target + stim.DemTarget('D1') + >>> t.coords + [1.5, 2.0] """ def __init__( self, - *, dem_target: stim.DemTarget, coords: List[float], ) -> None: @@ -5813,6 +5899,28 @@ class DetectorErrorModel: """ class ExplainedError: """Describes the location of an error mechanism from a stim circuit. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... R 0 + ... TICK + ... Y_ERROR(0.125) 0 + ... M 0 + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> print(err[0]) + ExplainedError { + dem_error_terms: L0 + CircuitErrorLocation { + flipped_pauli_product: Y0 + Circuit location stack trace: + (after 1 TICKs) + at instruction #3 (Y_ERROR) in the circuit + at target #1 of the instruction + resolving to Y_ERROR(0.125) 0 + } + } """ def __init__( self, @@ -5821,6 +5929,28 @@ class ExplainedError: circuit_error_locations: List[stim.CircuitErrorLocation], ) -> None: """Creates a stim.ExplainedError. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... R 0 + ... TICK + ... Y_ERROR(0.125) 0 + ... M 0 + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> print(err[0]) + ExplainedError { + dem_error_terms: L0 + CircuitErrorLocation { + flipped_pauli_product: Y0 + Circuit location stack trace: + (after 1 TICKs) + at instruction #3 (Y_ERROR) in the circuit + at target #1 of the instruction + resolving to Y_ERROR(0.125) 0 + } + } """ @property def circuit_error_locations( @@ -5835,6 +5965,25 @@ class ExplainedError: Note: if this list is empty, it may be because there was a DEM error decomposed into parts where one of the parts is impossible to make on its own from a single circuit error. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... R 0 + ... TICK + ... Y_ERROR(0.125) 0 + ... M 0 + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> print(err[0].circuit_error_locations[0]) + CircuitErrorLocation { + flipped_pauli_product: Y0 + Circuit location stack trace: + (after 1 TICKs) + at instruction #3 (Y_ERROR) in the circuit + at target #1 of the instruction + resolving to Y_ERROR(0.125) 0 + } """ @property def dem_error_terms( @@ -6625,6 +6774,7 @@ class FlipSimulator: Examples: >>> import stim + >>> import numpy as np >>> sim = stim.FlipSimulator(batch_size=9) >>> sim.do(stim.Circuit('M(1) 0 1 2')) @@ -6632,12 +6782,11 @@ class FlipSimulator: >>> xs, zs, ms, ds, os = sim.to_numpy( ... transpose=True, ... bit_packed=True, - ... output_zs=True, + ... output_xs=True, ... output_measure_flips=ms_buf, ... ) >>> assert ms is ms_buf >>> xs - >>> zs array([[0], [0], [0], @@ -6647,6 +6796,7 @@ class FlipSimulator: [0], [0], [0]], dtype=uint8) + >>> zs >>> ms array([[7], [7], @@ -6665,6 +6815,18 @@ class FlippedMeasurement: Gives the measurement's index in the measurement record, and also the observable of the measurement. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... M(0.25) 1 10 + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> err[0].circuit_error_locations[0].flipped_measurement + stim.FlippedMeasurement( + record_index=1, + observable=(stim.GateTargetWithCoords(stim.target_z(10), []),), + ) """ def __init__( self, @@ -6691,6 +6853,15 @@ class FlippedMeasurement: """Returns the observable of the flipped measurement. For example, an `MX 5` measurement will have the observable X5. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... M(0.25) 1 10 + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> err[0].circuit_error_locations[0].flipped_measurement.observable + [stim.GateTargetWithCoords(stim.target_z(10), [])] """ @property def record_index( @@ -6699,6 +6870,15 @@ class FlippedMeasurement: """The measurement record index of the flipped measurement. For example, the fifth measurement in a circuit has a measurement record index of 4. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... M(0.25) 1 10 + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> err[0].circuit_error_locations[0].flipped_measurement.record_index + 1 """ class Flow: """A stabilizer flow (e.g. "XI -> XX xor rec[-1]"). @@ -7541,7 +7721,21 @@ class GateTarget: """Initializes a `stim.GateTarget`. Args: - value: A target like `5` or `stim.target_rec(-1)`. + value: A value to convert into a gate target, like an integer + to interpret as a qubit target or a string to parse. + + Examples: + >>> import stim + >>> stim.GateTarget(stim.GateTarget(5)) + stim.GateTarget(5) + >>> stim.GateTarget("X7") + stim.target_x(7) + >>> stim.GateTarget("rec[-3]") + stim.target_rec(-3) + >>> stim.GateTarget("!Z7") + stim.target_z(7, invert=True) + >>> stim.GateTarget("*") + stim.GateTarget.combiner() """ def __ne__( self, @@ -7656,7 +7850,6 @@ class GateTarget: ) -> bool: """Returns whether or not this is a sweep bit target like `sweep[4]`. - Examples: >>> import stim >>> stim.GateTarget(6).is_sweep_bit_target @@ -7828,6 +8021,14 @@ class GateTargetWithCoords: problem in a circuit, instead of having to constantly manually look up the coordinates of a qubit index in order to understand what is happening. + + Examples: + >>> import stim + >>> t = stim.GateTargetWithCoords(0, [1.5, 2.0]) + >>> t.gate_target + stim.GateTarget(0) + >>> t.coords + [1.5, 2.0] """ def __init__( self, @@ -7835,6 +8036,14 @@ class GateTargetWithCoords: coords: List[float], ) -> None: """Creates a stim.GateTargetWithCoords. + + Examples: + >>> import stim + >>> t = stim.GateTargetWithCoords(0, [1.5, 2.0]) + >>> t.gate_target + stim.GateTarget(0) + >>> t.coords + [1.5, 2.0] """ @property def coords( @@ -7843,12 +8052,24 @@ class GateTargetWithCoords: """Returns the associated coordinate information as a list of floats. If there is no coordinate information, returns an empty list. + + Examples: + >>> import stim + >>> t = stim.GateTargetWithCoords(0, [1.5, 2.0]) + >>> t.coords + [1.5, 2.0] """ @property def gate_target( self, ) -> stim.GateTarget: """Returns the actual gate target as a `stim.GateTarget`. + + Examples: + >>> import stim + >>> t = stim.GateTargetWithCoords(0, [1.5, 2.0]) + >>> t.gate_target + stim.GateTarget(0) """ class PauliString: """A signed Pauli tensor product (e.g. "+X \u2297 X \u2297 X" or "-Y \u2297 Z". @@ -10711,6 +10932,18 @@ class TableauSimulator: Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.c_xyz(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +Y +Z +X """ def c_zyx( self, @@ -10720,6 +10953,18 @@ class TableauSimulator: Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.c_zyx(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +Z +X +Y """ def canonical_stabilizers( self, @@ -10780,6 +11025,18 @@ class TableauSimulator: *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.cnot(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +_ +_ +Z +X """ def copy( self, @@ -10924,6 +11181,18 @@ class TableauSimulator: *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.cx(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +_ +_ +Z +X """ def cy( self, @@ -10935,6 +11204,18 @@ class TableauSimulator: *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.cy(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X """ def cz( self, @@ -10946,6 +11227,18 @@ class TableauSimulator: *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.cz(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +_ +_ +Z +X """ def depolarize1( self, @@ -10958,6 +11251,11 @@ class TableauSimulator: *targets: The indices of the qubits to target with the noise. p: The chance of the error being applied, independently, to each qubit. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.depolarize1(0, 1, 2, p=0.01) """ def depolarize2( self, @@ -10972,6 +11270,11 @@ class TableauSimulator: zip(targets[::1], targets[1::2]). p: The chance of the error being applied, independently, to each qubit pair. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.depolarize1(0, 1, 4, 5, p=0.01) """ def do( self, @@ -11084,6 +11387,18 @@ class TableauSimulator: Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.h(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +Z -Y +X """ def h_xy( self, @@ -11093,6 +11408,18 @@ class TableauSimulator: Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.h_xy(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +Y +X -Z """ def h_xz( self, @@ -11102,6 +11429,18 @@ class TableauSimulator: Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.h_xz(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +Z -Y +X """ def h_yz( self, @@ -11111,6 +11450,18 @@ class TableauSimulator: Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.h_yz(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + -X +Z +Y """ def iswap( self, @@ -11122,6 +11473,18 @@ class TableauSimulator: *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.iswap(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +_ +_ +Y +Z """ def iswap_dag( self, @@ -11133,6 +11496,18 @@ class TableauSimulator: *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.iswap_dag(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +_ +_ -Y +Z """ def measure( self, @@ -11151,6 +11526,15 @@ class TableauSimulator: Returns: The measurement result as a bool. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.x(1) + >>> s.measure(0) + False + >>> s.measure(1) + True """ def measure_kickback( self, @@ -11218,6 +11602,13 @@ class TableauSimulator: Returns: The measurement results as a list of bools. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.x(1) + >>> s.measure_many(0, 1) + [False, True] """ def measure_observable( self, @@ -11691,6 +12082,18 @@ class TableauSimulator: Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.s(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +Y -X +Z """ def s_dag( self, @@ -11700,6 +12103,18 @@ class TableauSimulator: Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.s_dag(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + -Y +X +Z """ def set_inverse_tableau( self, @@ -11926,6 +12341,18 @@ class TableauSimulator: Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.sqrt_x(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Z -Y """ def sqrt_x_dag( self, @@ -11935,6 +12362,18 @@ class TableauSimulator: Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.sqrt_x_dag(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X -Z +Y """ def sqrt_y( self, @@ -11944,6 +12383,18 @@ class TableauSimulator: Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.sqrt_y(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + -Z +Y +X """ def sqrt_y_dag( self, @@ -11953,6 +12404,18 @@ class TableauSimulator: Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.sqrt_y_dag(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +Z +Y -X """ def state_vector( self, @@ -12015,6 +12478,18 @@ class TableauSimulator: *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.swap(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +Y +X +X +Z """ def x( self, @@ -12024,6 +12499,18 @@ class TableauSimulator: Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.x(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X -Y -Z """ def x_error( self, @@ -12036,6 +12523,11 @@ class TableauSimulator: *targets: The indices of the qubits to target with the noise. p: The chance of the X error being applied, independently, to each qubit. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.x_error(0, 1, 2, p=0.01) """ def xcx( self, @@ -12047,6 +12539,18 @@ class TableauSimulator: *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.xcx(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X """ def xcy( self, @@ -12058,6 +12562,18 @@ class TableauSimulator: *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.xcy(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +_ +_ """ def xcz( self, @@ -12069,6 +12585,18 @@ class TableauSimulator: *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.xcz(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +_ +_ """ def y( self, @@ -12078,6 +12606,18 @@ class TableauSimulator: Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.y(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + -X +Y -Z """ def y_error( self, @@ -12090,6 +12630,11 @@ class TableauSimulator: *targets: The indices of the qubits to target with the noise. p: The chance of the Y error being applied, independently, to each qubit. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.y_error(0, 1, 2, p=0.01) """ def ycx( self, @@ -12101,6 +12646,18 @@ class TableauSimulator: *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.ycx(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +_ +_ +Z +X """ def ycy( self, @@ -12112,6 +12669,18 @@ class TableauSimulator: *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.ycy(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +_ +_ """ def ycz( self, @@ -12123,6 +12692,18 @@ class TableauSimulator: *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.ycz(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +_ +_ +_ +_ """ def z( self, @@ -12132,6 +12713,18 @@ class TableauSimulator: Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.z(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + -X -Y +Z """ def y_error( self, @@ -12144,6 +12737,11 @@ class TableauSimulator: *targets: The indices of the qubits to target with the noise. p: The chance of the Z error being applied, independently, to each qubit. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.z_error(0, 1, 2, p=0.01) """ def zcx( self, @@ -12155,6 +12753,18 @@ class TableauSimulator: *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.zcx(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +_ +_ +Z +X """ def zcy( self, @@ -12166,6 +12776,18 @@ class TableauSimulator: *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.zcy(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X """ def zcz( self, @@ -12177,6 +12799,18 @@ class TableauSimulator: *targets: The indices of the qubits to target with the gate. Applies the gate to the first two targets, then the next two targets, and so forth. There must be an even number of targets. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0, 3) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +X +Y +Z +X + >>> s.zcz(0, 1, 2, 3) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(4))) + +_ +_ +Z +X """ @overload def gate_data( diff --git a/src/stim/circuit/gate_target.pybind.cc b/src/stim/circuit/gate_target.pybind.cc index ba7db7f4..32495158 100644 --- a/src/stim/circuit/gate_target.pybind.cc +++ b/src/stim/circuit/gate_target.pybind.cc @@ -21,6 +21,11 @@ using namespace stim; using namespace stim_pybind; GateTarget handle_to_gate_target(const pybind11::handle &obj) { + try { + std::string_view text = pybind11::cast(obj); + return GateTarget::from_target_str(text); + } catch (const pybind11::cast_error &ex) { + } try { return pybind11::cast(obj); } catch (const pybind11::cast_error &ex) { @@ -65,7 +70,21 @@ void stim_pybind::pybind_circuit_gate_target_methods(pybind11::module &m, pybind Initializes a `stim.GateTarget`. Args: - value: A target like `5` or `stim.target_rec(-1)`. + value: A value to convert into a gate target, like an integer + to interpret as a qubit target or a string to parse. + + Examples: + >>> import stim + >>> stim.GateTarget(stim.GateTarget(5)) + stim.GateTarget(5) + >>> stim.GateTarget("X7") + stim.target_x(7) + >>> stim.GateTarget("rec[-3]") + stim.target_rec(-3) + >>> stim.GateTarget("!Z7") + stim.target_z(7, invert=True) + >>> stim.GateTarget("*") + stim.GateTarget.combiner() )DOC") .data()); @@ -340,7 +359,6 @@ void stim_pybind::pybind_circuit_gate_target_methods(pybind11::module &m, pybind clean_doc_string(R"DOC( Returns whether or not this is a sweep bit target like `sweep[4]`. - Examples: >>> import stim >>> stim.GateTarget(6).is_sweep_bit_target diff --git a/src/stim/simulators/matched_error.pybind.cc b/src/stim/simulators/matched_error.pybind.cc index 88446410..141653fd 100644 --- a/src/stim/simulators/matched_error.pybind.cc +++ b/src/stim/simulators/matched_error.pybind.cc @@ -310,6 +310,14 @@ pybind11::class_ stim_pybind::pybind_gate_target_with_coor problem in a circuit, instead of having to constantly manually look up the coordinates of a qubit index in order to understand what is happening. + + Examples: + >>> import stim + >>> t = stim.GateTargetWithCoords(0, [1.5, 2.0]) + >>> t.gate_target + stim.GateTarget(0) + >>> t.coords + [1.5, 2.0] )DOC") .data()); } @@ -321,6 +329,12 @@ void stim_pybind::pybind_gate_target_with_coords_methods( &GateTargetWithCoords::gate_target, clean_doc_string(R"DOC( Returns the actual gate target as a `stim.GateTarget`. + + Examples: + >>> import stim + >>> t = stim.GateTargetWithCoords(0, [1.5, 2.0]) + >>> t.gate_target + stim.GateTarget(0) )DOC") .data()); @@ -331,6 +345,12 @@ void stim_pybind::pybind_gate_target_with_coords_methods( Returns the associated coordinate information as a list of floats. If there is no coordinate information, returns an empty list. + + Examples: + >>> import stim + >>> t = stim.GateTargetWithCoords(0, [1.5, 2.0]) + >>> t.coords + [1.5, 2.0] )DOC") .data()); @@ -349,6 +369,14 @@ void stim_pybind::pybind_gate_target_with_coords_methods( pybind11::arg("coords"), clean_doc_string(R"DOC( Creates a stim.GateTargetWithCoords. + + Examples: + >>> import stim + >>> t = stim.GateTargetWithCoords(0, [1.5, 2.0]) + >>> t.gate_target + stim.GateTarget(0) + >>> t.coords + [1.5, 2.0] )DOC") .data()); c.def("__repr__", &GateTargetWithCoords_repr); @@ -373,6 +401,14 @@ pybind11::class_ stim_pybind::pybind_dem_target_with_coords problem in a circuit, instead of having to constantly manually look up the coordinates of a detector index in order to understand what is happening. + + Examples: + >>> import stim + >>> t = stim.DemTargetWithCoords(stim.DemTarget("D1"), [1.5, 2.0]) + >>> t.dem_target + stim.DemTarget('D1') + >>> t.coords + [1.5, 2.0] )DOC") .data()); } @@ -435,7 +471,6 @@ void stim_pybind::pybind_dem_target_with_coords_methods( [](const ExposedDemTarget &dem_target, const std::vector &coords) -> DemTargetWithCoords { return DemTargetWithCoords{dem_target, coords}; }), - pybind11::kw_only(), pybind11::arg("dem_target"), pybind11::arg("coords"), clean_doc_string(R"DOC( @@ -466,6 +501,18 @@ pybind11::class_ stim_pybind::pybind_flipped_measurement(pyb Gives the measurement's index in the measurement record, and also the observable of the measurement. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... M(0.25) 1 10 + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> err[0].circuit_error_locations[0].flipped_measurement + stim.FlippedMeasurement( + record_index=1, + observable=(stim.GateTargetWithCoords(stim.target_z(10), []),), + ) )DOC") .data()); } @@ -478,6 +525,15 @@ void stim_pybind::pybind_flipped_measurement_methods( The measurement record index of the flipped measurement. For example, the fifth measurement in a circuit has a measurement record index of 4. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... M(0.25) 1 10 + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> err[0].circuit_error_locations[0].flipped_measurement.record_index + 1 )DOC") .data()); @@ -488,6 +544,15 @@ void stim_pybind::pybind_flipped_measurement_methods( Returns the observable of the flipped measurement. For example, an `MX 5` measurement will have the observable X5. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... M(0.25) 1 10 + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> err[0].circuit_error_locations[0].flipped_measurement.observable + [stim.GateTargetWithCoords(stim.target_z(10), [])] )DOC") .data()); @@ -561,6 +626,19 @@ void stim_pybind::pybind_circuit_targets_inside_instruction_methods( clean_doc_string(R"DOC( Returns the name of the gate / instruction that was being executed. @signature def gate(self) -> Optional[str]: + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... R 0 1 + ... X_ERROR(0.25) 0 1 + ... M 0 1 + ... DETECTOR(2, 3) rec[-1] rec[-2] + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> loc: stim.CircuitErrorLocation = err[0].circuit_error_locations[0] + >>> loc.instruction_targets.gate + 'X_ERROR' )DOC") .data()); @@ -570,6 +648,21 @@ void stim_pybind::pybind_circuit_targets_inside_instruction_methods( clean_doc_string(R"DOC( Returns the inclusive start of the range of targets that were executing within the gate / instruction. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... R 0 1 + ... X_ERROR(0.25) 0 1 + ... M 0 1 + ... DETECTOR(2, 3) rec[-1] rec[-2] + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> loc: stim.CircuitErrorLocation = err[0].circuit_error_locations[0] + >>> loc.instruction_targets.target_range_start + 0 + >>> loc.instruction_targets.target_range_end + 1 )DOC") .data()); @@ -579,6 +672,21 @@ void stim_pybind::pybind_circuit_targets_inside_instruction_methods( clean_doc_string(R"DOC( Returns the exclusive end of the range of targets that were executing within the gate / instruction. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... R 0 1 + ... X_ERROR(0.25) 0 1 + ... M 0 1 + ... DETECTOR(2, 3) rec[-1] rec[-2] + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> loc: stim.CircuitErrorLocation = err[0].circuit_error_locations[0] + >>> loc.instruction_targets.target_range_start + 0 + >>> loc.instruction_targets.target_range_end + 1 )DOC") .data()); @@ -587,6 +695,19 @@ void stim_pybind::pybind_circuit_targets_inside_instruction_methods( &CircuitTargetsInsideInstruction::args, clean_doc_string(R"DOC( Returns parens arguments of the gate / instruction that was being executed. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... R 0 1 + ... X_ERROR(0.25) 0 1 + ... M 0 1 + ... DETECTOR(2, 3) rec[-1] rec[-2] + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> loc: stim.CircuitErrorLocation = err[0].circuit_error_locations[0] + >>> loc.instruction_targets.args + [0.25] )DOC") .data()); @@ -597,6 +718,19 @@ void stim_pybind::pybind_circuit_targets_inside_instruction_methods( Returns the subset of targets of the gate/instruction that were being executed. Includes coordinate data with the targets. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... R 0 1 + ... X_ERROR(0.25) 0 1 + ... M 0 1 + ... DETECTOR(2, 3) rec[-1] rec[-2] + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> loc: stim.CircuitErrorLocation = err[0].circuit_error_locations[0] + >>> loc.instruction_targets.targets_in_range + [stim.GateTargetWithCoords(0, [])] )DOC") .data()); @@ -622,6 +756,16 @@ void stim_pybind::pybind_circuit_targets_inside_instruction_methods( pybind11::arg("targets_in_range"), clean_doc_string(R"DOC( Creates a stim.CircuitTargetsInsideInstruction. + + Examples: + >>> import stim + >>> val = stim.CircuitTargetsInsideInstruction( + ... gate='X_ERROR', + ... args=[0.25], + ... target_range_start=0, + ... target_range_end=1, + ... targets_in_range=[stim.GateTargetWithCoords(0, [])], + ... ) )DOC") .data()); c.def("__repr__", &CircuitTargetsInsideInstruction_repr); @@ -878,6 +1022,28 @@ pybind11::class_ stim_pybind::pybind_explained_error(pybind11::m "ExplainedError", clean_doc_string(R"DOC( Describes the location of an error mechanism from a stim circuit. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... R 0 + ... TICK + ... Y_ERROR(0.125) 0 + ... M 0 + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> print(err[0]) + ExplainedError { + dem_error_terms: L0 + CircuitErrorLocation { + flipped_pauli_product: Y0 + Circuit location stack trace: + (after 1 TICKs) + at instruction #3 (Y_ERROR) in the circuit + at target #1 of the instruction + resolving to Y_ERROR(0.125) 0 + } + } )DOC") .data()); } @@ -903,6 +1069,25 @@ void stim_pybind::pybind_explained_error_methods(pybind11::module &m, pybind11:: Note: if this list is empty, it may be because there was a DEM error decomposed into parts where one of the parts is impossible to make on its own from a single circuit error. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... R 0 + ... TICK + ... Y_ERROR(0.125) 0 + ... M 0 + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> print(err[0].circuit_error_locations[0]) + CircuitErrorLocation { + flipped_pauli_product: Y0 + Circuit location stack trace: + (after 1 TICKs) + at instruction #3 (Y_ERROR) in the circuit + at target #1 of the instruction + resolving to Y_ERROR(0.125) 0 + } )DOC") .data()); @@ -928,6 +1113,28 @@ void stim_pybind::pybind_explained_error_methods(pybind11::module &m, pybind11:: pybind11::arg("circuit_error_locations"), clean_doc_string(R"DOC( Creates a stim.ExplainedError. + + Examples: + >>> import stim + >>> err = stim.Circuit(''' + ... R 0 + ... TICK + ... Y_ERROR(0.125) 0 + ... M 0 + ... OBSERVABLE_INCLUDE(0) rec[-1] + ... ''').shortest_graphlike_error() + >>> print(err[0]) + ExplainedError { + dem_error_terms: L0 + CircuitErrorLocation { + flipped_pauli_product: Y0 + Circuit location stack trace: + (after 1 TICKs) + at instruction #3 (Y_ERROR) in the circuit + at target #1 of the instruction + resolving to Y_ERROR(0.125) 0 + } + } )DOC") .data()); c.def("__repr__", &MatchedError_repr); diff --git a/src/stim/simulators/tableau_simulator.pybind.cc b/src/stim/simulators/tableau_simulator.pybind.cc index bd916a3d..e8eefbbc 100644 --- a/src/stim/simulators/tableau_simulator.pybind.cc +++ b/src/stim/simulators/tableau_simulator.pybind.cc @@ -1,17 +1,3 @@ -// 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. - #include "stim/simulators/tableau_simulator.pybind.h" #include "stim/circuit/circuit_instruction.pybind.h" @@ -20,7 +6,6 @@ #include "stim/simulators/tableau_simulator.h" #include "stim/stabilizers/pauli_string.pybind.h" #include "stim/stabilizers/tableau.h" -#include "stim/util_bot/probability_util.h" #include "stim/util_bot/str_util.h" #include "stim/util_top/circuit_vs_amplitudes.h" #include "stim/util_top/stabilizers_to_tableau.h" @@ -575,6 +560,18 @@ void stim_pybind::pybind_tableau_simulator_methods( Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.h(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +Z -Y +X )DOC") .data()); @@ -597,6 +594,11 @@ void stim_pybind::pybind_tableau_simulator_methods( *targets: The indices of the qubits to target with the noise. p: The chance of the error being applied, independently, to each qubit. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.depolarize1(0, 1, 2, p=0.01) )DOC") .data()); @@ -620,6 +622,11 @@ void stim_pybind::pybind_tableau_simulator_methods( zip(targets[::1], targets[1::2]). p: The chance of the error being applied, independently, to each qubit pair. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.depolarize1(0, 1, 4, 5, p=0.01) )DOC") .data()); @@ -642,6 +649,11 @@ void stim_pybind::pybind_tableau_simulator_methods( *targets: The indices of the qubits to target with the noise. p: The chance of the X error being applied, independently, to each qubit. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.x_error(0, 1, 2, p=0.01) )DOC") .data()); @@ -663,6 +675,11 @@ void stim_pybind::pybind_tableau_simulator_methods( *targets: The indices of the qubits to target with the noise. p: The chance of the Y error being applied, independently, to each qubit. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.y_error(0, 1, 2, p=0.01) )DOC") .data()); @@ -684,6 +701,11 @@ void stim_pybind::pybind_tableau_simulator_methods( *targets: The indices of the qubits to target with the noise. p: The chance of the Z error being applied, independently, to each qubit. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.z_error(0, 1, 2, p=0.01) )DOC") .data()); @@ -697,6 +719,18 @@ void stim_pybind::pybind_tableau_simulator_methods( Args: *targets: The indices of the qubits to target with the gate. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.reset_x(0) + >>> s.reset_y(1) + + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +X +Y +Z + >>> s.h_xz(0, 1, 2) + >>> print(" ".join(str(s.peek_bloch(k)) for k in range(3))) + +Z -Y +X )DOC") .data()); @@ -1886,6 +1920,15 @@ void stim_pybind::pybind_tableau_simulator_methods( Returns: The measurement result as a bool. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.x(1) + >>> s.measure(0) + False + >>> s.measure(1) + True )DOC") .data()); @@ -1906,6 +1949,13 @@ void stim_pybind::pybind_tableau_simulator_methods( Returns: The measurement results as a list of bools. + + Examples: + >>> import stim + >>> s = stim.TableauSimulator() + >>> s.x(1) + >>> s.measure_many(0, 1) + [False, True] )DOC") .data());