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.