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

# MITC4 비선형 정적 Newton 해석

## 목적과 경계

2026-10-20 현재 drilling 기본값은 초기 director의 직접 작은 스프링이다.
모델 전체의 한 코드 설정으로 기존 상대 비틀림도 선택하며 정적 pressure에도 같은
선택을 적용한다. 직접 방식은 drilling의 polar/swing/twist 계산을 생략한다.
아래 polar 근사 실험의 실패는 보존한 기존 방식의 근거이며 직접 스프링 식을 뜻하지 않는다.

2026-10-18 후속 사용자 지시의 [local 근사 실험](../abaqus-tolerance/local-kernel-experiment.md)에서
공유 nonlinear MITC4의 polar 반복을 12→1회로 변경했다. 후속 사용자 지시로 관련 접선
테스트 오차를 1e-3으로 완화한 뒤에도 drilling constraint의 gradient 항등식 검사가
실패했으므로 과거 정적 검증을 변경본에 승계하지 않는다.
정적 Newton tolerance 자체는 변경하지 않았다.

등방 선형탄성 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와 선택한 numerical drilling potential을 분리한다.
Drilling scale은 초기 상태에서 정하고 trial마다 다시 tuning하지 않는다.
직접 방식은 `gamma_i=d_i0·phi_i`, `f_i=kd*gamma_i*d_i0`,
`K_ii=kd*d_i0*d_i0^T`다. 병진과 절점 간 drilling coupling은 exact zero다.
유한 강체 회전에도 인공 복원모멘트가 생기는 것을 허용한다. 기존 방식의 objective
유도와 polar1 구현을 이 직접 방식에 적용하지 않는다.
평형 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은 matching external scale이 nonzero이면 infinity-norm relative `<=1e-2`,
exact-zero이면 typed absolute `<=1e-3` force 또는 force-length다. Factor-one 전역 force/moment
balance는 각각 normalized `<=1e-8`이다. 이는 기존 comparator의 승인 계약이며 두 양을
하나의 `1e-10` 기준으로 요약하지 않는다. Linear 정적·HHT·eigen의 별도 gate는 바꾸지 않는다.
이 전역 수치 판정은 기존 reference 비교기의 책임이다. Procedure에 새 전역 gate를
만들지 않는다. 비교기는 직접 방식 marker일 때 기존 moment family에
`raw_moment-Mdrill`을, 기존 방식·marker 없는 옛 파일에는 raw 값을 사용한다.
`Mdrill`은 현재 위치의 병진 모멘트팔과 `Jl(phi)^(-T)`로 변환한 내부 drilling
모멘트의 source 순서 합이다. 분모에 인공 모멘트를 더하지 않는다.

## 구현과 상태 수명

[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를 오염시키지 않아야 한다.

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

2026-10-20 source `6bbbb2b`의 기본 직접 방식과 별도 기존 방식에서 정식 coarse
nonlinear 입력의 생성·기존 비교를 통과했다. 두 방식의 저장·reader·원자적 실패 보존도
검사했다. 보존한 기존 방식의 gradient 항등식은 차이 약0.00329135로 계속 실패하며,
전체 Native/CTest 각각1035개는1024 PASS·10 FAIL·1 INCONCLUSIVE SKIP이다.
이는 현재 실행 결과이며 아래 과거 기록이나 coarse U 통과로 모든 비선형 검증을 대체하지 않는다.

기존 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 모델의 수렴을 보장하지 않는다.

## 통합 시 자료와 API 상태

Procedure는 공통 [AnalysisProcedure](../../include/fesa/analysis/analysis_procedure.h)로 선택되고
local trial은 [ShellTrialElement](../../include/fesa/elements/element_capabilities.h)를 통해 계산한다.
Kernel은 immutable·stable-address borrowed object이고 accepted candidate는 procedure 소유다.
Full Newton의 typed pending·iteration 순서는 [모듈화 요약](../cpp-object-oriented-modular-refactoring/README.md)을 따른다.
정식 `reference/shellNL-meshfine/`와 `reference/shellNL-meshfine_02/` 자료가 없어 해당 비교는 미완료다.
2026-10-18 사용자 지시에 따라 `reference/temp`로 대체하지 않는다. Fine 사례는 정식 자료 확보 후
hash·source identity를 확인해야 비교를 재개할 수 있다. `_02`는 별도로 comparator의 case identity와
전용 비교 계약도 구현되어 있지 않으므로 자료 확보만으로 비교를 재개할 수 없다.