# Hex8 입출력과 내부 전달 계약

권위 있는 field/enum/shape·지원 입력·진단/실패 의미는 [PRD](PRD.md)의
FEM-REQ-HEX8-008–011,016–020,022–023다. Public CLI·path/lease/exit는
[공통 계약](../contracts.md), tolerance는 [TOLERANCE](../TOLERANCE.md)를 따른다.
이 문서는 그 계약을 구현 경계까지 상세화한다. Physics 선택은 [ADR](ADR.md)를 따른다.

## Source 입력과 실패 경계

기존 single Part/identity Instance/set/target subset을 재사용하고 source spelling/location/
instance/label과 internal index를 구분한다. C3D8의8 distinct nodes와 SOLID SECTION의 elset/
material 연결, constant E/nu 및 procedure별 density capability를 검증한다. Blank section row는
허용하되 thickness/material orientation·다른 solid type를 default로 흡수하지 않는다.

실제 BC/CLOAD 성분은 DOF1–3이다. 사용자 승인된 호환 예외로 supported displacement BC의
exact-zero DOF4–6(생략0 포함)만 source/location warning/no-op으로 처리한다. Mixed1–6 range는
1–3을 적용하고4–6만 경고하며 회전 equation/state를 만들지 않는다. 비영 회전 BC와 모든
회전 CLOAD는 거부하고 unsupported BC 옵션·DOF범위 밖 의미를 이 예외로 수용하지 않는다.
Static 비영 prescribed는 absolute target이며 nonlinear의
factor가 force/target 모두에 적용된다. Frequency는 homogeneous BC, dynamic은 exact-zero BC와
initial q/v0만 허용한다. Unused node·mixed element·alias element·unknown set/material/source
identity·bad density/geometry·unsupported meaningful keyword는 model/input failure다.

TABULAR amplitude는 canonical name uniqueness를 검증하며 raw name/location을 보존한다.
TIME=STEP TIME/VALUE=RELATIVE/DEFINITION=TABULAR의 생략 default와 명시 동일 값만 지원한다.
One/many rows의 pair를 flatten해 finite time>=0/strict increasing/value finite를 검사한다.
Knot 원 값·linear interpolation·end hold를 사용한다. Curve 없는 CLOAD는 initial0+부터 constant다.
다른 curve를 사용하는 load block은 미리 하나의 base vector로 합치지 않는다. Static/BC amplitude,
TOTAL TIME/SMOOTH STEP/smoothing option을 fail-closed로 거부한다.

STATIC DIRECT는 h/T/INC의 fixed schedule을 지원하며 nonlinear load factor는 n*h/T다.
기존 일반 STATIC fixed-factor subset도 유지한다. DYNAMIC DIRECT h/T/INC는 integer n과
binary64 n*h로 대응한다. FREQUENCY의 N은 source mode request이며 LANCZOS/SIM option 표기와
실제 generalized MKL FEAST를 metadata/diagnostic에서 구분한다. Provided PRESELECT/무해한
output/restart 요청은 명시된 no-op이고 required 공식 결과를 삭제하는 selector가 아니다.

## T2/T3와 이후 절차의 typed 경계

다음 class/method 이름은 구현 계획용 초기 interface다. 같은 행동/배열 크기·소유권을 유지하는
repository-conforming 이름 조정은 허용하며 physics/schema 수정은 아니다.

- `Hex8Element`는 기존 Element interface의 linear `ComputeStiffness`와 `Recover`를 제공한다.
  Create 입력은 internal element index, source/local layout, 기준 좌표8×3, 기존 isotropic
  elastic material와 optional density다. 생성에 아직 없는 Solid Domain/section 타입을 요구하지
  않아 T2/T3를 분리한다. Layout은8 source-order nodes×UX/UY/UZ다.
- Explicit `EvaluateLinear(u)`/`EvaluateNonlinear(u)`는 immutable element의 local u[24]를 받아
  f[24], Kmat/Kgeo/Kt[24,24], strain energy와8 typed integration-point rows를 반환한다.
  Linear은 material=K0/geo=0, nonlinear은 같은 trial의 energy 미분이다. `ComputeMass()`는
  local consistent24×24 Matrix contribution이며 absent density이면 실패한다.
- Typed Solid point row는 internal element index, point ID1–8, natural/reference coordinate3,
  Cauchy stress6·infinitesimal/Green tensor strain6를 가진다. Identity/상수 coordinates를 trial마다
  다른 source row로 만들지 않는다. Generic recovery variant의 Solid payload는 별도 type이다.
- Semantic Domain은 Solid element/section/material/density·amplitude 정의를 소유한다.
  DOF profile은 `kSolidStructural`에 해당하는3-component 구조이며 `FullDof`, free/constrained,
  generic `ElementScatter`, sparse pattern의 기존 공개 의미를 유지한다. 동작별 node component
  count를 조회해6으로 고정된 loops를 Solid branch에서 제거한다.
- Matrix assembly는 local layout+24×24 contribution의 stable ordered reduction이다. Mass/stiffness
  storage는 같은 full-space pattern이며 free restriction은 실제 constraint mask를 사용한다.
  Runtime factory 연결은 Domain material/coords를 Hex8 Create에 전달하는 단일 owner가 수행한다.
- Static/eigen/dynamic executor는 procedure별 typed outcome/state를 반환한다. Accepted frames는
  source identity·3N physical arrays·8점 result·physical scalars와 validation evidence를 소유한다.
  Eigen은 modes/vector/all-pair check/Gram을 소유하고 static displacement frame으로 위장하지 않는다.
- Trial은 accepted history의 독립 값이며 invalid geometry/finite/recovery/iteration failure는
  commit하지 않는다. Static force/correction·dynamic force/rate channels의 raw norm/scale/branch/
  unit/pass와 increment/iteration을 기록한다. 필요한 failure evidence는 Status/로그까지 전달한다.
  Shared Shell4-channel logger에 dummy rotation/moment convergence를 만들지 않는다.
- Central prepared outcome·writer/CLI 연결은 T7의 한 owner다. Vendor objects는 private adapter에
  두고 공개 Matrix/Vector/Result/Status 경계를 유지한다.

## HDF5 metadata와 결과 attribute

Model/accepted/eigen compound field 집합과 순서·dtype는 PRD017 그대로다. New Solid schema1과
procedure/element/integration/mass attributes로 식별하고 기존 file contract는 유지한다.
Required strings는 UTF-8, numeric은 explicit little-endian U64/U8/F64다.
Metadata의 추가 공개 의미는 다음과 같다.

| attribute | 값/의미 |
| --- | --- |
| `source_input_identity` | 실제 읽은 원본 byte identity; 기존 공통 hashing 의미 |
| `source_step_name` | 입력 raw step 이름; storage key Step-1과 별도 |
| `unit_system_label` | `user-consistent-unspecified` |
| `coordinate_convention` | `global-cartesian; reference-strain; current-cauchy-stress` |
| `component_order` | `node-major; UX,UY,UZ` |

Physical dataset은 `component_names`와 `unit_dimensions`를 UTF-8 string으로 기록한다.
각 frame dataset에는 `frame_index:U64`, `increment_index:U64` 및 해당 `time:F64` 또는
`load_factor:F64`, `coordinate_system=global-cartesian`, 필요한 `location`을 붙인다.
Result array의 leading node/element inventory와 component list를 self-check한다.

| quantity | component_names / unit_dimensions / 필요한 의미 |
| --- | --- |
| displacement | `U1,U2,U3` / `length` |
| reaction/residual | `RF1,RF2,RF3` 또는 `R1,R2,R3` / `force`; reaction은 constrained projection |
| stress | `S11,S22,S33,S12,S13,S23` / `force/length^2`; `stress_measure=cauchy`, `location=integration-point` |
| strain | `E11,E22,E33,E12,E13,E23` / `dimensionless`; `strain_measure=infinitesimal` 또는 `green-lagrange`, `shear_convention=tensor` |
| velocity | `V1,V2,V3` / `length/time` |
| physical/algorithmic acceleration | `A1,A2,A3` / `length/time^2`; 각각 `acceleration_kind=physical`/`algorithmic` |
| strain/kinetic energy, work, balance error | `scalar` / `force*length`; 각 계산 정의를 별도 `definition` attribute로 기록 |
| linear/angular momentum | `P1,P2,P3` 또는 `L1,L2,L3` / `mass*length/time` 또는 `mass*length^2/time`; angular origin은 global0 |
| lambda/frequency | `eigenvalue` 또는 `frequency` / `1/time^2` 또는 `1/time`; 서로 다른 eigen table field |
| mode vectors | `UX,UY,UZ` / `mass-normalized`; `normalization=phi^T*M*phi=1` |

Strain-energy definition은 linear `0.5*u^T*K0*u`, nonlinear `sum(W*detJ0)`다.
Kinetic은 `0.5*v^T*M*v`, work는 `sum(0.5*(F_old+F_new)*delta_u)`이며 initial0이다.
Balance error는 `T+U-T0-U0-Wext`이고 HHT numerical dissipation을0으로 보정하지 않는다.
Constrained mask/prescribed 의미·point ordering은 model inventory에서 확인한다.

## 출력 candidate와 self-check

Writer는 완결된 accepted state만 받는다. Dtype/정확한 compound member/order·shape·source
IDs·finite·flags·frame/increment/time/factor·physical3 component·eigen norm/검증량을 확인한다.
Write 후 readback 값을 candidate와 대조하고 close까지 성공한 뒤 atomic replace한다.
잘못된 payload, 임시 write/readback/close/replace 실패에서 기존 final HDF5를 보존한다.
File 존재와 이번 실행 성공은 별개이며 CLI native exit와 stored source identity를 확인한다.

## Comparison projection

Quantity/key/family와 원본 준비 상태는 [reference-model](reference-model.md)에 있다.
Static은 final factor-one source increment를 FESA final accepted frame에 대응한다. Dynamic은
integer increment0..N과 decimal source time을 n*h에 대응한다. RF는 constrained projection,
S는 element/IntPt와6 global Cauchy component다. 좌표는 보조검사이고 ID 추정에 쓰지 않는다.
Modal Value는 원본이 제공되면 quantity/units/mode/step을 확인하며 최저10 eigenvalues를
singleton families로 비교한다. Missing 원본·nonfinite/identity/completeness 오류는 미실행/실패다.