baram2584/FESADev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

modify docu

Browse Source
This commit is contained in:
김경종
2026-06-11 17:18:03 +09:00
parent c4f8f95d4b
commit 742f311be1
66 changed files with 3354 additions and 375 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/reference-models/README.md
+55 -44
View File
@@ -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는 FESA 기능 검증에 필요한 Abaqus `.inp` 기반 테스트 모델 포트폴리오와 `references/<feature-id>/<model-id>/` artifact bundle 계약을 정의한다. Agent는 Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않고, reference HDF5 파일이나 deterministic CSV view 값을 생성하지 않으며, solver 결과 비교나 release readiness 승인도 하지 않는다.
기본 파일명은 `docs/reference-models/<feature-id>-reference-models.md` 형식을 사용한다. 각 문서는 요구조건, 연구 브리프, 정식화, 수치 리뷰, I/O 정의를 입력으로 받아 구현 전에 준비해야 할 테스트 모델과 reference artifact 요구사항을 정의해야 한다.
@@ -13,7 +13,7 @@ Reference Model Agent는 FESA 기능 검증에 필요한 Abaqus `.inp` 기반
- `model.inp`가 I/O Definition Agent의 supported Abaqus keyword subset 안에 있는지 확인한다.
- `references/<feature-id>/<model-id>/` artifact bundle 구조와 필수 파일을 정의한다.
- `metadata.json` provenance, 단위, 좌표계, Abaqus version/source, output request, tolerance 정책을 정의한다.
- `displacements.csv`, `reactions.csv`, `element_forces.csv`, `stresses.csv` 요구사항을 정의한다.
- `reference.h5` 요구사항과 HDF5 dataset에서 추출되는 deterministic CSV view 요구사항을 정의한다.
- requirement와 model, compared quantity, tolerance, artifact status를 연결하는 Coverage Matrix를 작성한다.
수행하지 않는다:
@@ -21,7 +21,7 @@ Reference Model Agent는 FESA 기능 검증에 필요한 Abaqus `.inp` 기반
- parser를 구현하지 않는다.
- C++ API나 파일 구조를 설계하지 않는다.
- Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않는다.
- reference CSV를 생성하지 않는다.
- reference HDF5 파일이나 deterministic CSV view를 생성하지 않는다.
- solver 결과를 비교하지 않는다.
- release readiness를 승인하지 않는다.
- reference 값, tolerance, Abaqus compatibility를 임의로 만들지 않는다.
@@ -53,11 +53,11 @@ Reference Model Agent는 FESA 기능 검증에 필요한 Abaqus `.inp` 기반
| model_id | category | purpose | status | required_artifacts |
| --- | --- | --- | --- | --- |
| <model-id> | smoke | <basic parser/solve path> | draft | model.inp, metadata.json, required CSVs |
| <model-id> | analytical | <closed-form comparison> | draft | model.inp, metadata.json, required CSVs |
| <model-id> | patch test | <element consistency check> | draft | model.inp, metadata.json, required CSVs |
| <model-id> | benchmark | <trusted benchmark comparison> | draft | model.inp, metadata.json, required CSVs |
| <model-id> | regression | <known defect guard> | draft | model.inp, metadata.json, required CSVs |
| <model-id> | smoke | <basic parser/solve path> | draft | model.inp, metadata.json, reference.h5, required CSV views |
| <model-id> | analytical | <closed-form comparison> | draft | model.inp, metadata.json, reference.h5, required CSV views |
| <model-id> | patch test | <element consistency check> | draft | model.inp, metadata.json, reference.h5, required CSV views |
| <model-id> | benchmark | <trusted benchmark comparison> | draft | model.inp, metadata.json, reference.h5, required CSV views |
| <model-id> | regression | <known defect guard> | draft | model.inp, metadata.json, reference.h5, required CSV views |
| <model-id> | negative/invalid-input | <unsupported keyword or invalid model diagnostic> | draft | model.inp, metadata.json |
## Model Record
@@ -81,7 +81,7 @@ Reference Model Agent는 FESA 기능 검증에 필요한 Abaqus `.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 reference CSV files>
- output_requests: <requests needed to populate reference.h5 datasets and deterministic CSV views>
- unsupported_keyword_policy: unsupported | ignored-with-warning | requires-user-decision
## Artifact Bundle Contract
@@ -92,25 +92,28 @@ references/
<model-id>/
model.inp
metadata.json
displacements.csv
reactions.csv
element_forces.csv
stresses.csv
reference.h5
csv/
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.
- `reference.h5`: authoritative reference result artifact.
- `csv/displacements.csv`: deterministic view of nodal displacement reference results.
- `csv/reactions.csv`: deterministic view of nodal reaction force reference results.
- `csv/element_forces.csv`: deterministic view of element internal force reference results.
- `csv/stresses.csv`: deterministic view of stress reference results.
- `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.
- `csv/strains.csv`: deterministic strain view when required.
- `csv/energy_or_residual.csv`: deterministic energy, residual, or convergence view when required.
- `notes.md`: manual review notes.
## Metadata JSON Contract
@@ -132,62 +135,70 @@ Optional files:
"boundary_condition_summary": "<summary>",
"load_summary": "<summary>",
"output_requests": ["U", "RF", "S", "<feature-specific quantities>"],
"csv_schema_version": "<version>",
"hdf5_schema_version": "<version>",
"csv_view_schema_version": "<version>",
"csv_view_source": "reference.h5",
"tolerance_policy": "<absolute/relative/norm policy>",
"limitations": ["<known limitation>"]
}
```
## Reference CSV Requirements
## Reference HDF5 and CSV View Requirements
### displacements.csv
### reference.h5
- Required when any numerical reference comparison is part of the acceptance criteria.
- Must include schema version, units, coordinate system, step/frame identity, output location, component naming, and row identity metadata.
- Must contain datasets sufficient to derive all required deterministic CSV views.
### csv/displacements.csv
- Required when nodal displacement is a verification quantity.
- Must include step/frame identity, node id, displacement components, coordinate system, and units.
### reactions.csv
### csv/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.
### element_forces.csv
### csv/element_forces.csv
- Required when element internal force is a verification quantity.
- Must include step/frame identity, element id, output location, component, value, and units.
### stresses.csv
### csv/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 CSVs
- `strains.csv`: required when strain is part of the acceptance criteria.
- `energy_or_residual.csv`: required when energy balance, residual, or convergence data is part of the acceptance criteria.
### Optional CSV Views
- `csv/strains.csv`: required when strain is part of the acceptance criteria.
- `csv/energy_or_residual.csv`: required when energy balance, residual, or convergence data is part of the acceptance criteria.
## Coverage Matrix
| requirement_id | model_id | compared_quantity | artifact_file | tolerance | verification_method | status |
| --- | --- | --- | --- | --- | --- | --- |
| <req-id> | <model-id> | displacement | displacements.csv | <policy> | reference-comparison | draft |
| <req-id> | <model-id> | reaction | reactions.csv | <policy> | reference-comparison | draft |
| <req-id> | <model-id> | element force | element_forces.csv | <policy> | reference-comparison | draft |
| <req-id> | <model-id> | stress | stresses.csv | <policy> | reference-comparison | draft |
| requirement_id | model_id | compared_quantity | hdf5_dataset | csv_view | tolerance | verification_method | status |
| --- | --- | --- | --- | --- | --- | --- | --- |
| <req-id> | <model-id> | displacement | <dataset path> | csv/displacements.csv | <policy> | reference-comparison | draft |
| <req-id> | <model-id> | reaction | <dataset path> | csv/reactions.csv | <policy> | reference-comparison | draft |
| <req-id> | <model-id> | element force | <dataset path> | csv/element_forces.csv | <policy> | reference-comparison | draft |
| <req-id> | <model-id> | stress | <dataset path> | csv/stresses.csv | <policy> | reference-comparison | draft |
## Artifact Acceptance Checklist
- 모든 `must` requirement가 최소 하나의 `model_id`와 `compared_quantity`에 연결되어 있다.
- `model.inp`가 기능별 supported Abaqus keyword subset을 벗어나지 않는다.
- `metadata.json`에 provenance, Abaqus version/source, units, coordinate system, tolerance, CSV schema version이 기록되어 있다.
- 필수 CSV 파일이 존재하거나, 기능상 불필요한 파일은 명확한 reason과 함께 제외되어 있다.
- output request가 필요한 CSV 물리량을 생성할 수 있도록 정의되어 있다.
- reference CSV가 없으면 status는 `needs-reference-artifacts`다.
- `metadata.json`에 provenance, Abaqus version/source, units, coordinate system, tolerance, HDF5 schema version, CSV view schema version이 기록되어 있다.
- `reference.h5`가 존재하거나, 기능상 불필요하면 명확한 reason과 함께 제외되어 있다.
- 필수 deterministic CSV view가 존재하거나, 기능상 불필요한 view는 명확한 reason과 함께 제외되어 있다.
- output request가 필요한 HDF5 dataset과 CSV view 물리량을 생성할 수 있도록 정의되어 있다.
- `reference.h5` 또는 required CSV view가 없으면 status는 `needs-reference-artifacts`다.
- tolerance, source, units, coordinate system이 불명확하면 status는 `needs-user-decision`이다.
## Open Issues and Downstream Handoff
### I/O Definition Agent
- <supported keyword, output request, CSV schema clarification>
- <supported keyword, output request, HDF5 schema clarification, CSV view schema clarification>
### Implementation Planning Agent
- <tests that should fail before implementation, model order, acceptance criteria>
### Reference Verification Agent
- <CSV schema, ID matching, units, coordinate conventions, output locations, tolerance mapping>
- <HDF5 dataset paths, CSV view 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>
@@ -198,8 +209,8 @@ Optional files:
- Reference model의 목적과 검증 대상 requirement가 명확해야 한다.
- `model.inp`는 Abaqus input file이며, 기능별 supported keyword subset을 따라야 한다.
- model data와 history data를 구분해야 한다.
- output request와 required CSV 사이의 연결이 명확해야 한다.
- output request와 required HDF5 dataset/CSV view 사이의 연결이 명확해야 한다.
- `references/<feature-id>/<model-id>/` 구조와 필수 artifact가 명시되어야 한다.
- `metadata.json`에는 provenance, Abaqus version/source, units, coordinate system, tolerance, CSV schema version이 포함되어야 한다.
- reference CSV가 없으면 완료 상태가 아니라 `needs-reference-artifacts` 상태로 둔다.
- 모든 `must` requirement는 Coverage Matrix에서 model, compared quantity, tolerance, verification method로 추적되어야 한다.
- `metadata.json`에는 provenance, Abaqus version/source, units, coordinate system, tolerance, HDF5 schema version, CSV view schema version이 포함되어야 한다.
- `reference.h5` 또는 required CSV view가 없으면 완료 상태가 아니라 `needs-reference-artifacts` 상태로 둔다.
- 모든 `must` requirement는 Coverage Matrix에서 model, compared quantity, HDF5 dataset, CSV view, tolerance, verification method로 추적되어야 한다.