FPGA EOFM measurement and recovery reproducibility artifact

This repository contains the released FPGA EOFM measurements, annotations, ground-truth references, and recovery code used to study memory and staging structures testbed. The artifact supports a direct traceability chain from optical measurement to decoded digital state and, for the recovery experiments, from the decoded state to the reported numerical results.

1. Experimental setup

• Board / device: Digilent Genesys 2 development board with an AMD/Xilinx Kintex-7 XC7K325T-2FFG900C FPGA
• FPGA technology: 28 nm, flip-chip package
• Core supply voltage: 1.0 V
• Clock frequency: 200 MHz
• EOFM modulation frequency: 12.5 MHz
  • Generated by alternating a target data value with an all-zero value of matching width every 16 clock cycles at 200 MHz
• Optical setup: Hamamatsu PHEMOS-X FA microscope
• Objective: 50× / 0.76 NA
• Optical zoom: FF EOFM used 50× objective + 2× optical zoom; the 8-bit and 16-bit BRAM experiments used 50× objective + 4× optical zoom
• Scan settings: raster scan of the selected region; reflected optical signal was measured by the photodetector and processed by the spectrum analyzer to form a frequency-selective spatial map
• Pixel dwell / scan speed: 0.33 ms/pixel
• Vivado version: Vivado 2023

2. Design context and measurement principle

• Design type: systolic-array matrix multiplier with BRAM and register boundaries retained to represent memory and staging structures
• Input data width: signed 8-bit
• Output data width: signed 17-bit
• Operating clock: 200 MHz
• Matrix computation latency: 16 clock cycles

At each target bit position, the design alternates the intended value with an all-zero value of matching width once every 16 cycles: 8-bit targets use 0x00, while 16-bit targets use 0x0000. This creates a 12.5 MHz modulation component. The EOFM map isolates active bit locations at that modulation frequency. A bright / active physical location is decoded as logic 1; its absence is decoded as logic 0.

3. Repository organization

artifact/
├── original images/       raw TIFF EOFM measurements
├── annotation images/     annotated image overlays
├── ground truth/          reference images and decoding-workflow animation
├── recovery_artifact/     code and inputs for the three recovery experiments
│   ├── input/             supplied Figure 5 measurement and decoded states
│   ├── reference/         immutable numeric reference hashes/statistics
│   ├── src/               decoder and exact experiment implementations
│   ├── results/           regenerated CSV/JSON outputs
│   ├── reproduce_all.py
│   ├── reproduce_experiment1.py
│   ├── reproduce_experiment2.py
│   ├── reproduce_experiment3.py
│   ├── verify_artifact.py
│   ├── METADATA.json
│   ├── requirements.txt
│   └── ARTIFACT_MANIFEST.md
└── README.md

The released image files are organized by pattern family rather than by isolated image labels.

• 8-bit patterns: 0x11, 0x22, 0x44, 0x66, 0x88, 0xAA, 0xFF
• 16-bit BRAM patterns: 0x1111, 0x2222, 0x4444, 0x8888, 0xFFFF
• Annotation files represent the same pattern family with visual overlays and are not independent measurements.

Representative files include:

• original images/fig_3_EOFM_ff_11.tif
• original images/fig_4_EOFM_BRAM_11.tif
• original images/fig_5_BRAM16_88_11.tif
• Annotation images/fig_4_EOFM_BRAM_8_annotated_11.png
• Annotation images/fig_5_EOFM_BRAM_16_annotated.png
• ground truth/annotation_example_bram.gif

4. Image review and direct decoding workflow

For a released EOFM image:

1. Inspect the image and localize active ROIs in the EOFM map.
2. Use the annotation or reference overlay to map each ROI to its corresponding physical bit location.
3. Convert the mapped locations into bit states, where an active bit location is 1 and its absence is 0.
4. Compare the decoded state with the expected ground truth for that pattern family.

Example: 0x11 BRAM-8 panel

• Source image: original images/fig_4_EOFM_BRAM_11.tif
• Annotation helper: Annotation images/fig_4_EOFM_BRAM_8_annotated_11.png
• Reference overlay: ground truth/fig_4_EOFM_BRAM_11.png
• Expected ground truth: 0x11
• Binary interpretation: 00010001
• Alternating reference: 0x11 <-> 0x00

The traceability chain for this direct-readout example is:

raw EOFM image -> annotation / reference overlay -> physical bit locations -> decoded bit state -> ground-truth check

Animated workflow example

The following GIF illustrates the BRAM-8 decoding workflow for the 0x11 case:

5. Measurement metadata by image family

The following table records the acquisition metadata for each raw image family. The programmed pattern is shown at the target width; the alternating reference is the all-zero value of matching width. Annotations and reference overlays are stored separately in Annotation images/ and ground truth/.

File	Modality	Target	Width	Programmed pattern	Reference	Output	Clock	Modulation	Objective	Zoom	Dwell	Vcore
original images/fig_3_EOFM_ff_*.tif	EOFM	FF input/output	8/17	0x11, 0x66, 0xAA, 0xFF	0x00	0x00011, 0x00066, 0x1FFAA, 0x1FFFF	200 MHz	12.5 MHz	50×/0.76 NA	2×	0.33 ms/pixel	1.0 V
original images/fig_4_EOFM_BRAM_*.tif	EOFM	BRAM output	8	0x11, 0x22, 0xAA, 0xFF	0x00	N/A	200 MHz	12.5 MHz	50×/0.76 NA	4×	0.33 ms/pixel	1.0 V
original images/fig_5_BRAM16_*.tif	EOFM	registered BRAM output	16	0x1111, 0x2222, 0x4444, 0x8888, 0xFFFF	0x0000	N/A	200 MHz	12.5 MHz	50×/0.76 NA	4×	0.33 ms/pixel	1.0 V

6. Recovery experiment reproducibility

The recovery_artifact/ directory reproduces the numerical results in the recovery section of the accompanying submission. It uses the supplied Figure 5 EOFM image and deterministic post-processing; it does not collect or synthesize any optical measurement.

The three experiments are:

1. Observation diversity and rank. Decode the four Figure 5 X/Y states, evaluate all 15 nonempty observation subsets, and solve each induced 2×2-weight system with exact rational arithmetic.
2. Joint incomplete-W/incomplete-Y recovery. Enumerate or deterministically sample missing W/Y masks, test 12,898 mask pairs and all 24 observation orders, and record every candidate-survival trajectory.
3. Missing-X-bit recovery. Exhaustively test 856 X masks and 12,032 candidate completions, accepting candidates only when their predicted downstream Y equals the measured Y.

The labels FF, AA, 11, and 66 identify the four panels. The decoder reconstructs X from the two green-circled bit rows and Y from the two upper orange-circled bit rows; numeric states are never inferred from the panel label alone.

Requirements

• Python 3.10 or newer
• Packages pinned in recovery_artifact/requirements.txt
• Approximately 50 MB of free disk space

Example isolated setup from the artifact root:

cd recovery_artifact
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements.txt

The package uses exact integers for candidate prediction and fractions.Fraction for rank/affine-system calculations. Floating-point values are used only for pixel-activity decoding and figure layout, not for the recovery algebra.

Reproduce and validate

From artifact/recovery_artifact/, reproduce all three experiments with:

python reproduce_all.py

Run an individual experiment with:

python reproduce_experiment1.py
python reproduce_experiment2.py
python reproduce_experiment3.py

After reproduction, perform a read-only verification with:

python verify_artifact.py

Each reproduction command independently decodes the image, verifies its hash and decoded states, recomputes the requested results, and compares the generated numeric CSV files against preserved SHA-256 reference hashes. A mismatch produces a FAIL validation report and a nonzero exit. Successful runs print PASS.

Expected runtime for python reproduce_all.py is approximately 5--15 seconds on a current laptop and should remain under two minutes on a slower system. The clean-room verification run used to prepare this package completed in 3.8 seconds. Experiment 2 dominates runtime because it evaluates 12,898 mask pairs, 755,438 W-candidate completions, 3,021,752 candidate-observation comparisons, and 309,552 order trajectories. Experiments 1 and 3 normally complete in seconds.

7. Recovery outputs and expected results

The most useful reviewer-facing outputs are:

• recovery_artifact/results/all_experiments_summary.json: combined exact summaries
• recovery_artifact/results/experiment1_rank_{detailed,summary}.csv: all 15 rank cases and aggregates
• recovery_artifact/results/experiment2_joint_WY_{detailed,summary}.csv: all mask pairs, trajectories, and aggregates
• recovery_artifact/results/experiment2_sampling_plan.json: exact seed and exhaustive/sampled mask selection metadata
• recovery_artifact/results/experiment3_missing_X_{detailed,summary}.csv: all masks/completions and aggregates
• recovery_artifact/results/tables/: regenerated LaTeX tables, when produced
• recovery_artifact/results/figures/: regenerated figures, when produced
• recovery_artifact/results/validation/: detailed PASS/FAIL validation reports, when produced

Expected headline results are:

• All 15 Experiment 1 systems have input rank 1 and system rank 2, so no subset uniquely determines an arbitrary 2×2 W.
• Experiment 2 tests 12,898 mask pairs and 309,552 order trajectories, with 421 of 508 pairs uniquely recovering W at the maximum tested k_W=8, k_Y=8 condition.
• Experiment 3 tests all 856 masks and 12,032 candidate completions, and every unique survivor is the original experimentally decoded X.

8. Scientific provenance and verification notes

Within recovery_artifact/, input/figure5_eofm.png is the sole experimental measurement consumed by the recovery scripts. Its SHA-256 is recorded in METADATA.json and every validation report. input/decoded_observations.json records the four authoritative decoded X/Y states used by the analysis, and the decoder must independently reproduce them from the image before any experiment runs. input/ground_truth_W.json records the programmed identity matrix and bit packing.

Everything under recovery_artifact/results/ is generated post-processing. Hidden-bit masks affect only which existing decoded bits are made available to a candidate filter; they do not modify or fabricate EOFM pixels. No new optical measurements are needed.

Experiment 1 concerns identifiability of an otherwise arbitrary 2×2 W from the measured observation space. Feasibility of the programmed identity is checked separately from uniqueness. Experiment 2 begins from the programmed W with selected bits declared unknown, then filters all completions using only visible measured Y bits. Experiment 3 declares selected upstream X bits unknown and tests every completion against the complete measured downstream Y.

The strict CSV hashes in recovery_artifact/reference/expected_results.json cover every detailed and aggregate numeric row. They are validation data only; the algorithms do not load them while computing candidates, ranks, masks, or trajectories.

9. Pattern conventions

• The encoded 8-bit patterns are intentionally simple and human-readable: 0x11, 0x22, 0x44, 0x66, 0x88, 0xAA, 0xFF.
• For 16-bit BRAM, the corresponding values are 0x1111, 0x2222, 0x4444, 0x8888, and 0xFFFF.
• These patterns are the expected ground-truth states for the corresponding EOFM and BRAM image panels.
• Annotation files are overlays of the same underlying pattern and are not independent experiments.
• When a panel is named by its pattern, the recovery target is that exact value.