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 provides Abaqus input files and solved reference result files under the repository references/ folder. Abaqus is not available locally, so validation must compare against stored reference artifacts.

Current Architecture Constraints

• Follow AGENTS.md, PROGRESS.md, PLAN.md, docs/README.md, docs/HARNESS_ENGINEERING.md, docs/ARCHITECTURE.md, and docs/ADR.md.
• Use PLAN.md for future task ownership, priority, and open questions.
• Use PROGRESS.md for completed work, verification notes, blockers, and risks.
• 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.
• Use the Planner -> Generator -> Evaluator harness from docs/HARNESS_ENGINEERING.md for nontrivial implementation and phase execution.

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, references/ 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.

5. harness_sprint_planner

   • File: .codex/agents/harness-sprint-planner.toml
   • Role: convert PLAN.md tasks and phase steps into testable sprint contracts.

6. implementation_generator

   • File: .codex/agents/implementation-generator.toml
   • Role: implement exactly one accepted sprint contract using TDD.

7. harness_sprint_evaluator

   • File: .codex/agents/harness-sprint-evaluator.toml
   • Role: independently pass/fail sprint output against the contract, docs, tests, and reference artifacts.

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.

Before asking phase_planner or harness_sprint_planner to create implementation steps, review PROGRESS.md, PLAN.md, docs/README.md, and docs/HARNESS_ENGINEERING.md; list any unchecked Implementation Readiness Checklist items in the planning output.

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.

7. reference_artifact_curator

   • Reviews user-provided references/ artifacts for CSV/manifest completeness, result schema consistency, source solver metadata, tolerance clarity, and comparison path validity.

8. numerical_conventions_reviewer

   • Reviews implementation plans for drift from DOF, unit, sign, precision, reaction recovery, and singular diagnostic rules.

User-Provided Inputs Needed

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

1. Additional small Abaqus .inp files and solved result artifacts under references/.
2. Reaction-force reference exports when available, preferably using a documented *_reactions.csv convention.
3. Preferred numerical tolerances for reference comparison, or permission for agents to propose initial tolerances per benchmark.
4. The Abaqus version used to generate each reference artifact when it is not evident from the .inp file header.
5. Whether the first implementation plan should target CMake, another build system, or a project-specific build layout.
6. 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.