# Architecture Decision Records

## ADR-001: Solver Development Workflow Is Stage-Gated
**Decision**: FESA solver features must follow this workflow: requirements, research, formulation, I/O contract, TDD reference models, implementation, reference comparison, tolerance decision, release.

**Reason**: Structural solver correctness depends on more than code execution. Requirements, mathematical formulation, input/output contracts, reference artifacts, numerical comparison, and release evidence must be traceable.

**Tradeoff**: Initial feature delivery is slower. The benefit is that implementation agents do not invent formulation, tolerance, or reference assumptions during coding.

## ADR-002: C++17/MSVC/CMake/CTest Remain The Baseline
**Decision**: The project targets C++17 or newer, MSVC on Windows, CMake, and CTest. Default validation uses Visual Studio 17 2022, x64, Debug.

**Reason**: The project is a Windows/MSVC structural solver. CMake/CTest gives a consistent build and test entry point for both harness validation and feature development.

**Tradeoff**: Visual Studio solution-only workflows and non-MSVC toolchains are not the primary path. They can be introduced by explicit ADR when needed.

## ADR-003: MITC4 Linear Static Shell Is The Initial Solver Feature
**Decision**: The first solver implementation target is `mitc4-linear-static-shell`: a 4-node MITC4 shell element for linear static structural analysis.

**Reason**: MITC4 is a meaningful shell element target with strong research and OpenSees reference structure. It exercises element formulation, assembly, solver, I/O, and reference verification without immediately requiring nonlinear or dynamic analysis.

**Tradeoff**: This is more complex than a truss/bar bootstrap. The project accepts the complexity because MITC4 is the requested initial element.

## ADR-004: OpenSees-Inspired Architecture, Modern C++ Ownership
**Decision**: FESA follows OpenSees-like conceptual boundaries: `Domain`, `Node`, `Element`, `Material/Section`, `Analysis`, `SystemOfEqn`, and `Recorder/ResultWriter`. It does not clone OpenSees raw ownership style.

**Reason**: OpenSees provides a useful solver architecture vocabulary, while modern C++17 RAII gives safer ownership and testable module boundaries.

**Tradeoff**: FESA classes will not be drop-in compatible with OpenSees. Similarity is architectural, not API compatibility.

## ADR-005: MKL PARDISO For Global Linear Solves
**Decision**: FESA uses Intel oneAPI MKL CSR matrices and PARDISO for the initial global linear static solve.

**Reason**: Shell models need sparse linear algebra beyond toy dense solvers. MKL is already aligned with the Windows/MSVC toolchain and provides production-grade direct sparse solving.

**Tradeoff**: oneAPI MKL becomes a required dependency for real solver builds. The CMake configuration must detect `MKLROOT` or a known oneAPI installation path.

## ADR-006: TBB For Parallel Element Work
**Decision**: FESA uses Intel oneAPI TBB for parallel element stiffness, residual/result recovery, and other embarrassingly parallel solver phases.

**Reason**: Element-level computation is a natural parallelism boundary. TBB integrates with oneAPI and avoids designing a custom thread pool.

**Tradeoff**: Global assembly must be deterministic. FESA will use thread-local contribution buffers and deterministic merge rather than concurrent writes into global CSR arrays.

## ADR-007: HDF5 For Solver And Reference Results
**Decision**: FESA writes solver results to HDF5 and compares against stored HDF5 reference artifacts.

**Reason**: Shell results contain structured mesh, step/frame, nodal, element, Gauss point, resultant, stress, metadata, and tolerance data. HDF5 is better suited than flat CSV for this result hierarchy.

**Tradeoff**: HDF5 becomes a required dependency. FESA will provide an internal RAII wrapper over the HDF5 C API, but the actual HDF5 C library must be supplied by `HDF5_ROOT` or `HDF5_DIR`. The current local Windows install is `C:\Program Files\HDF_Group\HDF5\2.1.1`; use `HDF5_ROOT` for that root or `HDF5_DIR` for `C:\Program Files\HDF_Group\HDF5\2.1.1\cmake`.

## ADR-008: Single Tolerance Policy
**Decision**: Reference comparison uses a single tolerance value `1e-5`. A compared scalar passes when absolute error or relative error is within `1e-5`.

**Reason**: A single tolerance policy is simple, explicit, and matches the current project decision.

**Tradeoff**: Quantity-specific scaling is deferred. If future models show that one global tolerance is too strict or too loose for some quantities, a new ADR must revise this policy.

## ADR-009: Agents Do Not Run Reference Solvers
**Decision**: Abaqus, Nastran, and other reference solvers are not run by agents. Agents only consume stored reference artifacts.

**Reason**: Reference solver execution requires licensing, environment control, provenance, and human approval. Stored artifacts make validation reproducible inside the harness.

**Tradeoff**: Implementation can be blocked until required reference artifacts are supplied.

## ADR-010: Domain, AnalysisModel, And AnalysisState Are Separate
**Decision**: `Domain` owns parsed model definition, `AnalysisModel` owns the active step execution view, and `AnalysisState` owns mutable solution and iteration state.

**Reason**: This prevents equation ids, displacement vectors, residuals, and future nonlinear/time states from leaking into input model objects. It also keeps the static solver compatible with future nonlinear, dynamic, and thermal workflows.

**Tradeoff**: The initial implementation has more object boundaries than a single monolithic model container.

## ADR-011: Factory/Registry Handles Input Object Creation
**Decision**: Abaqus keyword parsing and internal object creation are separated through factory/registry mechanisms.

**Reason**: Adding elements, materials, loads, boundary conditions, sets, or properties should not require rewriting parser control flow.

**Tradeoff**: The first parser implementation needs a small registry layer before many object types exist.

## ADR-012: Boundary Conditions Use DOF Elimination
**Decision**: Essential boundary conditions are applied by constrained DOF elimination. Reactions are recovered from the full system as `K_full * U_full - F_full`.

**Reason**: This gives a clear reduced solve while preserving physically meaningful reaction recovery for reference comparison.

**Tradeoff**: The implementation must preserve enough full-system information for reaction recovery instead of only storing the reduced matrix.

## ADR-013: Results Use Step/Frame/Field/History Model
**Decision**: HDF5 results are organized by step, frame, field output, and history output.

**Reason**: The same result model can support static, nonlinear, dynamic, heat-transfer, and thermal-stress analyses.

**Tradeoff**: The v0 linear static output is more structured than a flat single-step result file.

## ADR-014: Double Precision And 64-Bit Numbering
**Decision**: Solver scalar calculations use `double`; ids, sparse indices, and equation numbering are designed around int64 boundaries.

**Reason**: Structural solver verification needs double precision, and large sparse systems should not be blocked by 32-bit numbering assumptions.

**Tradeoff**: Memory use may be higher than a 32-bit-only implementation.

## ADR-015: Units Are User-Consistent, Not Enforced
**Decision**: FESA does not enforce a unit system. Inputs and reference artifacts must be unit-consistent and record units in metadata.

**Reason**: Abaqus-style workflows commonly rely on user-consistent units.

**Tradeoff**: The solver cannot automatically detect every unit mismatch. Reference metadata and validation reports must make unit assumptions visible.