FESADev/docs/MULTI_AGENT_RESEARCH_PLAN.md

Multi-Agent Research Plan

Purpose

This document is the durable planning memo for FESA's research-oriented multi-agent workflow. It records what the agents should investigate before solver implementation begins.

No solver code should be implemented from this plan directly. Each agent should produce an English technical dossier that an implementer can later follow.

Project Context

FESA is a C++17 finite element structural analysis solver. Phase 1 targets a linear static MITC4 shell solver with linear elastic material, nodal loads, fixed boundary conditions, an Abaqus input subset, HDF5-oriented results, and reference-result comparison.

The user will provide Abaqus input files and solved reference result files under a repository reference/ folder. Abaqus is not available locally, so validation must compare against stored reference artifacts.

Current Architecture Constraints

• Follow AGENTS.md, docs/ARCHITECTURE.md, and docs/ADR.md.
• Use runtime polymorphism for elements, materials, loads, boundary conditions, and analysis algorithms.
• Keep Domain close to immutable after parsing.
• Use AnalysisModel for the active step view.
• Use AnalysisState for mutable physical state and iteration state.
• Let DofManager own DOF definitions, constrained/free DOF mapping, equation numbering, and sparse pattern support.
• Use Strategy plus Template Method for analysis execution.
• Use Factory plus Registry for Abaqus keyword to object creation.
• Keep MKL, TBB, and HDF5 behind adapter/wrapper boundaries.
• Store results using step/frame/field/history concepts.

Created Codex Agents

The first recommended batch has been created under .codex/agents/.

1. fem_literature_researcher

   • File: .codex/agents/fem-literature-researcher.toml
   • Role: research FEM shell literature, MITC family background, locking behavior, and implementation implications.

2. verification_benchmark_researcher

   • File: .codex/agents/verification-benchmark-researcher.toml
   • Role: research benchmark cases, reference folder contracts, comparison methods, and acceptance criteria.

3. mitc4_formulation_researcher

   • File: .codex/agents/mitc4-formulation-researcher.toml
   • Role: research MITC4 formulation details and convert them into implementation requirements.

4. abaqus_compatibility_researcher

   • File: .codex/agents/abaqus-compatibility-researcher.toml
   • Role: research the Phase 1 Abaqus input subset and parser compatibility rules.

Recommended Agent Execution Order

1. Run fem_literature_researcher.
2. Run verification_benchmark_researcher.
3. Run mitc4_formulation_researcher.
4. Run abaqus_compatibility_researcher.

This order keeps theory, verification targets, element formulation, and input compatibility aligned before implementation planning.

Later Agent Candidates

These agents should be created after the first four produce dossiers.

1. solver_architecture_researcher

   • Refines responsibilities among Domain, AnalysisModel, AnalysisState, DofManager, Assembler, and LinearSolver.

2. sparse_solver_researcher

   • Researches sparse pattern generation, CSR/COO assembly, MKL PARDISO integration, and TBB-safe assembly strategies.

3. results_hdf5_schema_researcher

   • Designs the HDF5 group/dataset schema for step/frame/field/history outputs.

4. nonlinear_roadmap_researcher

   • Researches geometric nonlinearity, Newton-Raphson, tangent stiffness, increments, and convergence criteria.

5. thermal_coupling_researcher

   • Researches heat transfer, thermal load generation, thermal strain, and thermal-stress coupling.

6. architecture_guardrail_reviewer

   • Reviews dossiers, phase plans, and future implementation against project rules and ADRs.

User-Provided Inputs Needed

The following inputs should be requested from the user as the research matures:

1. The intended reference/ folder layout, or permission to propose one.
2. At least one simple Abaqus .inp file and its solved reference result artifact.
3. Preferred reference result format if available: .dat, .rpt, exported .csv, HDF5, or another structured format.
4. Whether Phase 1 should map Abaqus S4 directly to FESA MITC4.
5. Whether Phase 1 shell nodes use six DOFs per node from the beginning: three translations and three rotations.
6. Preferred numerical tolerances for reference comparison, or permission for agents to propose initial tolerances per benchmark.
7. Whether the first implementation plan should target CMake, another build system, or a project-specific build layout.

Seed Sources

• Abaqus input syntax rules: https://abaqus-docs.mit.edu/2017/English/SIMACAEMODRefMap/simamod-c-inputsyntax.htm
• Abaqus shell section behavior: https://abaqus-docs.mit.edu/2017/English/SIMACAEELMRefMap/simaelm-c-shellsectionbehavior.htm
• OpenSees ShellMITC4 manual: https://opensees.berkeley.edu/OpenSees/manuals/usermanual/640.htm
• MITC3+/MITC4+ benchmark paper: https://web.mit.edu/kjb/www/Principal_Publications/Performance_of_the_MITC3%2B_and_MITC4%2B_shell_elements_in_widely_used_benchmark_problems.pdf
• COMSOL Scordelis-Lo benchmark example: https://doc.comsol.com/5.6/doc/com.comsol.help.models.sme.scordelis_lo_roof/scordelis_lo_roof.html
• NAFEMS nonlinear benchmark survey page: https://www.nafems.org/publications/pubguide/benchmarks/Page6/

Non-Goals

• Do not implement solver code.
• Do not generate phase execution files until the user explicitly asks for implementation planning.
• Do not require Abaqus execution in local validation.
• Do not treat unsourced formulas or benchmark constants as final.