modify docu and reference

2026-08-28 00:32:30 +09:00
parent 41816c8aef
commit ca06b4b551
37 changed files with 30338 additions and 590 deletions
@@ -0,0 +1,191 @@
+# Step 11: reference-comparison-gate
+
+## 읽어야 할 파일
+
+- `AGENTS.md`
+- `docs/TOLERANCE.md`
+- `docs/nonlinear-static-newton-raphson/reference-model.md`
+- `docs/nonlinear-static-newton-raphson/io.md`
+- `docs/nonlinear-static-newton-raphson/numerical-review.md`
+- `tests/reference/reference_tolerance_policy.h`
+- `tests/reference/reference_tolerance_policy.cpp`
+- `tests/reference/reference_comparison.h`
+- `tests/reference/reference_comparison.cpp`
+- `tests/reference/mitc4_reference_comparison.h`
+- `tests/reference/mitc4_reference_comparison.cpp`
+- Step 9 files: `include/fesa/results/nonlinear_results_writer.h`, `include/fesa/io/hdf5/nonlinear_hdf5_results_writer.h`
+- Step 10 files: `include/fesa/analysis/prepared_analysis.h`, `src/fesa/app/fesa_application.cpp`
+
+## 이전 Step 전제
+
+Step 10 runs copied input files through FESA and writes authoritative HDF5 outputs after log close.
+
+## 소유 파일
+
+- Create: `tests/reference/nonlinear_static_reference_comparison.h`
+- Create: `tests/reference/nonlinear_static_reference_comparison.cpp`
+- Create: `tests/reference/nonlinear_static_reference_cases_test.cpp`
+- Modify: `tests/CMakeLists.txt`
+
+## 인터페이스
+
+```cpp
+namespace fesa::test {
+
+struct NonlinearReferenceCase {
+  std::string case_id;
+  std::filesystem::path original_input_path;
+  std::filesystem::path displacement_csv_path;
+  std::filesystem::path reaction_csv_path;
+  std::filesystem::path stress_inventory_path;
+  std::filesystem::path execution_directory;
+};
+
+struct ArtifactSnapshot {
+  std::filesystem::path path;
+  std::string sha256;
+  std::uintmax_t byte_size;
+  std::filesystem::file_time_type last_write_time;
+};
+
+enum class NonlinearReferenceDisposition {
+  kBlocking,
+  kWarningOnly,
+  kExcluded
+};
+
+struct NonlinearReferenceRowKey {
+  std::string case_id;
+  std::string accepted_state;
+  std::string instance_name;
+  std::int64_t source_node_label;
+  std::string component;
+};
+
+struct NonlinearReferenceFamilyReport {
+  std::string family_identity;
+  std::vector<std::string> components;
+  NonlinearReferenceDisposition disposition;
+  std::size_t row_count;
+  ReferenceToleranceFamilyDecision tolerance;
+};
+
+struct GeneratedRunArtifacts {
+  std::filesystem::path copied_input_path;
+  std::filesystem::path generated_results_hdf5;
+  std::filesystem::path generated_log_path;
+};
+
+struct NonlinearReferenceComparisonReport {
+  std::string case_id;
+  std::filesystem::path original_input_path;
+  std::filesystem::path copied_input_path;
+  std::filesystem::path generated_results_hdf5;
+  std::filesystem::path generated_log_path;
+  std::vector<ArtifactSnapshot> pre_run_artifacts;
+  std::vector<ArtifactSnapshot> post_run_artifacts;
+  std::vector<NonlinearReferenceFamilyReport> families;
+  bool blocking_passed;
+};
+
+enum class NonlinearReferenceClassification {
+  kPassed,
+  kFailed,
+  kWarningOnlyDifferences
+};
+
+Result<std::vector<ArtifactSnapshot>> ArtifactCheck(
+    const NonlinearReferenceCase& reference_case);
+Result<std::filesystem::path> CopyInputToExecutionDirectory(
+    const NonlinearReferenceCase& reference_case);
+Result<GeneratedRunArtifacts> RunFesaApplicationOnCopiedInput(
+    const NonlinearReferenceCase& reference_case,
+    const std::filesystem::path& copied_input_path);
+Result<NonlinearReferenceComparisonReport> CompareHdf5ToReferenceCsv(
+    const NonlinearReferenceCase& reference_case,
+    const std::filesystem::path& hdf5_results_path);
+NonlinearReferenceClassification ClassifyReferenceComparison(
+    const NonlinearReferenceComparisonReport& report);
+NonlinearReferenceComparisonReport BuildReferenceComparisonReport(
+    const NonlinearReferenceCase& reference_case,
+    const std::filesystem::path& hdf5_results_path);
+
+}  // namespace fesa::test
+```
+
+## RED
+
+Add tests first.
+
+- `NSNR-REF-001`: artifact check verifies exact pre-run SHA-256 for every declared input/CSV path.
+- `NSNR-REF-002`: original `reference/shellNL/shellNL.inp` bytes are copied unchanged into a unique build-local temp case directory and only the copied `.inp` is passed to `FesaApplication`.
+- `NSNR-REF-003`: original `reference/shell/shell.inp` bytes are copied unchanged into a unique build-local temp case directory and only the copied `.inp` is passed to `FesaApplication`.
+- `NSNR-REF-004`: copied shellNL run produces copied-sibling `shellNL_results.h5` and `shellNL_log.txt`; copied shell run produces copied-sibling `shell_results.h5` and `shell_log.txt`.
+- `NSNR-REF-005`: HDF5 source path identity matches the copied user-addressed input path, and source content identity matches the approved original input hash.
+- `NSNR-REF-006`: exact post-run SHA-256, byte size, timestamp, and inventory for all original declared reference artifacts match pre-run snapshots.
+- `NSNR-REF-007`: shellNL displacement/reaction rows require exact `Frame` value `Increment     10: Step Time =    1.000`.
+- `NSNR-REF-008`: required CSV wide rows expand to unique `(case_id, accepted_state, instance, source_node_label, component)` keys.
+- `NSNR-REF-009`: HDF5 rows and CSV rows reject missing, extra, duplicate, and nonfinite required rows before tolerance.
+- `NSNR-REF-010`: `linear.translation` has 147 blocking rows.
+- `NSNR-REF-011`: `linear.rotation` has 147 warning-only rows.
+- `NSNR-REF-012`: `nonlinear.translation` has 147 blocking rows.
+- `NSNR-REF-013`: `nonlinear.rotation` has 147 warning-only rows.
+- `NSNR-REF-014`: shellNL constrained nodes select only labels `1,3,4,5,6,7,8,9,14,15,16,17,22,23,24,25,26,27,28,29,30,31,32,33`.
+- `NSNR-REF-015`: `RF1/RF2` has 48 blocking rows, `RF3` has 24 blocking rows, and `RM1/RM2` has 48 blocking rows.
+- `NSNR-REF-016`: `RM3` and stress quantities create no numeric comparison family.
+- `NSNR-REF-017`: docs/TOLERANCE.md family policy is applied exactly and warning-only failures do not change blocking verdict.
+- `NSNR-REF-018`: stress CSV files are hash-audited as nonblocking inventory artifacts and their schema/order is not a blocking verdict.
+
+Run:
+
+```powershell
+cmake --build .harness/build --config Debug
+ctest --test-dir .harness/build -C Debug -R "NonlinearStaticReference|ReferenceTolerance|Mitc4Reference" --output-on-failure
+```
+
+Expected: new tests fail. Unexpected pass stops.
+
+## GREEN
+
+Implement `ARTIFACT CHECK -> COPY -> RUN -> COMPARE -> CLASSIFY -> REPORT` while preserving the required public gate wording `ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT` in reports. The runner never passes the original reference input path to `FesaApplication`; it copies input bytes unchanged into a unique build-local temp case directory, runs the copied `.inp`, consumes copied-sibling `_results.h5` and `_log.txt`, and compares HDF5 data to original read-only CSVs. Use exact declared paths and hashes:
+
+| path | rows | SHA-256 |
+| --- | ---: | --- |
+| `reference/shellNL/shellNL.inp` | input | `4BF3ECB0F7F1E8462C573E993DBC97AC5D920C91CF6F23AD4C6891D77FFBADA2` |
+| `reference/shellNL/shellNL displacements.csv` | 49 | `4E0F99CA9372B1ADF7FAF102F43BC0B887DC743FDEDA378E4342D2CF8E0C0786` |
+| `reference/shellNL/shellNL reactions.csv` | 49 | `001CB1541A9E94424E5E650509D46BC8724970DF4DE47184D9DB09C7938AB069` |
+| `reference/shellNL/shellNL stresses.csv` | 288 | `5500E5114B1C44887528E30CEC054A1EB0F68BE3F4B8CE81FA59FC74A881483F` |
+| `reference/shell/shell.inp` | input | `4005851E1AB22FD3A16AC17A8D5DA3E051233F69F37419079F3553AD134ECFCF` |
+| `reference/shell/shell displacements.csv` | 49 | `C81D94E0B4A849F87AA0F79C83A79B94D5661AC79E44ED826919AB432C87746B` |
+| `reference/shell/shell reactions.csv` | 49 | `0E34EEC27E700C3C0C744C1DAFD8A3B95EFEF34B8616FE96665876586FE82D41` |
+| `reference/shell/shell stresses.csv` | 288 | `2B75A5B0DEB045A283C9BB7E9B1153B79F7537FF487214BF4A23316B59B660A7` |
+
+Use docs/TOLERANCE.md exactly: family scale `S=max(abs(reference))`, near-zero band `0.01*S`, non-near relative error `<=0.05`, family `RMS(error)/S<=0.01`, zero-scale exact zero only. Original reference directory inventory, bytes, timestamps, and hashes must be unchanged after the run.
+
+## VERIFY
+
+```powershell
+cmake --fresh -S . -B .harness/build -G "Visual Studio 18 2026" -A x64 `
+  "-DFESA_GTEST_SOURCE_DIR=$gtestSource" `
+  "-DMKL_DIR=$mklDir" `
+  "-DTBB_DIR=$tbbDir" `
+  "-DHDF5_DIR=$hdf5Dir"
+cmake --build .harness/build --config Debug
+ctest --test-dir .harness/build -C Debug -R "NonlinearStaticReference|ReferenceTolerance|Mitc4Reference" --output-on-failure
+ctest --test-dir .harness/build -C Debug --show-only=json-v1
+ctest --test-dir .harness/build -C Debug --output-on-failure
+```
+
+Recheck `.harness/config.json` before default commands.
+
+## 상태 기록
+
+Update only Step 11 status and one-line payload. Executor owns timestamps, commits, retry, and advancement.
+
+## 금지사항
+
+- Do not rewrite, rename, normalize, or repair `.inp` or CSV artifacts. 이유: reference artifacts are immutable external evidence.
+- Do not run `FesaApplication` on original `reference/shellNL/shellNL.inp` or `reference/shell/shell.inp`. 이유: CLI derives sibling outputs and would mutate the reference directory.
+- Do not compare `RM3`. 이유: approved contract excludes stabilization-dependent drilling reaction.
+- Do not numerically compare stress CSV data. 이유: stress artifacts are nonblocking inventory only in this feature.
+- Do not average, omit, synthesize, or row-order match reference rows. 이유: source/component identity prechecks are mandatory.