docs: align FESA agents with minimal reference cases
This commit is contained in:
KOKO\Mimi
@@ -158,7 +158,8 @@ INTAKE -> STATE AUDIT -> GATE DECISION -> HANDOFF PACKAGE -> STATUS REPORT
|
||||
- `needs-formulation`: Formulation Agent가 FEM 정식화를 작성하거나 수정해야 한다.
|
||||
- `needs-numerical-review`: Numerical Review Agent가 정식화를 검토하거나 재검토해야 한다.
|
||||
- `needs-io-definition`: I/O Definition Agent가 Abaqus input/output 계약을 정의하거나 수정해야 한다.
|
||||
- `needs-reference-model`: Reference Model Agent가 reference model artifacts를 정의하거나 수정해야 한다.
|
||||
- `needs-reference-model`: Reference Model Agent가 lightweight reference-case inventory,
|
||||
required input/CSV presence, source-ID/component matching 또는 tolerance를 정의해야 한다.
|
||||
- `needs-implementation-plan`: Implementation Planning Agent가 TDD implementation plan을 작성하거나 수정해야 한다.
|
||||
- `ready-for-implementation`: implementation plan이 준비되었고 downstream 구현을 막는 upstream gate가 없다.
|
||||
- `needs-build-test`: 구현 이후 독립 Build/Test Executor 검증이 필요하다.
|
||||
|
||||
@@ -2,7 +2,10 @@
|
||||
|
||||
이 디렉터리는 Implementation Planning Agent가 작성하거나 제안한 기능별 구현계획 문서를 보관하는 위치다.
|
||||
|
||||
Implementation Planning Agent는 승인된 요구조건, 연구 브리프, 정식화, 수치 리뷰, I/O 정의, reference model 계약을 C++/MSVC 구현 전 TDD 작업계획으로 변환한다. Agent는 코드, 테스트, CMake 파일을 작성하지 않고, Abaqus/Nastran을 실행하지 않으며, Abaqus reference CSV 생성 또는 수정이나 solver 결과 비교, release readiness 승인도 하지 않는다.
|
||||
Implementation Planning Agent는 승인된 요구조건, 연구 브리프, 정식화, 수치 리뷰, I/O
|
||||
정의와 lightweight reference-case inventory를 C++/MSVC 구현 전 TDD 작업계획으로
|
||||
변환한다. Project-local `$harness`를 사용해 multi-Step 초안을 먼저 제시하고 사용자가
|
||||
승인한 뒤에만 `phases/` planning files를 생성한다.
|
||||
|
||||
기본 파일명은 `docs/implementation-plans/<feature-id>-implementation-plan.md` 형식을 사용한다. 각 문서는 Implementation Agent가 먼저 작성해야 할 실패 테스트, 최소 구현 순서, CMake/CTest 등록 계획, acceptance traceability를 제공해야 한다.
|
||||
|
||||
@@ -16,6 +19,9 @@ Implementation Planning Agent는 승인된 요구조건, 연구 브리프, 정
|
||||
- candidate source/header/test/CMake 파일과 ownership boundary를 제안한다.
|
||||
- requirement, task, test, reference model, acceptance criterion을 Acceptance Traceability Matrix로 연결한다.
|
||||
- `.harness/config.json` 또는 자동 감지 기본값에서 해석되는 MSVC build/test 명령과 feature-specific command를 명시한다.
|
||||
- 한 Step을 하나의 layer/module로 제한하고 prerequisite files, RED/GREEN/VERIFY, exact
|
||||
acceptance commands와 구체적 금지사항을 포함한다.
|
||||
- 사용자 승인 전에는 `phases/` 파일을 만들지 않고, 별도 요청 없이는 `scripts/execute.py`를 실행하지 않는다.
|
||||
|
||||
수행하지 않는다:
|
||||
- C++ 코드를 구현하지 않는다.
|
||||
@@ -96,8 +102,8 @@ Implementation Planning Agent는 승인된 요구조건, 연구 브리프, 정
|
||||
1. Abaqus `.inp` input follows docs/io-definitions/<feature-id>-io.md.
|
||||
2. Parser/I/O path maps model data and history data into the internal semantic model.
|
||||
3. Solver path produces authoritative `results.h5` with displacement, reaction, internal force, stress, or feature-specific result datasets.
|
||||
4. Reference artifacts are Abaqus-generated CSV files under `reference/<model-id>/`.
|
||||
5. Reference comparison tests compare FESA `results.h5` rows against `reference/<model-id>/<model-id>_*.csv` rows.
|
||||
4. Reference inputs and required CSV files use exact existing paths declared by the feature.
|
||||
5. Reference comparison tests compare only blocking/warning quantities by source ID/component.
|
||||
|
||||
## Acceptance Traceability Matrix
|
||||
|
||||
@@ -130,17 +136,28 @@ MSVC build/test를 다시 확인하며, 구현 보고서의 RED 실패 증거를
|
||||
- <likely failure classifications and upstream rollback guidance>
|
||||
|
||||
### Reference Verification Agent
|
||||
- <planned HDF5/CSV view comparison tests, reference model ids, tolerance mapping, ID matching assumptions>
|
||||
- <planned HDF5/CSV comparison tests, exact case paths, tolerance mapping, source-ID/component matching>
|
||||
|
||||
## Harness Step Draft
|
||||
|
||||
| step | name | owned layer/module | prerequisite files | RED/GREEN/VERIFY | acceptance commands | stop condition |
|
||||
| ---: | --- | --- | --- | --- | --- | --- |
|
||||
| 0 | <kebab-case> | <one scope> | <exact paths> | <test-first sequence> | <exact commands> | <condition> |
|
||||
|
||||
User approval is required before materializing this draft under `phases/`.
|
||||
|
||||
## Open Issues
|
||||
- <requirement, formulation, I/O, reference artifact, tolerance, or architecture issue>
|
||||
- <requirement, formulation, I/O, required comparison file/mapping, tolerance, or architecture issue>
|
||||
```
|
||||
|
||||
## 품질 기준
|
||||
|
||||
- 모든 `must` requirement는 최소 하나의 task와 test에 연결되어야 한다.
|
||||
- C++ production 변경마다 선행 테스트 파일 또는 테스트 추가 계획이 있어야 한다.
|
||||
- reference artifact가 필요한 기능은 `reference/<model-id>/`와 FESA HDF5-to-reference-CSV 비교 테스트 계획을 가져야 한다.
|
||||
- reference comparison이 필요한 기능은 exact existing input/required CSV path와 FESA
|
||||
HDF5-to-reference-CSV source-ID/component mapping test 계획을 가져야 한다.
|
||||
- Implementation Planning Agent는 Harness Step 초안을 사용자에게 승인받은 뒤에만 phase
|
||||
index와 step files를 생성하며 executor는 자동 실행하지 않는다.
|
||||
- CMake/CTest 계획은 MSVC x64 Debug 검증 경로와 호환되어야 한다.
|
||||
- 구현 계획은 테스트 작성, 실패 확인, 최소 구현, validation 순서를 명시해야 한다.
|
||||
- upstream 문서가 불완전하면 값을 임의로 채우지 않고 `needs-upstream-decision` 또는 `blocked`로 표시한다.
|
||||
|
||||
@@ -16,7 +16,7 @@ I/O Definition Agent는 Abaqus input file subset, 내부 solver model mapping, o
|
||||
- model data와 history data를 내부 solver 개념으로 매핑한다.
|
||||
- node, element, set, material, section, boundary condition, load, step, output request의 의미 계약을 정의한다.
|
||||
- `results.h5`의 authoritative HDF5 schema를 정의한다.
|
||||
- FESA HDF5 dataset을 `reference/<model-id>/` 아래 Abaqus reference CSV rows와 비교하기 위한 deterministic row schema를 정의한다.
|
||||
- 기능이 선언한 existing Abaqus CSV와 비교하기 위한 최소 source-ID/component mapping을 정의한다.
|
||||
|
||||
수행하지 않는다:
|
||||
- parser를 구현하지 않는다.
|
||||
@@ -123,58 +123,25 @@ I/O Definition Agent는 Abaqus input file subset, 내부 solver model mapping, o
|
||||
| element_force | /steps/<step>/frames/<frame>/field_outputs/element_forces | <nrow, ncomp> | float64 | component_names, element_ids, location | element | feature-dependent |
|
||||
| stress | /steps/<step>/frames/<frame>/field_outputs/S | <nrow, ncomp> | float64 | component_names, element_ids, integration_points | integration_point | feature-dependent |
|
||||
|
||||
## FESA HDF5 to Reference CSV Comparison Schema
|
||||
## FESA HDF5 to Reference CSV Comparison Mapping
|
||||
|
||||
FESA solver output은 `results.h5`이다. Comparison tooling reads required HDF5 datasets and maps them to deterministic row records that can be matched against Abaqus reference CSV files under `reference/<model-id>/`.
|
||||
FESA solver output은 `results.h5`이다. 기능이 blocking 또는 warning-only로 선언한
|
||||
quantity에 대해서만 existing CSV path와 다음 mapping을 정의한다.
|
||||
|
||||
공통 규칙:
|
||||
- reference_root: `reference/<model-id>/`
|
||||
- hdf5_schema_version: <version>
|
||||
- reference_csv_schema_version: <version>
|
||||
- sort_order: step, frame, id, location, component
|
||||
- numeric_format: <precision and exponent policy>
|
||||
- missing_component_policy: 0 | N/A | omitted, feature-specific
|
||||
- hdf5_dataset_source: HDF5 dataset path를 각 row schema 또는 report에 기록한다.
|
||||
| field | contract |
|
||||
| --- | --- |
|
||||
| reference_input | exact existing `.inp` path |
|
||||
| reference_csv | exact existing required CSV path |
|
||||
| hdf5_dataset | authoritative FESA dataset path |
|
||||
| source_identity | node/element source label used for exact matching |
|
||||
| components | required CSV columns and corresponding HDF5 components |
|
||||
| row_precheck | missing/extra/duplicate/nonfinite required rows fail before tolerance |
|
||||
| behavior | blocking or warning-only |
|
||||
| tolerance | upstream-approved formula |
|
||||
|
||||
### displacement rows / `<model-id>_displacements.csv`
|
||||
| column | type | description |
|
||||
| --- | --- | --- |
|
||||
| step | string | step name or index |
|
||||
| frame | integer | frame or increment id |
|
||||
| node_id | integer/string | Abaqus node label |
|
||||
| ux | float | displacement component |
|
||||
| uy | float | displacement component or 0/N/A |
|
||||
| uz | float | displacement component or 0/N/A |
|
||||
|
||||
### reaction rows / `<model-id>_reactions.csv`
|
||||
| column | type | description |
|
||||
| --- | --- | --- |
|
||||
| step | string | step name or index |
|
||||
| frame | integer | frame or increment id |
|
||||
| node_id | integer/string | Abaqus node label |
|
||||
| rfx | float | reaction component |
|
||||
| rfy | float | reaction component or 0/N/A |
|
||||
| rfz | float | reaction component or 0/N/A |
|
||||
|
||||
### internal force rows / `<model-id>_internalforces.csv`
|
||||
| column | type | description |
|
||||
| --- | --- | --- |
|
||||
| step | string | step name or index |
|
||||
| frame | integer | frame or increment id |
|
||||
| element_id | integer/string | Abaqus element label |
|
||||
| location | string | element/nodal/integration_point location |
|
||||
| component | string | force component name |
|
||||
| value | float | component value |
|
||||
|
||||
### stress rows / `<model-id>_stresses.csv`
|
||||
| column | type | description |
|
||||
| --- | --- | --- |
|
||||
| step | string | step name or index |
|
||||
| frame | integer | frame or increment id |
|
||||
| element_id | integer/string | Abaqus element label |
|
||||
| integration_point | integer/string | integration point id or N/A |
|
||||
| component | string | stress component name |
|
||||
| value | float | stress value |
|
||||
Row order alone으로 대응하지 않는다. Canonical filename, reference CSV schema version,
|
||||
README, metadata, provenance 또는 single-step/final-frame case의 duplicated unit/coordinate/
|
||||
step-frame columns를 요구하지 않는다.
|
||||
|
||||
## Validation Rules
|
||||
- required_fields: <required input fields>
|
||||
@@ -208,4 +175,5 @@ FESA solver output은 `results.h5`이다. Comparison tooling reads required HDF5
|
||||
- 내부 모델 계약은 semantic fields로 작성하고 C++ class/function/API를 확정하지 않는다.
|
||||
- `results.h5`가 authoritative solver output임을 명시해야 한다.
|
||||
- HDF5 schema는 dataset path, dtype/shape, required attributes, ID field, component naming, coordinate system, units, step/frame identity, quantity location을 포함해야 한다.
|
||||
- Reference CSV comparison row schema는 column name, stable sort order, ID field, component naming, coordinate system, units, step/frame identity, quantity location을 포함해야 한다.
|
||||
- Reference CSV comparison mapping은 exact path, source-ID column, required component columns,
|
||||
HDF5 projection, row prechecks와 tolerance를 포함해야 한다.
|
||||
|
||||
@@ -32,12 +32,12 @@ Numerical Review Agent는 정식화의 수학적 일관성, 수치 안정성 위
|
||||
## Metadata
|
||||
- feature_id: <feature-id>
|
||||
- source_formulation: docs/formulations/<feature-id>-formulation.md
|
||||
- status: pass-for-implementation-planning | needs-formulation-revision | needs-research | needs-reference-model | blocked
|
||||
- status: pass-for-implementation-planning | needs-formulation-revision | needs-research | blocked
|
||||
- owner_agent: numerical-review-agent
|
||||
- date: <YYYY-MM-DD>
|
||||
|
||||
## Review Verdict
|
||||
- verdict: pass-for-implementation-planning | needs-formulation-revision | needs-research | needs-reference-model | blocked
|
||||
- verdict: pass-for-implementation-planning | needs-formulation-revision | needs-research | blocked
|
||||
- reason: <판정 이유>
|
||||
|
||||
## Critical Findings
|
||||
@@ -82,7 +82,7 @@ Numerical Review Agent는 정식화의 수학적 일관성, 수치 안정성 위
|
||||
- <연구 보강 지시>
|
||||
|
||||
### Reference Model Agent
|
||||
- <reference model 또는 artifact 요구사항>
|
||||
- <optional downstream test note; not a formulation blocker>
|
||||
|
||||
## Downstream Handoff
|
||||
|
||||
@@ -99,4 +99,6 @@ Numerical Review Agent는 정식화의 수학적 일관성, 수치 안정성 위
|
||||
- `pass-for-implementation-planning`은 구현 계획으로 넘겨도 된다는 뜻이며 기능 완료나 release 승인이 아니다.
|
||||
- 정식화 문서를 직접 수정하지 않고 필요한 수정을 명확히 지시해야 한다.
|
||||
- 모든 검토는 dimension, sign, DOF ordering, coordinate transform, Jacobian, integration weight, element equation, output recovery를 포함해야 한다.
|
||||
- numerical risk는 rigid body modes, patch test, symmetry, positive definiteness, hourglass, locking, singular Jacobian, conditioning을 포함해야 한다.
|
||||
- numerical risk는 approved feature scope가 요구하는 항목만 포함한다. 이후 Reference Model
|
||||
문서, canonical naming, README, metadata, provenance, expanded portfolio 또는 아직 없는
|
||||
comparison result는 formulation verdict의 blocker가 아니다.
|
||||
|
||||
@@ -40,7 +40,7 @@ EVIDENCE CHECK -> PHYSICS CHECKS -> CLASSIFY -> REPORT
|
||||
|
||||
- Reference Verification report status가 `pass-for-physics-evaluation`인지 여부
|
||||
- checked solver HDF5 file: `<solver output directory>/results.h5`
|
||||
- checked Abaqus reference CSV files under `reference/<model-id>/`
|
||||
- checked feature-declared Abaqus reference CSV files
|
||||
- optional FESA deterministic CSV view derived from `results.h5` for review only
|
||||
- compared quantities
|
||||
- model purpose
|
||||
@@ -97,10 +97,7 @@ EVIDENCE CHECK -> PHYSICS CHECKS -> CLASSIFY -> REPORT
|
||||
| reference_verification | docs/reference-verifications/<feature-id>-reference-verification.md | pass-for-physics-evaluation | <summary> |
|
||||
| solver_hdf5 | <solver output directory>/results.h5 | present | missing | <summary> |
|
||||
| solver_csv_views | <solver output directory>/csv/ | present | missing | <summary or N/A> |
|
||||
| reference_displacements_csv | reference/<model-id>/<model-id>_displacements.csv | present | missing | <summary> |
|
||||
| reference_reactions_csv | reference/<model-id>/<model-id>_reactions.csv | present | missing | <summary> |
|
||||
| reference_internalforces_csv | reference/<model-id>/<model-id>_internalforces.csv | present | missing | <summary> |
|
||||
| reference_stresses_csv | reference/<model-id>/<model-id>_stresses.csv | present | missing | <summary> |
|
||||
| declared_reference_csv | <exact feature-declared path> | present | missing | <blocking/warning quantity summary> |
|
||||
| model_purpose | docs/reference-models/<feature-id>-reference-models.md | documented | missing | <summary> |
|
||||
| physical_expectations | <source docs> | documented | missing | <summary> |
|
||||
|
||||
@@ -154,7 +151,7 @@ EVIDENCE CHECK -> PHYSICS CHECKS -> CLASSIFY -> REPORT
|
||||
|
||||
- `pass-for-release-agent`: documented physics checks가 통과했고 Release Agent가 release readiness를 평가할 수 있다.
|
||||
- `needs-correction`: implementation-owned physical failure가 있어 Correction Agent가 필요하다.
|
||||
- `needs-reference-model`: reference model coverage가 부족하거나 추가 physical expectation이 필요하다.
|
||||
- `needs-reference-model`: feature-required case 또는 명시적으로 요구된 physical expectation이 누락됐다.
|
||||
- `needs-formulation-review`: formulation 또는 numerical review 재검토가 필요하다.
|
||||
- `needs-io-decision`: output location, component naming, sign convention, unit, coordinate mapping이 evaluation을 막는다.
|
||||
- `needs-upstream-decision`: physical expectation, sign convention, model purpose, acceptance criterion이 누락 또는 충돌한다.
|
||||
@@ -163,7 +160,9 @@ EVIDENCE CHECK -> PHYSICS CHECKS -> CLASSIFY -> REPORT
|
||||
## 품질 기준
|
||||
|
||||
- Reference Verification report가 `pass-for-physics-evaluation`이 아니면 physics pass를 판정하지 않는다.
|
||||
- documented expectation이 없는 항목은 pass/fail로 판정하지 않고 `skipped`, `needs-upstream-decision`, 또는 `needs-reference-model`로 둔다.
|
||||
- documented expectation이 없는 항목은 `skipped`로 두며 expanded portfolio나 calibration을
|
||||
새 gate로 만들지 않는다. Feature-required expectation 자체가 누락된 경우에만
|
||||
`needs-upstream-decision` 또는 `needs-reference-model`을 사용한다.
|
||||
- 평형 검토는 적용 하중, 반력, element/internal force sign convention이 문서화된 경우에만 수행한다.
|
||||
- stress/strain 검토는 output location, component naming, coordinate system, units가 정의된 경우에만 수행한다.
|
||||
- FESA `results.h5`, Abaqus reference CSV files, optional FESA debug CSV view는 읽기 전용 evidence로만 사용한다.
|
||||
|
||||
+63
-193
@@ -1,221 +1,91 @@
|
||||
# Reference Model 문서 작성 가이드
|
||||
# Reference Case 문서 작성 가이드
|
||||
|
||||
이 디렉터리는 Reference Model Agent가 작성하거나 제안한 기능별 reference model 설계 문서를 보관하는 위치다.
|
||||
이 디렉터리는 Reference Model Agent가 작성하는 기능별 lightweight reference-case
|
||||
inventory를 보관한다. Abaqus는 외부 수치 reference이며 FESA의 formulation 또는 내부
|
||||
동작 계약이 아니다.
|
||||
|
||||
Reference Model Agent는 FESA 기능 검증에 필요한 Abaqus `.inp` 기반 테스트 모델 포트폴리오와 `reference/<model-id>/` artifact bundle 계약을 정의한다. Agent는 Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않고, Abaqus reference CSV 파일을 생성하거나 수정하지 않으며, solver 결과 비교나 release readiness 승인도 하지 않는다.
|
||||
기본 파일명은 `docs/reference-models/<feature-id>-reference-models.md`다. Agent는 Abaqus
|
||||
또는 다른 reference solver를 실행하지 않고 `reference/` 파일을 생성, 수정, rename,
|
||||
repair 또는 normalize하지 않는다.
|
||||
|
||||
기본 파일명은 `docs/reference-models/<feature-id>-reference-models.md` 형식을 사용한다. 각 문서는 요구조건, 연구 브리프, 정식화, 수치 리뷰, I/O 정의를 입력으로 받아 구현 전에 준비해야 할 테스트 모델과 reference artifact 요구사항을 정의해야 한다.
|
||||
## 필수 내용
|
||||
|
||||
## Reference Model Agent 역할
|
||||
기능이 실제로 비교하는 case마다 다음만 기록한다.
|
||||
|
||||
수행한다:
|
||||
- 기능별 reference model portfolio를 smoke, analytical, patch test, benchmark, regression, negative/invalid-input model로 구분한다.
|
||||
- `model.inp`가 I/O Definition Agent의 supported Abaqus keyword subset 안에 있는지 확인한다.
|
||||
- `reference/<model-id>/` artifact bundle 구조와 필수 파일을 정의한다.
|
||||
- provenance, 단위, 좌표계, Abaqus version/source, output request, tolerance 정책을 기능별 Reference Model Contract에 정의한다. 선택 `metadata.json`이 존재하면 read-only로 inventory하고 계약과 대조한다.
|
||||
- Abaqus reference CSV 파일 요구사항을 정의한다.
|
||||
- requirement와 model, compared quantity, FESA HDF5 dataset, reference CSV, tolerance, artifact status를 연결하는 Coverage Matrix를 작성한다.
|
||||
- case id와 목적
|
||||
- existing `.inp` exact path
|
||||
- blocking 또는 warning-only quantity의 existing CSV exact path
|
||||
- FESA HDF5 dataset
|
||||
- source identity와 component mapping
|
||||
- missing/extra/duplicate/nonfinite row precheck
|
||||
- approved tolerance
|
||||
- artifact presence/readability status
|
||||
|
||||
수행하지 않는다:
|
||||
- C++ 코드를 구현하지 않는다.
|
||||
- parser를 구현하지 않는다.
|
||||
- C++ API나 파일 구조를 설계하지 않는다.
|
||||
- Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않는다.
|
||||
- Abaqus reference CSV 파일을 생성하거나 수정하지 않는다.
|
||||
- solver 결과를 비교하지 않는다.
|
||||
- release readiness를 승인하지 않는다.
|
||||
- reference 값, tolerance, Abaqus compatibility를 임의로 만들지 않는다.
|
||||
다음은 기본 readiness 조건이 아니다.
|
||||
|
||||
- canonical directory/file naming 또는 legacy-alias 승인
|
||||
- bundle `README.md` 또는 `metadata.json`
|
||||
- Abaqus version/generation provenance
|
||||
- duplicated units, coordinates, model, step/frame, material, section, thickness, element type
|
||||
- reference CSV schema version
|
||||
- 비교하지 않는 quantity CSV
|
||||
- 요구조건이 요청하지 않은 benchmark portfolio
|
||||
|
||||
단일 static step/final frame 기능은 input/CSV pair로 result state를 식별한다. Material,
|
||||
section, loads, constraints와 source element type은 `.inp`에서 읽는다.
|
||||
|
||||
## 문서 템플릿
|
||||
|
||||
```markdown
|
||||
# <feature title> Reference Models
|
||||
# <Feature Title> Reference Cases
|
||||
|
||||
## Metadata
|
||||
- feature_id: <feature-id>
|
||||
- source_requirement: docs/requirements/<feature-id>.md
|
||||
- source_research: docs/research/<feature-id>-research.md
|
||||
- source_formulation: docs/formulations/<feature-id>-formulation.md
|
||||
- source_numerical_review: docs/numerical-reviews/<feature-id>-review.md
|
||||
- source_io_definition: docs/io-definitions/<feature-id>-io.md
|
||||
- status: draft | needs-user-decision | needs-reference-artifacts | ready-for-implementation-planning | blocked
|
||||
- owner_agent: reference-model-agent
|
||||
- date: <YYYY-MM-DD>
|
||||
|
||||
## Reference Strategy
|
||||
- verification_scope: <feature verification purpose>
|
||||
- code_verification: <unit/math-level checks supported by this portfolio>
|
||||
- solution_verification: <mesh, convergence, patch, or analytical checks>
|
||||
- benchmark_reference_comparison: <Abaqus/NAFEMS/NASA/paper-derived comparison plan>
|
||||
- excluded_validation_scope: <physical experiment validation excluded unless explicitly available>
|
||||
## Reference Acceptance Scope
|
||||
- blocking_quantities: [<quantity/components>]
|
||||
- warning_only_quantities: [<quantity/components>]
|
||||
- excluded_quantities: [<quantity/reason>]
|
||||
|
||||
## Model Inventory
|
||||
## Reference Case Inventory
|
||||
|
||||
| model_id | category | purpose | status | required_artifacts |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| <model-id> | smoke | <basic parser/solve path> | draft | model.inp, required Abaqus reference CSV files |
|
||||
| <model-id> | analytical | <closed-form comparison> | draft | model.inp, required Abaqus reference CSV files |
|
||||
| <model-id> | patch test | <element consistency check> | draft | model.inp, required Abaqus reference CSV files |
|
||||
| <model-id> | benchmark | <trusted benchmark comparison> | draft | model.inp, required Abaqus reference CSV files |
|
||||
| <model-id> | regression | <known defect guard> | draft | model.inp, required Abaqus reference CSV files |
|
||||
| <model-id> | negative/invalid-input | <unsupported keyword or invalid model diagnostic> | draft | model.inp |
|
||||
| case_id | purpose | input | required_csv | quantity | behavior | status |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| <case> | <purpose> | reference/<dir>/<file>.inp | reference/<dir>/<file>.csv | <components> | blocking | warning-only | present | missing |
|
||||
|
||||
## Model Record
|
||||
## HDF5-to-CSV Comparison Mapping
|
||||
|
||||
### <model-id>
|
||||
- category: smoke | analytical | patch test | benchmark | regression | negative/invalid-input
|
||||
- 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>
|
||||
- material: <material model and values>
|
||||
- boundary_conditions: <BC summary>
|
||||
- loads: <load summary>
|
||||
- expected_physical_quantities: displacement | reaction | internal force | stress | strain | energy | residual
|
||||
- tolerance: <absolute/relative/norm policy or needs-user-decision>
|
||||
- source: <user | analytical | Abaqus Verification Guide | Abaqus Benchmarks Guide | NAFEMS | NASA/FEMCI | paper>
|
||||
- artifact_status: draft | needs-reference-artifacts | ready-for-implementation-planning | blocked
|
||||
| case_id | hdf5_dataset | source_id | csv_id_column | components | row_precheck |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| <case> | <path> | <node/element source id> | <column> | <components> | exact set; unique; finite |
|
||||
|
||||
## Abaqus Input Requirements
|
||||
- input_file: reference/<model-id>/model.inp
|
||||
- supported_keyword_subset: <keywords from docs/io-definitions/<feature-id>-io.md>
|
||||
- model_data: <nodes, elements, sets, material, section, coordinates, units>
|
||||
- history_data: <step, procedure, boundary conditions, loads, output requests>
|
||||
- output_requests: <requests needed to populate Abaqus reference CSV files>
|
||||
- unsupported_keyword_policy: unsupported | ignored-with-warning | requires-user-decision
|
||||
## Tolerance and Blocking/Warning Policy
|
||||
- reference_scale: <formula>
|
||||
- row_tolerance: <formula>
|
||||
- zero_policy: no clamp
|
||||
- blocking_behavior: <rule>
|
||||
- warning_behavior: <rule>
|
||||
|
||||
## Artifact Bundle Contract
|
||||
|
||||
```text
|
||||
reference/
|
||||
<model-id>/
|
||||
model.inp
|
||||
metadata.json # optional
|
||||
<model-id>_displacements.csv
|
||||
<model-id>_reactions.csv
|
||||
<model-id>_internalforces.csv
|
||||
<model-id>_stresses.csv
|
||||
README.md
|
||||
```
|
||||
|
||||
Required files:
|
||||
- `model.inp`: Abaqus input file for the reference model.
|
||||
- `<model-id>_displacements.csv`: required when nodal displacement is a verification quantity.
|
||||
- `<model-id>_reactions.csv`: required when constrained DOF reactions or global equilibrium are verification quantities.
|
||||
- `<model-id>_internalforces.csv`: required when element internal force is a verification quantity.
|
||||
- `<model-id>_stresses.csv`: required when stress is a verification quantity.
|
||||
- `README.md`: short description, generation notes, and limitations.
|
||||
|
||||
Optional files:
|
||||
- `metadata.json`: optional machine-readable copy of reference metadata; inspect read-only and cross-check against the approved Reference Model Contract when present.
|
||||
- `<model-id>_strains.csv`: required when strain is part of the acceptance criteria.
|
||||
- `<model-id>_energy_or_residual.csv`: required when energy balance, residual, or convergence data is part of the acceptance criteria.
|
||||
- `<model-id>_<quantity>.csv`: feature-specific reference quantity when upstream contracts require it.
|
||||
- `notes.md`: manual review notes.
|
||||
|
||||
## Reference Metadata Contract
|
||||
|
||||
The feature-specific Reference Model Contract is the required source of truth for every field
|
||||
below. A bundle does not need a `metadata.json` file. When the optional file exists, use this
|
||||
schema, inventory it read-only, and compare every overlapping field with the contract and stored
|
||||
artifacts. Absence is `absent-allowed`; a conflict is an upstream contract/provenance issue and
|
||||
must not be resolved by silently preferring either value.
|
||||
|
||||
```json
|
||||
{
|
||||
"feature_id": "<feature-id>",
|
||||
"model_id": "<model-id>",
|
||||
"artifact_status": "draft | needs-reference-artifacts | ready-for-implementation-planning | blocked",
|
||||
"input_file": "model.inp",
|
||||
"abaqus_version": "<version or needs-user-decision>",
|
||||
"generation_owner": "<person/procedure>",
|
||||
"generation_date": "<YYYY-MM-DD>",
|
||||
"source_documents": ["docs/requirements/<feature-id>.md"],
|
||||
"units": "<unit system>",
|
||||
"coordinate_system": "global Cartesian unless otherwise documented",
|
||||
"analysis_type": "<analysis type>",
|
||||
"element_types": ["<Abaqus element type>"],
|
||||
"material_values": {},
|
||||
"boundary_condition_summary": "<summary>",
|
||||
"load_summary": "<summary>",
|
||||
"output_requests": ["U", "RF", "S", "<feature-specific quantities>"],
|
||||
"reference_csv_schema_version": "<version>",
|
||||
"reference_csv_files": [
|
||||
"<model-id>_displacements.csv",
|
||||
"<model-id>_reactions.csv",
|
||||
"<model-id>_internalforces.csv",
|
||||
"<model-id>_stresses.csv"
|
||||
],
|
||||
"tolerance_policy": "<absolute/relative/norm policy>",
|
||||
"limitations": ["<known limitation>"]
|
||||
}
|
||||
```
|
||||
|
||||
## Abaqus Reference CSV Requirements
|
||||
|
||||
### `<model-id>_displacements.csv`
|
||||
- Required when nodal displacement is a verification quantity.
|
||||
- Must include step/frame identity, node id, displacement components, coordinate system, and units.
|
||||
|
||||
### `<model-id>_reactions.csv`
|
||||
- Required when constrained DOF reactions or global equilibrium are verification quantities.
|
||||
- Must include step/frame identity, node id, reaction components, coordinate system, and units.
|
||||
|
||||
### `<model-id>_internalforces.csv`
|
||||
- Required when element internal force is a verification quantity.
|
||||
- Must include step/frame identity, element id, output location, component, value, and units.
|
||||
|
||||
### `<model-id>_stresses.csv`
|
||||
- Required when stress is a verification quantity.
|
||||
- Must include step/frame identity, element id, integration point or recovery location, component, value, coordinate system, and units.
|
||||
|
||||
### Optional Reference CSV Files
|
||||
- `<model-id>_strains.csv`: required when strain is part of the acceptance criteria.
|
||||
- `<model-id>_energy_or_residual.csv`: required when energy balance, residual, or convergence data is part of the acceptance criteria.
|
||||
- `<model-id>_<quantity>.csv`: required when a feature-specific quantity is part of the acceptance criteria.
|
||||
|
||||
## Coverage Matrix
|
||||
|
||||
| requirement_id | model_id | compared_quantity | fesa_hdf5_dataset | reference_csv | tolerance | verification_method | status |
|
||||
| --- | --- | --- | --- | --- | --- | --- | --- |
|
||||
| <req-id> | <model-id> | displacement | /steps/<step>/frames/<frame>/field_outputs/U | reference/<model-id>/<model-id>_displacements.csv | <policy> | hdf5-to-reference-csv | draft |
|
||||
| <req-id> | <model-id> | reaction | /steps/<step>/frames/<frame>/field_outputs/RF | reference/<model-id>/<model-id>_reactions.csv | <policy> | hdf5-to-reference-csv | draft |
|
||||
| <req-id> | <model-id> | internal force | /steps/<step>/frames/<frame>/field_outputs/element_forces | reference/<model-id>/<model-id>_internalforces.csv | <policy> | hdf5-to-reference-csv | draft |
|
||||
| <req-id> | <model-id> | stress | /steps/<step>/frames/<frame>/field_outputs/S | reference/<model-id>/<model-id>_stresses.csv | <policy> | hdf5-to-reference-csv | draft |
|
||||
|
||||
## Artifact Acceptance Checklist
|
||||
- 모든 `must` requirement가 최소 하나의 `model_id`와 `compared_quantity`에 연결되어 있다.
|
||||
- `model.inp`가 기능별 supported Abaqus keyword subset을 벗어나지 않는다.
|
||||
- Reference Model Contract에 provenance, Abaqus version/source, units, coordinate system, tolerance, reference CSV schema version과 artifact inventory가 기록되어 있다.
|
||||
- 선택 `metadata.json`의 부재는 허용되고, 존재하면 read-only inventory와 계약 일치 검사가 기록되어 있다.
|
||||
- 필요한 Abaqus reference CSV 파일이 존재하거나, 기능상 불필요한 quantity는 명확한 reason과 함께 제외되어 있다.
|
||||
- output request가 필요한 Abaqus reference CSV 물리량을 생성할 수 있도록 정의되어 있다.
|
||||
- required Abaqus reference CSV 또는 Reference Model Contract의 필수 provenance가 없으면 status는 `needs-reference-artifacts`다.
|
||||
- tolerance, source, units, coordinate system이 불명확하면 status는 `needs-user-decision`이다.
|
||||
## Readiness Checklist
|
||||
- declared input exists and is readable
|
||||
- every required CSV exists and is readable
|
||||
- source identity and required components are deterministic
|
||||
- row-set/nonfinite prechecks are defined
|
||||
- tolerance and blocking/warning behavior are approved
|
||||
|
||||
## Open Issues and Downstream Handoff
|
||||
|
||||
### I/O Definition Agent
|
||||
- <supported keyword, output request, FESA HDF5 schema clarification, reference CSV row schema clarification>
|
||||
|
||||
### Implementation Planning Agent
|
||||
- <tests that should fail before implementation, model order, acceptance criteria>
|
||||
|
||||
### Reference Verification Agent
|
||||
- <FESA HDF5 dataset paths, reference CSV schema, ID matching, units, coordinate conventions, output locations, tolerance mapping>
|
||||
|
||||
### Physics Evaluation Agent
|
||||
- <equilibrium, symmetry, displacement direction, stress location, rigid body mode, load path sanity checks>
|
||||
- <only missing required files, matching, tolerance, or feature-owned decisions>
|
||||
```
|
||||
|
||||
## 품질 기준
|
||||
## 상태 규칙
|
||||
|
||||
- Reference model의 목적과 검증 대상 requirement가 명확해야 한다.
|
||||
- `model.inp`는 Abaqus input file이며, 기능별 supported keyword subset을 따라야 한다.
|
||||
- model data와 history data를 구분해야 한다.
|
||||
- output request와 required Abaqus reference CSV 사이의 연결이 명확해야 한다.
|
||||
- `reference/<model-id>/` 구조와 필수 artifact가 명시되어야 한다.
|
||||
- Reference Model Contract에는 provenance, Abaqus version/source, units, coordinate system, tolerance, reference CSV schema version이 포함되어야 한다.
|
||||
- 선택 `metadata.json`은 없어도 되며, 존재할 때만 read-only로 참고하고 계약과 대조한다.
|
||||
- required Abaqus reference CSV가 없으면 완료 상태가 아니라 `needs-reference-artifacts` 상태로 둔다.
|
||||
- 모든 `must` requirement는 Coverage Matrix에서 model, compared quantity, FESA HDF5 dataset, reference CSV, tolerance, verification method로 추적되어야 한다.
|
||||
- `ready-for-implementation-planning`: required input/CSV files, mapping, and tolerance are complete.
|
||||
- `needs-reference-artifacts`: a declared input or required comparison CSV is missing.
|
||||
- `needs-user-decision`: required quantity, mapping, or tolerance is undefined.
|
||||
- `blocked`: no safe progress is possible without an external decision or state change.
|
||||
|
||||
Canonical naming, README, metadata, provenance, and unrequested portfolio coverage do not select
|
||||
any failure status.
|
||||
|
||||
@@ -1,156 +1,95 @@
|
||||
# Reference Verification Report 문서 작성 가이드
|
||||
# Reference Verification Report 작성 가이드
|
||||
|
||||
이 디렉터리는 Reference Verification Agent가 작성하거나 제안하는 기능별 reference comparison report를 보관하는 위치다.
|
||||
Reference Verification Agent는 Build/Test 통과 뒤 FESA `results.h5`와 기능이 선언한
|
||||
Abaqus CSV quantity를 비교한다. 비교 대상은 observable value이며 Abaqus 내부 formulation
|
||||
동등성이 아니다.
|
||||
|
||||
Reference Verification Agent는 Build/Test Executor Agent 통과 후 generated solver `results.h5`와 Abaqus reference CSV files를 tolerance 기준으로 비교한다. Reference CSV는 동일한 Abaqus `.inp` 모델을 Abaqus로 해석해 추출한 변위, 반력, 내력, 응력 결과이며, FESA HDF5 dataset에서 파생된 파일이 아니다. 이 agent는 comparison과 report만 수행하며, source code, tests, CMake files, requirements, formulations, I/O contracts, reference artifacts, tolerance policies를 수정하지 않는다.
|
||||
|
||||
기본 문서명은 `docs/reference-verifications/<feature-id>-reference-verification.md` 형식을 사용한다.
|
||||
|
||||
## Reference Verification Agent 역할
|
||||
|
||||
수행한다:
|
||||
- `reference/<model-id>/` artifact bundle과 generated solver `results.h5`를 확인한다.
|
||||
- `model.inp`, required Abaqus reference CSV files, Reference Model Contract의 provenance, reference CSV schema version, FESA HDF5 schema version, units, coordinate system, step/frame identity, node/element ID matching rule, output location, component naming, tolerance policy를 확인한다. 선택 `metadata.json`이 존재하면 read-only로 inventory하고 계약과 대조한다.
|
||||
- FESA HDF5 dataset을 normalized row record로 읽고 Abaqus reference CSV row와 직접 비교한다.
|
||||
- comparison command가 FESA `results.h5`에서 deterministic CSV view를 materialize할 수 있지만, 이 파일은 debugging/review용 derived artifact일 뿐 reference artifact가 아니다.
|
||||
- upstream 문서가 요구할 때만 `<model-id>_strains.csv`, `<model-id>_energy_or_residual.csv`, 또는 `<model-id>_<quantity>.csv`를 추가 비교한다.
|
||||
- max absolute error, max relative error, RMS error, norm error, worst id/component, missing rows, extra rows, pass/fail을 보고한다.
|
||||
- 실패를 missing-reference-artifact, missing-solver-output, schema-mismatch, id-mismatch, unit-or-coordinate-mismatch, tolerance-failure, nonfinite-result, upstream-contract, environment로 분류한다.
|
||||
|
||||
수행하지 않는다:
|
||||
- source code를 수정하지 않는다.
|
||||
- tests를 수정하지 않는다.
|
||||
- CMake files를 수정하지 않는다.
|
||||
- requirements, formulations, I/O contracts, reference model contracts를 수정하지 않는다.
|
||||
- reference artifacts 또는 tolerance policies를 수정하지 않는다.
|
||||
- Abaqus, Nastran 또는 reference solver를 실행하지 않는다.
|
||||
- Abaqus reference CSV 파일을 생성하거나 수정하지 않는다.
|
||||
- solver output을 tolerance에 맞추기 위해 보정하지 않는다.
|
||||
- physics validation success 또는 release readiness를 승인하지 않는다.
|
||||
기본 문서명은 `docs/reference-verifications/<feature-id>-reference-verification.md`다.
|
||||
|
||||
## 실행 순서
|
||||
|
||||
Reference Verification Agent는 항상 다음 순서를 따른다.
|
||||
|
||||
```text
|
||||
ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT
|
||||
```
|
||||
|
||||
`ARTIFACT CHECK`에서 다음 항목이 없으면 비교를 시작하지 않는다.
|
||||
`ARTIFACT CHECK`는 다음만 요구한다.
|
||||
|
||||
- `model.inp`
|
||||
- generated solver `results.h5`
|
||||
- `reference/<model-id>/<model-id>_displacements.csv`
|
||||
- `reference/<model-id>/<model-id>_reactions.csv`
|
||||
- `reference/<model-id>/<model-id>_internalforces.csv`
|
||||
- `reference/<model-id>/<model-id>_stresses.csv`
|
||||
- reference CSV schema version
|
||||
- FESA HDF5 schema version
|
||||
- units
|
||||
- coordinate system
|
||||
- step/frame identity
|
||||
- node/element ID matching rule
|
||||
- output location
|
||||
- component naming
|
||||
- tolerance policy
|
||||
- declared `.inp`
|
||||
- generated FESA `results.h5`
|
||||
- every feature-required Abaqus CSV
|
||||
- HDF5 dataset projection
|
||||
- source-ID/component mapping
|
||||
- blocking/warning behavior
|
||||
- approved tolerance
|
||||
|
||||
`metadata.json`은 필수 artifact가 아니다. 파일이 없으면 inventory에 `absent-allowed`로
|
||||
기록하고 비교를 계속한다. 파일이 존재하면 read-only로 읽어 Reference Model Contract와
|
||||
실제 input/CSV의 중복 필드를 대조한다. 충돌은 `needs-upstream-decision` 또는 적절한
|
||||
schema/provenance failure로 분류하며, 파일 부재만으로 `needs-reference-artifacts`를
|
||||
선택하지 않는다.
|
||||
Canonical naming, README, metadata, Abaqus version/provenance, duplicated units/coordinates/
|
||||
step-frame fields와 reference CSV schema version은 기본 gate가 아니다.
|
||||
|
||||
## 비교 대상
|
||||
Missing, extra, duplicate 또는 nonfinite required row는 tolerance 전에 실패한다. Row order
|
||||
alone으로 대응하지 않는다. FESA/Reference 값을 zero-clamp하거나 tolerance에 맞게 보정하지
|
||||
않는다.
|
||||
|
||||
| quantity | fesa_hdf5_dataset | reference_csv |
|
||||
| --- | --- | --- |
|
||||
| displacement | /steps/<step>/frames/<frame>/field_outputs/U | reference/<model-id>/<model-id>_displacements.csv |
|
||||
| reaction | /steps/<step>/frames/<frame>/field_outputs/RF | reference/<model-id>/<model-id>_reactions.csv |
|
||||
| internal force | /steps/<step>/frames/<frame>/field_outputs/element_forces | reference/<model-id>/<model-id>_internalforces.csv |
|
||||
| stress | /steps/<step>/frames/<frame>/field_outputs/S | reference/<model-id>/<model-id>_stresses.csv |
|
||||
## 보고 항목
|
||||
|
||||
선택 Abaqus reference CSV:
|
||||
- `reference/<model-id>/<model-id>_strains.csv`: strain이 acceptance criteria에 포함된 경우
|
||||
- `reference/<model-id>/<model-id>_energy_or_residual.csv`: energy, residual, convergence quantity가 acceptance criteria에 포함된 경우
|
||||
- `reference/<model-id>/<model-id>_<quantity>.csv`: feature-specific quantity가 acceptance criteria에 포함된 경우
|
||||
각 blocking 또는 warning-only quantity에 대해 다음을 보고한다.
|
||||
|
||||
- exact input and CSV path
|
||||
- FESA HDF5 dataset
|
||||
- source ID/component mapping
|
||||
- compared, missing, extra, duplicate, nonfinite row counts
|
||||
- max absolute and relative error
|
||||
- RMS and norm error when required
|
||||
- worst source ID/component
|
||||
- pass, fail, or warning
|
||||
|
||||
## Failure Classification
|
||||
|
||||
- `missing-reference-artifact`: required Abaqus reference CSV file 또는 provenance가 없다.
|
||||
- `missing-solver-output`: generated solver `results.h5` 또는 comparison command가 없다.
|
||||
- `schema-mismatch`: FESA HDF5 또는 reference CSV row schema가 다르다.
|
||||
- `id-mismatch`: node id, element id, step/frame, integration point, component matching이 실패했다.
|
||||
- `unit-or-coordinate-mismatch`: units 또는 coordinate system이 비교 가능하지 않다.
|
||||
- `tolerance-failure`: schema와 matching은 유효하지만 error가 tolerance를 초과했다.
|
||||
- `nonfinite-result`: NaN 또는 infinite value가 발견됐다.
|
||||
- `upstream-contract`: tolerance, schema, units, output location, ID matching policy가 누락 또는 충돌한다.
|
||||
- `environment`: 로컬 실행 환경 문제로 비교가 불가능하다.
|
||||
- `missing-reference-artifact`: declared input or required CSV missing
|
||||
- `missing-solver-output`: `results.h5` or comparison command missing
|
||||
- `schema-mismatch`: required source ID/component columns unavailable
|
||||
- `id-mismatch`: required source row sets do not match
|
||||
- `tolerance-failure`: blocking value exceeds approved tolerance
|
||||
- `nonfinite-result`: required FESA or reference value is not finite
|
||||
- `upstream-contract`: quantity, HDF5 projection, mapping, or tolerance missing/contradictory
|
||||
- `environment`: local comparison cannot run
|
||||
|
||||
## 문서 템플릿
|
||||
|
||||
```markdown
|
||||
# <feature title> Reference Verification Report
|
||||
# <Feature Title> Reference Verification Report
|
||||
|
||||
## Metadata
|
||||
- feature_id: <feature-id>
|
||||
- source_build_test_report: docs/build-test-reports/<feature-id>-build-test.md
|
||||
- source_reference_models: docs/reference-models/<feature-id>-reference-models.md
|
||||
- source_io_definition: docs/io-definitions/<feature-id>-io.md
|
||||
- source_implementation_report: <path or N/A>
|
||||
- status: pass-for-physics-evaluation | needs-correction | needs-reference-artifacts | needs-solver-results | needs-upstream-decision | blocked
|
||||
- owner_agent: reference-verification-agent
|
||||
- date: <YYYY-MM-DD>
|
||||
|
||||
## Artifact Inventory
|
||||
|
||||
| item | path | status | notes |
|
||||
| --- | --- | --- | --- |
|
||||
| reference_model_dir | reference/<model-id>/ | present | missing | <notes> |
|
||||
| reference_input | reference/<model-id>/model.inp | present | missing | <input summary> |
|
||||
| optional_metadata | reference/<model-id>/metadata.json | present / absent-allowed / conflict | <contract cross-check summary> |
|
||||
| reference_displacements_csv | reference/<model-id>/<model-id>_displacements.csv | present | missing | <row/schema summary> |
|
||||
| reference_reactions_csv | reference/<model-id>/<model-id>_reactions.csv | present | missing | <row/schema summary> |
|
||||
| reference_internalforces_csv | reference/<model-id>/<model-id>_internalforces.csv | present | missing | <row/schema summary> |
|
||||
| reference_stresses_csv | reference/<model-id>/<model-id>_stresses.csv | present | missing | <row/schema summary> |
|
||||
| solver_hdf5 | <solver output directory>/results.h5 | present | missing | <schema summary> |
|
||||
| solver_debug_csv_view | <solver output directory>/csv/ | present | missing | <optional, derived from results.h5 only> |
|
||||
| input | <exact path> | present | missing | <summary> |
|
||||
| required_csv | <exact path> | present | missing | <summary> |
|
||||
| solver_hdf5 | <path>/results.h5 | present | missing | <summary> |
|
||||
|
||||
## Comparison Contract
|
||||
- hdf5_schema_version: <version>
|
||||
- reference_csv_schema_version: <version>
|
||||
- id_matching: node_id | element_id | step/frame | integration_point | component
|
||||
- units: <unit system>
|
||||
- coordinate_system: <global/local convention>
|
||||
- output_location: nodal | element | integration_point | centroid | recovery_location
|
||||
- component_naming: <component naming policy>
|
||||
- row_sort_order: <step, frame, id, location, component order>
|
||||
- tolerance_source: <requirement/reference model/I/O document>
|
||||
- tolerance_policy: absolute | relative | norm-based | combined
|
||||
- zero_reference_policy: <policy or N/A>
|
||||
- hdf5_dataset: <path>
|
||||
- source_id_mapping: <rule>
|
||||
- components: <blocking/warning inventory>
|
||||
- row_precheck: exact set; unique; finite
|
||||
- tolerance_source: <path/requirement>
|
||||
- tolerance_policy: <formula>
|
||||
|
||||
## Quantity Results
|
||||
|
||||
| quantity | model_id | fesa_hdf5_dataset | reference_csv | compared_rows | missing_rows | extra_rows | max_abs_error | max_rel_error | rms_error | norm_error | worst_id | worst_component | result |
|
||||
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
|
||||
| displacement | <model-id> | /steps/<step>/frames/<frame>/field_outputs/U | reference/<model-id>/<model-id>_displacements.csv | <n> | <n> | <n> | <value> | <value> | <value> | <value or N/A> | <node id> | <component> | pass | fail |
|
||||
| reaction | <model-id> | /steps/<step>/frames/<frame>/field_outputs/RF | reference/<model-id>/<model-id>_reactions.csv | <n> | <n> | <n> | <value> | <value> | <value> | <value or N/A> | <node id> | <component> | pass | fail |
|
||||
| internal force | <model-id> | /steps/<step>/frames/<frame>/field_outputs/element_forces | reference/<model-id>/<model-id>_internalforces.csv | <n> | <n> | <n> | <value> | <value> | <value> | <value or N/A> | <element id> | <component> | pass | fail |
|
||||
| stress | <model-id> | /steps/<step>/frames/<frame>/field_outputs/S | reference/<model-id>/<model-id>_stresses.csv | <n> | <n> | <n> | <value> | <value> | <value> | <value or N/A> | <element/ip id> | <component> | pass | fail |
|
||||
| quantity | components | behavior | compared | missing | extra | max_abs | max_rel | rms | norm | worst_id/component | result |
|
||||
| --- | --- | --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | --- | --- |
|
||||
| <quantity> | <components> | blocking | warning-only | <values> |
|
||||
|
||||
## Failure Classification
|
||||
- classification: missing-reference-artifact | missing-solver-output | schema-mismatch | id-mismatch | unit-or-coordinate-mismatch | tolerance-failure | nonfinite-result | upstream-contract | environment | N/A
|
||||
- primary_failure: <short summary>
|
||||
- evidence: <short relevant excerpt or computed metric>
|
||||
- classification: <value or N/A>
|
||||
- evidence: <summary>
|
||||
|
||||
## Handoff Recommendation
|
||||
|
||||
| target_agent | reason | required_input |
|
||||
| --- | --- | --- |
|
||||
| Correction Agent | <implementation-owned mismatch or nonfinite result> | <comparison metrics and failing quantity> |
|
||||
| Reference Model Agent | <missing or invalid reference artifact/provenance> | <artifact inventory> |
|
||||
| I/O Definition Agent | <FESA HDF5 schema, reference CSV schema, units, coordinate, output location mismatch> | <contract mismatch> |
|
||||
| Physics Evaluation Agent | <reference comparisons passed> | <quantity results and report> |
|
||||
| Coordinator Agent | <blocked or repeated ambiguity> | <classification and open issue> |
|
||||
- <target and exact evidence>
|
||||
|
||||
## No-Change Assertion
|
||||
- source_files_modified: false
|
||||
@@ -158,30 +97,11 @@ schema/provenance failure로 분류하며, 파일 부재만으로 `needs-referen
|
||||
- cmake_files_modified: false
|
||||
- reference_artifacts_modified: false
|
||||
- tolerance_policies_modified: false
|
||||
- notes: <observed no-change evidence or exception>
|
||||
|
||||
## Open Issues
|
||||
- <missing solver outputs, missing reference artifacts, schema gaps, tolerance gaps, or repeated comparison failures>
|
||||
- <only actual comparison blockers>
|
||||
```
|
||||
|
||||
## 상태 값
|
||||
|
||||
- `pass-for-physics-evaluation`: required reference comparisons가 모두 통과했고 Physics Evaluation Agent로 넘길 수 있다.
|
||||
- `needs-correction`: implementation-owned solver result mismatch 또는 nonfinite result가 있다.
|
||||
- `needs-reference-artifacts`: required Abaqus reference CSV 또는 provenance가 누락됐다.
|
||||
- `needs-solver-results`: generated solver `results.h5` 또는 comparison command가 없다.
|
||||
- `needs-upstream-decision`: schema, tolerance, units, coordinate system, output location, ID matching policy가 누락 또는 충돌한다.
|
||||
- `blocked`: 사용자 또는 Coordinator Agent 결정 없이는 안전하게 진행할 수 없다.
|
||||
|
||||
## 품질 기준
|
||||
|
||||
- 모든 `must` requirement의 reference-comparison 항목은 model id, compared quantity, FESA HDF5 dataset, reference CSV, tolerance에 trace되어야 한다.
|
||||
- reference artifact는 읽기 전용이다. `model.inp`, 존재하는 `metadata.json`, `reference/<model-id>/<model-id>_*.csv`를 수정하지 않는다.
|
||||
- FESA `results.h5`가 authoritative solver output이고 Abaqus reference CSV files가 authoritative reference result다.
|
||||
- solver debug CSV view는 행 정렬과 사람이 검토 가능한 비교 view일 뿐이며 tolerance에 맞추기 위해 후처리 보정하지 않는다.
|
||||
- stress/strain은 element id, integration point 또는 recovery location, component naming이 일치할 때만 비교한다.
|
||||
- nodal displacement/reaction은 node id, DOF/component, coordinate system, unit이 일치할 때만 비교한다.
|
||||
- missing rows와 extra rows를 숨기지 않고 보고한다.
|
||||
- NaN 또는 infinite value는 `nonfinite-result`로 분류한다.
|
||||
- pass는 reference tolerance 통과만 의미한다.
|
||||
- physics validation과 release readiness는 각각 Physics Evaluation Agent와 Release Agent가 판정한다.
|
||||
`pass-for-physics-evaluation`은 required blocking comparison 통과만 의미한다. Warning-only
|
||||
quantity는 경고를 남기되 verdict를 바꾸지 않는다. Physics validation과 release readiness는
|
||||
각 후속 agent가 판정한다.
|
||||
|
||||
@@ -138,7 +138,7 @@ GATE AUDIT -> TRACEABILITY CHECK -> RELEASE DOCUMENTATION -> RELEASE VERDICT
|
||||
| Physics Evaluation Agent | <missing or failed physics evaluation> | <reference verification evidence> |
|
||||
| Requirement Agent | <requirement or acceptance gap> | <open decision> |
|
||||
| I/O Definition Agent | <I/O scope or Abaqus keyword limitation gap> | <contract gap> |
|
||||
| Reference Model Agent | <reference artifact or coverage gap> | <model gap> |
|
||||
| Reference Model Agent | <missing required input/CSV or comparison mapping> | <exact gap> |
|
||||
|
||||
## No-Change Assertion
|
||||
- source_files_modified: false
|
||||
@@ -149,7 +149,7 @@ GATE AUDIT -> TRACEABILITY CHECK -> RELEASE DOCUMENTATION -> RELEASE VERDICT
|
||||
- notes: <observed no-change evidence or exception>
|
||||
|
||||
## Open Issues
|
||||
- <missing evidence, contradictory upstream report, unresolved defect, incomplete reference artifact, or documentation gap>
|
||||
- <missing evidence, contradictory upstream report, unresolved defect, missing required comparison file/mapping, or documentation gap>
|
||||
```
|
||||
|
||||
## 상태 값
|
||||
@@ -159,7 +159,7 @@ GATE AUDIT -> TRACEABILITY CHECK -> RELEASE DOCUMENTATION -> RELEASE VERDICT
|
||||
- `needs-reference-verification`: reference verification report가 없거나 `pass-for-physics-evaluation`이 아니다.
|
||||
- `needs-physics-evaluation`: physics evaluation report가 없거나 `pass-for-release-agent`가 아니다.
|
||||
- `needs-documentation`: gate evidence는 통과했지만 release scope, known limitations, release notes, traceability 문서가 불완전하다.
|
||||
- `needs-upstream-decision`: requirement, tolerance, reference artifact, I/O, acceptance evidence가 누락되었거나 상충한다.
|
||||
- `needs-upstream-decision`: requirement, tolerance, required comparison file/mapping, I/O, acceptance evidence가 누락되었거나 상충한다.
|
||||
- `blocked`: 사용자 또는 Coordinator Agent 결정 없이는 안전하게 진행할 수 없다.
|
||||
|
||||
## 품질 기준
|
||||
@@ -167,5 +167,7 @@ GATE AUDIT -> TRACEABILITY CHECK -> RELEASE DOCUMENTATION -> RELEASE VERDICT
|
||||
- `ready-for-release`는 Build/Test, Reference Verification, Physics Evaluation gate evidence가 모두 present and passing일 때만 사용할 수 있다.
|
||||
- 모든 `must` requirement는 acceptance criterion, test/reference evidence, release scope에 trace되어야 한다.
|
||||
- known limitations와 deferred/open issue는 Release Notes Draft에 명확히 기록되어야 한다.
|
||||
- missing evidence, contradictory upstream reports, unresolved defects, incomplete reference artifacts는 release pass가 아니라 적절한 `needs-*` 상태로 분류한다.
|
||||
- missing evidence, contradictory upstream reports, unresolved defects, missing declared comparison
|
||||
files는 적절한 `needs-*` 상태로 분류한다. Canonical naming, README, metadata, provenance와
|
||||
unrequested portfolio는 blocker가 아니다.
|
||||
- 이 문서는 FESA 내부 feature release readiness 판정을 위한 것이며, 외부 publish/deploy/package/tag/commit 자동화는 포함하지 않는다.
|
||||
|
||||
+13
-10
@@ -73,16 +73,19 @@ Requirement Agent는 솔버 기능 요청을 검증 가능한 요구조건으로
|
||||
- relative_tolerance: <value or TBD>
|
||||
- norm_based_tolerance: <value or TBD>
|
||||
|
||||
## Reference Artifact Requirements
|
||||
Expected location: `reference/<model-id>/`
|
||||
## Reference Case Requirements
|
||||
|
||||
- `model.inp`: required | not-applicable
|
||||
- `metadata.json`: optional; if present, inspect read-only and cross-check against the approved Reference Model Contract
|
||||
- `<model-id>_displacements.csv`: required | not-applicable
|
||||
- `<model-id>_reactions.csv`: required | not-applicable
|
||||
- `<model-id>_internalforces.csv`: required | not-applicable
|
||||
- `<model-id>_stresses.csv`: required | not-applicable
|
||||
- Reference Model Contract metadata: required; record provenance, generator/version, units, coordinate system, step/frame identity, schema, tolerance, artifact inventory, and limitations
|
||||
- input_path: <exact existing `.inp` path or N/A>
|
||||
- required_csv_paths: <only blocking/warning quantity CSV paths or N/A>
|
||||
- blocking_quantities: <components or N/A>
|
||||
- warning_only_quantities: <components or N/A>
|
||||
- hdf5_projection: <dataset or N/A>
|
||||
- source_id_component_matching: <rule or N/A>
|
||||
- row_precheck: missing/extra/duplicate/nonfinite fail before tolerance
|
||||
- tolerance: <approved formula or N/A>
|
||||
|
||||
Canonical naming, README, metadata, provenance, duplicated units/coordinates/step-frame fields,
|
||||
CSV schema versions와 비교하지 않는 quantity CSV는 기본 요구조건이 아니다.
|
||||
|
||||
## Requirement Verification Matrix
|
||||
|
||||
@@ -105,7 +108,7 @@ Expected location: `reference/<model-id>/`
|
||||
- <입력/출력 schema 요구조건>
|
||||
|
||||
### Reference Model Agent
|
||||
- <필요한 references/<feature-id>/ artifact 목록>
|
||||
- <exact input/required CSV paths, blocking/warning quantities, matching, tolerance>
|
||||
|
||||
### Implementation Planning Agent
|
||||
- <먼저 작성할 테스트와 acceptance criteria>
|
||||
|
||||
Reference in New Issue
Block a user