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

# 구현 방법과 재사용 Handoff

현재 구현·검증 상태는 [PRD](PRD.md)와 [구현 검증](implementation-verification.md)을 따른다. 아래는 채택 방법론이며 새 실행 계획이 아니다.

<a id="design-plan"></a>

<a id="design-plan--shell-transient-heat-transfer-상세-설계구현-계획안"></a>
## Shell Transient Heat Transfer 상세 설계·구현 계획안

- 상태: 사용자 승인 실행 계획. 구현·검증 진행 중이며 수치 통과 evidence와 구별한다.
- 기준: [Feature PRD](PRD.md), [프로젝트 지침](../../AGENTS.md), [ARCHITECTURE](../ARCHITECTURE.md),
  [CODINGSTYLE](../CODINGSTYLE.md), [TOLERANCE](../TOLERANCE.md)
- 수식의 상세 원본: [정식화](formulation.md). 현재 checklist는 [PRD](PRD.md#현재-checklist)에만 둔다.
- 독립 검토: [numerical-review.md](numerical-review.md). 수식의 일관성 검토이며 구현·정확도 통과 판정은 아니다.

<a id="design-plan--1-구현할-해석과-채택-방법"></a>
### 1. 구현할 해석과 채택 방법

입력의 4절점 Shell mesh에서 온도만 풀며, 한 절점에 두께 방향 온도 5개를 둔다.
요소당 20개 온도 자유도로 면내·두께 방향 전도와 열저장을 함께 계산한다.
기존 MITC4의 변위·회전 강성행렬을 열행렬로 전용하지 않는다.

| 항목 | 채택 방법 | 선택 이유와 한계 |
| --- | --- | --- |
| 면내 보간 | Bilinear Q4 | 승인된 4절점 topology와 연결되며 상수 온도·평판 선형 온도장을 재현 |
| 두께 보간 | 2개 구간의 C0 2차 Lagrange 보간 | 5개 온도점을 사용하고 중앙 온도점을 공유. 전체 두께 단일 4차 보간보다 구간별 gradient와 적분을 분리하기 쉬움 |
| geometry | 실제 3차원 midsurface의 metric과 법선을 이용하는 thin-shell product-domain | 접힌 판·곡면을 같은 scalar 열전도 문제로 구성. 두께 offset에 따른 곡률 보정은 생략하는 모델임을 명시 |
| 열용량 | Consistent heat-capacity matrix | Galerkin 약형에서 직접 유도하고 열저장·반력·에너지 계산에 같은 행렬 사용. Lumping·인공 확산·온도 clamp는 승인 범위 밖 |
| 적분 | 면내 3×3 Gauss, 두께의 두 P2 구간은 정확 적분한 Z 행렬 사용 | 직접 54점 적분과 대조. Affine 평판은 2×2 면내 적분도 정확하며 곡면·왜곡은 고차 적분 대조로 오차 확인 |
| 시간 적분 | Backward Euler, 고정 Δt | 일정 계수 선형 문제에서 factorization을 재사용할 수 있고 첫 구현의 시간 수렴 검증이 명확 |
| 열유속 | 보간 온도의 기울기에서 직접 복구 | 요소별·위치별 Fourier 열유속과 전체 residual 반력을 구별하여 검증 |

이 표는 사용자가 채택한 FESA 방법이며 Abaqus 내부 알고리즘 동등성의 약속이 아니다.
특히 consistent C가 현재 reference의 과도응답을 공통 tolerance 안에서 재현하는지는
아직 검증하지 않았다. 시간 적분의 안정성이 양의 온도 보존이나 정확도를 보장하지도 않는다.

<a id="design-plan--2-온도-자유도와-보간"></a>
### 2. 온도 자유도와 보간

온도점의 무차원 두께 좌표는 `ζ = [-1, -1/2, 0, 1/2, 1]`, 실제 좌표는 `z=hζ/2`다.
요소 vector는 node-major 순서로 정의한다.

\[
\mathbf T_e=[T_{1,1},\ldots,T_{1,5},T_{2,1},\ldots,T_{4,5}]^T.
\]

Source 자유도 11~15와 위 온도점 1~5를 명시적으로 대응시킨다. 내부 equation 번호와
source 자유도를 같은 정수로 취급하지 않는다. 현재 reference의 NT11은 아랫면 값이다.

\[
T_h(\xi,\eta,\zeta)=\sum_{a=1}^4\sum_{s=1}^5
N_a(\xi,\eta)L_s(\zeta)T_{a,s}=\mathbf H\mathbf T_e.
\]

Q4의 `N_a`와 두께의 `L_s` 및 도함수는 [정식화](formulation.md)에 명시한다.
5개의 서로 독립적인 2D 판을 만드는 것이 아니라, 두께 도함수 항으로 온도점 사이를 결합한다.

<a id="design-plan--3-3차원-geometry와-열전도행렬-k"></a>
### 3. 3차원 geometry와 열전도행렬 K

Midsurface를 `r(ξ,η)=Σ N_a x_a`로 나타낸다. 접선 행렬 `A=[r_,ξ r_,η]`, metric
`G=AᵀA`, 면적 Jacobian `J_s=|r_,ξ×r_,η|`, 단위 법선 `n`을 계산한다.
면내 gradient와 전체 gradient의 각 열은 다음과 같다.

\[
\nabla_sN_a=A G^{-1}\begin{bmatrix}N_{a,\xi}\\N_{a,\eta}\end{bmatrix},
\qquad
\mathbf B_{a,s}=L_s\nabla_sN_a+
\mathbf n N_a\frac{2}{h}L'_s.
\]

`B`는 3×20이며 `∇T=B T_e`다. 등방성 전도율 `k>0`에 대해

\[
\boxed{\mathbf K_e=\frac h2\int_{-1}^1\!\int_{-1}^1\!\int_{-1}^1
\mathbf B^T(k\mathbf I)\mathbf B\,J_s\,d\zeta\,d\eta\,d\xi}
\]

를 20×20 행렬로 계산한다. `L_s L_t ∇_sN_a·∇_sN_b`는 면내 전도,
`N_aN_b(2/h)^2 L'_sL'_t`는 두께 전도다. 법선과 면내 접선의 직교성 때문에 이
product-domain 모델의 교차항은 0이다. 평판에서 각각 대략 `kh`, `k/h`의 두께 scaling을 갖는다.

`G`의 퇴화, 뒤집히거나 자기 교차하는 요소, 불일치하는 surface side는 입력 geometry
진단으로 처리한다. `|det J|`로 invalid 요소를 정상화하거나 임의의 최소 두께를 대입하지 않는다.
중앙면 접속은 같은 normalized thickness station을 공유하는 이상화다.
두께가 다른 요소의 단차·급한 fold의 실제 3D 접합부 열장은 이 모델의 해상 범위 밖이다.
이 접속 의미와 얇은 Shell 곡률 근사는 사용자가 채택한 물리 모델이며 상세 3D 전도를 보장하지 않는다.

<a id="design-plan--4-열용량행렬-c와-적분-절차"></a>
### 4. 열용량행렬 C와 적분 절차

밀도 `ρ>0`, 비열 `c>0`에 대해

\[
\boxed{\mathbf C_e=\frac h2\int\rho c\,\mathbf H^T\mathbf H\,J_s
\,d\zeta\,d\eta\,d\xi}
\]

를 계산한다. K의 단위는 `power/temperature`, C는 `energy/temperature`다.
사용자가 일관된 단위계를 제공하며 코드가 입력 숫자를 보고 SI 단위로 추정하지 않는다.

계산 순서는 다음과 같다.

1. 면내 9개 Gauss 위치에서 `N`, 도함수, `J_s`, `G`, 법선을 계산한다.
2. `M_ij=∫N_iN_j dA`, `S_ij=∫∇_sN_i·∇_sN_j dA`의 4×4 행렬을 누적한다.
3. 정확히 적분한 `Z0_ab=∫L_aL_b dζ`, `Z1_ab=∫L'_aL'_b dζ`의 5×5 행렬을 사용한다.
4. Node-major 순서에서 `C=ρc(h/2)(M⊗Z0)`, `K=k[(h/2)(S⊗Z0)+(2/h)(M⊗Z1)]`를 구성한다.
5. finite·대칭성·차원과 상수 온도 null mode를 확인한 element candidate를 반환한다.

Z의 명시 행렬은 [정식화](formulation.md)에 있다. 별도의 직접 적분 검산은 면내 9점 ×
두께 2구간 × 구간당 3점, 총 54개 위치에서 H/B를 구성해 같은 K/C를 얻는지 확인한다.
Affine 평판은 면내 2×2 × 두께 6점, 총 24점으로도 정확하다. 5개 온도점, 6개 두께 적분
위치, 아래의 flux trace 위치는 서로 다른 개념이다. 곡면은 면내 3×3→5×5→7×7 대조로
적분 오차를 평가하며 reduced integration이나 hourglass 안정화항을 추가하지 않는다.

<a id="design-plan--5-열입력과-지정-온도"></a>
### 5. 열입력과 지정 온도

공개 입력은 source DOF 11/15에 대한 일정한 절점 집중 power P만 지원한다.
양수는 모델로 공급되는 열이며 h·면적·shape weight를 곱하지 않는다. Source row 순서로
더하고 constrained DOF의 입력도 full Q에 유지한다. Edge 분포 입력 011은 연기되었으며
이번에 kernel이나 keyword를 추가하지 않는다. 지정되지 않은 외부 경계는 자연 단열이다.

초기 온도는 node/Nset별 signed finite 값으로 5점에 동일 적용하고 미지정 값은 0이다.
BC 생략값은 0이며 model 단계와 step 단계 각각에서 중복 충돌을 검사한 뒤 step이
동일 target의 model 값을 덮어쓴다. 동일 값 중복은 허용하고 다른 값은 오류다.
정확한 subset·미지원 옵션·no-op warning은 [PRD STH-C02](PRD.md#sth-c02--공개-입력-충돌과-부가-keyword)를 따른다.

<a id="design-plan--6-transient-equation과-해법"></a>
### 6. Transient equation과 해법

\[
\mathbf C\dot{\mathbf T}+\mathbf K\mathbf T=\mathbf Q+\mathbf R.
\]

Backward Euler로 다음을 구성한다.

\[
\mathbf A=\mathbf C/\Delta t+\mathbf K,\qquad
\mathbf b^{n+1}=\mathbf Q^{n+1}+\mathbf C\mathbf T^n/\Delta t.
\]

free/constrained partition에서

\[
\boxed{\mathbf A_{ff}\mathbf T_f^{n+1}=
\mathbf Q_f^{n+1}+\mathbf C_{ff}\mathbf T_f^n/\Delta t+
\mathbf C_{fc}\mathbf T_c^n/\Delta t-\mathbf A_{fc}\mathbf g^{n+1}}
\]

를 푼다. 초기 구속점 온도와 step 지정 온도가 다르면 첫 증분의
`C_fc(T_c^0−g)/Δt` 항을 빠뜨리면 안 된다. 입력 초기 상태를 `t=0`에 보존하고
첫 양의 시점부터 step 지정 온도를 부과하는 것이다. 초기 값을 덮어쓴 다른 해석과
에너지·reference 결과가 달라지므로 raw 초기값을 조용히 projection하지 않는다.

고정 물성·geometry·구속 집합·Δt에서는 A_ff를 한 번 factorize하고 매 증분 RHS만 갱신한다.
전체 시간이 Δt로 나누어떨어지지 않으면 마지막 증분만 종료까지 단축한다. Δt가 전체 시간보다
크면 한 증분이다. 시간은 n*Δt로 생성하고 마지막 저장 시점은 입력 종료 시간이다. 표현 오차
수준으로 같은 마지막 간격은 같은 계수를 사용하고 실제로 짧은 간격만 재분해한다.
시간격자·INC·표현 가능성의 상세 판정은 정식화와 독립 numerical review에서 고정한다.

절연체의 K는 상수 온도 null mode를 가지지만 양의 C 때문에 A는 양정치다.
정적 solver처럼 “온도 구속이 없으므로 singular”로 판정하지 않는다. 일반 partition 연산은
전체 구속 시 0×0 free solve를 건너뛰도록 검산한다. 다만 이번 공개 입력은 bottom/top만
구속하므로 내부 3개 온도점까지 모두 구속한 사례는 CLI 지원 모델이 아닌 algebra fixture다.

<a id="design-plan--7-heat-flux와-reaction-heat-rate-복구"></a>
### 7. Heat flux와 reaction heat rate 복구

각 완료 증분에 element scatter로 `T_e`를 모아, 동일한 B로

\[
\boxed{\mathbf q^{global}=-k\mathbf B\mathbf T_e}
\]

를 계산한다. 단위는 `power/area`이며 고온에서 저온 방향이 양의 흐름이다.
local 직교 frame `R=[e_1,e_2,n]`이면 `q_local=Rᵀq_global`이고,
앞 두 성분은 면내, 세 번째는 두께 방향 열유속이다.

- 기본 authoritative flux는 면내 2×2 Gauss 위치와 두께 trace
  `[-1+, -1/2, 0−, 0+, 1/2, 1−]`의 곱인 24개 위치에서 복구한다. 두께 trace는 구간
  안쪽에서 평가하는 위치/접근 방향이다. Global 성분과 local frame을 저장하고 local 성분은 Rᵀq로 후처리한다.
- 위 trace 위치에서 B를 직접 평가한다. C0 보간의 중앙면에서 두께 도함수는 한쪽 극한
  두 개일 수 있으므로 `0−`와 `0+`를 평균으로 합치지 않는다. 행렬의 적분 위치와 복구 위치는 독립이다.
- 재료 경계와 요소 경계를 넘어 nodal averaging한 값을 공식 heat flux로 사용하지 않는다.
- 부호를 비교할 때 아랫면의 외향 법선은 `−n`, 윗면은 `+n`임을 구별한다.

반력 열률은 gradient flux를 절점으로 평균하여 만들지 않고 full residual에서 계산한다.

\[
\boxed{\mathbf r^{n+1}=\mathbf C(\mathbf T^{n+1}-\mathbf T^n)/\Delta t
+\mathbf K\mathbf T^{n+1}-\mathbf Q^{n+1}}
\]

free 성분은 평형 잔차, constrained 성분은 지정 온도 유지에 필요한 반력 열률이다.
양의 반력은 모델에 추가로 공급한 열이다. transient 반력에는 열저장 항이 포함되어야 한다.
초기 온도는 저장하지만 `t=0` flux와 reaction dataset은 생성하지 않는다. 반력을 계산된 0이나 NaN으로 대체하지 않는다.

<a id="design-plan--8-기존-코드와-연결할-책임파일"></a>
### 8. 기존 코드와 연결할 책임·파일

현재 `Element::Recover`는 displacement를 소비하고 `DofManager`는 `kDofsPerNode=6`을
전제로 한다. 따라서 parser에 DS4만 추가해서 완료할 수 없다. 다음은 실제 저장소 경로와
신규 파일 배치다. 세부 C++ signature는 승인된 I/O·정식화 계약과 기존 객체 책임을 따른다.

| 작업 경계 | 기존 수정 대상 | 신규 파일과 책임 |
| --- | --- | --- |
| Semantic model | `include/fesa/model/domain.h`, `src/fesa/model/domain.cpp`, `include/fesa/model/model_types.h`, `include/fesa/materials/material.h` | `include/fesa/materials/isotropic_thermal_material.h`, `src/fesa/materials/isotropic_thermal_material.cpp`: 양의 k·ρ·c와 source identity |
| Thermal element | `include/fesa/elements/element_definition.h`, `src/fesa/elements/element_factory.cpp`의 definition/runtime 생성 경계 | `include/fesa/elements/thermal_shell.h`, `src/fesa/elements/thermal_shell.cpp`: 20×20 K/C와 직접 flux 복구. 열 kernel을 구조 Element의 displacement 계약에 억지로 넣지 않음 |
| Geometry | 기존 `model/shell_geometry`의 MITC4 definition/director 의존성 확인 | `src/fesa/elements/thermal_shell_geometry.h`, `.cpp`: Q4 metric·법선·geometry 검증. 구조 shear tying·drilling 정보 불필요 |
| DOF | `include/fesa/elements/element.h`, `include/fesa/fem/dof_manager.h`, `src/fesa/fem/dof_manager.cpp` | Explicit layout/constraint 입력 경계를 추가하여 DofManager 안에서 구조 6개·열 5개 profile을 구별. 기존 구조 numbering/scatter 계약 보존 |
| Thermal assembly | `SparseMatrix::FromCoo`, `ParallelFor` 재사용 | `include/fesa/assembly/thermal_assembler.h`, `src/fesa/assembly/thermal_assembler.cpp`: 동일 scatter의 K/C, stable COO reduction과 source-ordered Q |
| Procedure/state | `analysis_model.h/.cpp`, `prepared_analysis.h/.cpp`, `src/fesa/app/fesa_application.cpp` | `include/fesa/analysis/transient_heat_procedure.h`, `src/fesa/analysis/transient_heat_procedure.cpp`, `include/fesa/analysis/thermal_analysis_state.h`: factorize/step/recover/candidate commit |
| Abaqus mapping | `src/fesa/io/abaqus/domain_mapping_context.cpp`, `domain_builder.cpp`, `topology_mapper.cpp`, `material_property_mapper.cpp`, `step_definition_mapper.cpp` | 책임별 thermal block mapping 추가. 기존 structural validation의 제한을 온도에 그대로 적용하지 않음 |
| Results | 기존 HDF5 atomic file·primitives와 prepared outcome dispatch | `include/fesa/results/thermal_results_writer.h`, `include/fesa/io/hdf5/thermal_hdf5_results_writer.h`, `src/fesa/io/hdf5/thermal_hdf5_results_writer.cpp`: 온도/flux/reaction/history identity와 atomic finalize |

Domain이 정의를 소유하고 AnalysisModel이 non-owning view를 제공하는 기존 책임을 유지한다.
새 thermal state만 temperature/history를 소유한다. Node/Element에 equation 번호를 저장하지 않는다.
열용량 C를 structural mass field에 저장하지 않으며 vendor API는 기존 backend 경계에 둔다.

<a id="design-plan--10-방법론을-반증할-검증-사례"></a>
### 10. 방법론을 반증할 검증 사례

필수 사례의 원본은 [PRD STH-C07](PRD.md#sth-c07--독립-검증과-수치-계약의-선행-조건)이다.
정확 fixture·norm·시간/mesh 목록·oracle 절단 및 order 판정은 [독립 수치 검토](numerical-review.md)가 소유한다.

- Shape partition, affine exact K/C, constant null mode, C SPD, 양의 에너지와 회전 변환.
- 일정 온도·면내 선형·두께 선형 flux 및 중앙면 0-/0+를 구별하는 직접 미분.
- 두 자유도 C=[[2,1],[1,2]], K=[[1,-1],[-1,1]], delta=.5, old=0, 두 번째 g=1에서
  첫 free=-.2, 두 번째 .04, reaction=4.8와1.44. 첫 C_fc 이전 상태 항을 검출한다.
- No-BC 균일 보존, P/-P·constrained P·source 중복과 component별 에너지 수지.
- Semidiscrete 독립 eigenmode로 시간1차, Fourier 직사각형의 L2 온도2차·gradient1차.
- Bottom step/top 단열 slab series의 온도·flux·에너지·반력; 고정5점 두께 오차 plateau와 초기 침투 깊이 보고.
- 다중 재료/두께 strip 저항은 full-end assembly fixture로 확인한다. 내부 station BC를 CLI로 확대하지 않는다.
- 원본 Step-1 t37 NT11 729행의 identity precheck와 공통 tolerance 진단 비교;
  새 reference 모델이 확정되면 별도 필수 비교. [STH-ADR-015](ADR.md#sth-adr-015-원본-reference-진단-전환과-새-모델-비교)를 따른다.

에너지 defect의 scale은 저장·외력·반력 항의 절댓값 합이며 free residual을 별도로 검사한다.
E=1ᵀCT의 기준 온도 이동에 대한 DeltaE 불변성과 BE C-norm 소산은 서로 다른 검사다.
외부 5%/1% 기준으로 내부 수지를 판정하거나 max(1,scale)로 작은 모델의 오류를 숨기지 않는다.

<a id="design-plan--12-채택-모델의-한계"></a>
### 12. 채택 모델의 한계

Product-domain은 실제 offset 곡률과 상세 접합부를 해상하지 않는다. 고정5점은 초기 두께
경계층을 충분히 해상하지 못할 수 있고 면내 refinement가 두께 오차를 제거하지 않는다.
Consistent C/BE의 안정성은 positivity나 정확도를 보장하지 않는다. Point source 부근의
mesh 독립적인 유한 flux는 보장하지 않는다. 이 한계를 임의 clamp나 tolerance 완화로 숨기지 않는다.

Reference의 NT11 최소값 -15.5742216은 S=1000, B=10의 near-zero 범위 밖이다.
공통 상대오차 검사를 유지하고 초기 jump·공간 이산·열용량의 영향을 독립적으로 평가한다.
현재 채택 계약을 바꾸어야 하는 충돌이 확인되면 근거를 제시하고 사용자 결정으로 돌린다.