FESADev/docs/project-plan/SOLVER_IMPLEMENT_INITIAL_PLAN.md

# MITC4 Linear Static Shell Solver Initial Implementation Plan

## Summary
FESA will implement an initial finite element structural solver feature named `mitc4-linear-static-shell`. The feature reads an Abaqus-style input file, builds an internal finite element model, performs linear static analysis with a MITC4 shell element, writes HDF5 results, and verifies those results against stored Abaqus reference artifacts.

The implementation must follow the full solver development workflow:

1. Analyze new solver feature requirements.
2. Research books, papers, manuals, and related solver implementations.
3. Write the finite element formulation required for code implementation.
4. Define solver input and output data contracts.
5. Create TDD test models for both FESA and the reference solver.
6. Implement code.
7. Compare FESA results against reference solver results for nodal displacement, reaction, element internal force, and stress.
8. Mark implementation complete only when result differences are within tolerance.
9. Release the solver feature.

## Scope
Feature id: `mitc4-linear-static-shell`

Included:
- Linear static structural analysis.
- MITC4 4-node shell element.
- Six DOF per node: `U1, U2, U3, UR1, UR2, UR3`.
- Single-layer isotropic linear elastic shell section.
- Abaqus `.inp` subset input.
- Intel oneAPI MKL CSR/PARDISO sparse linear solve.
- Intel oneAPI TBB parallel element computation and result recovery.
- HDF5 solver result output.
- Stored Abaqus S4R primary reference comparison.
- Stored Abaqus S4 diagnostic reference comparison.

Excluded:
- Nastran BDF input.
- Nonlinear geometry.
- Nonlinear material.
- Dynamic analysis.
- Buckling/eigenvalue analysis.
- Composite/layered shell section.
- Contact.
- Agent-run Abaqus or Nastran execution.
- Reference artifact generation by agents.
- OpenSees API compatibility.

## Architecture
Use OpenSees as an architectural reference, not as an API clone. FESA should use modern C++17 ownership and small testable modules.

Primary conceptual modules:
- `Domain`: model container for nodes, elements, constraints, loads, materials, sections, and analysis metadata.
- `Node`: id, coordinates, and six ordered DOFs.
- `Element`: abstract element behavior for stiffness, internal force, result recovery, and connectivity.
- `ShellMITC4Element`: four-node MITC4 implementation with 24 element DOFs.
- `Material/Section`: isotropic elastic shell section with membrane, bending, shear, and stress recovery contract.
- `Analysis`: linear static analysis driver.
- `SystemOfEqn`: DOF numbering, constraints, CSR assembly, MKL PARDISO solve.
- `ResultWriter`: HDF5 output.
- `ReferenceComparator`: HDF5 reference comparison.

## Step 1: New Solver Feature Requirements Analysis
Create `docs/requirements/mitc4-linear-static-shell.md`.

The requirements analysis document must define:
- analysis type: linear static
- element type: MITC4 shell
- DOF order: `U1, U2, U3, UR1, UR2, UR3`
- material: isotropic linear elastic
- section: uniform shell thickness
- input: Abaqus `.inp` subset
- output: HDF5
- verification quantities: nodal displacement, reaction, element internal force/resultant, stress
- tolerance: single value `1e-5`
- pass rule: `abs(error) <= 1e-5` or `relative(error) <= 1e-5`

Acceptance criteria:
- Every must requirement has a verification method.
- Every numerical output requirement has component names and units policy.
- Reference artifact needs are listed under `references/mitc4-linear-static-shell/`.

## Step 2: Research Evidence
Create `docs/research/mitc4-linear-static-shell-research.md`.

Research must cover:
- Dvorkin-Bathe continuum mechanics based four-node shell formulation.
- MITC4 mixed interpolation of tensorial components.
- Assumed transverse shear strain interpolation and shear locking.
- OpenSees `ShellMITC4` class structure and resultants.
- Abaqus S4/S4R behavior as practical reference elements.
- Patch tests and Scordelis-Lo shell benchmark.

The research document must separate verified source facts from implementation inference.

## Step 3: FEM Formulation
Create `docs/formulations/mitc4-linear-static-shell-formulation.md`.

The formulation must define:
- reference coordinates and node ordering.
- shell midsurface interpolation.
- director and local coordinate basis policy.
- six-DOF nodal displacement vector.
- membrane, bending, transverse shear strain measures.
- MITC transverse shear tying/interpolation.
- isotropic shell constitutive matrix.
- element stiffness expression.
- 2x2 Gauss integration.
- drill stiffness policy.
- stress and resultant recovery.
- invalid Jacobian and degenerate element checks.

Default drill stiffness policy:
- v0 hardcodes `alpha=1`.
- `Ktt = alpha * min_eigenvalue(D_membrane)`.
- Input override is deferred to a later phase.

## Step 4: I/O Contract
Create `docs/io-definitions/mitc4-linear-static-shell-io.md`.

Input subset:
- `*NODE`
- `*ELEMENT, TYPE=S4`
- `*ELEMENT, TYPE=S4R`
- `*MATERIAL`
- `*ELASTIC`
- `*SHELL SECTION`
- `*BOUNDARY`
- `*CLOAD`
- `*STEP`

Output format:
- HDF5 file.
- No CSV output is required for this feature.

Required HDF5 layout:
```text
/metadata
  feature_id
  solver_version
  model_id
  units
  tolerance
  reference_solver

/mesh/nodes
/mesh/elements/mitc4/connectivity

/results/step_000/frame_000/nodal/displacement
/results/step_000/frame_000/nodal/reaction
/results/step_000/frame_000/element/forces
/results/step_000/frame_000/element/stress
```

Required result components:
- displacement: `U1, U2, U3, UR1, UR2, UR3`
- reaction: `RF1, RF2, RF3, RM1, RM2, RM3`
- element force/resultant: `N11, N22, N12, M11, M22, M12, Q13, Q23`
- stress: `S11, S22, S12, S13, S23`

## Step 5: TDD Reference Models
Create `docs/reference-models/mitc4-linear-static-shell-reference-models.md`.

Reference policy:
- FESA agents do not run Abaqus or Nastran.
- Stored Abaqus S4R HDF5 artifacts are the primary pass/fail reference.
- Stored Abaqus S4 HDF5 artifacts are diagnostic only.

Initial model portfolio:
- membrane patch
- bending patch
- transverse shear patch
- twist patch
- coarse Scordelis-Lo shell

Each model bundle must include:
```text
references/mitc4-linear-static-shell/<model-id>/
  model.inp
  metadata.json
  abaqus_s4r/results.h5
  abaqus_s4/results.h5
  README.md
```

`metadata.json` must record:
- model id
- source/provenance
- Abaqus version
- element type
- units
- output locations
- tolerance `1e-5`
- compared quantities
- known limitations

## Step 6: Code Implementation Plan
Create `docs/implementation-plans/mitc4-linear-static-shell-implementation-plan.md`.

Implementation must be TDD-first:

1. Write failing parser tests.
2. Implement minimum Abaqus `.inp` parser behavior.
3. Write failing MITC4 element tests.
4. Implement shape functions, Jacobian checks, MITC shear interpolation, stiffness, and recovery.
5. Write failing assembly tests.
6. Implement DOF numbering, constraint handling, and deterministic CSR assembly.
7. Write failing MKL PARDISO solve tests.
8. Implement solver wrapper and reaction recovery.
9. Write failing TBB deterministic parallel tests.
10. Implement TBB parallel element computations with deterministic merge.
11. Write failing HDF5 schema tests.
12. Implement HDF5 C API RAII wrapper and result writer.
13. Write failing reference comparison tests.
14. Implement HDF5 reference comparator.
15. Run full validation.

Required validation commands:
```powershell
python -m unittest discover -s scripts -p "test_*.py"
python scripts/validate_workspace.py
ctest --test-dir build/msvc-debug --output-on-failure -C Debug -L mitc4
```

## Step 7: Reference Verification
Create `docs/reference-verifications/mitc4-linear-static-shell-reference-verification.md`.

Comparison inputs:
- FESA `results.h5`
- stored Abaqus S4R `results.h5`
- diagnostic Abaqus S4 `results.h5`
- metadata tolerance and schema version

Compared quantities:
- nodal displacement
- nodal reaction
- element internal force/resultant
- stress

Matching rules:
- node id for nodal quantities
- element id plus Gauss point id for element quantities
- component name for scalar comparisons

Pass rule:
```text
abs(error) <= 1e-5 OR relative(error) <= 1e-5
```

Report:
- compared quantity
- number of matched rows
- missing rows
- extra rows
- maximum absolute error
- maximum relative error
- worst id
- worst component
- pass/fail

## Step 8: Completion Decision
Implementation is complete only when:
- all required tests pass;
- CMake/MSVC/x64/Debug build passes;
- all required HDF5 result quantities compare within tolerance `1e-5`;
- no required reference artifact is missing;
- failures are not hidden as known limitations.

If comparison fails, classify the failure as one of:
- missing reference artifact
- schema mismatch
- id mismatch
- unit or coordinate mismatch
- formulation defect
- implementation defect
- tolerance failure
- reference artifact issue

Then return to the owning workflow step.

## Step 9: Release
Create `docs/releases/mitc4-linear-static-shell-release.md`.

Release document must include:
- feature id and scope
- supported input keywords
- supported outputs
- dependency versions
- test model list
- reference comparison summary
- tolerance policy
- known limitations
- validation commands and status

Release is not approved by build success alone. Release requires reference comparison success and documented limitations.

## Dependency Plan
MKL:
- Use oneAPI MKL through `MKLROOT` or known oneAPI path.
- Use CSR matrix storage and PARDISO for the global linear system.

TBB:
- Use oneAPI TBB through `TBBROOT` or known oneAPI path.
- Parallelize element-local stiffness and result recovery.
- Use deterministic merge for global assembly.

HDF5:
- FESA provides an internal RAII wrapper around the HDF5 C API.
- The HDF5 C library itself must be supplied through `HDF5_ROOT` or `HDF5_DIR`.
- The current local default is `C:\Program Files\HDF_Group\HDF5\2.1.1`; use `HDF5_ROOT` for this root or `HDF5_DIR` for `C:\Program Files\HDF_Group\HDF5\2.1.1\cmake`.
- HDF5 is required for solver output and reference comparison.

## Assumptions
- Abaqus reference artifacts are generated outside the agent workflow.
- S4R is the primary reference for pass/fail.
- S4 is diagnostic and does not determine pass/fail.
- The single tolerance value is `1e-5`.
- The initial implementation prioritizes correctness and traceability over broad element coverage.