update the readme

Author: LalehB

README.md

@@ -1,40 +1,32 @@
 # Tesseract Decoder
 
-A most-likely-error decoder for quantum error correction
+A Search-Based Decoder for Quantum Error Correction
 
 [![Licensed under the Apache 2.0 open-source
 license](https://img.shields.io/badge/License-Apache%202.0-3c60b1.svg?logo=opensourceinitiative&logoColor=white&style=flat-square)](https://github.com/quantumlib/tesseract-decoder/blob/main/LICENSE)
 
-## Introduction
-
-The implementation of [quantum error
-correction](https://en.wikipedia.org/wiki/Quantum_error_correction) (QEC)
-requires fast and accurate decoders to achieve low logical error rates. Decoding
-is an NP-hard optimization problem in the worst case, but there exists a variety
-of partial solutions for specific error-correcting codes. The Tesseract Decoder
-takes a novel approach: rather than building an algorithm with a polynomial
-runtime and using heuristics to make it more accurate, we begin with an
-exponential-time algorithm that always identifies the most likely error and use
-heuristics to make it faster. The decoder uses [A*
-search](https://en.wikipedia.org/wiki/A*_search_algorithm) along with a variety
-of pruning heuristics.
+## Overview
+
+Tesseract is a Most Likely Error decoder designed for Low Density Parity Check (LDPC) quantum error-correcting codes. It employs the A\* search algorithm to efficiently navigate the exponentially large graph of possible error subsets, identifying the most likely error configuration consistent with the observed syndrome. Tesseract leverages several pruning heuristics and manifold orientation techniques to achieve significant speed improvements over traditional integer programming-based decoders, while maintaining comparable accuracy at moderate physical error rates.
+
 We tested the Tesseract decoder for:
 
 -   Surface codes
--   Superdense Color codes
+-   Color codes
 -   Bivariate-bicycle codes
 -   Transversal CNOT protocols for surface codes
+Stim circuits for these protocols are stored in `testdata/`.
 
 ## Features
 
-
--   **A\* search:** deploys A* search while running a semi Dijkstra algorithm with early stop for high performance.
--   **Stim and DEM Support:** Processes Stim circuit files and Detector Error Model (DEM) files for comprehensive error decoding.
+-   **A\* search:** deploys A* search while running a Dijkstra algorithm with early stop for high performance.
+-   **Stim and DEM Support:** Processes Stim circuit files and Detector Error Model (DEM) files with arbitrary error models.
 -   **Parallel Decoding:** Utilizes multi-threading to accelerate the decoding process, making it suitable for large-scale simulations.
 -   **Efficient Beam Search:** Implements a beam search algorithm to minimize decoding cost and enhance efficiency.
 -   **Sampling and Shot Range Processing:** Supports sampling shots from circuits and processing specific ranges of shots for flexible experiment setups.
 -   **Detailed Statistics:** Provides comprehensive statistics output, including shot counts, error counts, and processing times.
-- **Heuristics**: Includes heuristics such as beam climbing and at most two errors per detector to improve performance.
+- **Heuristics**: Includes flexible heuristic options: `--beam, --det-penalty, --beam-climbing, --no-revisit-dets, --at-most-two-errors-per-detector` and `--pqlimit` to improve performance while maintaining a low logical error rate. To learn more about these options, use `./bazel-bin/tesseract/tesseract --help`
+
 
 ## Installation
 
@@ -58,7 +50,7 @@ The tesseract_main.cc file provides the main entry point for the Tesseract decod
 Basic Usage:
 
  ```bash 
-./tesseract --circuit <circuit_file> --out <output_file>
+./tesseract --circuit <circuit_file.stim> --sample-num-shots <N> --print-stats
 ```
 Example with Advanced Options:
 
@@ -77,12 +69,11 @@ Example with Advanced Options:
   --shot-range-begin 582 \
   --shot-range-end 583
 ```
-
 ### Example Usage
 
 Sampling Shots from a Circuit
 ```bash 
-./tesseract --circuit surface_code.stim --sample-num-shots 1000 --out sampled_results.txt
+./tesseract --circuit surface_code.stim --sample-num-shots 1000 --out predictions.01 --out-format 01
 ```
 Using a Detection Event File
 ```bash 
@@ -92,9 +83,9 @@ Using a Detection Event File and Observable Flips
 ```bash 
 ./tesseract --in events.01 --in-format 01 --obs_in obs.01 --obs-in-format 01 --dem surface_code.dem --out decoded.txt
 ```
-
+Tesseract supports reading and writing from all of Stim's standard output formats (see https://github.com/quantumlib/Stim/blob/main/doc/result_formats.md).
 ### Performance Optimization
-* Parallelism: Increase ```--threads``` to leverage multi-core processors for faster decoding.
+* Parallelism over shots: Increase ```--threads``` to leverage multi-core processors for faster decoding.
 * Beam Search: Use ```--beam``` to control the trade-off between accuracy and speed. Smaller beam sizes result in faster decoding but potentially lower accuracy.
 * Beam Climbing: Enable ```--beam-climbing``` for enhanced cost-based decoding.
 * At most two errors per detector: Enable ```--at-most-two-errors-per-detector``` to improve performance.
@@ -106,9 +97,6 @@ Using a Detection Event File and Observable Flips
 * Statistics output: Includes number of shots, errors, low confidence shots, and processing time.
 
 
-<!-- ## Installation -->
-
-<!-- ## Usage -->
 
 <!-- ## Citing Tesseract Decoder<a name="how-to-cite-tesseract"> -->