From 3d25b50a1330f2de9ad065fedd32af6564868561 Mon Sep 17 00:00:00 2001
From: stefan <mail@s-holst.de>
Date: Sat, 27 Jun 2026 11:29:06 +0900
Subject: [PATCH] add docs and fix suprious detects in incremental

---
 README.md               | 9 +++++----
 src/fsim/incremental.py | 9 +++++++--
 src/fsim/simple.py      | 4 ++++
 3 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index e0235bc..d62a11a 100644
--- a/README.md
+++ b/README.md
@@ -40,13 +40,14 @@ Choose `uv-env` as kernel in Jupyter Lab.
 
 Numbers are given in `gfs/s` = `gates * faults * patterns / second`.
 
-`SAFSimSimple` on 1024 patterns (baseline):
+Single-core `SAFSimSimple` on 1024 patterns (baseline):
 
 | OS, CPU, RAM | `tests/c6288.bench` | `polito-itc99-b15-sky130` |
 |--------------|---------------------|---------------------------|
-| MacOS, M3 Max, 32GiB (Stefan)  | 1.52G | 1.97G |
-| WSL, i7-14650HX, 15GiB (Zhang) | 1.68G | 2.03G |
-
+| MacOS, M3 Max, 32GiB (Stefan)         | 1.52G | 1.97G |
+| WSL, i7-14650HX, 15GiB (Zhang)        | 1.68G | 2.03G |
+| Ubuntu, Xeon E5-1650, 251GiB (Nosaka) | 0.94G | 1.18G |
+| WSL2, ?, ? (Kawachi)                  | 0.82G | ?     |
 
 ## Notes
 
diff --git a/src/fsim/incremental.py b/src/fsim/incremental.py
index 18667d9..5b0c622 100644
--- a/src/fsim/incremental.py
+++ b/src/fsim/incremental.py
@@ -8,6 +8,10 @@ from kyupy.circuit import Circuit
 from kyupy.logic_sim import LogicSim2V
 
 class SAFSimIncremental:
+    """A stuck-at fault simulator that uses incremental simulation.
+
+    After priming the circuit with a batch of patterns, faults are injected and only the gates in its fan-out cone are re-simulated.
+    """
 
     def __init__(self, circuit_resolved: Circuit, batch_size: int):
         self.sim = LogicSim2V(circuit_resolved, sims=batch_size)
@@ -21,6 +25,7 @@ class SAFSimIncremental:
             fclass_DS = set()
             nbatches = cdiv(patterns.shape[1], self.sim.sims)
             nfaults = len(faults)
+            obs_mask = np.packbits(np.full(patterns.shape[1], 1, dtype=np.uint8), bitorder='little')[np.newaxis, np.newaxis]
 
         with self.timers['sim'], log.progress() as p:
             for bidx, (bo, bs) in enumerate(batchrange(patterns.shape[1], self.sim.sims)):
@@ -30,7 +35,7 @@ class SAFSimIncremental:
                 with self.timers['sim_full_prop']:
                     self.sim.c_prop()
                 c_golden[...] = self.sim.c
-                c_golden_poppo = c_golden[self.sim.poppo_c_locs]
+                c_golden_poppo = c_golden[self.sim.poppo_c_locs] & obs_mask
                 for fidx, fault in enumerate(faults):
                     fault_site = fault//2
                     fault_polarity = fault&1
@@ -38,7 +43,7 @@ class SAFSimIncremental:
                     with self.timers['sim_incr_prop']:
                         self.sim.c_prop(fault_line=fault_site, fault_model=fault_polarity)
                     with self.timers['sim_incr_eval']:
-                        if not np.all(c_golden_poppo == self.sim.c[self.sim.poppo_c_locs]):
+                        if not np.all(c_golden_poppo == (self.sim.c[self.sim.poppo_c_locs] & obs_mask)):
                             fclass_DS.add(fault)
                     with self.timers['sim_incr_reset']:
                         self.sim.c[...] = c_golden # clear fault
diff --git a/src/fsim/simple.py b/src/fsim/simple.py
index 4866f4d..1ee2b15 100644
--- a/src/fsim/simple.py
+++ b/src/fsim/simple.py
@@ -8,6 +8,10 @@ from kyupy.circuit import Circuit
 from kyupy.logic_sim import LogicSim2V
 
 class SAFSimSimple:
+    """A simple stuck-at fault simulator.
+
+    Simplest brute-force simulation of all given stuck-at faults.
+    """
 
     def __init__(self, circuit_resolved: Circuit, batch_size: int):
         self.sim = LogicSim2V(circuit_resolved, sims=batch_size)