feat(nonlinear-static-newton-raphson): step 12 - execution-closure-and-evidence-docs

docs/PRD.md

@@ -2,7 +2,7 @@
 
 ## 목표
 FESA는 Abaqus `.inp` keyword subset을 입력으로 받아 자체 유한요소 정식화로 구조해석을
-수행하고, step/frame 단위 결과를 `results.h5` HDF5로 저장하며, 기능이 지정한 Abaqus
+수행하고, step/frame 단위 결과를 input lexical sibling `<stem>_results.h5` HDF5로 저장하며, 기능이 지정한 Abaqus
 reference CSV 수치와 비교 가능한 C++17/MSVC 솔버를 제공한다. Abaqus의 요소 알고리즘,
 적분법, stabilization 또는 내부 결과 생성 절차를 재현하는 것은 목표가 아니다.
 
@@ -36,7 +36,7 @@ Element/material 계층의 일반적인 runtime polymorphism, iterative solver,
 2. FESA는 syntax를 읽은 뒤 semantic mapping과 model validation을 수행한다. 지원하지 않는 모델 의미는 구조화된 diagnostic과 안정된 exit code로 거부한다.
 3. 해석 procedure는 active model view, DOF/equation map과 sparse system을 만들고, essential constraint elimination을 적용해 선형계를 factorize하고 substitution한다.
 4. FESA는 full displacement를 복구하고 equilibrium residual/reaction과 element 결과를 계산한다.
-5. 성공 시 output request와 무관한 mandatory 결과, metadata와 diagnostic을 versioned `results.h5`에 기록한다. 실패 시 불완전한 최종 결과 파일을 정상 결과처럼 남기지 않는다.
+5. 성공 시 output request와 무관한 mandatory 결과, metadata와 diagnostic을 versioned lexical sibling `<stem>_results.h5`에 기록한다. 실패 시 불완전한 최종 결과 파일을 정상 결과처럼 남기지 않는다.
 6. 검증 workflow는 기능이 지정한 HDF5 quantity를 기존 Abaqus CSV의 source identity와
    component에 대응시켜 tolerance를 판정하고, 별도로 equilibrium과 물리적 타당성을
    검토한다. Reference bundle naming이나 provenance는 수치 비교 gate가 아니다.
@@ -76,10 +76,27 @@ Parser keyword, element kernel, solver backend 또는 output dataset 중 하나
 - displacements, reactions, equilibrium end actions, section resultants, generalized results,
   axial `S11` output
 - HDF5 result schema v0
-- `fesa.exe <model.inp> --output <results.h5>` CLI
+- `fesa.exe <model.inp>` CLI with lexical sibling result/log names
 - 승인된 `reference/cantilever beam/` B33 결과와 displacement, reaction, section resultant
   comparison; beam stress reference comparison은 N/A
 
+## 승인된 Nonlinear Static 확장
+
+- `*STATIC, NLGEOM=YES` 단일 step은 parse/map을 정확히 한 번 수행한 뒤 linear static과
+  분리된 full-Newton procedure로 dispatch한다. Nonlinear path는 별도 mutable state,
+  unsymmetric tangent solver, iteration log writer와 schema-v1 HDF5 writer를 사용한다.
+- CLI는 정확히 하나의 `<model.inp>`만 받고 `<stem>_results.h5`와 `<stem>_log.txt`를 같은
+  lexical sibling directory에 유도한다. `--output`은 지원하지 않는다.
+- Nonlinear HDF5 schema v1은 committed accepted frame만 기록한다. factor-zero는 metadata
+  baseline이며 accepted frame이 아니고, successful factor-one row는 unique
+  `load_factor=1.0` accepted frame이다.
+- Factor-one `/global/equilibrium`은 global origin에서 current `X+u` arm과 spatial physical
+  moment를 사용한 applied-plus-constrained-reaction balance error다. Accepted free residual과
+  constrained-reaction resultant는 그 dataset의 대체 quantity가 아니다.
+- `shellNL-meshfine`는 primary nonlinear case, `shellNL`은 companion, `shell`은 linear
+  regression control이다. `U1/U2/U3`는 blocking, `UR1/UR2/UR3`는 warning-only이며 local
+  `RF/RM`은 review-only (`RM3` 및 stress 제외)로 비교한다.
+
 ## 신규 기능의 제품 완료 정의
 
 새로운 element, load, constraint, material, analysis procedure 또는 output quantity는 다음 조건을 모두 만족할 때 FESA 제품 기능으로 취급한다.
@@ -102,7 +119,7 @@ Parser keyword, element kernel, solver backend 또는 output dataset 중 하나
 | FESA-PRD-003 | FESA는 현재 step의 실행 view를 `AnalysisModel`로 구성해야 한다. | active elements, loads, boundary conditions, properties/materials가 Domain 복사 없이 참조 또는 id view로 연결된다. | analysis model unit test |
 | FESA-PRD-004 | FESA는 equation numbering과 constraint/free mapping을 `DofManager`에 집중해야 한다. | Node/Element 내부에 equation id를 분산 저장하지 않는다. | code review, DofManager unit test |
 | FESA-PRD-005 | FESA는 해석 중 변하는 물리량을 `AnalysisState`에 저장해야 한다. | V0 displacement, external/internal force, residual, constrained reaction, step/frame identity와 element recovery rows가 출력에 연결되고 velocity, acceleration, temperature, iteration history는 할당하지 않는다. | state unit test, integration test |
-| FESA-PRD-006 | FESA는 solver 결과를 HDF5 authoritative output `results.h5`로 저장해야 한다. | V0 step/frame field results, metadata, diagnostics가 schema version과 함께 저장된다. | HDF5 schema test |
+| FESA-PRD-006 | FESA는 solver 결과를 derived HDF5 authoritative output `<stem>_results.h5`로 저장해야 한다. | V0 step/frame field results, metadata, diagnostics가 schema version과 함께 저장된다. | HDF5 schema test |
 | FESA-PRD-007 | FESA는 기능이 지정한 Abaqus reference CSV quantity와 비교 가능한 deterministic source-row/component mapping을 제공해야 한다. | Required source IDs/components는 일대일 대응되고 missing/extra/duplicate/nonfinite row는 tolerance 전에 실패한다. Canonical naming, README, metadata, provenance 또는 CSV schema version은 요구하지 않는다. | reference comparison report |
 | FESA-PRD-008 | FESA의 production C++ 변경은 테스트를 먼저 작성하고 실패를 확인한 뒤 구현해야 한다. | 관련 C++ test file, RED 실패와 후속 GREEN 성공 증거가 있고 Stop의 전체 MSVC build/test가 통과한다. | implementation report, Hook guardrail, CTest |
 | FESA-PRD-009 | FESA는 외부 라이브러리 API를 solver core에 직접 노출하지 않아야 한다. | MKL, TBB, HDF5 의존은 adapter module에 제한된다. | architecture review, dependency review |
@@ -139,7 +156,7 @@ Parser keyword, element kernel, solver backend 또는 output dataset 중 하나
    required reference quantity의 최소 source-ID/component matching이 승인되어 있다.
 5. Tests fail before implementation: C++/integration/reference test를 제품 코드보다 먼저 작성하고 같은 Step 안에서 RED 실패와 후속 GREEN 성공을 확인한다.
 6. CMake/CTest pass: MSVC/x64/Debug 기준 configure, build, test가 통과한다.
-7. Reference comparison pass: 기능이 blocking으로 선언한 FESA `results.h5` quantity가
+7. Reference comparison pass: 기능이 blocking으로 선언한 FESA `<stem>_results.h5` quantity가
    선언된 Abaqus CSV와 source identity/component별로 대응되고 승인된 tolerance 안에 있다.
 8. Physics sanity pass: equilibrium, reaction consistency, displacement direction, symmetry, section-force consistency와 normalized residual이 검토되어 있다.
 9. Release readiness pass: acceptance traceability, known limitations, release notes draft가 준비되어 있다.
@@ -151,7 +168,8 @@ Parser keyword, element kernel, solver backend 또는 output dataset 중 하나
 - instance translation/rotation, nested assembly 및 dependent/independent mesh semantics
 - `I12 != 0`, taper, offset, release, curved beam, warping
 - Abaqus `*DLOAD` 입력과 Domain distributed-load object
-- 기하·재료비선형, dynamics, contact, thermal effects
+- 승인된 fixed-load-factor nonlinear-static 범위를 벗어난 기하·재료비선형, dynamics,
+  contact, thermal effects
 - transverse shear stress와 torsional shear stress recovery
 - beam stress에 대한 Abaqus reference comparison
 - Abaqus, Nastran 또는 reference solver 직접 실행 자동화