Upload 11 files

README.md

@@ -1,15 +1,45 @@
 ---
-title: FWD
-emoji: 📉
-colorFrom: gray
-colorTo: indigo
+title: DBFT Pavement Strain Predictor
+emoji: 🛣️
+colorFrom: green
+colorTo: gray
 sdk: gradio
-sdk_version: 6.20.0
-python_version: '3.12'
+sdk_version: 5.24.0
 app_file: app.py
 pinned: false
-license: apache-2.0
-short_description: Falling weight deflectometer calculation
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# DBFT — Pavement Strain Predictor
+
+Predicts the two critical pavement strains **directly** from a Falling Weight
+Deflectometer (FWD) test — no backcalculation step:
+
+- **ε_t** — horizontal tensile strain at the bottom of the asphalt layer
+  (fatigue-cracking criterion)
+- **ε_c** — vertical compressive strain at the top of the subgrade
+  (rutting criterion)
+
+Model: **DBFT (Deflection-Basin Fusion Transformer)**, ~150k parameters,
+trained with a combined surrogate + field loss (λ = 1.0) on an extended
+layered-elastic surrogate (14,174 PyMastic/EVERSTRESS solutions) plus 7,651
+Thai DOH field measurements. Held-out-route field performance:
+**R² = 0.96 (AC) / 0.88 (subgrade)**.
+
+Every prediction includes a **local SHAP attribution** (KernelExplainer over
+the 12 field-measurable inputs: 9 deflections D0–D1800 + 3 layer thicknesses)
+showing how each input pushed the prediction away from the model baseline.
+
+## Inputs
+
+| Input | Unit | Note |
+|---|---|---|
+| D0 … D1800 | μm | deflection basin, normalized to 707 kPa plate pressure |
+| h_AC, h_Base, h_Subbase | mm | h_Subbase = 0 for structures without a subbase |
+
+## Run locally
+
+```bash
+pip install -r requirements.txt gradio
+python app.py
+```

app.py

@@ -0,0 +1,195 @@
+"""DBFT Pavement Strain Predictor — Gradio app for Hugging Face Spaces.
+
+Predicts the two critical pavement strains directly from an FWD deflection
+basin + layer thicknesses, using the best model from the paper (combined
+loss lambda_f = 1.0, extended surrogate), with a local SHAP explanation
+for every prediction.
+"""
+
+from pathlib import Path
+
+import gradio as gr
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+import numpy as np
+import shap
+import torch
+
+from fwd_fusion_transformer import DBFT, basin_indices
+
+HERE = Path(__file__).resolve().parent
+ASSETS = HERE / "assets"
+TAG = "combined_lam1.0_ext"
+FEATURES = ["D0", "D200", "D300", "D450", "D600", "D900", "D1200", "D1500",
+            "D1800", "h_AC", "h_Base", "h_Subbase"]
+NSAMPLES = 200
+
+# ---------------- model ----------------
+sc = np.load(ASSETS / f"dbft_{TAG}_scalers.npz")
+model = DBFT()
+model.load_state_dict(torch.load(ASSETS / f"dbft_{TAG}.pt", map_location="cpu"))
+model.eval()
+
+
+def f(X):
+    """X: (n, 12) raw [D0..D1800 um, h_AC..h_Subbase mm] -> (n, 2) strains ue."""
+    X = np.asarray(X, np.float32)
+    D, H = X[:, :9], X[:, 9:12]
+    I = basin_indices(D).astype(np.float32)
+    t = lambda a, k: torch.tensor((a - sc[f"{k}_mean"]) / sc[f"{k}_std"],
+                                  dtype=torch.float32)
+    with torch.no_grad():
+        p = model(t(D, "D"), t(I, "I"), t(H, "H")).numpy()
+    return p * sc["Y_std"] + sc["Y_mean"]
+
+
+bg = np.load(ASSETS / "bg_cache.npz")["bg"]
+explainer = shap.KernelExplainer(f, bg)
+BASE = np.asarray(explainer.expected_value, float)
+
+RED, BLUE, GREEN, AMBER = "#d64545", "#3b7dd8", "#10a37f", "#d69e2e"
+
+
+def severity(v, lo, hi):
+    return (("low", GREEN) if v < lo else
+            ("moderate", AMBER) if v < hi else ("high", RED))
+
+
+def shap_figure(sv_ac, sv_sg, pred):
+    """Two-panel horizontal bar chart of local SHAP values (ue)."""
+    fig, axes = plt.subplots(1, 2, figsize=(11, 4.2), dpi=140)
+    titles = [(r"$\varepsilon_t$ — AC tensile", sv_ac, BASE[0], pred[0]),
+              (r"$\varepsilon_c$ — subgrade compressive", sv_sg, BASE[1],
+               pred[1])]
+    for ax, (title, sv, base, p) in zip(axes, titles):
+        order = np.argsort(np.abs(sv))
+        names = [FEATURES[i] for i in order]
+        vals = sv[order]
+        colors = [RED if v >= 0 else BLUE for v in vals]
+        ax.barh(range(len(vals)), vals, color=colors, alpha=0.85)
+        ax.axvline(0, color="#999", lw=1)
+        ax.set_yticks(range(len(vals)))
+        ax.set_yticklabels(names, fontsize=9)
+        ax.set_xlabel("SHAP value (με)", fontsize=9)
+        ax.set_title(f"{title}\nbaseline {base:.0f} με → prediction "
+                     f"{p:.0f} με", fontsize=10)
+        ax.grid(alpha=0.3, axis="x")
+        for s in ["top", "right"]:
+            ax.spines[s].set_visible(False)
+    fig.suptitle("Local SHAP — red pushes strain up, blue pushes it down",
+                 fontsize=10.5, y=1.02)
+    fig.tight_layout()
+    return fig
+
+
+def predict(d0, d200, d300, d450, d600, d900, d1200, d1500, d1800,
+            h_ac, h_base, h_subbase, explain):
+    d = [d0, d200, d300, d450, d600, d900, d1200, d1500, d1800]
+    h = [h_ac, h_base, h_subbase]
+    if any(v is None for v in d + h):
+        raise gr.Error("Please fill in all 12 inputs (use 0 only for "
+                       "h_Subbase when there is no subbase).")
+    d, h = np.array(d, np.float32), np.array(h, np.float32)
+    if np.any(d <= 0):
+        raise gr.Error("Deflections must be positive (μm at 707 kPa).")
+    if h[0] <= 0 or np.any(h < 0):
+        raise gr.Error("Thicknesses must be ≥ 0 mm with h_AC > 0.")
+    if d[0] < d[-1]:
+        raise gr.Error("D0 should exceed D1800 — check the basin order.")
+
+    x = np.concatenate([d, h])[None, :]
+    eps_ac, eps_sg = map(float, f(x)[0])
+
+    s_ac, c_ac = severity(eps_ac, 150, 400)
+    s_sg, c_sg = severity(eps_sg, 300, 600)
+    html = f"""
+    <div style="display:flex;gap:14px;flex-wrap:wrap;font-family:system-ui">
+      <div style="flex:1;min-width:230px;border:1px solid #e3e3e6;
+                  border-radius:12px;padding:14px;background:#fafbfc">
+        <div style="font-size:13px;color:#6e6e80">ε<sub>t</sub> — AC tensile
+          strain (fatigue criterion)</div>
+        <div style="font-size:30px;font-weight:700">{eps_ac:.1f}
+          <span style="font-size:15px;color:#6e6e80">με</span>
+          <span style="font-size:14px;color:{c_ac}">· {s_ac}</span></div>
+        <div style="font-size:12px;color:#6e6e80">bottom of the asphalt layer
+        </div>
+      </div>
+      <div style="flex:1;min-width:230px;border:1px solid #e3e3e6;
+                  border-radius:12px;padding:14px;background:#fafbfc">
+        <div style="font-size:13px;color:#6e6e80">ε<sub>c</sub> — subgrade
+          compressive strain (rutting criterion)</div>
+        <div style="font-size:30px;font-weight:700">{eps_sg:.1f}
+          <span style="font-size:15px;color:#6e6e80">με</span>
+          <span style="font-size:14px;color:{c_sg}">· {s_sg}</span></div>
+        <div style="font-size:12px;color:#6e6e80">top of the subgrade</div>
+      </div>
+    </div>"""
+
+    fig = None
+    if explain:
+        sv = explainer.shap_values(x, nsamples=NSAMPLES, silent=True)
+        sv = np.array(sv)
+        if sv.ndim == 3 and sv.shape[-1] == 2:
+            sv = np.moveaxis(sv, -1, 0)
+        fig = shap_figure(sv[0, 0], sv[1, 0], (eps_ac, eps_sg))
+    return html, fig
+
+
+EXAMPLES = [
+    # Thai DOH route 23 (thin structure, unbound base)
+    [171.0, 154.5, 145.1, 89.6, 62.8, 47.4, 32.9, 22.6, 17.9,
+     100, 150, 300, True],
+    # factorial-like softer structure
+    [1126.8, 940.1, 815.5, 663.5, 548.0, 390.7, 293.9, 231.7, 189.9,
+     100, 200, 300, True],
+    # stiff bound-base section
+    [120.0, 100.0, 90.0, 75.0, 62.0, 45.0, 33.0, 25.0, 20.0,
+     50, 200, 0, True],
+]
+
+with gr.Blocks(theme=gr.themes.Soft(primary_hue="emerald"),
+               title="DBFT — Pavement Strain Predictor") as demo:
+    gr.Markdown(
+        "# 🛣️ DBFT — Pavement Strain Predictor\n"
+        "Predicts the two critical pavement strains **directly** from a "
+        "Falling Weight Deflectometer test — no backcalculation step. "
+        "Model: Deflection-Basin Fusion Transformer (~150k parameters), "
+        "combined loss λ = 1.0 on an extended layered-elastic surrogate + "
+        "7,651 Thai DOH field points. Held-out-route field accuracy: "
+        "**R² = 0.96 (AC) / 0.88 (subgrade)**."
+    )
+    gr.Image(str(ASSETS / "fwd_diagram.png"), show_label=False,
+             container=False, interactive=False, show_download_button=False,
+             show_fullscreen_button=False)
+
+    gr.Markdown("### Deflection basin — μm, normalized to 707 kPa")
+    with gr.Row():
+        d_in = [gr.Number(label=lab, precision=1) for lab in
+                ["D0", "D200", "D300", "D450", "D600", "D900", "D1200",
+                 "D1500", "D1800"]]
+    gr.Markdown("### Layer thicknesses — mm (h_Subbase = 0 if no subbase)")
+    with gr.Row():
+        h_in = [gr.Number(label="h_AC (mm)", precision=0),
+                gr.Number(label="h_Base (mm)", precision=0),
+                gr.Number(label="h_Subbase (mm)", precision=0)]
+        explain_in = gr.Checkbox(value=True,
+                                 label="Explain with local SHAP (~3 s)")
+
+    btn = gr.Button("Predict", variant="primary")
+    out_html = gr.HTML()
+    out_plot = gr.Plot(label="Why? — local SHAP attribution")
+
+    btn.click(predict, inputs=d_in + h_in + [explain_in],
+              outputs=[out_html, out_plot])
+    gr.Examples(examples=EXAMPLES, inputs=d_in + h_in + [explain_in],
+                label="Examples (click a row, then Predict)")
+    gr.Markdown(
+        "<small>Research prototype — trained on Thai DOH FWD data and "
+        "layered-elastic theory at 707 kPa / 150 mm plate. SHAP: "
+        "KernelExplainer over the 12 measurable inputs; red bars push the "
+        "prediction up, blue bars down.</small>"
+    )
+
+if __name__ == "__main__":
+    demo.launch()

assets/bg_cache.npz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:118d15e4d97b3835806e276ead4cc4f2365a81c23788eece1bccc2de71e2df2f
+size 3138

assets/dbft_combined_lam1.0_ext.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:069a9b079895c97f66aa0ca5ee39567fec21fa97076991bc9071acdb82f1e79f
+size 935386

assets/dbft_combined_lam1.0_ext_scalers.npz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:04ab6582e463d1a8f59f6c9065c1ac7e51bd56c41924d0ace837dc1496e89d7d
+size 2118

fwd_fusion_transformer.py

@@ -0,0 +1,227 @@
+"""
+DBFT: Deflection-Basin Fusion Transformer for FWD critical strain prediction
+=============================================================================
+Predicts the two critical pavement responses from Falling Weight Deflectometer
+(FWD) measurements:
+  - AC          : horizontal tensile strain at the bottom of the asphalt layer
+  - Subgrade.2  : vertical compressive strain at the top of the subgrade
+
+Inputs (field-measurable only — no layer moduli, avoiding backcalculation):
+  - Deflection basin D0..D1800  (9 geophones, treated as a spatial sequence)
+  - Layer thicknesses (Asphalt, Base, Subbase)
+
+Architecture (novel elements):
+  1. Continuous sensor-offset positional encoding: Fourier features of the
+     physical geophone offset (mm), so the model knows the true basin geometry
+     and generalizes to arbitrary sensor arrays.
+  2. Physics-informed basin tokens: SCI, BDI, BCI, AREA, AUPP indices are
+     embedded as extra tokens alongside raw deflections.
+  3. Thickness encoder branch producing (a) memory tokens and (b) FiLM
+     (feature-wise linear modulation) parameters applied to the basin tokens.
+  4. Strain-query transformer decoder: one learnable query per target strain
+     cross-attends over the fused basin+thickness memory (set-to-vector
+     decoding), giving per-target attention maps for interpretability.
+"""
+
+import math
+import numpy as np
+import pandas as pd
+import torch
+import torch.nn as nn
+
+SENSOR_OFFSETS_MM = np.array([0, 200, 300, 450, 600, 900, 1200, 1500, 1800], dtype=np.float32)
+DEFLECTION_COLS = ["D0", "D200", "D300", "D450", "D600", "D900", "D1200", "D1500", "D1800"]
+THICKNESS_COLS = ["Asphalt", "Base", "Subbase"]
+TARGET_COLS = {"AC_tensile": "AC", "Subgrade_compressive": "Subgrade.2"}
+
+
+# ----------------------------------------------------------------------------
+# Physics-informed deflection basin indices
+# ----------------------------------------------------------------------------
+def basin_indices(D: np.ndarray) -> np.ndarray:
+    """D: (N, 9) deflections at SENSOR_OFFSETS_MM. Returns (N, 5) indices."""
+    d0, d200, d300, d450, d600, d900, d1200, d1500, d1800 = D.T
+    sci = d0 - d300                     # Surface Curvature Index (AC condition)
+    bdi = d300 - d600                   # Base Damage Index
+    bci = d600 - d900                   # Base Curvature Index (subbase/subgrade)
+    # AASHTO AREA parameter (normalized basin area, first 4 sensors ~ 0-600 mm here)
+    area = 6.0 * (1 + 2 * d300 / d0 + 2 * d600 / d0 + d900 / d0)
+    # AUPP: Area Under Pavement Profile — strongly correlated with AC tensile strain
+    aupp = (5 * d0 - 2 * d300 - 2 * d600 - d900) / 2.0
+    return np.stack([sci, bdi, bci, area, aupp], axis=1)
+
+
+# ----------------------------------------------------------------------------
+# Continuous positional encoding of physical sensor offsets
+# ----------------------------------------------------------------------------
+class SensorOffsetEncoding(nn.Module):
+    """Fourier features of the physical geophone offset (mm), projected to d_model.
+    Unlike integer positional encoding, this respects the true non-uniform
+    basin geometry (0,200,300,450,...) and supports arbitrary sensor arrays."""
+
+    def __init__(self, d_model: int, n_freq: int = 16, max_offset: float = 2000.0):
+        super().__init__()
+        freqs = torch.exp(torch.linspace(math.log(1.0), math.log(max_offset), n_freq))
+        self.register_buffer("freqs", freqs)
+        self.proj = nn.Linear(2 * n_freq, d_model)
+
+    def forward(self, offsets_mm: torch.Tensor) -> torch.Tensor:
+        # offsets_mm: (S,) -> (S, d_model)
+        x = offsets_mm.unsqueeze(-1) / self.freqs  # (S, n_freq)
+        feats = torch.cat([torch.sin(x), torch.cos(x)], dim=-1)
+        return self.proj(feats)
+
+
+class FiLM(nn.Module):
+    """Feature-wise linear modulation of basin tokens by the thickness code."""
+
+    def __init__(self, cond_dim: int, d_model: int):
+        super().__init__()
+        self.to_gamma_beta = nn.Linear(cond_dim, 2 * d_model)
+
+    def forward(self, tokens: torch.Tensor, cond: torch.Tensor) -> torch.Tensor:
+        gamma, beta = self.to_gamma_beta(cond).chunk(2, dim=-1)  # (B, d_model) each
+        return tokens * (1 + gamma.unsqueeze(1)) + beta.unsqueeze(1)
+
+
+# ----------------------------------------------------------------------------
+# DBFT model
+# ----------------------------------------------------------------------------
+class DBFT(nn.Module):
+    def __init__(
+        self,
+        d_model: int = 64,
+        n_heads: int = 4,
+        n_encoder_layers: int = 3,
+        n_decoder_layers: int = 2,
+        d_ff: int = 128,
+        dropout: float = 0.10,
+        n_targets: int = 2,
+        n_thickness: int = 3,
+        n_indices: int = 5,
+        use_film: bool = True,
+        use_indices: bool = True,
+        use_thickness_memory: bool = True,
+    ):
+        super().__init__()
+        self.use_film = use_film
+        self.use_indices = use_indices
+        self.use_thickness_memory = use_thickness_memory
+
+        # --- basin branch ---
+        self.deflection_embed = nn.Linear(1, d_model)
+        self.pos_enc = SensorOffsetEncoding(d_model)
+        self.register_buffer("offsets", torch.tensor(SENSOR_OFFSETS_MM))
+
+        # physics-informed index tokens
+        self.index_embed = nn.Linear(1, d_model)
+        self.index_type_embed = nn.Parameter(torch.randn(n_indices, d_model) * 0.02)
+
+        enc_layer = nn.TransformerEncoderLayer(
+            d_model, n_heads, d_ff, dropout, activation="gelu",
+            batch_first=True, norm_first=True,
+        )
+        self.basin_encoder = nn.TransformerEncoder(enc_layer, n_encoder_layers)
+
+        # --- thickness branch ---
+        self.thickness_encoder = nn.Sequential(
+            nn.Linear(n_thickness, d_model), nn.GELU(),
+            nn.Linear(d_model, d_model), nn.GELU(),
+        )
+        self.film = FiLM(d_model, d_model)
+        self.thickness_token_proj = nn.Linear(d_model, d_model)
+
+        # --- fusion decoder: learnable strain queries ---
+        self.strain_queries = nn.Parameter(torch.randn(n_targets, d_model) * 0.02)
+        dec_layer = nn.TransformerDecoderLayer(
+            d_model, n_heads, d_ff, dropout, activation="gelu",
+            batch_first=True, norm_first=True,
+        )
+        self.fusion_decoder = nn.TransformerDecoder(dec_layer, n_decoder_layers)
+
+        self.head = nn.Sequential(
+            nn.LayerNorm(d_model), nn.Linear(d_model, d_model), nn.GELU(),
+            nn.Linear(d_model, 1),
+        )
+
+    def forward(self, deflections, indices, thickness):
+        """deflections (B,9), indices (B,5), thickness (B,3) — all standardized."""
+        B = deflections.shape[0]
+
+        # basin tokens with continuous offset encoding
+        tok = self.deflection_embed(deflections.unsqueeze(-1))        # (B,9,d)
+        tok = tok + self.pos_enc(self.offsets).unsqueeze(0)           # (B,9,d)
+
+        if self.use_indices:
+            idx_tok = self.index_embed(indices.unsqueeze(-1)) + self.index_type_embed
+            tok = torch.cat([tok, idx_tok], dim=1)                    # (B,14,d)
+
+        # thickness conditioning
+        t_code = self.thickness_encoder(thickness)                    # (B,d)
+        if self.use_film:
+            tok = self.film(tok, t_code)
+
+        memory = self.basin_encoder(tok)                              # (B,S,d)
+        if self.use_thickness_memory:
+            memory = torch.cat([memory, self.thickness_token_proj(t_code).unsqueeze(1)], dim=1)
+
+        queries = self.strain_queries.unsqueeze(0).expand(B, -1, -1)  # (B,2,d)
+        decoded = self.fusion_decoder(queries, memory)                # (B,2,d)
+        return self.head(decoded).squeeze(-1)                        # (B,2)
+
+    @torch.no_grad()
+    def attention_map(self, deflections, indices, thickness):
+        """Cross-attention weights of each strain query over memory tokens
+        (last decoder layer), for interpretability."""
+        self.eval()
+        B = deflections.shape[0]
+        tok = self.deflection_embed(deflections.unsqueeze(-1))
+        tok = tok + self.pos_enc(self.offsets).unsqueeze(0)
+        if self.use_indices:
+            idx_tok = self.index_embed(indices.unsqueeze(-1)) + self.index_type_embed
+            tok = torch.cat([tok, idx_tok], dim=1)
+        t_code = self.thickness_encoder(thickness)
+        if self.use_film:
+            tok = self.film(tok, t_code)
+        memory = self.basin_encoder(tok)
+        if self.use_thickness_memory:
+            memory = torch.cat([memory, self.thickness_token_proj(t_code).unsqueeze(1)], dim=1)
+
+        x = self.strain_queries.unsqueeze(0).expand(B, -1, -1)
+        attn_out = None
+        for i, layer in enumerate(self.fusion_decoder.layers):
+            q = layer.norm1(x)
+            x = x + layer.dropout1(layer.self_attn(q, q, q, need_weights=False)[0])
+            q2 = layer.norm2(x)
+            out, w = layer.multihead_attn(q2, memory, memory,
+                                          need_weights=True, average_attn_weights=True)
+            if i == len(self.fusion_decoder.layers) - 1:
+                attn_out = w  # (B, n_targets, S_mem)
+            x = x + layer.dropout2(out)
+            x = x + layer._ff_block(layer.norm3(x))
+        return attn_out
+
+
+# ----------------------------------------------------------------------------
+# Data loading / preprocessing
+# ----------------------------------------------------------------------------
+def load_dataset(path="strain_result.xlsx"):
+    df = pd.read_csv(path) if str(path).endswith(".csv") else pd.read_excel(path)
+    D = df[DEFLECTION_COLS].to_numpy(np.float32)
+    H = df[THICKNESS_COLS].to_numpy(np.float32)
+    Y = df[list(TARGET_COLS.values())].to_numpy(np.float32)
+    I = basin_indices(D).astype(np.float32)
+    return D, I, H, Y, df
+
+
+class Standardizer:
+    def fit(self, x):
+        self.mean = x.mean(axis=0, keepdims=True)
+        self.std = x.std(axis=0, keepdims=True) + 1e-8
+        return self
+
+    def transform(self, x):
+        return (x - self.mean) / self.std
+
+    def inverse(self, x):
+        return x * self.std + self.mean

make_diagram.py

@@ -0,0 +1,59 @@
+"""Generate assets/fwd_diagram.png — schematic of the FWD test for the app."""
+
+import numpy as np
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+from matplotlib.patches import Rectangle, FancyArrowPatch
+
+plt.rcParams.update({"font.size": 11, "figure.dpi": 200})
+
+OFFSETS = [0, 200, 300, 450, 600, 900, 1200, 1500, 1800]
+
+fig, ax = plt.subplots(figsize=(11, 4.4))
+ax.set_xlim(-260, 2050)
+ax.set_ylim(-165, 105)
+ax.axis("off")
+
+# layers
+layers = [(0, -34, "#4a4a52", "AC — h$_{AC}$", "white"),
+          (-34, -76, "#c9a86a", "Base — h$_{Base}$", "#4d3d18"),
+          (-76, -124, "#e3d5b8", "Subbase — h$_{Subbase}$", "#6d5f3a"),
+          (-124, -165, "#a4b58c", "Subgrade (semi-infinite)", "#33402a")]
+for top, bot, c, lab, tc in layers:
+    ax.add_patch(Rectangle((-260, bot), 2310, top - bot, fc=c, ec="none"))
+    ax.text(2020, (top + bot) / 2, lab, ha="right", va="center",
+            fontsize=10.5, color=tc, fontweight="bold")
+
+# falling weight + plate
+ax.add_patch(Rectangle((-55, 62), 110, 34, fc="#8b95a5", ec="#5d6673"))
+ax.add_patch(FancyArrowPatch((0, 60), (0, 12), arrowstyle="-|>",
+                             mutation_scale=18, lw=2, color="#333",
+                             linestyle=(0, (4, 3))))
+ax.text(0, 100, "falling weight — 707 kPa", ha="center", fontsize=10.5)
+ax.add_patch(Rectangle((-150, 0), 300, 9, fc="#3d4451", ec="none"))
+ax.text(-170, 14, "plate r = 150 mm", ha="right", fontsize=9.5)
+
+# geophones + basin
+basin_y = [-30 * np.exp(-x / 550) for x in OFFSETS]
+ax.plot(OFFSETS, basin_y, "--", color="#ff6b6b", lw=1.8, zorder=5)
+ax.text(700, -12, "deflection basin", color="#e04848", fontsize=9.5)
+for x in OFFSETS:
+    ax.plot(x, 14, "v", ms=8, color="#10a37f" if x == 0 else "#5436da",
+            zorder=6)
+    ax.text(x, 26, f"D{x}", ha="center", fontsize=8.6)
+ax.text(1050, 55, "9 geophones record the deflection basin (μm)",
+        ha="center", fontsize=10, color="#444")
+
+# strain markers
+ax.plot(0, -32, "o", ms=10, mfc="none", mec="#ff8f8f", mew=2, zorder=6)
+ax.text(50, -28, r"$\varepsilon_t$ — AC tensile strain (fatigue)",
+        fontsize=10.5, color="#ffb3b3", fontweight="bold")
+ax.plot(0, -126, "o", ms=10, mfc="none", mec="#2e6bc4", mew=2, zorder=6)
+ax.text(50, -140, r"$\varepsilon_c$ — subgrade compressive strain (rutting)",
+        fontsize=10.5, color="#1d4e94", fontweight="bold")
+
+fig.tight_layout()
+fig.savefig("assets/fwd_diagram.png", bbox_inches="tight",
+            facecolor="white")
+print("wrote assets/fwd_diagram.png")

requirements.txt

@@ -0,0 +1,7 @@
+--extra-index-url https://download.pytorch.org/whl/cpu
+torch>=2.2
+numpy>=1.24
+shap>=0.45
+scikit-learn>=1.3
+pandas>=2.0
+matplotlib>=3.7