# 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.