add uncommitted files

2026-07-29 23:32:26 +09:00
parent fb0f8f39a0
commit f5379472ce
80 changed files with 7461 additions and 1 deletions
@@ -0,0 +1,21 @@
+{
+  "project": "FESA",
+  "phase": "equation-and-linear-solve",
+  "steps": [
+    {
+      "step": 0,
+      "name": "symmetric-csr-assembly",
+      "status": "pending"
+    },
+    {
+      "step": 1,
+      "name": "essential-bc-elimination",
+      "status": "pending"
+    },
+    {
+      "step": 2,
+      "name": "pardiso-linear-solver",
+      "status": "pending"
+    }
+  ]
+}
@@ -0,0 +1,58 @@
+# Step 0: Symmetric CSR Assembly
+
+## 읽어야 할 파일
+
+- `/AGENTS.md`
+- `/docs/PRD.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/ADR.md`
+- `/include/fesa/model/domain.hpp`
+- `/include/fesa/fem/dof_manager.hpp`
+- `/include/fesa/elements/beam/beam3d2.hpp`
+
+## 작업
+
+Beam local contribution으로부터 deterministic serial symmetric CSR과 full load vector를
+조립한다.
+
+```cpp
+struct SymmetricCsr final {
+    std::size_t order;
+    std::vector<std::int32_t> row_offsets;
+    std::vector<std::int32_t> column_indices;
+    std::vector<double> values;
+};
+struct EquationSystem final {
+    SymmetricCsr stiffness;
+    std::vector<double> force;
+};
+[[nodiscard]] EquationSystem assemble_serial(
+    const Domain&,
+    const DofManager&);
+```
+
+- sparsity pattern builder와 numeric contribution merge를 분리한다.
+- `(row,column,element-origin,local-order)`의 안정된 순서로 합산한다.
+- hand-calculated 2-element system, duplicate contribution, external ID 순서 변화,
+  CSR invariant를 실패 테스트로 먼저 작성한다.
+
+## Acceptance Criteria
+
+```powershell
+cmake --build --preset windows-debug
+ctest --preset windows-debug -R "SparsePattern|SerialAssembly|SymmetricCsr" --output-on-failure
+ctest --preset windows-debug --output-on-failure
+```
+
+## 검증 절차
+
+1. expected CSR 구조와 값을 고정한 실패 테스트를 실행한다.
+2. pattern과 numeric assembly를 최소 구현한다.
+3. row offset, sorted column, upper/lower storage 계약을 확인한다.
+4. 전체 테스트와 index를 갱신한다.
+
+## 금지사항
+
+- 공유 CSR에 병렬 누적하지 마라. 이유: 이 phase는 serial oracle을 만든다.
+- PARDISO를 호출하지 마라. 이유: backend step의 책임이다.
+- element formulation을 assembly에 복제하지 마라. 이유: 모듈 경계를 깨뜨린다.
@@ -0,0 +1,56 @@
+# Step 1: Essential BC Elimination
+
+## 읽어야 할 파일
+
+- `/AGENTS.md`
+- `/docs/PRD.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/ADR.md`
+- `/include/fesa/assembly/symmetric_csr.hpp`
+- `/include/fesa/assembly/equation_system.hpp`
+- `/include/fesa/fem/dof_manager.hpp`
+- `/include/fesa/model/step_definition.hpp`
+
+## 작업
+
+0과 비영 지정변위를 지원하는 essential-BC elimination과 full-vector 복원을 구현한다.
+
+```cpp
+struct ReducedSystem final {
+    SymmetricCsr stiffness;
+    std::vector<double> force;
+    std::vector<std::size_t> free_to_full;
+    std::vector<double> prescribed_full;
+};
+[[nodiscard]] ConstraintResult eliminate_essential_bcs(
+    const EquationSystem& original,
+    const DofManager& dofs,
+    std::span<const PrescribedDof> prescribed);
+[[nodiscard]] std::vector<double> recover_reaction(
+    const EquationSystem& original,
+    std::span<const double> full_displacement);
+```
+
+- 작은 hand calculation으로 RHS shift, 0/비영 prescribed value, all constrained,
+  충돌 조건, \(r=Ku-f\) 반력 복원을 먼저 테스트한다.
+
+## Acceptance Criteria
+
+```powershell
+cmake --build --preset windows-debug
+ctest --preset windows-debug -R "EssentialBc|ConstraintElimination|Reaction" --output-on-failure
+ctest --preset windows-debug --output-on-failure
+```
+
+## 검증 절차
+
+1. 비영 지정값 테스트의 실패를 먼저 확인한다.
+2. 원래 EquationSystem을 보존한 채 reduced system을 생성한다.
+3. 복원 변위와 원래 평형식 반력을 assertion한다.
+4. 전체 테스트와 index를 갱신한다.
+
+## 금지사항
+
+- penalty나 큰 수를 사용하지 마라. 이유: 승인된 elimination 정책과 다르다.
+- 반력을 reduced matrix에서 계산하지 마라. 이유: 원래 \(K,u,f\)가 필요하다.
+- MPC/Lagrange multiplier를 추가하지 마라. 이유: 범위 밖이다.
@@ -0,0 +1,65 @@
+# Step 2: PARDISO Linear Solver
+
+## 읽어야 할 파일
+
+- `/AGENTS.md`
+- `/docs/PRD.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/ADR.md`
+- `/cmake/FesaDependencies.cmake`
+- `/include/fesa/assembly/symmetric_csr.hpp`
+- `/include/fesa/core/diagnostic.hpp`
+
+## 작업
+
+MKL PARDISO를 RAII adapter 뒤에 격리하고 symmetric positive-definite reduced system을
+푼다.
+
+```cpp
+struct LinearSolveResult final {
+    std::vector<double> solution;
+    double relative_residual;
+    std::vector<Diagnostic> diagnostics;
+};
+class LinearSolver {
+public:
+    virtual ~LinearSolver() = default;
+    [[nodiscard]] virtual LinearSolveResult solve(
+        const SymmetricCsr&,
+        std::span<const double> rhs) = 0;
+};
+class PardisoLinearSolver final : public LinearSolver {
+public:
+    PardisoLinearSolver();
+    ~PardisoLinearSolver() override;
+    [[nodiscard]] LinearSolveResult solve(
+        const SymmetricCsr&,
+        std::span<const double>) override;
+};
+```
+
+- 3x3 SPD, repeated solve, invalid CSR, dimension mismatch, singular matrix를 먼저
+  테스트한다.
+- `mtype=2`, LP64 index, `iparm[34]=1`, matrix checker, analysis/factor/solve/release
+  phase를 사용한다.
+
+## Acceptance Criteria
+
+```powershell
+cmake --build --preset windows-debug
+ctest --preset windows-debug -R "Pardiso|LinearSolver" --output-on-failure
+ctest --preset windows-debug --output-on-failure
+```
+
+## 검증 절차
+
+1. adapter test의 link/behavior 실패를 확인한다.
+2. 모든 MKL handle/workspace를 RAII로 해제한다.
+3. 해와 상대잔차를 독립 계산으로 확인한다.
+4. 전체 테스트와 index를 갱신한다.
+
+## 금지사항
+
+- MKL 타입을 `LinearSolver` public contract에 노출하지 마라. 이유: backend 격리다.
+- singular system을 임의 regularization하지 마라. 이유: 모델 오류를 숨긴다.
+- PARDISO 실행 중 TBB task를 중첩하지 마라. 이유: oversubscription 정책 위반이다.