Deterministic reference sample

[rafaelha]

Tsim currently supports detector/observable reference samples using the use_X_reference_sample in CompiledDetectorSampler.sample.

We should consider making these samples deterministic. For example, Stim biases all reference samples towards +Z

    def reference_sample(
        self,
        *,
        bit_packed: bool = False,
    ) -> np.ndarray:
        """Samples the given circuit in a deterministic fashion.

        Discards all noisy operations, and biases all collapse events
        towards +Z instead of randomly +Z/-Z.

        Args:
            bit_packed: Defaults to False. Determines whether the output numpy arrays
                use dtype=bool_ or dtype=uint8 with 8 bools packed into each byte.

        Returns:
            A numpy array containing the reference sample.

            if bit_packed:
                shape == (math.ceil(num_measurements / 8),)
                dtype == np.uint8
            else:
                shape == (num_measurements,)
                dtype == np.bool_

        Examples:
            >>> import stim
            >>> stim.Circuit('''
            ...     X 1
            ...     M 0 1
            ... ''').reference_sample()
            array([False,  True])
        """