FESADev/docs/README.md

FESA Documentation Index

Purpose

This directory is the source of truth for FESA solver planning, architecture, numerical conventions, verification, and future implementation work.

Before changing solver code, read this file, then read the documents listed under "Required Reading".

Required Reading

1. ../AGENTS.md
2. ../PROGRESS.md
3. ../PLAN.md
4. PRD.md
5. HARNESS_ENGINEERING.md
6. ARCHITECTURE.md
7. ADR.md
8. NUMERICAL_CONVENTIONS.md
9. ABAQUS_INPUT_SUBSET.md
10. VERIFICATION_PLAN.md
11. RESULTS_SCHEMA.md
12. MITC4_FORMULATION.md

MULTI_AGENT_RESEARCH_PLAN.md is required when planning delegated research or creating/updating Codex agents.

Document Roles

Document	Role
PRD.md	Product scope, users, phase roadmap, and Phase 1 success criteria
HARNESS_ENGINEERING.md	Planner/Generator/Evaluator workflow, sprint contract format, and evaluator rubric
ARCHITECTURE.md	Solver architecture, ownership boundaries, data flow, and extension model
ADR.md	Durable architecture decisions and tradeoffs
NUMERICAL_CONVENTIONS.md	DOF, units, coordinate/sign conventions, precision, boundary/reaction policy
ABAQUS_INPUT_SUBSET.md	Phase 1 Abaqus .inp subset, parser behavior, and unsupported features
VERIFICATION_PLAN.md	Reference folder contract, benchmark matrix, tolerances, and negative tests
RESULTS_SCHEMA.md	Step/frame/field/history result model and HDF5 layout
MITC4_FORMULATION.md	MITC4 baseline formulation contract and pre-implementation open decisions
MULTI_AGENT_RESEARCH_PLAN.md	Codex agent roles, research sequence, and source map

Root-level coordination files:

Document	Role
../PLAN.md	Forward-looking task plan, priorities, owners, and open questions
../PROGRESS.md	Completed work, verification results, blockers, and current risks

Precedence Rules

When documents conflict:

1. AGENTS.md critical rules win.
2. ADR.md wins for accepted design decisions.
3. NUMERICAL_CONVENTIONS.md wins for DOF, units, precision, signs, and reaction recovery.
4. Domain-specific dossier documents win within their area:
   • Abaqus parser: ABAQUS_INPUT_SUBSET.md
   • Verification/reference data: VERIFICATION_PLAN.md
   • HDF5 results: RESULTS_SCHEMA.md
   • MITC4 element formulation: MITC4_FORMULATION.md
5. ARCHITECTURE.md provides system structure and should be updated when module responsibilities change.
6. PRD.md records scope and roadmap, not low-level implementation details.

If a lower-precedence document needs to override a higher-precedence decision, update or add an ADR first.

Phase 1 Hard Invariants

• Use 6 shell DOFs per node: UX, UY, UZ, RX, RY, RZ.
• Retain drilling DOF and use a small artificial drilling stiffness.
• Use double for real values.
• Use signed int64 ids, indices, equation ids, and sparse indices.
• Do not enforce a unit system; require self-consistent Abaqus-style units.
• Follow Abaqus-compatible sign conventions for results.
• Apply essential boundary conditions by constrained DOF elimination.
• Recover reactions from full vectors: R_full = K_full * U_full - F_full.
• Map Abaqus S4 to FESA MITC4.
• Defer S4R.
• Require singular system diagnostics.
• Defer mesh quality diagnostics.
• Validate against stored reference artifacts under ../references/; do not require Abaqus execution.
• Treat Abaqus *.inp files plus *_displacements.csv result files as the initial accepted reference artifact contract.

Implementation Readiness Checklist

Before creating Phase 1 implementation steps:

• Use ../references/ as the accepted reference artifact folder.
• Use Abaqus .inp files plus solved *_displacements.csv files as the first automated displacement reference format.
• Keep a compatibility note when a stored Abaqus reference input contains features outside the current Phase 1 parser subset.
• Finalize the MITC4 transverse shear tying-point equations.
• Finalize the MITC4 local shell basis algorithm.
• Finalize the default artificial drilling stiffness scale.
• Decide whether Phase 1 outputs only U and RF, or also S, E, and SF.
• Decide the build system, with CMake as the recommended default unless project constraints say otherwise.

Documentation Change Rules

• Keep changes narrow and update every affected document.
• When a change affects future work, update ../PLAN.md.
• When a meaningful change is completed, update ../PROGRESS.md.
• When a rule becomes binding, add or update an ADR.
• When a scope changes, update PRD.md.
• When module ownership changes, update ARCHITECTURE.md.
• When parser behavior changes, update ABAQUS_INPUT_SUBSET.md.
• When numerical conventions change, update NUMERICAL_CONVENTIONS.md.
• When output layout changes, update RESULTS_SCHEMA.md.
• When benchmark or tolerance policy changes, update VERIFICATION_PLAN.md.
• When MITC4 math or assumptions change, update MITC4_FORMULATION.md.