modify docu and reference

2026-08-28 00:32:30 +09:00
parent 41816c8aef
commit ca06b4b551
37 changed files with 30338 additions and 590 deletions
@@ -0,0 +1,105 @@
+# Step 6: backend-neutral-tangent-solver
+
+## 읽어야 할 파일
+
+- `AGENTS.md`
+- `docs/ARCHITECTURE.md`
+- `docs/ADR.md`
+- `docs/nonlinear-static-newton-raphson/formulation.md`
+- `docs/nonlinear-static-newton-raphson/numerical-review.md`
+- `include/fesa/solvers/linear/linear_solver.h`
+- `include/fesa/solvers/linear/mkl_pardiso_solver.h`
+- `src/fesa/solvers/linear/mkl_pardiso_solver.cpp`
+- `tests/unit/solvers/linear/linear_solver_test.cpp`
+- `tests/unit/solvers/linear/mkl_pardiso_solver_test.cpp`
+- Step 4 files: `include/fesa/elements/nonlinear_mitc4_shell.h`
+
+## 이전 Step 전제
+
+Step 4 defines generally nonsymmetric nonlinear tangent matrices. Current SPD `MklPardisoSolver` must remain unchanged.
+
+## 소유 파일
+
+- Create: `include/fesa/solvers/linear/tangent_solver.h`
+- Create: `include/fesa/solvers/linear/mkl_pardiso_tangent_solver.h`
+- Create: `src/fesa/solvers/linear/mkl_pardiso_tangent_solver.cpp`
+- Create: `tests/unit/solvers/linear/tangent_solver_test.cpp`
+- Test: `tests/unit/solvers/linear/mkl_pardiso_solver_test.cpp`
+- Modify: `src/fesa/CMakeLists.txt`
+- Modify: `tests/CMakeLists.txt`
+
+## 인터페이스
+
+```cpp
+namespace fesa {
+
+class TangentSolver {
+ public:
+  virtual ~TangentSolver() = default;
+  virtual Status FactorizeFresh(const SparseMatrix& matrix) = 0;
+  virtual Status SolveCorrection(const Vector& rhs,
+                                 Vector& correction) const = 0;
+};
+
+class MklPardisoTangentSolver final : public TangentSolver {
+ public:
+  MklPardisoTangentSolver();
+  ~MklPardisoTangentSolver() override;
+  Status FactorizeFresh(const SparseMatrix& matrix) override;
+  Status SolveCorrection(const Vector& rhs, Vector& correction) const override;
+};
+
+}  // namespace fesa
+```
+
+The MKL tangent adapter uses unsymmetric PARDISO full CSR with `mtype=11`. Existing `MklPardisoSolver` keeps `mtype=2`, SPD symmetry validation, and upper-triangle copy unchanged.
+
+## RED
+
+Add tests first.
+
+- `NSNR-SOLVER-001`: nonsymmetric 2x2 matrix factorizes and solves a known correction.
+- `NSNR-SOLVER-002`: `0x0` matrix factorize/solve succeeds with zero-size vectors.
+- `NSNR-SOLVER-003`: nonfinite matrix or RHS values fail without modifying output correction.
+- `NSNR-SOLVER-004`: singular/factorization failure maps to deterministic solver diagnostic.
+- `NSNR-SOLVER-005`: solve before successful factorization fails with solver diagnostic.
+- `NSNR-SOLVER-006`: existing SPD `MklPardisoSolver` still rejects nonsymmetric public CSR and passes prior tests.
+
+Run:
+
+```powershell
+cmake --build .harness/build --config Debug
+ctest --test-dir .harness/build -C Debug -R "TangentSolver|MklPardiso" --output-on-failure
+```
+
+Expected: new tests fail. Unexpected pass stops.
+
+## GREEN
+
+Implement backend-neutral tangent solver boundary and MKL full-CSR adapter. Factorization is fresh per call, releases previous backend state, validates dimensions and finite values, and translates PARDISO errors to FESA `Status`.
+
+## VERIFY
+
+```powershell
+cmake --fresh -S . -B .harness/build -G "Visual Studio 18 2026" -A x64 `
+  "-DFESA_GTEST_SOURCE_DIR=$gtestSource" `
+  "-DMKL_DIR=$mklDir" `
+  "-DTBB_DIR=$tbbDir" `
+  "-DHDF5_DIR=$hdf5Dir"
+cmake --build .harness/build --config Debug
+ctest --test-dir .harness/build -C Debug -R "TangentSolver|MklPardiso" --output-on-failure
+ctest --test-dir .harness/build -C Debug --show-only=json-v1
+ctest --test-dir .harness/build -C Debug --output-on-failure
+```
+
+Recheck `.harness/config.json` before default commands.
+
+## 상태 기록
+
+Update only Step 6 status and one-line payload. Executor owns timestamps, commits, retry, and advancement.
+
+## 금지사항
+
+- Do not modify SPD `MklPardisoSolver` behavior except tests proving it is unchanged. 이유: existing linear solver contract must remain stable.
+- Do not symmetrize or regularize tangent matrices. 이유: approved tangent may be nonsymmetric and failures must surface.
+- Do not expose MKL types in public headers. 이유: backend types remain behind solver boundaries.