modify documents

2026-06-11 11:08:27 +09:00
parent 98eba54a12
commit 986cc9888e
35 changed files with 1984 additions and 169 deletions
@@ -2,7 +2,7 @@

 이 디렉터리는 Reference Model Agent가 작성하거나 제안한 기능별 reference model 설계 문서를 보관하는 위치다.

-Reference Model Agent는 FESA 기능 검증에 필요한 Abaqus `.inp` 기반 테스트 모델 포트폴리오와 `references/<feature-id>/<model-id>/` artifact bundle 계약을 정의한다. Agent는 Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않고, reference CSV 값을 생성하지 않으며, solver 결과 비교나 release readiness 승인도 하지 않는다.
+Reference Model Agent는 Abaqus User Subroutine 검증에 필요한 Abaqus `.inp` 기반 테스트 모델 포트폴리오와 `references/<feature-id>/<model-id>/` artifact bundle 계약을 정의한다. Agent는 Abaqus 해석을 직접 실행하지 않고, reference CSV 값을 생성하지 않으며, solver 결과 비교나 release readiness 승인도 하지 않는다.

 기본 파일명은 `docs/reference-models/<feature-id>-reference-models.md` 형식을 사용한다. 각 문서는 요구조건, 연구 브리프, 정식화, 수치 리뷰, I/O 정의를 입력으로 받아 구현 전에 준비해야 할 테스트 모델과 reference artifact 요구사항을 정의해야 한다.

@@ -17,10 +17,10 @@ Reference Model Agent는 FESA 기능 검증에 필요한 Abaqus `.inp` 기반
 - requirement와 model, compared quantity, tolerance, artifact status를 연결하는 Coverage Matrix를 작성한다.

 수행하지 않는다:
- C++ 코드를 구현하지 않는다.
+- Fortran 코드를 구현하지 않는다.
 - parser를 구현하지 않는다.
- C++ API나 파일 구조를 설계하지 않는다.
- Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않는다.
+- Fortran source layout이나 파일 구조를 설계하지 않는다.
+- Abaqus 해석을 직접 실행하지 않는다.
 - reference CSV를 생성하지 않는다.
 - solver 결과를 비교하지 않는다.
 - release readiness를 승인하지 않는다.
@@ -67,7 +67,7 @@ Reference Model Agent는 FESA 기능 검증에 필요한 Abaqus `.inp` 기반
 - purpose: <what this model proves>
 - verified_requirements: [<requirement-id>]
 - analysis_type: <linear static | nonlinear static | modal | other>
- element_type: <Abaqus element type and FESA feature element>
+- element_type: <Abaqus element type and subroutine feature scope>
 - material: <material model and values>
 - boundary_conditions: <BC summary>
 - loads: <load summary>
@@ -92,25 +92,33 @@ references/
    <model-id>/
      model.inp
      metadata.json
-      displacements.csv
-      reactions.csv
-      element_forces.csv
-      stresses.csv
+      job.msg.tail.txt
+      job.dat.tail.txt
+      job.log.tail.txt
+      job.sta.tail.txt
+      result.odb.sha256
+      extraction/
+        extract_odb_to_csv.py
+      extracted/
+        displacements.csv
+        reactions.csv
+        element_forces.csv
+        stresses.csv
      README.md
 ```

 Required files:
 - `model.inp`: Abaqus input file for the reference model.
 - `metadata.json`: provenance and model contract metadata.
- `displacements.csv`: nodal displacement reference results.
- `reactions.csv`: nodal reaction force reference results.
- `element_forces.csv`: element internal force reference results.
- `stresses.csv`: stress reference results.
+- `.msg/.dat/.log/.sta` tail files: externally generated Abaqus job evidence.
+- `extracted/*.csv`: ODB-extracted CSV reference results declared in `metadata.json`.
 - `README.md`: short description, generation notes, and limitations.

 Optional files:
- `strains.csv`: strain reference results when required.
- `energy_or_residual.csv`: energy, residual, or convergence reference results when required.
+- `result.odb.sha256`: ODB hash evidence when the ODB itself is not stored.
+- `extraction/extract_odb_to_csv.py`: copy of the user-run extraction script when available.
+- `extracted/strains.csv`: strain reference results when required.
+- `extracted/energy_or_residual.csv`: energy, residual, or convergence reference results when required.
 - `notes.md`: manual review notes.

 ## Metadata JSON Contract
@@ -216,8 +224,7 @@ For Fortran Abaqus UserSubroutine work, each stored artifact bundle may include
  "artifact_status": "draft | needs-reference-artifacts | ready-for-comparison | blocked",
  "abaqus": {
    "version": "<Abaqus version>",
-    "precision": "single | double",
-    "command": "abaqus job=<job> user=<subroutine>"
+    "precision": "single | double"
  },
  "compiler": {
    "vendor": "Intel oneAPI",
@@ -239,13 +246,59 @@ For Fortran Abaqus UserSubroutine work, each stored artifact bundle may include
    "tails": {
      "msg": "job.msg.tail.txt",
      "dat": "job.dat.tail.txt",
-      "log": "job.log.tail.txt"
+      "log": "job.log.tail.txt",
+      "sta": "job.sta.tail.txt"
    },
    "csv": {
-      "stresses": "stresses.csv"
+      "stresses": "extracted/stresses.csv"
+    }
+  },
+  "extraction": {
+    "source_odb": "job.odb",
+    "tool": "Abaqus Python",
+    "extracted_at": "<ISO-8601 datetime>",
+    "csv_directory": "extracted",
+    "script": "extraction/extract_odb_to_csv.py",
+    "odb_sha256_file": "result.odb.sha256"
+  },
+  "comparisons": {
+    "stresses": {
+      "reference_csv": "extracted/stresses.csv",
+      "actual_csv": "extracted/stresses.csv",
+      "required_columns": [
+        "step",
+        "frame",
+        "instance",
+        "element_label",
+        "integration_point",
+        "section_point",
+        "output_position",
+        "component",
+        "coordinate_system",
+        "unit",
+        "value"
+      ],
+      "key_columns": [
+        "step",
+        "frame",
+        "instance",
+        "element_label",
+        "integration_point",
+        "section_point",
+        "output_position",
+        "component"
+      ],
+      "value_column": "value",
+      "unit_column": "unit",
+      "coordinate_system_column": "coordinate_system",
+      "tolerance": {
+        "absolute": 1.0e-8,
+        "relative": 1.0e-6,
+        "relative_floor": 1.0e-12
+      }
    }
  }
 }
 ```

-`artifact_status=ready-for-comparison` means `scripts/validate_reference_artifacts.py` must find all declared files and confirm source SHA-256 values. Agents must not generate or edit the declared reference CSVs unless an explicit reference-artifact phase authorizes that work.
+`artifact_status=ready-for-comparison` means `scripts/validate_reference_artifacts.py` must find all declared files, confirm source SHA-256 values, require `.msg/.dat/.log/.sta` tails, require ODB extraction provenance, and require declared CSVs to match `extracted/*.csv`. `comparisons` defines the executable CSV schema, row key, and tolerance contract for `scripts/compare_extracted_csv.py`. Agents must not generate or edit the declared reference CSVs unless an explicit reference-artifact phase authorizes that work.