sparkainlp-x · Sep 26, 2026 · Sep 26, 2026
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Jean-François Brisson, Spark AI NLP
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
diff --git a/README.md b/README.md
@@ -2,6 +2,32 @@
 
 [![C++ CI](https://github.com/sparkainlp-x/qldpc_decoder_cpp/actions/workflows/ci.yml/badge.svg)](https://github.com/sparkainlp-x/qldpc_decoder_cpp/actions/workflows/ci.yml)
 
+## English summary
+
+A C++/HLS **research scaffold** for a qLDPC decoder: CMake + Catch2 + a sparse GF(2) micro-benchmark, plus Vitis HLS / Vivado / PetaLinux scripts that target the AMD ZCU111 board. It uses Joschka Roffe's [`ldpc`](https://github.com/quantumgizmos/ldpc) library through CMake `FetchContent`. This is research software, not a hardware product and not a quantum-hardware result.
+
+### Evidence status
+
+| Item | Tag | Notes |
+|---|---|---|
+| Software build, Catch2 tests, smoke test | Runs in CI (GitHub-hosted) | |
+| GF(2) sparse mat-vec micro-benchmark, ~70 ns median | **REPORTED; host/conditions unspecified** | A single micro-operation on a synthetic 32×64 matrix. **Not** qLDPC decoding latency, **not** an FPGA or end-to-end figure. CPU, compiler, OS, and raw samples were not recorded |
+| HLS kernel (`hls/qldpc_kernel.cpp`) | Scaffold | No belief-propagation message updates yet |
+| HLS synthesis, 300/400 MHz timing | **TARGET / UNRUN** | Clock periods are set in TCL; no post-route timing report exists |
+| HIL benchmark on ZCU111, FER | **UNRUN** | Needs the board and a self-hosted runner. No run has been published |
+
+### Known limitations
+
+- **`verify_correction()` always returns `true`** (`hil/hil_benchmark.cpp`). Any HIL run would therefore report FER = 0 *by construction*. It must be replaced with a code-aware check (`H · correction = syndrome (mod 2)`, plus a logical-error check against a known injected error) before any FER figure is published.
+- The HLS kernel is an integration skeleton, not a complete BP/OSD decoder.
+- `docs/scientific_review.md` is an **AI-assisted internal review**, not independent peer review.
+
+A French description follows. / La description en français suit.
+
+---
+
+## Description (français)
+
 Exemple C++ minimal utilisant la bibliothèque [`ldpc`](https://github.com/quantumgizmos/ldpc) de Joschka Roffe via CMake `FetchContent`. La configuration active OpenMP ainsi que les optimisations processeur en mode non-MSVC.
 
 ## Prérequis
@@ -23,7 +49,7 @@ cmake --build build --parallel
 
 ## Benchmark de latence
 
-Le projet construit également `ldpc_benchmark`, qui mesure une multiplication matrice-vecteur sparse sur GF(2) après une phase d’échauffement. Il exécute 31 échantillons de 1 000 itérations, puis affiche la latence médiane et le 95e percentile en nanosecondes.
+Le projet construit également `ldpc_benchmark`, qui mesure une multiplication matrice-vecteur sparse sur GF(2) après une phase d’échauffement. Il exécute 31 échantillons de 1 000 itérations, puis affiche la latence médiane et le 95e percentile en nanosecondes. Les valeurs d'environ 70 ns observées jusqu'ici sont **REPORTED ; hôte/conditions non précisés** et concernent une micro-opération, pas le décodage qLDPC complet.
 
 ```bash
 ./build/ldpc_benchmark
@@ -67,7 +93,9 @@ Le workflow contient un job `hardware-bitstream-build` qui s’exécute uniqueme
 
 Le job matériel attend la réussite de `software-ci`, lance `make all`, puis publie les fichiers `.xsa`, `BOOT.BIN`, `image.ub` et `download.bit` comme artefacts GitHub Actions. Pour protéger la machine locale, il n’est pas déclenché par les pull requests : les changements doivent d’abord être fusionnés dans `main`, ou le workflow doit être lancé manuellement par un opérateur de confiance.
 
-## Test HIL automatisé
+## Test HIL automatisé (UNRUN)
+
+> **Statut : UNRUN.** Aucun test HIL n'a été exécuté ni publié. `verify_correction()` retourne toujours `true` (voir « Known limitations » ci-dessus) : tant qu'elle n'est pas remplacée, le FER rapporté vaut 0 par construction.
 
 Le benchmark [`hil/hil_benchmark.cpp`](./hil/hil_benchmark.cpp) exécute 100 000 transferts AXI-DMA/FPGA, mesure chaque aller-retour en nanosecondes, exporte `latencies_report.csv` et vérifie la latence maximale.
 

diff --git a/docs/linkedin_review.md b/docs/linkedin_review.md
diff --git a/docs/newsletter_quantum_edge.md b/docs/newsletter_quantum_edge.md
diff --git a/docs/quantum_magazine_feature.md b/docs/quantum_magazine_feature.md
diff --git a/docs/scientific_review.md b/docs/scientific_review.md
@@ -1,6 +1,6 @@
-# Scientific Review of `qldpc_decoder_cpp`
+# AI-assisted internal review of `qldpc_decoder_cpp`
 
-**External technical analysis — Manus AI**  
+**AI-assisted internal review (Manus AI), not independent peer review.** This text was generated with an AI tool at the owner's request. It has not been reviewed by an independent third party.  
 **Repository:** [sparkainlp-x/qldpc_decoder_cpp](https://github.com/sparkainlp-x/qldpc_decoder_cpp)
 
 ## Executive assessment
@@ -27,7 +27,7 @@ The project also contains a reproducible intent for timing closure. The 300 MHz
 
 ## Benchmark interpretation
 
-The reported software results are approximately 70–76 ns median and 81–87 ns at p95 for a sparse GF(2) operation on a synthetic 32×64 matrix. Those values support the claim that the selected software micro-operation is sub-microsecond on the tested host configuration. They do **not** establish a 70 ns qLDPC decoding latency, an FPGA latency, or an end-to-end host-to-FPGA latency.
+The reported software results are approximately 70–76 ns median and 81–87 ns at p95 for a sparse GF(2) operation on a synthetic 32×64 matrix (**REPORTED; host/conditions unspecified**: CPU model, compiler, OS, affinity, and raw samples were not recorded alongside these numbers). Those values support the claim that the selected software micro-operation is sub-microsecond on the tested host configuration. They do **not** establish a 70 ns qLDPC decoding latency, an FPGA latency, or an end-to-end host-to-FPGA latency.
 
 A publication-quality benchmark should report the processor model, compiler version, operating-system version, CPU affinity, number of repetitions, warm-up policy, clock source, raw samples, and confidence intervals. It should also compare the optimized implementation with a defined baseline. Without those controls, the numbers are useful engineering observations but not yet a portable performance claim.