docs(hex8): define approved mean-volume energy contract

docs/hex8-structural-analysis/PRD.md

@@ -10,9 +10,11 @@ Feature ID: `hex8-structural-analysis`. 작성일: 2026-10-08. 상태: 사용자
 완료하지 않는다. 기존 프로젝트를 유지하며 새 프로젝트 기준을 재작성하지 않는다.
 
 첫 구현은 큰 회전·작은 탄성 변형률을 대상으로 한다. 전체 8점 적분과 Total Lagrangian
-St. Venant–Kirchhoff 식을 선택해 에너지·내력·접선의 일관성을 독립 검증한다. 일관 질량은
+St. Venant–Kirchhoff의 deviatoric 항과 요소 평균 Green trace 체적 energy를 선택해
+에너지·내력·접선의 일관성을 독립 검증한다. 2026-10-10 사용자 B 승인으로 최초 pointwise
+체적 항을 대체했으며 [ADR-009](ADR.md)를 따른다. 일관 질량은
 고유치와 동해석 모두에 사용한다. 집중 질량이나 안정화로 계산 결과를 맞추지 않는다.
-일반 등매개 육면체를 지원하지만 full integration의 굽힘·체적 잠김 한계는 공개한다.
+일반 등매개 육면체를 지원하며 체적 projection의 안정성·conditioning 및 남은 굽힘 잠김 한계를 검증·공개한다.
 
 초기 합의의 일정 동하중에 더해, 제공된 reference의 ramp를 처리하도록 구간별 선형
 집중력 amplitude를 포함한다. 지정 변위의 시간 변화나 비영 초기 변위·속도까지 확대하지 않는다.
@@ -64,9 +66,9 @@ Source `C3D8`을 FESA Hex8로 연결하고 source 표기·instance·element/node
 ### FEM-REQ-HEX8-003 — 재료와 단위
 
 상수 등방성 탄성 \(E>0,-1<\nu<0.5\)와 기준 밀도 \(\rho_0>0\)를 사용한다.
-모든 값과 파생 Lamé 상수는 finite여야 한다. 밀도는 고유치·동해석에서 필수이며 정적
+모든 값과 파생 shear/bulk 실행 계수는 finite여야 한다. 밀도는 고유치·동해석에서 필수이며 정적
 입력의 양의 density는 보존하되 강성에 사용하지 않는다. 입력 일관 단위를 유지한다.
-\(\mu=E/[2(1+\nu)]\), \(\lambda=E\nu/[(1+\nu)(1-2\nu)]\)다.
+\(\mu=E/[2(1+\nu)]\), \(\kappa=E/[3(1-2\nu)]\)다. 두 실행 계수는 finite·positive여야 한다.
 거의 비압축성인 입력을 다른 재료식으로 바꾸지 않으며 잠김과 conditioning을 구분해 보고한다.
 
 ### FEM-REQ-HEX8-004 — 적분 규칙
@@ -74,33 +76,45 @@ Source `C3D8`을 FESA Hex8로 연결하고 source 표기·instance·element/node
 강성·내력·접선·질량·에너지에 동일한 2×2×2 Gauss 규칙을 사용한다.
 각 축은 ±1/√3, weight=1이며 volume weight는 det J0다. 출력 point ID는
 `1:---, 2:+--, 3:-+-, 4:++-, 5:--+, 6:+-+, 7:-++, 8:+++` 순서다.
-절점 순서와 적분점 순서를 혼동하지 않는다. 감소 적분·선택적 체적 적분·hourglass 항은 없다.
+절점 순서와 적분점 순서를 혼동하지 않는다. 모든 평균과 deviatoric 항은 이8점의 reference
+체적 가중치로 계산한다. 체적 항은 요소 평균 trace energy이며 pointwise8점 체적 항이나
+중심점 단일 적분으로 바꾸지 않는다. One-point reduced element·hourglass 항은 없다.
 일반 뒤틀린 요소에서 8점 질량이나 비선형 적분이 연속체 적분과 항상 exact하다고 주장하지 않는다.
 높은 차수 적분 oracle는 정확도·한계의 검사이며 production 규칙의 자동 변경이 아니다.
 
 ### FEM-REQ-HEX8-005 — 선형 강성
 
-미소변형률 \(\epsilon=\operatorname{sym}\nabla_Xu\), \(\sigma=\lambda\operatorname{tr}\epsilon I+2\mu\epsilon\).
+미소변형률 \(\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]`다. 일의 짝이 되는 B0와 C를 사용해
-\(K_0=\sum_g B_{0g}^TCB_{0g}\det J_{0g}\), \(f_{int}=K_0u\)를 계산한다.
+`[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_G=(F^TF-I)/2\), \(W=\lambda(\operatorname{tr}E_G)^2/2+\mu E_G:E_G\),
-\(S=\lambda\operatorname{tr}E_GI+2\mu E_G\), \(P=FS\)다.
+\(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}\)를 반환한다.
 
 \[
-A_{iJkL}=\delta_{ik}S_{LJ}+F_{iI}\mathbb C_{IJLN}F_{kN},\qquad
-(K_t)_{ai,bk}=\sum_gG_{aJ}A_{iJkL}G_{bL}\det J_{0g}.
+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}.
 \]
 
-\(\mathbb C_{IJLN}=\lambda\delta_{IJ}\delta_{LN}+\mu(\delta_{IL}\delta_{JN}+\delta_{IN}\delta_{JL})\).
-기하 항은 \(\delta_{ik}G_a^TSG_b\), 나머지는 재료항이다. Kgeo만으로 전체 비선형 강성을
+모든 gradient는 실제 relative kinematics의 같은 derivative이며 paired 경로는 Ghat를 사용한다.
+평균 trace의 미분을 유지하고 point-local 기존 C로 체적 tangent를 대체하지 않는다. Kgeo만으로 전체 비선형 강성을
 대체하지 않는다. 내부 API는 두 항과 합, 내력·에너지·복구량을 구별한다. 같은 trial에서
 계산하며 유한차분 접선을 production 계산으로 사용하지 않는다. 강체 유한회전의 zero
 strain/energy, 에너지 gradient·내력 tangent, 좌표 공변성, 선형극한을 검사한다.
@@ -412,9 +426,9 @@ mixed mesh·Shell–Solid 연결·prestressed modes·좌굴·다중 step/restart
 
 ## 방법과 자료의 한계
 
-StVK는 선택한 탄성 regime의 FESA 모델이며 Abaqus `*ELASTIC, NLGEOM=YES`와 내부
-유한변형 재료 알고리즘이 동일하다고 주장하지 않는다. Full 8점은 Abaqus C3D8의 체적
-처리까지 그대로 재현하겠다는 선택이 아니다. 제공 결과의 일치만으로 다른 regime을 보증하지 않는다.
+평균 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)을 따른다.
@@ -424,18 +438,22 @@ Generalized sparse FEAST의 공개 진입점은
 
 ## 현재 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 완료
-- [x] Hex8 K0/consistent M/비선형 f/Kmat/Kgeo/Kt·형상·복구 kernel 검증
+- [ ] 승인된 체적 평균 수식·입출력·numeric controls·원본 mapping 정리 및 독립 numerical review 완료
+- [ ] 체적 평균 Hex8 K0/consistent M/비선형 f/Kmat/Kgeo/Kt·형상·복구 kernel 검증
 - [x] Solid Domain/parser/3N DOF/ordered assembly/amplitude 검증
-- [x] 선형·비선형 정적 accepted state/반력/잔차 검증
-- [x] Generalized consistent-mass frequency·최저 N·original-pencil 검증
-- [x] 선형·비선형 HHT u/v/physical a·시간수렴·수지 내부 검증
-- [x] 공식 HDF5/CLI/self-check/실패 final 보존 검증
+- [ ] 체적 평균 선형·비선형 정적 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 대조 완료
@@ -467,6 +485,9 @@ native CTest exit0이며 독립 수치 검토를 통과했다. 두 정적 원본
 정적 수치 실패와 modal NOT RUN을 재현했다. 두 정적 원본은 실제 CLI native0이지만
 U/RF/S 필수 비교는 모두 FAIL이다. 고유치 공식 readback은 검사했으나 원본 Value 부재로
 비교는 NOT RUN이다. [verification](verification.md)의 metric과
-[미채택 변경안](reference-discrepancy-proposal.md)을 구분한다. 별도 선형 Python 후보의
+[승인된 변경 근거](reference-discrepancy-proposal.md)를 구분한다. 별도 선형 Python 후보의
 수치 일치는 현재 구현의 PASS가 아니다. Source `1eb9cdd`의 전체 build는 native0이고
-780개 CTest는 진행 중이다. 종료 전 checklist를 통과로 바꾸지 않는다.
+제외 없는780개 CTest는 native8,777 PASS·2 FAIL·1 SKIP으로 종료됐다. 추가163개는 모두
+PASS이며 기존 예외3개의 이름·status·metric body가 baseline과 동일하다. 전체 green은 아니다.
+기존 pointwise 구현의 두 동적 원본도 native0으로101 endpoint를 완료했다. 이는 새 체적
+평균 energy의 결과가 아니며 변경본의 검증은 위 checklist에 따라 다시 수행한다.