HaomingLuo/AgentFEM-T4-Modal-Neural-State-Space

AgentFEM T4 Modal Neural State-Space

Recommended version: 0.1.0
Required dataset: T4 v1.1.0 or later

Purpose

This model predicts the transient displacement field of a family of damped cantilever structures from physical configuration, modal frequencies, and a time-dependent load. It is the first learning baseline designed specifically for the corrected AgentFEM T4 structural-dynamics benchmark.

Model idea

The architecture retains the governing form of linear structural dynamics:

[ \ddot q_i + 2\zeta_i\omega_i\dot q_i + \omega_i^2q_i = b_i f(t). ]

AgentFEM supplies the modal frequencies and the load history. A POD basis maps the full finite-element field to compact coordinates. A small neural conditioner learns the geometry-dependent participation of four stable modal oscillators in that shared basis. Known traction, density and length scaling is applied analytically. The network therefore learns only the remaining coupling, while oscillation, damping, causality, force/mass scaling, and state recursion remain explicit.

Inputs

• beam length and height;
• Young's modulus and density;
• target damping ratio;
• traction amplitude;
• first four AgentFEM modal frequencies;
• normalized load history and time increment.

Output

Time-resolved two-component displacement at all 245 finite-element nodes. The same rollout can be sampled at the five T4 virtual sensors.

Evaluation protocol

All four trajectories from one structural configuration remain in the same split. Reported cohorts are:

• configuration-level ID test;
• unseen excitation ranges (excitation OOD);
• parameter-boundary structures (parameter OOD).

The main metric is full-field relative (L^2) error over all nodes and times. The model is compared with the POD projection floor, an oracle modal-coupling fit, and the data-only second-order latent ridge baseline.

Data integrity requirement

The trainer rejects T4 schema 1.0.0. It only accepts schema 1.1.0 case files carrying the component-preserving-kinematic-bcs seal. This prevents training on the superseded trajectories affected by over-constrained component boundary conditions in AgentFEM 0.3.7 implicit dynamics.

Frozen results

All 128 corrected configurations passed completeness, energy, analytical frequency, modal/transient-frequency and time-refinement gates. The final 1,496-parameter model obtained the following full-field rollout errors:

Cohort	Relative L2	Percentage
ID test	0.00720	0.72%
excitation OOD	0.00683	0.68%
parameter OOD	0.01432	1.43%
all test	0.01195	1.20%

The data-only second-order latent ridge baseline gives 1.0783 (107.83%) on the same all-test rollout. The physics-conditioned model reduces that error by about 90 times while remaining stable. The sparse-sensor ridge baseline obtains 0.67%, but it uses current-time measurements and solves a different, non-autonomous reconstruction task; it is not presented as a rollout baseline.

The modal oracle and POD projection floors are about 0.00026% on the all-test cohort. This shows that the remaining 1.20% error is dominated by generalizing the geometry-to-participation map, not by unstable time integration or loss of field information.

Files and reuse

• model_state_dict.pt: PyTorch weights only;
• model_arrays.npz: POD basis and normalization arrays;
• config.json: architecture and schema contract;
• inference.py: full-field rollout API;
• train.py: deterministic training and frozen-cohort evaluation;
• metrics.json: aggregate and per-trajectory results.

from inference import T4ModalNeuralStateSpace

model = T4ModalNeuralStateSpace(".")
field = model.predict(
    parameter=parameter_vector,
    frequencies_hz=modal_frequencies,
    force_scale=load_history,
    dt=0.000125,
    rayleigh_mass_coefficient_per_s=alpha,
    rayleigh_stiffness_coefficient_s=beta,
    field_stride=20,
)

field has shape (time_frames, 245, 2). The model requires the first four modal frequencies, which may come from AgentFEM modal analysis or compatible experimental modal identification. It is a bounded surrogate for the declared linear cantilever family, not a universal structural-dynamics model.