agentfem-performance
Optimize and package reproducible AgentFEM simulations using phase timing, accepted-state replay, rollback checks and full-run evidence. Use for AgentFEM runtime bottlenecks and reproducible case delivery, not general website performance or claims based solely on short microbenchmarks.
haoming-luo · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add haoming-luo/agentfem --skill agentfem-performanceAbout this skill
name: agentfem-performance description: Optimize and package reproducible AgentFEM simulations using phase timing, accepted-state replay, rollback checks and full-run evidence. Use for AgentFEM runtime bottlenecks and reproducible case delivery, not general website performance or claims based solely on short microbenchmarks. license: Apache-2.0
AgentFEM performance and reproducible cases
This is optional development guidance, not a solver or runtime dependency. A delivered project must execute its declared model and installed providers without an agent generating code, repairing inputs or making scientific choices during the run. Skills help prepare and review it; they do not supply missing executable behavior or prove that its results are valid.
Read the target repository's AGENTS.md and focused architecture/performance documents. Inspect running numerical jobs before launching another. Preserve private meshes and user laws outside the public library.
When promoting a private fast path into core, or diagnosing a regression after that migration, read Migration parity. This is an evolving engineering playbook, not a fixed optimization recipe. Past worker counts, test lengths and architecture choices are observations, not defaults for the next problem. Reusable execution and export correctness belong in the library, not in agent-written case workarounds.
Choose work by expected whole-run benefit
Start with the user's outcome: runtime, memory, case simplicity or release readiness. Use existing trustworthy evidence before collecting more. Separate total increments, cost per accepted increment, rejected work, and one-off I/O; a fast kernel does not address an excessive increment count. Inspect the actual execution route, concurrency and data movement before tuning arithmetic.
Pick the largest plausible bottleneck, estimate its ceiling on total savings, and state what measurement would change the decision. Consider algorithmic work reduction, conservative search/certificate reuse, batching, fused passes, ownership and memory layout—not just small kernel substitutions. Such changes still need their relevant invalidation, failure and accuracy checks. Change scientific inputs only as an explicitly scoped, sensitivity-tested experiment.
Use risk-proportionate gates:
- Exploration: one focused correctness check and a representative timing can reject a bad idea; they cannot establish a release or whole-run speed claim.
- Candidate: test the changed boundary and relevant failure paths; compare stages that exercise it. Increase repetitions only when uncertainty could change the decision. Do not cycle indefinitely around noisy small wins.
- Delivery: freeze the selected installed candidate, run the relevant release gates, and measure a complete run if full-run performance is being claimed. Do not repeat that expensive gate after every local edit or unrelated fix.
Set a bounded investigation budget appropriate to the requested sprint. Stop or reprioritize when measured cost is too small, savings are not repeatable, or complexity outweighs expected benefit. Preserve a compact finding so the same failed experiment is not repeatedly rediscovered.
Identify the expensive boundary
Measure preparation, kinematics, material update, force assembly, contact, state transactions, reporting, checkpoint and export separately. Repeated copy/validation of large state arrays and rewriting an expanding JSON history can dominate a fast material kernel. Follow data ownership, not only FLOPs. Prefer one immutable accepted owner with explicit publication boundaries; never leave callbacks observing stale fields. An optimization requiring exclusive ownership must declare and test that restriction. This is a preferred implementation, not a ban on a better transaction design. The invariant is that readers see valid accepted state and failed trials do not corrupt it. Repeated validation may be fused or removed when a checked, immutable owner proves the same invariant across consumers. A pointer/address cache or an unchecked writable alias is not that proof.
Guarded native fast paths may reject individual points and repair them with the unchanged reference algorithm before publishing a batch. Do not fall back the entire batch unnecessarily; do not accept half-repaired trial state. Preserve validation coverage, requested cutbacks and source-law diagnostics, not every historical scan, copy or call boundary. Native callbacks and function pointers are trusted code, not data assets.
Evidence before speed claims
Choose the comparison before choosing the gate:
- Same discretization/algorithm: fix scientific inputs and compare equivalent accepted states. Bitwise equality is useful when arithmetic order is unchanged.
- New algorithm/discretization: compare time-to-solution at a declared accuracy target using common physical times, quantities and admissible field mappings. Different step counts, meshes and reduction order are allowed; justify error, convergence, path history and event handling instead of requiring byte equality.
- New hardware/backend: reselect operational budgets from capabilities and representative work. Keep scientific inputs separate from execution evidence; a missing optional accelerator need not invalidate the physical Model.
Freeze the selected candidate for its comparison, not the product forever. For a same-algorithm comparison fix mesh, inertia, time grid, contact and output cadence. For a method study name every intentionally varied choice and preserve the reference. Do not require replay from the same checkpoint when the methods have incompatible states; use a common initial problem and physical stations. Do not patch a running reference or replace its loaded runtime. If unrelated builds or tests overl
Read the complete source ↗