KOKO\Mimi
102 lines
3.4 KiB
Markdown
102 lines
3.4 KiB
Markdown
# 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.
|