FESADev/docs/hex8-structural-analysis/ADR.md

# Hex8 기능 결정 기록

Feature ID: `hex8-structural-analysis`. 상태: 사용자 승인된 구현 계약.
기준: [프로젝트 지침](../../AGENTS.md), [공통 PRD](../PRD.md), [공통 ADR](../ADR.md).
상세 행동은 [PRD](PRD.md), 수식은 [formulation](formulation.md)을 따른다.
아래 결정은 ready 인터뷰 및 최종 승인 뒤 go 실행 요청으로 확정했다. 구현/검증 통과를 의미하지 않는다.

## HEX8-ADR-001 — Full-integration TL–StVK

**선택:** 8절점 일반 등매개 육면체, 3개 병진 DOF,2×2×2 전체 Gauss 적분,
Total Lagrangian–St. Venant–Kirchhoff의 energy/internal force/material+geometric tangent.
**이유와 영향:** 큰 회전·작은 elastic strain을 대상으로 같은 energy의 미분 일관성을 검증한다.
이 최초 선택의 pointwise 체적 항은 이후 HEX8-ADR-009로 대체됐다. Hourglass/hybrid/incompatible mode는 범위 밖이다. 굽힘/체적 잠김과
거의 비압축성 conditioning 한계를 공개한다. Abaqus C3D8 내부 처리와 동일하다고 주장하지 않는다.

## HEX8-ADR-002 — Constant reference consistent mass

**대체 이력:** 2026-10-11 HEX8-ADR-010이 질량 선택을 대체했다. 아래는 당시 승인 기록이다.
**선택:** M은 기준 밀도와 형상의 rho NiNj I 적분이며 eigen과 linear/nonlinear HHT에 동일하게 사용한다.
**영향:** 전역 sparse generalized K/M가 필요하다. Shell nodal whitening·null-space 처리나
row-sum lumping을 호환 경로로 쓰지 않는다. Solid에는 회전/convective 관성이나 drilling이 없다.

## HEX8-ADR-003 — End-to-end Solid-only 절차

**선택:** Linear/nonlinear static, 원형상 unloaded frequency, linear/nonlinear HHT와 공식 HDF5를 연결한다.
Nodal force와 static 영/비영 prescribed displacement만 지원하며 mixed Beam/Shell/Solid·pressure/
body force·prestressed modes는 제외한다. Dynamic은 initial q/v0, fixed zero BC·fixed step이다.
**영향:** Model/DOF/state/writer에 Solid의3성분 분기가 필요하며 dummy6성분 결과로 대체하지 않는다.

## HEX8-ADR-004 — Reference ramp와 integration-point stress

**선택:** 제공된 dynamic 원본에 필요한 TABULAR/STEP TIME/RELATIVE piecewise-linear CLOAD
amplitude를 지원한다. 사용자 최종 답변 `1A, 2B 적분점 응력 결과로 수정했습니다.`에 따라
수정된 static S의8점6성분을 필수 비교한다. Static/BC amplitude·비영 초기 상태는 추가하지 않는다.
**영향:** 곡선별 source load block을 보존하고 endpoint/initial force를 평가한다. Point key는
element/IntPt/component이며 elemental-nodal stress·평균·외삽으로 바꾸지 않는다.

## HEX8-ADR-005 — 독립 검증과 필수 외부 비교

**선택:** 분석/불변량·독립 numerical/physics 검토·실제 전체 Debug 회귀 및 승인 원본 비교를 결합한다.
**영향:** 공통 row5%/RMS1%를 유지한다. MITC4 eigen RMS5% scoped exception은 적용하지 않는다.
원본 frequency Value 부재는 필수 비교 미실행이며 기능 검증 완료 대기다. 제공된4개 응답 case와
독립 eigen 검증은 진행한다. 기존 HHT baseline FAIL/SKIP을 신규 문제와 구분하며 전체 green을 주장하지 않는다.

## HEX8-ADR-006 — 기존 프로젝트와 소유권 유지

**선택:** Absent local marker에도 사용자 선택 A에 따라 기존 AGENTS/docs 맥락을 유지한다.
**영향:** Foundation과 공통 요구/결정을 재작성하지 않는다. Feature 문서는 자체 계약과 필요한
handoff/evidence만 소유한다. Shared CMake/factory와 prepared/HDF5 연결에 단일 writer를 둔다.
Failed candidate/출력 실패에서 accepted history와 기존 final HDF5를 보존한다.

## HEX8-ADR-007 — Inactive zero rotational BC의 한정된 호환 예외

**승인:** 2026-10-09 사용자는 필수 원본의 zero DOF4–6 경계와 strict 거부 계약 충돌에 대해
A(영 회전 경계만 경고/no-op으로 수용)를 선택했다. 독립 검토 HEX8-NR-001의 해결이다.
**선택:** Solid-only supported displacement BC의 exact-zero DOF4–6(생략0 포함)만 source/location
warning/no-op으로 수용한다. Mixed1–6 range의1–3은 적용하고4–6만 경고한다.
**영향:** 실제 DOF·constraint·state/output은3성분이다. 비영 회전 BC·모든 회전 CLOAD,
DOF범위 밖이나 의미 있는 미지원 BC 옵션은 계속 거부한다. 원본을 수정·preprocess하지 않는다.
Parser에서 경고·translational 적용·회전 equation 부재·거부 경계를 행동 테스트로 확인한다.

## HEX8-ADR-008 — High+low 내부 물리 상태와 Float64 observable

**승인:** 2026-10-09 사용자는 제한된 단일·두 좌표 및 보상 가산 관찰 실패 이후
A([내부 정밀도 변경안](precision-proposal.md))를 선택했다.
**선택:** Solid HHT 내부 상태·predictor·힘·rates·수지·gate에 normalized high+low를
일관되게 사용하고 accepted history/rollback도 전체 상태를 보존한다. 기존 Float64
backend와 HDF5 field/shape/dtype은 유지하되 공식 값은 전체 물리량의 반올림 observable이다.
**영향:** 기존 Si/exact-zero·strict gate·HHT 계수·기준 M·고정 h/schedule·100회와 외부
tolerance는 유지한다. Kernel/geometry에 low를 전달하지 않는 update carry와 구분한다.
작은 독립 산술/Hex8·시간수렴·상태 보존 검증과 긍정적 실제 실행 이후 필수 원본101개
endpoint·HDF5/외부 비교·전체 회귀를 진행한다. 승인과 수렴 완료를 혼동하지 않는다.

## HEX8-ADR-009 — Reference-volume 평균 Green trace energy

**대체 이력:** 2026-10-11 HEX8-ADR-010이 consistent M 보존 부분만 대체한다. 평균 energy 결정은 유지한다.
**승인:** 2026-10-10 사용자는 [체적 차이와 변경안](reference-discrepancy-proposal.md)의
B: 체적 평균 energy 도입 후 전체 재검증을 선택했다.
**선택:** 선형·비선형 정적, unloaded frequency, 선형·비선형 HHT 모두 같은 요소 energy를
사용한다. Reference 8점 가중치와 실제 infinitesimal/Green strain의 deviatoric 항을 유지하고,
체적 항을 `kappa*V*theta_bar^2/2`, `theta_bar=sum(w*trace(strain))/V`로 정의한다.
내력과 Kmat/Kgeo/Kt는 이 energy의 일관 미분이며 체적 tangent는 서로 다른 Gauss 점의
coupling을 포함한다. 평균 determinant/Fbar/로그변형률 재료식은 채택하지 않는다.
**영향:** ADR-001의 pointwise 체적 energy/구성식과 그 강성을 대체한다. 실제 strain을
출력하고 응력은 요소 평균에 의존하는 law로 복구한다. Reference consistent M·HHT 식·
고정 schedule·100회·strict gate·전체 pair 상태·반올림 observable·공식 field/schema와
원본·수치 기준은 유지한다. 새 solver 선택 옵션이나 원본 diagnostic 전환은 추가하지 않는다.
**검증:** 한 선형 private 후보의 원본 일치와 독립 변분 검토는 근거이며 production PASS가 아니다.
새 kernel/절차·시간/공간수렴·공식 출력·필수 원본·전체 MSVC Debug 회귀를 다시 검증한다.
기존 pointwise 구현의 통과·실패 기록은 과거 evidence로 보존하고 변경본에 승계하지 않는다.

## HEX8-ADR-010 — 고유치·HHT reference row-sum lumped mass

**승인:** 2026-10-11 사용자 “앞으로 고유치 해석과 HHT 동해석에서 질량 행렬은 lumped mass로 계산”.
**선택:** Full reference consistent24×24 M_C를 기존8점 적분으로 계산한 후 각 row sum을
대각에 둔 M_L을 eigen과 선형/비선형 HHT에 공통 사용한다. BC restriction 이전 요소 전체
행 합을 계산한다. Free block만 lump하거나 warped 요소의 절점 질량을 rho*V/8로 치환하지 않는다.
**영향:** HEX8-ADR-002 및 ADR-009의 consistent M 보존 부분만 대체한다. 평균 체적 energy,
high+low state/force/rates/gate·HHT 계수·schedule·100회·strict gate·외부 tolerance·출력 layout은
유지하며 metadata는 `lumped-reference`다. 관성력·T·P·L와 rates에도 같은 M_L을 사용한다.
**검증:** 질량·대각/SPD·warped 독립 적분·Jensen·BC 전후의 차이·원래 pencil residual/Gram/count와
HHT/반력·시간수렴·공식 readback·필수 원본5개·전체 Debug 회귀를 새로 확인한다. 기존 consistent
PASS/FAIL 및 private 후보의 일치는 변경본 production 통과로 승계하지 않는다.
현재 진행 상태는 [PRD](PRD.md)의 현재 checklist를 따른다.