# Hex8 구조해석 제품 요구사항

Feature ID: `hex8-structural-analysis`. 작성일: 2026-10-08. 상태: 사용자 승인된 구현 계약; 검증 완료 대기.
기준 저장소: `dev`, `2382d3af7ef335bef216d963540f2e9bd2befd68`.

## 목적과 선택 이유

개인 연구용 FESA에 8절점 육면체의 선형 강성, 기하비선형 내력·접선 강성, 일관 질량을
구현하고 입력부터 정적·고유치·동해석과 HDF5 결과까지 연결한다. 요소 행렬 계산만으로
완료하지 않는다. 기존 프로젝트를 유지하며 새 프로젝트 기준을 재작성하지 않는다.

첫 구현은 큰 회전·작은 탄성 변형률을 대상으로 한다. 전체 8점 적분과 Total Lagrangian
St. Venant–Kirchhoff의 deviatoric 항과 요소 평균 Green trace 체적 energy를 선택해
에너지·내력·접선의 일관성을 독립 검증한다. 2026-10-10 사용자 B 승인으로 최초 pointwise
체적 항을 대체했으며 [ADR-009](ADR.md)를 따른다. 일관 질량은
고유치와 동해석 모두에 사용한다. 집중 질량이나 안정화로 계산 결과를 맞추지 않는다.
일반 등매개 육면체를 지원하며 체적 projection의 안정성·conditioning 및 남은 굽힘 잠김 한계를 검증·공개한다.

초기 합의의 일정 동하중에 더해, 제공된 reference의 ramp를 처리하도록 구간별 선형
집중력 amplitude를 포함한다. 지정 변위의 시간 변화나 비영 초기 변위·속도까지 확대하지 않는다.

상위 기준: [공통 요구](../PRD.md), [구조](../ARCHITECTURE.md),
[외부 계약](../contracts.md), [수치 정책](../TOLERANCE.md),
[기능 기록](../FEATURE_DOCUMENTATION.md). 기존 상세 계약을 구현 편의로 덮어쓰지 않는다.

지역 지침과 문서 목록은 [FEATURED_AGENTS](FEATURED_AGENTS.md), 결정은 [ADR](ADR.md),
상세 유도는 [formulation](formulation.md), 입력/내부 API는 [io](io.md), 수치 controls는
[numeric-controls](numeric-controls.md), 원본 mapping은 [reference-model](reference-model.md)을 따른다.

## 요구사항과 계산 계약

### FEM-REQ-HEX8-001 — 지원 해석과 모델

육면체 단독 모델에서 선형 정적, 기하비선형 정적, 원형상·무응력 선형 frequency,
선형 및 기하비선형 HHT 동해석을 지원한다. 한 입력에 단일 step·단일 procedure이며
기존 Part/identity Instance·target/set subset을 재사용한다. 혼합 Beam/Shell/Solid 모델은 거부한다.
서로 다른 유효한 영역에 재료를 배정할 수 있지만 한 요소 내부의 재료는 균질하다.

### FEM-REQ-HEX8-002 — 요소·형상·순서

Source `C3D8`을 FESA Hex8로 연결하고 source 표기·instance·element/node label을 보존한다.
`C3D8R`, `C3D8I`, `C3D8H`, 20절점 요소를 alias로 수용하지 않는다. 요소는 서로 다른
8개 절점과 병진 `[UX,UY,UZ]`를 가지며 local 행렬은 node-major 24×24다.

자연 좌표 절점 순서는 다음과 같다.

| 절점 | ξ | η | ζ |
| --- | ---: | ---: | ---: |
| 1 | -1 | -1 | -1 |
| 2 | +1 | -1 | -1 |
| 3 | +1 | +1 | -1 |
| 4 | -1 | +1 | -1 |
| 5 | -1 | -1 | +1 |
| 6 | +1 | -1 | +1 |
| 7 | +1 | +1 | +1 |
| 8 | -1 | +1 | +1 |

\(N_a=(1+\xi_a\xi)(1+\eta_a\eta)(1+\zeta_a\zeta)/8\),
\(X=\sum N_aX_a\), \(u=\sum N_au_a\). J0의 column은 자연 좌표에 대한 X 미분이다.
\(G_a=\nabla_XN_a=J_0^{-T}\nabla_\xi N_a\)를 사용한다.
뒤틀린 면·기울어진 모서리를 허용한다. 비유한·중복/퇴화 절점, 반전·접힌 형상은 거부한다.
유효성은 자연 cell의 양의 Jacobian을 확인하는 보수적 검증으로 정의하고, 적분점만 양수인
접힌 cell을 정상으로 선언하지 않는다. 양성을 판정하지 못한 형상은 명시적 진단으로 거부한다.
현재 형상의 반전도 trial 실패다. `abs(det J)`·절점 재배열·epsilon 보정은 금지한다.

### FEM-REQ-HEX8-003 — 재료와 단위

상수 등방성 탄성 \(E>0,-1<\nu<0.5\)와 기준 밀도 \(\rho_0>0\)를 사용한다.
모든 값과 파생 shear/bulk 실행 계수는 finite여야 한다. 밀도는 고유치·동해석에서 필수이며 정적
입력의 양의 density는 보존하되 강성에 사용하지 않는다. 입력 일관 단위를 유지한다.
\(\mu=E/[2(1+\nu)]\), \(\kappa=E/[3(1-2\nu)]\)다. 두 실행 계수는 finite·positive여야 한다.
거의 비압축성인 입력을 다른 재료식으로 바꾸지 않으며 잠김과 conditioning을 구분해 보고한다.

### FEM-REQ-HEX8-004 — 적분 규칙

강성·내력·접선·질량·에너지에 동일한 2×2×2 Gauss 규칙을 사용한다.
각 축은 ±1/√3, weight=1이며 volume weight는 det J0다. 출력 point ID는
`1:---, 2:+--, 3:-+-, 4:++-, 5:--+, 6:+-+, 7:-++, 8:+++` 순서다.
절점 순서와 적분점 순서를 혼동하지 않는다. 모든 평균과 deviatoric 항은 이8점의 reference
체적 가중치로 계산한다. 체적 항은 요소 평균 trace energy이며 pointwise8점 체적 항이나
중심점 단일 적분으로 바꾸지 않는다. One-point reduced element·hourglass 항은 없다.
일반 뒤틀린 요소에서 8점 질량이나 비선형 적분이 연속체 적분과 항상 exact하다고 주장하지 않는다.
높은 차수 적분 oracle는 정확도·한계의 검사이며 production 규칙의 자동 변경이 아니다.

### FEM-REQ-HEX8-005 — 선형 강성

미소변형률 \(\epsilon_g=\operatorname{sym}\nabla_Xu\), \(V=\sum_gw_g\),
\(\bar\theta=\sum_gw_g\operatorname{tr}\epsilon_g/V\),
\(\sigma_g=2\mu\operatorname{dev}\epsilon_g+\kappa\bar\theta I\)다.
공학 전단 벡터 순서는 `[ε11,ε22,ε33,2ε12,2ε13,2ε23]`, 응력은
`[S11,S22,S33,S12,S13,S23]`다. 선형 energy는
\(U=\sum_gw_g\mu\operatorname{dev}\epsilon_g:\operatorname{dev}\epsilon_g+\kappa V\bar\theta^2/2\)다.
\(K_0=\partial^2U/\partial u^2\), \(f_{int}=K_0u\)이며 weighted divergence vector의
외적 \(\kappa bb^T/V\)로 서로 다른 point의 체적 coupling을 포함한다.
대칭성·6개 강체 영모드·상수 변형률 patch·단위와 scale을 독립 검증한다.

### FEM-REQ-HEX8-006 — 비선형 내력과 접선

기준 형상에서 \(F=I+\sum_a u_a\otimes G_a\),
\(E_{Gg}=(F_g^TF_g-I)/2\), \(\bar\theta=\sum_gw_g\operatorname{tr}E_{Gg}/V\)와
\(U=\sum_gw_g\mu\operatorname{dev}E_{Gg}:\operatorname{dev}E_{Gg}+\kappa V\bar\theta^2/2\),
\(S_g=2\mu\operatorname{dev}E_{Gg}+\kappa\bar\theta I\), \(P_g=F_gS_g\)다.
\(f_{ai}=\sum_g P_{iJ}G_{aJ}\det J_{0g}\)와 같은 에너지의 일관 미분
\(K_t=K_{mat}+K_{geo}\)를 반환한다.

\[
Z_g^{ai}=\operatorname{sym}(F_g^T(e_i\otimes G_{ag})),\quad
b_{ai}=\sum_gw_g(F_gG_{ag})_i,
\]
\[
(K_{mat})_{ai,bk}=2\mu\sum_gw_g\operatorname{dev}Z_g^{ai}:\operatorname{dev}Z_g^{bk}
                  +\kappa b_{ai}b_{bk}/V,\quad
(K_{geo})_{ai,bk}=\delta_{ik}\sum_gw_gG_{ag}^TS_gG_{bg}.
\]

F64와 paired 경로 모두 실제 relative kinematics의 같은 derivative인 Ghat를 사용한다.
평균 trace의 미분을 유지하고 point-local 기존 C로 체적 tangent를 대체하지 않는다. Kgeo만으로 전체 비선형 강성을
대체하지 않는다. 내부 API는 두 항과 합, 내력·에너지·복구량을 구별한다. 같은 trial에서
계산하며 유한차분 접선을 production 계산으로 사용하지 않는다. 강체 유한회전의 zero
strain/energy, 에너지 gradient·내력 tangent, 좌표 공변성, 선형극한을 검사한다.

### FEM-REQ-HEX8-007 — 일관 질량

\((M_e)_{ai,bj}=\delta_{ij}\sum_g\rho_0N_aN_b\det J_{0g}\)를 사용한다.
기준 형상과 밀도로 정해져 변형·시간에 따라 바뀌지 않으며 회전 자유도·drilling 관성은 없다.
고유치와 동해석은 같은 전역 일관 M을 사용한다. Row-sum lumping·nodal block 치환은 금지한다.
대칭 양정성·각 병진 방향 총질량·좌표 회전·독립 적분을 검증한다. 전역 행렬은 sparse로 조립한다.

### FEM-REQ-HEX8-008 — 경계와 집중력

실제 `*BOUNDARY`와 `*CLOAD` 성분은 DOF1–3이다. Solid-only 입력 호환 예외로
지원 displacement `*BOUNDARY`의 DOF4–6 exact-zero(생략된0 포함)만 source/location을
남기는 명시적 warning/no-op으로 수용한다. 범위1–6은1–3을 적용하고4–6만 경고한다.
회전 equation·constraint·state는 만들지 않는다. 비영 회전 BC, DOF4–6 CLOAD(값0 포함),
DOF1–6 밖의 경계와 의미 있는 미지원 BC 옵션은 계속 거부한다.
정적은 영/비영 지정 변위를 지원하고, 선형은 \(K_{ff}u_f=F_f-K_{fc}u_c\)다.
비선형 정적에서는 지정 값과 외력을 같은 load factor로 증가시켜 이전 accepted 상태에서
Newton을 수행한다. 동해석은 고정 exact-zero 경계만 지원한다. 동일 resolved node/DOF의
집중력은 source 순서로 합산한다. 모든 자유도가 constrained인 유효한 모델은 empty free
system으로 처리한다. 미구속 자유 강체의 정적 특이성은 질량·임의 고정점으로 보정하지 않는다.

### FEM-REQ-HEX8-009 — 동하중 amplitude

육면체 dynamic에서 모델-level `*AMPLITUDE, NAME=...`의 TABULAR, STEP TIME,
VALUE=RELATIVE만 지원한다. 각 선택자는 생략 시 이 값이며 명시된 동일 값도 허용한다.
유일한 이름과 한 개 이상 finite `(t,A)` pair, `t>=0`·strictly increasing 시간을 요구한다.
한 row의 여러 pair와 여러 data row를 허용한다. Knot은 원 값, 내부는 구간별 선형 보간,
범위 밖은 첫/마지막 값 유지다. Unresolved/duplicate 이름, 같은 시간, 역순·홀수 항목,
nonfinite, 다른 정의·시간 기준·값 종류·smoothing 옵션은 명시적 실패다.

`*CLOAD, AMPLITUDE=name`의 \(F(t)=A(t)F_{base}\)를 source 순서로 합산한다.
각 load block의 curve를 보존하며 서로 다른 curve를 미리 하나의 base force로 합치지 않는다.
Amplitude 없는 CLOAD는 `0+`부터 일정 하중이다. 표의 첫 시간/값을 강제로 0으로 만들지 않는다.
현재 reference Amp-1은 `(0,0),(0.1,1),(10,1)`이다. 지정 변위 amplitude와 static amplitude,
TOTAL TIME·SMOOTH STEP·주기 하중·물리적 damping은 이번 범위가 아니다.

### FEM-REQ-HEX8-010 — 공개 입력과 CLI

기존 lexical/source identity를 재사용하고 `*SOLID SECTION, ELSET=..., MATERIAL=...`와
생략 또는 blank data row를 허용한다. Thickness/plane stress/axisymmetric 의미를 추가하지 않는다.
`*STATIC`과 `*STATIC, DIRECT`의 고정 증분 subset을 지원한다. DIRECT의 `h,T`가 양수이며
`N*h==T`, `N<=INC`를 만족해야 한다. 일반 STATIC의 기존 load-factor subset도 유지한다.
`*FREQUENCY`의 mode 수가 권위이며 Lanczos/SIM source 옵션은 실제 MKL FEAST와 구별한다.
`*DYNAMIC, DIRECT`는 `NLGEOM=NO` 또는 `YES`, 고정 h/T와 INC를 지원한다.
Static/frequency/dynamic 각각의 기존 무해한 출력 요청 subset 및 제공 원본의 PRESELECT 요청을
명시적으로 검증한다. Output no-op이 필수 결과의 삭제·선택 기능이 되지 않는다.
기존 CLI 입력·lexical sibling 결과/로그 경로·exit category를 유지한다.

### FEM-REQ-HEX8-011 — 소유권과 전역 조립

Domain은 의미·재료/section·topology·amplitude를, DofManager는 3N full/free mapping과
scatter/pattern을, element는 local 계산을, analysis는 state/trial/commit을 소유한다.
공유 sparse 직접 쓰기 없이 source 순서의 결정적 누적을 유지한다. 6N Shell layout이나
회전 영공간에 Hex8을 끼워 넣지 않는다. 사용되지 않는 절점·잘못된 scatter는 fail-closed다.

내부 C++ API의 행동 계약은 다음과 같다. 구체적인 class/method 이름은 구현 계획의 영역이다.

| 연산 | 입력·출력과 불변량 |
| --- | --- |
| 요소 생성 | 검증된 source topology·기준 좌표·재료로 immutable 요소 생성; 실패는 기존 Result/Status |
| 선형 평가 | K0[24,24]·M[24,24], 주어진 u[24]의 f[24]·W·8점 복구량 |
| 비선형 trial 평가 | u[24]에서 f[24], Kmat/Kgeo/Kt[24,24], W, 8점 Cauchy/Green tensor; 호출이 accepted state를 변경하지 않음 |
| 조립·절차 실행 | Domain과 3N DOF mapping으로 sparse K/M 및 검증된 procedure별 결과; source 순서 유지 |
| 기록 | 완결된 accepted 결과만 받는 Solid writer; 검증 실패 시 기존 final 파일 보존 |

길이·성분 불일치와 nonfinite trial을 실패로 반환하며 vendor handle/type은 공개 API에 노출하지 않는다.

### FEM-REQ-HEX8-012 — 선형 정적

Kff solve 후 prescribed 값을 정확히 복구하고 full residual `K0u-F`를 계산한다.
Constrained 성분은 반력, free 성분은 평형 잔차이며 서로 별도 dataset으로 보존한다.
완료 load factor의 결과를 frame0으로 저장한다. 빈 free solve와 solver 실패를 구별한다.

### FEM-REQ-HEX8-013 — 비선형 정적

Accepted 증분별 q·내외력·응력·에너지와 convergence evidence를 보존한다. Newton은
\(f_{int}(u)-F\)의 free residual과 일관 tangent를 사용한다. 불안정 tangent를 SPD라고
가정하지 않는다. Recovery까지 검증한 candidate만 accept하며 실패 증분은 공개하지 않는다.
현재 일반 Newton controls를 재사용할 때 물리 3성분·force/length 단위에 맞는 적용을 검토한다.
회전·모멘트의 dummy channel은 만들지 않는다. 초기 tuning default는 기존 정적 기준의
force residual/translation correction 상대 `1e-2`, scale0 absolute `1e-3`의 해당 입력
force/length 단위, 증분당 최대100 iteration이다. 분모·분자·branch·단위·판정을 남긴다.
내부 solver tuning 조정은 독립 검토와 재검증을 기록하며 외부 acceptance를 바꾸지 않는다.

### FEM-REQ-HEX8-014 — 일반화 고유치

실제 동차 경계 적용 후 \(K_{ff}\phi=\omega^2M_{ff}\phi\)의 최저 N 모드를 구한다.
반복 고유치를 제거하지 않고 실제 3N 공간으로 복구해 mass-normalize한다. 해석 출력에는
lambda, frequency, mode vector와 residual/Gram evidence를 구별한다. 음수값을 abs/clamp하지 않는다.
강체 모드·cluster 경계·모드 누락·empty free/과도한 N을 검증한다.
\(\|K\phi-\lambda M\phi\|/[(\|K\|+|\lambda|\|M\|)\|\phi\|]\),
\(|\phi^TM\phi-1|\)와 mass Gram 오차는 `1e-10` 이하를 요구하며 zero denominator는
exact-zero 분기로 처리한다. 모든 backend 반환 pair를 검증한 뒤 공개 N을 선택한다.
Shell 전용 nodal whitening을 일관 M에 적용하지 않는다. 실제 generalized-SPD sparse
FEAST 또는 일관 문제를 정확히 보존하는 변환을 사용한다. Sparse pencil을 바꿔 수렴시키지 않는다.

### FEM-REQ-HEX8-015 — HHT 동해석

초기 q/v=0, constrained q/v/a/A=0이다. \(M_{ff}a_{0f}=F_f(0+)-f_{int,f}(0)\),
\(A_0=a_0\)로 초기화한다. Amplitude가 0이면 그 초기 힘을 그대로 사용한다.
공개 계수는 기존 HHT의 `alpha=-0.05`, `beta=0.275625`, `gamma=0.55`다.
Predictor/Newmark 갱신은 auxiliary A를 사용하고
\(A_{n+1}=(1+\alpha)a_{n+1}-\alpha a_n\)로 physical a와 구별한다.

\[
R=M A_{n+1}+(1+\alpha)(f_{n+1}-F(t_{n+1}))-\alpha(f_n-F(t_n)),
\quad K_{eff}=M/(\beta h^2)+(1+\alpha)K_t.
\]

이 weighted residual은 이전 physical endpoint 평형을 포함하며, 같은 관계로 환산한
endpoint 잔차를 쓰는 것도 동등성 검증을 전제로 허용한다. 서로 다른 표현의 tangent와
reaction을 혼용하지 않는다. Amplitude는 실제 각 endpoint에서 평가하고 한 step의 힘을
고정해두거나 잘못된 시간에서 한 번만 평가하지 않는다. 질량은 상수이므로 Shell의
회전 chart·moving-null·convective 관성은 이 절차에 없다. 선형은 K0, 비선형은 Kt를 사용한다.
물리 반력은 constrained \(Ma+f_{int}-F(t)\), free endpoint residual은 별도 evidence다.
초기부터 마지막까지 `n=0..N`, `time=double(n)*h`, exact schedule `N*h==T`를 유지한다.
마지막 증분 축소·adaptive time·restart는 지원하지 않는다.
동적 초기 tuning default는 기존 HHT의 normalized residual/correction `1e-10`,
Newmark update 일치 `1e-12`, 증분당 최대100 iteration이다. Force 잔차의 scale은
같은 endpoint의 uncancelled inertia/internal/external force로 만들며 scale0은 exact-zero다.
Correction은 기준 형상의 양의 길이 L로 u를, L/h와 L/h²로 v와 physical/auxiliary a를
정규화해 각각 확인한다. 회전 channel을 복제하거나 잔차를 보정한 뒤 accept하지 않는다.

### FEM-REQ-HEX8-016 — 응력·변형률 복구

8개 적분점에서 선형 global Cauchy stress·미소변형률, 비선형
\(\sigma=FSF^T/\det F\)와 기준 global Green–Lagrange strain을 복구한다.
Tensor strain 성분은 `[11,22,33,12,13,23]`의 실제 shear이며 B 계산용 engineering shear와
구별한다. 적분점 평균·절점 외삽·nodal smoothing을 하지 않는다. Cauchy stress와 PK2를
같은 이름으로 저장하지 않는다. 기본 공식 응력은 Cauchy다. Frequency의
mode vector를 물리 응답 변위/응력으로 복구하지 않는다.

### FEM-REQ-HEX8-017 — HDF5 계약

새 형식은 `/metadata`의 `feature_id=hex8-structural-analysis`, `schema_version=1`과
`analysis_procedure`로 식별한다. 값 집합은 `linear-static`, `nonlinear-static-full-newton`,
`linear-frequency`, `hht-linear-dynamics`, `hht-nonlinear-dynamics`다.
`element_formulation=FESA-Hex8`, `integration_rule=gauss-2x2x2`,
`mass_formulation=consistent-reference`, source step 이름·입력 byte identity·단위 의미를 보존한다.

Model row의 source instance/label은 기존 model identity 의미를 유지하되 Solid topology/section
분기를 추가한다. Node row는 Domain 선언 순서다. `/model/nodal_constraint_mask`는 U8[N,3],
free0/constrained1이다. 다음 mandatory compound field 순서와 dtype을 사용한다.
U64/U8/F64는 각각 unsigned 64/8-bit integer와 Float64 little-endian이며 문자열은 UTF-8다.

| model 경로 | field 순서·dtype |
| --- | --- |
| `/model/nodes` | `internal_node_id:U64, instance_name:string, source_label:string, coordinates:F64[3]` |
| `/model/elements` | `internal_element_id:U64, instance_name:string, source_label:string, source_element_type:string, internal_formulation:string, node_internal_ids:U64[8], solid_section_internal_id:U64, material_internal_id:U64` |
| `/model/solid/materials` | `internal_material_id:U64, name:string, youngs_modulus:F64, poisson_ratio:F64, density_present:U8, density:F64` |
| `/model/solid/sections` | `internal_section_id:U64, source_file:string, source_line:U64, source_elset:string, material_internal_id:U64` |
| `/model/solid_integration_points` | `internal_element_id:U64, point_id:U8, natural_coordinates:F64[3], reference_coordinates:F64[3]` |

Internal ID는 각 inventory의 zero-based index이고 point ID는1–8이다. 요소는 Domain 선언 순서,
integration-point row는 element-major/point-major다. `density_present`는0/1이고 부재 시
`density=0`은 저장 placeholder이며 해석 밀도로 사용하지 않는다. 필수 밀도 절차에서는 부재를
writer 이전에 거부한다. 원본 positive density가 있는 정적 모델은 이를 그대로 기록한다.

| 경로 또는 frame 상대 경로 | shape / 의미 |
| --- | --- |
| `/steps/Step-1/accepted_frames` | 아래 정의한 비선형 정적/동적 compound table |
| `/steps/Step-1/frames/<n>/nodal/displacement` | [N,3], U1/U2/U3 |
| `nodal/reaction` / `nodal/residual` | 각각 [N,3], 반력은 free exact0, residual은 full endpoint/static residual |
| `solid/stress` / `solid/strain` | [E,8,6], point 순서·global frame·Cauchy 또는 Green/infinitesimal 의미 attribute |
| `global/strain_energy` | scalar; accepted physical elastic energy |
| 동적 `nodal/velocity`, `acceleration`, `algorithmic_acceleration` | 각각 [N,3], V·physical a·auxiliary A |
| 동적 `global/kinetic_energy`, `external_work`, `energy_balance_error` | scalar; 서로 다른 양, 계산 정의 attribute |
| 동적 `global/linear_momentum`, `angular_momentum` | [3], global O=(0,0,0) 기준 |
| `/steps/Step-1/eigen/modes`, `frequencies`, `vectors` | 아래 정의한 mode records, frequency subset, F64[Nmode,Nnode,3] mass-normalized vector |

위 `Step-1`은 기존 storage step key이고 source step 이름은 metadata에 별도 보존한다.
모든 물리 배열·scalar는 F64다. Accepted table은 아래 field를 정확히 이 순서로 가진다.

- 비선형 정적: `frame_index:U64, increment_index:U64, load_factor:F64, iteration_count:U64, is_factor_one:U8`.
- 동적: `frame_index:U64, increment_index:U64, time:F64, iteration_count:U64, is_initial:U8`.

Flag는0/1이다. Static linear에는 accepted table이 없다. 비선형 정적 frame0은 첫 accepted
증분이고 baseline factor0은 공개 frame이 아니다. Dynamic은 frame=increment=n,
initial의 iteration_count=0이며 이후 값은 실제 accepted Newton/선형 solve 횟수다.
Final-static flag는 마지막 factor1 frame에만1이다.

Eigen `modes`는 `mode_id:U64, eigenvalue:F64, classification:U8, cluster_id:U64`,
`frequencies`는 `mode_id:U64, frequency:F64`다. Mode/cluster ID는1부터 증가하며 mode는
lambda 오름차순이다. Classification 집합은0=rigid-near-zero, 1=positive다. 검증된 near-zero
음수 lambda도 원 값으로 남기고 frequency row를 만들지 않으며 유의한 음수는 solver failure다.
Nonnegative lambda에만 `frequency=sqrt(lambda)/(2*pi)`를 기록한다. 초기 tuning default는
`lambda_scale=max_i(abs(Kff_ii)/Mff_ii)`에서 `abs(lambda/lambda_scale)<=1e-9`를 near-zero,
인접 normalized gap `>1e-8`을 새 cluster로 분류한다. 양의 M diagonal과 finite positive
lambda_scale을 확인한다. 이 scale은 FEAST interval의 스펙트럼 상한으로 주장하지 않는다.
기능 numeric-controls에 scale·설정·독립 검증을 기록하고 저장 lambda를 보정하지 않는다.
`/steps/Step-1/eigen/verification/pairs`는 backend가 반환한 모든 검증 pair의 table이며
`sorted_rank:U64, solver_column:U64, eigenvalue:F64, modal_mass:F64, rayleigh_quotient:F64, eta_r:F64, eta_norm:F64, eta_energy:F64`다.
Backend column은0-based, rank는1-based다. 같은 verification group의 `eta_gram`,
`max_eta_orth`는 F64 scalar다. Backend 고유 trace는 기존 공개 의미로 추가 기록할 수 있으나
필수 original K/M 검증량을 다른 operator의 잔차로 대체하지 않는다.

Static frame0은 완료 결과, nonlinear static frame은 accepted 증분, dynamic frame0은 initial이다.
Frequency에는 static/dynamic frame dataset을 요구하지 않는다. 각 결과에 component_names,
unit dimensions, coordinate/location, step/frame/time 또는 load_factor 의미를 명시한다.
Self-check는 위 dtype/field 순서·shape·identity·flag·finite·frame schedule와 accepted 값의
readback 일치를 검증한다. 기능 I/O 문서는 이 계약을 상세화하며 다른 field 집합으로 바꾸지 않는다.
기존 Beam/Shell/Thermal 파일의 required dataset이나 schema를 바꾸지 않는다.
Full/element matrix dump는 공식 결과에 포함하지 않는다.

### FEM-REQ-HEX8-018 — 물리 수지와 에너지

정적은 힘·모멘트 평형, 동적은 운동량 변화율과 applied/support 힘·모멘트를 검사한다.
Consistent M으로 \(T=v^TMv/2\), \(U=\sum W_g\det J_{0g}\)를 계산한다.
외력 일은 endpoint force와 displacement increment의 trapezoid 누적이며 초기0,
`energy_balance_error=T+U-T0-U0-Wext`다. 현재 BC는 동적 exact0여서 support work=0이다.
HHT의 알고리즘 소산과 quadrature에 따른 work 오차를 설명하며 각 frame exact conservation을
강제하지 않는다. Alpha0 내부 검사에서는 선형 무하중 보존을 독립 확인한다.
Moment와 angular momentum은 현재 위치와 consistent interpolation의 kinetic 식으로 평가한다.

### FEM-REQ-HEX8-019 — 실패와 진단

미지원 physics/옵션, geometry/trial 반전, 비유한 값, singular/invalid matrix, 수렴 실패,
backend resource 실패를 source/entity와 함께 명시적으로 보고한다. Invalid model과
solver failure, output failure를 기존 category로 구분한다. 실패 candidate는 마지막
accepted state/history와 기존 final HDF5를 변경하지 않는다. Write·readback·close·atomic
replace 실패를 검사한다. 로그 보존과 final 결과 보존은 서로 다른 계약이다.

### FEM-REQ-HEX8-020 — 결정론

Serial/parallel local 계산에서 source identity·equation/scatter·ordered reduction·결과 row와
진단 순서를 재현한다. 같은 수치 설정에서 반복 실행 결과를 검증한다. Modal sign은
최대 절대 성분의 최초 source-order index를 양수로 고정한다. 반복 고유값의 벡터별 일치는
외부 비교하지 않으며 해당 공간의 mass Gram·residual·subspace 불변량으로 검증한다.

## 검증과 완료 조건

### FEM-REQ-HEX8-021 — 독립 수치·물리 검증

정식화·numeric controls를 독립 검토한 뒤 의미 있는 local/integration 검사를 수행한다.
검사 oracle는 production 식·assembly를 단순 복제하지 않는다. 최소 사례는 다음과 같다.

1. 정육면체의 독립 정확 적분 K/M, 다항 patch, 6 rigid modes, total mass·scale·좌표변환.
2. 비대칭 왜곡·뒤틀린 요소의 Jacobian, folded/inverted/degenerate 및 비유한 입력.
3. 유한 rigid rotation과 strained-then-rotated 상태, 에너지 gradient·tangent directional
   difference의 step sweep, Kmat/Kgeo 분리와 zero-state Kt=K0.
4. 비영 BC·전체 구속·static singular 모델·성공/실패 state와 HDF5 보존.
5. 실제 generalized K/M 고유쌍의 독립 dense 작은 모델 oracle, density scaling,
   clustered/rigid modes·최저 N·original-free residual/Gram.
6. 선형 oscillator의 해석해 및 alpha0, amplitude knot 전/정확/후·초기 a·서로 다른 curve,
   비선형 constant-mass 제조해의 전체 u/v/physical a 시간수렴.
7. 실제 Hex8 mesh의 h/h2/h4 응답·가속도·힘/모멘트/에너지 수지, 큰 회전과 작은 strain,
   spatial mesh refinement·full-integration 잠김 한계, serial/parallel 결정론.

내부 zero/noise scale과 conditioning 기준은 수식·정밀도·oracle에 근거한 기능별
numeric controls로 정하고 독립 검토한다. 외부 5%/1%를 내부 정확성 기준으로 사용하지 않는다.
시간수렴은 변위만 맞는 사례로 대신하지 않으며 유의한 오차 구간과 미분량 차수를 함께 판정한다.

### FEM-REQ-HEX8-022 — 필수 reference

2026-10-08 확인된 원본은 `reference/hexa/`다. 모두 read-only다.

| case | 입력 | 결과·필수 family |
| --- | --- | --- |
| 선형 정적 | `hexa_linearstatic.inp` | `_U.csv`, `_RF.csv`, `_S.csv`: 완료 frame의 U1–3, constrained RF1–3, Cauchy S 6성분 |
| 비선형 정적 | `hexa_nonlinearstatic.inp` | 동일 suffix: 완료 load-factor frame의 U·RF·적분점 Cauchy S |
| 선형 동적 | `hexa_dynlinear.inp` | `hexa_dynlinear_U.csv`: initial 포함 101 frame U1–3 전체 |
| 비선형 동적 | `hexa_dynnonlinear.inp` | `hexa_dynnonlinear_U.csv`: initial 포함 101 frame U1–3 전체 |
| Frequency | `hexa_freq.inp` | 원본 modal Value 결과 아직 없음. 사용자 준비 자료로 최저10 modes를 비교해야 함 |

현재 inventory는 442 nodes, 300 elements다. 정적 U/RF 각442행, 수정된 정적 S 각2400행의
`IntPt=1..8`, 동적 U 각각44642행이다. 기존 elemental-nodal 응력 CSV의 위치 계약을
사용하지 않는다. 동적 V/A·reaction/energy reference는 없으므로 독립 검증이 필수다.
필요한 고유치 원본이 없으면 그 비교는 미실행이고 전체 기능 완료도 대기다.
원본 추가 전이라도 독립 구현·검증 작업은 계속할 수 있다.

### FEM-REQ-HEX8-023 — 비교 identity와 수치 정책

Nodal key는 case/source step/increment/instance/node/component, stress key는
case/source step/frame/instance/element/IntPt/component다. CSV header의 공백은 lexical
정규화하되 source row를 삭제·평균하거나 nonfinite를 보정하지 않는다. 좌표와 point convention은
원본 precision을 고려한 보조 검증이며 nearest-position matching으로 ID를 추정하지 않는다.
Dynamic은 integer increment로 대응한 뒤 각 source decimal time과 binary64 n*h schedule을
검증한다. Static은 마지막 factor-one frame에 대응하고 storage frame 번호가 같다고 가정하지 않는다.

정적 U-global·RF-global·S-global은 서로 다른 blocking family, 동적 U-global은 frame별
blocking family다. RF는 원본 전체442행 inventory를 먼저 확인한 뒤 실제 constrained components를
투영한다. Free RF를 FESA free residual로 비교하지 않는다. S는 각 case/frame의 300×8×6을
포함한다. Modal Value는 mode별 singleton blocking family이며 외부 mode-shape 비교는 비목표다.
Missing/extra/duplicate/identity/nonfinite 오류는 tolerance 이전 실패다.
공통 정책의 S=max|reference|, B=.01S, 일반 row relative≤.05, family RMS/S≤.01,
S=0 exact-zero를 적용한다. MITC4 eigen의 RMS5% 예외는 육면체에 적용하지 않는다.
Source C3D8의 입력 호환성과 Abaqus 내부 integration/constitutive/time-algorithm 동등성은
서로 다르다. 불일치 시 정식화·reference identity·절차를 조사하며 acceptance를 임의 완화하지 않는다.

### FEM-REQ-HEX8-024 — 회귀·완료 판정

구현 완료 시 실제 설정의 MSVC x64 Debug 전체 build/CTest와 필수 reference 비교,
독립 수치·물리 검토가 필요하다. 최신 source revision·명령·native exit·metric·hash를 기록한다.
모든 신규/영향 검사 PASS, 모든 필수 reference PASS, 미해결 신규 physics 오류0이 완료 조건이다.
기존 HHT C08 두 FAIL·C04a SKIP의 과거 기록은 baseline으로 직접 재확인하고, 동일하다면
기존 미해결로 별도 보고한다. 전체 suite를 green이라 부르거나 제외 실행으로 대체하지 않는다.
기존 오류를 새 오류와 섞거나 현재 작업의 성공을 위해 Shell/Thermal 수식·policy를 변경하지 않는다.
Reference·필수 실행이 대기라면 구현/내부 검증 완료와 기능 검증 완료를 분리한다.

## 범위 밖

20절점·tetra·wedge·hybrid/incompatible/reduced 요소, lumped 선택 API, 큰 strain용 다른
재료·소성·contact·물리 damping·압력·중력·체적력·시간변화 BC·비영 초기 q/v,
mixed mesh·Shell–Solid 연결·prestressed modes·좌굴·다중 step/restart·adaptive/explicit dynamics,
열-구조 연성·matrix dump·외부 배포·release-readiness는 포함하지 않는다.

## 방법과 자료의 한계

평균 Green trace energy는 선택한 탄성 regime의 FESA 모델이며 Abaqus `*ELASTIC, NLGEOM=YES`의
평균 J/Fbar·유한변형 재료 알고리즘과 동일하다고 주장하지 않는다. 선형 체적 평균 일치를
비선형 동등성으로 승계하지 않는다. 제공 결과의 일치만으로 다른 regime을 보증하지 않는다.

Amplitude의 step-time·상대 값·선형 보간·끝 값 유지 의미는
[Abaqus 공식 설명](https://docs.software.vt.edu/abaqusv2025/English/SIMACAEPRCRefMap/simaprc-c-amplitude.htm)을 따른다.
Generalized sparse FEAST의 공개 진입점은
[Intel 공식 문서](https://www.intel.com/content/www/us/en/docs/onemkl/developer-reference-c/2026-0/feast-scsrgv-feast-hcsrgv.html)에서 확인했다.
이는 설치 runtime·빈 interval·workspace·정식화 검증 evidence를 대신하지 않는다.

## 현재 checklist

2026-10-10 사용자 B 승인은 HEX8-ADR-009의 체적 평균 energy를 다섯 절차에 적용하고
전체 재검증하는 변경이다. 아래 관련 항목은 변경본에서 다시 확인한다. 이어지는 이전
pointwise 구현의 실행 기록은 과거 evidence이며 변경본 PASS로 승계하지 않는다.

2026-10-09 사용자 A 승인은 [내부 정밀도 변경안](precision-proposal.md)의 전체 high+low
물리 상태와 Float64 반올림 observable을 FEM-REQ-HEX8-015·017–020에 적용한다.
HHT 식·기준 consistent M·입력·고정 schedule·100회·Si/exact-zero·원래 strict gate 및
외부 tolerance는 유지한다. 아래 구현·검증 checklist는 이 승인만으로 완료되지 않는다.

- [x] 승인된 체적 평균 수식·입출력·numeric controls·원본 mapping 정리 및 독립 numerical review 완료
- [ ] 체적 평균 Hex8 K0/consistent M/비선형 f/Kmat/Kgeo/Kt·형상·복구 kernel 검증
- [x] Solid Domain/parser/3N DOF/ordered assembly/amplitude 검증
- [ ] 체적 평균 선형·비선형 정적 accepted state/반력/잔차 검증
- [ ] 체적 평균 generalized consistent-mass frequency·최저 N·original-pencil 검증
- [ ] 체적 평균 선형·비선형 HHT u/v/physical a·시간수렴·수지 내부 검증
- [ ] 체적 평균 공식 HDF5/CLI/self-check/실패 final 보존 검증
- [ ] 정적2·동적2 원본 필수 family 비교 PASS
- [ ] 사용자 원본 최저10 modal Value 제공 및 필수 비교 PASS
- [ ] 최신 전체 MSVC Debug build/CTest·기존 baseline 대조 완료
- [ ] Independent numerical/physics blocker0·범위/한계/evidence 기록 완료

Local kernel과 입력·3N mapping은 독립 검토 및 연결 후 관련180개 검사를 통과했다.
정적 구현 `a34466f`의 관련98개와 고유치 구현 `0e07b4d`의 관련48개 검사가 각각
native CTest exit0이며 독립 수치 검토를 통과했다. 두 정적 원본과442절점 고유치 원본은
직접 API로 실행했지만 원본 결과값 비교를 수행한 것은 아니다. 연결 source `28be39f`의
전체 MSVC Debug build는 exit0이며 이 build 자체를 전체 CTest 통과로 해석하지 않는다.
과거 단일 Float64 구현 `f661864`는 관련76개 검사와 독립 수치 검토를 통과했지만,
두 동적 원본의 세 번째 증분에서 strict gate를 만족하지 못했다. 이 실패는
[lessons](lessons.md)에 보존하며 현재 방식의 결과와 구분한다.
승인된 전체 high+low 구현 `c49cae4`는 소규모32/32 및 별도 성공한 LIN/TL·SDOF/MDOF
시간수렴 사례와 독립 numerical/physics 검토를 확보했다. Root 연결 후 관련49/49와
추가 직렬/TBB low 일치1/1 검사도 native build/CTest0/0이다. 두 원본의 초기 상태와
증분1–3은 unchanged schedule로 관측했고, 원래 모든 free 성분의 전체 pair 물리 gate를
독립 재계산했다. 이 관측은 네 번째 증분 전에 종료했으며 전체101 endpoint 완료가 아니다.
상세 범위와 한계는 [수치 검토](numerical-review.md), [물리 검토](physics-review.md)에 있다.
공식 결과 연결은 `e2c3c5b`에 통합했다. 작성자 행동본의 관련101/101과 public header만
보완한 후속본의5절차 API/schema1/1이 native build/CTest0/0이며, 독립 수치·I/O 검토에서
요청 밖 modal pair의 입력 검증 누락을 보완하고 잔여 finding0을 확인했다. 메인 연결 후
실제 CLI·HDF5·full-pair RN64·실패 final 보존 관련17/17도 native build/CTest0/0이다.
이 범위의 완료와 외부 비교·최신 전체 회귀는 구분한다. 실행 방법은 [README](README.md),
세부 근거와 한계는 [수치 검토](numerical-review.md)에 있다.
원본 frequency 결과 부재는 구현 진행을 막지 않지만 기능 검증 완료를 막는다.
비교기 `317fe5c`는 원본 identity·schema·finite·허용오차·원본 덮어쓰기 보호의 독립 검토와
관련124/124 Python 검사(native0)를 통과했다. Root 연결 후 같은 관련124/124도 native0이며
정적 수치 실패와 modal NOT RUN을 재현했다. 두 정적 원본은 실제 CLI native0이지만
U/RF/S 필수 비교는 모두 FAIL이다. 고유치 공식 readback은 검사했으나 원본 Value 부재로
비교는 NOT RUN이다. [verification](verification.md)의 metric과
[승인된 변경 근거](reference-discrepancy-proposal.md)를 구분한다. 별도 선형 Python 후보의
수치 일치는 현재 구현의 PASS가 아니다. Source `1eb9cdd`의 전체 build는 native0이고
제외 없는780개 CTest는 native8,777 PASS·2 FAIL·1 SKIP으로 종료됐다. 추가163개는 모두
PASS이며 기존 예외3개의 이름·status·metric body가 baseline과 동일하다. 전체 green은 아니다.
기존 pointwise 구현의 두 동적 원본도 native0으로101 endpoint를 완료했다. 이는 새 체적
평균 energy의 결과가 아니며 변경본의 검증은 위 checklist에 따라 다시 수행한다.