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

docs: align FESA agents with minimal reference cases

Browse Source
This commit is contained in:
KOKO\Mimi
2026-08-12 03:31:08 +09:00
parent 5c08f1cf83
commit 188bf31e44
27 changed files with 438 additions and 593 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/reference-models/README.md
+63 -193
View File
@@ -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.