Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add some instruction utility methods #833

Merged
merged 2 commits into from
Sep 21, 2024
Merged

Add some instruction utility methods #833

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
23776a4
Add some instruction utility methods
Strilanc Sep 21, 2024
b21e6e8
Check for loops
Strilanc Sep 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
130 changes: 123 additions & 7 deletions doc/python_api_reference_vDev.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,7 @@ API references for stable versions are kept on the [stim github wiki](https://gi
- [`stim.CircuitRepeatBlock.__repr__`](#stim.CircuitRepeatBlock.__repr__)
- [`stim.CircuitRepeatBlock.body_copy`](#stim.CircuitRepeatBlock.body_copy)
- [`stim.CircuitRepeatBlock.name`](#stim.CircuitRepeatBlock.name)
- [`stim.CircuitRepeatBlock.num_measurements`](#stim.CircuitRepeatBlock.num_measurements)
- [`stim.CircuitRepeatBlock.repeat_count`](#stim.CircuitRepeatBlock.repeat_count)
- [`stim.CircuitTargetsInsideInstruction`](#stim.CircuitTargetsInsideInstruction)
- [`stim.CircuitTargetsInsideInstruction.__init__`](#stim.CircuitTargetsInsideInstruction.__init__)
Expand Down Expand Up @@ -3762,6 +3763,30 @@ class CircuitErrorLocationStackFrame:
The full location of an instruction is a list of these frames,
drilling down from the top level circuit to the inner-most loop
that the instruction is within.


Examples:
>>> import stim
>>> err = stim.Circuit('''
... REPEAT 5 {
... R 0
... Y_ERROR(0.125) 0
... M 0
... }
... OBSERVABLE_INCLUDE(0) rec[-1]
... ''').shortest_graphlike_error()
>>> err[0].circuit_error_locations[0].stack_frames[0]
stim.CircuitErrorLocationStackFrame(
instruction_offset=0,
iteration_index=0,
instruction_repetitions_arg=5,
)
>>> err[0].circuit_error_locations[0].stack_frames[1]
stim.CircuitErrorLocationStackFrame(
instruction_offset=1,
iteration_index=4,
instruction_repetitions_arg=0,
)
"""
```

Expand All @@ -3778,6 +3803,14 @@ def __init__(
instruction_repetitions_arg: int,
) -> None:
"""Creates a stim.CircuitErrorLocationStackFrame.

Examples:
>>> import stim
>>> frame = stim.CircuitErrorLocationStackFrame(
... instruction_offset=1,
... iteration_index=2,
... instruction_repetitions_arg=3,
... )
"""
```

Expand All @@ -3795,6 +3828,18 @@ def instruction_offset(
from the line number, because blank lines and commented lines
don't count and also because the offset of the first instruction
is 0 instead of 1.

Examples:
>>> import stim
>>> err = stim.Circuit('''
... R 0
... TICK
... Y_ERROR(0.125) 0
... M 0
... OBSERVABLE_INCLUDE(0) rec[-1]
... ''').shortest_graphlike_error()
>>> err[0].circuit_error_locations[0].stack_frames[0].instruction_offset
2
"""
```

Expand All @@ -3810,6 +3855,23 @@ def instruction_repetitions_arg(
"""If the instruction being referred to is a REPEAT block,
this is the repetition count of that REPEAT block. Otherwise
this field defaults to 0.

Examples:
>>> import stim
>>> err = stim.Circuit('''
... REPEAT 5 {
... R 0
... Y_ERROR(0.125) 0
... M 0
... }
... OBSERVABLE_INCLUDE(0) rec[-1]
... ''').shortest_graphlike_error()
>>> full = err[0].circuit_error_locations[0].stack_frames[0]
>>> loop = err[0].circuit_error_locations[0].stack_frames[1]
>>> full.instruction_repetitions_arg
5
>>> loop.instruction_repetitions_arg
0
"""
```

Expand All @@ -3825,6 +3887,23 @@ def iteration_index(
"""Disambiguates which iteration of the loop containing this instruction
is being referred to. If the instruction isn't in a REPEAT block, this
field defaults to 0.

Examples:
>>> import stim
>>> err = stim.Circuit('''
... REPEAT 5 {
... R 0
... Y_ERROR(0.125) 0
... M 0
... }
... OBSERVABLE_INCLUDE(0) rec[-1]
... ''').shortest_graphlike_error()
>>> full = err[0].circuit_error_locations[0].stack_frames[0]
>>> loop = err[0].circuit_error_locations[0].stack_frames[1]
>>> full.iteration_index
0
>>> loop.iteration_index
4
"""
```

Expand Down Expand Up @@ -3873,19 +3952,30 @@ def __eq__(
def __init__(
self,
name: str,
targets: List[object],
gate_args: List[float] = (),
targets: Optional[Iterable[Union[int, stim.GateTarget]]] = None,
gate_args: Optional[Iterable[float]] = None,
) -> None:
"""Initializes a `stim.CircuitInstruction`.
"""Creates or parses a `stim.CircuitInstruction`.

Args:
name: The name of the instruction being applied.
If `targets` and `gate_args` aren't specified, this can be a full
instruction line from a stim Circuit file, like "CX 0 1".
targets: The targets the instruction is being applied to. These can be raw
values like `0` and `stim.target_rec(-1)`, or instances of
`stim.GateTarget`.
gate_args: The sequence of numeric arguments parameterizing a gate. For
noise gates this is their probabilities. For `OBSERVABLE_INCLUDE`
instructions it's the index of the logical observable to affect.

Examples:
>>> import stim

>>> print(stim.CircuitInstruction('DEPOLARIZE1', [5], [0.25]))
DEPOLARIZE1(0.25) 5

>>> stim.CircuitInstruction('CX rec[-1] 5 # comment')
stim.CircuitInstruction('CX', [stim.target_rec(-1), stim.GateTarget(5)], [])
"""
```

Expand Down Expand Up @@ -3989,7 +4079,7 @@ def num_measurements(
3
>>> stim.Circuit('MPP X0*X1 X0*Z1*Y2')[0].num_measurements
2
>>> stim.CircuitInstruction('HERALDED_ERASE', [0]).num_measurements
>>> stim.CircuitInstruction('HERALDED_ERASE', [0], [0.25]).num_measurements
1
"""
```
Expand Down Expand Up @@ -4207,6 +4297,27 @@ def name(
"""
```

<a name="stim.CircuitRepeatBlock.num_measurements"></a>
```python
# stim.CircuitRepeatBlock.num_measurements

# (in class stim.CircuitRepeatBlock)
@property
def num_measurements(
self,
) -> int:
"""Returns the number of bits produced when running this loop.

Examples:
>>> import stim
>>> stim.CircuitRepeatBlock(
... body=stim.Circuit("M 0 1"),
... repeat_count=25,
... ).num_measurements
50
"""
```

<a name="stim.CircuitRepeatBlock.repeat_count"></a>
```python
# stim.CircuitRepeatBlock.repeat_count
Expand Down Expand Up @@ -5336,13 +5447,15 @@ def __eq__(
def __init__(
self,
type: str,
args: List[float],
targets: List[object],
args: Optional[Iterable[float]] = None,
targets: Optional[Iterable[stim.DemTarget]] = None,
) -> None:
"""Creates a stim.DemInstruction.
"""Creates or parses a stim.DemInstruction.

Args:
type: The name of the instruction type (e.g. "error" or "shift_detectors").
If `args` and `targets` aren't specified, this can also be set to a
full line of text from a dem file, like "error(0.25) D0".
args: Numeric values parameterizing the instruction (e.g. the 0.1 in
"error(0.1)").
targets: The objects the instruction involves (e.g. the "D0" and "L1" in
Expand All @@ -5356,6 +5469,9 @@ def __init__(
... [stim.target_relative_detector_id(5)])
>>> print(instruction)
error(0.125) D5

>>> print(stim.DemInstruction('error(0.125) D5 L6 ^ D4 # comment'))
error(0.125) D5 L6 ^ D4
"""
```

Expand Down
Loading
Loading