docs: consolidate solver knowledge and preserve formulation originals

docs/shell-surface-pressure-load/README.md

@@ -1,38 +1,77 @@
 # Shell 표면 압력
 
-## 목적과 현재 범위
+## 목적과 경계
 
-SURFACE의 SPOS/SNEG와 DSLOAD의 P를 사용하는 압력의 방향·면적·follower tangent 및 선형/비선형 조립를 구현한 기능이다. 역사적 기능 검증과 현재 통합 회귀의 범위를 구분한다.
-최근 dev 통합 회귀는 [전체 현황](../tracking/status.md)에 연결하며, 과거 release 판정은
-[release.md](release.md)에 남긴다. 문서 정리는 새 기능 검증이나 재승인을 뜻하지 않는다.
+Named shell surface의 균일 signed `DSLOAD P`를 선형·비선형 정적 해석에 조립한다.
+선형은 reference geometry, `NLGEOM=YES`는 current geometry의 follower pressure다.
+4절점 `S4|S4R` 중앙면만 대상이며 offset·director face·edge/body load는 포함하지 않는다.
+공통 계약은 [solver-core](../solver-core/README.md), 유도 원문은 [정식화](formulation.md)다.
 
-## 계약과 재사용 Handoff
+## 방향·면적·접선
 
-- [요구사항·acceptance](requirements.md): 지원·제외와 기존 요구사항 ID.
-- [정식화](formulation.md): 수식·가정·부호·좌표계·복구 위치.
-- [I/O](io.md): 입력 subset·진단·source identity·결과 schema.
-- [Reference 모델](reference-model.md): 원본과 비교량·행 identity·적용 범위.
-- [독립 수치 검토](numerical-review.md): 검산·위험·반례와 수정 확인.
-- [검증·물리 결과](verification.md): 실제 실행한 명령·수치·실패·미실행·한계.
-- [연구 근거](research.md): 정식화에 필요한 출처와 적용 경계.
+Connectivity의 `g_xi×g_eta=a`를 양의 oriented area vector로 둔다.
+Side multiplier s는 `SPOS=+1`, `SNEG=-1`이며 force density는 `-lambda*p*s*a`다.
+따라서 양의 P는 선택한 면의 outward normal 반대 방향이다.
+음의 P는 그대로 부호를 뒤집으며 abs·clamp로 바꾸지 않는다.
+Bilinear shape로 nodal force를 적분하고 고정 Gauss 순서로 누적한다.
+Current area의 방향과 크기를 함께 미분하여 `Kext=dFext/dq`를 계산한다.
+Newton tangent에는 `Kint-Kext`로 들어가며 follower tangent는 일반적으로 비대칭이다.
+Pressure geometry는 translation만 사용하므로 rotational force와 tangent row/column은 exact zero다.
+Thick shell의 실제 offset face traction으로 임의 확장하지 않는다.
 
-공통 소유권은 [ARCHITECTURE](../ARCHITECTURE.md)를 따른다. Element는 local 계산,
-Assembly는 결정적 reduction, Procedure는 trial/commit, Recovery는 물리 의미,
-Writer는 직렬화를 담당한다. 새 기능에서 기존 stage/phase 실행 계획을 재사용하지 않는다.
-현재 공개 API는 `include/fesa/`, 실제 구현은 `src/fesa/`와 대응 검사를 확인한다.
+## 입력과 결과 대응
 
-## 사용법
+Assembly 안이며 instance block 밖에서 다음 형태를 사용한다.
 
-환경 준비·build·CTest·CLI 기본 사용은 [operations](../operations.md), 입력과 결과의
-공통 계약은 [contracts](../contracts.md)를 따른다. 이 기능의 keyword·option 허용 범위는
-위 I/O 계약을 확인한다. 과거 보고서의 machine 경로·임시 command를 현재 기본값으로 쓰지 않는다.
+```text
+*SURFACE, TYPE=ELEMENT, NAME=Surf-1
+<assembly element set 또는 instance.element>, SPOS
+*DSLOAD
+Surf-1, P, <signed finite magnitude>
+```
 
-## 개발 과정과 주의사항
+Surface member는 source element·side로 정규화한다.
+같은 side의 중복 facet은 warning 후 하나로 만들고 양쪽 side 충돌은 실패한다.
+반면 같은 DSLOAD 행은 각각의 additive load record이며 합법적으로 누적한다.
+Part/instance-level surface, node surface, 다른 face label, `*DLOAD`는 지원하지 않는다.
+DSLOAD `AMPLITUDE`, `FOLLOWER`, `OP`, `REF NODE` 및 unknown parameter는 거부한다.
+Follower 여부는 procedure로 결정하며 keyword 옵션을 조용히 무시하지 않는다.
+양의 Jacobian·nondegenerate oriented area·finite force/tangent를 검사한다.
 
-기존 단계별 계획·coordination은 완료된 실행 운영 기록이어서 제거했다. 승인된 요구사항·
-수식·검토·실제 검증 결과는 위 문서에 보존한다. Git `858e87b`의 이전 경로는 당시 원문을
-조회하는 용도로만 사용하며 현행 작업 지침이 아니다.
+결과는 기존 linear schema0 또는 nonlinear schema1의 displacement/reaction·shell recovery다.
+별도의 가상 pressure stress 또는 nodal averaged stress를 추가하지 않는다.
+Nonlinear 비교는 exact factor-one accepted frame만 사용한다.
 
-- 실패한 trial·candidate는 기존 accepted state와 최종 결과를 변경하지 않아야 한다.
-- 같은 trial의 기하·내력·하중·접선을 사용하고 generalized rotation moment와 spatial moment를 구분한다.
-- [수정·실패 기록](lessons.md)에 원인과 검증 결과를 보존한다.
+| 원본 bundle | 비교 의미 |
+| --- | --- |
+| `reference/shellNL-meshfine-pressure/shellNL-meshfine-pressure.inp` | 729 nodes, 676 S4의 nonlinear follower pressure |
+| 같은 stem `displacements.csv` | U1–3 blocking, UR1–3 warning-only |
+| 같은 stem `reactions.csv` | review-only |
+| 같은 stem `stresses.csv` | 수치 equality 비교에서 제외 |
+
+CSV의 frame·instance·source node와 component를 HDF5 nodal row에 직접 대응한다.
+Shared row/schema/finite precheck는 tolerance 이전 조건이며 warning family에도 적용한다.
+Reference-only `S=max(abs(ref))`에 대해 `abs(ref)<=0.01*S`는 error `<=0.01*S`,
+나머지는 relative error `<=5%`, family RMS/S `<=1%`를 요구한다. `S=0`은 exact zero다.
+내부 free residual·전역 force/moment balance는 normalized `1e-10`을 사용한다.
+
+## 구현과 수명
+
+[EvaluateShellSurfacePressure](../../include/fesa/loads/shell_surface_pressure.h)는
+24 DOF force와 양의 external derivative를 돌려주는 stateless local kernel이다.
+[실제 구현](../../src/fesa/loads/shell_surface_pressure.cpp)은 reference/current geometry를 선택한다.
+[AssembleSurfacePressure](../../include/fesa/assembly/surface_pressure_assembler.h)는
+Domain의 surface/load identity를 stable full DOF contribution으로 조립한다.
+[Assembler 구현](../../src/fesa/assembly/surface_pressure_assembler.cpp)을 대조한다.
+Surface와 load definition은 Domain 소유이며 procedure의 trial displacement는 빌려 사용한다.
+Local 계산→ordered reduction→내력과 외력 결합→free solve→accepted recovery 순서다.
+Candidate 실패가 기존 accepted state·최종 결과를 바꾸지 않아야 한다.
+
+## 검증 의미와 교훈
+
+기존 방향·합력·moment·강체 회전·finite-difference tangent 및 지정 reference 검증 기록이 있다.
+문서 정리는 이번 revision의 새 실행 evidence가 아니다.
+DSLOAD와 DLOAD의 부호 규칙을 섞거나 reference area로 follower load를 계산하면 안 된다.
+같은 trial의 force/tangent를 함께 써야 Newton 일관성을 유지한다.
+외부 displacement 일치만으로 압력 tangent나 local reaction 정확성을 추론하지 않는다.
+한 개의 지정 shell pressure bundle은 arbitrary closed surface·offset face·contact pressure 검증이 아니다.