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,101 @@
+# Step 2: finite-rotation-state
+
+## 읽어야 할 파일
+
+- `AGENTS.md`
+- `docs/ARCHITECTURE.md`
+- `docs/ADR.md`
+- `docs/nonlinear-static-newton-raphson/formulation.md`
+- `docs/nonlinear-static-newton-raphson/numerical-review.md`
+- `docs/nonlinear-static-newton-raphson/implementation-plan.md`
+- `include/fesa/math/vector3.h`
+- `include/fesa/math/matrix.h`
+- `tests/unit/math/vector3_test.cpp`
+- `tests/unit/math/matrix_test.cpp`
+- Step 1 files: `include/fesa/model/model_types.h`, `include/fesa/model/domain.h`
+
+## 이전 Step 전제
+
+Step 1 exposes nonlinear static semantic selection. This Step adds finite rotation math used by nonlinear MITC4 and state recovery.
+
+## 소유 파일
+
+- Create: `include/fesa/elements/finite_rotation.h`
+- Create: `src/fesa/elements/finite_rotation.cpp`
+- Create: `tests/unit/elements/finite_rotation_test.cpp`
+- Modify: `src/fesa/CMakeLists.txt`
+- Modify: `tests/CMakeLists.txt`
+
+## 인터페이스
+
+```cpp
+namespace fesa {
+
+struct FiniteRotationState {
+  Vector3 phi;
+  Matrix q;
+  Vector3 director;
+};
+
+Matrix ExpSkew(const Vector3& phi);
+Matrix LeftJacobianSO3(const Vector3& phi);
+Matrix InverseTransposeLeftJacobianSO3(const Vector3& phi);
+Result<FiniteRotationState> MakeFiniteRotationState(
+    const Vector3& phi, const Matrix& initial_frame);
+Result<FiniteRotationState> ApplyGlobalRotationIncrement(
+    const FiniteRotationState& committed,
+    const Vector3& delta_phi,
+    const Matrix& initial_frame);
+
+}  // namespace fesa
+```
+
+## RED
+
+Add tests first.
+
+- `NSNR-ROT-001`: zero `phi` returns `Q0` and `director=Q0*e3`.
+- `NSNR-ROT-002`: finite `phi` satisfies `Q=exp(phi^)Q0`, `Q^T Q=I`, `det(Q)=1`, `director=Qe3`.
+- `NSNR-ROT-003`: update uses `Q+ = exp((phi + delta_phi)^)Q0`.
+- `NSNR-ROT-004`: principal branch margin `sqrt(epsilon_double)` rejects ambiguous rotations near `pi`.
+- `NSNR-ROT-005`: `LeftJacobianSO3` and inverse-transpose are finite and derivative-consistent for small, medium, and near-branch-safe rotations.
+- `NSNR-ROT-006`: nonfinite rotation components fail with `invalid-accepted-state` or the Step-introduced finite-rotation diagnostic.
+
+Run:
+
+```powershell
+cmake --build .harness/build --config Debug
+ctest --test-dir .harness/build -C Debug -R "FiniteRotation" --output-on-failure
+```
+
+Expected: tests fail because the rotation module does not exist. Unexpected pass stops.
+
+## GREEN
+
+Implement the SO(3) helper functions with finite checks and principal-branch validation. Use existing FESA math types and keep MKL/vendor types out of public headers.
+
+## 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 "FiniteRotation" --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 using default commands.
+
+## 상태 기록
+
+Update only Step 2 status and summary/error/blocked payload. Executor owns timestamps, commits, retry, and advancement.
+
+## 금지사항
+
+- Do not normalize invalid rotation matrices to make tests pass. 이유: invalid nonlinear state must fail closed.
+- Do not add element residual or tangent code here. 이유: this Step owns only finite rotation state.
+- Do not expose backend/vendor types. 이유: public solver core must remain backend-neutral.