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

# Shell Transient Heat Transfer 요구사항과 승인 계약

- Feature ID: `shell-transient-heat-transfer`
- Owner: 메인 assistant
- 상태: 사용자 승인 계약; 구현·검증 진행 중
- 승인 근거: ready 인터뷰의 명시 선택, 최종 “네 승인합니다”, 후속 `dryforge:go` 실행 요청.

기준: [프로젝트 지침](../../AGENTS.md), [프로젝트 PRD](../PRD.md),
[공통 ADR](../ADR.md#adr-028), [ARCHITECTURE](../ARCHITECTURE.md),
[CODINGSTYLE](../CODINGSTYLE.md), [TOLERANCE](../TOLERANCE.md).
지역 지침은 [FEATURED_AGENTS](FEATURED_AGENTS.md), 결정 근거는 [ADR](ADR.md),
수식은 [formulation](formulation.md), 구현 순서는 [design-plan](design-plan.md),
독립 수치 판정은 [numerical-review](numerical-review.md)를 따른다.

개인 연구용 솔버가 일차 목적이며 외부 배포와 양방향 열–구조 연성은 장기 목표다.
현재 목표는 3차원 공간의 4절점 shell에 대한 단일 step uncoupled transient heat transfer다.
입력 의미, 열 방정식, 시간 적분, 결과 복구, HDF5 저장과 독립 검증을 함께 구현한다.
채택 승인은 정확도 통과 evidence가 아니다. 아래는 승인된 실행 명세를 영속 문서에 반영한 계약이다.
초기 제안 중 edge 입력 지원과 정수 배수 종료 제한은 아래 계약으로 대체한다.

## 요구사항과 경계

`FEM-REQ-SHELL-THERMAL-`를 아래 표의 ID prefix로 사용한다. 기존 ID를 재번호화하지 않는다.

| ID | 구현할 동작 |
| --- | --- |
| 001 | 구조해석과 분리된 과도 열전달 procedure |
| 002 | 3차원 공간의 DS4 4절점 shell; 평판·유효한 warped patch·곡면 mesh·접힌 판 |
| 003 | 절점마다 두께 온도점 5개, 면내와 두께 방향 전도 |
| 004 | 단면 전체가 같은 재료인 centered homogeneous shell |
| 005 | 상수 등방성 양의 유한 열전도율 k, 밀도 rho, 비열 c |
| 006 | 요소 집합별 서로 다른 재료 |
| 007 | 요소 집합별 양의 유한 두께 h; 요소 내부에서는 일정 |
| 008 | 절점/절점 집합의 초기 온도; 동일 절점의 5점에는 같은 값 |
| 009 | 아랫면·윗면의 독립적인 지정 온도 |
| 010 | 아랫면·윗면의 독립적인 절점 집중 열입력 |
| 011 | **이번 구현에서 연기:** 모서리 분포 열입력. Kernel·keyword·공개 테스트 지원을 추가하지 않음 |
| 012 | 지정 온도와 열입력은 step 중 일정 |
| 013 | 사용자 지정 총 시간과 기본 시간 간격; 마지막 증분만 필요 시 단축 |
| 014 | 온도·요소 전역 열유속·지정 온도점의 반력 열률 |
| 015 | 초기 온도와 모든 완료 증분을 공식 HDF5에 저장 |
| 016 | 원본 reference Step-1, t=37, NT11의 진단 외부 비교와 새 reference 모델의 필수 비교 |
| 017 | 전체 온도·flux·반력에 대한 해석해·수지·시간 및 공간 수렴 검증 |
| 018 | 하나의 transient step만 지원 |

추가 상세 계약은 이 문서의 `STH-C01`–`STH-C08`이다. 위 요구사항의 구체화이며 별도 기능을
추가하지 않는다. 제외: 열–구조 연성, 삼각형, 적층, 이방성·온도 의존 물성, 잠열,
대류·복사·내부 발열, 윗면/아랫면 분포 열유속, 모서리 분포 입력, 두께 비균일 초기 온도,
내부 온도점 직접 BC/CFLUX, 절점별 두께, 사용자 선택 온도점 수, 시간 이력·amplitude,
적응 시간 간격, 여러 step, restart, Abaqus 내부 정식화 동등성.

## STH-C01 — 모델, geometry와 자유도

### Source 의미

- Shell geometry 절점은 midsurface에 있다. Source DOF `[11,12,13,14,15]`는 각각
  `zeta=[-1,-1/2,0,1/2,1]`이며 11은 bottom, 13은 midsurface, 15는 top이다.
- 요소 절점 순서는 자연좌표 `(-1,-1),(1,-1),(1,1),(-1,1)`이다. 요소 로컬 DOF는
  node-major `p=5*(i-1)+a`, i=1..4, a=1..5의 20개다.
- Source instance/label, Domain index, full DOF, equation index는 서로 다른 identity다.
  집합을 전개해도 source row와 target identity를 진단까지 보존한다.
- 모든 열 방정식은 활성 DS4에 연결된 온도 DOF에 대해 구성한다. 비활성/미연결 절점을
  열 방정식에 넣어 0 용량 행을 만들지 않는다. 그런 절점을 명시적으로 대상으로 하는 열
  initial/BC/load는 유효한 열 target이 아니므로 모델 오류다. 일반 source model의 미사용
  절점은 보존할 수 있으며 결과의 활성 절점 mapping으로 구분한다.
- 한 열해석 모델에 structural B33/S4/S4R 또는 coupled 요소를 혼합하지 않는다.
  각 DS4에는 정확히 하나의 shell section과 thermal material이 연결되어야 한다.
  Section 중복 지정은 값이 같아도 오류이며, set 내부의 동일 member는 한 번만 전개한다.

### Geometry와 접속

`r=sum(N_i*x_i)`, `a1=r_,xi`, `a2=r_,eta`, `g=A^T A`, `A=[a1,a2]`,
`Js=|a1 cross a2|`, `n=(a1 cross a2)/Js`를 평가점별로 사용한다.
Warped 요소를 중심 평면에 투영하지 않는다.

`grad_s(N_i)=A*g^-1*[N_i,xi,N_i,eta]^T`,
`grad_*T=grad_s(T)+n*(2/h)*T_,zeta`, `dV*=Js*(h/2)*dxi*deta*dzeta`다.
실제 offset surface의 곡률에 따른 metric·면적 변화는 포함하지 않는다.
이는 두께 방향 등온 가정이 아니다. 얇은 shell product-domain 모델의 한계를 문서화하며,
큰 h/곡률 또는 초기 두께 경계층에 대한 정량 정확도를 검증 없이 보장하지 않는다.

공유 source node의 같은 normalized zeta 온도는 공유한다. 서로 다른 두께에서도 같으며,
실제 물리 z 좌표 일치, 접촉 열저항, 접합부의 유한 부피·추가 용량을 의미하지 않는다.
접힌 판·두께 단차의 국소 3D 전도장은 이번 모델의 해상 대상이 아니다.

Topology는 방향이 일관된 manifold shell 표면이다. 하나의 edge에 최대 두 요소가 접속하고
공유 edge를 따라 절점 순서는 반대여야 한다. 불일치는 오류이며 자동으로 뒤집지 않는다.
T자 분기 edge, vertex-only 접합과 nonmanifold vertex fan은 거부한다.
분리된 여러 shell 영역은 허용하며 좌표만 같은 서로 다른 source node를 자동 병합하지 않는다.
서로 다른 instance도 명시적인 공유 source identity가 없으면 연결되지 않는다.

유한 좌표, 서로 다른 4절점, 양의 Js와 비특이 metric, 자기 교차 없는 patch를 요구한다.
적분점 몇 곳의 검사만으로 전체 patch 유효성을 증명했다고 하지 않는다.
Roundoff를 고려한 전체 patch의 유효성 판정과 geometry 오차 분리는 STH-C07의 선행
수치 계약 작업에서 고정한다. 양의 작은 Jacobian을 clamp하거나 구조 shell의 drilling/
director/두께 비율 제한을 검토 없이 전용하지 않는다.

## STH-C02 — 공개 입력, 충돌과 부가 keyword

공통 ASCII·대소문자·source ordering·single physical file·part/identity-instance·set 규칙은
[공통 입력 계약](../contracts.md)의 기존 계약을 따른다. 열 입력의 추가 subset은 다음과 같다.

| 입력 | 허용 형식과 의미 |
| --- | --- |
| `*ELEMENT, TYPE=DS4` | 4절점; 기존 선택적 ELSET 및 topology 구문 사용 |
| `*SHELL SECTION, ELSET=..., MATERIAL=...` | 단일 row `h` 또는 `h,5`; 온도점 수 생략은 5. 명시 값은 5만 허용; offset/composite/nodal thickness 제외 |
| `*CONDUCTIVITY` | parameter 없는 상수 k 한 row; 선택적 마지막 빈 field 하나 허용 |
| `*DENSITY` | 기존 상수 rho 구문; 양의 유한 값 |
| `*SPECIFIC HEAT` | parameter 없는 상수 c 한 row; 선택적 마지막 빈 field 하나 허용 |
| `*INITIAL CONDITIONS, TYPE=TEMPERATURE` | model-level, `node-or-nset,T`; 각 target의 5점에 같은 유한 T |
| `*BOUNDARY` | model 또는 step, `target,dof,dof[,T]`; dof는 11 또는 15, T 생략은 0 |
| `*CFLUX` | step-level, parameter 없이 `target,dof,P`; dof 11 또는 15, 유한한 signed P |
| `*STEP` | 기존 NAME, INC; NLGEOM은 생략 또는 NO, PERTURBATION 제외 |
| `*HEAT TRANSFER` | END 생략 또는 PERIOD; 한 row `dt,T_end` 뒤 최대 3개의 빈 field 허용 |
| `*END STEP` | 단일 step 종료 |

추가 material temperature/field columns, ANISOTROPIC/ORTHOTROPIC, STEADY STATE,
DELTMX, 시간증분 최소/최대의 명시 숫자, OP/AMPLITUDE 등 미지원 option은 거부한다.
`*BOUNDARY`의 11..15 범위 표기는 내부 station을 포함하므로 거부한다.
물성·두께·시간은 양의 유한 값이며 온도는 signed finite scalar다. 섭씨/절대온도 단위를
숫자로 추정하지 않는다. Reference 파일의 상수 값을 변환하지 않는다.

미지정 초기 온도는 0이다. 같은 초기 선언에서 집합이 겹치면 동일 값은 허용하고 다른
값은 오류다. BC는 model 단계와 step 단계 각각에서 target을 완전히 전개하여 충돌을
확인한 뒤 step의 값이 동일 node/DOF에 대한 model 값을 덮어쓴다. 각 단계 안의 동일
값 중복은 허용하며 다른 값은 오류다. 이 override는 thermal에만 적용한다.

집중 입력은 source row 순서로 더한다. 양수 P는 모델 안으로 공급되는 열률이며 음수는
열 제거다. P에 h·면적·shape weight를 곱하지 않는다. 지정 온도와 겹치는 입력도 full Q에
유지하여 반력에 반영한다. 온도 또는 열입력이 지정되지 않은 외부 경계는 자연 단열이다.

Reference에 있는 다음 부가 구문만 열 procedure의 no-op으로 허용한다. Data row가
필요 없는 구문에 data를 추가하거나 미지원 option을 붙이면 오류다. 허용한 각 no-op
block에 source 위치를 갖는 warning을 하나씩 남기며 필수 결과를 줄이지 않는다.

- `*PREPRINT, ECHO=NO, MODEL=NO, HISTORY=NO, CONTACT=NO`.
- `*RESTART, WRITE, FREQUENCY=0`: restart 파일을 생성하지 않는다.
- `*OUTPUT, FIELD, VARIABLE=PRESELECT` 및 `*OUTPUT, HISTORY, FREQUENCY=0`.
  Child NODE/ELEMENT OUTPUT 및 그 밖의 output 설정은 제외한다.
- 하중이 참조하지 않는 assembly `*SURFACE, TYPE=ELEMENT, NAME=...`:
  기존 target 및 SPOS/SNEG facet 의미를 검증하고 보존하되 열하중으로 사용하지 않는다.
- Model-level `*PHYSICAL CONSTANTS, ABSOLUTE ZERO=<finite>`:
  이번 상수 물성·비복사 모델에서 온도 변환이나 에너지 영점 이동에 쓰지 않는다.

Unknown/unsupported keyword를 일반적으로 무시하는 fallback은 없다.

## STH-C03 — 행렬과 시간 적분

두께는 `[-1,0]`, `[0,1]`의 C0 quadratic 구간 둘로 구성한다. 각 구간에서
`s=2*zeta+1` 또는 `s=2*zeta-1`로 두고
`l=[s(s-1)/2, 1-s*s, s(s+1)/2]`를 각각 station `(1,2,3)`과 `(3,4,5)`에 놓는다.
`dL/dzeta=2*dl/ds`이며 중립면의 온도는 하나지만 미분의 두 trace는 별도다.

`H_ia=N_i*L_a`, `B_ia=L_a*grad_s(N_i)+n*N_i*(2/h)*L_a,zeta`다.

```text
M_ij = integral_surface N_i N_j dA
S_ij = integral_surface grad_s(N_i) dot grad_s(N_j) dA
Z0_ab = integral_-1^1 L_a L_b dzeta
Z1_ab = integral_-1^1 L_a,zeta L_b,zeta dzeta
C_e = rho*c*(h/2) * (M tensor Z0)
K_e = k * [(h/2)*(S tensor Z0) + (2/h)*(M tensor Z1)]
Z0_segment = [[4,2,-1],[2,16,2],[-1,2,4]] / 30
Z1_segment = [[7,-8,1],[-8,16,-8],[1,-8,7]] / 3
```

각 segment의 3×3 행렬을 공유 station 3에 조립한다. 면내 production 적분은 3×3
Gauss, 두께는 위 exact Z다. 동일 보간의 직접 54점 적분과 교차 검산한다.
Affine 평판의 exact 면내 2×2 검산과 production 규칙을 혼동하지 않는다.
Structural 질량을 C로 재사용하지 않으며 lumping, reduced integration, hourglass,
인공 확산·온도 clamp를 추가하지 않는다. Consistent C는 급변 BC에서 undershoot를
만들 수 있으므로 온도 범위 초과만으로 성공/실패를 결정하지 않는다.

기본 dt>0, 총 시간 T_end>0에서 종료까지의 증분을 구성한다. 마지막 구간이 남으면 그
길이 delta로 단축한다. dt>T_end이면 delta=T_end인 한 증분이다. 적응 제어는 없다.
일반 시점은 누적 덧셈 대신 n*dt로 만들고 마지막 저장 시점은 입력 T_end다.
정수 배수의 부동소수점 표현 오차 때문에 거의 0인 가짜 증분을 만들지 않는다.
시간 비교의 roundoff bound는 입력·곱셈·나눗셈 연산을 근거로 STH-C07에서 고정한다.
정상 간격과 표현 오차 수준에서 같은 마지막 간격에는 같은 계수를 사용하며, 실제로
단축된 마지막 간격은 모든 방정식·반력·에너지에 동일한 delta를 사용한다.
시점이 유한하고 엄격히 증가해야 하며 표현할 수 없는 격자는 진단으로 거부한다.
INC는 기존 STEP 기본 100 또는 명시 양의 uint32다. 필요한 완료 증분 수가 INC를
넘으면 실행 전에 오류로 처리하며 중간 결과를 성공 결과로 저장하지 않는다.

각 증분의 Backward Euler 식은 다음과 같다.

```text
A = C/delta + K
A_ff*T_f_new = Q_f + C_ff*T_f_old/delta + C_fc*T_c_old/delta - A_fc*g_new
T_c_new = g_new
```

입력 초기 T_raw를 t=0에 보존하며 첫 old state로 그대로 쓴다. t=0에 g로 projection하지
않는다. 따라서 첫 증분의 `C_fc*(T_c_old-g_new)/delta`는 생략할 수 없다.
이 정책은 초기 불연속을 첫 유한 증분에 반영하며 순간 impulse를 해상한다는 뜻은 아니다.
동일 계수의 A_ff factorization은 재사용하고 마지막 delta가 바뀌면 다시 구성·분해한다.
무구속 단열 모델도 C가 양정치여서 transient A는 양정치다. 연결 component별 K의 상수
null mode를 과도계의 singular error로 오인하지 않는다. Generic 0×0 free partition은
solve 없이 처리하되 공개 입력은 내부 station을 구속하지 못하므로 all-constrained는
algebra fixture로만 검증한다.

## STH-C04 — 열유속, 반력과 수지

각 완료 온도장으로 `q_global=-k*B*T_e`를 직접 평가한다. 단위 차원은 power/area다.
`e1=a1/|a1|`, `e2=n cross e1`, `R=[e1,e2,n]`이고 후처리 local 성분은 `R^T*q_global`다.
Local q3는 bottom에서 top으로 흐를 때 양수다. Local 성분을 중복 필수 저장하지 않는다.

면내 점 순서는 `(-g,-g),(g,-g),(g,g),(-g,g)`, g=1/sqrt(3)이다.
각 점에서 두께 순서는 `(-1,+),(-1/2,interior),(0,-),(0,+),(1/2,interior),(1,-)`로
고정한다. 총 24개/요소다. 부호는 해당 두께 위치로 접근하는 쪽이며 바깥 법선 부호가 아니다.
중립면 양쪽, 재료 경계와 인접 요소의 값을 평균하지 않는다. Nodal smoothing/extrapolation을
공식 flux로 추가하지 않는다. Point source 부근의 mesh 독립적인 유한 flux를 보장하지 않는다.

```text
r = C*(T_new-T_old)/delta + K*T_new - Q
reaction = r의 constrained 성분           [power, 양수: 모델에 공급]
free residual = r의 free 성분             [내부 검증 evidence]
DeltaE = 1^T*C*(T_new-T_old)               [energy]
DeltaE = delta*(sum(Q)+sum(reaction)+sum(free residual))
```

물리 수지 defect와 free residual 크기를 별도로 검사한다. 위 등식이 대수적으로 맞는다는
사실만으로 free equation 정확도를 주장하지 않는다. 에너지 영점을 자동 추정하지 않으며
온도 기준 이동에 대한 에너지 변화의 불변성을 검사한다. Fourier flux의 경계 적분은
일반적으로 FE 반력과 같지 않으며 반력 대신 사용하지 않는다. BE의 C-norm 소산도
실제 열에너지 보존과 별도 검증한다. t=0 반력은 미정의다.

## STH-C05 — HDF5 외부 계약

CLI는 기존 `fesa.exe <model.inp>`이고 output은 lexical sibling `<stem>_results.h5`다.
새 thermal 형식은 기존 structural 형식을 변경하지 않는다. 아래 모든 필드는 mandatory다.
F64/U64/U8/I8은 고정 폭 little-endian, 문자열은 UTF-8다. Compound는 field/type/extent로
읽으며 메모리 padding을 계약으로 삼지 않는다. Float 결과는 모두 finite다.

### Metadata와 model

`/metadata` scalar attributes:

| 이름 | 값/형식 |
| --- | --- |
| schema_version | U64, 1 |
| feature_id | `shell-transient-heat-transfer` |
| analysis_procedure | `uncoupled-transient-heat-transfer` |
| source_step_name | 입력의 원문 step 이름, 생략 시 Step-1 |
| solver_version | 기존 build version |
| source_input_identity | 실제 읽은 입력 byte의 기존 identity 계약 |
| unit_system_label | `user-consistent-unspecified` |
| internal_formulation | `FESA-Q4-P2x2-thermal-shell` |
| integration_rule | `surface-3x3-gauss; thickness-exact-P2x2` |
| time_integration | `backward-euler` |
| nominal_time_increment | F64, 입력 dt |
| time_period | F64, 입력 T_end |

Model의 기본 row 순서는 기존 Domain의 stable source declaration/instance expansion 순서다.

| Dataset | Shape/field와 의미 |
| --- | --- |
| `/model/nodes` | 기존 node compound: internal_node_id U64, instance_name/string, source_label/string, coordinates F64[3] |
| `/model/elements` | thermal DS4 row: internal_element_id U64, instance_name/string, source_label/string, source_element_type=`DS4`, internal_formulation/string, node_internal_ids U64[4], shell_section_internal_id U64, material_internal_id U64 |
| `/model/thermal_materials` | internal_material_id U64, name/string, conductivity F64, density F64, specific_heat F64 |
| `/model/shell_sections` | internal_section_id U64, source_file/string, source_line U64, source_elset/string, material_internal_id U64, thickness F64 |
| `/model/thermal_node_ids` | U64[N], 활성 온도 절점의 internal_node_id, 원래 node 순서를 유지 |
| `/model/thermal_element_ids` | U64[E], flux 요소 행에 대응하는 internal_element_id, 원래 element 순서 유지 |
| `/model/temperature_dofs` | U64[5]=[11,12,13,14,15] |
| `/model/temperature_zeta` | F64[5]=[-1,-0.5,0,0.5,1] |
| `/model/thermal_constraint_mask` | U8[N,5], free=0/constrained=1 |
| `/model/thermal_reaction_dofs` | compound[P]: internal_node_id U64, source_dof U64; mask의 1인 항목을 thermal node 행/DOF 순서로 나열 |
| `/model/thermal_flux_inplane_coordinates` | F64[4,2], 위 xi/eta 순서 |
| `/model/thermal_flux_zeta` | F64[6]=[-1,-0.5,0,0,0.5,1] |
| `/model/thermal_flux_trace_side` | I8[6]=[1,0,-1,1,0,-1]; 0=interior, +/-1=위의 접근 방향 |
| `/model/thermal_flux_local_frames` | F64[E,4,3,3], 마지막 두 축은 global component와 local axis; R의 열이 e1,e2,n |

ID는 해당 model table에 존재해야 하며 중복·누락 mapping은 self-check 실패다.
Reaction mapping은 source DOF 11/15만 포함한다. P=0이면 길이 0인 dataset을 유지한다.
Material/section의 source provenance는 기존 모델 writer convention을 보존한다.
Structural elastic E/nu나 displacement mask를 thermal material/DOF 대신 기록하지 않는다.

### Frames

Storage slot은 `/steps/Step-1`로 고정하며 실제 step 이름은 metadata로 구별한다.
`/steps/Step-1/accepted_frames`는 compound[N_step+1]이고 field는
`frame_index U64`, `increment_index U64`, `time F64`, `time_increment F64`, `is_initial U8`다.
Frame/index는 0..N_step이고 서로 같다. 초기 행은 time=0, time_increment=0, is_initial=1,
나머지는 완료 시간과 해당 방정식에 사용한 양의 delta, is_initial=0이다.
각 `/steps/Step-1/frames/<decimal-index>` group에도 위 다섯 scalar attribute를 저장한다.

| Frame 상대 경로 | Shape | 초기 frame | 완료 frame |
| --- | --- | --- | --- |
| `nodal/temperature` | F64[N,5] | raw 초기 온도 | 완료 온도 |
| `nodal/reaction_heat_rate` | F64[P] | **dataset 없음** | constrained full residual, reaction mapping 순서 |
| `element/heat_flux` | F64[E,4,6,3] | **dataset 없음** | global qx,qy,qz |

Temperature attributes는 `component_order=NT11,NT12,NT13,NT14,NT15`,
`units_label=temperature`, `coordinate_system=scalar`, `location=nodal-thickness-stations`다.
Reaction은 `component_order=RFL`, `units_label=power`, `coordinate_system=scalar`,
`location=prescribed-temperature-dofs`, `positive_direction=into-model`이다.
Flux는 `component_order=QX,QY,QZ`, `units_label=power/area`,
`coordinate_system=global-cartesian`, `location=element-inplane-thickness-traces`다.
Model geometry의 좌표·두께는 length, normalized coordinates/frames/masks/IDs는
dimensionless다. `/model/nodes`는 `units_label=length`,
`/model/shell_sections`는 `thickness_units_label=length`를 가진다.
`/model/thermal_materials`의 세 attribute는
`conductivity_units_label=power/(length*temperature)`,
`density_units_label=mass/volume`, `specific_heat_units_label=energy/(mass*temperature)`다.
`/steps/Step-1/accepted_frames`에는 `time_units_label=time`을 저장하며 time과
time_increment 모두에 적용한다. 서로 다른 단위의 compound field를 하나의
모호한 units_label로 합치지 않는다.

초기 frame의 누락 flux/reaction은 정해진 schema이며 NaN이나 계산된 0으로 대체하지 않는다.
Free residual·열에너지는 검증 보고서의 evidence로 유지하고 필수 공개 dataset을 추가하지 않는다.
Warnings는 기존 `/diagnostics` compound convention의 source/severity/code/message를 유지한다.
형식 discriminator, schema, mandatory field·shape·identity·finite value·frame 완전성을
atomic finalization 이전에 self-check한다. Unknown optional additive field를 무시할 수
있으나 잘못된 mandatory schema를 허용하지 않는다.

## STH-C06 — 런타임 소유권과 실패

Domain은 thermal material/section/initial/BC/load/step 정의를 소유하며 parsing 이후
불변이다. AnalysisModel은 non-owning active view, DofManager는 열 5개와 구조 6개의
layout, numbering, scatter, constraint 및 sparse pattern을 전담한다. Equation ID를
Node/Element에 분산시키지 않는다. Thermal kernel/procedure/state/recovery를 구분하고
구조 displacement API에 temperature를 위장하거나 structural mass로 C를 취급하지 않는다.
미래 coupling state를 미리 할당하지 않는다. Vendor type은 기존 adapter 경계 안에 둔다.

Assembly는 element-local contribution, stable COO ordering/reduction을 사용한다.
병렬 worker가 global CSR를 직접 갱신하지 않는다. 같은 입력은 같은 sparse structure,
축약 순서, diagnostic order와 result row order를 만든다.

증분마다 solve, full temperature 복구, residual/flux/finite/수지 검증을 끝낸 candidate만
accepted state에 반영한다. 실패 시 마지막 accepted state를 오염시키지 않는다.
최종 output은 전체 해석 성공과 writer self-check·close 후 원자적으로 교체한다.
실패 시 기존 최종 HDF5를 보존하며 로그는 실패 진단으로 갱신될 수 있다.
Output lease와 CLI exit 2/3/4/5/6의 기존 분류를 유지한다. 초기 해석 성공이나 이전
파일 존재만으로 이번 실행 성공을 표시하지 않는다. Failed trial을 accepted_frames에 넣지 않는다.

## STH-C07 — 독립 검증과 수치 계약의 선행 조건

채택된 수식의 일관성에 관한 기존 독립 검토와 실제 solver 정확도 검증을 구별한다.
수치 전문 작업은 kernel 구현 전에 [정식화](formulation.md)와 [독립 수치 검토](numerical-review.md)에 아래 세부 계약을 문서화하고 독립 numerical review를
통과해야 한다. 이는 기존 PRD가 numerical owner에게 맡긴 상세 설계 작업이다.

1. 전체 bilinear patch 유효성·orientation 판정, 비다양체 판정, scale-aware degeneracy
   bound와 검증할 geometry군. 전역 자기 교차 검출이나 contact 기능을 추가하지 않는다.
2. Roundoff metric: 행렬 norm·연산 수·machine epsilon·conditioning을 근거로 exact
   fixture 및 free residual의 bound를 도출한다. 예: backward error의 분모는
   `||A_ff||*||T_f||+||b_f||`; 분모 0은 별도 처리한다. `max(1,scale)` floor 금지.
3. 에너지 defect는 저장·외력·반력 항의 절댓값 합을 기준으로 정의하고 free residual
   평가와 분리한다. 이산 수지와 BE 소산 각각의 roundoff 전파를 문서화한다.
4. 3×3/5×5/7×7 quadrature 비교, 시간/공간 convergence의 norm·mesh·시간·series
   절단 오차·판정 구간을 독립 oracle와 예상 asymptotic order에서 도출한다.
5. 고정 5점의 slab 오차 plateau와 초기 열침투 깊이 sqrt(alpha*t)를 보고하는 기준,
   비교 시점과 각 물리량의 허용 이산 오차를 테스트 실행 전에 고정한다.
6. 시간격자 roundoff 동등성·increment count·overflow와 representability 판정을 고정한다.

이 수치 기준을 구현 결과에 맞춰 완화하거나 외부 reference 5%/1%를 내부 검사에
전용하지 않는다. 검토에서 3×3 방법 변경, 지원 geometry 축소, 추가 물리 또는 accuracy
acceptance 변경이 필요하면 구체적 근거를 제시하고 사용자 결정으로 돌아간다.
수치 상세 기준의 독립 검토가 끝나기 전 production kernel 착수를 통과로 표시하지 않는다.

필수 검증은 다음과 같다. 별도 허용을 뜻하는 fixture와 공개 CLI 사례를 구별한다.

| 검증 | 독립 oracle와 실패 검출 |
| --- | --- |
| Shape/K/C | sum(H)=1, sum(B)=0, 정확 M/S/Z, C SPD, K rank19/상수 null, symmetry, 양의 에너지, h 및 1/h scaling, 분리식/직접54점 일치 |
| 방향/flux | constant/면내선형/두께선형 patch, global rotation covariance, normal 반전과 station 재매핑, R 직교성 |
| 중립면 trace | kernel state (0,0,0,1,2)에서 q3(0-)=0, q3(0+)=-4k/h; 공개 초기조건 사례로 오인하지 않음 |
| 초기 jump | C=[[2,1],[1,2]], K=[[1,-1],[-1,1]], delta=1/2, old=(0,0), 두 번째 g=1: 첫 free=-1/5, 다음=1/25, 반력24/5와36/25 |
| 시간격자 | 정수배, 10/3 마지막1, dt>T, decimal roundoff, INC 초과, 비표현 가능 시간, 마지막 factorization 변경 및 실제delta 반력/수지 |
| 열저장/하중 | 단열 균일 온도 유지, no-BC transient, P 및 -P, overlapping source load 합산, constrained DOF에 P 유지, disconnected component별 보존 |
| Partition | 0×0 all-constrained generic algebra; 공개 내부 station BC 금지 유지 |
| 면내 해석해 | 단열 직사각형 T=T0+A*cos(pi*x/L)*exp(-alpha*(pi/L)^2*t), alpha=k/(rho*c); 온도와 미분 flux, 면내 L2 온도2차/gradient1차 |
| 시간 해석해 | 같은 고정 spatial discretization의 독립 eigenpair Kv=lambda Cv 및 exp(-lambda*t), BE 증폭률; dt refinement의 1차 오차 |
| 두께 slab | 균일 초기온도, bottom step 온도/top 단열 Fourier series; 5점 온도·flux·열에너지·반력, series 절단 bound 및 두께 오차 plateau |
| 재료/두께/접속 | full-end prescribed strip의 sum L/(k*h*w) 저항은 assembly fixture; 실제 bottom/top-only CLI는 해당 조건의 독립 oracle 사용. Fold 등온 및 조립 열률 수지 |
| Geometry | 왜곡/warped patch 적분 비교, scaling/translation, zero/negative/uncertain metric, 자기 교차, 방향 충돌, T edge와 vertex-only junction 음성 사례 |
| IO/실패 | 모든 양성/음성 subset, source identity, HDF5 round trip, 초기 dataset 부재, P=0 반력, 마지막delta, no-op warnings, candidate/lease/write/self-check/close 실패 시 기존결과 보존 |

구현 단계에는 열해석 관련 검사를 먼저 수행하고 전체 MSVC x64 Debug build/CTest와
확정된 새 reference의 필수 비교를 수행한다. 기존 reference의 진단 비교도 실패 수치까지
보고한다. 새 compiler warning을 추가하지 않는다.
구현 전 전체 검사를 실행하여 기존 HHT 시간수렴 실패 2건의 실제 재현·이름·metric을
기록한다. 기록만으로 현재 실패를 가정하지 않는다. 구현 후 전체 검사에서 제외하지 않고,
새 실패·기존 실패 악화를 허용하지 않는다. 재현된 기존의 무관한 HHT 실패만 별도
미해결로 유지할 수 있으며 전체 CTest green이라고 보고하지 않는다.
예상하지 못한 baseline failure는 자동 면제하지 않고 원인과 영향 범위를 확인한다.
열해석의 필수 검증 실패는 이 예외에 포함되지 않는다.

## STH-C08 — Reference 원본과 완료 evidence

대상 경로는 다음 두 개다.

- `reference/shell-thermal/shell-thermal.inp`
- `reference/shell-thermal/shell-thermal NodalTemperature.csv`

구현 preflight에서 동일 저장소의 기존 dev worktree에 있는
동일 상대 경로에서 byte 그대로 복사한다. `git worktree list --porcelain`으로 dev
worktree를 찾고 파일별 SHA256을 아래와 대조한다. 이 방식은 머신 절대경로를 계약에
고정하지 않는다. 원본이 달라졌거나 없으면 임의 생성·보정·대체하지 않는다.

| 파일 | 확인한 SHA256 |
| --- | --- |
| shell-thermal.inp | 955C8BEEC35CE53DA5F5DD48785CF8C12FCE726EBFDE7EAE40CF69DBF00D6EA4 |
| shell-thermal NodalTemperature.csv | 765B0D0F64C24CDE6D033D6EF80E0267275A496C97E28D932466EB877810D3E5 |

목적 파일이 이미 있으면 hash 일치를 확인해 재사용하고 다르면 덮어쓰지 않는다.
복사 전후 hash와 사용한 경로를 evidence에 남긴다. Abaqus를 실행하거나 원본 파일명,
내용, metadata를 수정하는 권한은 포함하지 않는다. FESA HDF5/log는 복사한 입력 옆에
생성한다. 보조 deterministic CSV view는 공식 결과가 아니다.

기존 외부 family는 `(shell-thermal, source step Step-1, time 37, bottom temperature NT11,
scalar, user-consistent temperature units, diagnostic)`이다. 원본은 단일 Part-1-1,
676 DS4, 729 node이며 CSV의 `Step,Frame,Node Label,NT11`에서 instance 열 부재는
입력의 단일 instance 및 label 집합 검증으로만 복원한다. HDF5의 source_step_name,
정확한 t=37 accepted frame, source DOF11을 일대일 대응한다. Nearest-time matching,
station 평균, 행 순서 추정, 잘못된 instance 추정은 금지한다.

Missing/extra/duplicate/nonfinite/identity 오류는 tolerance 전에 실패다.
[공통 tolerance](../TOLERANCE.md)의 S=max|reference|, B=0.01S, near-zero absolute<=B,
그 밖의 relative<=0.05, family RMS/S<=0.01, S=0 exact-zero 규칙을 그대로 적용한다.
관찰된 min=-15.5742216, max=1000은 정적 관찰이며 solver 통과 evidence가 아니다.
음수·미소값을 clamp하거나 온도 기준·단위를 조정해 비교를 통과시키지 않는다.
이 원본 비교의 tolerance 초과는 진단 실패로 남긴다. Row identity 오류와 metric을
숨기거나 원본 비교를 통과로 표시하지 않는다. 독립 계산과 실제 실패 evidence는
[충돌 보고서](reference-comparison-conflict.md)에 보존한다. 사용자가 새 reference 모델과
CSV를 기존 `reference/shell-thermal`과 분리된 경로에 두기로 결정했다. 해당 입력·CSV
경로, source row identity, 비교 시점·성분과 새 파일의 hash가 확정되면
이를 별도의 필수 family로 지정하여 실제 비교한다. 새 artifact가 아직 제공되지 않았으므로
새 family의 통과를 주장하지 않는다. 공통 tolerance 수치는 변경하지 않는다.

완료 보고서는 구현 diff, 실제 검증 명령/환경·결과, 독립 numerical/physics 검토,
외부 비교 row/family 판정, 기존 HHT 실패, 남은 물리 한계를 구분한다.
새 reference 모델과 그 결과 CSV가 확정되어야 새 필수 family를 실행할 수 있다.
이는 다른 물리량의 해석해·수지·수렴성 검증을 생략하는 근거가 아니다.

## 현재 checklist

- [x] 요구사항 인터뷰와 단일 uncoupled step 범위 확정
- [x] Q4×P2 두 구간, consistent C, 3×3/exact Z, BE 채택 승인
- [x] Geometry 접속 이상화, raw 초기값, 마지막 짧은 증분, 입력·HDF5 계약 승인
- [x] 모서리 분포 입력 011 연기 및 reference 복사 승인
- [x] 실행 계획 승인 및 구현 요청
- [x] 정식화 정합과 상세 수치 기준의 [독립 검토](numerical-review.md) 완료
- [x] Production 변경 전 전체 baseline과 reference hash evidence 기록
- [x] Thermal semantic model·DOF·geometry·K/C·flux 구현 및 [독립·통합 검증](implementation-verification.md#요소-kernel과-형상-검증)
- [x] Thermal 입력 subset·진단·결정적 조립·시간 적분 구현 및 [범위별 검증](implementation-verification.md#backward-euler-procedure와-candidate-검증)
- [x] HDF5·CLI·candidate와 기존 결과 보존 [검증](implementation-verification.md#application과-실제-cli)
- [x] 승인 정식화와 원본 reference 통과 조건의 [실측 충돌](reference-comparison-conflict.md)에 대한 사용자 결정: 기존 비교는 진단, 정식화 유지, 새 reference 모델 사용
- [ ] 해석해·수지·수렴성 검증과 원본 NT11 진단 비교의 실패 metric 보존
- [ ] 새 reference 모델·CSV·identity 확정 및 필수 외부 비교 통과
- [ ] 전체 MSVC Debug build/CTest 및 기존 실패 대비 확인
- [ ] 독립 physics 검토와 완료 evidence 기록

미실행 검사를 통과로 표시하지 않는다. 전문 문서의 수치 유도·검산, 실제 solver 검사,
외부 reference 비교와 physics 검토는 서로 다른 evidence다.