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.
• Follow the technical dossier documents:
  • docs/NUMERICAL_CONVENTIONS.md
  • docs/ABAQUS_INPUT_SUBSET.md
  • docs/VERIFICATION_PLAN.md
  • docs/RESULTS_SCHEMA.md
  • docs/MITC4_FORMULATION.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.
• Use 6 DOFs per shell node: UX, UY, UZ, RX, RY, RZ.
• Use small artificial drilling stiffness in Phase 1, with the final scale documented before implementation.
• Do not enforce a unit system; use Abaqus-style self-consistent units.
• Follow Abaqus result sign conventions.
• Use constrained DOF elimination and full-vector reaction recovery.
• Use double precision and int64 ids/indices/equation numbering.
• Require singular system diagnostics.
• Defer mesh quality diagnostics in Phase 1.
• Map Abaqus S4 to FESA MITC4; defer S4R.

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. Confirmation or revision of the proposed reference/ folder layout in docs/VERIFICATION_PLAN.md.
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, JSON, HDF5, or another structured format.
4. Preferred numerical tolerances for reference comparison, or permission for agents to propose initial tolerances per benchmark.
5. The Abaqus version used to generate reference artifacts.
6. Whether the first implementation plan should target CMake, another build system, or a project-specific build layout.
7. The final default scale for artificial drilling stiffness, after formulation research.

Seed Sources

• Abaqus input syntax rules: https://abaqus-docs.mit.edu/2017/English/SIMACAEMODRefMap/simamod-c-inputsyntax.htm
• Abaqus conventions for DOFs, units, coordinate systems, and stress/strain components: https://abaqus-docs.mit.edu/2017/English/SIMACAEMODRefMap/simamod-c-conventions.htm
• Abaqus boundary keyword reference: https://abaqus-docs.mit.edu/2017/English/SIMACAEKEYRefMap/simakey-r-boundary.htm
• Abaqus concentrated load keyword reference: https://abaqus-docs.mit.edu/2017/English/SIMACAEKEYRefMap/simakey-r-cload.htm
• Abaqus shell section behavior: https://abaqus-docs.mit.edu/2017/English/SIMACAEELMRefMap/simaelm-c-shellsectionbehavior.htm
• Abaqus conventional shell element library: https://abaqus-docs.mit.edu/2017/English/SIMACAEELMRefMap/simaelm-r-shellgeneral.htm
• OpenSees ShellMITC4 manual: https://opensees.berkeley.edu/OpenSees/manuals/usermanual/640.htm
• Dvorkin-Bathe four-node shell element paper: https://web.mit.edu/kjb/www/Publications_Prior_to_1998/A_Continuum_Mechanics_Based_Four-Node_Shell_Element_for_General_Nonlinear_Analysis.pdf
• 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/
• HDF5 data model: https://docs.hdfgroup.org/documentation/hdf5/latest/_h5_d_m__u_g.html
• HDF5 datasets: https://docs.hdfgroup.org/documentation/hdf5/latest/_h5_d__u_g.html
• HDF5 attributes: https://portal.hdfgroup.org/documentation/hdf5/latest/_h5_a__u_g.html
• Intel oneMKL pardiso_64: https://www.intel.com/content/www/us/en/docs/onemkl/developer-reference-c/2024-2/pardiso-64.html

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.
• Do not add mesh quality diagnostics to Phase 1 planning unless the user changes the decision.