FESADev/HANDOFF.md

# HHT implicit dynamics 인수인계

최초 작성: 2026-09-22. 이 문서는 중단·재개를 위한 작업 상태 기록이다. **기능 완료 보고서가 아니며, 미실행·진행 중·INCONCLUSIVE를 PASS로 해석하면 안 된다.** 후속 작업은 아래 실행 일지에 덧붙인다. Feature의 공식 acceptance/checklist 원본은 [PRD](docs/hht-implicit-dynamics/PRD.md)다.

## 1. 사용자 요청과 권한

사용자는 HHT implicit 동적 해석의 requirement/research, formulation, numerical review 이후 **consistent mass**를 선택했고, 이어서 **I/O definition, implementation, physics evaluation gate를 모두 수행**하도록 요청했다. 이후 **Git에 커밋하면서 진행**, 이번에는 **HANDOFF.md 작성 후에도 계속 진행하며 추가 결과를 기록**하도록 요청했다.

- 승인 범위: 기존 격리 worktree에서 구현, 테스트, 지정 reference 해석·비교, 독립 수치·물리 검토, 로컬 커밋.
- 외부 Abaqus 실행, reference 입력/CSV 수정, push, release는 승인되지 않았다.
- reference는 외부 수치 비교 대상이다. Abaqus 내부 알고리즘 동등성을 주장하지 않는다.
- 원래 MITC4 논문 재현/eigen 실험과 현재 HHT 기능은 구별한다. 현재 작업에서 기존 static/eigen 질량 계약을 변경하지 않는다.

## 2. 저장소와 커밋

- 작업 worktree: `C:/Users/baram/orca/workspaces/FESADev/hht-implicit-dynamics`
- branch: `hht-implicit-dynamics`
- 원본 저장소: `C:/git/FESADev` — 해당 dev 작업 트리는 건드리지 않는다.
- 시작 commit: `23b37ca644563b51472654af3b22811f077f15f6`
- `1dbd8cc docs: define consistent-mass HHT dynamics contracts`: Feature 계약 15개 문서.
- `0820259 feat: map fixed-step HHT shell dynamics input`: 입력/semantic model 및 parser tests.
- 이 문서 작성 시점에서 **관성·적분·procedure·state·writer·대부분 테스트와 comparator는 아직 미커밋**이다. 파일은 공유 worktree에 존재한다. 다음 담당자는 reset/clean/전체 stage로 잃거나 생성 결과를 섞지 말 것.
- main만 stage/commit한다. Agent들은 source/doc/test 파일만 수정했다.

## 3. 우선 읽을 계약

[Feature 지침](docs/hht-implicit-dynamics/FEATURED_AGENTS.md), [PRD](docs/hht-implicit-dynamics/PRD.md), [ADR](docs/hht-implicit-dynamics/ADR.md), [정식화](docs/hht-implicit-dynamics/formulation.md), [관성 정식화](docs/hht-implicit-dynamics/formulation-inertia.md), [수치 기준](docs/hht-implicit-dynamics/numerical-controls.md), [검증 C01–C12](docs/hht-implicit-dynamics/verification-cases.md), [I/O 계약](docs/hht-implicit-dynamics/io-contract.md), [reference 계약](docs/hht-implicit-dynamics/reference-model.md).

공통 [TOLERANCE](docs/TOLERANCE.md), [ARCHITECTURE](docs/ARCHITECTURE.md), [CODINGSTYLE](docs/CODINGSTYLE.md), 프로젝트 AGENTS.md를 따른다. 프로젝트 PRD/ADR/AGENTS는 일반 Feature 작업에서 읽기 전용이다. Feature 문서는 한국어로 작성한다.

### 고정된 수학·지원 범위

- Original negative-alpha HHT: `alpha=-.05`, `beta=.275625`, `gamma=.55`.
- physical endpoint acceleration `a`와 auxiliary acceleration `A`를 분리한다.
- `A0=a0`, `A_(n+1)=(1+alpha)a_(n+1)-alpha*a_n`.
- `q_p=q_n+h*v_n+h²*(.5-beta)*A_n`, `v_p=v_n+h*(1-gamma)*A_n`.
- `A=(q-q_p)/(beta*h²)`, `v=v_p+gamma*(q-q_p)/(beta*h)`, `a=(A+alpha*a_n)/(1+alpha)`.
- Endpoint residual: `I(q,v,a)+f_int(q)-F(t)`.
- Tangent: `Kint+DqI+gamma/(beta*h)*DvI+M/((1+alpha)*beta*h²)`.
- Current configuration consistent kinetic mass. 임의 drilling 질량, epsilon, mass-null cutoff, pseudoinverse-only initialization 금지.
- 초기 a는 positive physical range 식을 푼 뒤 differentiated drilling constraint로 null 성분을 결정한다.
- 단일 NLGEOM shell `*DYNAMIC,DIRECT`, 균일 고정 dt, zero 초기 q/v, homogeneous fixed BC, constant translational CLOAD만 공개 지원한다.
- Newton100/no cutback. Residual와 correction/rate 각각1e-10, linear backward1e-12. 모든 scale은 계약대로 dimensionally consistent, finite-first, zero-scale exact branch.
- **HHT-ADR-010**: Newton 시작 좌표를 `q_n`으로 명시 변경했다. Constant-A 외삽은 지정 큰 dt에서 최초 geometry를 무효화했다. HHT predictor/rate/tangent와 dt/tolerance는 그대로다. 수렴 후 또는 trial 실패 시 retry/clamp는 없다. 독립 reviewer는 이 변경이 physics/scheme 변경이 아닌 시작값 선택임을 확인했고, N2 문구도 갱신했다.

## 4. 구현 현황과 파일 소유권

### 입력/semantic — 커밋됨

`include/fesa/model/{model_types,domain}.h`, `src/fesa/model/domain.cpp`, `src/fesa/io/abaqus/domain_mapping_context.cpp`, `tests/unit/io/abaqus/hht_dynamic_domain_test.cpp`.

DynamicStepDefinition, step/domain accessor, rho 연결, schedule/INC 검증, fail-closed unsupported controls, 원본 reference 무수정 mapping을 구현했다. 원본의 `0.1,10.,` 끝 빈 field도 허용한다. 추가 nonempty field는 거부한다. 기존 static/frequency 입력 의미는 유지한다.

### 적분과 procedure — main

- `include/fesa/analysis/hht_time_integration.h`
- `src/fesa/analysis/hht_time_integration.cpp`
- `include/fesa/analysis/hht_dynamic_procedure.h`
- `src/fesa/analysis/hht_dynamic_procedure.cpp`
- `src/fesa/analysis/hht_dynamic_internal.h`
- `src/fesa/analysis/hht_dynamic_assembly.cpp`
- `include/fesa/analysis/prepared_analysis.h`, `src/fesa/analysis/prepared_analysis.cpp`
- `src/fesa/app/fesa_application.cpp`

별도 dynamic lifecycle로 parse→initial a→full Newton→전체 accepted history→atomic HDF5를 연결했다. 기존 static lifecycle에 동적 분기를 누적하지 않았다. Deterministic local parallel evaluation 뒤 stable source reduction을 한다. Physical reaction은 full endpoint residual constrained selector, moment balance는 `Jl^-T` 공간 moment로 검증한다.

### 관성 및 대수 제약 — hht_inertia_completion

- `include/fesa/elements/nonlinear_mitc4_inertia.h`
- `src/fesa/elements/nonlinear_mitc4_inertia.cpp`
- `src/fesa/analysis/hht_dynamic_algebra.cpp`
- `tests/unit/elements/nonlinear_mitc4_inertia_test.cpp`
- `tests/unit/analysis/hht_dynamic_algebra_test.cpp`
- `tests/unit/analysis/hht_temporal_verification_test.cpp`
- `tests/unit/analysis/hht_energy_verification_test.cpp`

Exact director D1/D2/D3, I/M/c/DqI/DvI, T/P/L/rates, analytic moving null, scaled positive complement, local conditioning, global SPD factorization, W-scaled regularity, P/Z Gram, 초기 hidden constraints를 구현했다. 독립 검토에서 찾은 inverse cofactor 이중 부호와 `c=I-Ma` cancellation은 수정했다. 물리 20차원 local mass/rcond 및 partial-BC actual-free checks가 있다.

### 기존 nonlinear shell 확장 — main

`include/fesa/elements/nonlinear_mitc4_shell.h`, `src/fesa/elements/nonlinear_mitc4_shell.cpp`, `tests/unit/elements/nonlinear_mitc4_shell_tangent_test.cpp`.

- physical/drilling force, drill energy/tangent/metric 분리.
- exact directional third energy variation으로 `D²f[v,v]`.
- 작은각 ExpSkew D3 cancellation을 stable series의 추가 directional derivative로 수정.
- **영변형 산술 수정**: decimal 좌표에서 초기 drill force가 약1.7e-9 생기고 normalized residual1이 되는 반례를 확인했다. Covariant increment에서 Green strain과 `F=I+delta_g⊗Gdual`을 직접 계산한다. Clamp 없이 수학적으로 같은 식이며 초기 exact-zero 회귀가 통과했다.
- **exact hidden2 scale**: 처음의 `sum_e |D²f_e[v,v]|`는 N3의 `|ψqq|[|v|,|v|]`와 달랐다. 독립 reviewer가 `ψ_i=σ_i Σ_e kd_e γ_ei`, `σ=1/||Jl^-1 d||`를 유도했다. 기존 second-order Jet로 scalar ψ Hessian을 구하고 **global (j,k)별 합산 후 abs contraction**하여 exact scale을 조립한다. 현재 공개 rotational F=0 조건의 식이다.
- 위 scalarψ/gradient/Hessian은 finite+warped fixture에서 nᵀf, n′ᵀf+nᵀK, Hessian FD와 대조해 통과했다.

### 상태/HDF5/log/comparator — hht_output_completion

- `include/fesa/analysis/dynamic_analysis_state.h`, `src/fesa/analysis/dynamic_analysis_state.cpp`
- `include/fesa/results/dynamic_results_writer.h`
- `include/fesa/io/hdf5/dynamic_hdf5_results_writer.h`, `src/fesa/io/hdf5/dynamic_hdf5_results_writer.cpp`
- `include/fesa/analysis/newton_iteration_log.h`, `src/fesa/analysis/newton_iteration_log.cpp`
- state/writer/log unit tests
- `scripts/verification/compare_hht_dynamic.py`, `tests/test_compare_hht_dynamic.py`

State는 complete validated frame만 commit하고 실패 candidate는 기존 history를 보존한다. q/v/a/A 분리, frame0, zero corrections, triad/director/chart, source identity, residual/reaction 등을 검증한다. Writer는 full schema·dtype·attrs·values readback 뒤 atomic replace한다. Density/BC mask, physical spatial reaction, HDF5 diagnostic source_file/source_line 이름을 명시했다. 기존 static diagnostic file/line은 유지한다. Log는 별도 hht-log-v1; accepted frame마다 flush한다.

Comparator는 원본 101×9행, full HDF5 101×729×6 U/UR identity·finite 검사 후 projection, 202 families, 모든 scalar/error/branch, blocking U와 warning UR를 JSON으로 쓴다. Precheck 오류는 UR도 blocking이다.

## 5. 검증 결과 — 최초 작성 시점

### 이미 확보한 제한 evidence

- MSVC x64 **Debug** fesa_solver/fesa_cli/unit target build 통과(전체 configured Harness는 아직 미실행).
- `.harness/build/hht-numerical/focused-io.log`: 29 tests PASS. State/writer/log, input, rotation 등을 포함한다. 전체 기능 suite를 뜻하지 않는다.
- 관성8 + rotation4 + algebra8 + C07 4개는 최신 최적화 focused binary에서 PASS.
- C01/C02/C03/C04b scalar temporal verification: prescribed grids의 q/v/physical a 차수·오차와 N7 evidence 확보.
- C07 alpha0 energy maximum defect `1.14353e-13`; default alpha endpoint energy defect `-2.45134e-5`; rho(omega*h=1000)≈`.904763`, analytic limit `.904762`; physical inertial support reaction oracle PASS.
- 작은각 threshold 양쪽/2e-4/1e-3 internal third derivative 검사, finite/warped scalar ψ Hessian 검사 PASS.
- `uv run --with h5py --with pytest python -B -m pytest -q tests/test_compare_hht_dynamic.py`: **41 passed**, main도 재실행 확인.

### C04a qualification — 지우거나 PASS로 바꾸지 말 것

C04a 시간수렴은 통과한다. Finest binary64 full2×2 대 scalar reduction의 acceleration 차이는 약 `3.079e-10`으로 계약1e-10보다 크지만 N7 산술/solve resolution 약 `6.296e-10`보다 작다. 해당 비교는 별도 `GTEST_SKIP`으로 **INCONCLUSIVE**를 남긴다. Coarse binary grids는 통과했고 decimal80 독립 수식 계산의 finest 차이는 `1.69e-73`이다.

`.harness/build/hht-numerical/c04a-decimal-reduction.json`은 고정밀 수학 identity 근거다. FESA binary64 finest 통과를 대체하지 않는다. Numerical reviewer가 이 구분을 N7에 맞는 qualification으로 확인했다.

### 아직 완료되지 않은 검증

- 최신 Debug focused 실행이 진행 중이다. 종료코드·최종 summary 확인 필요.
- Original reference는 **16/100 increments accepted**까지만 최초 작성 시 확인했다. 최종 HDF5/전체 비교는 아직 없다.
- C08a actual shell manufactured rigid orbit의 **시간 적분 검증은 미구현**. Pointwise independent volume oracle test는 작성되었으나 아직 빌드/실행 전이다.
- C08b free deformable 4-element plate의 5-grid, q/v/a self-convergence, energy/P/L, N7 test 파일은 작성되었으나 **아직 CMake 등록/빌드/실행 전**이다.
- C09–C11 일부 단위 evidence는 있으나 전체 production empty-channel/rigid-translation/failure100/determinism3회/회전된 전체모델 등 coverage를 acceptance 원문과 대조해야 한다.
- configured 전체 Debug build/CTest, 기존 static/eigen/reference regression, final physics evaluation은 미완료.

`focused-optimized.log`에는 과거 LargeDirectStep fixture의 부적절한 displacement<.1 예상 때문에 failure가 있다. 실제 첫 increment는 수렴했고 약-.3235였다. 해당 검사는 하중 방향·실제 N2 잔차 및 초기 가속도 크기로 수정했다. **수정 후 최신 Debug 결과를 확인해야 하며 이전 실패 로그를 통과로 승계하면 안 된다.** 같은 fixture의 두 번째 큰 dt increment가 chart 밖으로 나가는 것은 별도 negative evidence이며 현재 테스트는 시작값 회귀를 위해 최초 increment만 다룬다.

## 6. 현재 실행 중인 작업

세션 ID는 현 tool 세션에서만 유효하다. 새 세션에서 ID가 없으면 process/log/file 상태를 확인한다. 원본 input/CSV는 수정하지 않는다.

| 작업 | 상태/위치 |
|---|---|
| Original reference, optimized + MKL/OMP1 | `exec session_id=70291`; `.harness/build/hht-numerical/reference-run-optimized.log`; live `reference/shellNL-dyn-meshfine/shellNL-dyn-meshfine_log.txt` |
| 최신 Debug focused suite | `exec session_id=81971`; `.harness/build/hht-numerical/focused-debug-complete.log` |
| Comparator pytest | 종료0, 41 passed; session88341 종료 확인 완료 |
| C08 작성 owner | `/root/hht_output_completion`; `tests/unit/analysis/hht_shell_physics_test.cpp` 준비, C08a temporal pending |
| Physics reviewer | `/root/hht_physics_evaluation`; 독립 `docs/hht-implicit-dynamics/physics-evaluation.md` 초안 및 실제 결과 기다리는 중 |
| Numerical reviewer | `/root/hht_formulation_review`; `implementation-numerical-review.md` 작성. NR005/006 closed, ADR010/N2 시작값 문서 갱신 전달 필요 |
| Inertia/algebra/temporal owner | `/root/hht_inertia_completion`; 현재 담당 파일 완료/idle, 추가 수정 시 재사용 |

main이 빌드를 직렬 조정한다. **빌드 중 public header를 변경하지 말 것.** 실제로 null_second 필드 제거와 optimized compile이 겹쳐 ABI 혼합/SEH가 발생했다. 해당 header touch 후 모든 의존 object를 재빌드하여 해소했고 kernel/rotation 재검증이 통과했다. 새로운 compile failure가 아니라 stale mixed ABI였으며 실패 로그는 보존한다.

## 7. 실행 환경과 명령

로컬 helper `.harness/run-msvc.ps1`이 VsDevCmd x64 환경과 dependency CMake dirs를 설정한다. 이 helper와 build 디렉터리는 개인 exclude이며 commit하지 않는다.

- VS: `C:/Program Files/Microsoft Visual Studio/18/Community`
- GoogleTest: `C:/git/googletest`
- MKL2026.1, TBB2023.1, HDF5 2.1.1
- 기본 검증: `.harness/build-ninja-msvc-debug`, preset `windows-msvc-ninja-debug`
- reference/긴 physics 실험용 추가 최적화 빌드: `.harness/build-hht-relwithdebinfo`
- `.harness/config.json`은 Debug preset과 binaryDir로 설정되어 있다.

```powershell
# 반드시 위 worktree에서 실행
& ./.harness/run-msvc.ps1 cmake --build --preset windows-msvc-ninja-debug --target fesa_unit_tests fesa_cli --parallel 8

# 완료 시 구성된 전체 Debug 검증을 한 번 실행
& ./.harness/run-msvc.ps1 python scripts/execute.py

# 별도 optimized build — Debug 검증을 대체하지 않는다
& ./.harness/run-msvc.ps1 @('cmake','--preset','windows-msvc-ninja-debug','-B','.harness/build-hht-relwithdebinfo','-DCMAKE_BUILD_TYPE=RelWithDebInfo')
& ./.harness/run-msvc.ps1 cmake --build .harness/build-hht-relwithdebinfo --target fesa_cli fesa_unit_tests --parallel 8

# 작은 반복 PARDISO solve의 oversubscription 방지, 비교 시 설정 기록
$env:MKL_NUM_THREADS='1'
$env:OMP_NUM_THREADS='1'
& ./.harness/run-msvc.ps1 ./.harness/build-hht-relwithdebinfo/src/fesa/fesa.exe reference/shellNL-dyn-meshfine/shellNL-dyn-meshfine.inp

# 최종 HDF5가 생성된 다음만 비교
uv run --with h5py python -B scripts/verification/compare_hht_dynamic.py --report .harness/build/hht-numerical/reference-comparison.json

# comparator 자체 검증
uv run --with h5py --with pytest python -B -m pytest -q tests/test_compare_hht_dynamic.py
```

PowerShell helper의 `-B`는 named parameter로 잘못 bind될 수 있어 위 array splat을 사용한다. `clang-format`은 `C:/Program Files/LLVM/bin/clang-format.exe`다. Python은 Korean Git output을 읽을 때 UTF-8 encoding을 명시한다. 환경 전체/자격증명을 출력하지 않는다.

## 8. 지정 reference 및 비교 정책

- 입력: `reference/shellNL-dyn-meshfine/shellNL-dyn-meshfine.inp`
- 비교 CSV: `reference/shellNL-dyn-meshfine/shellNL-dyn-meshfine displacements.csv`
- INP SHA256: `b8922243ca8ddfe20b1dd39f3123207f789a1a75f6b10dbb6b0bc0b5a40dfff5`
- CSV SHA256: `422ecf17609e14fd119d60a3d5af7a0d1bc4a95e0f556608a7d791e2718c56c5`
- 729 nodes/676 S4, 10×10 flat plate, t=.5, E=2.1e11, nu=.3, rho2700.
- 104 boundary nodes all6 fixed; 625 free nodes, 3750 free DOFs; analytic mass positive3125/null625.
- Center node2, F=(-100000,-100000,-100000), constant STEP; h=.1,T=10,N=100,frames101.
- CSV: 101frames×9nodes=909rows; nodes2,21,22,69,70,165,309,442,586; U/UR6.
- 202 frame×family metrics. U blocking, UR warning; missing/extra/duplicate/nonfinite/time/identity 오류는 모두 blocking.
- `S=max(abs(reference))`, near-zero `.01S`, 일반 relative5%, family RMS1%, S0 exactzero. 공통 policy를 변경하지 않는다.
- CSV decimal schedule과 HDF5 double(n)*double(.1)을 각각 검증하고 increment로 대응한다. 최근접/보간은 금지한다.
- `h/T1≈7.4567`로 시간 해상도가 거칠다. Reference 일치만으로 finite-rotation/time accuracy/velocity/acceleration/energy를 검증한 것은 아니다.

## 9. 남은 작업의 권장 순서

1. 실행 중인 Debug focused의 종료·skip/failure 상세를 확인하고 필요한 수정만 수행한다. 검증된 I/O/kernel/procedure를 검토 가능한 단위로 commit한다.
2. C08 파일을 CMake에 등록하고 먼저 compile과 pointwise oracle, 이후 5-grid test를 실행한다. Optimized 실험에 더해 Debug에서 필요한 검증을 수행한다.
3. C08a의 time-dependent generalized F(t)는 trial null과 직교하지 않으므로 공개 zero-moment용 hidden 검사를 그대로 사용할 수 없다. Test-only에서 `ψ=nᵀ(f-F(t))`, `ψt=-nᵀFdot`, `ψqt=-n′ᵀFdot`, `ψtt=-nᵀFddot`와 full hidden derivatives를 계산한다. 외력은 독립 volume oracle에서 생성하며 production I를 다시 호출해 정답을 만들지 않는다. 현 owner에게 이 방침을 전달했다.
4. Original100increments 종료 후 HDF5를 comparator에 넣고 raw precheck/metrics 전량을 저장한다. 불일치를 분석하며 reference/tolerance를 조정하지 않는다.
5. Physics reviewer에 실제 C08/HDF5/comparison을 전달한다. Missing coverage와 물리적 타당성을 구별해 보고한다.
6. C09–C11, determinism3회, fail lifecycle, 기존 static/eigen 영향 검증을 보충하고 구성된 전체 Debug Harness/CTest와 필수 reference 비교를 수행한다.
7. Feature PRD·implementation report·numerical/physics reports를 실제 결과로 갱신한다. 이전의 전체 NOT RUN 기록은 이력과 현재 상태를 구별한다. C04a qualification은 유지한다.
8. 최종 diff/format/links/reference hashes를 확인하고 작업 파일만 commit한다. 생성 HDF5/log/build/개인 helper는 commit하지 않으며 push하지 않는다.

## 10. 追加作業記録

この節に時刻、変更、実行コマンド/結果、commit、残件を追記する。途中状態を最終PASSで上書きしない。

- 2026-09-22 初回記録: 本文のsnapshot作成。Reference16/100受理、最新Debug focused実行中。Comparator41testsのmain再実行PASSを確認。今後も作業を継続する。

- 2026-09-22 후속 확인: 독립 physics reviewer가 `physics-evaluation.md` 초안을 작성했다. 최신 Debug focused는 68 tests 중67 PASS/1 C04a INCONCLUSIVE SKIP으로 종료했다. Main은 다음 명령에서 종료코드와 summary를 직접 확인한다. C08 및 최종 reference 검증은 계속 PENDING이다.

- 2026-09-22 후속 작업: main이 Debug focused session81971 종료코드0을 직접 확인했다. 68 tests/67 PASS/1 INCONCLUSIVE SKIP, 총117.526s. Comparator41tests도 main 확인 완료. 구현 묶음을 로컬 커밋한 뒤 C08 파일을 등록한다. 신규 private test는 아직 이 Debug 실행에 포함되지 않았다.

- 2026-09-22 구현 커밋: `f0dc42a`에 HHT core/state/writer/log/comparator와 검증된 테스트를 커밋했다. 이후 `hht_shell_physics_test.cpp`를 tests/CMakeLists.txt에 등록했다. C08 build/run 결과는 다음 기록에 추가한다.

- 2026-09-22T21:41:48: C08 첫 Debug snapshot build PASS. 이후 owner가 C08a temporal fixture를 추가했고 optimized compile에서 GridEvidence.algorithmic_acceleration_gap 누락으로 실패했다. 테스트 파일 owner가 필드 위치 및 q_n 시작값을 수정 중이다. Production reference는75/100 accepted까지 확인했으며 최종 파일은 아직 기다린다.