docs: consolidate solver knowledge and preserve formulation originals

docs/hex8-structural-analysis/README.md

@@ -1,105 +1,122 @@
 # Hex8 구조해석
 
-개인 연구용 FESA에 8절점 육면체의 선형 강성, Total Lagrangian–StVK 기하비선형
-내력·접선 강성과 기준 형상의 row-sum lumped 질량을 추가한다. 요소당 병진 자유도는24개다.
+## 범위와 현재 근거
 
-2026-10-11 [HEX8-ADR-010](ADR.md)이 질량 정책을 변경했다. 아래 기존 구현의 실행 결과는
-consistent M의 당시 evidence이며 lumped 변경본 재검증은 [PRD](PRD.md)의 현재 checklist를 따른다.
+8절점 육면체 C3D8의 요소당24 병진 DOF로 선형/비선형 정적, unstressed generalized
+고유치와 선형/비선형 HHT 동해석을 제공한다. 2026-10-10 mean-volume 강성과 10-11 row-sum lumped 질량을 승인했다. **Mean-volume 강성·
+reference row-sum lumped 질량**이 현재 정책이다. 현재 구현·원본5개 비교·검토·인계는
+확보했으나 최신 전체 통합 완료(FEM-REQ-HEX8-024)는 보류다.
 
-2026-10-13 현재 구현·필수 원본5개 비교·검토·인계를 마쳤다. 이번 확인은
-Debug 관련 C++91 PASS·Hex8 비교기 Python96 PASS 및 보존된 원본5개 결과의
-현재 비교기 재대조 PASS다. 새 장시간 원본 실행이나 전체 CTest는 수행하지 않았다.
-정적2·고유치의 원본 결과는 Debug, 동적2는 Release에서 생성한 기존 근거다.
-Hex8 경로의 source 동일성과 독립 검토, 성능 최적화로 넘길 범위는
-[최종 인계](final-handoff.md)에 기록했다.
+2026-10-13의 관련 Debug C++91/91·비교기 Python96개가 PASS였고, 현재 비교기로 보존된
+정적2·고유치1·동적2 결과를 재대조해 모두 PASS였다. 새 장시간 원본 실행이나 전체 CTest는
+수행하지 않았다. 정적/고유치 결과는 당시 Debug, 동적2는 Release 산출물이다. Hex8 직접
+실행·질량·복구·출력 source 동일성은 확인했으나 전체 공용 binary 동일성이나 전체 green을
+주장하지 않는다. Shell의 최신 C08b·원본·전체 Debug 사용자 중단은 [HHT 요약](../hht-implicit-dynamics/README.md)을 따른다.
 
-초기 lumped 변경본의 관련38개·Python137개·전체789개의 결과와 당시 Shell
-실패는 [채택·재검증 보고서](lumped-mass-adoption.md)의 과거 이력이다.
-당시 C08b runtime 실패는 후속 승인된 초기 Newton 정책으로 해소됐고,
-ADR-018의 C09와 공식 Release C08a7도 통과했다. 최신 C08b·Shell 원본·전체
-Debug는 사용자 중단이며, 전체 검증은 성능 최적화 후 진행한다.
-FEM-REQ-HEX8-024의 최종 통합 완료 판정은 보류한다.
-선형/비선형 정적, reference lumped-mass frequency,
-선형/비선형 HHT 동해석을 typed state에서 공식 HDF5와 CLI까지 연결한다.
+## 채택 방법과 이유
 
-다음 단락은 변경 전 consistent mass 구현의 이력이다.
+[기본 정식화](formulation.md)와 [정밀도 정식화](precision-formulation.md)가 상세 수식을
+보존한다. 강성·복구·reference mass 적분은 2×2×2다. 선형 infinitesimal strain 또는
+TL–StVK Green strain에서 deviatoric energy를 점별 적분하고, 체적 energy는
+`kappa*V*theta_bar^2/2`, `theta_bar=sum(w_g*tr(E_g))/V`로 계산한다. Pointwise bulk의
+과도한 강성을 줄이는 채택이며 center/unweighted mean, Fbar, mean-J와 다르다.
+Force와 Kmat/Kgeo/Kt는 같은 energy의 gradient/Hessian이다. 평균의 미분에는 서로 다른
+GP 간 coupling도 포함하며 local StVK tangent로 대체하지 않는다.
 
-강성·질량·복구에2×2×2 reference 적분점을 사용한다. 2026-10-10 승인으로 deviatoric 항과
-요소 평균 infinitesimal/Green trace 체적 energy를 사용한다. 변경본 구현·내부 검증은 완료했고
-두 정적 원본의 U/RF/S 및 두 동적 원본의101-frame U 필수 비교도 PASS다.
-실제 정적·동적 원본의 독립 수치·물리 검토도 bounded PASS다. 전체787 CTest는
-784 PASS·기존 Shell FAIL2·SKIP1(native8)으로 종료했고 추가170개는 모두 PASS다.
-전체 green은 아니다. 2026-10-11 제공된 modal Value 원본과 실제 비교했으나
-최저10개 중7개가1% RMS 기준을 초과했다. 최대 차이는5번 고유치의20.2513%이며
-[최종 비교](verification.md#2026-10-11-제공된-고유치-원본의-최종-비교)에 근거를 기록한다.
-필수 modal 불일치가 해결되기 전 기능 검증 완료는 대기다. 전체 Python도 기존 collection5
-오류로 native2·실행0개다.
+Mass는 full reference consistent24×24 matrix의 **행합을 BC 축소 전에** 구한 대각 matrix다.
+Warped 요소의 모든 node를 rho*V/8로 치환하지 않는다. Eigen normalization·HHT inertia·
+reaction·kinetic energy·momentum은 같은 reference M을 사용한다. Current geometry에 따라
+mass를 재계산하지 않는다. 이 질량 변경은 입력 선택 option을 추가하지 않는다.
 
-구현과 기능 검증 완료는 다르다. 원본 정적2·동적2의 필수 수치 비교, 사용자 modal Value와
-최신 전체 회귀·최종 검토가 완료 조건이다. 현재 상태는 [PRD checklist](PRD.md#현재-checklist),
-선택과 승인 이력은 [ADR](ADR.md)에 있다.
+Solid HHT는 normalized high+low로 전체 physical state와 이력을 유지한다. Element의
+상대변위 `u_a-u_0`에서 strain/force를 만들고 `Ghat_0=-sum(a>0)G_a`를 실제 gradient와
+미분에 함께 사용한다. Tiny Green strain은 sym(H)+H^T H/2로 계산한다. Predictor·rates·
+full residual·recovery·work·energy·momentum·다음 accepted state에 low를 보존한다.
+Backend에는 RN64 operator/RHS를 전달하지만 acceptance는 full pair에서 검사한다.
+공식 F64 출력은 전체 값의 RN64 observable이며 low를 별도 영속 field로 내보내지 않는다.
+Rounded 출력만 다시 넣어 엄격한 내부 gate의 같은 PASS를 기대하지 않는다. Restart는 없다.
 
-## 사용법
+Whole-cell positive Jacobian은 outward-rounded interval/Bernstein subdivision으로 인증한다.
+현재 좌표는 X+u_high+u_low 전체를 포함한다. Depth10/cell budget65536에서 인증되지 않는
+uncertain 형상도 실패하며 |detJ|·clamp·자동 다른 요소로 정상화하지 않는다.
 
-[공통 환경·빌드 방법](../operations.md)에 따라 MSVC x64 Debug 실행 파일과 dependency DLL을
-준비한다. CLI는 입력 `.inp` 하나를 받으며 입력의 lexical parent에 `<stem>_results.h5`와
-`<stem>_log.txt`를 생성한다. `--output`은 지원하지 않는다.
+## 입력·출력·reference mapping
 
-Read-only 원본에서 직접 실행하지 않고 별도 폴더에 복사한 입력으로 실행한다. 저장소 루트의
-다음 예시는 제공된 선형 정적 입력을 사용한다.
+Single Part/identity Instance의 Solid-only C3D8, SOLID SECTION, 상수 isotropic ELASTIC을
+지원한다. Frequency/HHT는 양의 DENSITY가 필요하다. 실제 BC/CLOAD는 DOF1–3이다.
+Exact-zero 회전 BC4–6만 source warning/no-op이며 비영 회전 BC와 값0을 포함한 모든
+회전 CLOAD는 거부한다. 정적 비영 prescribed는 absolute target이고 비선형 factor가
+force/target에 함께 적용된다. HHT는 zero BC/initial u,v와 fixed DYNAMIC,DIRECT schedule,
+TABULAR step-time relative CLOAD amplitude의 linear interpolation/end hold를 지원한다.
+Static/BC amplitude·TOTAL TIME·smoothing은 제외한다. Source FREQUENCY LANCZOS/SIM
+표기와 내부 generalized MKL FEAST를 구분한다. [공통 solver 요약](../solver-core/README.md)에
+CLI·lease·공통 수치 정책이 있다. CLI는 입력 sibling에 결과를 쓰며 --output은 지원하지 않는다.
 
-```powershell
-New-Item -ItemType Directory -Path '.harness/hex8-example' -Force
-Copy-Item -LiteralPath 'reference/hexa/hexa_linearstatic.inp' -Destination '.harness/hex8-example/hexa_linearstatic.inp'
-& '.harness/build-ninja-msvc-debug/src/fesa/fesa.exe' '.harness/hex8-example/hexa_linearstatic.inp'
-$LASTEXITCODE
-```
+Schema version1, feature_id=hex8-structural-analysis,
+`mass_formulation=lumped-reference`, `component_order=node-major; UX,UY,UZ`다.
+기존 consistent-reference 파일을 metadata만 바꿔 재사용하지 않는다. F64/U64/U8은 explicit
+little-endian, 문자열은 UTF-8이고 모든 physical 값은 finite다.
 
-Native exit0과 이번 입력의 `source_input_identity`를 함께 확인한다. 기존 결과 파일의 존재만으로
-이번 실행의 성공을 판단하지 않는다. 해석·로그·쓰기·readback·close·final 교체 실패에서는 기존
-최종 HDF5를 보존한다.
+| 결과 | Shape·의미 |
+| --- | --- |
+| frame nodal/displacement, reaction, residual | [N,3]; U, constrained projection RF, full R는 별도 |
+| frame solid/stress, solid/strain | [E,8,6]; global Cauchy S11/S22/S33/S12/S13/S23, infinitesimal 또는 Green strain의 tensor shear |
+| dynamic nodal/velocity, acceleration, algorithmic_acceleration | [N,3]; v, physical a, auxiliary A |
+| dynamic energy/work/balance·linear/angular momentum | 같은 full pair의 RN64; balance=T+U-T0-U0-W, W는 endpoint force 사다리꼴 work |
+| /steps/Step-1/eigen/modes, frequencies, vectors | eigenvalue와 cycles/time 구분; vectors [modes,N,3], phi^T M phi=1 |
+| eigen/verification/pairs, eta_gram, max_eta_orth | 반환한 모든 pair의 residual·normalization·직교 검증량 |
 
-입력은 single Part/identity Instance의 Solid-only `C3D8`, `SOLID SECTION`, 상수 등방성
-`ELASTIC`을 사용한다. Frequency와 동해석에는 양의 `DENSITY`가 필요하다. 실제 BC/CLOAD는
-DOF1–3이다. 승인된 exact-zero 회전 BC4–6만 source 경고와 no-op으로 처리하며, 비영 회전
-BC와 값0을 포함한 모든 회전 CLOAD는 거부한다. Unsupported 의미를 기본값으로 흡수하지 않는다.
+Strain은 실제 point kinematics이며 평균 strain으로 바꾸지 않는다. Cauchy stress의
+isotropic 항이 모든 점에서 같은 pressure라는 뜻도 아니다. Extrapolation/절점 평균은 없다.
 
-정적 해석은 지정 변위·집중하중, 비선형은 full Newton을 사용한다. 동해석은 fixed
-`DYNAMIC,DIRECT` schedule, 영 초기 변위·속도와 영 지정 BC를 사용하며 CLOAD의
-`TABULAR` step-time relative amplitude·선형 보간·끝 값 유지를 지원한다. Frequency의 원본
-LANCZOS 표기는 보존하지만 내부 해법은 generalized MKL FEAST다. 상세 subset과 실패 의미는
-[I/O 계약](io.md), field·shape는 [PRD017](PRD.md#fem-req-hex8-017--hdf5-계약)을 따른다.
+Reference/hexa의5 INP·8 CSV와 hexa_freq.txt는 read-only다. 442nodes/300elements,
+E=2.1e11,nu=.3,rho=7850, Step-1이다. Static DIRECT h=.1/T=1의 Increment10에서 U/RF/S를
+각각 blocking family로 비교한다. U/RF 전체442 inventory 뒤 RF만 실제 constrained 성분으로
+투영하며 free RF와 FESA free residual을 비교하지 않는다. Stress는300×8×6 전부다.
+Dynamic h=.1/T=10의101 frames 각각442×3 U family이며 Amp-1=(0,0),(.1,1),(10,1)이다.
+Frequency TXT의 Mode1..10 Value=lambda를 eigen/modes.eigenvalue와 직접 비교한다.
+Freq를 lambda로 변환하거나 mode를 근접 재매칭하지 않는다.
 
-## 결과와 다른 기능 개발의 참조점
+Key는 case/step/increment/instance/source node 또는 element/IntPt/component다.
+IntPt 순서는 `---,+--,-+-,++-,--+,+-+,-++,+++`이며 node 순서와3/4·7/8이 다르다.
+Missing/extra/duplicate/nonfinite/schema/mass 오류는 tolerance 전에 실패한다. S=max|reference|,
+near-zero band/error limit .01S, 일반 relative .05, family RMS/S .01, S=0 exact-zero이며
+Shell eigen의5% RMS 예외는 적용하지 않는다. Coordinate는 reference 위치다.
 
-Nodal 결과는 `N×3`, 적분점 stress/strain은 `E×8×6`이다. Source node/element/IntPt identity를
-보존하고 절점 평균·외삽을 하지 않는다. Stress는 global Cauchy, strain은 선형 infinitesimal
-또는 비선형 Green–Lagrange이며 shear 성분은 tensor다. 반력과 전체 residual은 구분한다.
-Frequency는 modes/vectors와 모든 반환 pair의 검증량을 별도 eigen 경로에 저장한다.
+## 실제 코드와 수명
 
-HHT는 변위·속도·physical a·algorithmic A와 force·energy·history를 normalized high+low로
-유지한다. 공식 Float64는 전체 물리량의 RN64 observable이며 low를 별도 영속 field로 내보내지
-않는다. 출력 배열만으로 엄격한 내부 gate를 다시 계산해 같은 판정을 기대하지 않는다.
-Restart는 지원하지 않는다. [정밀도 정식화](precision-formulation.md)는 같은 gradient의
-내력·미분, 산술 범위와 반올림 의미를 다음 개발에 전달한다.
+[Hex8Element](../../include/fesa/elements/hex8_element.h)의 ComputeStiffness/ComputeMass,
+EvaluateLinear/EvaluateNonlinear 및 high+low 대응 함수가 local response를 제공한다.
+[기본 kernel](../../src/fesa/elements/hex8_element.cpp),
+[paired kernel](../../src/fesa/elements/hex8_high_low.cpp),
+[형상 인증](../../src/fesa/elements/hex8_geometry.cpp)은 immutable reference cache와 독립 trial을 사용한다.
+[HighLow arithmetic](../../src/fesa/math/high_low_arithmetic.h)은 RN·FTZ/DAZ 환경과 지원 product
+범위를 검사하고 unsupported underflow/overflow를 실패로 전파한다. Universal correctly-rounded
+106-bit 보장은 아니다. Reduction 순서를 바꾸는 최적화도 수치 변경이다.
 
-[정식화](formulation.md)는 K/M·접선·형상 인증·물리량의 기준이다.
-[수치 기준](numeric-controls.md)은 엄격한 내부 gate와 외부 tolerance를 구분한다.
-[원본 mapping](reference-model.md)은 case/frame/source identity·point 순서·RF projection을
-소유한다. 독립 평가의 범위는 [수치 검토](numerical-review.md)와 [물리 검토](physics-review.md),
-실패와 수정 근거는 [lessons](lessons.md)에 보존한다.
-원본 고유치 불일치의 [질량·요소 설정 조사](reference-mass-investigation.md)는 공식
-Abaqus row-sum mass 설명과 별도 K/M 분리 계산을 기록한다. Mean K+lumped M의
-수치 재현은 채택 전 연구 이력이다. 현재 [HEX8-ADR-010](ADR.md)의 production 변경본은
-[별도 새 실행](lumped-mass-adoption.md#원본-비교)으로 원본5개 비교 PASS를 확인했다.
+Domain이 정의를 소유하고 DofManager가3N numbering/scatter를 소유한다. Stable local contribution을
+ordered assembly한 뒤 [Solid static](../../src/fesa/analysis/solid_static_procedure.cpp),
+[frequency](../../src/fesa/analysis/solid_frequency_procedure.cpp),
+[SolidHhtDynamicProcedureExecutor](../../src/fesa/analysis/solid_hht_dynamic_procedure.cpp)가 typed state를
+만든다. [SolidDynamicAnalysisState](../../include/fesa/analysis/solid_dynamic_analysis_state.h)의
+accepted full pairs가 다음 predictor의 원본이다. Domain은 view보다, 호출자 adapter는 Execute보다
+오래 살아야 한다. [Solid writer](../../src/fesa/io/hdf5/solid_hdf5_results_writer.cpp)는 완결 결과를
+write/close/reopen/self-check 후 atomic finalize하며 실패 candidate는 history와 기존 final을 보존한다.
 
-## 적용 한계
+## 수치 의미와 검증 한계
 
-체적 projection의 conditioning·안정성과 남은 굽힘 shear locking을 검증하고,
-다른 요소 formulation으로 자동 대체하지 않는다. Warped geometry는 보수적으로 cell 전체의 Jacobian 양성을 인증하며
-uncertain geometry/trial도 실패한다. StVK 선택과 입력 호환성은 외부 solver의 내부 재료·체적
-처리·시간 알고리즘 동등성을 보증하지 않는다.
+Solid HHT physical residual r=Ma+f-F는 모든 원래 free 성분에서
+`|r_i|/(|Ma_i|+|f_i|+|F_i|)<=1e-10`, zero scale exact-zero다. Weighted 식과
+`(1+alpha)r_new-alpha*r_old`의 identity·update는 uncancelled scale의1e-12이며 old residual을
+0으로 치환하지 않는다. q/v/a/A fresh correction은 h와 reference length로 무차원화해1e-10,
+증분당100 corrections를 유지한다. Geometry/recovery/finite/gate를 모두 통과한 trial만 commit한다.
 
-Reduced/hybrid/incompatible·20절점 요소, 소성·contact, mixed Shell–Solid mesh, 압력·체적력,
-시간변화 지정 BC·비영 초기 상태, adaptive/explicit dynamics와 restart는 범위 밖이다.
-한 원본 U의 일치만으로 physical a·에너지·일반 mesh나 장시간 정확성을 검증했다고 주장하지 않는다.
+과거 consistent mass의 modal7/10 FAIL·최대20.2513%와 Python collection5 오류는 당시 이력이다.
+Lumped 변경본의 새 원본5개 PASS와 후속 재대조가 이를 대체하는 해당 범위 근거이며 과거 전체787의
+784 PASS/2 FAIL/1 SKIP이나 전체789/802를 새 전체 green으로 합산하지 않는다.
+
+Reduced/hybrid/incompatible/20절점, plasticity/contact, mixed shell-solid, pressure/body load,
+시간변화 BC·비영 초기상태, adaptive/explicit/restart는 제외한다. Mean-volume의 conditioning·
+warped stability·남은 bending shear locking, 임의 큰 변형/mesh/시간간격은 일반 보증 범위 밖이다.
+원본 U 일치만으로 physical a·장시간 에너지·전체 시간수렴을 검증했다고 주장하지 않는다.
+최적화 후 최종 source의 전체 MSVC Debug build/CTest·필수 원본·독립 물리 확인이 남는다.