FESADev/phases/1-linear-static-mitc4/step7.md

Step 7: math-solver-adapters

Sprint Contract

Objective

Implement vector, sparse matrix, and linear solver interfaces plus a deterministic test solver adapter while preserving future MKL/TBB adapter boundaries.

Required Reading

• /AGENTS.md
• /PROGRESS.md
• /PLAN.md
• /docs/README.md
• /docs/HARNESS_ENGINEERING.md
• /docs/ARCHITECTURE.md
• /docs/ADR.md
• /docs/NUMERICAL_CONVENTIONS.md
• /phases/1-linear-static-mitc4/step6.md

Scope

• Add minimal vector and sparse matrix abstractions needed by assembly and linear static solving.
• Add a linear solver interface with deterministic test implementation.
• Keep MKL/TBB-specific code behind adapter boundaries if any placeholder is added.
• Surface solver singularity diagnostics in a structured way.

Allowed Files

• include/**
• src/**
• tests/**
• docs/ADR.md if adapter decisions need clarification
• PLAN.md
• PROGRESS.md
• phases/1-linear-static-mitc4/index.json

Explicit Non-Goals

• Do not require Intel oneAPI installation for Phase 1 unit tests.
• Do not expose MKL, TBB, or HDF5 APIs in solver core headers.
• Do not implement element assembly or analysis algorithms in this step.

Tests To Write First

• Sparse pattern and insertion tests with int64 indices.
• Deterministic small linear solve tests.
• Singular solve diagnostic tests.
• Adapter-boundary tests or compile checks showing core APIs do not include MKL/TBB headers.

Reference Artifacts

• None.

Acceptance Commands

python scripts/validate_workspace.py

Evaluator Checklist

• Core math interfaces are dependency-clean.
• Singular solver failures produce diagnostics, not crashes or silent NaNs.
• Tests cover sparse storage, solve success, and solve failure.
• Future MKL acceleration remains possible without changing solver core contracts.

Handoff Requirements

• Record math interfaces, validation, and adapter caveats in PROGRESS.md.
• Update PLAN.md if MKL/TBB integration becomes a future task.
• Update the matching phase index entry: use completed with a one-line summary, or blocked with blocked_reason, or error with error_message.

Verification

1. Run the acceptance command.
2. Inspect public headers for third-party API leakage.

Do Not

• Do not optimize sparse storage before correctness and testability are established.