Skip to content

Commit b2deab3

Browse files
StrilancStrilanc
committed
regen docs
1 parent 1cd2d58 commit b2deab3

File tree

2 files changed

+168
-0
lines changed

2 files changed

+168
-0
lines changed

‎doc/chromobius.pyi

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -162,6 +162,86 @@ class CompiledDecoder:
162162
>>> mistakes = np.count_nonzero(differences)
163163
>>> assert mistakes < shots / 5
164164
"""
165+
@staticmethod
166+
def predict_weighted_obs_flips_from_dets_bit_packed(
167+
dets: np.ndarray,
168+
) -> tuple[np.ndarray, np.ndarray]:
169+
"""Predicts observable flips and weights from detection events.
170+
171+
The returned weight comes directly from the underlying call to pymatching, not
172+
accounting for the lifting process.
173+
174+
Args:
175+
dets: A bit packed numpy array of detection event data. The array can either
176+
be 1-dimensional (a single shot to decode) or 2-dimensional (multiple
177+
shots to decode, with the first axis being the shot axis and the second
178+
axis being the detection event byte axis).
179+
180+
The array's dtype must be np.uint8. If you have an array of dtype
181+
np.bool_, you have data that's not bit packed. You can pack it by
182+
using `np.packbits(array, bitorder='little')`. But ideally you
183+
should attempt to never have unpacked data in the first place,
184+
since it's 8x larger which can be a large performance loss. For
185+
example, stim's sampler methods all have a `bit_packed=True` argument
186+
that cause them to return bit packed data.
187+
188+
Returns:
189+
A tuple (obs, weights).
190+
Obs is a bit packed numpy array of observable flip data.
191+
Weights is a numpy array (or scalar) of floats.
192+
193+
If dets is a 1D array, then the result has:
194+
obs.shape = (math.ceil(num_obs / 8),)
195+
obs.dtype = np.uint8
196+
weights.shape = ()
197+
weights.dtype = np.float32
198+
If dets is a 2D array, then the result has:
199+
shape = (dets.shape[0], math.ceil(num_obs / 8),)
200+
dtype = np.uint8
201+
weights.shape = (dets.shape[0],)
202+
weights.dtype = np.float32
203+
204+
To determine if the observable with index k was flipped in shot s, compute:
205+
`bool((obs[s, k // 8] >> (k % 8)) & 1)`
206+
207+
Example:
208+
>>> import stim
209+
>>> import chromobius
210+
>>> import numpy as np
211+
212+
>>> repetition_color_code = stim.Circuit('''
213+
... # Apply noise.
214+
... X_ERROR(0.1) 0 1 2 3 4 5 6 7
215+
... # Measure three-body stabilizers to catch errors.
216+
... MPP Z0*Z1*Z2 Z1*Z2*Z3 Z2*Z3*Z4 Z3*Z4*Z5 Z4*Z5*Z6 Z5*Z6*Z7
217+
...
218+
... # Annotate detectors, with a coloring in the 4th coordinate.
219+
... DETECTOR(0, 0, 0, 2) rec[-6]
220+
... DETECTOR(1, 0, 0, 0) rec[-5]
221+
... DETECTOR(2, 0, 0, 1) rec[-4]
222+
... DETECTOR(3, 0, 0, 2) rec[-3]
223+
... DETECTOR(4, 0, 0, 0) rec[-2]
224+
... DETECTOR(5, 0, 0, 1) rec[-1]
225+
...
226+
... # Check on the message.
227+
... M 0
228+
... OBSERVABLE_INCLUDE(0) rec[-1]
229+
... ''')
230+
231+
>>> # Sample the circuit.
232+
>>> shots = 4096
233+
>>> sampler = repetition_color_code.compile_detector_sampler()
234+
>>> dets, actual_obs_flips = sampler.sample(
235+
... shots=shots,
236+
... separate_observables=True,
237+
... bit_packed=True,
238+
... )
239+
240+
>>> # Decode with Chromobius.
241+
>>> dem = repetition_color_code.detector_error_model()
242+
>>> decoder = chromobius.compile_decoder_for_dem(dem)
243+
>>> pred, weights = decoder.predict_obs_flips_from_dets_bit_packed(dets)
244+
"""
165245
def compile_decoder_for_dem(
166246
dem: stim.DetectorErrorModel,
167247
) -> chromobius.CompiledDecoder:

‎doc/chromobius_api_reference.md

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
- [`chromobius.CompiledDecoder`](#chromobius.CompiledDecoder)
88
- [`chromobius.CompiledDecoder.from_dem`](#chromobius.CompiledDecoder.from_dem)
99
- [`chromobius.CompiledDecoder.predict_obs_flips_from_dets_bit_packed`](#chromobius.CompiledDecoder.predict_obs_flips_from_dets_bit_packed)
10+
- [`chromobius.CompiledDecoder.predict_weighted_obs_flips_from_dets_bit_packed`](#chromobius.CompiledDecoder.predict_weighted_obs_flips_from_dets_bit_packed)
1011
```python
1112
# Types used by the method definitions.
1213
from typing import overload, TYPE_CHECKING, Any, Dict, Iterable, List, Optional, Tuple, Union
@@ -266,3 +267,90 @@ def predict_obs_flips_from_dets_bit_packed(
266267
>>> assert mistakes < shots / 5
267268
"""
268269
```
270+
271+
<a name="chromobius.CompiledDecoder.predict_weighted_obs_flips_from_dets_bit_packed"></a>
272+
```python
273+
# chromobius.CompiledDecoder.predict_weighted_obs_flips_from_dets_bit_packed
274+
275+
# (in class chromobius.CompiledDecoder)
276+
@staticmethod
277+
def predict_weighted_obs_flips_from_dets_bit_packed(
278+
dets: np.ndarray,
279+
) -> tuple[np.ndarray, np.ndarray]:
280+
"""Predicts observable flips and weights from detection events.
281+
282+
The returned weight comes directly from the underlying call to pymatching, not
283+
accounting for the lifting process.
284+
285+
Args:
286+
dets: A bit packed numpy array of detection event data. The array can either
287+
be 1-dimensional (a single shot to decode) or 2-dimensional (multiple
288+
shots to decode, with the first axis being the shot axis and the second
289+
axis being the detection event byte axis).
290+
291+
The array's dtype must be np.uint8. If you have an array of dtype
292+
np.bool_, you have data that's not bit packed. You can pack it by
293+
using `np.packbits(array, bitorder='little')`. But ideally you
294+
should attempt to never have unpacked data in the first place,
295+
since it's 8x larger which can be a large performance loss. For
296+
example, stim's sampler methods all have a `bit_packed=True` argument
297+
that cause them to return bit packed data.
298+
299+
Returns:
300+
A tuple (obs, weights).
301+
Obs is a bit packed numpy array of observable flip data.
302+
Weights is a numpy array (or scalar) of floats.
303+
304+
If dets is a 1D array, then the result has:
305+
obs.shape = (math.ceil(num_obs / 8),)
306+
obs.dtype = np.uint8
307+
weights.shape = ()
308+
weights.dtype = np.float32
309+
If dets is a 2D array, then the result has:
310+
shape = (dets.shape[0], math.ceil(num_obs / 8),)
311+
dtype = np.uint8
312+
weights.shape = (dets.shape[0],)
313+
weights.dtype = np.float32
314+
315+
To determine if the observable with index k was flipped in shot s, compute:
316+
`bool((obs[s, k // 8] >> (k % 8)) & 1)`
317+
318+
Example:
319+
>>> import stim
320+
>>> import chromobius
321+
>>> import numpy as np
322+
323+
>>> repetition_color_code = stim.Circuit('''
324+
... # Apply noise.
325+
... X_ERROR(0.1) 0 1 2 3 4 5 6 7
326+
... # Measure three-body stabilizers to catch errors.
327+
... MPP Z0*Z1*Z2 Z1*Z2*Z3 Z2*Z3*Z4 Z3*Z4*Z5 Z4*Z5*Z6 Z5*Z6*Z7
328+
...
329+
... # Annotate detectors, with a coloring in the 4th coordinate.
330+
... DETECTOR(0, 0, 0, 2) rec[-6]
331+
... DETECTOR(1, 0, 0, 0) rec[-5]
332+
... DETECTOR(2, 0, 0, 1) rec[-4]
333+
... DETECTOR(3, 0, 0, 2) rec[-3]
334+
... DETECTOR(4, 0, 0, 0) rec[-2]
335+
... DETECTOR(5, 0, 0, 1) rec[-1]
336+
...
337+
... # Check on the message.
338+
... M 0
339+
... OBSERVABLE_INCLUDE(0) rec[-1]
340+
... ''')
341+
342+
>>> # Sample the circuit.
343+
>>> shots = 4096
344+
>>> sampler = repetition_color_code.compile_detector_sampler()
345+
>>> dets, actual_obs_flips = sampler.sample(
346+
... shots=shots,
347+
... separate_observables=True,
348+
... bit_packed=True,
349+
... )
350+
351+
>>> # Decode with Chromobius.
352+
>>> dem = repetition_color_code.detector_error_model()
353+
>>> decoder = chromobius.compile_decoder_for_dem(dem)
354+
>>> pred, weights = decoder.predict_obs_flips_from_dets_bit_packed(dets)
355+
"""
356+
```

0 commit comments

Comments
 (0)