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

# 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를 따른다.

2026-10-13 현재 구현·필수 원본5개 비교·검토·인계를 마쳤다. 이번 확인은
Debug 관련 C++91 PASS·Hex8 비교기 Python96 PASS 및 보존된 원본5개 결과의
현재 비교기 재대조 PASS다. 새 장시간 원본 실행이나 전체 CTest는 수행하지 않았다.
정적2·고유치의 원본 결과는 Debug, 동적2는 Release에서 생성한 기존 근거다.
Hex8 경로의 source 동일성과 독립 검토, 성능 최적화로 넘길 범위는
[최종 인계](final-handoff.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 구현의 이력이다.

강성·질량·복구에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개다.

구현과 기능 검증 완료는 다르다. 원본 정적2·동적2의 필수 수치 비교, 사용자 modal Value와
최신 전체 회귀·최종 검토가 완료 조건이다. 현재 상태는 [PRD checklist](PRD.md#현재-checklist),
선택과 승인 이력은 [ADR](ADR.md)에 있다.

## 사용법

[공통 환경·빌드 방법](../operations.md)에 따라 MSVC x64 Debug 실행 파일과 dependency DLL을
준비한다. CLI는 입력 `.inp` 하나를 받으며 입력의 lexical parent에 `<stem>_results.h5`와
`<stem>_log.txt`를 생성한다. `--output`은 지원하지 않는다.

Read-only 원본에서 직접 실행하지 않고 별도 폴더에 복사한 입력으로 실행한다. 저장소 루트의
다음 예시는 제공된 선형 정적 입력을 사용한다.

```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
```

Native exit0과 이번 입력의 `source_input_identity`를 함께 확인한다. 기존 결과 파일의 존재만으로
이번 실행의 성공을 판단하지 않는다. 해석·로그·쓰기·readback·close·final 교체 실패에서는 기존
최종 HDF5를 보존한다.

입력은 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 의미를 기본값으로 흡수하지 않는다.

정적 해석은 지정 변위·집중하중, 비선형은 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-계약)을 따른다.

## 결과와 다른 기능 개발의 참조점

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의
내력·미분, 산술 범위와 반올림 의미를 다음 개발에 전달한다.

[정식화](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를 확인했다.

## 적용 한계

체적 projection의 conditioning·안정성과 남은 굽힘 shear locking을 검증하고,
다른 요소 formulation으로 자동 대체하지 않는다. Warped geometry는 보수적으로 cell 전체의 Jacobian 양성을 인증하며
uncertain geometry/trial도 실패한다. StVK 선택과 입력 호환성은 외부 solver의 내부 재료·체적
처리·시간 알고리즘 동등성을 보증하지 않는다.

Reduced/hybrid/incompatible·20절점 요소, 소성·contact, mixed Shell–Solid mesh, 압력·체적력,
시간변화 지정 BC·비영 초기 상태, adaptive/explicit dynamics와 restart는 범위 밖이다.
한 원본 U의 일치만으로 physical a·에너지·일반 mesh나 장시간 정확성을 검증했다고 주장하지 않는다.