# HHT Implicit Dynamics PRD

- Feature ID: `hht-implicit-dynamics`
- 기준: `dev` commit `23b37ca644563b51472654af3b22811f077f15f6`
- 문서 상태: `implementation-present; C08-failed; recovery-candidate-not-adopted`, 2026-09-27
- 기준 문서: [프로젝트 지침](../../AGENTS.md), [프로젝트 PRD](../PRD.md), [공통 ADR](../ADR.md#adr-028).

## 사용자 요청과 범위

사용자는 HHT implicit 적분법을 사용한 dynamic 해석 구현을 준비하기 위해 requirement/research, formulation, numerical research를 차례로 요청했고, 검증 모델로 `reference/shellNL-dyn-meshfine`을 지정했다. 현재 산출물은 요구사항·근거·정식화·독립 수치 검토와 검증 계약이다. 사용자의 후속 I/O definition·implementation·physics evaluation 전체 진행 요청에 따라 [I/O 계약](io-contract.md)과 [구현 계획](README.md#재사용-handoff)을 작성하고 실제 solver 구현·검증을 진행한다.

[시간적분 정식화](formulation.md)와 [shell 관성 상세](formulation-inertia.md)의 후속으로 [독립 수치 검토](numerical-review.md#numerical-review), [수치 기준](numerical-controls.md), [검증 사례](verification-cases.md), [추가 연구](research.md#numerical-research)를 작성한다. 사용자가 **consistent kinetic mass**를 선택했으며 이번 HHT 구현 범위는 일관질량이다. 후속 전체 gate 진행 요청에 따른 구현 대상·공개 subset·출력 schema는 [HHT-ADR-009](ADR.md)에 기록한다.

최소 구현 목표 후보는 기존 FESA-MITC4 shell의 선형 탄성 재료·기하비선형 동적 해석이다. 단일 step의 `*Dynamic,direct`, 초기 정지 상태, 고정 외곽 경계와 집중하중에 필요한 지원을 우선 정의한다. 질량·회전 관성·HHT 생략값·공식 동적 결과 범위는 근거를 확인하여 후속 정식화와 연결한다. 임의 amplitude, 시간변화 경계, 물리적 damping, contact, 소성, explicit, 다중 step/restart 또는 다른 요소의 dynamics는 이번 요청에서 지원을 약속하지 않는다.

## 지정 reference와 acceptance intent

원본: [INP](../../reference/shellNL-dyn-meshfine/shellNL-dyn-meshfine.inp), [변위 CSV](<../../reference/shellNL-dyn-meshfine/shellNL-dyn-meshfine displacements.csv>). 상세 inventory와 요구사항 ID는 [requirements](requirements.md)가 소유한다.

- 평면 shell 729 nodes / 676 S4 elements, 두께 `0.5`, `E=2.1e11`, `nu=0.3`, `rho=2700`.
- `NLGEOM=YES`, `DIRECT`, 시간증분 `0.1`, 종료시간 `10`, 중심 node `2`에 global 1–3방향 각각 `-100000` 집중하중.
- CSV는 101 frames × 9 nodes = 909 rows, U/UR 6성분을 제공한다. 초기 frame을 포함한 모든 시간 이력이 비교 대상이다.
- source instance/node와 increment/time을 결정적으로 대응시킨다. HDF5 전체 node 결과에서 승인된 reference subset으로 projection한 뒤 누락·추가·중복·nonfinite를 검사한다. 최근접 시간 선택, 시간 보간 또는 평균으로 대응 오류를 숨기지 않는다.
- [공통 TOLERANCE](../TOLERANCE.md)의 frame별 U blocking / UR warning-only family를 사용한다. [Reference 비교 계약](reference-model.md)은 101 frames × 2 quantities의 202 families와 각 27 scalars, source/time mapping을 정의한다. Eigen 전용 예외는 적용하지 않는다. 실제 HDF5 field binding은 후속 I/O 계약이다.
- V/A, 동적 반력, 에너지 reference는 없다. 독립 oscillator·시간 수렴·관성 평형·회전 및 에너지 검증이 필요하다. 원본 모델의 작은 변위만으로 유한회전 동역학을 검증했다고 주장하지 않는다.

## 현행 dev와의 차이

다음은 소스 정적 조사 결과이며, 현재 dynamic 실행 결과가 아니다.

| 경계 | 현재 코드 evidence | 후속 작업에서 정의할 내용 |
| --- | --- | --- |
| 입력·semantic model | [domain_mapping_context.cpp](../../src/fesa/io/abaqus/domain_mapping_context.cpp)의 `ParseStepBlock` 분기는 STATIC/FREQUENCY를 처리한다. `FinalizeDensities`는 FREQUENCY 외 DENSITY를 거부한다. [Domain](../../include/fesa/model/domain.h)의 step 정의도 동적 절차가 없다. | DYNAMIC/DIRECT 및 density의 승인 subset, 실제 시간·기본값·초기조건·진단 |
| 절차 선택 | [prepared_analysis](../../src/fesa/analysis/prepared_analysis.cpp)는 선형 정적·비선형 정적·고유치만 선택한다. | 정적 lifecycle에 누적하지 않는 별도 dynamic procedure와 결과 경계 |
| 상태 | [NonlinearAnalysisState](../../include/fesa/analysis/nonlinear_analysis_state.h)는 load factor, q, triad/director, 내외력과 정적 recovery를 저장한다. v/a 및 실제 시간 이력은 없다. | trial/committed q/v/a·시간·이력의 소유권과 일괄 commit/실패 보존 |
| 내력·접선 | [NonlinearMitc4Shell](../../include/fesa/elements/nonlinear_mitc4_shell.h)은 total rotation-vector trial의 내력·접선·recovery 평가를 제공한다. | 이 좌표계에 맞는 관성력·HHT residual·유효 접선과 일관된 회전 운동학 |
| 질량 | [Mitc4Mass](../../include/fesa/elements/mitc4_shell.h)는 consistent/lumped global24를 제공한다. [현행 frequency](../../src/fesa/analysis/linear_frequency_procedure.cpp)는 lumped nodal mass를 사용한다. | 동적 질량 선택·구성 의존성·회전 관성과 mass-null 자유도 처리; 정적/eigen 계약의 무단 변경 금지 |
| 선형계 backend | [비선형 PARDISO adapter](../../src/fesa/solvers/linear/mkl_pardiso_tangent_solver.cpp)는 이미 비대칭 full CSR 접선을 처리한다. | 동적 관성 접선의 비대칭 성분 보존과 기존 경계 재사용 검토 |
| 에너지 | [비선형 요소](../../src/fesa/elements/nonlinear_mitc4_shell.cpp)는 physical+drilling potential의 내력·Hessian을 계산하지만 반환 에너지는 physical strain energy다. | 운동에너지·수치 drilling 에너지·외력 일을 구분하는 회복 계약 |
| 공식 결과 | 정적/eigen 전용 state/writer가 존재한다. | HDF5의 step/time/frame 및 q/v/a·반력·에너지 공개 범위, readback·comparison |

Density 허용과 HHT update 식 추가만으로 기능이 완성되는 것은 아니다. Semantic model부터 동적 상태, 방정식, recovery, 공식 결과 및 검증까지 연결해야 한다.

## 결정과 후속 인계

결정 기록은 [ADR](ADR.md), 결정 항목의 원본은 [requirements의 HHT-OPEN-001–006](requirements.md#범위-경계와-미결정-사항)이다. 질량 종류는 사용자 결정으로 확정했다. 수식과 수치 검증 계약을 연결하되 공개 parameter·결과 범위 및 I/O binding은 후속으로 확정한다. 문서 검토만으로 구현이 검증되었다고 표시하지 않는다.

이번 [Research](research.md#research)에서 확인한 공개 입력 의미는 무접촉 기본 HHT-TF 계수 `alpha=-0.05`, `beta=0.275625`, `gamma=0.55`, amplitude 생략 시 STEP 하중, DIRECT 고정 증분 및 기본 초기 가속도 계산이다. 최초 HHT force history와 초기 frame의 결합, FESA 질량·유한회전 관성 및 공개 결과 범위는 여전히 후속 계약이 필요하다. 원 HHT의 표준 결합 계수 범위와 vendor가 허용하는 전체 parameter 범위를 혼동하지 않는다.

Reference의 `max|U3|/thickness≈9.84e-5`, 기존 동일 mesh eigen reference에 대한 `dt/T1=7.4567`은 작은 응답과 성긴 시간간격을 보여준다. 이 CSV와의 일치만으로 큰 회전 관성, V/A 또는 시간 정확도를 검증할 수 없다. 단위계는 입력의 일관된 단위를 따르며 SI로 단정하지 않는다.

## Formulation 결과

[정식화](formulation.md)의 추천 후보는 유한회전 kinetic energy의 정확한 관성력과 물리적 가속도 `a` / 적분용 보조 가속도 `A`의 분리다. `A_(n+1)=(1+alpha)a_(n+1)-alpha a_n`를 Newmark update에 사용하고 endpoint 물리 평형을 푼다. 일정 질량에서는 기존 HHT 식으로 환원한다. 비선형 내력은 현행 dev의 objective drilling을 포함한 에너지 미분을 보존하며 이전 논문 실험의 접선·drilling 변경을 도입하지 않는다.

[독립 수식 검토](numerical-review.md#numerical-review)와 [재현 가능한 검산](numerical-review.md#numerical-review-probes)은 일정 질량 HHT 식에 `M(q)`만 대입하면 일반적으로 1차 오차가 남음을 확인했다. 추천 후보는 smooth variable-mass 제조해와 영질량 방향이 회전하는 제한된 모델에서 U/V/물리적 a의 2차 수렴을 보였다. 메인도 공개된 재현 코드를 실행하여 표의 결과를 확인했다. 이는 실제 MITC4 shell의 동적 해석 또는 보편적인 singular-DAE 증명의 대체물이 아니다.

| 기존 open 항목 | 이번 정식화에서 구체화한 후보 | 남은 결정/검증 |
| --- | --- | --- |
| HHT-OPEN-001 | 음수 alpha 관례, 결합 beta/gamma, 물리적 a와 보조 A 분리 | 추천 HHT 확장 채택 및 공개 parameter subset |
| HHT-OPEN-002 | frame 0을 `0+`로 정의, 전값 force와 동적·대수 초기 평형으로 a0 계산, A0=a0; 수치 기준 N2–N4 정의 | 초기화 계약 채택과 I/O 진단 binding, 구현 후 검증 |
| HHT-OPEN-003 | **사용자 선택: consistent kinetic mass**; lumped는 비교 연구로 보존하고 이번 HHT 지원에서 제외 | 질량 종류 결정 완료; 임의 drilling inertia 없이 회전관성·영공간의 실제 구현 검증 필요 |
| HHT-OPEN-004 | 기존 total rotation-vector chart에서 exact 관성·convective 항·비대칭 접선, moving-null 조건; N4–N7 및 C05–C08 정의 | 구현 후 실제 shell의 regularity·시간 수렴·회전 검증 |
| HHT-OPEN-005 | 물리적 a/각가속도와 A, endpoint 반력, T/Uphys/Udrill/W의 수학적 의미 구별 | 공식 공개 quantity·HDF5 schema 및 mapping의 I/O 결정 |
| HHT-OPEN-006 | 고정 100 increments, full Newton, 실패 trial 폐기, 동일 state의 전체 이력 commit; N2의 100 corrections/수렴 기준 정의 | I/O 실패 lifecycle과 reference 밖 입력 범위, 구현 후 실패 보존 검증 |

현재 후보에 대한 독립 검토와 후속 구현 acceptance를 구별한다. 실제 shell 검증의 미실행은 현재 수식에서 오류를 발견했다는 뜻이 아니며, 구현 이후 반드시 확보해야 할 evidence다. 물리 선택과 수치·입출력 계약은 구현 착수 전 확정할 항목이다.

## Numerical Review 결과

[내부 수치 기준 N1–N7](numerical-controls.md)은 변위·회전의 scale를 분리하고, 관성·내력·외력의 상쇄 전 크기로 endpoint 잔차를 판정한다. Newton 잔차와 correction/rate 판정은 각각 `1e-10`, 선형 solve backward error는 `1e-12`다. 해석적으로 정의한 질량 영공간과 양의 물리 질량을 구별하며, 국소 positive block·대수 regularity에는 scale된 `rcond_inf>=2^-32`를 요구한다. 이 값은 외부 reference tolerance의 변경이 아니다.

[검증 사례 C01–C12](verification-cases.md)는 oscillator·STEP 초기화·variable mass·moving null, 운동에너지 적분·관성 접선, 반력·에너지·실제 shell 유한회전, 실패 보존·결정론·전체 reference 이력을 포함한다. D3 회전 미분에는 독립 block-exponential oracle를 지정했다. 문서 gate 당시 신규 solver 사례는 모두 NOT RUN이었다. 현재 실행 결과는 아래 checklist와 [독립 수치 검토](implementation-numerical-review.md), [물리 평가](physics-evaluation.md)에 구분한다.

추가 full Cartesian moving-null 수식 probe는 전체 시점 최대 오차에서 q/v/물리적 a의 최종 refinement 차수 `1.99985/1.99992/1.99834`를 보였고 독립 reviewer가 재현했다. 이는 기하학적 normalization이나 각도 축약 없이 계산한 제한된 수식 evidence다. 전체 N1–N7 구현 검사와 실제 shell·reference 통과를 의미하지 않는다. 자세한 실행 범위는 [수식 검산](numerical-review.md#numerical-review-probes)에 기록한다.

## 현재 checklist

- [x] 사용자 지정 모델·출력과 현행 dev 기준 확인.
- [x] 격리 worktree 및 Feature 핵심 문서 작성.
- [x] Requirement 초안: 원자적 요구사항과 acceptance intent 작성.
- [x] Research 초안: 일차·공식 근거의 열람 범위, 입력 생략 의미, 검증 후보와 근거 공백 정리.
- [x] 문서 간 범위·비교 정책·로컬 링크 및 reference 원본 보존 정적 검토.
- [x] 사용자 질량 선택 반영: 이번 HHT 기본·구현 범위는 consistent kinetic mass.
- [x] 나머지 물리·공개 parameter·공식 결과 범위 확정: HHT-ADR-009와 I/O 계약.
- [x] Formulation 후보 작성: HHT·정확한 유한회전 관성·초기화·잔차·접선·회복.
- [x] 독립 수식 검토와 variable-mass / moving-null 제조해 검산; 메인 재현 확인.
- [x] 추가 수치 근거 조사와 full Cartesian moving-null 독립 검산·재현.
- [x] Numerical Review의 내부 기준·검증 사례·reference 수치 비교 계약 검토 완료.
- [x] I/O 계약과 실제 field/schema binding 정의·정식화 대조.
- [x] HDF5 구현과 readback 검증: state/writer focused Debug suite와 원본 101-frame 비교 실행 완료. 후속 발견된 굽힘 단면력 복구 오류의 수정 후 HDF5 재검증은 별도 항목이다.
- [x] 지정 reference U 101 families PASS, UR row/RMS 경고 200건 기록. Reference 성공은 C08/physics 통과가 아니다.
- [ ] C08a/C08b 시간수렴 실패 해결: [독립 검토](implementation-numerical-review.md), [물리 검토](physics-evaluation.md). 현 알고리즘과 tolerance를 유지한 실패 재현 완료.
- [ ] HHT-ADR-011에 따른 가속도 복구 후보 정식화·독립 검증 후 채택 여부 결정.
- [x] 굽힘 단면력의 두께 계수 수정: 최신 Debug 관련 14 tests PASS, 원본 HDF5 재생성·비교 및 `M=t³Cκ/12` 독립 대조 완료. 전체 회귀 상태는 아래 항목과 구분한다.
- [ ] C09–C11 잔여 coverage: rigid translation 전체 이력, Newton100/101·실패 보존, 3회 결정론·partition·전체 모델 covariance.
- [ ] Solver 구현·구성된 build/test·독립 물리 및 reference 검증. 최신 Debug build 및 C08 temporal2개 제외 CTest는475 PASS/1 C04a SKIP; C08 실패와 전체 gate 미완료는 유지한다.

문서 gate의 완료와 solver 기능의 완료를 구별한다. 현재 구현 단계에서는 내부 수치 검증, solver build/test 및 지정 reference 해석·비교를 실행한다. 통과 여부와 physics 평가는 실제 evidence로 갱신한다.