FESADev/docs/reference-models/README.md

Reference Model 문서 작성 가이드

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

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 형식을 사용한다. 각 문서는 요구조건, 연구 브리프, 정식화, 수치 리뷰, I/O 정의를 입력으로 받아 구현 전에 준비해야 할 테스트 모델과 reference artifact 요구사항을 정의해야 한다.

Reference Model Agent 역할

수행한다:

• 기능별 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 구조와 필수 파일을 정의한다.
• metadata.json provenance, 단위, 좌표계, Abaqus version/source, output request, tolerance 정책을 정의한다.
• Abaqus reference CSV 파일 요구사항을 정의한다.
• requirement와 model, compared quantity, FESA HDF5 dataset, reference CSV, tolerance, artifact status를 연결하는 Coverage Matrix를 작성한다.

수행하지 않는다:

• C++ 코드를 구현하지 않는다.
• parser를 구현하지 않는다.
• C++ API나 파일 구조를 설계하지 않는다.
• Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않는다.
• Abaqus reference CSV 파일을 생성하거나 수정하지 않는다.
• solver 결과를 비교하지 않는다.
• release readiness를 승인하지 않는다.
• reference 값, tolerance, Abaqus compatibility를 임의로 만들지 않는다.

문서 템플릿

# <feature title> Reference Models

## 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>

## Model Inventory

| model_id | category | purpose | status | required_artifacts |
| --- | --- | --- | --- | --- |
| <model-id> | smoke | <basic parser/solve path> | draft | model.inp, metadata.json, required Abaqus reference CSV files |
| <model-id> | analytical | <closed-form comparison> | draft | model.inp, metadata.json, required Abaqus reference CSV files |
| <model-id> | patch test | <element consistency check> | draft | model.inp, metadata.json, required Abaqus reference CSV files |
| <model-id> | benchmark | <trusted benchmark comparison> | draft | model.inp, metadata.json, required Abaqus reference CSV files |
| <model-id> | regression | <known defect guard> | draft | model.inp, metadata.json, required Abaqus reference CSV files |
| <model-id> | negative/invalid-input | <unsupported keyword or invalid model diagnostic> | draft | model.inp, metadata.json |

## Model Record

### <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

## 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

## Artifact Bundle Contract

```text
reference/
  <model-id>/
    model.inp
    metadata.json
    <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.
• metadata.json: provenance and model contract metadata.
• <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:

• <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.

Metadata JSON Contract

{
  "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
		displacement	/steps//frames//field_outputs/U	reference//_displacements.csv		hdf5-to-reference-csv	draft
		reaction	/steps//frames//field_outputs/RF	reference//_reactions.csv		hdf5-to-reference-csv	draft
		internal force	/steps//frames//field_outputs/element_forces	reference//_internalforces.csv		hdf5-to-reference-csv	draft
		stress	/steps//frames//field_outputs/S	reference//_stresses.csv		hdf5-to-reference-csv	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, reference CSV schema version이 기록되어 있다.
• 필요한 Abaqus reference CSV 파일이 존재하거나, 기능상 불필요한 quantity는 명확한 reason과 함께 제외되어 있다.
• output request가 필요한 Abaqus reference CSV 물리량을 생성할 수 있도록 정의되어 있다.
• required Abaqus reference CSV 또는 metadata provenance가 없으면 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, 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>

## 품질 기준

- 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가 명시되어야 한다.
- `metadata.json`에는 provenance, Abaqus version/source, units, coordinate system, tolerance, reference CSV schema version이 포함되어야 한다.
- required Abaqus reference CSV가 없으면 완료 상태가 아니라 `needs-reference-artifacts` 상태로 둔다.
- 모든 `must` requirement는 Coverage Matrix에서 model, compared quantity, FESA HDF5 dataset, reference CSV, tolerance, verification method로 추적되어야 한다.