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

# Shell Transient Heat Transfer PRD

- Feature ID: `shell-transient-heat-transfer`
- Owner: 메인 assistant
- 상태: 상세 계획을 반영한 요구사항 초안. 인터뷰 합의와 수치 제안을 구분하며 baseline 최종 검토 전이다.
- 기록일: 2026-09-28

기준: [프로젝트 지침](../../AGENTS.md), [프로젝트 PRD](../PRD.md),
[공통 ADR](../ADR.md#adr-028), [ARCHITECTURE](../ARCHITECTURE.md),
[TOLERANCE](../TOLERANCE.md). 지역 지침은 [Feature 지침](FEATURED_AGENTS.md),
결정 근거는 [Feature ADR](ADR.md)을 따른다.

## 제품 목적과 문서 범위

3차원 공간에 배치된 4절점 Shell의 시간에 따른 온도장과 열전달을 계산한다.
양방향 열–구조 연성은 장기 목표이며, 이번 기능은 구조해석과 분리된 uncoupled transient
heat transfer다. 해석 사용자는 승인된 Abaqus 입력 subset으로 모델을 정의하고, 개발·검증
담당자는 온도·열유속·반력 열률과 열에너지 수지를 재현할 수 있어야 한다.

이 PRD는 [상세 설계·구현 계획안](design-plan.md), [정식화 제안](formulation.md),
[독립 수치 검토](numerical-review.md)를 연결하는 요구사항 원본이다. 현재 작업은 이 계획을
바탕으로 `FEATURED_AGENTS.md`, `PRD.md`, `ADR.md`를 구성하는 문서 작업이며 구현 실행은 포함하지 않는다.

초기의 두께 방향 균일 온도 선택은 reference 확인 후 사용자가 명시적으로 변경했다.
현재 범위는 균질 단면의 두께 방향 온도점 5개와 면내·두께 방향 열전달을 포함한다.

## 상태와 채택의 구분

| 구분 | 현재 상태 | 의미 |
| --- | --- | --- |
| 기능 범위 | 인터뷰 합의 | 아래 001~018의 지원·제외 범위를 사용자가 선택했다. |
| 수치 방법 | Proposed | 20 DOF 보간·K/C·적분·BE·flux recovery의 우선안을 작성했다. 문서 작성 요청을 방법별 채택 승인으로 확대하지 않는다. |
| 독립 수치 검토 | 문서 검토·정확 산술 검산 수행 | 명시 행렬과 두 증분의 일관성 evidence가 있으며 geometry·초기 상태·I/O 선택은 남아 있다. |
| 구현·제품 검증 | 미실행 | Solver code, build/CTest, FESA/reference 비교와 실제 결과의 physics 검증 완료를 주장하지 않는다. |

## 사용자와 합의한 요구사항

아래 acceptance는 확인해야 할 관찰 가능한 동작과 검증 의도다. 테스트가 실행되었거나
정식화·I/O 세부 계약이 승인되었다는 뜻은 아니다.

| ID | 요구사항 | Acceptance intent |
| --- | --- | --- |
| FEM-REQ-SHELL-THERMAL-001 | 구조 변위와 연성하지 않는 과도 열전달 해석을 제공한다. | 구조해석 없이 초기 온도에서 시간별 열해석 결과를 생성한다. |
| FEM-REQ-SHELL-THERMAL-002 | 3차원 공간의 4절점 사각형 Shell을 지원한다. | 평판·접힌 판·곡면 mesh의 열전달과 모델 회전에 대한 결과 변환을 검증한다. 허용 요소 왜곡은 후속 계약에서 정한다. |
| FEM-REQ-SHELL-THERMAL-003 | 모든 단면에 두께 방향 온도점 5개를 사용하고 면내·두께 방향 열전달을 계산한다. | 두께 방향으로 온도가 달라지는 독립 사례와 균일 온도 사례를 구분하여 확인한다. |
| FEM-REQ-SHELL-THERMAL-004 | 각 단면은 두께 전체에 동일한 재료를 사용하는 균질 단면이다. | 적층 단면은 지원 범위에 포함하지 않는다. |
| FEM-REQ-SHELL-THERMAL-005 | 열전도율·밀도·비열은 온도에 무관한 상수이며 열전도율은 등방성이다. | 상수 물성의 전도·열저장 응답을 검증하고 온도 의존·이방성 입력은 지원으로 해석하지 않는다. |
| FEM-REQ-SHELL-THERMAL-006 | 여러 재료를 정의하고 요소 집합별로 배정할 수 있다. | 재료 배정과 서로 다른 물성 영역 사이의 열전달을 확인한다. |
| FEM-REQ-SHELL-THERMAL-007 | 요소 집합별 두께를 지원하며 각 요소 내부의 두께는 일정하다. | 서로 다른 두께가 전도·열저장·가장자리 열입력에 반영되는지 검증한다. |
| FEM-REQ-SHELL-THERMAL-008 | 초기 온도는 절점 또는 절점 집합별로 지정할 수 있다. | 비균일 면내 초기 온도를 읽고 해당 절점의 5개 두께 방향 온도점에 같은 값을 적용한다. |
| FEM-REQ-SHELL-THERMAL-009 | 아랫면·윗면에 각각 독립적인 지정 온도를 적용한다. | 한쪽 면만 구속한 경우와 두 면에 서로 다른 온도를 구속한 경우를 확인한다. 내부 온도점 지정 온도는 제외한다. |
| FEM-REQ-SHELL-THERMAL-010 | 절점 집중 열입력은 아랫면·윗면 온도점에 각각 독립적으로 적용한다. | 선택한 면의 열입력이 조립·열에너지 수지에 반영되는지 확인한다. 내부 온도점 직접 입력은 제외한다. |
| FEM-REQ-SHELL-THERMAL-011 | Shell 가장자리에 두께 전체로 균일하게 분포하는 열입력을 적용한다. | 대상 edge, 두께 방향 분포와 총 열률의 일관성을 독립 적분값으로 확인한다. |
| FEM-REQ-SHELL-THERMAL-012 | 지정 온도와 열입력은 해석 중 일정하다. | 시간 이력 표·진폭 함수에 의한 변화 없이 초기 온도에서 과도응답을 계산한다. 시작 시점의 적용 의미는 후속 계약에서 명시한다. |
| FEM-REQ-SHELL-THERMAL-013 | 사용자가 전체 해석 시간과 고정 시간 증분을 지정한다. | 지정된 시간 격자와 종료 시점을 확인한다. 나누어떨어지지 않는 종료 시간의 처리는 후속 계약에서 명시한다. |
| FEM-REQ-SHELL-THERMAL-014 | 온도, 요소 열유속, 지정 온도 경계의 반력 열률을 필수 결과로 제공한다. | 온도점·열유속 위치와 성분·반력 열률의 물리적 의미를 확인한다. 두께 방향 범위 확대에 따른 열유속 성분은 후속 출력 계약에서 명시한다. |
| FEM-REQ-SHELL-THERMAL-015 | 모든 시간 증분의 결과를 HDF5로 저장하고 초기 온도 분포도 보존한다. | 입력의 lexical sibling인 `<stem>_results.h5`에서 초기 온도와 완료 증분별 결과·시간·source identity를 확인한다. |
| FEM-REQ-SHELL-THERMAL-016 | 기존 reference CSV의 `Step-1`, `t=37`, `NT11`을 외부 비교 대상으로 한다. | source node와 두께 위치·시점을 대응시킨 뒤 공통 tolerance 정책을 적용한다. |
| FEM-REQ-SHELL-THERMAL-017 | 외부 CSV에 없는 결과도 독립적으로 검증한다. | 해석해·열에너지 수지·시간 및 공간 수렴성으로 전체 온도 이력, 내부 온도, 열유속과 반력 열률을 검증한다. 추가 Abaqus CSV 확보를 필수 조건으로 삼지 않는다. |
| FEM-REQ-SHELL-THERMAL-018 | 하나의 transient step만 지원한다. | 초기 온도와 일정한 경계조건·열입력으로 지정 시간까지 계산하고, 여러 해석 step의 입력은 지원 범위 밖으로 진단한다. |

## 제외 범위

- 열–구조 순차 연계와 양방향 연성, 변형에 따른 열전달 변화
- 3절점 요소, 적층 단면, 이방성·온도 의존 열물성
- 대류·복사·내부 발열, Shell 윗면·아랫면에 직접 적용하는 분포 열유속
- 두께 방향 비균일 초기 온도, 내부 온도점의 지정 온도·집중 열입력
- 두께 방향 비균일 가장자리 열입력, 절점별 가변 두께
- 사용자 선택 두께 방향 온도점 수, 자동 시간 증분, 시간 변화 경계조건·열입력
- 여러 해석 step 및 step 사이의 온도 상태 전달·경계조건 변경
- Abaqus 내부 요소·적분·열용량 처리·결과 생성 절차의 동등성

면의 온도점에 적용하는 절점 집중 열입력은 지원하며, 면적에 걸쳐 적용하는 분포 표면
열유속은 제외한다. 두 입력을 혼동하지 않는다.

## Reference 정적 관찰

사용자가 지정한 논리적 경로는 `reference/shell-thermal`이다. 2026-09-28 확인 시
현재 `ThermalAnalysis` worktree에는 없고 동일 저장소의 `dev` checkout에서 다음 원본을
읽었다. 원본 복사·수정·solver 실행은 수행하지 않았다.

| Artifact | 확인한 내용 |
| --- | --- |
| `reference/shell-thermal/shell-thermal.inp` | `DS4` 676개, 절점 729개, instance `Part-1-1`, 단일 재료, `*Shell Section` 데이터 `0.5, 5` |
| 같은 `.inp`의 재료 | Conductivity `54`, Density `7850`, Specific Heat `460`. 입력 숫자만 기록하며 단위계를 추정하지 않는다. |
| 같은 `.inp`의 step | `*Heat Transfer, end=PERIOD`와 `1., 100., , ,`; `Set-10, 11, 11, 1000.` 지정 온도. 명시적인 초기 온도·집중 열입력·가장자리 열입력은 없다. |
| 같은 `.inp`의 step 전 경계 | `*Boundary`의 `Set-10, 11, 11`이 존재한다. 생략된 값과 step 내부 재지정의 의미를 I/O에서 확인하며 model-level 경계를 무시하지 않는다. |
| `reference/shell-thermal/shell-thermal NodalTemperature.csv` | `Step`, `Frame`, `Node Label`, `NT11`; `Step-1`, `Increment 37: Step Time = 37.00`의 729행. 다른 시간·열유속·반력 열률은 없다. |

CSV에는 instance 열이 없으므로 `.inp`의 단일 instance로 row identity를 복원할 수 있는지
I/O 단계에서 명시적으로 검증한다. 파일명·행 순서만으로 다중 instance를 추정하지 않는다.
이 사례 하나로 다중 재료·두께, 가장자리·집중 열입력 또는 전체 시간 이력의 coverage를 주장하지 않는다.
독립 검토의 CSV 정적 통계에서 729개 label이 고유하고 값이 유한했으며 NT11 범위는
`[-15.5742216, 1000]`이었다. 초기 경계 급변·공간 이산과 관련된 undershoot 가능성을
조사해야 하며 reference 음수를 단순 roundoff로 취급하지 않는다.

Abaqus의 공개 열전달 Shell 규약에서 자유도 11은 아랫면, 5개 온도점 단면의 13은 중앙면,
15는 윗면에 해당한다. 기하학적 절점 위치와 온도 자유도의 두께 위치는 구별한다.
[Abaqus 문서: Heat Transfer Shell Elements](https://docs.software.vt.edu/abaqusv2025/English/SIMACAEELMRefMap/simaelm-c-shellelem.htm).
원본은 CAE 2024 생성 표시가 있으며 공개 의미 확인에는 접근 가능한 2025 문서를 사용했다.

## 제안하는 계산 방법과 상세 계획

아래는 사용자가 선택한 기능 범위를 구현할 수 있도록 작성한 수치 방법 제안이다.
인터뷰로 확정한 요구사항과 구분하며 최종 채택 승인을 받은 것으로 기록하지 않는다.

- 면내 Q4와 두께 두 구간의 C0 2차 보간으로 요소당 온도 자유도 20개를 구성한다.
- 실제 3차원 midsurface의 metric과 법선을 이용해 `∇T=B T_e`를 구성한다.
  Thin-shell product-domain 근사와 접힌 판·다른 두께의 normalized-station 접속 의미를 명시한다.
- `K_e=∫BᵀkB dV`, `C_e=∫ρcHᵀH dV`를 사용한다. 두께의 명시 Z 행렬과
  면내 3×3 Gauss 적분을 조합하고 직접 54점 적분으로 검산한다.
- Backward Euler의 `(C/Δt+K)T^(n+1)=Q+C T^n/Δt`를 free/constrained 공간으로
  분할한다. 첫 증분의 이전 constrained 온도 항까지 보존하고 고정 계수 factorization을 재사용한다.
- `q=−kBT_e`로 면내·두께 방향 열유속을 직접 계산한다. 면내 4점과 두께 6개 trace의
  총 24개 위치를 제안하며 중앙면의 양쪽 flux를 구별한다.
- 반력 열률은 `C(T^(n+1)−T^n)/Δt+K T^(n+1)−Q`의 구속 성분에서 계산한다.

[계획안](design-plan.md)은 각 선택의 이유, 단계별 수정 파일과 검증을,
[정식화](formulation.md)는 shape function·미분·행렬·적분·에너지 수식의 원본을 소유한다.
기존 `Element`/`DofManager`의 구조 자유도 전제를 확인했으며 별도 thermal kernel/state와
DOF layout 확장이 필요하다. 구체적인 수치 제안·I/O 의미·geometry 허용 범위를 검토한 뒤 구현한다.

## 입력·결과 계약의 범위

입력의 topology·material·section·load·boundary·step은 Domain에 보존하고, 실행 view와
mutable thermal state를 분리한다. `DS4`, `*SHELL SECTION`, 열물성과 `*HEAT TRANSFER`를
읽는 것만으로 기능 완료를 선언하지 않는다. Source label/instance는 방정식과 결과까지 보존한다.

| 물리량·입력 | 의미와 위치 | 단위 차원·확정 상태 |
| --- | --- | --- |
| 온도 | 절점마다 두께 위치 5개, initial 및 모든 완료 증분 | Temperature. 값의 단위계를 추정하지 않는다. |
| 열전도율·밀도·비열 | 요소 집합이 참조하는 상수 재료 | Power/(length·temperature), mass/volume, energy/(mass·temperature) |
| 절점 집중 열입력 | 아랫면 또는 윗면 온도점의 입력 | Power. 면적이나 두께를 중복 곱하지 않는 제안 |
| 가장자리 열입력 | 두께 전체에 균일한 edge 입력 | 외부 단위·syntax 미확정. 계산안의 면적당 flux는 power/area, 적분 후 총 열률은 power |
| Heat flux | 요소별·면내 위치·두께 trace·component·시점 | Power/area. 제안은 24개 trace 위치, global/local 저장 선택은 미확정 |
| 반력 열률 | 지정 온도 자유도·시점 | Power. 제안은 모델 안으로 공급되는 열을 양으로 정의 |
| 열에너지·free residual | 검증 evidence | Energy / power. 별도 필수 공개 dataset으로 추가 승인된 것은 아님 |

공식 출력은 입력 경로의 lexical sibling인 `<stem>_results.h5`다. Dataset layout·schema
version·초기 frame validity·좌표계는 I/O 계약에서 정한다. `t=0` 초기 온도 저장을
시간 차분이 없는 반력 열률의 계산 완료로 표시하지 않는다.

## 검증 기준과 후속 계약 경계

외부 `NT11` 비교는 [TOLERANCE](../TOLERANCE.md)의 공통 정책을 적용한다. Row identity,
필수 component·시간·두께 위치의 대응과 missing·extra·duplicate·nonfinite 사전검사를
tolerance 전에 수행한다. 음수 reference를 zero-clamp하거나 결과에 맞춰 보정하지 않는다.

독립 검증은 최소한 균일 온도 보존, 열입력·열저장·반력 열률의 에너지 수지, 면내 및
두께 방향의 해석 가능한 전도 사례, 열유속·반력의 부호, 시간 및 공간 수렴성을 다룬다.
구체적인 사례·mesh·시간 간격·판정 기준은 정식화와 독립 numerical review에서 확정한다.
외부 비교 tolerance를 내부 에너지 수지나 수렴성 기준으로 대신 사용하지 않는다.

정식화·계획안에서 제시한 방안은 아직 사용자 미승인이다. 다음 계약은 제안을 검토하여
확정할 필요가 있으며 기존 인터뷰 범위를 조용히 변경하지 않는다.

- 정식화: 곡면·왜곡 geometry의 허용 범위, 서로 다른 두께 단면의 접속 의미, 온도 보간,
  면내·두께 적분, 열용량 행렬, 시간 적분법, 초기/지정 온도 적용 순서와 반력 열률 정의
- I/O: 승인 keyword subset, edge 열입력의 단위·부호·대상 표기, 생략된 초기 온도 등 default,
  중복/상충 집합 진단, source identity, 열유속 위치·좌표계·성분, 초기 상태와 증분의 HDF5 schema
- Numerical Review: reference frame 대응과 comparison family, analytical/invariant 사례와
  각 판정 기준, 고정 5개 온도점 조건에서의 공간 수렴성·두께 해상도 한계
- 구현 전 runtime 계약: 별도 thermal procedure/state, 실패 candidate와 기존 최종 HDF5 보존,
  deterministic assembly·결과 순서, 기존 구조해석의 회귀 검증 범위

## 기능 완료 기준

| 검증 묶음 | 요구사항 연결 | 필요한 evidence |
| --- | --- | --- |
| 입력과 모델 의미 | 001~013, 018 | 양성 입력의 semantic mapping과 미지원·상충·불량 값 진단; pre-step boundary와 단일 transient step 구분 |
| Element·조립 | 002~007, 010~011 | Shape·K/C·edge 일관 하중 검산, source DOF scatter, 결정적인 조립·결과 순서 |
| 시간 적분과 물리 | 008~013, 017~018 | 초기 경계 불일치, 해석해·에너지 수지·시간/공간 수렴, 실패 candidate 보존 |
| 결과와 저장 | 014~015 | 모든 온도점·완료 증분, flux trace, reaction의 identity·단위·좌표계 및 HDF5 round trip·실패 보존 |
| 외부 비교 | 016 | 원본 NT11 t37 row 대응 사전검사와 공통 tolerance의 blocking 비교 |
| 통합 회귀 | 전체 | 구성된 MSVC x64 Debug build/CTest, 신규 warning 없음, 영향받는 구조해석 회귀와 독립 검토 결과 |

단일 kernel 통과, reference 한 시점의 일치 또는 문서의 정확 산술 검산만으로 위 묶음을
대체하지 않는다. 검증 상세는 [계획안 9~11절](design-plan.md#9-구현-순서와-각-단계의-완료-조건)과
[독립 검토 3절](numerical-review.md#3-구현-후-반증-가능한-검증-계획)을 따른다.

## 구현 전 미결정 계약

| 항목 | 우선 제안·남은 선택 | 결정·상세 계약 owner | 근거 |
| --- | --- | --- | --- |
| 보간·행렬·적분 | Q4×두 P2 구간, consistent C, 면내 3×3·두께 exact Z의 채택 | 메인/사용자, formulation·numerical review | STH-ADR-007 |
| Geometry·접속 | Thin-shell 곡률 근사와 normalized station 접속의 적용 범위·퇴화 기준 | 메인/사용자, formulation·numerical review | STH-ADR-008, NR-01 |
| 시간 제어 | Backward Euler 및 종료시간을 Δt 정수 배로 제한할지 | 메인/사용자, formulation·I/O | STH-ADR-009 |
| 초기 상태 | Raw 초기값의 첫 증분 사용, pre-step 경계·생략값·step 재정의 의미 | 메인/사용자, I/O·formulation | STH-ADR-010, NR-02 |
| 결과 계약 | 24개 trace, global/local 저장, 반력 부호, t=0 validity | 메인/사용자, I/O·numerical review | STH-ADR-011 |
| Edge 입력 | 면적당 또는 길이당 단위·공개 keyword·대상 및 중복 의미 | 메인/사용자, I/O | STH-ADR-012, NR-03 |
| 내부 수치 판정 | Geometry margin, 적분 오차, residual·수렴성 기준 | numerical review, 해당 계약 owner | NR-04; 외부 tolerance와 구분 |

Owner 역할은 후속 할당 책임이며 아직 수행하지 않은 I/O 작업이나 새 승인을 뜻하지 않는다.
NR 항목의 상세 근거는 [독립 수치 검토](numerical-review.md#1-영향이-큰-판단과-필요한-결정)에 있다.

## 사용자 검토 항목

개별 범위 선택 인터뷰를 마쳤다. 이 초안의 범위·제외·acceptance intent를 사용자에게
요약하여 제시하고 문서 전체의 requirement baseline을 확정한다. 구현 실행은 별도 요청 범위다.

후속 정식화·I/O에서 physics나 공개 의미의 추가 선택이 필요하면 근거와 함께 사용자에게
돌려보낸다. 위 전문 항목을 이미 결정되었거나 검증된 것으로 취급하지 않는다.

## 현재 checklist

- [x] 물리·요소·재료·두께·초기 온도·경계조건·열입력 범위 인터뷰
- [x] 고정 시간 증분·모든 증분 결과 저장·필수 결과 선택
- [x] 기존 reference 원본 정적 확인과 외부 비교 범위 합의
- [x] 핵심 문서 3개에 합의와 미결정 항목 기록
- [x] 단일 transient step으로 범위 확정
- [x] 열전도·열용량행렬, 열유속·반력, 시간 적분과 코드 연결을 포함한 상세 계획 제안
- [x] [독립 수치 검토](numerical-review.md)의 문서 지적 반영; 미결정 물리·I/O 계약은 별도로 유지
- [x] 상세 계획을 바탕으로 지역 FEATURED_AGENTS·PRD·ADR 구성
- [ ] 사용자 검토 후 requirement baseline 확정
- [ ] 사용자 검토 후 수치 방법·I/O 계약·geometry 허용 범위와 실행 계획 확정

Solver build/test, Abaqus 실행, FESA/reference 수치 비교와 실제 결과의 physics 검토는
수행하지 않았다. [독립 수치 검토](numerical-review.md)는 두께 Z 행렬, 평판 20 DOF 행렬과
두 증분 BE 에너지 수지를 정확 유리수로 검산하고 잔여 물리·I/O 결정을 기록했다.