FESADev/docs/linear-static-mitc4-shell/README.md

# MITC4 shell 선형 정적 해석

## 목적과 경계

4절점 shell의 작은 변형·회전 막·굽힘·횡전단 응답을 해석한다.
Source `S4`와 `S4R`는 모두 내부 `FESA-MITC4`로 매핑한다.
`S4R` 이름은 Abaqus reduced integration이나 hourglass 공식을 선택하지 않는다.
중앙면 기준 일정 두께, 단층 등방 선형탄성이 대상이다.
Composite·offset·material nonlinearity·mixed beam-shell은 이 기능 범위 밖이다.
공통 규칙은 [solver-core](../solver-core/README.md), 수식 원문은 [정식화](formulation.md)다.

## 채택한 수식과 이유

2026-10-20부터 모델 전체의 drilling 방식은 코드의 단일 설정으로 선택한다.
기본 `kDirectSpring`은 초기 global 단위 director `d0`와 전체 회전 `phi`에 대해
`gamma=d0·phi`, `Udrill=0.5*kd*sum(gamma²)`를 사용한다.
`kLegacyCorotatedTwist`는 기존 상대 비틀림 방식이다. 선형 정적과 원형상 고유치의
drilling block은 두 선택에서 같으며, 차이를 만들기 위해 physical 강성을 바꾸지 않는다.
직접 방식은 유한 강체 회전의 인공 에너지·모멘트를 허용한다.

각 절점의 6 global DOF에서 director 접평면의 5 physical DOF를 분리한다.
Bilinear geometry와 canonical edge-midpoint tying으로 공변 횡전단장을 보간한다.
이는 직접 shear interpolation의 locking을 줄이기 위한 MITC 선택이다.
물리 stiffness는 고정 `2×2×2` 적분을 사용한다.
Numerical drilling stiffness는 physical stiffness와 별도이며 stress/resultant/physical energy에 넣지 않는다.
현재 구현의 scale은 physical rotary diagonal 8개의 trace 평균에 `10^-3`을 곱한다.
이 값은 후속 eigen2에서 채택한 규칙이며 초기 최소 양의 대각 규칙을 현행으로 재사용하지 않는다.
Centered section은 `N=A*epsilon0`, `M=D*kappa`, `Q=As*gamma0`를 쓴다.
특히 `D=t^3*Cps/12`이며 막력과 같은 두께 계수로 바꾸지 않는다.

## 입력과 결과 대응

`*ELEMENT,TYPE=S4|S4R`, `*SHELL SECTION,ELSET=...,MATERIAL=...`,
`thickness[,integration_points]`, `*ELASTIC`과 identity-instance 모델을 사용한다.
Section의 optional integration-point 수는 source metadata이며 실제 적분법을 바꾸지 않는다.
DOF 1–6의 지정값과 global nodal `*CLOAD`, 단일 linear `*STATIC`을 지원한다.
Geometry·director·양의 Jacobian을 검사하며 director-parallel aggregate nodal moment는 거부한다.
그 방향의 artificial stiffness를 physical moment 저항으로 사용하지 않는다.
Pressure 입력은 [shell pressure](../shell-surface-pressure-load/README.md)가 추가한 별도 계약이다.
Output 요청 allowlist는 warning no-op이며 mandatory result를 선택하거나 억제하지 못한다.

결과는 `/steps/Step-1/frames/0`의 global nodal displacement/reaction과 shell recovery다.
각 element의 4 midsurface Gauss 위치에 local frame, 8 generalized strain/resultant를 보존한다.
Stress `[S11,S22,S12]`는 각 Gauss 위치의 bottom/middle/top에서 복구한다.
Nodal averaging, Abaqus extrapolated stress와의 임의 대응, `S33/S13/S23` 출력은 만들지 않는다.

| Reference | 판정 범위 |
| --- | --- |
| `reference/shell/shell.inp`와 `shell displacements.csv` | 49 nodes, 36 S4; global U1–3 blocking, UR1–3 warning-only |
| 같은 폴더 reactions/stresses CSV | 검토용이며 equality gate 아님 |
| Optional Abaqus S4R artifacts | 외부 비교에 소비하지 않음 |

Key는 frame·instance·source node·component이며 row-set·finite·unit/location을 먼저 검사한다.
공통 family의 reference-only `S`에 대해 near-zero `abs(ref)<=0.01*S`는 error `<=0.01*S`,
그 밖은 relative error `<=5%`, family `RMS(error)/S<=1%`를 동시에 요구한다.
`S=0`은 exact zero다. UR 수치 실패는 warning이며 잘못된 identity를 허용하는 의미는 아니다.
내부 free residual·전역 force/moment balance는 normalized `1e-10` 한계다.
직접 방식의 기존 전역 gate는 raw moment에서 별도 내부 spatial drilling moment를
차감한 값을 사용한다. 기존 방식은 raw 판정을 유지하며 분모·허용치는 같다.
기존 `global/equilibrium`은 raw 값이다. 새 파일에는 실제 방식과 진단 version,
`global/drilling_moment[3]`, `global/equilibrium_with_drilling[6]`을 추가한다.
선형 변위 비교기에 새 평형 수치 family를 추가하지 않고 진단의 형식·관계만 사전검사한다.

## 구현과 데이터 흐름

[Mitc4Shell](../../include/fesa/elements/mitc4_shell.h)의 `Create`, `Stiffness`,
`StrainDisplacement20`, `RecoverPhysical`가 geometry·수식·물리 복구를 담당한다.
[실제 kernel](../../src/fesa/elements/mitc4_shell.cpp)은 physical/drilling/stabilized 행렬을 분리한다.
Domain이 source definition과 초기 frame을 소유하며 AnalysisModel은 Domain보다 짧게 산다.
DofManager mapping→element-local buffer→결정적 assembly→free solve→full residual 순서다.
[ShellResultRecovery](../../src/fesa/results/shell_result_recovery.h)는 위치별 typed candidate를 생성한다.
Procedure는 해석 상태, writer는 serialization을 소유하며 element에 equation·writer를 넣지 않는다.

## 검증 의미와 한계

2026-10-20 source `6bbbb2b`의 두 방식 별도 실행에서 정식 S4 입력의 생성·U 비교를
통과했고 실제 선형 변위도 정확히 같았다. 직접 방식의 인공 torque·보정 부호·실제
불평형 거부 검사를 포함했다. 전체 Debug 검사는 Native/CTest 각각
1035개 중1024 PASS·기존10 FAIL·1 INCONCLUSIVE SKIP으로 전체 수치 검증 통과는 아니다.

과거 S4 reference는 147 blocking U rows와 평형·대칭·constitutive·physical energy 검사를 통과했다.
그때 중심 U3는 약 `-2.35504418e-5`, normalized free residual은 약 `1.08e-14`였다.
이는 당시 실행 evidence이며 이번 문서 정리에 따른 현재 build/test 통과 선언이 아니다.
Patch·rigid-mode·rank·drilling 분리 검사는 한 개의 외부 plate 사례를 보완한다.
직접 shell end-action 출력이 없어 GP 값에서 element-end 평형을 추정하지 않는다.
Distorted/curved membrane locking, 광범위 mesh convergence, pinched cylinder 등은 미특성화다.
전단 tying을 사용한다는 사실만으로 모든 thin/thick·곡면 정확도가 검증되었다고 말하지 않는다.