README.md

---
license: apache-2.0
language:
- en
- zh
library_name: pytorch
datasets:
- HaomingLuo/AgentFEM-Programmable-Soft-Rods
tags:
- agentfem
- soft-robotics
- inverse-design
- physics
- tabular-regression
---

# AgentFEM · Morph Rod Surrogates

[Try Morph Lab](https://lab.haoming-luo.com/morph/) · [Browse the dataset](https://huggingface.co/datasets/HaomingLuo/AgentFEM-Programmable-Soft-Rods)

Start with the browser to explore target shapes, then use this repository for neural prediction and reproducible solver experiments. The browser inverse-design routine uses mechanics and optimization, not these neural weights.

**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)

Two small PyTorch MLP baselines, a conservative rod solver, and bounded inverse
design examples. The branch-conditioned model takes the requested coarse branch
as an input; it does not independently discover branches.

[Dataset](https://huggingface.co/datasets/HaomingLuo/AgentFEM-Programmable-Soft-Rods) ·
[AgentFEM](https://github.com/haoming-luo/agentfem) · [Equations & schema](SCHEMA.md)

## Results

| Method | Test centerline RMSE / L | Mean endpoint error / L |
|---|---:|---:|
| Ordinary MLP, no branch input | 0.27097 | 0.26332 |
| 1-nearest-neighbor, branch provided | 0.13899 | 0.15082 |
| MLP, branch provided | **0.00661** | **0.00784** |

The ordinary model has deliberately ambiguous inputs on the multi-branch family;
the comparison demonstrates why branch information matters, not a novel network
architecture. The branch-conditioned model's stiffness-OOD centerline RMSE is
0.00941 L. Raw predictions are approximations, not equilibrium or stability certificates.

## Run

Download this repository and install `requirements.txt`, then:

```bash
python src/inference.py
```

```python
import sys
sys.path.insert(0, "src")
from inference import predict
c = dict(chi=.0001, fx=-.016428, fy=0., moment=0., h=.01,
         delta=.1, k1=0., k2=0., k3=0.)
result = predict(c, branch="down", correct=True)
print(result["tip"], result["residual"], result["stability"])
```

`correct=True` initializes the released mechanics solver from the neural output.
Always inspect convergence and the returned branch before accepting a design.
In 102 sampled held-out cases, correction converged and preserved the intended
coarse branch; this is not a universal guarantee.

To design a bounded three-zone intrinsic-curvature rod for an endpoint or complete
centerline, see `src/inverse.py`. Twelve known-reachable test targets were recovered
with maximum error 6.10e-6 L; 25 equilibrium samples along each proposed curvature
ramp were locally stable. Unsampled intervals are not certified. This inverse
example uses numerical optimization plus mechanics, not the neural model.

## Model details

- 8 normalized physical features; branch model adds a 3-way coarse-branch encoding.
- Tanh MLP, hidden widths 96/96, 48 angle outputs. No graph network or neural operator claim.
- Safetensors weights, training-only normalization, validation-selected checkpoint.
- Seed14, Adam, 401 epochs. Reports include grouped test and stiffness-OOD results.
- 126 training, 27 validation and 27 test scenes; 36 separate stiffness-OOD scenes.
- Stable and unstable equilibrium samples are both present in training.

Files: `models/`, `src/rod.py`, `src/train.py`, `src/inference.py`,
`src/inverse.py`, `reports/`, and [SCHEMA.md](SCHEMA.md).
To retrain, download the linked dataset repository and run its reproduction steps.

## 中文

这是可编程柔性杆的第一版代理模型与计算工具，包含普通 MLP、指定分支的 MLP、
力学求解器及逆向设计示例。模型预测 48 个转角自由度，再由运动学关系恢复中心线。

给定分支的模型在场景留出测试中，中心线均方根误差为杆长的约 **0.66%**，
端点平均误差约 **0.78%**。分支标签是输入条件，不是模型自己判断出的答案。
需要平衡与稳定性结果时，应开启力学校正，并检查收敛结果。

当前针对平面、准静态、无接触杆；不宣称真实机器人控制或跳跃动力学。

## Attribution

Version **0.1.0**, Haoming Luo / AgentFEM Morph Lab (2026). Code and weights:
Apache-2.0; generated figures CC BY 4.0.
Microforce theory: Ye, Piccolroaz & Bigoni,
[DOI 10.1016/j.jmps.2026.106870](https://doi.org/10.1016/j.jmps.2026.106870).