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

Hex8 입출력과 내부 전달 계약

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

Source 입력과 실패 경계

Solid HHT의 승인된 high+low 계산은 내부 전체 물리 상태를 accepted history와 다음 trial에 유지한다. 공식 HDF5의 기존 field·shape·Float64 dtype은 변경하지 않으며 값은 전체 물리량의 round-to-Float64 observable이다. Self-check는 직렬화가 그 반올림과 일치하는지 확인한다. 내부 gate PASS를 rounded 배열 자체의 동일 gate PASS로 해석하지 않는다. 로그에 내부 산술을 명시하고 직렬화 비유한 값· overflow는 실패로 처리해 기존 final을 보존한다. Restart는 지원하지 않는다.

기존 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는 nh/T다. 기존 일반 STATIC fixed-factor subset도 유지한다. DYNAMIC DIRECT h/T/INC는 integer n과 binary64 nh로 대응한다. 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 정의 대신 이 local 입력에 의존한다. 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은 새 체적 평균 energy의 zero Hessian material=K0/geo=0, nonlinear은 같은 trial의 체적 평균 Green energy 미분이다. ComputeMass()는 full reference consistent24×24 matrix의 각 row sum을 대각에 둔 local lumped24×24 Matrix contribution이며 absent density이면 실패한다. Row sum은 BC reduction 전에 전체24 성분으로 계산하고 이후 실제 constraint mask로 restriction한다. Warped 요소에서 동일한 rho*V/8을 모든 절점에 대신 배정하지 않는다. Eigen/HHT는 같은 reference mass를 사용하며 시간·변형에 따라 재계산하는 current mass가 아니다.
• Typed Solid point row는 internal element index, point ID1–8, natural/reference coordinate3, Cauchy stress6·infinitesimal/Green tensor strain6를 가진다. Identity/상수 coordinates를 trial마다 다른 source row로 만들지 않는다. 저장 strain은 실제 kinematics의 strain이며 평균된 대체 strain이 아니다. 응력은 같은 point의 deviatoric strain과 요소 전체의 reference-volume 평균 trace에 의존한다. 비선형은 PK2를 실제 F/J로 Cauchy 변환하며 평균 Cauchy pressure를 가정하지 않는다. 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
mass_formulation	lumped-reference; full reference element matrix의 row-sum diagonal mass

2026-10-11 사용자 승인으로 질량의 공개 의미와 mass_formulation 값을 consistent-reference에서 lumped-reference로 변경한다. 입력에 질량 선택 parameter를 추가하지 않으며 기존 CLI, schema_version=1, dataset field/shape/dtype, high+low 내부 상태의 round-to-Float64 규칙은 유지한다. 과거 consistent 결과는 당시 evidence로 보존하며 현재 reader/self-check/comparator는 mass identity mismatch를 tolerance 적용 전에 거부한다. Metadata를 바꾸어 과거 수치 결과를 새 정책의 결과로 표시하지 않는다. 이 변경만으로 새 정책의 verification PASS를 선언하지 않으며 production readback와 원본 비교는 새 실행 evidence가 필요하다.

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)다. K0는 승인된 mean-trace energy의 zero Hessian이고 nonlinear Wg는 mu*dev(Eg):dev(Eg)+0.5*kappa*theta_bar^2다. 같은 theta_bar를8점의 reference 가중치로 계산하므로 그 합은 요소 체적 항 0.5*kappa*V*theta_bar^2와 같다. 기존 attribute 문자열과 field/schema/dtype은 유지하며 새 energy 의미는 HEX8-ADR-009 및 정식화를 따른다. Kinetic은 동일한 reference lumped M으로 계산한 0.5*v^T*M*v이고, eigen의 mass normalization과 HHT의 관성력·반력·physical momentum에도 같은 M을 사용한다. 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에 있다. 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는 제공된 hexa_freq.txt의 고유치 λ(1/time^2)를 최저10개 mode별 singleton families로 직접 비교한다. Freq (cycles/time)는 보조 열이며 변환하지 않는다. TXT에 없는 step field는 고정 case와 승인 입력의 sole Step-1에 한정해 대응한다. 형식·hash·mode/finite 검사는 원본 mapping을 따른다. Missing 원본은 미실행, nonfinite/identity/completeness 오류는 실패다.