docs: consolidate solver knowledge and preserve formulation originals

docs/linear-static-3d-euler-beam/README.md

@@ -1,42 +1,68 @@
-# 3D Euler–Bernoulli Beam
+# 3D Euler–Bernoulli beam 선형 정적 해석
 
-## 목적과 현재 범위
+## 목적과 경계
 
-B33 선형 정적 해석, 지정 변위·절점 하중과 endpoint 복구. 등분포 등가하중은 local 검산이며 공개 DLOAD 지원이 아니다를 구현한 기능이다. 역사적 기능 검증과 현재 통합 회귀의 범위를 구분한다.
-최근 dev 통합 회귀는 [전체 현황](../tracking/status.md)에 연결하며, 과거 release 판정은
-[release.md](release.md)에 남긴다. 문서 정리는 새 기능 검증이나 재승인을 뜻하지 않는다.
+직선 2절점 `B33`의 축변형·비틀림·두 방향 굽힘을 해석한다.
+Prismatic general section, 등방 선형탄성, 작은 변형·회전이 대상이다.
+`B31` 전단변형 beam, `I12!=0` 결합 단면, 소성·좌굴·동적 beam은 포함하지 않는다.
+`LocalEquivalentLoad`는 정식화 검산용이며 공개 beam `DLOAD` 지원을 뜻하지 않는다.
+공통 실행·소유권·수치 비교 규칙은 [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): 정식화에 필요한 출처와 적용 경계.
+각 절점은 global `[UX,UY,UZ,URX,URY,URZ]`를 가지며 요소는 12 DOF다.
+Connectivity가 local x를, 입력 guide의 x 직교 투영이 local y를 정하고 z는 외적이다.
+퇴화 길이·평행 guide를 임의 축으로 대체하지 않는다.
+`G=E/(2(1+nu))`, `Iy=I11`, `Iz=I22`이며 양의 `A,Iy,Iz,J`를 요구한다.
+축·비틀림과 Hermite 굽힘의 local stiffness를 두 점 Gauss 순서로 계산하고 global로 변환한다.
+Endpoint outward action과 단면력은 같은 이름의 값이 아니므로 부호를 별도로 복구한다.
+단면 응력은 입력 section point의 local 위치에서 `S11`로 복구한다.
+Section point 생략 시 centroid는 `fesa-default` identity를 가진다.
 
-공통 소유권은 [ARCHITECTURE](../ARCHITECTURE.md)를 따른다. Element는 local 계산,
-Assembly는 결정적 reduction, Procedure는 trial/commit, Recovery는 물리 의미,
-Writer는 직렬화를 담당한다. 새 기능에서 기존 stage/phase 실행 계획을 재사용하지 않는다.
-현재 공개 API는 `include/fesa/`, 실제 구현은 `src/fesa/`와 대응 검사를 확인한다.
+## 입력과 결과 대응
 
-## 사용법
+`*ELEMENT,TYPE=B33`, `*BEAM GENERAL SECTION,SECTION=GENERAL,ELSET=...,MATERIAL=...`를 사용한다.
+단면 첫 행은 `A,I11,I12,I22,J`, 둘째 행은 guide vector다.
+`*SECTION POINTS`의 `x1,x2`는 local y,z 좌표이며 입력 순서를 보존한다.
+Part·set·identity instance, `*ELASTIC`, DOF 1–6 `*BOUNDARY`와 step `*CLOAD`를 지원한다.
+선형 `*STATIC`의 네 양수 field는 호환성 값이며 증분 loop를 만들지 않는다.
+단일 step 결과의 storage identity는 `Step-1`, frame `0`이다.
+Instance transform, include와 미지원 model keyword는 실패하며 output 요청 allowlist만 warning no-op이다.
 
-환경 준비·build·CTest·CLI 기본 사용은 [operations](../operations.md), 입력과 결과의
-공통 계약은 [contracts](../contracts.md)를 따른다. 이 기능의 keyword·option 허용 범위는
-위 I/O 계약을 확인한다. 과거 보고서의 machine 경로·임시 command를 현재 기본값으로 쓰지 않는다.
+HDF5 `/steps/Step-1/frames/0` 아래 nodal displacement/reaction과
+`element/section_resultant`, `end_force_local`, `generalized_strain`,
+`generalized_resultant`, `stress_s11`을 서로 다른 위치 identity로 저장한다.
 
-## 개발 과정과 주의사항
+| 원본 `reference/cantilever beam/` | 비교 의미 |
+| --- | --- |
+| `cantilever beam.inp`, `cantilever beam displacements.csv` | 11 nodes의 U1–3→UX–UZ, UR1–3→URX–URZ |
+| `cantilever beam reactions.csv` | RF1–3와 RM1–3의 global nodal reaction |
+| `cantilever beam elemental forces.csv` | 10 elements×2 endpoint; SF1→N, SM1→My, SM2→Mz, SM3→T |
 
-기존 단계별 계획·coordination은 완료된 실행 운영 기록이어서 제거했다. 승인된 요구사항·
-수식·검토·실제 검증 결과는 위 문서에 보존한다. Git `858e87b`의 이전 경로는 당시 원문을
-조회하는 용도로만 사용하며 현행 작업 지침이 아니다.
+Key는 frame·instance·source node이며 endpoint는 source element도 포함한다.
+공유 절점의 여러 endpoint를 평균하지 않는다. Abaqus stress equality gate는 없다.
+각 family는 reference-only `S=max(abs(reference))`를 쓴다.
+`abs(reference)<=0.01*S`는 absolute error `<=0.01*S`, 그 밖은 relative error `<=5%`이며
+모든 row와 `RMS(error)/S<=1%`를 함께 요구한다. `S=0`이면 FESA도 exact zero다.
+Free residual·force/moment balance의 내부 정규화 한계는 `1e-10`이다.
 
-- Dense Matrix 저장 크기 곱의 overflow가 실제 음성 검사에서 드러났다. 크기를 할당 전에 검사하도록 수정했다.
-- 빌드 실패 뒤 `No tests were found`가 나온 실행은 통과 evidence가 아니다. discovery inventory와 실제 실행을 함께 확인한다.
-- 여러 instance의 같은 source label과 공유 절점의 서로 다른 element endpoint를 합치지 않는다.
-- Beam endpoint action 부호와 회전·local/global 좌표를 검산하며 displacement 일치로 stress/reaction 정확성을 추론하지 않는다.
-- 초기 단계의 header 누락 RED는 예상 TDD 실패이고 위 overflow는 실제 결함이었다. 두 종류를 구분한다.
+## 구현과 수명
 
-실제 numerical·parser·solver·reaction·CLI 수정의 세부 evidence는 [수정 기록](lessons.md)에 남긴다.
+[EulerBeam3D](../../include/fesa/elements/euler_beam_3d.h)의 `Create`, `LocalStiffness`,
+`RecoverBeam`이 local 계산을 소유한다. [구현](../../src/fesa/elements/euler_beam_3d.cpp)을 대조한다.
+Domain의 semantic definition은 equation을 저장하지 않으며 AnalysisModel은 non-owning view다.
+DofManager의 stable mapping→local contribution→ordered global assembly 순서로 진행한다.
+[LinearStaticProcedureExecutor](../../include/fesa/analysis/linear_static_procedure.h)는
+`Kff` factorization 뒤 `Ff-Kfc*dc`를 풀고 full residual `K*d-F`로 반력과 평형을 복구한다.
+[BeamResultRecovery](../../src/fesa/results/beam_result_recovery.h)는 typed recovery candidate를 채운다.
+Writer는 검증된 candidate만 직렬화하며 실패한 결과가 기존 최종 HDF5를 덮지 않게 한다.
+
+## 검증 의미와 교훈
+
+기존 beam reference 비교와 analytical·rigid-mode·endpoint 부호 검산의 통과 기록이 있다.
+이 문서 정리는 현재 revision의 새 실행이나 외부 solver 재실행을 뜻하지 않는다.
+Dense matrix 크기 곱 overflow를 할당 전에 검사하게 된 결함 이력을 기억한다.
+빌드 실패 후 `No tests were found`는 통과가 아니며 discovery와 실행을 함께 확인한다.
+변위 일치만으로 단면 응력·반력·end action 정확도를 추론하지 않는다.
+외부 검증은 지정된 하나의 cantilever bundle이며 일반 단면·곡선 beam coverage를 주장하지 않는다.