Upload folder using huggingface_hub

.gitattributes

@@ -33,3 +33,5 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+fig5_mls_convergence.png filter=lfs diff=lfs merge=lfs -text
+fig6_cross_operator.png filter=lfs diff=lfs merge=lfs -text

README.md

@@ -5,124 +5,166 @@ tags:
 - neural-operator
 - pde-solver
 - physics-informed
+- computational-mechanics
 - elasticity
 - linear-attention
 - transolver
+- stress-prediction
 metrics:
 - relative-l2
+model-index:
+- name: transolver-linearno-elasticity-eqreg
+  results:
+  - task:
+      type: operator-learning
+      name: Elastic von Mises stress-field prediction (Geo-FNO Elasticity)
+    dataset:
+      type: geo-fno-elasticity
+      name: Geo-FNO Elasticity (Li et al., 2022)
+    metrics:
+    - type: relative-l2
+      value: 0.00597
+      name: Test relative L2 (shipped checkpoint, mean over 200 meshes)
+    - type: r-squared
+      value: 0.99986
+      name: Pooled R^2 vs FEM ground truth
 ---
 
-# Model Card for Equilibrium-Regularized LinearNO — Elastic Stress Surrogate (Geo-FNO Elasticity)
+# Equilibrium-Regularized LinearNO — Elastic Stress Surrogate
 
-A neural-operator surrogate that predicts the per-node von Mises stress field of a hyper-elastic
-unit cell with a central void, on the **Geo-FNO Elasticity** benchmark. It maps a 2-D unstructured
-mesh (972 nodes) directly to the stress field in milliseconds on CPU, replacing a per-geometry
-finite-element (FEM) solve for fast design-space exploration.
+A neural-operator surrogate that predicts the per-node **von Mises stress field** of a hyper-elastic
+unit cell with an arbitrary central void, on the **Geo-FNO Elasticity** benchmark. It maps a 2-D
+unstructured mesh (972 nodes) directly to the stress field in **milliseconds on CPU**, replacing a
+per-geometry finite-element (FEM) solve for fast design-space exploration.
+
+Verified node-by-node against FEM: pooled **R² = 0.99986**, test relative-L2 **0.00597** on the shipped
+checkpoint. **Interactive demo:** https://huggingface.co/spaces/Efradeca/elastic-stress-surrogate
+
+> **Honesty note.** This card reports the model's limitations as prominently as its strengths. The
+> deployed value is *accuracy + speed*. The equilibrium regularizer is a well-characterized **trade-off**
+> (a prior-art idea in a new meshfree instantiation), not a free win — see *Evaluation* and *Findings*.
 
 ## Model Details
 
 ### Model Description
 
-The model is a Transolver-family transformer operator whose attention block is the asymmetric
-linear-attention operator **LinearNO**. Its distinguishing component is an **equilibrium-residual
-regularizer**: the network predicts the full stress tensor (σ_xx, σ_yy, σ_xy) and is penalized by a
-discrete divergence operator so the predicted field approaches static mechanical equilibrium
-(∇·σ ≈ 0), yielding physically consistent predictions at no measured accuracy cost.
+The model is a **Transolver-family transformer operator** whose attention block is the asymmetric
+**LinearNO** linear-attention operator. It predicts the full symmetric Cauchy stress tensor
+(σ_xx, σ_yy, σ_xy) per node; the supervised target is the derived scalar von Mises stress. Its
+distinguishing component is a soft **equilibrium-residual regularizer** — the training loss penalizes the
+discrete divergence ‖∇·σ‖² so the predicted field approaches static mechanical equilibrium (∇·σ ≈ 0),
+with the divergence discretized by a **meshfree moving-least-squares (MLS)** operator that needs no mesh
+connectivity.
 
 - **Developed by:** Efradeca
 - **Model type:** Neural operator (transformer PDE surrogate) for 2-D static hyper-elastic stress
-- **Inputs / outputs:** node coordinates (B, 972, 2) → per-node von Mises stress (B, 972)
+- **Inputs / outputs:** node coordinates `(B, 972, 2)` → per-node von Mises stress `(B, 972)`
+- **Parameters:** 582,275 (parameter-matched to the official LinearNO Elasticity configuration)
 - **License:** MIT
-- **Built on (not original to this work):** the **Transolver** solver (Wu et al., ICML 2024) and a
-  reimplementation of the **LinearNO** attention block (Hu et al., AAAI 2026). The original
-  contribution here is the equilibrium-residual regularizer and the out-of-distribution analysis.
+- **Built on (not original to this work):** the **Transolver** solver (Wu et al., ICML 2024, MIT — its
+  attention block is reused verbatim) and an independent, from-equations reimplementation of the
+  **LinearNO** attention block (Hu et al., AAAI 2026).
+
+### What is and isn't novel (read this)
+
+The soft equilibrium-residual penalty `λ‖∇·σ‖²` on a predicted stress field is **established prior art**
+(PI-UNet 2022; PiFNO 2024; and especially **P-DivGNN 2025**, which uses the same loss and the same
+three-component Cauchy-stress target on the same kind of holed mesh). We do **not** claim the idea. This
+repository's actual contribution is (1) a specific, previously-unattested **instantiation** — the penalty
+on a *transformer* operator with a *meshfree, connectivity-free* MLS divergence (exact on affine fields by
+the degree-1 GMLS reproduction property), distinct from the FE / FFT / finite-difference operators of all
+prior work — and (2) a **cross-operator honesty analysis** of when that penalty actually helps.
 
 ### Model Sources
 
-- **Papers:** Transolver (arXiv:2402.02366); LinearNO (arXiv:2511.06294); Geo-FNO dataset (arXiv:2207.05209)
-- **Demo:** https://huggingface.co/spaces/Efradeca/elastic-stress-surrogate
+- **Reference papers:** Transolver (arXiv:2402.02366, MIT); LinearNO (arXiv:2511.06294); Geo-FNO dataset
+  (arXiv:2207.05209, MIT); closest prior work P-DivGNN (arXiv:2507.05291).
+- **Interactive demo (Space):** https://huggingface.co/spaces/Efradeca/elastic-stress-surrogate
+- **Full technical report + committed evidence:** the project repository (`docs/PAPER.md`,
+  `docs/RESULTS.md`, and the `results/` run logs).
 
 ## Uses
 
 ### Direct Use
 
 Millisecond-scale, CPU prediction of the von Mises stress field of a hyper-elastic unit cell with a
-central void, for design-space exploration / shape optimization of the void (screen many candidate
-geometries, then verify the few best with FEM).
+central void — for **design-space exploration / void-shape optimization**: screen many candidate
+geometries with the surrogate, then verify only the best few with FEM.
 
 ### Downstream Use
 
-A starting point for fine-tuning to related geometries, materials, or boundary conditions, which
-requires retraining on the corresponding FEM data.
+A starting point for fine-tuning to related geometries, materials, or boundary conditions — which
+**requires retraining** on the corresponding FEM data.
 
 ### Out-of-Scope Use
 
-This is a narrow surrogate, not a general stress solver. It is **not** valid, without retraining,
-for other materials (e.g. steel), other boundary conditions, or geometries outside the training
-distribution, and it must not be used as a certified solver for safety-critical decisions.
+This is a **narrow surrogate, not a general stress solver**. Without retraining it is **not** valid for
+other materials (e.g. steel), other boundary conditions, or geometries outside the training distribution,
+and it **must not** be used as a certified solver for safety-critical decisions.
 
 ## Bias, Risks, and Limitations
 
-- **Narrow domain:** a single benchmark, one hyper-elastic (rubber-like) material, one geometry
-  family (unit cell, central void, radius 0.2–0.4, clamped bottom, tensile top).
-- **Run-to-run variance:** the training set is small (1000 samples), so per-seed results vary
-  noticeably; results are reported as mean ± std with the full per-seed distribution (see Evaluation).
-- **Reimplemented component:** LinearNO has no official public reference implementation; it was
-  reproduced from the paper's equations.
-- **Regularizer scope:** the supervised target is scalar von Mises stress; the tensor components are
-  latent and shaped by a *discrete* ∇·σ penalty (validated against analytic fields), which is a
-  physical-consistency prior, not exact continuous momentum balance.
-- **Out-of-distribution:** accuracy degrades on geometries far from the training distribution
-  (extreme voids); the regularizer maintains physical consistency OOD but does not improve OOD accuracy.
+- **Narrow domain.** One benchmark, one hyper-elastic (rubber-like Rivlin–Saunders) material, one geometry
+  family (unit cell, central void, radius 0.2–0.4, clamped bottom, tensile top). Not a foundation model.
+- **Units.** Stress is in **consistent non-dimensional benchmark units, not MPa** (traction = 100,
+  C₁ = 1.86×10⁵); a physical-units result requires re-scaling to the target material.
+- **Run-to-run variance.** The training set is small (1000 samples), so per-seed results vary noticeably.
+  We report median + mean ± std with the **full per-seed distribution** and do not hide outliers. The
+  shipped checkpoint is the **best of 3** eqreg seeds (0.00597 < 0.00653 < 0.00754).
+- **Regularizer scope.** The supervised target is scalar von Mises; the tensor components are *latent*,
+  shaped by a *discrete* ∇·σ penalty (a physical-consistency prior, not exact continuous momentum balance).
+- **The physics benefit is a trade-off, and partly operator-specific.** See *Evaluation → Findings*: the
+  large residual reduction is mostly measured by the model's own operator, it costs ~+30% accuracy, and it
+  nearly vanishes when the stress tensor is directly supervised.
+- **Out-of-distribution.** Accuracy degrades on geometries far from the training distribution (extreme
+  voids). The regularizer keeps *its own MLS* residual low OOD, but — per the cross-operator analysis —
+  that consistency gain is itself largely operator-specific, and it does **not** improve OOD accuracy.
 
 ### Recommendations
 
-Use within the training distribution; verify any safety-critical prediction with FEM; monitor the
-equilibrium residual ‖∇·σ‖² as a physical-consistency indicator.
+Use within the training distribution; verify any safety-critical prediction with FEM; treat the
+equilibrium residual ‖∇·σ‖² as a physical-consistency indicator, not a correctness guarantee.
 
 ## How to Get Started with the Model
 
 ```python
 from huggingface_hub import snapshot_download
-from model import load_checkpoint, predict_stress   # bundled with the repo
+import sys
 
 repo = snapshot_download("Efradeca/transolver-linearno-elasticity")
+sys.path.insert(0, repo)                              # model.py is bundled with the repo
+from model import load_checkpoint, predict_stress
+
 model, normalizer, info = load_checkpoint(f"{repo}/model.safetensors", device="cpu")
 
 # coords: (N, 2) node coordinates of a unit cell with a central void
-stress = predict_stress(model, coords, normalizer, info)   # (N,) von Mises stress
+stress = predict_stress(model, coords, normalizer, info)   # (N,) von Mises stress, CPU, < 50 ms
 ```
 
 ## Training Details
 
 ### Training Data
 
-Geo-FNO Elasticity (Li et al., 2022, arXiv:2207.05209): FEM simulations of an incompressible
-hyper-elastic (Rivlin–Saunders, `C₁=1.86e5`, `C₂=9.79e3`) `[0,1]²` unit cell with a random central
-void (radius 0.2–0.4), 972 nodes per sample; target = per-node von Mises stress. Split: 1000 train /
-200 test (first-1000 / last-200 of 2000, upstream Transolver protocol).
+**Geo-FNO Elasticity** (Li et al., 2022, arXiv:2207.05209, MIT): FEM simulations of an incompressible
+Rivlin–Saunders hyper-elastic (`C₁ = 1.863×10⁵`, `C₂ = 9.79×10³`) `[0,1]²` unit cell with a random central
+void (radius 0.2–0.4), 972 nodes per sample; target = per-node von Mises stress. Split: **1000 train /
+200 test** (first-1000 / last-200 of 2000, the upstream Transolver protocol).
 
-**Fixed boundary conditions (identical for every sample):** the bottom edge is **clamped**
-(zero displacement) and a uniform **tensile traction `t = [0, 100]` is applied on the top edge** (`+y`);
-left/right edges are free. **Units are non-dimensional benchmark units (not MPa).** The model's only
-input is the 972 node coordinates — the loads/supports are *not* inputs (they are constant across the
-dataset; only the void geometry varies).
+**Fixed boundary conditions (identical for every sample):** the bottom edge is **clamped** (zero
+displacement) and a uniform **tensile traction `t = [0, 100]`** acts on the top edge (`+y`); left/right
+edges are free. The model's only input is the 972 node coordinates — loads, supports, and material are
+**not** inputs (they are constant; only the void geometry varies).
 
 ### Training Procedure
 
-#### Preprocessing
-
-Global z-score normalization of the stress target (de-normalized before the metric). The
-equilibrium-regularized model outputs three stress-tensor channels and derives von Mises.
-
-#### Training Hyperparameters
-
-- **Architecture:** 8 layers, hidden dim 128, 8 heads, dim_head 16, slices M = 64;
-  attention `linearno` (variant `shared_qk`, project_out=`False`)
-- **Optimization:** AdamW, lr 1e-3, weight decay 1e-5, cosine annealing, 500 epochs, batch size 1,
-  gradient clipping 0.1
-- **Loss:** relative L2 + λ·‖∇·σ‖² on interior nodes (λ = 0.01)
-- **Seeds:** {0, 1, 2} (mean ± std reported)
+- **Preprocessing:** global z-score normalization of the target (de-normalized before the metric). The
+  regularized model outputs 3 stress-tensor channels and derives von Mises.
+- **Hyperparameters:** 8 layers, hidden 128, 8 heads, `dim_head` 16, `M = 64` slices; `shared_qk` LinearNO
+  attention, 3-channel output. AdamW (lr 1e-3, weight decay 1e-5), cosine annealing, **500 epochs**, batch
+  size 1, gradient clipping 0.1.
+- **Loss:** relative-L2 (on von Mises) + `λ·‖∇·σ‖²` on interior nodes, **λ = 0.01**, MLS divergence with
+  `k = 12` neighbors.
+- **Compute:** single NVIDIA A10 GPU (Modal); total project compute ≈ $90. CPU inference for the demo.
 
 ## Evaluation
 
@@ -130,70 +172,102 @@ equilibrium-regularized model outputs three stress-tensor channels and derives v
 
 - **Testing data:** the 200 held-out FEM meshes.
 - **Factors:** in-distribution vs. out-of-distribution (geometry-stratified by void size).
-- **Metrics:** relative L2 (primary); the discrete equilibrium residual ‖∇·σ‖²; per-node Pearson r
-  and R² against the FEM ground truth; peak-stress relative error.
+- **Metrics:** relative-L2 (primary); the discrete equilibrium residual ‖∇·σ‖²; pooled Pearson r and R²
+  vs. FEM; peak-stress relative error.
 
-### Results
+### Results (Geo-FNO Elasticity test relative L2)
 
-Geo-FNO Elasticity test relative L2. We report **median** (robust to the high run-to-run variance of
-this 1000-sample benchmark) alongside mean ± std and the seed count; full committed per-seed
-distributions are in the repository (`docs/RESULTS.md`, `results/study_summary.json`). The
-accuracy-comparison rows (baseline, LinearNO M=64/M=256) use `torch.compile`; the
-equilibrium-regularized row is eager (`compile:false`). The baseline reproduces the published 0.0064
-on its good seeds.
+We report **median** (robust to this dataset's high run-to-run variance) alongside mean ± std and seed
+count `n`. Accuracy-comparison rows use `torch.compile`; the equilibrium-regularized row is eager. Full
+committed per-seed distributions are in the repository (`docs/RESULTS.md`, `results/`).
 
 | Model | median | mean ± std | n | params |
 |---|---|---|---|---|
 | Published Transolver (Wu et al. 2024) | — | 0.0064 | — | ~0.7M |
 | Published LinearNO (Hu et al. 2026, M=64) | — | 0.0050 | — | — |
-| Transolver baseline (this work) | 0.00766 | 0.00827 ± 0.0022 | 6 | 713,665 |
-| LinearNO, M=64 (this work) | **0.00606** | 0.00645 ± 0.0017 | 8 | 713,089 |
-| LinearNO, M=256 (this work) | 0.00635 | 0.00622 ± 0.0007 | 3 | 765,313 |
-| **+ equilibrium regularizer (this model)** | 0.00653 | 0.00668 ± 0.0006 | 3 | 582,275 |
-
-**Controlled comparison (with appropriate caution).** In this sample, LinearNO's median error
-(0.00606) is lower than our reproduced baseline's (0.00766) at fewer parameters, and LinearNO reaches
-the published LinearNO/Transolver level on its good seeds (best run, M=256: **0.00529**). However, both
-models show **high run-to-run variance** (`torch.compile` non-determinism on a 1000-sample dataset),
-and the baseline's higher mean is driven by 2 outlier seeds. We **do not** claim LinearNO "beats" the
-baseline or is "more robust": with these seed counts (6 vs. 8) the difference may partly reflect
-sampling noise, and an attempted mechanistic explanation (degenerate slice assignments in the
-baseline's slice self-attention) was **empirically tested and refuted** — the outlier seed is a generic
-poor-generalization minimum (healthy train loss, worse test loss), not a slice-attention failure. The
-honest reading is that LinearNO is **comparable to** the baseline at ≤ its parameters, both reproducing
-~0.0064 on good seeds.
-
-**Physical consistency.** The regularizer reduces the discrete equilibrium residual ‖∇·σ‖² by
-**~360×** (6.1e6 → 1.7e4) at no measured accuracy cost, and this consistency is maintained
-out-of-distribution (OOD residual 1.73e4 vs. in-distribution 1.61e4).
-
-**Verification against FEM ground truth** (200 test meshes): per-sample relative L2 mean 0.00597
-(median 0.00533), pooled Pearson r = 0.9999, R² = 0.9999, peak-stress relative error 0.3%.
-
-#### Summary
-
-Over 6–8 seeds under identical conditions, LinearNO is **comparable to** the reproduced Transolver
-baseline (lower median in this sample, but within the high run-to-run variance), at ≤ its parameter
-count. The original contribution of this checkpoint is physical consistency: the equilibrium
-regularizer makes the predicted stress field satisfy discrete static equilibrium (∇·σ ≈ 0) at no
-measured accuracy cost — a property maintained under geometric covariate shift and verified node-by-node
-against FEM (R² = 0.9999).
+| Transolver baseline (this work) | 0.00766 | 0.00827 ± 0.00222 | 6 | 713,665 |
+| LinearNO, M=64 (this work) | **0.00606** | 0.00645 ± 0.00173 | 8 | 713,089 |
+| LinearNO, M=256 (this work) | 0.00635 | 0.00622 ± 0.00071 | 3 | 765,313 |
+| **+ equilibrium regularizer (this model)** | 0.00653 | 0.00668 ± 0.00065 | 3 | 582,275 |
+
+**Comparable, not "beats."** In this sample LinearNO's median (0.00606) is lower than our reproduced
+baseline's (0.00766) at fewer parameters, and it reaches the published ~0.0050 level on good seeds. But
+both models have **high run-to-run variance** (`torch.compile` non-determinism on 1000 samples), and the
+baseline's higher mean is driven by 2 outlier seeds. We do **not** claim LinearNO beats or is more robust
+than the baseline; an attempted mechanistic explanation (slice-attention instability) was **empirically
+tested and refuted**. Honest reading: LinearNO is **comparable** to the baseline at ≤ its parameters, both
+reproducing ~0.0064 on good seeds. As a cross-check, we re-evaluated the authors' released official
+checkpoint on our data with their code and reproduced **0.005007** — confirming the dataset, split, and
+metric are identical, so the table is mutually comparable.
+
+**Verification against FEM ground truth** (200 test meshes; shipped checkpoint = best of 3 eqreg seeds):
+per-sample relative-L2 mean **0.00597** (median 0.00533), pooled Pearson **r = 0.99993**, **R² = 0.99986**,
+peak-stress relative error **0.27%** — reproducible via `scripts/verify_model.py` → `results/verify_model.json`.
+
+### Findings (the honest part)
+
+**1. The meshfree MLS operator is rigorously grounded.** It is a degree-1 GMLS derivative: *exact on
+affine fields* (~1e-14 in float64) and *O(h)-convergent* on smooth fields (fitted slope 1.01), validated
+on connectivity-free point clouds — no mesh required.
+
+![MLS operator O(h) validation](fig5_mls_convergence.png)
+
+**2. The headline residual reduction is largely operator-specific ("gaming").** On a clean,
+same-architecture, epoch-matched ablation the regularizer cuts the residual **~325× as measured by the
+model's own (MLS) operator**, but an **independent FE operator** sees only **~6–53×** — at a **measured
+accuracy cost** (test rel-L2 0.00479 → 0.00621, +30%). A model-free control on exactly-divergence-free
+analytic fields confirms the FE operator is *comparable* to MLS off the void-rim slivers (the large raw
+gap is a sliver artifact), so the honest operator-agnostic reduction (~53×) still sits **an order of
+magnitude below** the trained-operator 325×. The gaming reproduces on the *literal* official LinearNO
+block (gap ~25×), so it is a property of the soft-penalty objective, not our implementation.
+
+![cross-operator gaming](fig6_cross_operator.png)
+
+**3. On a supervised tensor the effect nearly vanishes.** On a second benchmark, **Tensile2d** (PLAID),
+where the full Cauchy tensor is *directly supervised*, the gaming gap collapses to **~1.3×** and the
+regularizer becomes nearly redundant — the supervised data already pins the field near its
+discrete-equilibrium floor. (This Tensile2d transfer is a **single-seed indicative** result and is **not**
+comparable to the PLAID Tensile2d leaderboard, which scores a different RRMSE metric on a withheld test.)
+
+**4. Out-of-distribution: a reported negative result.** The regularizer does **not** improve OOD accuracy
+(degradation +51.5% vs. LinearNO's +52.8%; the plain baseline degrades least, +45.1%). It keeps *its own*
+equilibrium residual low OOD (+7%), but on an orthogonal field-smoothness proxy it is indistinguishable
+from the unregularized models.
+
+**Takeaway:** the soft equilibrium penalty looks most impressive exactly where it is least physical (an
+unsupervised latent tensor). We report this rather than paper over it. The deployed model's value is its
+accuracy (R² = 0.99986) and millisecond CPU speed.
 
 ## Technical Specifications
 
 ### Model Architecture and Objective
 
-Transolver-family transformer (encoder → 8 pre-norm blocks → linear decoder head) with the LinearNO
-asymmetric linear-attention block; objective = relative-L2 data loss + equilibrium-residual penalty.
+Transolver-family transformer (coordinate encoder → 8 pre-norm blocks → linear decoder head) with the
+LinearNO asymmetric linear-attention block `φ(Q)·(ψᵀ(K)·V)` (φ softmax over the M slices, ψ over the N
+points). Objective = relative-L2 data loss on von Mises + λ·‖∇·σ‖² equilibrium penalty (meshfree MLS
+divergence). Output: 3 latent Cauchy-stress channels → von Mises.
 
 ### Compute Infrastructure
 
-- **Hardware:** single NVIDIA A10 GPU (Modal).
-- **Software:** PyTorch, einops, safetensors; CPU inference for the demo.
+- **Hardware:** single NVIDIA A10 GPU (Modal) for training; CPU for demo inference.
+- **Software:** PyTorch, einops, safetensors.
+
+## Licenses & Attribution
+
+This model, its weights, and the bundled architecture code are **MIT**-licensed. It builds on and uses
+data from the following sources — please honor their licenses:
+
+- **Transolver** (Wu et al., ICML 2024) — attention block reused verbatim, **MIT**.
+- **Geo-FNO Elasticity** dataset (Li et al., 2022) — the training/evaluation data, **MIT**.
+- **Tensile2d** — the second-benchmark data ([`PLAID-datasets/Tensile2d`](https://huggingface.co/datasets/PLAID-datasets/Tensile2d),
+  Casenave et al.), licensed **CC-BY-SA-4.0**. Any derived Tensile2d fields we redistribute (e.g. the demo
+  data in the companion Space) are shared under the **same CC-BY-SA-4.0 (share-alike)** with attribution.
+  The MIT license of this model applies to the code and weights, **not** to the CC-BY-SA-4.0 Tensile2d data.
 
 ## Citation
 
-**BibTeX:**
+If you use this model, please cite the underlying works.
+
 ```bibtex
 @inproceedings{wu2024transolver,
   title={Transolver: A Fast Transformer Solver for PDEs on General Geometries},
@@ -213,12 +287,14 @@ asymmetric linear-attention block; objective = relative-L2 data loss + equilibri
   journal={arXiv:2207.05209},
   year={2022}
 }
+@article{guevaragarban2025pdivgnn,
+  title={Physics-Informed Graph Neural Networks to Reconstruct Local Fields Considering Finite Strain Hyperelasticity},
+  author={Guevara Garban, Manuel R. and Chemisky, Yves and others},
+  journal={arXiv:2507.05291},
+  year={2025}
+}
 ```
 
-## Model Card Authors
-
-Efradeca.
-
-## Model Card Contact
+## Model Card Authors & Contact
 
-https://huggingface.co/Efradeca
+Efradeca — https://huggingface.co/Efradeca

stress_operator/data/tensile2d.py

@@ -0,0 +1,137 @@
+"""Tensile2d (PLAID-datasets/Tensile2d, HF, CC-BY-SA-4.0) adapter — SECOND benchmark.
+
+Why: unlike Geo-FNO Elasticity (scalar von Mises target -> our tensor is latent), Tensile2d directly
+supervises the full 2D Cauchy stress tensor (sig11, sig22, sig12) per node on an irregular mesh, so our
+equilibrium regularizer acts on a SUPERVISED tensor and we can validate the predicted tensor itself.
+
+VERIFIED facts (golden rule, by reading real samples):
+  - Each sample is a pickled CGNS tree (no PLAID lib needed): GridCoordinates {CoordinateX, CoordinateY}
+    and PointData {sig11, sig22, sig12, U1, U2, q}; plus input scalars {P, p1..p5} and output scalars.
+  - 702 rows: samples 0-499 are the labeled `train_500` set (full stress); samples 500-701 (test 200 +
+    OOD 2) have stress fields WITHHELD (competition) -> only coords + input scalars. So we use the 500
+    labeled samples and hold out a local test split (no official test ground truth is public).
+  - Node count varies per sample (6143-11801, mean ~9400). Static, plane-strain, quasistatic.
+
+`build_cache()` writes data/tensile2d/samples/*.npz once. `build_tensile_splits()` loads them, fits
+z-score normalizers on the train split, and returns per-sample lists (variable N -> no stacking).
+"""
+from __future__ import annotations
+
+import glob
+import os
+from dataclasses import dataclass
+from typing import List
+
+import numpy as np
+import torch
+
+INPUT_SCALARS = ["P", "p1", "p2", "p3", "p4", "p5"]
+
+
+def _field(tree, name):
+    stack = [tree]
+    while stack:
+        n = stack.pop()
+        if isinstance(n, list) and len(n) == 4:
+            if n[0] == name and isinstance(n[1], np.ndarray):
+                return n[1]
+            stack.extend(n[2] or [])
+    return None
+
+
+def build_cache(out_dir: str = "data/tensile2d/samples") -> int:
+    """Download Tensile2d parquet shards and cache the 500 labeled samples as .npz. Returns count."""
+    from huggingface_hub import hf_hub_download
+    import pyarrow.parquet as pq
+    import pickle
+
+    os.makedirs(out_dir, exist_ok=True)
+    shards = [hf_hub_download("PLAID-datasets/Tensile2d",
+                              f"data/all_samples-0000{i}-of-00002.parquet", repo_type="dataset")
+              for i in (0, 1)]
+    idx = 0
+    saved = 0
+    for sh in shards:
+        col = pq.read_table(sh).column("sample")
+        for i in range(len(col)):
+            try:
+                obj = pickle.loads(col[i].as_py())
+                tree = list(obj["meshes"].values())[0]
+                x, y = _field(tree, "CoordinateX"), _field(tree, "CoordinateY")
+                s11, s22, s12 = _field(tree, "sig11"), _field(tree, "sig22"), _field(tree, "sig12")
+                if any(v is None for v in (x, y, s11, s22, s12)):
+                    idx += 1
+                    continue  # withheld test/OOD sample
+                coords = np.stack([x, y], 1).astype(np.float32)
+                sigma = np.stack([s11, s22, s12], 1).astype(np.float32)
+                vm = np.sqrt(s11 ** 2 - s11 * s22 + s22 ** 2 + 3 * s12 ** 2).astype(np.float32)
+                sc = obj.get("scalars", {})
+                scin = np.array([float(sc[k]) for k in INPUT_SCALARS], np.float32)
+                np.savez(os.path.join(out_dir, f"{saved:04d}.npz"),
+                         coords=coords, sigma=sigma, vm=vm, scalars_in=scin)
+                saved += 1
+            except Exception:
+                pass
+            idx += 1
+    return saved
+
+
+@dataclass
+class TensileSplits:
+    train_coords: List[torch.Tensor]
+    train_sigma: List[torch.Tensor]     # scaled by 1/S (N,3)
+    train_scalars: List[torch.Tensor]   # z-scored (6,)
+    test_coords: List[torch.Tensor]
+    test_sigma: List[torch.Tensor]
+    test_scalars: List[torch.Tensor]
+    scale_S: float                      # SINGLE global stress scale; de-normalize: sigma*S
+    scalar_mean: torch.Tensor           # (6,)
+    scalar_std: torch.Tensor
+
+
+def build_tensile_splits(samples_dir: str = "data/tensile2d/samples",
+                         ntrain: int = 400, ntest: int = 100, seed: int = 0) -> TensileSplits:
+    """Load cached samples; deterministic train/test split; z-score normalizers fit on TRAIN only.
+
+    Coords are kept RAW (physical units) so the MLS divergence operator measures true distances; the
+    model conditions on raw coords + normalized input scalars (the encoder MLP handles the coord scale).
+    Stress is z-scored per component; input scalars z-scored per dim.
+    """
+    files = sorted(glob.glob(os.path.join(samples_dir, "*.npz")))
+    if not files:
+        raise FileNotFoundError(f"no cached Tensile2d samples in {samples_dir} — run build_cache() first")
+    rng = np.random.default_rng(seed)
+    order = rng.permutation(len(files))
+    tr_idx, te_idx = order[:ntrain], order[ntrain:ntrain + ntest]
+
+    def load(i):
+        d = np.load(files[i])
+        return d["coords"], d["sigma"], d["scalars_in"]
+
+    tr = [load(i) for i in tr_idx]
+    te = [load(i) for i in te_idx]
+
+    # SINGLE global stress scale S (RMS of all train stress components) so the divergence regularizer
+    # de-normalizes with one scalar: sigma_phys = S * sigma_norm  =>  div(sigma_phys) = S * div(sigma_norm).
+    # (Per-component z-score would scale each channel differently and corrupt the physical divergence.)
+    sig_all = np.concatenate([s for _, s, _ in tr], 0)            # (sum N, 3)
+    S = float(np.sqrt((sig_all ** 2).mean()))                    # global RMS scale
+    sc_all = np.stack([sc for _, _, sc in tr], 0)                 # (ntrain, 6)
+    sc_mean, sc_std = sc_all.mean(0), sc_all.std(0) + 1e-8
+
+    def pack(rows):
+        cs, ss, scs = [], [], []
+        for c, s, sc in rows:
+            cs.append(torch.tensor(c))
+            ss.append(torch.tensor(s / S))
+            scs.append(torch.tensor((sc - sc_mean) / sc_std))
+        return cs, ss, scs
+
+    trc, trs, trsc = pack(tr)
+    tec, tes, tesc = pack(te)
+    return TensileSplits(
+        train_coords=trc, train_sigma=trs, train_scalars=trsc,
+        test_coords=tec, test_sigma=tes, test_scalars=tesc,
+        scale_S=S,
+        scalar_mean=torch.tensor(sc_mean), scalar_std=torch.tensor(sc_std),
+    )

stress_operator/losses/equilibrium.py

@@ -40,7 +40,7 @@ def knn_indices(coords: np.ndarray, k: int) -> Tuple[np.ndarray, np.ndarray]:
 
 
 def build_mls_gradient_operators(
-    coords: torch.Tensor, k: int = 12, eps: float = 1e-9
+    coords: torch.Tensor, k: int = 12, eps: float = 1e-9, dtype: torch.dtype = torch.float32
 ) -> Tuple[torch.Tensor, torch.Tensor]:
     """Build dense (N, N) operators Gx, Gy with (Gx @ f) ~ df/dx and (Gy @ f) ~ df/dy.
 
@@ -67,11 +67,44 @@ def build_mls_gradient_operators(
         Gy[i, nbr] += C[:, 1]
         Gy[i, i] -= C[:, 1].sum()
     return (
-        torch.tensor(Gx, dtype=torch.float32, device=coords.device),
-        torch.tensor(Gy, dtype=torch.float32, device=coords.device),
+        torch.tensor(Gx, dtype=dtype, device=coords.device),
+        torch.tensor(Gy, dtype=dtype, device=coords.device),
     )
 
 
+def build_mls_gradient_operators_sparse(coords: torch.Tensor, k: int = 12, eps: float = 1e-9):
+    """Sparse (N,N) MLS gradient operators, built directly without the dense intermediate.
+
+    Identical stencils to build_mls_gradient_operators (k+1 nonzeros per row) but assembled as COO,
+    so it scales to large meshes (e.g. Tensile2d's ~9k-12k nodes, where a dense (N,N) is ~0.7 GB).
+    """
+    cpu = coords.detach().cpu().numpy().astype(np.float64)
+    n = cpu.shape[0]
+    dist, idx = knn_indices(cpu, k)
+    sigma2 = float((dist.mean()) ** 2) + eps
+    rows = np.empty(n * (k + 1), dtype=np.int64)
+    cols = np.empty(n * (k + 1), dtype=np.int64)
+    vx = np.empty(n * (k + 1), dtype=np.float64)
+    vy = np.empty(n * (k + 1), dtype=np.float64)
+    p = 0
+    for i in range(n):
+        nbr = idx[i]
+        d = cpu[nbr] - cpu[i]
+        w = np.exp(-(d ** 2).sum(1) / sigma2)
+        A = np.einsum("k,ka,kb->ab", w, d, d)
+        C = (w[:, None] * d) @ np.linalg.pinv(A)     # (k, 2)
+        m = k + 1
+        rows[p:p + m] = i
+        cols[p:p + k] = nbr; cols[p + k] = i
+        vx[p:p + k] = C[:, 0]; vx[p + k] = -C[:, 0].sum()
+        vy[p:p + k] = C[:, 1]; vy[p + k] = -C[:, 1].sum()
+        p += m
+    ij = torch.tensor(np.stack([rows, cols]), device=coords.device)
+    Gx = torch.sparse_coo_tensor(ij, torch.tensor(vx, dtype=torch.float32), (n, n)).coalesce()
+    Gy = torch.sparse_coo_tensor(ij, torch.tensor(vy, dtype=torch.float32), (n, n)).coalesce()
+    return Gx.to(coords.device), Gy.to(coords.device)
+
+
 def build_graph_laplacian(coords: torch.Tensor, k: int = 12, eps: float = 1e-9) -> torch.Tensor:
     """Unnormalized graph Laplacian L = D - W with Gaussian kNN weights (Approach B)."""
     cpu = coords.detach().cpu().numpy().astype(np.float64)
@@ -93,11 +126,30 @@ def interior_mask(coords: torch.Tensor, tol: float = 0.03) -> torch.Tensor:
 
     The outer-box boundary carries the applied traction / clamp, where div(sigma)=0 need not
     hold; interior nodes (including those around the void) are valid for the constraint.
+    NOTE: assumes the Geo-FNO Elasticity [0,1]^2 unit cell. For arbitrary geometries (e.g. Tensile2d
+    on [-1,1]^2 with an irregular free surface) use ``interior_mask_knn`` instead.
     """
     x, y = coords[..., 0], coords[..., 1]
     return (x > tol) & (x < 1 - tol) & (y > tol) & (y < 1 - tol)
 
 
+def interior_mask_knn(coords: torch.Tensor, k: int = 12, thresh: float = 0.5) -> torch.Tensor:
+    """Geometry-agnostic, connectivity-free interior mask via k-NN stencil symmetry.
+
+    A node deep in the interior has neighbors roughly symmetric around it, so the offset of its
+    k-NN centroid is small relative to the mean neighbor distance; a boundary/free-surface node has
+    one-sided neighbors and a large centroid offset (where the MLS gradient is also least reliable).
+    Interior iff ``||mean(neighbors) - node|| / mean_neighbor_dist < thresh``. Works for any mesh.
+    """
+    cpu = coords.detach().cpu().numpy().astype(np.float64)
+    dist, idx = knn_indices(cpu, k)
+    nbr = cpu[idx]                                   # (N, k, 2)
+    centroid = nbr.mean(axis=1)                      # (N, 2)
+    offset = np.linalg.norm(centroid - cpu, axis=1)  # (N,)
+    scale = dist.mean(axis=1) + 1e-12                # (N,)
+    return torch.tensor((offset / scale) < thresh, device=coords.device)
+
+
 def divergence(stress3: torch.Tensor, Gx: torch.Tensor, Gy: torch.Tensor) -> torch.Tensor:
     """Divergence of the symmetric 2x2 stress tensor field.
 

stress_operator/losses/fe_divergence.py

@@ -0,0 +1,80 @@
+"""FE shape-function divergence operator (the P-DivGNN-style operator), for the head-to-head ablation.
+
+P-DivGNN computes div(sigma) with **FE P1 shape-function gradients on a mesh**; we use a **meshfree MLS**
+gradient that needs no connectivity. To isolate that single difference, this module builds an FE nodal
+gradient operator on the SAME points (via a Delaunay triangulation), so we can compare both operators'
+divergence residuals on identical predicted stress fields. The FE operator REQUIRES connectivity (the
+triangulation); the MLS operator does not — that is the differentiating point.
+
+Build is analogous to build_mls_gradient_operators: returns dense (N,N) Gx_fe, Gy_fe with
+(Gx_fe @ f) ~ df/dx via area-weighted recovery of per-triangle P1 gradients. Exact on affine fields
+(P1 elements reproduce linear fields exactly) — verified in tests.
+"""
+from __future__ import annotations
+
+import numpy as np
+import torch
+from scipy.spatial import Delaunay
+
+
+def build_fe_gradient_operators(coords: torch.Tensor):
+    """Dense (N,N) FE nodal-gradient operators from a Delaunay triangulation of `coords` (N,2)."""
+    pts = coords.detach().cpu().numpy().astype(np.float64)
+    n = pts.shape[0]
+    tri = Delaunay(pts).simplices  # (T,3)
+    Gx = np.zeros((n, n)); Gy = np.zeros((n, n)); wsum = np.zeros(n)
+    for t in tri:
+        i0, i1, i2 = t
+        p0, p1, p2 = pts[i0], pts[i1], pts[i2]
+        # 2*signed area
+        det = (p1[0] - p0[0]) * (p2[1] - p0[1]) - (p2[0] - p0[0]) * (p1[1] - p0[1])
+        if abs(det) < 1e-14:
+            continue
+        area = 0.5 * abs(det)
+        # P1 shape-function gradients (constant per triangle): grad N_i = (b_i, c_i)/(2A_signed)
+        # b_i = y_{i+1}-y_{i+2}, c_i = x_{i+2}-x_{i+1} (cyclic), using signed 2A=det
+        bs = [p1[1] - p2[1], p2[1] - p0[1], p0[1] - p1[1]]
+        cs = [p2[0] - p1[0], p0[0] - p2[0], p1[0] - p0[0]]
+        for local, node in enumerate(t):
+            gx = bs[local] / det
+            gy = cs[local] / det
+            # area-weighted nodal recovery: each incident node gets this triangle's (constant) gradient
+            for lv, nv in enumerate(t):
+                Gx[node, nv] += area * (bs[lv] / det)
+                Gy[node, nv] += area * (cs[lv] / det)
+            wsum[node] += area
+    nz = wsum > 0
+    Gx[nz] /= wsum[nz, None]
+    Gy[nz] /= wsum[nz, None]
+    return (torch.tensor(Gx, dtype=torch.float64), torch.tensor(Gy, dtype=torch.float64))
+
+
+def build_fe_gradient_operators_sparse(coords: torch.Tensor):
+    """Sparse FE nodal-gradient operators (same stencils as the dense builder), for large meshes."""
+    pts = coords.detach().cpu().numpy().astype(np.float64)
+    n = pts.shape[0]
+    tri = Delaunay(pts).simplices
+    rows, cols, vx, vy = [], [], [], []
+    wsum = np.zeros(n)
+    for t in tri:
+        i0, i1, i2 = t
+        p0, p1, p2 = pts[i0], pts[i1], pts[i2]
+        det = (p1[0] - p0[0]) * (p2[1] - p0[1]) - (p2[0] - p0[0]) * (p1[1] - p0[1])
+        if abs(det) < 1e-14:
+            continue
+        area = 0.5 * abs(det)
+        bs = [p1[1] - p2[1], p2[1] - p0[1], p0[1] - p1[1]]
+        cs = [p2[0] - p1[0], p0[0] - p2[0], p1[0] - p0[0]]
+        for node in t:
+            wsum[node] += area
+            for lv, nv in enumerate(t):
+                rows.append(node); cols.append(nv)
+                vx.append(area * bs[lv] / det); vy.append(area * cs[lv] / det)
+    ij = torch.tensor(np.array([rows, cols]))
+    Gx = torch.sparse_coo_tensor(ij, torch.tensor(vx), (n, n)).coalesce()
+    Gy = torch.sparse_coo_tensor(ij, torch.tensor(vy), (n, n)).coalesce()
+    w = torch.tensor(np.where(wsum > 0, wsum, 1.0))
+    # normalize each row i by wsum[i]
+    Gx = torch.sparse_coo_tensor(Gx.indices(), Gx.values() / w[Gx.indices()[0]], (n, n)).coalesce()
+    Gy = torch.sparse_coo_tensor(Gy.indices(), Gy.values() / w[Gy.indices()[0]], (n, n)).coalesce()
+    return Gx.to(coords.device), Gy.to(coords.device)

stress_operator/models/linear_no.py

@@ -3,7 +3,11 @@
 Reimplemented from the equations of:
     "Transolver is a Linear Transformer: Revisiting Physics-Attention through the Lens of
      Linear Attention" — Hu, Liu, Qiao, Sun, Dou (NUDT), AAAI 2026, arXiv:2511.06294.
-There is no official public repo; only the attention block differs from Transolver.
+Reconstructed from the equations BEFORE the official code was released (github.com/HiPRL/LinearNO,
+Jan 2026); we did not consult it. A post-hoc check confirms structural agreement (softmax axes,
+associativity). Differences from the official Elasticity block: it adds a learnable per-head softmax
+temperature (init 0.5, clamped [0.01,1]) that we omit, and uses one shared in_project_x lift + small
+per-head q/k/v maps vs our full C->inner projections. Only the attention block differs from Transolver.
 
 Core idea: Physics-Attention is the special case of linear attention
 ``Attention(Q,K,V) ~ phi(Q) (psi^T(K) V)`` in which (a) phi and psi come from the SAME linear
@@ -50,12 +54,19 @@ class LinearNO(nn.Module):
         dropout=0.0,
         variant: str = "independent",
         project_out: bool = True,
+        temperature: bool = False,
     ):
         super().__init__()
         inner = heads * dim_head
         self.h, self.m, self.dh = heads, slice_num, dim_head
         self.variant = variant
         self.project_out = project_out
+        self.temperature = temperature
+        if temperature:
+            # Matches the official LinearNO `temp` block: learnable per-head temperature on both
+            # softmaxes, init 0.5, clamped to [0.01, 1] (github.com/HiPRL/LinearNO).
+            self.temp_q = nn.Parameter(torch.ones(1, heads, 1, 1) * 0.5)
+            self.temp_k = nn.Parameter(torch.ones(1, heads, 1, 1) * 0.5)
 
         if variant == "independent":
             # Independent Q, K, V projections (paper modification 1, literal).
@@ -93,8 +104,13 @@ class LinearNO(nn.Module):
             k = base
             v = self._heads(self.to_v(x), B, N)
 
-        phi = self.lin_q(q).softmax(dim=-1)  # (B,H,N,M)  softmax OVER M (slices)  <- rows sum to 1
-        psi = self.lin_k(k).softmax(dim=-2)  # (B,H,N,M)  softmax OVER N (points)  <- cols sum to 1
+        sq = self.lin_q(q)  # (B,H,N,M)
+        sk = self.lin_k(k)  # (B,H,N,M)
+        if self.temperature:
+            sq = sq / self.temp_q.clamp(0.01, 1.0)
+            sk = sk / self.temp_k.clamp(0.01, 1.0)
+        phi = sq.softmax(dim=-1)  # softmax OVER M (slices)  <- rows sum to 1
+        psi = sk.softmax(dim=-2)  # softmax OVER N (points)  <- cols sum to 1
         kv = torch.einsum("bhnm,bhnd->bhmd", psi, v)  # (B,H,M,dh)  cheap inner product first
         out = torch.einsum("bhnm,bhmd->bhnd", phi, kv)  # (B,H,N,dh)  linear in N
         out = rearrange(out, "b h n d -> b n (h d)")

stress_operator/models/transolver.py

@@ -27,6 +27,7 @@ def make_attention(
     slice_num,
     linearno_variant: str = "shared_qk",
     linearno_project_out: bool = False,
+    linearno_temperature: bool = False,
 ) -> nn.Module:
     if kind == "physics":
         return Physics_Attention_Irregular_Mesh(
@@ -43,6 +44,7 @@ def make_attention(
             dropout=dropout,
             variant=linearno_variant,
             project_out=linearno_project_out,
+            temperature=linearno_temperature,
         )
     raise ValueError(f"unknown attention kind {kind!r} (expected 'physics' or 'linearno')")
 
@@ -66,6 +68,7 @@ class StressOperator(nn.Module):
         act: str = "gelu",
         linearno_variant: str = "shared_qk",
         linearno_project_out: bool = False,
+        linearno_temperature: bool = False,
     ):
         super().__init__()
         if dim_head is None:
@@ -85,6 +88,7 @@ class StressOperator(nn.Module):
                         attention, n_hidden, n_heads, dim_head, dropout, slice_num,
                         linearno_variant=linearno_variant,
                         linearno_project_out=linearno_project_out,
+                        linearno_temperature=linearno_temperature,
                     ),
                     hidden_dim=n_hidden,
                     dropout=dropout,
@@ -152,6 +156,7 @@ def build_model(model_cfg: dict) -> StressOperator:
         act=model_cfg.get("act", "gelu"),
         linearno_variant=model_cfg.get("linearno_variant", "shared_qk"),
         linearno_project_out=model_cfg.get("linearno_project_out", False),
+        linearno_temperature=model_cfg.get("linearno_temperature", False),
     )
 
 

stress_operator/train_tensile.py

@@ -0,0 +1,144 @@
+"""Tensile2d training with the equilibrium regularizer — the SUPERVISED-tensor transfer experiment.
+
+Unlike Geo-FNO Elasticity (scalar von Mises target -> latent tensor), Tensile2d directly supervises the
+full Cauchy tensor (sig11, sig22, sig12) per node. So here:
+  - the data loss is relative-L2 on the 3 SUPERVISED stress components (not a derived von Mises);
+  - the model conditions on the 6 input scalars (P, p1..p5) via fun_dim=6 (broadcast per node);
+  - the physics loss is the same meshfree MLS divergence ||div(sigma)||^2 on interior nodes.
+Meshes are variable-size (~6k-12k nodes), so we keep per-sample lists (batch_size=1).
+
+This run lets us test the key question raised by the Elasticity cross-operator finding: does supervising
+the true tensor REDUCE the operator-specific 'gaming' (MLS-vs-FE residual gap)? (Checked post-hoc.)
+"""
+from __future__ import annotations
+
+import os
+import time
+from typing import Any, Dict, Optional
+
+import torch
+
+from .data.tensile2d import build_tensile_splits
+from .losses.equilibrium import build_mls_gradient_operators_sparse, interior_mask_knn
+from .losses.relative_l2 import relative_l2
+from .models.transolver import build_model, count_parameters
+from .seeds import set_seed
+from .utils.logging import MODAL_RATES_PER_SEC, write_run_log
+
+
+def _precompute_ops(coords_list, k, device):
+    ops = []
+    for c in coords_list:
+        Gx, Gy = build_mls_gradient_operators_sparse(c, k=k)   # sparse-direct (scales to ~10k nodes)
+        ops.append((Gx.to(device), Gy.to(device), interior_mask_knn(c, k=k).to(device)))
+    return ops
+
+
+def _div_residual(stress3, Gx_s, Gy_s, mask):
+    sxx, syy, sxy = stress3[:, 0:1], stress3[:, 1:2], stress3[:, 2:3]
+    dx = torch.sparse.mm(Gx_s, sxx) + torch.sparse.mm(Gy_s, sxy)
+    dy = torch.sparse.mm(Gx_s, sxy) + torch.sparse.mm(Gy_s, syy)
+    return (dx.squeeze(-1) ** 2 + dy.squeeze(-1) ** 2)[mask].mean()
+
+
+def run_training_tensile(
+    config: Dict[str, Any], seed: int, data_dir: str = "data/tensile2d/samples",
+    device: Optional[str] = None, gpu_name: str = "CPU",
+    results_path: Optional[str] = None, ckpt_path: Optional[str] = None,
+    log_every: int = 25, max_epochs: Optional[int] = None,
+    splits=None, lambda_override: Optional[float] = None,
+) -> Dict[str, Any]:
+    device = device or ("cuda" if torch.cuda.is_available() else "cpu")
+    set_seed(seed)
+    tr_cfg, model_cfg, eq_cfg = config["train"], config["model"], config["equilibrium"]
+    lam = float(lambda_override) if lambda_override is not None else float(eq_cfg.get("lambda", 0.01))
+    k = int(eq_cfg.get("knn_k", 12))  # interior_mask_knn is geometry-agnostic; no interior_tol needed
+
+    if splits is None:
+        d = config["data"]
+        splits = build_tensile_splits(data_dir, ntrain=d.get("ntrain", 400), ntest=d.get("ntest", 100), seed=0)
+    S = splits.scale_S
+    trc = [c.to(device) for c in splits.train_coords]
+    trs = [s.to(device).float() for s in splits.train_sigma]
+    trsc = [sc.to(device).float() for sc in splits.train_scalars]
+    tec = [c.to(device) for c in splits.test_coords]
+    tes = [s.to(device).float() for s in splits.test_sigma]
+    tesc = [sc.to(device).float() for sc in splits.test_scalars]
+    n_train, n_test = len(trc), len(tec)
+
+    print(f"[tensile seed {seed}] lambda={lam} k={k} S={S:.2f} ntrain={n_train} ntest={n_test}", flush=True)
+    t_build = time.time()
+    train_ops = _precompute_ops(splits.train_coords, k, device)
+    test_ops = _precompute_ops(splits.test_coords, k, device)
+    print(f"[tensile seed {seed}] precomputed operators in {time.time()-t_build:.0f}s", flush=True)
+
+    model = build_model(model_cfg).to(device)
+    n_params = count_parameters(model)
+    epochs = max_epochs or int(tr_cfg.get("epochs", 500))
+    opt = torch.optim.AdamW(model.parameters(), lr=float(tr_cfg.get("lr", 1e-3)),
+                            weight_decay=float(tr_cfg.get("weight_decay", 1e-5)),
+                            betas=tuple(tr_cfg.get("betas", (0.9, 0.999))))
+    sched = torch.optim.lr_scheduler.CosineAnnealingLR(opt, T_max=epochs)
+    mgn = tr_cfg.get("max_grad_norm", None)
+    eval_every = int(tr_cfg.get("eval_every", 10))
+    gen = torch.Generator().manual_seed(seed)
+
+    def fx_of(coords, scalars):  # broadcast the 6 input scalars to every node
+        return scalars.view(1, 1, -1).expand(1, coords.shape[0], -1)
+
+    def losses(coords, sigma, scalars, ops_i):
+        out = model(coords.unsqueeze(0), fx_of(coords, scalars))[0]   # (N,3) scaled stress
+        data = relative_l2(out.unsqueeze(0), sigma.unsqueeze(0), reduction="mean")  # SUPERVISED tensor
+        phys = _div_residual(out, *ops_i)
+        return data, phys
+
+    @torch.no_grad()
+    def evaluate():
+        model.eval()
+        d, p = 0.0, 0.0
+        for i in range(n_test):
+            dl, ph = losses(tec[i], tes[i], tesc[i], test_ops[i])
+            d += dl.item(); p += ph.item()
+        return d / n_test, p / n_test
+
+    t0 = time.time()
+    best, test_rel, test_phys, hist = float("inf"), float("nan"), float("nan"), []
+    for ep in range(epochs):
+        model.train()
+        run = 0.0
+        for i in torch.randperm(n_train, generator=gen).tolist():
+            opt.zero_grad()
+            dl, ph = losses(trc[i], trs[i], trsc[i], train_ops[i])
+            (dl + lam * ph).backward()
+            if mgn is not None:
+                torch.nn.utils.clip_grad_norm_(model.parameters(), mgn)
+            opt.step(); run += dl.item()
+        sched.step()
+        train_rel = run / n_train
+        if (ep % eval_every == 0) or (ep >= epochs - 5):
+            test_rel, test_phys = evaluate(); best = min(best, test_rel)
+        hist.append({"epoch": ep, "train_rel": train_rel, "test_rel": test_rel, "test_phys": test_phys})
+        if ep % log_every == 0 or ep == epochs - 1:
+            print(f"[tensile seed {seed}] epoch {ep:4d} train_rel={train_rel:.5f} "
+                  f"test_rel={test_rel:.5f} test_resid={test_phys:.4e}", flush=True)
+
+    wall = time.time() - t0
+    rate = MODAL_RATES_PER_SEC.get(gpu_name, 0.0)
+    metrics = {
+        "test_rel_l2": round(test_rel, 6), "best_test_rel_l2": round(best, 6),
+        "test_residual": test_phys * (S ** 2), "test_residual_scaled": test_phys,
+        "scale_S": S, "train_rel_l2": round(train_rel, 6),
+        "n_params": n_params, "epochs": epochs, "lambda": lam, "dataset": "tensile2d",
+    }
+    if ckpt_path is not None:
+        os.makedirs(os.path.dirname(ckpt_path) or ".", exist_ok=True)
+        torch.save({"state_dict": model.state_dict(), "scale_S": S, "config": config,
+                    "scalar_mean": splits.scalar_mean, "scalar_std": splits.scalar_std,
+                    "seed": seed, "metrics": metrics}, ckpt_path)
+    if results_path is None:
+        results_path = os.path.join("results", f"{config.get('name','tensile')}_seed{seed}.json")
+    write_run_log(results_path, config, seed, metrics, wall, gpu_name, wall * rate,
+                  extra={"history_tail": hist[-5:]})
+    print(f"[tensile seed {seed}] DONE test_rel={test_rel:.6f} resid={test_phys:.4e} "
+          f"wall={wall:.0f}s est_cost=${wall*rate:.4f}", flush=True)
+    return metrics