FESADev/docs/hex8-structural-analysis/reference-model.md

# Hex8 원본과 비교 mapping

기준은 [PRD](PRD.md)의 FEM-REQ-HEX8-022–023와 [공통 수치 정책](../TOLERANCE.md)이다.
기존 source revision은2382d3a이며 사용자 제공 `reference/hexa/`의5 INP·8 CSV와
2026-10-11 첨부된 `hexa_freq.txt`를 read-only로 사용한다. 새 TXT의 raw SHA로 추가 원본을 식별한다.
아래 hash는 현재 Windows working-tree raw bytes(CRLF) 기준이며 Git LF blob hash와 구분한다.

## 원본 inventory

442 nodes/300 C3D8 elements, material E=2.1e11/nu=.3/rho=7850, source Step-1이다.
Static DIRECT h=.1/T=1의 마지막 Increment10을 비교하고 nonlinear은 NLGEOM=YES다.
Dynamic DIRECT h=.1/T=10의 Increment0..100 전체를 비교한다. Amp-1은 `(0,0),(.1,1),(10,1)`다.
Frequency는 original unstressed 상태의10 modes 요청이며 결과 Value는 `hexa_freq.txt`에 제공됐다.
원본5개 모두 Set-1의 zero rotational BC4/5/6을 포함한다. 사용자 승인된
[HEX8-ADR-007](ADR.md#hex8-adr-007--inactive-zero-rotational-bc의-한정된-호환-예외)에 따라
이 행만 source warning/no-op으로 처리하며 원본과 실제3N mapping을 보존한다.

| 원본 | CSV rows | SHA-256 raw |
| --- | ---: | --- |
| `hexa_dynlinear.inp` | — | `f8db81b8ea56b689ab0ad892e6a84b7c6a0162c9d3ff95328ea99722f3de078e` |
| `hexa_dynlinear_U.csv` | 44642 | `623c20489e8cc18d23fa1728563ce5a26059f321861514ef8569e3d204ef6cb5` |
| `hexa_dynnonlinear.inp` | — | `1685f86f844e8020bf46e1747b949699ac9aff0d7570bd21ec95109399365ff9` |
| `hexa_dynnonlinear_U.csv` | 44642 | `f5832a24577f54838bb49dec86a0dc9668cf43e78953f718a9d3635e0f574226` |
| `hexa_freq.inp` | — | `42cbcec2a8b738f8b6d2c1e13114b8840dccdde6fc3e6f8a43a3272e85d82347` |
| `hexa_freq.txt` | 10 modes | `3d2dacbee13cd2cc8d3f7c1a38210611a72de41d5e31d169e636bf40e00d4370` |
| `hexa_linearstatic.inp` | — | `67183909c5dc962a4d4b65ffb81f7bd65b72e89a5d015c8369a8e0226347a647` |
| `hexa_linearstatic_RF.csv` | 442 | `3e04e71ec075ffef098cf4870d77f9c400557fccb375369da8bf67cf67c1e36b` |
| `hexa_linearstatic_S.csv` | 2400 | `8840a502b9d28a91e5685349301a56fed37d2ac62327b71304716b714db577e8` |
| `hexa_linearstatic_U.csv` | 442 | `1ff49aea3ec601cfd796d6a2fb6a4f91be3fc3de9426cdf3744d981216d4bd5f` |
| `hexa_nonlinearstatic.inp` | — | `7858254025b96c6bfe3fb6498605ecf9c473425c2bc3593f5fbdc6902fd7c6cb` |
| `hexa_nonlinearstatic_RF.csv` | 442 | `3ba67a4fb75b2ce3edee13d35b2ea66ac7d52fc16e612c086ed1122a834fee7b` |
| `hexa_nonlinearstatic_S.csv` | 2400 | `a8866a730f0d65b1e3921d504d255b72158b4a2b9ee30fc691712d94982b07ba` |
| `hexa_nonlinearstatic_U.csv` | 442 | `bd6c2fe2b2bb2ffb0bc2ea52f67513c3967a396b5707bbebc9533fde7be25ac6` |

## Quantity와 identity

Static은 U1/U2/U3의 U-global, RF1/RF2/RF3 constrained projection의 RF-global,
integration-point Cauchy S11/S22/S33/S12/S13/S23의 S-global을 각각 독립 blocking family로 비교한다.
U/RF는442-row 전체 inventory를 먼저 확인하고,
RF만 실제 constrained components로 투영한다. Free Abaqus RF와 FESA free residual을 비교하지 않는다.
Stress는300×8×6 전부 포함하며 elemental-nodal stress·절점 외삽·평균으로 변환하지 않는다.
Dynamic U는101 frame 각각442×3인 독립 blocking family다. Frequency Value는 mode별 singleton이며
MITC4 eigen scoped5% RMS 예외를 적용하지 않는다.

제공 TXT의 행 형식은 `Mode n: Value = lambda Freq = f (cycles/time)`다.
`Value`는 고유치 λ(`1/time^2`)이며 HDF5 `eigen/modes.eigenvalue`와 직접 비교한다.
`Freq`는 cycles/time의 보조 열이고 비교값으로 변환하지 않는다. 시간 단위를 SI로 추정하지 않는다.
TXT에는 step field가 없으므로 고정 case `hexa_freq`와 hash-checked 입력의 유일한 `Step-1`에
한정해 대응한다. 다른 모델·step을 판별하는 범용 형식으로 설명하지 않는다.
Mode ID1–10을 일대일 대응하고 반복 고유치를 제거하거나 가까운 값으로 재매칭하지 않는다.
빈 줄은 허용하되 잘못된 형식·mode 누락/추가/중복·비유한/음수 값·mode별 역순 Value는 실패다.
실제 비교에서는 원본 raw SHA도 고정하며 수정한 복사본을 정상 원본으로 취급하지 않는다.

2026-10-11 후속 [질량·요소 설정 조사](reference-mass-investigation.md)는 Abaqus1차 요소의
row-sum lumped 질량과 조사 당시 FESA consistent 질량의 차이를 확인했다. 동일 평균 K에
lumped M을 사용한 별도 진단은10개 λ 모두 상대차이0.00196105% 이내였지만,
생산 구현의 mass 계약이나 실제 modal FAIL 판정을 변경하지 않는다.

Key는 source case/step/frame 또는 increment/canonical instance/node 또는 element/IntPt/component다.
CSV header whitespace만 lexical 정규화하고 duplicate/missing/extra/nonfinite required value를
tolerance 전에 실패시킨다. `PART-1-1`과 input raw `Part-1-1`은 기존 Abaqus case 의미로 대응한다.
FESA storage Step-1/frame0과 source name/Increment10의 서로 다른 의미를 유지한다.
Dynamic은 integer increment로 match 후 source decimal time과 binary64 n*h를 대조한다.
Original coordinate는 reference 위치이며 nonlinear current 위치로 바꾸어 맞추지 않는다.

## Integration point convention의 보조 확인

Natural node 순서는 `---,+--,++-,-+-,--+,+-+,+++,-++`, IntPt 순서는
`---,+--,-+-,++-,--+,+-+,-++,+++`다. 뒤의3/4·7/8을 node 순서와 혼동하지 않는다.
전체300×8 point에서 고정 element/IntPt key로 입력 shape의 기준 위치를 계산해 CSV X/Y/Z와
대조했다. 선형/비선형 S 모두 최대 absolute coordinate difference는
`[1.4328052233558708e-7,1.4747179877261374e-7,2.4956611142101792e-6]`이었다.

이 보조 확인의 budget은 coordinate 성분의 uncancelled shape sum에16×float32 eps를 곱했다.
모든 point에서 maximum budget ratio=.112265였다. 이는 단정밀도 수준의 원본 출력 해상도를
기준으로 한 convention sanity check이며 실제 원본 precision metadata의 증명이나 stress값의
PASS가 아니다. Nearest-position matching을 수행하지 않았고 어떤 좌표/ID/값도 수정하지 않았다.

명령은 `python .dryforge/inspect-reference.py`, native exit0이었다. 로컬 raw 보고서는
`.harness/hex8-evidence/reference-inventory.json`이며 해당 ignored evidence를 지속할 사용자 파일로
오인하지 않는다. Formal comparator의 identity/coordinate controls는 동일 의미를 실제 tests로 검증한다.

## 비교 정책과 남은 검증

2026-10-11 [HEX8-ADR-010](ADR.md)이 reference lumped mass를 승인했다. 다음7/10 FAIL은
consistent M의 과거 판정이며 변경본은 원본5 case와 독립 물리/시간 검증을 다시 수행한다.
현재 metadata는 `lumped-reference`이며 과거 파일을 metadata만 바꾸어 재사용하지 않는다.

Common policy: reference-only S=max abs, B=.01S, near-zero error<=B, 일반 relative<=.05,
family RMS/S<=.01, S=0 exact-zero다. 다른 quantities/units/frame을 합쳐 scale을 바꾸지 않는다.
Frequency 원본 quantity/units/mode/step binding/hash 확인과 실제 비교를 수행했다.
최저10개 중7개 singleton이1% RMS 기준을 초과해 기능 검증은 완료 대기다.
상세 판정은 [최종 고유치 비교](verification.md#2026-10-11-제공된-고유치-원본의-최종-비교)에 있다.
결과를 생성·추정하거나 FESA 결과를 reference로 사용하지 않는다. 원본 부재 시에는 미실행이다.

Dynamic V/A/reaction/energy의 외부 자료는 없어 independent physical/temporal 검증이 필수다.
현재 inventory/convention 확인은 parser 실행·FESA 수치 결과 비교·기능 검증 PASS가 아니다.