refactor: Reorganize project assets

README.md

@@ -10,75 +10,126 @@ app_file: app.py
 pinned: false
 ---
 
-# Why Does SVD Turn a "3" into an "8"? Linear vs. Non-linear Manifolds on MNIST
+# Why Does SVD Turn a "3" into an "8"? The Conflict Between Shape and Topology
 
-[![Hugging Face Spaces](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-blue)](https://huggingface.co/spaces/ymlin105/Coconut-MNIST) [![Full Report](https://img.shields.io/badge/📖_Read-Full_Report-blue)](./docs/REPORT.md)
+[![Hugging Face Spaces](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-blue)](https://huggingface.co/spaces/ymlin105/Coconut-MNIST)
 
-This project investigates **why SVD systematically misclassifies digit 3 as 8**, revealing fundamental differences between linear (variance-based) and non-linear (topology-based) representations. Through mechanistic analysis and empirical validation, we show that SVD and CNN optimize different objectives, leading to **complementary strengths and failure modes**.
+This project investigates a phenomenon in linear dimensionality reduction: **Why does SVD systematically reconstruct a digit "3" as an "8"?**
+
+Through spectral analysis and noise testing, we uncover a fundamental conflict between **Linear Reconstruction (SVD)** and **Non-linear Classification (CNN)**. We demonstrate that SVD acts as a "low-pass filter" that sacrifices topological details (gaps) for global shape smoothness, leading to three distinct regimes of performance:
+
+1.  **Clean Data**: CNN wins by capturing topology; SVD fails by "closing the gap."
+2.  **Simple Noise (MNIST)**: CNN remains robust; SVD preprocessing becomes an "interference" that degrades performance.
+3.  **Complex Noise (Fashion)**: CNN collapses due to texture noise; SVD survives by discarding high-frequency chaos.
+
+## 1. The Mechanism: Energy vs. Topology
+
+While implementing SVD-based classification, we observed a systematic asymmetry. Comparing the confusion matrices reveals the stark difference between linear and non-linear representations.
 
 <p align="center">
-  <img src="./docs/research_results/fig_04_explainability.png" width="600" alt="Mechanistic Analysis: SVD Blind Spot">
+  <img src="assets/fig_01_svd_confusion.png" alt="SVD Confusion Matrix" width="45%" />
+  <img src="assets/fig_04_cnn_confusion.png" alt="CNN Confusion Matrix" width="45%" />
 </p>
 
-**Key Finding**: SVD's low-pass filtering property provides complementary benefits under realistic noise conditions (σ ∈ [0, 0.3]), but becomes destructive on texture-rich data. Methods succeed in different regimes based on their optimization objectives, not universally.
-
-## The Solution: Hybrid SVD-CNN
-
-I combine SVD's strength as a data-adapted low-pass filter with the CNN's robust feature extraction into a single pipeline.
-
-```mermaid
-flowchart TD
-    subgraph S1 [I. Noisy Manifold]
-        direction LR
-        X["Input $X + \eta$"]
-    end
-
-    subgraph S2 [II. Adaptive Projection]
-        direction LR
-        node_SVD["SVD: $X = U \Sigma V^T$"]
-        node_Trunc["$k$-Rank Truncation"]
-        node_Recon["$\hat{X} = \sum \sigma_i u_i v_i^T$"]
-        node_SVD --> node_Trunc --> node_Recon
-    end
-
-    subgraph S3 [III. CNN Features]
-        direction LR
-        node_Conv["Conv Layers"] --> node_Pool["Pooling / ReLU"] --> node_Flat["Global Flatten"]
-    end
-
-    subgraph S4 [IV. Latent Mapping]
-        direction LR
-        node_Soft["Logits / Softmax"] --> node_Pred["Class Prediction"]
-    end
-
-    S1 --> S2
-    S2 --> S3
-    S3 --> S4
-
-    style S2 fill:#f8f9ff,stroke:#0056b3,stroke-width:2px
-    style S3 fill:#f8fff9,stroke:#28a745,stroke-width:2px
-    style S1 fill:#fff,stroke:#333
-    style S4 fill:#fff,stroke:#333
-```
+-   **Left (SVD, Acc=0.88)**: Shows significant confusion between 3 and 8. Notably, 3 is misclassified as 8 (2.5%) and 8 as 3 (3.4%). The diagonal values (e.g., 80.6% for digit 5) indicate lower overall confidence.
+-   **Right (CNN, Acc=0.99)**: Near-perfect diagonal dominance (mostly >98%). The topology of "3" vs "8" is clearly distinguishable.
 
-### Key Takeaways
-For full analysis and detailed metrics, see the [Technical Report](./docs/REPORT.md).
+### Root Cause: The "Morphological Closing"
+Why does the linear model fail? SVD optimizes for global pixel variance (energy). The defining feature distinguishing "3" from "8"—the topological gap—is a high-frequency detail with low energy.
 
-1. **The Variance Trap**: SVD's optimization for global pixel variance treats the topological gap distinguishing 3 from 8 as low-variance noise, discarding it during dimensionality reduction. This causes systematic manifold collapse (98.74% k-NN raw pixels → 96.98% in SVD subspace).
+**Visualizing the "Low-Pass Filter" (Eigen-digits)**
+<p align="center">
+  <img src="assets/fig_02_eigen_digits.png" alt="Global SVD Eigen-digits" width="600" />
+</p>
 
-2. **Mechanistic Proof**: Grad-CAM visualization shows CNN focuses on topological boundaries (the gap), while SVD reconstructs phantom features (a closed loop). UMAP analysis confirms manifold overlap in SVD subspace but separation in raw pixel space.
+The eigen-digits visualize what SVD actually learns.
+-   **Comp 1**: Looks like a generic "0" or a smooth ellipse. This is the strongest basis vector—the **global silhouette**.
+-   **Comp 2+**: Subsequent components add details, but they quickly become noisy and overlapping.
+-   **Implication**: The primary components capture closed loops (low-frequency energy). The "gap" in digit 3 requires specific, high-frequency components that are pushed into the tail of the spectrum and truncated.
 
-3. **Complementary Strength**: Under realistic Gaussian noise (σ ∈ [0, 0.3]), Hybrid SVD→CNN maintains 90.02% accuracy at σ=0.3 while CNN drops to 95.67%, validating SVD as an adaptive low-pass filter that enables CNN to learn from cleaner input.
+**Spectral Evidence**
+<p align="center">
+  <img src="assets/fig_01_spectrum.png" alt="Singular Value Spectrum" width="600" />
+</p>
 
-4. **Data-Dependent Boundary**: On texture-rich Fashion-MNIST, the hybrid approach fails (CNN 89.79% → Hybrid 71.78%) because SVD destroys high-frequency features that distinguish clothing items, proving complementarity requires silhouette-based structure.
+The spectrum confirms this: the "gap" corresponds to the small singular values in the **long tail** (after the steep decay). By selecting rank $k=20$, we preserve the "loopy" energy (left side of the curve) but discard the "gap" energy (right side).
 
----
+### Mechanistic Proof (Grad-CAM)
+<p align="center">
+  <img src="assets/fig_04_explainability.png" alt="Grad-CAM vs SVD Reconstruction" width="600" />
+</p>
 
-## Experience it Yourself
+-   **CNN Attention**: Focuses sharply on the topological boundary (the gap). It learns "where the digit breaks".
+-   **SVD Reconstruction**: Produces a smooth, closed loop (an "8"). It learns "what the digit contours look like".
 
-### Online Demo
-Try the live dashboard to inject noise, adjust SVD rank, and compare model predictions in real-time:
-**[Launch Streamlit App](https://huggingface.co/spaces/ymlin105/Coconut-MNIST)**.
+## 2. Dynamic Validation: Interpolation Analysis
+
+To quantify this "morphological closing," we analyzed the transition from Digit 3 ($\alpha=0$) to Digit 8 ($\alpha=1$).
+
+<p align="center">
+  <img src="assets/fig_03_interpolation.png" alt="Interpolation Analysis" width="600" />
+</p>
+
+-   **SVD Reconstruction Error (Blue Squares)**: Drops significantly at $\alpha=0.5$. This means the "ambiguous" shape is *closer* to the SVD subspace centroid than either endpoint. SVD effectively "collapses" the ambiguous shape into a generic, smooth representation.
+-   **Manifold Distance (Brown Triangles)**: Shows a sharp **spike** at $\alpha=0.5$. The raw data space treats the ambiguous shape as an outlier (far from both 3 and 8), but SVD treats it as an "ideal" reconstruction target.
+-   **CNN Probability**: Gradually increases, correctly identifying the transition.
+
+**Conclusion**: SVD subspace creates a "shortcut" for ambiguous shapes, pulling them toward a closed-loop average.
+
+## 3. The Manifold: Boundary Erosion
+
+Does this flaw destroy the entire representation?
+
+<p align="center">
+  <img src="assets/fig_05_manifold_collapse.png" alt="Manifold Comparison" width="600" />
+</p>
+
+-   **Left (SVD Projection)**: Digit 3 (blue) and 8 (red) form a mixed, circular cloud with no clear boundary. The linear projection creates a high-density overlap.
+-   **Right (UMAP Non-linear)**: Distinct "islands" of blue and red, clearly separated by topology.
+
+## 4. The Interference Effect: When Denoising Removes Signal
+
+A common intuition is that SVD's low-pass filtering should help CNNs handle noise. Our experiments on MNIST reject this.
+
+<p align="center">
+  <img src="assets/fig_06_robustness_mnist_gaussian.png" alt="Robustness: MNIST" width="600" />
+</p>
+
+**Observations**:
+-   **CNN (Red)**: Maintains the highest accuracy (~0.985 to 0.958). It is robust to Gaussian noise on simple digits.
+-   **Hybrid (Green)**: Underperforms the raw CNN consistently.
+-   **SVD (Blue)**: The weakest performer, degrading rapidly as noise increases.
+
+**Conclusion**: On silhouette-based datasets like MNIST, CNN's non-linear robustness is superior. SVD preprocessing acts as an **information bottleneck**, stripping away edge signals that CNN needs to correct noise.
+
+## 5. The Reversal: The Fragility of Texture Recognition
+
+On **Fashion-MNIST**, the story flips. Classification here depends on **texture** (high-frequency).
+
+<p align="center">
+  <img src="assets/fig_08_robustness_fashion.png" alt="Robustness: Fashion-MNIST" width="600" />
+</p>
+
+**Observations**:
+-   **CNN (Red)**: Crashes dramatically from 0.90 to 0.32. It cannot distinguish "texture signal" from "texture noise".
+-   **SVD (Blue)**: Remains incredibly stable (0.80 to 0.68). Its "blindness" to high-frequency texture becomes a **shield** against noise. It survives by relying solely on low-frequency silhouette.
+-   **The Crossover**: SVD overtakes CNN at $\sigma \approx 0.12$.
+-   **Hybrid (Green)**: Starts low (0.72) and crashes. It suffers the worst of both worlds: SVD destroys discriminative texture features, and the CNN fails to classify the "smoothed" clothes.
+
+**Conclusion**: SVD's denoising comes at the cost of **semantic destruction** on texture-rich data. It survives the noise but kills the signal.
+
+## Key Insight
+
+There is no universal winner. Methods succeed based on the alignment between their optimization objective and the data's frequency profile:
+
+| Method  | Optimization Target     | Strength                  | Weakness                              |
+| :------ | :---------------------- | :------------------------ | :------------------------------------ |
+| **SVD** | Global Variance ($L_2$) | Robust to high-freq noise | Blinds to topology/texture            |
+| **CNN** | Discriminative Features | Sensitive to topology     | Vulnerable to texture-noise confusion |
+
+**Takeaway**: Before choosing a denoising pipeline, ask: *Is my signal high-frequency or low-frequency?* If your signal is in the edges (Topology), linear filtering will hurt more than help.
+
+## Quick Start
 
 ### Local Installation
 ```bash
@@ -97,10 +148,14 @@ streamlit run app.py
 ```
 ├── src/               Core modules (CNN, SVD layer) + Experimental Utils
 ├── experiments/       Sequential scripts (01 Diagnosis, 02 Proof, 03 Boundaries)
-├── docs/              Full report (REPORT.md) + figures
+├── assets/            Figures and images for README
 ├── models/            Pretrained checkpoints
 ├── run_all_experiments.sh  One-click reproduction script
 └── app.py             Streamlit dashboard
 ```
 
----
+### Run All Experiments
+```bash
+# Run the complete experimental pipeline
+./run_all_experiments.sh
+```

app.py

@@ -3,7 +3,7 @@ os.environ["STREAMLIT_SERVER_FILEWATCHERTYPE"] = "none"
 import streamlit as st
 import numpy as np
 import plotly.express as px
-import torch
+import torch，，，，，
 import umap
 import pandas as pd
 from sklearn.decomposition import TruncatedSVD
@@ -114,13 +114,12 @@ st.markdown("""
     }
 
     /* Slider and input styling */
-    /* Slider styling - Minimalist and Clean */
     div[data-baseweb="slider"] > div > div > div {
-        background-color: #ECEFF4 !important; /* Track color */
+        background-color: #ECEFF4 !important;
     }
 
     div[data-baseweb="slider"] > div > div > div > div {
-        background-color: #5E81AC !important; /* Progress color */
+        background-color: #5E81AC !important;
     }
 
     /* Radio button styling */
@@ -227,8 +226,8 @@ with st.sidebar:
 
     st.info("""
     **Key Finding:**\n
-    SVD optimizes global variance → fails at local topological features (the 3/8 gap).\n
-    CNN captures discriminative boundaries → sensitive to noise.
+    SVD optimizes global variance → fails at topology (the 3/8 gap).\n
+    CNN captures boundaries → vulnerable to texture-noise confusion.
     """)
 
     # Global Noise Control for Hybrid Analysis
@@ -238,7 +237,7 @@ with st.sidebar:
         help="Hybrid pipeline: SVD preprocessing → CNN classification"
     )
     if noise_mode:
-        st.success("SVD Denoising Active", icon="✅")
+        st.warning("SVD Preprocessing Active\n(May act as an 'Information Bottleneck')", icon="⚠️")
 
     st.markdown("---")
     st.markdown("### 🎚️ Model Calibration")
@@ -253,7 +252,7 @@ with st.sidebar:
     st.caption("""
     **Tabs:**
     - Topology: Decision boundary snap analysis
-    - Robustness: Noise filtering comparison
+    - Interference: Why denoising fails on MNIST
     - Manifold: Linear vs non-linear projections
     - Lab: Interactive testing
     """)
@@ -269,7 +268,7 @@ st.title("🥥 Coconut MNIST: Why SVD Misclassifies 3 as 8")
 st.markdown("""
 ### Mechanistic Analysis: Linear vs. Non-Linear Representations
 
-Explore how SVD's global variance optimization and CNN's local feature extraction lead to **complementary strengths and failure modes**.
+Explore the conflict between SVD's global variance optimization and CNN's local feature extraction.
 
 **Start your exploration below →**
 """)
@@ -279,7 +278,7 @@ st.markdown("---")
 # --- Tabs ---
 tab1, tab2, tab3, tab4 = st.tabs([
     "The Topology Gap", 
-    "Robustness Limits", 
+    "The Interference Effect", 
     "Manifold Explorer", 
     "Live Lab"
 ])
@@ -290,8 +289,8 @@ with tab1:
     st.markdown("### 🔍 Topological Decision Boundaries")
     st.markdown("""
     Smoothly interpolate between two digits and observe:
-    - **CNN's behavior**: Sharp phase transition at manifold boundary (topological snap)
-    - **SVD's behavior**: Gradual reconstruction error increase (tries to "bridge" manifolds)
+    - **CNN's behavior**: Sharp phase transition at manifold boundary (topological snap).
+    - **SVD's behavior**: "Morphological Closing" — tries to smooth the transition by closing gaps.
 
     This reveals the fundamental difference: CNN sees discrete topology, SVD sees continuous variance.
     """)
@@ -357,18 +356,20 @@ with tab1:
     st.caption(f"The vertical 'snap' in this curve highlights the non-linear decision boundary. Even as the pixels fade linearly, the CNN's internal representation jumps once a topological threshold is crossed.")
 
 
-# --- Tab 2: Robustness (The SVD Advantage) ---
+# --- Tab 2: Robustness (The Interference Effect) ---
 with tab2:
-    st.markdown("### 🛡️ SVD as Adaptive Denoiser")
+    st.markdown("### ⚠️ The Interference Effect: When Denoising Removes Signal")
     st.markdown("""
-    **Key insight**: While SVD fails on clean MNIST (destroys the 3-8 gap), it becomes powerful under noise.
+    **Myth busted**: SVD preprocessing does NOT always help CNNs.
 
-    **Mechanism**: By keeping only top-20 variance directions, SVD acts as a low-pass filter that:
-    - ✓ Preserves class-relevant structure
-    - ✓ Suppresses high-frequency Gaussian noise
-    - ✗ Cannot recover from information already lost to noise
+    **Observations on MNIST**:
+    - **CNN**: Remains surprisingly robust to moderate noise due to non-linear feature extraction.
+    - **SVD**: Acts as a "low-pass filter". While it removes noise, it also **strips away high-frequency edges** critical for classification.
+    - **Result**: The Hybrid model often **underperforms** the raw CNN. SVD creates an "Information Bottleneck".
 
-    **Trade-off**: SVD + CNN maintains accuracy under moderate noise better than CNN alone.
+    **The Fashion-MNIST Reversal** (See Report):
+    - On texture-rich data, CNN collapses under high noise (texture-noise confusion).
+    - SVD survives by discarding the chaotic high-frequency band entirely.
     """)
     
     col1, col2 = st.columns([1, 2])
@@ -408,11 +409,18 @@ with tab2:
         acc_hybrid = interp("Hybrid", sigma)
 
         m1, m2, m3 = st.columns(3)
-        m1.metric("SVD+LR Accuracy (10-class)", f"{acc_svd:.1%}")
-        m2.metric("CNN Accuracy (10-class)", f"{acc_cnn:.1%}")
-        m3.metric("Hybrid Robustness (10-class)", f"{acc_hybrid:.1%}")
-
-        st.caption("Metrics come from precomputed evaluation on the MNIST test set (test-time Gaussian noise).")
+        m1.metric("SVD+LR Accuracy", f"{acc_svd:.1%}", delta="Baseline Linear Model")
+        m2.metric("CNN Accuracy", f"{acc_cnn:.1%}", delta="Superior Robustness")
+        
+        # Logic to highlight the interference effect
+        delta_hybrid = acc_hybrid - acc_cnn
+        delta_text = f"{delta_hybrid:.1%} vs Raw CNN"
+        if delta_hybrid < 0:
+            m3.metric("Hybrid Accuracy", f"{acc_hybrid:.1%}", delta=delta_text, delta_color="inverse")
+        else:
+            m3.metric("Hybrid Accuracy", f"{acc_hybrid:.1%}", delta=delta_text, delta_color="normal")
+
+        st.caption("Metrics come from precomputed evaluation on the MNIST test set. Note that Hybrid often trails CNN, proving that linear denoising can remove useful signal.")
     else:
         st.info("Robustness metrics not found. Run `python experiments/09_hybrid_robustness.py` to generate evaluated curves.")
 
@@ -424,8 +432,8 @@ with tab3:
     **Question**: How different are linear (SVD) vs non-linear (UMAP) projections?
 
     **Observations**:
-    - **SVD (Blue regions)**: Classes overlap → global variance loses local structure
-    - **UMAP (Colorful clusters)**: Classes separate → preserves topological neighborhoods
+    - **SVD (Blue regions)**: Classes overlap → global variance loses local structure (Boundary Erosion).
+    - **UMAP (Colorful clusters)**: Classes separate → preserves topological neighborhoods.
 
     This visualizes why CNN (non-linear) works while SVD fails on the 3-8 pair.
     """)
@@ -492,7 +500,7 @@ with tab3:
             )
             fig_svd.update_traces(marker=dict(size=4, opacity=0.6))
             st.plotly_chart(fig_svd, use_container_width=True, key="svd_chart")
-            st.caption("Classes overlap significantly - 3 and 8 intertwine.")
+            st.caption("Boundary Erosion: 3 and 8 overlap significantly.")
         
         with col2:
             st.markdown("#### UMAP Projection")
@@ -512,7 +520,7 @@ with tab3:
             )
             fig_umap.update_traces(marker=dict(size=4, opacity=0.6))
             st.plotly_chart(fig_umap, use_container_width=True, key="umap_chart")
-            st.caption("Classes form distinct clusters - non-linear separation works.")
+            st.caption("Distinct Clusters: Non-linear separation preserves topology.")
     
     elif projection_method == "SVD (Linear)":
         fig = px.scatter(
@@ -550,13 +558,13 @@ with tab4:
     st.markdown("### 🧪 Interactive Testing")
     st.markdown("""
     **Experiment 1: Dataset Browser**
-    - Pick a digit and add Gaussian noise
-    - See how SVD denoises before CNN classification
-    - Compare predictions with/without SVD preprocessing
+    - Pick a digit and add Gaussian noise.
+    - Compare predictions with/without SVD preprocessing.
+    - **Observe**: Does SVD help or hurt the classification?
 
     **Experiment 2: Draw Your Own**
-    - Sketch a digit and watch both methods analyze it in real-time
-    - Observe the difference between CNN's sharp boundary detection and SVD's smooth reconstruction
+    - Sketch a digit and watch both methods analyze it in real-time.
+    - Observe the difference between CNN's sharp boundary detection and SVD's smooth reconstruction.
     """)
     
     # Two modes: sample browser or upload
@@ -679,4 +687,4 @@ with tab4:
 
 
 st.markdown("---")
-st.caption("Coconut MNIST | Linear vs Non-Linear Analysis | [View Report](./docs/REPORT.md)")
+st.caption("Coconut MNIST | Linear vs Non-Linear Analysis")

docs/REPORT.md

@@ -1,204 +0,0 @@
-# SVD vs CNN on MNIST: A Study of Complementary Representations
-
-## 1. Initial Observation
-
-While implementing SVD-based digit classification on MNIST, we observed systematic confusion between digits 3 and 8. The confusion matrix reveals:
-- Digit 8 misclassified as 3: **3.4%**
-- Digit 3 misclassified as 8: **2.5%**
-
-This asymmetric but correlated failure pattern warranted investigation into the fundamental mechanisms driving the two methods' behaviors.
-
-<p align="center">
-  <img src="research_results/fig_01_svd_confusion.png" alt="SVD Confusion Matrix" width="500" />
-  <br>
-  <em><strong>Figure 1:</strong> SVD Confusion Matrix (Accuracy: 88.13%). Errors concentrate on visually similar pairs: 3 ↔ 8, 5 ↔ 3, 4 ↔ 9.</em>
-</p>
-
----
-
-## 2. Diagnosis: The Variance Trap
-
-### 2.1 Overall Performance (Clean Data)
-
-<div align="center">
-
-| Method | Accuracy |
-|--------|----------|
-| SVD    | 88.13%   |
-| CNN    | 98.55%   |
-
-</div>
-
-SVD's 10% accuracy gap is not uniformly distributed. Confusion concentrates on visually ambiguous pairs (as shown in Figure 1):
-- 3 ↔ 8 (2.5% + 3.4%)
-- 5 ↔ 3 (6.4% + 0.9%)
-- 4 ↔ 9 (1.7% + 5.8%)
-
-Other digit pairs show error rates < 1.5%.
-
-### 2.2 Root Cause: SVD Optimizes for Global Variance
-
-SVD solves:
-$$X = U \Sigma V^T$$
-
-where $\Sigma$ contains singular values sorted in decreasing order. Truncation to rank $k=20$ retains only the $k$ dimensions with highest variance.
-
-<p align="center">
-  <img src="research_results/fig_01_spectrum.png" alt="Singular Value Spectrum" width="400" />
-  <br>
-  <img src="research_results/fig_02_eigen_digits.png" alt="Eigen-digits" width="400" />
-  <br>
-  <em><strong>Figure 2 & 3:</strong> Left: Singular value decay showing rapid drop after k≈5. Right: First 10 eigen-digits (principal components). SVD reconstructs shared circular silhouettes, smoothing over discriminative gaps.</em>
-</p>
-
-**The problem**: The topological gap distinguishing 3 from 8 has low pixel variance (few pixels differ). SVD treats it as noise and discards it during dimensionality reduction. The reconstructed 3 appears closer to an 8-like silhouette.
-
----
-
-## 3. Mechanistic Proof
-
-### 3.1 Grad-CAM Visualization
-
-<p align="center">
-  <img src="research_results/fig_04_explainability.png" alt="Grad-CAM vs SVD Reconstruction" width="700" />
-  <br>
-  <em><strong>Figure 4:</strong> Left: CNN Grad-CAM attention (red = high focus). Center: Original digit 3. Right: SVD reconstruction. CNN focuses on the gap; SVD hallucinates a closed loop to minimize reconstruction error.</em>
-</p>
-
-**CNN** attention heatmap: Focuses exclusively on the topological boundary (gap in digit 3).
-
-**SVD** reconstruction: Smooth, closed loop at the 3-8 ambiguity zone, indicating the linear model reconstructs a phantom feature to minimize overall error.
-
-### 3.2 UMAP Manifold Analysis
-
-<p align="center">
-  <img src="research_results/fig_05_manifold_collapse.png" alt="Manifold Comparison: Raw vs SVD Subspace" width="600" />
-  <br>
-  <em><strong>Figure 5:</strong> Left: UMAP of raw pixel space (3 and 8 clearly separated). Right: UMAP of SVD 20-component subspace (clusters overlap significantly).</em>
-</p>
-
-- **Raw pixel space**: Digit 3 and 8 clusters are clearly separated (98.74% k-NN accuracy).
-- **SVD 20-component subspace**: Clusters overlap significantly (96.98% k-NN accuracy, 1.76% loss).
-- **Interpretation**: SVD projection collapses the manifold boundaries that discriminate these digits.
-
-### 3.3 Interpolation Boundary
-
-<p align="center">
-  <img src="research_results/fig_03_interpolation.png" alt="Decision Boundary Interpolation" width="700" />
-  <br>
-  <em><strong>Figure 6:</strong> Interpolating from digit 3 to 8. Top: CNN class probability (sharp transition at manifold boundary). Bottom: SVD reconstruction error (peaks at midpoint where linear model struggles to bridge two manifolds).</em>
-</p>
-
-Interpolating smoothly from digit 3 to digit 8:
-- **CNN confidence**: Sharp phase transition at the midpoint (topological boundary detected).
-- **SVD reconstruction error**: Peaks at midpoint (linear model struggles to bridge two distinct manifolds).
-
----
-
-## 4. Complementarity: SVD as Denoising Filter
-
-While SVD fails as a classifier on clean data, its low-pass filtering property reveals complementary benefits under realistic noise conditions.
-
-### 4.1 Robustness Under Gaussian Noise (σ ∈ [0, 0.3])
-
-Test regime: Add Gaussian noise $\mathcal{N}(0, \sigma^2)$ to test images (image range normalized to [0, 1]).
-
-<p align="center">
-  <img src="research_results/fig_06_robustness_mnist_gaussian.png" alt="Robustness: Realistic Gaussian Noise on MNIST" width="500" />
-  <br>
-  <em><strong>Figure 7:</strong> Accuracy under Gaussian noise (σ ∈ [0, 0.3]). Hybrid (SVD→CNN) maintains stable performance, outperforming CNN at σ=0.2 and beyond.</em>
-</p>
-
-<div align="center">
-
-| σ | CNN | SVD | Hybrid |
-|---|-----|-----|--------|
-| 0.0 | 98.55% | 88.13% | 91.98% |
-| 0.1 | 98.48% | 87.18% | 91.84% |
-| 0.2 | 97.94% | 86.37% | 91.24% |
-| 0.3 | 95.67% | 80.64% | 90.02% |
-
-</div>
-
-**Key finding**:
-- **Clean data**: CNN >> Hybrid >> SVD
-- **At σ=0.3**: CNN drops to 95.67%, but Hybrid remains at 90.02%
-- **Hybrid advantage**: Maintains relative stability by filtering noise before feature extraction
-
-### 4.2 Mechanism: Selective Feature Preservation
-
-SVD truncation to rank $k=20$ acts as an adaptive low-pass filter:
-$$\text{Noisy Image} \xrightarrow{\text{SVD Project}} \text{Denoised} \xrightarrow{\text{CNN}} \text{Class}$$
-
-By discarding low-variance dimensions, SVD naturally suppresses high-frequency Gaussian noise while preserving the primary class-discriminative structure. CNN then works with cleaner input.
-
-### 4.3 Implication
-
-SVD's complementary benefit is **narrowly applicable**: it helps when:
-1. Noise is Gaussian (random, not aligned with data)
-2. Noise level is moderate (σ ≤ 0.3, images still recognizable)
-3. Data is simple/silhouette-based (MNIST works; texture-based data may not)
-
----
-
-## 5. Boundary: Failure on Texture-Rich Data
-
-On **Fashion-MNIST**, SVD's low-pass filtering becomes destructive.
-
-<p align="center">
-  <img src="research_results/fig_08_robustness_fashion.png" alt="Fashion-MNIST: SVD Filter Destroys Textures" width="500" />
-  <br>
-  <em><strong>Figure 8:</strong> Performance on Fashion-MNIST under noise (σ ∈ [0, 0.3]). CNN performance degrades rapidly, but SVD (which preserves structure in MNIST) performs even worse than Hybrid here, revealing data-dependent behavior.</em>
-</p>
-
-**Clean data (σ=0)**:
-
-<div align="center">
-
-| Method | Accuracy |
-|--------|----------|
-| CNN    | 89.79%   |
-| SVD    | 80.30%   |
-| Hybrid | 71.78%   |
-
-</div>
-
-**Why Hybrid fails worst (71.78%)**:
-1. SVD destroys high-frequency textures (buttons, zippers, stitching) that distinguish clothing items
-2. CNN receives a "simplified" image that has already lost class-relevant information
-3. CNN cannot recover from this information loss, performing worse than SVD alone
-
-**Implication**: SVD's denoising benefit is restricted to **silhouette-based datasets** where low-frequency structure dominates. On texture-rich data, the hybrid approach becomes a liability.
-
----
-
-## 6. Summary: Method Applicability by Data Regime
-
-<div align="center">
-
-| Scenario | Best Choice | Why |
-|----------|------------|-----|
-| **Clean MNIST** | CNN (98.55%) | No noise; SVD's simplification is pure loss |
-| **Noisy MNIST (σ=0.2-0.3)** | Hybrid (91.24%) | SVD filters Gaussian noise; CNN learns from cleaner input |
-| **Clean Fashion-MNIST** | CNN (89.79%) | Textures require non-linear feature extraction |
-| **Texture-rich + Noise** | CNN alone | SVD destroys high-freq features before noise filtering helps |
-
-</div>
-
-**No universal winner**: Methods succeed in different regimes based on their optimization objectives:
-
-- **SVD** optimizes: Global variance preservation → low-pass filter → stable on silhouette-based data
-- **CNN** optimizes: Discriminative feature learning → sensitive to noise, but powerful on complex data
-
----
-
-## 7. Conclusion
-
-This study demonstrates that methodological "limitations" are not flaws but **manifestations of optimization objectives**. SVD and CNN optimize different criteria—global reconstruction vs. local discrimination—leading to complementary failure modes and strengths.
-
-**Key insight**: Understanding a method's optimization target enables **predicting its applicability** rather than treating it as a black box. The choice of method should depend on:
-1. **Data characteristics** (silhouette vs. texture)
-2. **Noise conditions** (Gaussian vs. aligned; moderate vs. extreme)
-3. **Accuracy requirements** (marginal vs. acceptable loss)
-
-Rather than seeking universal solutions, practitioners should match methods to specific problem regimes.

run_all_experiments.sh

@@ -3,6 +3,15 @@
 
 set -e
 
+# Ensure python finds the modules in the current directory
+export PYTHONPATH=$PYTHONPATH:.
+
+echo "=== 0. Training Models (MNIST & Fashion-MNIST) ==="
+echo "Training MNIST models..."
+python -m src.train_models
+echo "Training Fashion-MNIST models..."
+python -m src.train_fashion
+
 echo "=== 1. Phenomenon Diagnosis (Global SVD & CNN Baseline) ==="
 python -m experiments.01_phenomenon_diagnosis
 
@@ -17,5 +26,5 @@ python -m experiments.03_operational_boundaries --dataset fashion
 
 echo "=========================================================="
 echo "All experiments completed successfully."
-echo "Results and figures saved in docs/research_results/"
+echo "Results and figures saved in assets/"
 echo "=========================================================="

src/config.py

@@ -4,7 +4,7 @@ import os
 BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 DATA_DIR = os.path.join(BASE_DIR, "data")
 MODELS_DIR = os.path.join(BASE_DIR, "models")
-RESULTS_DIR = os.path.join(BASE_DIR, "docs", "research_results")
+RESULTS_DIR = os.path.join(BASE_DIR, "assets")
 
 for d in [DATA_DIR, MODELS_DIR, RESULTS_DIR]:
     os.makedirs(d, exist_ok=True)

src/viz.py

@@ -144,8 +144,9 @@ def plot_manifold_comparison(X_svd, X_umap, y, acc_svd, acc_raw, filename):
         ax.set_xticks([])
         ax.set_yticks([])
 
-    plt.suptitle("Manifold Collapse: Linear SVD Overlap vs. Non-linear Topological Separation", 
-                 fontsize=14, fontweight='bold', y=1.02)
+    plt.suptitle("Manifold Collapse: SVD vs UMAP Projections", 
+                 fontsize=14, fontweight='bold', y=1.05)
+    plt.tight_layout(rect=[0, 0, 1, 0.95])  # Leave space for title
     save_fig(filename)
 
 def plot_learning_curves(history, title, filename):