pymatching 0.1.0

Safe Rust bindings for the PyMatching quantum error-correction decoder
Documentation
use std::str::FromStr;

use ndarray::{array, Array1};
use pymatching::{DecodeOptions, Matching};

fn assert_gap_is_valid(matching: &Matching, syndrome: &Array1<u8>) {
    let soft = matching.decode_gap(syndrome.view()).unwrap();

    assert_eq!(soft.gaps.len(), soft.prediction.len());
    assert!(soft.prediction.iter().all(|bit| *bit <= 1));
    assert!(soft.gaps.iter().all(|gap| gap.is_finite() && *gap >= 0.0));
}

#[test]
fn gap_is_inferred_for_every_observable_without_basis_metadata() {
    let dem = stim::DetectorErrorModel::from_str(
        "error(0.05) D0 L0 ^ D2 L1\n\
         error(0.1) D0 D1\n\
         error(0.2) D1\n\
         error(0.1) D2 D3\n\
         error(0.2) D3\n",
    )
    .unwrap();
    for enable_correlations in [false, true] {
        let matching =
            Matching::from_detector_error_model_with_options(&dem, enable_correlations).unwrap();
        let empty = matching.decode_gap(Array1::zeros(4).view()).unwrap();
        let correlated_error = matching
            .decode_gap(Array1::from_vec(vec![1, 0, 1, 0]).view())
            .unwrap();

        assert_eq!(empty.prediction.to_vec(), vec![0, 0]);
        assert_eq!(correlated_error.prediction.to_vec(), vec![1, 1]);
    }
}

#[test]
fn gap_batch_matches_single_shots_with_and_without_correlations() {
    let dem = stim::DetectorErrorModel::from_str(
        "error(0.05) D0 L0 ^ D2 L1\n\
         error(0.1) D0 D1\n\
         error(0.2) D1\n\
         error(0.1) D2 D3\n\
         error(0.2) D3\n",
    )
    .unwrap();
    let shots = array![[0_u8, 0, 0, 0], [1, 0, 1, 0], [0, 1, 0, 1], [0, 0, 0, 0]];

    for enable_correlations in [false, true] {
        let matching =
            Matching::from_detector_error_model_with_options(&dem, enable_correlations).unwrap();
        let batch = matching.decode_gap_batch(shots.view()).unwrap();

        assert_eq!(batch.predictions.dim(), (shots.nrows(), 2));
        assert_eq!(batch.gaps.dim(), batch.predictions.dim());
        for (row_index, syndrome) in shots.outer_iter().enumerate() {
            let single = matching.decode_gap(syndrome).unwrap();
            assert_eq!(batch.predictions.row(row_index), single.prediction.view());
            assert_eq!(batch.gaps.row(row_index), single.gaps.view());
        }
    }
}

#[test]
fn gap_inference_handles_rotated_x_and_z_memory_graphs() {
    for task in [
        "surface_code:rotated_memory_x",
        "surface_code:rotated_memory_z",
    ] {
        let circuit = stim::Circuit::generated_with_noise(task, 3, 3, 0.01, 0.0, 0.0, 0.0).unwrap();
        let dem = circuit
            .detector_error_model_with_options(true, true, false, 0.0, false, false)
            .unwrap();
        for enable_correlations in [false, true] {
            let matching =
                Matching::from_detector_error_model_with_options(&dem, enable_correlations)
                    .unwrap();
            assert_gap_is_valid(&matching, &Array1::zeros(matching.num_detectors()));
            let mut sampler = dem.compile_sampler_with_seed(7);
            let (detectors, _, _) = sampler.sample(16);
            for row in detectors.outer_iter() {
                let syndrome = Array1::from_iter(row.iter().map(|bit| u8::from(*bit)));
                assert_gap_is_valid(&matching, &syndrome);
            }
        }
    }
}

#[test]
fn gap_preserves_the_hard_decoder_prediction() {
    for task in [
        "surface_code:rotated_memory_x",
        "surface_code:rotated_memory_z",
    ] {
        let circuit =
            stim::Circuit::generated_with_noise(task, 3, 3, 0.01, 0.01, 0.01, 0.01).unwrap();
        let dem = circuit
            .detector_error_model_with_options(true, true, false, 0.0, false, false)
            .unwrap();
        let mut sampler = dem.compile_sampler_with_seed(7);
        let (detectors, _, _) = sampler.sample(512);

        for enable_correlations in [false, true] {
            let matching =
                Matching::from_detector_error_model_with_options(&dem, enable_correlations)
                    .unwrap();
            let options = DecodeOptions::new().with_enable_correlations(enable_correlations);
            for row in detectors.outer_iter() {
                let syndrome = Array1::from_iter(row.iter().map(|bit| u8::from(*bit)));
                let hard = matching
                    .decode_with_options(syndrome.view(), options)
                    .unwrap();
                let gap = matching.decode_gap(syndrome.view()).unwrap();

                assert_eq!(
                    gap.prediction, hard.prediction,
                    "{task}, correlations={enable_correlations}"
                );
            }
        }
    }
}

#[test]
fn gap_rejects_an_observable_that_is_not_a_graph_cut() {
    let dem = stim::DetectorErrorModel::from_str(
        "error(0.1) D0 L0\n\
         error(0.1) D0 D1\n\
         error(0.2) D1\n\
         error(0.15) D0 D1 L0\n",
    )
    .unwrap();
    let matching = Matching::from_detector_error_model_with_options(&dem, true).unwrap();
    let error = matching.decode_gap(Array1::zeros(2).view()).unwrap_err();

    assert!(error.to_string().contains("define a graph cut"));
}