FESADev/docs/hht-implicit-dynamics/requirements.md

# HHT implicit dynamics 상세 요구사항

- Feature ID: `hht-implicit-dynamics`
- 상태: `draft-pending-decisions` — 최초 requirement/research gate 이후 사용자 질량 선택과 후속 검증 계약을 반영했다. 문서 존재는 solver 검증 통과가 아니다.
- 기준: [프로젝트 지침](../../AGENTS.md), [제품 PRD](../PRD.md), [공통 ADR](../ADR.md), [ARCHITECTURE](../ARCHITECTURE.md), [TOLERANCE](../TOLERANCE.md).
- 범위·현재 checklist와 결정 기록의 원본은 Feature `PRD.md`와 `ADR.md`다. 이 문서는 상세 요구사항과 검증 의도만 소유한다.

## 요청과 실제 검증 대상

HHT implicit dynamic analysis를 도입하기 위한 요구조건을 정의한다. 최초 작성은 requirement/research gate였으며, 이번 갱신은 사용자 일관질량 선택의 요구사항 반영에 한정한다. Solver 구현, reference 재생성 및 Abaqus 실행을 포함하지 않는다. 아래 요구사항은 향후 구현의 acceptance intent이고, 미결정 사항은 승인된 수식·입출력 계약처럼 취급하지 않는다.

직접 읽은 원본은 [INP](../../reference/shellNL-dyn-meshfine/shellNL-dyn-meshfine.inp)와 [변위 CSV](<../../reference/shellNL-dyn-meshfine/shellNL-dyn-meshfine displacements.csv>)다.

| 관찰 항목 | 원본 evidence |
| --- | --- |
| Mesh/section | 평면 shell, `S4` 676개, node 729개, 두께 `0.5`, section 입력의 두께 방향 점 수 `5` |
| Material | `E=2.1e11`, `nu=0.3`, `rho=2700` |
| Constraint/load | 외곽 `Set-2`의 DOF 1–6 고정, 중심 node `2`의 global DOF 1–3에 각각 `-100000` |
| Procedure | 단일 `Step-1`, `nlgeom=YES`, `inc=1000`, `*Dynamic,direct`, 데이터 `0.1,10.` |
| 생략된 입력 | 명시적 HHT parameter, amplitude, 초기조건, 물리적 damping 정의 없음 |
| Output 요청 | Field/history `PRESELECT`, `frequency=1`; restart `frequency=0` |
| CSV coverage | `PART-1-1`, nodes `2,21,22,69,70,165,309,442,586`, 101 frames: increment `0..100`, step time `0..10`, 간격 `0.1` |
| CSV quantities | `U1/U2/U3`, `UR1/UR2/UR3`; 총 909 rows, frame/instance/node 중복 없음, 비교 성분 nonfinite 없음 |

수치 입력만으로 SI 단위를 확정하지 않는다. 일관된 입력 단위계에서 변위는 길이, 회전은 rad, 시간은 입력 시간, 힘은 힘, 밀도는 질량/길이³ 차원을 갖는다. 속도·가속도를 다룰 때도 이 단위계와 회전 운동학을 일관되게 연결해야 한다. 원본 CSV에 step 이름 column이 없으므로 단일 INP step과의 연결 근거가 필요하다.

## 요구사항과 acceptance intent

`FEM-REQ-HHT-*`는 향후 구현에서 관찰할 동작이다. 검증 방법은 evidence 종류를 지정하며, 수식·algorithm·schema·내부 수치 한계는 해당 owner가 후속 계약으로 정의한다.

| ID | 관찰 가능한 요구사항 | 검증 의도 |
| --- | --- | --- |
| FEM-REQ-HHT-001 | 지정 INP의 단일 기하비선형 shell 동적 문제를 원본 수정 없이 처리할 수 있어야 한다. `NLGEOM=YES`를 선형 해석으로 치환하지 않는다. | 실제 입력의 end-to-end 실행과 비선형 효과를 구별하는 독립 사례 |
| FEM-REQ-HHT-002 | HHT 시간적분으로 승인된 관성·내력·외력의 동적 응답을 계산해야 한다. 정적 step을 시간 frame으로 반복한 결과로 대체하지 않는다. | 자유진동·강제진동 analytical 사례 및 시간간격 변화에 따른 응답 검증 |
| FEM-REQ-HHT-003 | 원본 `DIRECT` 시간 의미를 보존하여 시작 frame과 `0.1` 간격의 `10`까지 응답을 식별 가능하게 제공해야 한다. 승인되지 않은 adaptive 전환으로 실패를 숨기지 않는다. | 초기 frame 및 100개 완료 increment의 시간·순서·마지막 시각 확인, 실패 종료 검증 |
| FEM-REQ-HHT-004 | HHT parameter 생략 시 적용 의미와 허용 범위를 명시해야 한다. 생략값을 CSV 적합도로 추정하거나 비교 결과에 맞춰 변경하지 않는다. | 공개 근거와 FESA 결정 추적, 승인 범위의 경계·잘못된 parameter 진단 |
| FEM-REQ-HHT-005 | Amplitude 없는 집중하중의 시간 이력과 시작 시점 의미를 확정하여 초기화와 모든 increment에서 일관되게 적용해야 한다. | 첫 increment 및 load onset 독립 사례; 최종 값만 같은 다른 하중 이력을 구별 |
| FEM-REQ-HHT-006 | 초기 변위·회전, 속도 및 가속도의 물리적 의미와 초기 평형 조건을 명시해야 한다. 원본에 초기조건이 없다는 이유로 초기 가속도를 무조건 영으로 가정하지 않는다. | 초기 frame과 첫 step의 동역학적 일관성; mass-null 자유도를 포함한 초기화 검증 |
| FEM-REQ-HHT-007 | 사용자 선택에 따라 shell 속도 보간의 운동에너지를 적분하는 일관질량(`consistent kinetic mass`)을 사용하고, 밀도·두께에 따른 질량과 회전 관성의 물리적 의미를 보존해야 한다. 질량이 없는 자유도나 drilling 자유도 처리를 임의의 관성 추가로 은폐하지 않는다. | 총 질량·관성 및 관련 강체 운동 검증, 허용/불허 mass-null 사례 |
| FEM-REQ-HHT-008 | 고정된 자유도와 비선형 회전 상태를 시간에 따라 일관되게 유지해야 한다. 회전 좌표의 미분과 물리적 각속도·각가속도를 근거 없이 동일시하지 않는다. | 고정 경계의 운동학, 좌표 회전 및 유한회전 일관성 검증 |
| FEM-REQ-HHT-009 | 각 increment의 수렴·실패와 마지막 유효 상태를 구별해야 하며, 실패 trial이 성공 frame이나 committed 상태로 노출되지 않아야 한다. | 비수렴·계산 실패·출력 실패 주입 및 기존 최종 결과 보존 확인 |
| FEM-REQ-HHT-010 | HHT 알고리즘 평형 잔차, 물리적 동적 평형 evidence, 구속 반력의 정의·평가 시점을 구별해야 한다. 정적 `K*d-F`를 동적 반력으로 재사용하지 않는다. | 관성력이 있는 구속 사례 및 전체 힘·모멘트 평형 검증 |
| FEM-REQ-HHT-011 | 알고리즘 감쇠와 물리적 damping을 구별해야 한다. 명시되지 않은 물리적 damping을 reference fitting 목적으로 추가하지 않는다. | 승인 parameter별 진동/소산 거동과 외력 일·에너지 변화 검증 |
| FEM-REQ-HHT-012 | 공식 결과는 입력 경로의 lexical sibling `<stem>_results.h5`이며, 동적 응답의 source instance/node, component와 step/time/frame 의미를 식별 가능하게 제공해야 한다. | HDF5 결과의 identity·단위·좌표·시간 의미 및 deterministic readback 확인 |
| FEM-REQ-HHT-013 | 지정 CSV의 모든 101 frames 및 9개 node에서 변위·회전 이력을 비교해야 한다. 최종 frame, peak 또는 중심점 하나만의 일치를 전체 통과로 보고하지 않는다. | 원본 CSV와 공식 HDF5의 결정적 비교; 승인된 reference subset projection 이후 누락·추가·중복·nonfinite 사전 거부 |
| FEM-REQ-HHT-014 | `U1/U2/U3`는 blocking, `UR1/UR2/UR3`는 warning-only로 유지하며 공통 `TOLERANCE` 정책을 적용해야 한다. | Frame별 결과·warning·전체 verdict 보고, zero-scale 초기 frame 및 실패 분류 검증 |
| FEM-REQ-HHT-015 | 속도·가속도·반력·에너지·내부력의 correctness를 현재 변위 CSV만으로 검증되었다고 주장하지 않는다. | Quantity별 coverage gap과 analytical/invariant/독립 evidence의 대응 |
| FEM-REQ-HHT-016 | 승인하지 않은 절차·입력 조합은 관련 source와 이유를 식별할 수 있게 거부해야 한다. | 미지원 동적 입력·잘못된 시간/물성·실패 경로 검사; 구체적인 지원 syntax는 후속 I/O 계약 |
| FEM-REQ-HHT-017 | 기존 정적·eigen의 승인된 물리·입출력·acceptance를 보존하고 같은 입력의 결과 및 진단 순서를 재현해야 한다. | 변경 영향 범위 회귀, 반복 실행·실행 순서 변경 검사 |

공통 tolerance의 scale, near-zero, relative/RMS, zero-scale 처리를 그대로 사용한다. 서로 다른 frame의 응답을 하나의 family로 합쳐 오차를 희석하지 않는다. Family·mapping의 현재 정의는 [reference 계약](reference-model.md)을 참조하며 Numerical Review/I/O owner가 관리한다. `mitc4-eigen-first-implementation`의 eigen 전용 RMS 5% 예외는 이 기능에 적용하지 않는다. Warning-only는 회전의 물리적 일관성 검증 면제를 의미하지 않는다.

## 범위 경계와 미결정 사항

최소 목표는 원본 모델에 필요한 선형 탄성 shell의 기하비선형 implicit dynamics다. 원본의 Abaqus `S4` 이름을 처리하는 것은 FESA shell과 Abaqus 내부 정식화·적분·stabilization의 동등성 약속이 아니다. 현재 문서는 contact, 소성·손상, explicit dynamics, 다중 step/restart, 시간변화 구속, base excitation, 임의 amplitude, follower load, Rayleigh/modal damping, adaptive stepping 또는 다른 element의 동적 지원을 약속하지 않는다.

[Research](research.md)에서 공식 문서에 따른 원본 입력의 생략 의미를 확인했다. 이는 reference 입력의 해석 근거이며 FESA 구현 승인이나 신규 사용자 결정이 아니다. 아래에서는 확인된 공개 의미와 남은 FESA 계약 결정을 구분한다.

사용자는 이번 HHT 기본 질량으로 일관질량을 명시 선택했다([HHT-ADR-007](ADR.md)). 이번 HHT의 lumped mass 지원은 제외한다. 이 선택으로 다른 미결정 physics·지원 범위·공식 schema의 승인을 추정하지 않는다.

| Decision ID | 확정이 필요한 내용 | 결정 근거·owner |
| --- | --- | --- |
| HHT-OPEN-001 | 공개 의미 확인: contact 없는 기본 `TRANSIENT FIDELITY`의 `HHT-TF`, `alpha=-0.05`, `beta=0.275625`, `gamma=0.55`. FESA의 공개 parameter 지원 범위와 정식화 세부는 미확정 | 공개 근거는 Research 참조; Formulation 검토 후 메인 결정, 실제 물리·호환성 변경은 사용자 결정 |
| HHT-OPEN-002 | 공개 의미 확인: amplitude 생략은 `STEP` 하중으로 첫 increment부터 전값, 기본 `INITIAL`은 초기 가속도 계산. FESA 초기화와 `t0-/t0+` 및 첫 잔차 평가 세부는 미확정 | Research의 공개 의미를 바탕으로 Formulation/I/O가 일관성을 입증; 첫 잔차 세부의 research gap과 source 충돌은 메인에 전달 |
| HHT-OPEN-003 | 질량 종류는 사용자 선택으로 `consistent kinetic mass` 확정, 이번 HHT lumped 지원 제외. 회전 관성 및 mass-null/drilling 지원·검증 세부는 전문 계약과 연결 | [정식화](formulation.md), [관성 상세](formulation-inertia.md), [수치 기준](numerical-controls.md), [검증 사례](verification-cases.md) 및 후속 I/O 계약을 대조; 질량 선택 자체를 재승인 대상으로 두지 않음 |
| HHT-OPEN-004 | 기존 기하비선형 shell 운동학을 동역학으로 확장할 때 허용하는 회전·관성 범위 | Formulation이 필요한 물리 가정과 한계를 명시; 원본 `NLGEOM=YES`를 충족하지 못하면 범위 충돌 |
| HHT-OPEN-005 | 공식 HDF5의 속도·가속도·동적 반력·에너지 공개 범위 및 기존 소비자 호환성 | Requirements는 독립 검증 필요성만 고정; 메인이 공개 범위를 확정하고 I/O가 schema를 정의 |
| HHT-OPEN-006 | 공개 의미 확인: contact 없는 `DIRECT`는 고정 시간간격. FESA 실패 종료·increment 제한 lifecycle과 고정 간격 밖의 지원 범위는 미확정 | 원본 DIRECT 보존이 최소 조건; adaptive 확대는 별도 범위 결정, 세부 lifecycle은 Formulation/I/O |

다른 worktree의 eigen 질량 진단에서 특정 mass 모델이 더 가까웠다는 사실은 동적 질량 선택의 승인이나 이 모델의 통과 evidence가 아니다. HHT alpha·시간간격·질량을 원본 CSV에 맞추어 조정하는 작업은 요구사항에서 허용하지 않는다. 공개 문서로 생략 의미가 해결되면 이를 사용자에게 반복 질문할 필요 없이 근거와 결정에 기록하되, FESA의 실제 physics 범위 변경은 명시적으로 구분한다.

## 후속 검증 인계

Formulation 이후 독립 Numerical Review가 초기화, 비선형 시간적분, 관성/질량 영공간, 회전 및 잔차·반력 정의를 검토해야 한다. 검증 사례는 최소한 analytical oscillator, 무하중 또는 강체 운동에 적합한 invariant, 관성력이 있는 구속 평형, 시간간격 변화, 알고리즘 소산, 비수렴 상태 보존과 지정 reference의 전체 이력을 다룬다. 구체적인 모델·수식·내부 수치 한계는 이 문서에서 선택하지 않는다.

변위 reference와 독립 물리 evidence를 함께 확보해야 기능 완료를 판단할 수 있다. 최초 requirement gate의 원본/계약 대조 이후 [수치 기준](numerical-controls.md), [검증 사례](verification-cases.md), [reference 계약](reference-model.md)이 작성되었다. 이는 검증 기준의 정의이며 신규 solver 사례와 HDF5/reference comparison은 **NOT RUN**이다. 이번 요구사항 갱신은 문서 정적 검사만 수행하며 build/test를 실행하지 않는다.