FESADev/docs/shell-transient-heat-transfer/README.md

# Shell transient heat transfer

## 범위와 현재 상태

DS4 4절점 shell의 5개 두께 온도점을 사용하는 단일 uncoupled transient heat transfer다.
Q4×two-P2 요소의 K/C, Backward Euler, 온도·24개 Fourier flux trace·열저장 포함 반력,
입력·CLI·atomic HDF5를 구현했다. 당시 추가139개 검사는 모두 PASS이고 전체617개는
614 PASS·기존 HHT2 FAIL·1 SKIP(native8)이었다. 이 문서 정리에서는 build/test를 재실행하지 않았다.
새 필수 reference 모델·NT11 CSV가 준비 중이므로 외부 검증 완료나 전체 green 상태가 아니다.

## 채택 방법과 물리 의미

[정식화](formulation.md)가 geometry·보간·행렬·시간격자·판정의 상세 원본이다.
한 node의 source DOF11..15는 zeta=[-1,-.5,0,.5,1]이며 11/13/15가 bottom/mid/top이다.
요소는 node-major20 DOF로 면내 Q4와 두 구간 C0 P2 두께 보간을 결합한다. 다섯 독립2D 판이
아니며 두께 미분으로 station 사이를 결합한다. Midsurface metric·법선의 thin-shell
product-domain이고 thickness offset의 곡률 보정은 생략한다. Fold·두께 단차는 같은 normalized
station을 공유하는 이상화이며 실제3D 접합부 전도와 동등하지 않다.

Consistent capacity를 사용하고 lumping·인공 확산·음수 온도 clamp는 하지 않는다. 면내3×3
Gauss와 정확 P2 thickness Z0/Z1로 `C=rho*c*(h/2)*(M⊗Z0)`,
`K=k*((h/2)*(S⊗Z0)+(2/h)*(M⊗Z1))`를 만든다. 별도9×2×3=54 직접 적분점은 검산 위치이며
아래24 flux trace와 다르다. 퇴화·뒤집힘·self-crossing·불일치 side는 실패하고 |detJ|로 보정하지 않는다.

BE는 `A=C/delta+K`, `b=Q+C*Told/delta`다. Free RHS에는
`C_fc*Told_c/delta-A_fc*g_new`가 포함된다. Raw 초기 온도를 t=0에 보존하고 첫 양의 시점부터
지정온도를 부과한다. 첫 BC jump를 초기 projection으로 없애지 않는다. 일정 계수·delta에서
A_ff factorization을 재사용하며 실제 마지막 간격이 짧을 때만 재분해한다. n*dt로 생성한
시간격자는 마지막을 입력 T_end로 저장한다. dt>T_end이면 한 증분이다. 단열 K의 상수 null은
양의 C가 있는 transient A의 singularity를 뜻하지 않는다.

## 공개 입력과 제외 범위

기존 Part/identity Instance·node/set subset과 DS4, SHELL SECTION의 상수 양의 두께,
CONDUCTIVITY/DENSITY/SPECIFIC HEAT의 상수 양의 k/rho/c를 사용한다.
`*INITIAL CONDITIONS, TYPE=TEMPERATURE`의 signed finite T는 target node/Nset의5점에
동일 적용하고 미지정은0이다. 공개 BOUNDARY와 CFLUX는 DOF11/15만 지원한다.
CFLUX의 signed P는 모델로 들어오는 power이며 면적·두께를 곱하지 않는다. Source row 순서로
중복 하중을 더하고 constrained 입력도 full Q에 남긴다. 자연 경계는 단열이다.

Model/step BC 각각의 동일 target 충돌을 검사한 뒤 step 값이 model 값을 덮어쓴다.
동일 값 중복은 허용하고 다른 값은 오류다. 생략 BC 값은0이다. 단일 `*HEAT TRANSFER`의
END 생략 또는 PERIOD와 dt,T_end를 지원한다. 시간변화/amplitude, 내부 station 직접 BC/CFLUX,
edge 열입력, 열-구조 연성, composite, 온도의존 물성, 절점별 두께와 사용자 station 수는 제외한다.
[공통 solver 요약](../solver-core/README.md)에 CLI·source identity·lease·공통 tolerance가 있다.
사용자 일관 단위를 쓰며 SI를 추정하지 않는다.

## 복구와 HDF5 계약

Flux는 같은 보간의 직접 미분 `q_global=-k*B*T_e`이며 power/area다.
면내2×2 Gauss 네 위치 × 두께 trace `[-1+,-.5,0-,0+,.5,1-]`의24 위치를 구별한다.
C0 중앙면의 양쪽 두께 도함수를 평균하지 않는다. Local frame R=[e1,e2,n]의 열은 global
축 성분이며 local flux=R^T*q_global로 후처리한다. Bottom 외향 법선은 -n, top은+n이다.

반력은 `r=C*(Tnew-Told)/delta+K*Tnew-Q`의 constrained projection이다. 양수는 모델에
추가 공급되는 열이며 전도 flux의 절점 평균과 다르다. Free residual·열에너지는 내부 검증량이고
필수 공개 dataset을 임의로 추가하지 않는다.

Schema version U64=1, feature_id=shell-transient-heat-transfer,
analysis_procedure=uncoupled-transient-heat-transfer,
internal_formulation=FESA-Q4-P2x2-thermal-shell,
integration_rule=surface-3x3-gauss; thickness-exact-P2x2,
time_integration=backward-euler다. Metadata에는 source_step_name·source_input_identity·
nominal_time_increment·time_period를 기록한다. 모든 숫자는 explicit little-endian F64/U64/U8/I8,
문자열은 UTF-8이며 mandatory finite·shape·identity를 검사한다. Compound padding은 계약이 아니다.

| 경로 | Shape·mapping |
| --- | --- |
| /model/nodes, elements, thermal_materials, shell_sections | Source identity/연결·k/rho/c·두께와 provenance |
| /model/thermal_node_ids, thermal_element_ids | U64[N], U64[E]; 활성 row의 stable model ID |
| /model/temperature_dofs, temperature_zeta | U64[5]=11..15, F64[5]=[-1,-.5,0,.5,1] |
| /model/thermal_constraint_mask, thermal_reaction_dofs | U8[N,5], compound[P]=(internal_node_id,source_dof); node/station 순서, P=0도 유지 |
| /model/thermal_flux_inplane_coordinates, thermal_flux_zeta, thermal_flux_trace_side | [4,2], [6], I8[6]=[1,0,-1,1,0,-1] |
| /model/thermal_flux_local_frames | F64[E,4,3,3]; global component × local axis |
| /steps/Step-1/accepted_frames | frame_index/increment_index U64, time/time_increment F64, is_initial U8; raw initial 포함 |
| frames/n/nodal/temperature | F64[N,5], NT11..NT15; initial과 completed 모두 존재 |
| frames/n/nodal/reaction_heat_rate | F64[P], RFL, power, positive into-model; completed만 존재 |
| frames/n/element/heat_flux | F64[E,4,6,3], QX/QY/QZ global; completed만 존재 |

위 frames 상대 경로의 부모는 /steps/Step-1이다. 실제 source step 이름은 metadata에서
구별한다. Frame0은 time=delta=0,is_initial=1이며 flux/reaction dataset이 **없다**.
이를 NaN·계산된0으로 채우지 않는다. 완료 frame은 실제 양의 delta를 저장한다.
Diagnostics는 source/severity/code/message의 기존 convention을 보존한다.

## 코드 흐름과 수명

[Abaqus step mapper](../../src/fesa/io/abaqus/step_definition_mapper.cpp)가 semantic Domain을
만들고 [ThermalShell::Create/Recover](../../src/fesa/elements/thermal_shell.cpp)와
[thermal geometry](../../src/fesa/elements/thermal_shell_geometry.cpp)가 local K/C·flux를 제공한다.
열 kernel은 구조 displacement Element::Recover를 전용하지 않는다.
[AssembleThermal](../../src/fesa/assembly/thermal_assembler.cpp)은 DofManager scatter와 stable
source 순서로 K/C/Q를 조립한다. C를 structural mass에 저장하지 않는다.

[TransientHeatProcedureExecutor::Execute](../../src/fesa/analysis/transient_heat_procedure.cpp)는
[ThermalTimeGrid](../../src/fesa/analysis/thermal_time_grid.cpp),
[BE algebra와 residual certificates](../../src/fesa/analysis/thermal_transient_algebra.cpp)를 사용해
solve→full temperature→residual/flux/finite/수지 검사→commit을 수행한다. 호출자 소유 solver와
parallel adapter는 Execute보다 오래 살아야 하고 Domain은 non-owning model보다 오래 살아야 한다.
[ThermalAnalysisState::Create/MakeCompletedFrame/CommitAcceptedFrame](../../include/fesa/analysis/thermal_analysis_state.h)는
inventory와 accepted history를 소유한다. Create 뒤 Domain/model/assembly 참조를 남기지 않아
state가 이들보다 오래 살 수 있다. 거부된 candidate는 기존 frames를 바꾸지 않는다.

[Thermal writer](../../src/fesa/io/hdf5/thermal_hdf5_results_writer.cpp)와
[self-check](../../src/fesa/io/hdf5/thermal_hdf5_self_check.cpp)는 candidate close 뒤 재개방해
schema/identity/초기값·완료 BC·frame completeness를 확인한다. Reader close까지 성공한 뒤
final을 교체한다. Write/candidate close/self-check/reader close/finalize 실패에서 기존 final을 보존한다.

## 검증 의미와 재사용 교훈

Residual backward error는 `D_f=||A_ff||inf*||T_f||inf+||b_f||inf`의 reduced-system scale을
사용한다. 큰 constrained 값의 full BE scale로 이를 바꾸면 RHS 상쇄 오류를 숨길 수 있다.
Direct full residual과 독립 signed construction의 enclosure 교집합으로 같은 stored-data 잔차를
인증하며 빈 교집합은 실패다. D_f=0은 exact-zero 증명이 필요하고 interval이0을 포함한다는
이유만으로 통과하지 않는다. 수지 bound에 방정식 구성 오차를 tolerance처럼 더하지 않는다.

독립2-DOF C=[[2,1],[1,2]],K=[[1,-1],[-1,1]],delta=.5,old=0,g=1 fixture의
첫 free=-.2·다음=.04·reaction4.8/1.44가 초기 용량 결합을 검출한다. 당시 시간차수
.981712..997660, 온도 공간차수1.996702..2.006577, gradient .997220..999826을 확인했다.
Slab의24해석·147456증분과 독립 oracle는 고정5점 두께 오차 plateau와 초기 침투 깊이를
구분했다. Slab energy/reaction oracle index 오류는 수정 후 focused 전체를 다시 실행했다.

기존 reference Step-1/t37/DOF11 NT11은676DS4/729nodes다. CSV에 instance 열이 없어
hash-checked 입력의 유일 instance와 결합하며 node source identity로 bottom 값을 비교한다.
원본87/729행 FAIL, RMS/S=.049674084615673214, max abs≈245.262946500919로
공통 .01 RMS 기준을 넘었다. 독립 정식화 oracle도 같은 불일치를 보였다. 사용자 선택으로
원 정식화·tolerance를 유지하고 이 비교만 diagnostic/nonblocking으로 분류했다.
진단 분류 테스트 PASS를 외부 수치 PASS로 바꾸지 않는다. 음수 NT11도 clamp하지 않는다.
새 모델/CSV의 별도 identity·시점·hash를 확정한 필수 비교가 남아 있다.

초기 두께 경계층의 local flux/reaction, 일반 curved mesh의 전역 응답·점열원 수렴·실제3D
접합부는 검증 한계다. 단일 NT11 시점으로 다른 station·flux·반력·전체 시간 정확도를
검증했다고 주장하지 않는다.
Dev 통합 승인은 새 필수 reference 통과 승인이 아니다.

## 통합된 kernel 경계

[ThermalElement/Ds4ThermalAdapter](../../include/fesa/elements/element_capabilities.h)는 immutable
DS4 kernel을 빌리고 DOF11–15 layout·K/C와 interval·복구를 typed로 제공한다.
Kernel의 주소·수명은 adapter보다 안정적이어야 한다. Thermal state·잔차 인증·accepted history와
writer 실패 경계는 그대로 procedure/state/writer에 남는다. 전체 검증 대상에 과도 열해석도 포함하며,
새 필수 reference 미확보와 기존 NT11 diagnostic 불일치를 통과로 바꾸지 않는다.