docs: align feature guidance with adopted Refactor structure

2026-10-18 03:35:15 +09:00
parent 7562d5a303
commit 0635cec53d
19 changed files with 224 additions and 29 deletions
@@ -12,4 +12,4 @@
 - [Hex8 구조해석](hex8-structural-analysis/README.md)
 - [Shell 열전달](shell-transient-heat-transfer/README.md)
 - [계산 성능](calculation-performance/README.md)
- [C++ 모듈화](cpp-object-oriented-modular-refactoring/README.md)
+- [C++ 모듈화·Refactor 병합 현황과 이관 근거](cpp-object-oriented-modular-refactoring/README.md)
@@ -35,3 +35,13 @@ Hex8 기하 packet 수정본의 관련 Debug/Release82개씩, 독립 snapshot9,8
 그 수정본의 단일 동적 개발 실행은 native0·117.7986225초로 완료됐으나100초 목표 초과다.101 U frame 비교는 blocking PASS, 최대 relative RMS 약2.155586e-6이었다. Outer wrapper는 종료 자식의 null StartTime 처리에서1로 끝났고 실제 FESA native0·후속 comparator0과 구분한다. 이전135.9302297초와의 차이는 서로 다른 source의 단일 개발 표본이며 반복 통계나 특정 함수 비용이 아니다.

 Shell 명시 영 seed 이후 SW60 수집은 partial이며 collector native4·target 종료 미관측, increment1까지 진행했다. 함수 sample의 Jet 산술·할당·작은 MKL 호출·OpenMP spin은 비용 후보지만 sample 부재를 cache hit 보장으로 바꾸거나 nested inclusive CPU를 합산해 wall time을 만들지 않는다. 전체 shell100초·최종 전체 Debug·원본5개 재실행·최종 물리 평가는 미완료다. 보류 후보의 PASS를 복원 source나 최신 통합본에 승계하지 않는다.
+
+## Refactor 채택 시 보존할 성능 한계
+
+Refactor의 2026-10-16 `0b8de3a` 당시 기록은 ShellNL whole elapsed가 원본 대비
+Native+86.52%·CMake+120.91% 회귀했다고 보고한다. 이는 해당 source·환경의 과거 단일 기록이며
+변산·메모리·배경 부하와 원인은 미확정이다. 이후 객체 복사 제거 revision의 정적 검증을
+새 Release 성능 향상으로 승계하지 않는다. 원본 `.build` archive는 통합 작업 공간으로
+자동 전달되지 않았으며 이번 병합에서 해당 시간의 원시 근거를 새로 재현한 것은 아니다.
+이번 작업은 제품 bytes를 채택하고 검증하는 범위다. 지속 SpMV cache나 새 산술 최적화를
+도입하지 않으며 성능 회귀 원인 해결·새 benchmark는 별도 작업으로 남긴다.
@@ -24,3 +24,54 @@ CLI는 입력 `.inp` 하나, lexical sibling HDF5·log, warning/오류 진단과
 - 과거 실행 절차를 현재 실행 계획으로 복원하지 않는다. CTest와 별도 Python suite의 성공을 합치지 않는다.

 이 문서 작업에서는 build/test를 실행하지 않았다. 당시 모듈화와 reference의 bounded 검증은 남기되 최신 전체 회귀·외부 배포 준비 완료를 선언하지 않는다. 현재 물리적 미해결 사항은 각 기능 README가 소유한다.
+
+## Refactor 코드 채택 후 구조
+
+2026-10-18 통합은 FESADev `7438c827` 이력에 Refactor `11f09eeb`의 제품 `.h/.cpp`
+274개와 직접 MSVC 빌드를 선별 도입한다. 옛 구현을 섞는 호환 계층이나 새 정식화는 추가하지 않는다.
+[파일 manifest](merge-manifest.json)는 원본 Git blob과 working bytes, 보존·도입 방침을 구분하고,
+[테스트 이관표](test-migration.tsv)는 양쪽 기존 identity·assertion·oracle와 최종 위치를 연결한다.
+
+- [AnalysisProcedure](../../include/fesa/analysis/analysis_procedure.h)와
+  [factory](../../src/fesa/analysis/prepared_analysis.cpp)는 shell linear/nonlinear static,
+  eigen, HHT, thermal과 solid static/frequency/HHT를 선택한다. 실행 수명은 호출자 adapter보다 짧다.
+  [PreparedAnalysisOutcome](../../include/fesa/analysis/prepared_analysis_outcome.h)은 family별
+  typed completed payload를 유지하고, [결과 dispatch](../../src/fesa/results/prepared_results_writer.cpp)는
+  검증된 payload를 해당 writer로 보낸다. 기존 schema·atomic finalize 의미는 유지한다.
+- [Element capabilities](../../include/fesa/elements/element_capabilities.h)는 ShellTrialElement,
+  SolidTrialElement, ShellInertiaElement, ThermalElement, ShellReferenceElement를 분리한다.
+  Adapter는 immutable kernel을 빌리므로 kernel의 수명과 주소가 안정적이어야 한다.
+  Equation·accepted history는 요소에 두지 않는다. Local layout과 full response를 typed로 보존한다.
+- [EquilibriumAlgorithm/EquilibriumStep](../../src/fesa/analysis/equilibrium_algorithm.h)는
+  iteration 순서와 procedure-local typed pending candidate를 분리한다. Algorithm은 candidate를
+  소유하거나 type-erase하지 않는다. Static은1, mechanical HHT는0에서 시작하는 inclusive 순서를 유지하고,
+  procedure의 검증·commit 경계가 accepted state를 바꾼다.
+- [ShellHhtIntegrator](../../src/fesa/analysis/hht_reduced_integrator.h)는 predictor·rate 계산·
+  physical-rate 복원을 분리한다. Chart/root/solver와 callback은 동기 borrowed view이며
+  rate 출력 buffer는 호출자 소유로 입력·서로와 alias하지 않는다. `RunReducedHhtStep`은
+  predictor→pending endpoint→commit 순서만 조정하고 accepted history를 소유하지 않는다.
+- [PARDISO Session](../../src/fesa/solvers/linear/pardiso_session.h)은 private factor/solve/release
+  수명을 공통화한다. 기존1×1 TLS 회피의 범위를 vendor 전체 해결로 확대하지 않는다.
+  [SparsePattern](../../include/fesa/math/sparse_pattern.h)은 CSR 값 구조이며 지속 backend cache가 아니다.
+  [SpMV](../../src/fesa/math/sparse_matrix.cpp)는 여전히 호출마다 변환 배열·값 복사·handle을 소유한다.
+
+수식·적분·reduction 순서·cache 수명에 영향이 있는 도입 차이는 manifest에 따로 분류했다.
+출처 일치·compile·테스트 통과만으로 수치 동등성을 선언하지 않으며 독립 수치 검토와
+영향받은 analytical/invariant·물리·reference 검증을 별도로 수행한다.
+
+## 이번 병합의 현재 검증 상태
+
+직접 MSVC와 CMake/Ninja의 Debug solver/CLI 및 세 테스트 target build가 완료됐다.
+제품274개는 Refactor working bytes와 일치한다. 양쪽 실제 discovery는 unit849,
+integration72, reference43으로 총964개이며 canonical identity가 일치한다.
+최종 선별 실행은 CMake176개, Native15개, 합성 reference comparator28개,
+Python145개가 failure/error/skip 없이 통과했다. 이는 전체964개 실행·실제 모델 비교 완료가 아니다.
+근거는 작업 공간의 `.build/merge-verification/t2-20261018-01/`와
+`t3-20261018-01/`에 있다. 원래 dev와 Refactor 저장소 및 기준자료는 보존했다.
+
+2026-10-18 사용자 지시로 `reference/temp`는 검증에 사용하지 않는다. 정식 경로에 없는
+`shellNL-meshfine`, `shellNL-meshfine_02`, `shellNL-meshfine-pressure` 자료는 복사·복원하지 않는다.
+해당 실제 비교는 자료 미확보로 미완료이며 테스트를 skip 처리하거나 통과로 바꾸지 않는다.
+전체 Debug 검증·독립 수치 검토·정식 자료의 필수 비교는 후속 실행 대상이다.
+정리 전 필수 검증을 충족하지 못하면 테스트 삭제와 최종 병합 완료 판정을 진행하지 않는다.
+문서 갱신 자체로 build/test를 추가 실행하지 않았다.
@@ -120,3 +120,11 @@ Reduced/hybrid/incompatible/20절점, plasticity/contact, mixed shell-solid, pre
 warped stability·남은 bending shear locking, 임의 큰 변형/mesh/시간간격은 일반 보증 범위 밖이다.
 원본 U 일치만으로 physical a·장시간 에너지·전체 시간수렴을 검증했다고 주장하지 않는다.
 최적화 후 최종 source의 전체 MSVC Debug build/CTest·필수 원본·독립 물리 확인이 남는다.
+
+## 통합된 local 경계
+
+[SolidTrialElement/Hex8TrialAdapter](../../include/fesa/elements/element_capabilities.h)가 같은
+stable-address immutable Hex8 kernel의 stiffness·reference mass·paired response를 빌린다.
+Adapter에 equation·trial history를 옮기지 않으며 원래 paired 산술·실패 경계를 유지한다.
+공통 procedure·typed pending과 결과 dispatch는 [모듈화 요약](../cpp-object-oriented-modular-refactoring/README.md)을 따른다.
+Frequency 비교는 `reference/hexa/hexa_freq.txt`의 modal Value를 직접 사용한다.
@@ -126,4 +126,13 @@ C08b finer-grid·최신 최적화 source의 원본 HDF5 비교·전체 회귀·
 | --- | --- |
 | [2026-10-04 본식](formulation-historical-docs-cleanup-20261004.md), [관성 원본](formulation-inertia-historical-docs-cleanup-20261004.md) | 당시 consistent 정책의 수식·검토 이력이다. 현재 lumped/reduced/fixed-null 정책이 우선한다. |
 | [C08b Newton 연구](formulation-c08b-newton-research-20261012.md), [DAE 연구](formulation-dae-research-20261012.md) | 원인·후보 조사이며 모든 Newton/DAE 후보의 채택을 뜻하지 않는다. |
-| [운동량 연구](formulation-momentum-research-20261012.md), [graph certificate 초안](formulation-graph-certificate-draft-20261012.md) | 불변량·controller/certificate 연구의 원본이다. 현재 acceptance나 엄밀한 전역 오차 보증을 자동 대체하지 않는다. |
+| [운동량 연구](formulation-momentum-research-20261012.md), [graph certificate 초안](formulation-graph-certificate-draft-20261012.md) | 불변량·controller/certificate 연구의 원본이다. 현재 acceptance나 엄밀한 전역 오차 보증을 자동 대체하지 않는다. |
+
+## 통합된 실행 경계
+
+공통 [AnalysisProcedure](../../include/fesa/analysis/analysis_procedure.h) 선택 뒤 reduced 절차를 실행한다.
+[ShellHhtIntegrator](../../src/fesa/analysis/hht_reduced_integrator.h)는 predictor/rate 복원을,
+[EquilibriumStep](../../src/fesa/analysis/equilibrium_algorithm.h)은0부터 시작하는 correction과
+typed pending을 분리한다. History는 procedure가 소유하고 동일 acceptance 뒤 commit한다.
+빌드·선별 검사 결과는 [통합 현황](../cpp-object-oriented-modular-refactoring/README.md)을 따르며,
+과거 interrupted run·finest binary64 noise의 미판정을 새 전체 통과로 바꾸지 않는다.
@@ -48,7 +48,10 @@ 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`이다.
+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는 바꾸지 않는다.

 ## 구현과 상태 수명

@@ -70,3 +73,13 @@ 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`로 대체하지 않는다. 정식 자료가 확보되어야
+hash·source identity·comparator 지원을 확인하고 실제 비교를 재개할 수 있다.
@@ -53,7 +53,9 @@ 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`을 사용한다.
+Nonlinear accepted free residual은 [비선형 정적 기준](../nonlinear-static-newton-raphson/README.md)을
+따르고, factor-one 전역 force/moment balance는 각각 normalized `<=1e-8`이다.
+이는 [기존 pressure 정식화](formulation.md)의 승인 범위이며 linear 정적 기준과 구분한다.

 ## 구현과 수명

@@ -75,3 +77,10 @@ DSLOAD와 DLOAD의 부호 규칙을 섞거나 reference area로 follower load를
 같은 trial의 force/tangent를 함께 써야 Newton 일관성을 유지한다.
 외부 displacement 일치만으로 압력 tangent나 local reaction 정확성을 추론하지 않는다.
 한 개의 지정 shell pressure bundle은 arbitrary closed surface·offset face·contact pressure 검증이 아니다.
+
+## 통합 시 기준자료 상태
+
+정식 `reference/shellNL-meshfine-pressure/` 자료가 없어 실제 pressure bundle 비교는 미완료다.
+2026-10-18 사용자 지시에 따라 `reference/temp`는 검증에 사용하지 않으며 임시 묶음을 승격하지 않는다.
+Kernel·synthetic comparator 검사가 실제 pressure reference 통과를 대신하지 않는다.
+정식 자료 확보 후 원본 hash·source/frame 대응을 확인하고 작업 복사본으로 재검증해야 한다.
@@ -131,3 +131,11 @@ hash-checked 입력의 유일 instance와 결합하며 node source identity로 b
 접합부는 검증 한계다. 단일 NT11 시점으로 다른 station·flux·반력·전체 시간 정확도를
 검증했다고 주장하지 않는다.
 Dev 통합 승인은 새 필수 reference 통과 승인이 아니다.
+
+## 통합된 kernel 경계
+
+[ThermalElement/Ds4ThermalAdapter](../../include/fesa/elements/element_capabilities.h)는 immutable
+DS4 kernel을 빌리고 DOF11–15 layout·K/C와 interval·복구를 typed로 제공한다.
+Kernel의 주소·수명은 adapter보다 안정적이어야 한다. Thermal state·잔차 인증·accepted history와
+writer 실패 경계는 그대로 procedure/state/writer에 남는다. 전체 검증 대상에 과도 열해석도 포함하며,
+새 필수 reference 미확보와 기존 NT11 diagnostic 불일치를 통과로 바꾸지 않는다.
@@ -1,6 +1,6 @@
 # 솔버 공통 구조와 계약

-FESA는 C++17 이상·Windows MSVC x64 Debug·CMake/CTest를 기준으로 하는 개인 연구용 솔버다. 승인된 Abaqus 입력 subset을 독립 모델로 해석하고 HDF5를 쓴다. Source spelling의 수용은 Abaqus 내부 요소·적분·알고리즘과의 동등성을 뜻하지 않는다. 외부 배포 형태·지원 환경·dependency 재배포 조건은 아직 정해지지 않았다.
+FESA는 C++17 이상·Windows MSVC x64 Debug·직접 MSBuild와 CMake/CTest를 기준으로 하는 개인 연구용 솔버다. 승인된 Abaqus 입력 subset을 독립 모델로 해석하고 HDF5를 쓴다. Source spelling의 수용은 Abaqus 내부 요소·적분·알고리즘과의 동등성을 뜻하지 않는다. 외부 배포 형태·지원 환경·dependency 재배포 조건은 아직 정해지지 않았다.

 ## 책임과 수명

@@ -49,23 +49,56 @@ Configure/build/test의 compiler·구성·build tree를 함께 맞추고 discove

 ## 빌드와 직접 검사

-MSVC x64 Developer PowerShell에서 저장소 root를 작업 디렉터리로 사용한다. CMake3.25 이상,
-Ninja, 로컬 GoogleTest source checkout과 MKL·TBB·HDF5 개발 package가 필요하다.
-`FESA_GTEST_SOURCE_DIR`은 GoogleTest의 CMakeLists.txt가 있는 source root이고,
-`MKL_DIR`·`TBB_DIR`·`HDF5_DIR`은 각각 package config 파일이 있는 디렉터리다.
-환경 변수에 로컬 경로를 지정한 뒤 [CMake presets](../../CMakePresets.json)의 직접 명령을 사용한다.
+직접 관리하는 [FESA.sln](../../FESA.sln)과 [msvc 지침](../../msvc/AGENTS.md)이 주 개발 빌드다.
+VS x64 개발 환경에서 저장소 root를 작업 디렉터리로 사용한다. v145 toolset과 로컬
+GoogleTest source checkout, MKL ILP64/dynamic/Intel threading·TBB·HDF5·OpenMP가 필요하다.
+`FESA_GTEST_SOURCE_DIR`, `FESA_MKL_ROOT`, `FESA_TBB_ROOT`, `FESA_HDF5_ROOT`,
+`FESA_OMP_ROOT`에 설치 root를 지정하거나 ignored `msvc/Fesa.Local.props`로 주입한다.
+개인 설치 경로를 추적 파일에 고정하거나 dependency를 자동 다운로드하지 않는다.

-```powershell
-cmake --preset windows-msvc-ninja-debug
-cmake --build --preset windows-msvc-ninja-debug
-ctest --preset windows-msvc-ninja-debug --show-only=json-v1
-ctest --preset windows-msvc-ninja-debug --output-on-failure
+```bat
+MSBuild FESA.sln /m:2 /p:Configuration=Debug /p:Platform=x64
+.build\native\Debug\tests\fesa_unit_tests.exe
+.build\native\Debug\tests\fesa_integration_tests.exe
+.build\native\Debug\tests\fesa_reference_tests.exe
 ```

-Debug build tree는 `build/windows-msvc-ninja-debug`, 별도 Release는
-`build/windows-msvc-ninja-release`이며 configure/build preset 이름도 각각 대응한다.
-Debug와 Release의 binary·test inventory·evidence를 섞지 않는다. CTest discovery와 실제
-종료 코드를 함께 확인한다. Python 검사가 필요하면 해당 suite를 별도로 실행하며 CTest에
-포함됐다고 추론하지 않는다. [CMake](../../CMakeLists.txt)의 `fesa_docs` target은 Doxygen을
-찾았을 때만 생성되므로 선택적 API 문서 산출물이다. CLI executable은 각 build tree의
-`src/fesa/fesa.exe`이며 dependency runtime DLL을 함께 준비한다.
+Native CLI는 `.build/native/Debug/src/fesa/fesa.exe`이며 테스트 executable은
+`.build/native/Debug/tests/`에 있다. Release는 같은 구조의 `Release` 디렉터리다.
+직접 MSBuild에 CMake·Ninja·Doxygen을 선행 조건으로 추가하지 않는다.
+
+보조 경로는 CMake3.25 이상·Ninja·동일 MSVC 환경을 사용한다. `MKL_DIR`·`TBB_DIR`·
+`HDF5_DIR`은 각각 config package 디렉터리다. 한국어 MSVC의 include 추적을 위해
+configure/build 모두 code page 65001을 사용한다.
+
+```bat
+chcp 65001
+cmake --preset windows-msvc-ninja-debug
+cmake --build --preset windows-msvc-ninja-debug --parallel 2
+ctest --preset windows-msvc-ninja-debug --show-only=json-v1
+ctest --preset windows-msvc-ninja-debug --output-on-failure -j 1
+python -m pytest tests -q
+```
+
+[Presets](../../CMakePresets.json)의 Debug tree는 `.build/cmake-debug`, Release는
+`.build/cmake-release`다. CMake CLI도 각 tree의 `src/fesa/fesa.exe`에 있다.
+Debug/Release의 binary·DLL·검사 목록·실행 근거를 섞지 않는다. AVX2는 전용 Hex8
+source에만 적용하며 CRT·정밀도·source·link·runtime DLL과 검사 identity를 두 경로에서 대조한다.
+`fesa_docs`는 Doxygen을 찾았을 때만 생기는 선택적 target이다.
+
+현재 통합 검증은 세 C++ executable의 전체 등록 검사와 별도 Python suite를 대상으로 한다.
+과거 Refactor의 정적 선별 실행을 이번 전체 실행으로 승계하지 않는다. Native/CTest는
+서로 다른 실행 전용 TMP/TEMP와 raw 출력 경로를 사용해 직렬 실행한다. 상속된 필터·sharding을
+제거하고 실제 identity·수·exit·XML/log를 discovery와 대조한다. Skip·0건·자료 누락은 PASS가 아니다.
+모델은 hash가 확인된 새 작업 복사본에서만 실행한다. `reference/temp`는 검증에 사용하지 않는다.
+현재 진행 결과와 미완료 비교는 [병합 현황](../cpp-object-oriented-modular-refactoring/README.md)에 기록한다.
+
+## 공통 procedure와 결과 경계
+
+[PrepareAnalysisInput/CreateAnalysisProcedure](../../include/fesa/analysis/prepared_analysis.h)는
+한 번 mapping한 Domain에서 한 family를 선택한다. `AnalysisProcedure::Execute`는
+[typed outcome](../../include/fesa/analysis/prepared_analysis_outcome.h)을 반환하며 파일을 열지 않는다.
+Domain과 주입된 solver·parallel·log adapter는 실행 동안 살아 있고 이동하지 않아야 한다.
+App이 로그 close 성공을 확인한 뒤 `FinalizePreparedAnalysisResult`가
+[WritePreparedAnalysisResult](../../include/fesa/results/prepared_results_writer.h)로 연결한다.
+필요한 writer 부재는 output failure이며 다른 결과 family로 위장하지 않는다.