FESADev/docs/nonlinear-static-newton-raphson/README.md

# MITC4 비선형 정적 Newton 해석

## 목적과 경계

등방 선형탄성 MITC4의 기하 비선형 정적 응답을 full Newton으로 계산한다.
재료 비선형·contact·arc length·line search·자동 cutback은 이 기능에 포함하지 않는다.
고정 global dead nodal force/moment와 factor-one prescribed target을 공통 load factor로 증가시킨다.
후속 pressure 확장은 [shell pressure](../shell-surface-pressure-load/README.md)를 따른다.
공통 소유권·실행은 [solver-core](../solver-core/README.md), 자세한 수식은 [정식화](formulation.md)다.

## 채택한 수식과 이유

고정 reference의 Total Lagrangian geometry와 finite rotation-vector total chart를 사용한다.
초기 director/frame에서 같은 trial의 기하·strain·internal force·consistent tangent를 계산한다.
Rotation-vector generalized moment와 global spatial moment는 일의 짝이 다르다.
반력의 공개 moment 복구에서 chart 변환을 적용하며 성분명 변경으로 대체하지 않는다.
Physical MITC strain·constitutive response와 objective numerical drilling potential을 분리한다.
Drilling scale은 초기 상태에서 정하고 trial마다 다시 tuning하지 않는다.
평형 residual은 internal minus external이며 follower load가 있으면 tangent는
`Kint-dFext/dq`다. Unsymmetric tangent를 대칭화하지 않는다.

## 입력과 결과 대응

`*STEP,NLGEOM=YES` 아래 단일 `*STATIC`을 사용한다.
Data는 `initial_increment,time_period,minimum_increment,maximum_increment` 네 양수다.
`time_period=1.0`이며 initial increment가 고정 h다. 최소·최대 값은 호환성 metadata다.
h의 ordinal multiple과 마지막 exact factor one을 사용하고 실패 시 increment를 줄여 재시도하지 않는다.
`S4|S4R`, centered `*SHELL SECTION`, `*ELASTIC`, identity instance와 DOF 1–6 BC를 사용한다.
`*CLOAD`는 global dead load이며 aggregate drilling-direction moment는 거부한다.
Composite·offset·instance transform·amplitude·MPC·restart·다중 step은 범위 밖이다.

HDF5 nonlinear schema `1`은 `Step-1`의 accepted frame과 load factor를 보존한다.
각 `/steps/Step-1/frames/<k>`에 displacement, reaction 및 4 GP physical shell recovery가 있다.
Bottom/middle/top stress 위치를 보존하며 nodal stress로 평균하지 않는다.
실패 iteration은 accepted frame이 아니며 Newton log와 최종 HDF5는 서로 다른 수명이다.

| Reference bundle | 대응과 의미 |
| --- | --- |
| `reference/shell/` | linear-limit 회귀, 비선형 응답 evidence 아님 |
| `reference/shellNL/` | 49 nodes·36 S4의 factor-one final displacement |
| `reference/shellNL-meshfine/` | 729 nodes·676 S4의 factor-one final displacement |
| `reference/shellNL-meshfine_02/` | 별도 후속 final-state 비교, 앞 사례의 단순 대체 아님 |

각 bundle의 같은 stem `displacements.csv`에서 frame·instance·source node를 맞춘다.
U1–3는 blocking, UR1–3는 warning-only다. Constrained local RF1–3와 spatial RM1–2는 review-only다.
RM3와 stress는 external comparison family를 만들지 않는다.
Fine optional stress의 malformed node label `ss`는 비차단 inventory 문제이며 원본을 보정하지 않는다.
Family의 reference-only `S=max(abs(ref))`에 대해 near-zero `abs(ref)<=0.01*S`는
error `<=0.01*S`, 나머지는 relative error `<=5%`, family RMS/S `<=1%`를 함께 검사한다.
Zero-scale은 exact zero다. Blocking·warning·review의 수치와 판정 영향을 구분한다.
내부 accepted free residual·force/moment 평형의 normalized 기준은 `1e-10`이다.

## 구현과 상태 수명

[NonlinearMitc4Shell](../../include/fesa/elements/nonlinear_mitc4_shell.h)은 immutable evaluator다.
`EvaluateInternalResidualAndTangent`는 한 trial의 내력·접선·물리 복구를 함께 돌려준다.
[Kernel 구현](../../src/fesa/elements/nonlinear_mitc4_shell.cpp)은 accepted state를 소유하지 않는다.
[NonlinearStaticProcedureExecutor](../../include/fesa/analysis/nonlinear_static_procedure.h)의
`Execute`가 증분·trial·수렴·commit을 소유한다.
[Procedure 구현](../../src/fesa/analysis/nonlinear_static_procedure.cpp)은 최대 100 Newton iterations를 허용한다.
Domain→non-owning model→stable full/free DOF→local trial response→ordered assembly→tangent solve 흐름이다.
수렴과 내부 검증을 마친 상태만 accepted collection에 추가한다.
실패 trial은 이전 accepted state와 기존 final HDF5를 오염시키지 않아야 한다.

## 검증에서 배운 점과 남은 경계

기존 nonlinear reference와 rollback·finite rotation·tangent·equilibrium 검증 기록이 있다.
이는 새 revision의 build/test 통과를 의미하지 않으며 이번 작업은 문서 정리만 수행한다.
Reaction은 단일 global 합만 맞춰 local reaction 정확성을 대체할 수 없다.
큰 자세 변화와 원점 이동에서 spatial moment balance를 함께 확인해야 한다.
외부 U 통과는 warning UR 또는 review RF/RM의 수치 일치를 뜻하지 않는다.
현재 prescribed path와 단일재료 shell 사례가 arbitrary nonlinear 모델의 수렴을 보장하지 않는다.