Add multi-zone residual surrogate with held-out evaluation and runnable predictor

README.md

@@ -16,6 +16,8 @@ tags:
 
 # AgentFEM · Morph Rod Surrogates
 
+**New: [multi-zone residual surrogate](multizone-v02/README.md)** — a separate 3/6/12-zone actuation model with 8-zone holdout, downloadable weights and a runnable predictor. Original branch-conditioned models below are retained unchanged.
+
 **Predict a flexible rod's shape without averaging its equilibrium branches.**
 
 ![Computed rod families](assets/overview.png)

multizone-v02/README.md

@@ -0,0 +1,30 @@
+# Multi-zone residual surrogate · v0.2
+
+This additional model predicts the load-induced angular correction to an intrinsic-curvature shape. It handles a fixed 48-element field representation rather than three named curvature inputs. It is a separate task from the v0.1 microforce branch-conditioned model, not a replacement or a directly comparable leaderboard result.
+
+## Run
+
+Install `numpy torch safetensors`, then:
+
+```bash
+python predict.py --curvatures 1 .5 -1 1 .2 .8
+```
+
+The 51 inputs are 48 element-wise intrinsic curvatures, fx/chi, fy/chi, and log10(chi). A 51→96→96→48 tanh network predicts the angle correction; analytically integrated intrinsic curvature supplies the base shape. Weights use safetensors. `config.json` contains training-only normalization statistics. Output is a surrogate estimate, not an equilibrium-certified solution; use the accompanying mechanics solver when certification is required.
+
+## Held-out results
+
+| Split | Intrinsic-shape baseline RMSE / L | Learned correction RMSE / L |
+|---|---:|---:|
+| Scenario-held-out test, 3/6/12 zones | 0.03450 | 0.002255 |
+| Zone-count OOD, 8 zones | 0.03387 | 0.009063 |
+
+These are centerline errors at 49 nodes, including zero-loading states. Nonzero-only errors, endpoint means and 95th percentiles are in evaluation.json. No runtime advantage over the already fast mechanical solver has been established. The web Space continues to use that solver, not this neural model.
+
+Training uses 2,520 states, validation 540, test 540, and zone-count OOD 480. Whole six-state loading paths stay in one split. The validation-best checkpoint is selected over 201 epochs; the test split is not used for selection. No contact, dynamics, multi-branch loading or hardware control is covered by this model.
+
+## 中文
+
+这版模型学习的是“本征曲率形状在外力下还会变多少”，而不是从零预测整个形状。测试集误差约为杆长的 0.226%，未见过的 8 分区工况约为 0.906%。它与原来的多分支模型用途不同，不能直接比较两个版本的误差来判断进步幅度。网页仍采用实际力学求解。
+
+Code and model: Apache-2.0. Associated data: CC BY 4.0.

multizone-v02/config.json

@@ -0,0 +1,118 @@
+{
+  "mean": [
+    -0.021105827763676643,
+    -0.021105827763676643,
+    -0.021105827763676643,
+    -0.021105827763676643,
+    0.010166754014790058,
+    0.010166754014790058,
+    0.010166754014790058,
+    0.010166754014790058,
+    0.005382698494940996,
+    0.005382698494940996,
+    0.005382698494940996,
+    0.005382698494940996,
+    0.01833205670118332,
+    0.01833205670118332,
+    0.01833205670118332,
+    0.01833205670118332,
+    -0.01243000291287899,
+    -0.01243000291287899,
+    -0.01243000291287899,
+    -0.01243000291287899,
+    -0.04185189679265022,
+    -0.04185189679265022,
+    -0.04185189679265022,
+    -0.04185189679265022,
+    -0.06519726663827896,
+    -0.06519726663827896,
+    -0.06519726663827896,
+    -0.06519726663827896,
+    -0.09435442835092545,
+    -0.09435442835092545,
+    -0.09435442835092545,
+    -0.09435442835092545,
+    0.03800766170024872,
+    0.03800766170024872,
+    0.03800766170024872,
+    0.03800766170024872,
+    0.005421004723757505,
+    0.005421004723757505,
+    0.005421004723757505,
+    0.005421004723757505,
+    0.02227204106748104,
+    0.02227204106748104,
+    0.02227204106748104,
+    0.02227204106748104,
+    0.013483509421348572,
+    0.013483509421348572,
+    0.013483509421348572,
+    0.013483509421348572,
+    0.15130436420440674,
+    -0.0051275817677378654,
+    -3.2511823177337646
+  ],
+  "std": [
+    0.8128650188446045,
+    0.8128650188446045,
+    0.8128650188446045,
+    0.8128650188446045,
+    0.8196129202842712,
+    0.8196129202842712,
+    0.8196129202842712,
+    0.8196129202842712,
+    0.8226141333580017,
+    0.8226141333580017,
+    0.8226141333580017,
+    0.8226141333580017,
+    0.8281049728393555,
+    0.8281049728393555,
+    0.8281049728393555,
+    0.8281049728393555,
+    0.8390543460845947,
+    0.8390543460845947,
+    0.8390543460845947,
+    0.8390543460845947,
+    0.8081016540527344,
+    0.8081016540527344,
+    0.8081016540527344,
+    0.8081016540527344,
+    0.8240239024162292,
+    0.8240239024162292,
+    0.8240239024162292,
+    0.8240239024162292,
+    0.8097495436668396,
+    0.8097495436668396,
+    0.8097495436668396,
+    0.8097495436668396,
+    0.8323362469673157,
+    0.8323362469673157,
+    0.8323362469673157,
+    0.8323362469673157,
+    0.8128801584243774,
+    0.8128801584243774,
+    0.8128801584243774,
+    0.8128801584243774,
+    0.8216692805290222,
+    0.8216692805290222,
+    0.8216692805290222,
+    0.8216692805290222,
+    0.8180782794952393,
+    0.8180782794952393,
+    0.8180782794952393,
+    0.8180782794952393,
+    0.1490403264760971,
+    0.21210536360740662,
+    0.4438764750957489
+  ],
+  "output_scale": 0.1,
+  "n": 48,
+  "architecture": [
+    51,
+    96,
+    96,
+    48
+  ],
+  "features": "48 piecewise intrinsic curvatures, fx/chi, fy/chi, log10(chi)",
+  "prediction": "cumulative intrinsic angle + output_scale * network(standardized features)"
+}

multizone-v02/evaluation.json

@@ -0,0 +1,159 @@
+{
+  "version": "0.2",
+  "states": 4080,
+  "scenes": 680,
+  "counts": {
+    "train": 2520,
+    "validation": 540,
+    "test": 540,
+    "zone_ood": 480
+  },
+  "zones_id": [
+    3,
+    6,
+    12
+  ],
+  "zones_ood": [
+    8
+  ],
+  "rejected": 0,
+  "mesh_checks": 34,
+  "max_mesh_tip_difference_over_L": 4.603976254440725e-05,
+  "best_epoch": 189,
+  "metrics": {
+    "train": {
+      "intrinsic_shape": {
+        "centerline_rmse_over_L": 0.03217696650573636,
+        "tip_mean_over_L": 0.04703082547593874,
+        "tip_p95_over_L": 0.1389949922209111,
+        "nonzero_loading_rmse_over_L": 0.035248100774559976
+      },
+      "learned_residual": {
+        "centerline_rmse_over_L": 0.0007707721406115093,
+        "tip_mean_over_L": 0.0010672698493170232,
+        "tip_p95_over_L": 0.0032114897744955654,
+        "nonzero_loading_rmse_over_L": 0.0008432933805167641
+      }
+    },
+    "validation": {
+      "intrinsic_shape": {
+        "centerline_rmse_over_L": 0.030841632665898296,
+        "tip_mean_over_L": 0.04443062956595426,
+        "tip_p95_over_L": 0.13412200027231663,
+        "nonzero_loading_rmse_over_L": 0.03378531584280138
+      },
+      "learned_residual": {
+        "centerline_rmse_over_L": 0.002139143213742544,
+        "tip_mean_over_L": 0.0023906575722607896,
+        "tip_p95_over_L": 0.00985920275845111,
+        "nonzero_loading_rmse_over_L": 0.002342985905624226
+      }
+    },
+    "test": {
+      "intrinsic_shape": {
+        "centerline_rmse_over_L": 0.03449966638469762,
+        "tip_mean_over_L": 0.04949992729501256,
+        "tip_p95_over_L": 0.15202171303892403,
+        "nonzero_loading_rmse_over_L": 0.037792491010603176
+      },
+      "learned_residual": {
+        "centerline_rmse_over_L": 0.0022550218060435672,
+        "tip_mean_over_L": 0.0025461652398190942,
+        "tip_p95_over_L": 0.010101520708292833,
+        "nonzero_loading_rmse_over_L": 0.002469874665768664
+      }
+    },
+    "zone_ood": {
+      "intrinsic_shape": {
+        "centerline_rmse_over_L": 0.03387460541227201,
+        "tip_mean_over_L": 0.05124979340575448,
+        "tip_p95_over_L": 0.1401572788163453,
+        "nonzero_loading_rmse_over_L": 0.03710777102177594
+      },
+      "learned_residual": {
+        "centerline_rmse_over_L": 0.009062882912828973,
+        "tip_mean_over_L": 0.012180452320820882,
+        "tip_p95_over_L": 0.040638126307767204,
+        "nonzero_loading_rmse_over_L": 0.009927801522037316
+      }
+    }
+  },
+  "seconds": 4.511781215667725,
+  "mechanics_correction_checks": [
+    {
+      "id": "z3_008_5",
+      "residual": 5.312265384527226e-15,
+      "tip_error_over_L": 2.5286101803848858e-11
+    },
+    {
+      "id": "z3_051_5",
+      "residual": 4.446925569975155e-11,
+      "tip_error_over_L": 2.999757286531255e-08
+    },
+    {
+      "id": "z3_097_5",
+      "residual": 7.789608621038927e-16,
+      "tip_error_over_L": 4.949868572479711e-13
+    },
+    {
+      "id": "z3_144_5",
+      "residual": 1.3740308793209865e-11,
+      "tip_error_over_L": 2.148295597082969e-08
+    },
+    {
+      "id": "z3_176_5",
+      "residual": 5.722921340540243e-12,
+      "tip_error_over_L": 2.746265069278408e-07
+    },
+    {
+      "id": "z6_014_5",
+      "residual": 6.901285641049137e-17,
+      "tip_error_over_L": 7.371685286925458e-13
+    },
+    {
+      "id": "z6_044_5",
+      "residual": 2.206625380615194e-11,
+      "tip_error_over_L": 1.0975236022566359e-06
+    },
+    {
+      "id": "z6_077_5",
+      "residual": 1.4517147984741103e-11,
+      "tip_error_over_L": 8.451519429810074e-07
+    },
+    {
+      "id": "z6_138_5",
+      "residual": 4.744584467966025e-17,
+      "tip_error_over_L": 3.519878195556559e-08
+    },
+    {
+      "id": "z6_156_5",
+      "residual": 3.385439432791542e-11,
+      "tip_error_over_L": 1.3208994208734372e-07
+    },
+    {
+      "id": "z12_002_5",
+      "residual": 4.696980651641702e-15,
+      "tip_error_over_L": 5.641037807459418e-07
+    },
+    {
+      "id": "z12_037_5",
+      "residual": 2.122790464208461e-12,
+      "tip_error_over_L": 1.8782719327230075e-09
+    },
+    {
+      "id": "z12_083_5",
+      "residual": 6.979108458062555e-11,
+      "tip_error_over_L": 4.442049511326813e-06
+    },
+    {
+      "id": "z12_111_5",
+      "residual": 7.040594326440894e-17,
+      "tip_error_over_L": 5.582728434790076e-10
+    },
+    {
+      "id": "z12_172_5",
+      "residual": 2.369698582393759e-12,
+      "tip_error_over_L": 2.2341706552832602e-07
+    }
+  ]
+}

multizone-v02/predict.py

@@ -0,0 +1,24 @@
+"""Apache-2.0. Run: python predict.py --curvatures 1 .5 -1 1 .2 .8"""
+from pathlib import Path
+import argparse,json
+import numpy as np
+import torch
+from torch import nn
+from safetensors.torch import load_file
+
+def predict(curvatures,chi=.001,fx=.0003,fy=-.0001):
+    root=Path(__file__).resolve().parent;cfg=json.loads((root/'config.json').read_text())
+    k=np.asarray(curvatures,float)
+    if k.ndim!=1 or len(k) not in [3,6,8,12] or not np.all(np.isfinite(k)) or np.max(np.abs(k))>2.4:raise ValueError('3, 6, 12 zones (8 is OOD), finite curvature in [-2.4,2.4]')
+    if chi<=0:raise ValueError('chi must be positive')
+    field=k[np.floor((np.arange(48)+.5)*len(k)/48).astype(int)]
+    features=np.r_[field,fx/chi,fy/chi,np.log10(chi)]
+    x=torch.tensor((features-cfg['mean'])/cfg['std'],dtype=torch.float32)
+    net=nn.Sequential(nn.Linear(51,96),nn.Tanh(),nn.Linear(96,96),nn.Tanh(),nn.Linear(96,48))
+    net.load_state_dict(load_file(str(root/'residual.safetensors')));net.eval()
+    with torch.no_grad():z=np.cumsum(field)/48+cfg['output_scale']*net(x).numpy()
+    angle=(np.r_[0,z[:-1]]+z)/2;stretch=1+fx*np.cos(angle)+fy*np.sin(angle)
+    xy=np.vstack([np.zeros(2),np.cumsum(stretch[:,None]*np.c_[np.cos(angle),np.sin(angle)]/48,axis=0)])
+    return {'z':z.tolist(),'xy':xy.tolist(),'tip':xy[-1].tolist(),'source':'learned_residual_surrogate','equilibrium_verified':False}
+if __name__=='__main__':
+    p=argparse.ArgumentParser();p.add_argument('--curvatures',type=float,nargs='+',required=True);p.add_argument('--chi',type=float,default=.001);p.add_argument('--fx',type=float,default=.0003);p.add_argument('--fy',type=float,default=-.0001);a=p.parse_args();print(json.dumps(predict(a.curvatures,a.chi,a.fx,a.fy)))

multizone-v02/residual.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:450959ecdf0bcb0915972db42ed378b9e1feb62a73ae7fa3ad8fcb1499cf0bac
+size 76264

multizone-v02/source/multizone.py

@@ -0,0 +1,84 @@
+"""Reproducible v0.2 multi-zone supplement; preserves v0.1 artifacts."""
+import os
+os.environ.setdefault('OPENBLAS_NUM_THREADS','1')
+os.environ.setdefault('OMP_NUM_THREADS','1')
+from pathlib import Path
+import json,gzip,time
+import numpy as np
+import torch
+from torch import nn
+from safetensors.torch import save_file,load_file
+from rod import Rod,Controls,serial
+
+ROOT=Path(__file__).resolve().parents[1]
+OUT=ROOT/'release/dataset/multizone-v02'
+MODEL=ROOT/'release/model/multizone-v02'
+def features(ks,chi,fx,fy):
+    field=np.asarray(ks)[np.floor((np.arange(48)+.5)*len(ks)/48).astype(int)]
+    return np.r_[field,fx/chi,fy/chi,np.log10(chi)],np.cumsum(field)/48
+def network():
+    return nn.Sequential(nn.Linear(51,96),nn.Tanh(),nn.Linear(96,96),nn.Tanh(),nn.Linear(96,48))
+def xy(z,fx,fy):
+    angle=(np.c_[np.zeros(len(z)),z[:,:-1]]+z)/2
+    stretch=1+fx[:,None]*np.cos(angle)+fy[:,None]*np.sin(angle)
+    ds=stretch[:,:,None]*np.stack([np.cos(angle),np.sin(angle)],axis=2)/48
+    return np.concatenate([np.zeros((len(z),1,2)),np.cumsum(ds,axis=1)],axis=1)
+def main():
+    start=time.time();OUT.mkdir(parents=True,exist_ok=True);MODEL.mkdir(parents=True,exist_ok=True)
+    rng=np.random.default_rng(20261015);rod=Rod(48);fine=Rod(96);rows=[];mesh=[];rejected=[]
+    for m in [3,6,12,8]:
+        total=200 if m!=8 else 80
+        order=rng.permutation(total);splits={int(j):('train' if i<140 else 'validation' if i<170 else 'test') for i,j in enumerate(order)}
+        for j in range(total):
+            split=splits[j] if m!=8 else 'zone_ood';ks=rng.uniform(-2.4,2.4,m);chi=float(10**rng.uniform(-4,-2.5));fx=float(chi*rng.uniform(0,.6));fy=float(chi*rng.uniform(-.6,.6))
+            for step,t in enumerate(np.linspace(0,1,6)):
+                k=ks*t;c=Controls(chi=chi,fx=fx*t,fy=fy*t,curvatures=tuple(k));_,seed=features(k,chi,c.fx,c.fy);s=rod.solve(c,seed)
+                row=dict(id=f'z{m}_{j:03d}_{step}',scene_id=f'z{m}_{j:03d}',split=split,zones=m,t=float(t),chi=chi,fx=c.fx,fy=c.fy,curvatures=k.tolist(),**serial(s))
+                if not s['accepted'] or s['stability']!='stable':rejected.append(row);continue
+                rows.append(row)
+                if step==5 and j%20==0:
+                    field=k[np.floor((np.arange(96)+.5)*m/96).astype(int)];f=fine.solve(c,np.cumsum(field)/96)
+                    assert f['accepted'] and f['stability']=='stable'
+                    mesh.append(dict(id=row['id'],tip_difference_over_L=float(np.linalg.norm(f['tip']-s['tip'])),centerline_rmse_over_L=float(np.sqrt(np.mean(np.sum((f['centerline']-s['centerline'])**2,axis=1))))))
+        print('Generated zones',m,'states',len(rows),flush=True)
+    for split in ['train','validation','test','zone_ood']:
+        with gzip.open(OUT/f'{split}.jsonl.gz','wt') as f:
+            for row in rows:
+                if row['split']==split:f.write(json.dumps(row)+'\n')
+    (OUT/'rejected.json').write_text(json.dumps(rejected))
+    (OUT/'mesh-checks.json').write_text(json.dumps(mesh,indent=2))
+    items=[features(r['curvatures'],r['chi'],r['fx'],r['fy']) for r in rows]
+    x=np.array([a for a,b in items],np.float32);seed=np.array([b for a,b in items],np.float32);z=np.array([r['z'] for r in rows],np.float32)
+    ix={s:np.array([i for i,r in enumerate(rows) if r['split']==s]) for s in ['train','validation','test','zone_ood']}
+    mean=x[ix['train']].mean(0);std=x[ix['train']].std(0);std[std<1e-6]=1
+    X=torch.from_numpy((x-mean)/std);Y=torch.from_numpy((z-seed)/.1)
+    torch.set_num_threads(2);torch.manual_seed(15);net=network();opt=torch.optim.Adam(net.parameters(),lr=.0015);best=float('inf');best_epoch=0
+    for epoch in range(201):
+        net.train()
+        for batch in np.array_split(rng.permutation(ix['train']),12):
+            opt.zero_grad();loss=(net(X[batch])-Y[batch]).square().mean();loss.backward();opt.step()
+        net.eval()
+        with torch.no_grad():val=float((net(X[ix['validation']])-Y[ix['validation']]).square().mean())
+        if val<best:best=val;best_epoch=epoch;weights={k:v.clone().contiguous() for k,v in net.state_dict().items()}
+        if epoch%50==0:print('Epoch',epoch,'validation',val,flush=True)
+    save_file(weights,str(MODEL/'residual.safetensors'));net.load_state_dict(load_file(str(MODEL/'residual.safetensors')))
+    with torch.no_grad():pred=seed+.1*net(X).numpy()
+    fx=np.array([r['fx'] for r in rows]);fy=np.array([r['fy'] for r in rows]);truth=xy(z,fx,fy)
+    metrics={}
+    for split,idx in ix.items():
+        metrics[split]={}
+        for name,zz in [('intrinsic_shape',seed),('learned_residual',pred)]:
+            err=np.linalg.norm(xy(zz,fx,fy)[idx]-truth[idx],axis=2)
+            metrics[split][name]={'centerline_rmse_over_L':float(np.sqrt(np.mean(err**2))),'tip_mean_over_L':float(err[:,-1].mean()),'tip_p95_over_L':float(np.quantile(err[:,-1],.95))}
+            nonzero=np.array([rows[i]['t']>0 for i in idx]);metrics[split][name]['nonzero_loading_rmse_over_L']=float(np.sqrt(np.mean(err[nonzero]**2)))
+    correction=[]
+    for i in ix['test'][5::36]:
+        r=rows[i];c=Controls(chi=r['chi'],fx=r['fx'],fy=r['fy'],curvatures=tuple(r['curvatures']))
+        corrected=rod.solve(c,pred[i]);assert corrected['accepted']
+        correction.append(dict(id=r['id'],residual=corrected['residual'],tip_error_over_L=float(np.linalg.norm(corrected['tip']-r['tip']))))
+    report=dict(version='0.2',states=len(rows),scenes=len(set(r['scene_id'] for r in rows)),counts={s:len(i) for s,i in ix.items()},zones_id=[3,6,12],zones_ood=[8],rejected=len(rejected),mesh_checks=len(mesh),max_mesh_tip_difference_over_L=max(r['tip_difference_over_L'] for r in mesh),best_epoch=best_epoch,metrics=metrics,seconds=time.time()-start)
+    report['mechanics_correction_checks']=correction
+    (MODEL/'config.json').write_text(json.dumps(dict(mean=mean.tolist(),std=std.tolist(),output_scale=.1,n=48,architecture=[51,96,96,48],features='48 piecewise intrinsic curvatures, fx/chi, fy/chi, log10(chi)',prediction='cumulative intrinsic angle + output_scale * network(standardized features)'),indent=2))
+    for p in [MODEL/'evaluation.json',OUT/'validation.json',ROOT/'reports/multizone-v02.json']:p.write_text(json.dumps(report,indent=2))
+    print(json.dumps(report,indent=2),flush=True)
+if __name__=='__main__':main()

multizone-v02/source/rod.py

@@ -0,0 +1,106 @@
+"""Conservative planar extensible rod. L=EA=1; chi=EI/(EA L^2).
+
+Rod: linear angle FE, midpoint axial elimination. Chain: Ye et al. (2026)
+cell rotations, first cell clamped; kr=chi*n. Independent implementations
+share ONLY the reduced local energy density. No contact or dynamics.
+SPDX-License-Identifier: Apache-2.0
+"""
+from dataclasses import dataclass, asdict
+import numpy as np
+from scipy.linalg import solve, eigh
+from scipy.optimize import root
+
+@dataclass
+class Controls:
+    chi: float = .001
+    fx: float = 0.
+    fy: float = 0.
+    moment: float = 0.
+    h: float = 0.
+    delta: float = .1
+    k1: float = 0.
+    k2: float = 0.
+    k3: float = 0.
+    curvatures: tuple | None = None
+
+class Rod:
+    def __init__(self, n=48, kind="rod"):
+        self.n, self.kind, self.ds = n, kind, 1/n
+        if kind == "rod":
+            self.d = n
+            A = np.zeros((n,n+1)); B = A.copy()
+            for i in range(n):
+                A[i,i:i+2] = .5
+                B[i,i:i+2] = [-n,n]
+            self.A,self.B = A[:,1:],B[:,1:]
+            self.mass = (A[:,1:].T@A[:,1:])/n
+        elif kind == "chain":
+            self.d = n-1
+            self.A = np.eye(n)[:,1:]
+            self.B = np.diff(np.eye(n),axis=0)[:,1:]*n
+            self.mass = np.eye(n-1)/n
+        else: raise ValueError(kind)
+        self.s = (np.arange(n)+.5)/n
+
+    def terms(self, z, c):
+        angle=self.A@z
+        ks=np.asarray(c.curvatures if c.curvatures is not None else [c.k1,c.k2,c.k3])
+        intrinsic=ks[np.minimum((np.arange(self.B.shape[0])+.5)*len(ks)/self.B.shape[0],len(ks)-1).astype(int)]
+        curvature=self.B@z-intrinsic
+        a=c.fx+2*c.h
+        f=a*np.cos(angle)+c.fy*np.sin(angle)
+        fp=-a*np.sin(angle)+c.fy*np.cos(angle)
+        g=4*c.h*c.delta
+        density=-f-.5*f*f+g*np.cos(angle)
+        energy=self.ds*(.5*c.chi*(curvature@curvature)+density.sum())-c.moment*z[-1]
+        local_g=-(1+f)*fp-g*np.sin(angle)
+        local_h=(1+f)*f-fp*fp-g*np.cos(angle)
+        grad=self.ds*(c.chi*self.B.T@curvature+self.A.T@local_g)
+        grad[-1]-=c.moment
+        tangent=self.ds*(c.chi*self.B.T@self.B+self.A.T@(local_h[:,None]*self.A))
+        return energy,grad,tangent
+
+    def solve(self,c,seed=None):
+        z=np.zeros(self.d) if seed is None else np.array(seed,dtype=float).copy()
+        it=0; trace=[]; fallback_nfev=0
+        for it in range(60):
+            _,r,K=self.terms(z,c)
+            trace.append(dict(iteration=it,residual_inf=float(np.max(np.abs(r)))))
+            if np.max(np.abs(r))<1e-10: break
+            try: dz=solve(K,-r,assume_a='sym')
+            except Exception: break
+            old=np.linalg.norm(r)
+            step=1.
+            for _ in range(16):
+                trial=z+step*dz
+                if np.linalg.norm(self.terms(trial,c)[1])<old: break
+                step*=.5
+            else: break
+            z=trial
+            trace[-1]['accepted_step_scale']=step
+        residual=float(np.max(np.abs(self.terms(z,c)[1])))
+        if residual>1e-9:
+            sol=root(lambda v:self.terms(v,c)[1],z,jac=lambda v:self.terms(v,c)[2],tol=1e-10)
+            z=sol.x; fallback_nfev=sol.nfev
+        energy,r,K=self.terms(z,c)
+        residual=float(np.max(np.abs(r)))
+        angle=self.A@z
+        stretch=1+(c.fx+2*c.h)*np.cos(angle)+c.fy*np.sin(angle)
+        admissible=bool(np.min(stretch)>(2*c.delta if c.h!=0 else 0))
+        good=bool(residual<1e-9 and admissible and np.all(np.isfinite(z)))
+        eig=float(eigh(K,self.mass,subset_by_index=[0,0],eigvals_only=True)[0]/c.chi) if good else None
+        stability='unknown' if eig is None else ('stable' if eig>1e-4 else 'unstable' if eig< -1e-4 else 'critical')
+        segments=self.ds*stretch[:,None]*np.column_stack([np.cos(angle),np.sin(angle)])
+        xy=np.vstack([np.zeros(2),np.cumsum(segments,axis=0)])
+        # Output resampled on reference coordinate, not current arc length.
+        center=np.column_stack([np.interp(np.linspace(0,1,65),np.linspace(0,1,self.n+1),xy[:,j]) for j in range(2)])
+        return dict(z=z,centerline=center,angle=angle,strain=stretch-1,energy=float(energy),residual=residual,
+                    iterations=it+1,accepted=good,lambda_min_over_chi=eig,stability=stability,
+                    tip=center[-1],min_stretch=float(stretch.min()),solver_trace=trace,fallback_nfev=fallback_nfev)
+
+    def mode_seed(self,amplitude):
+        s=np.arange(1,self.d+1)/self.n
+        return amplitude*np.sin(np.pi*s/2)
+
+def serial(result):
+    return {k:(v.tolist() if isinstance(v,np.ndarray) else v) for k,v in result.items()}