FESADev/docs/reference-models/README.md

Reference Model 문서 작성 가이드

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

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 요구사항을 정의해야 한다.

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 안에 있는지 확인한다.
• references/<feature-id>/<model-id>/ artifact bundle 구조와 필수 파일을 정의한다.
• metadata.json provenance, 단위, 좌표계, Abaqus version/source, output request, tolerance 정책을 정의한다.
• reference.h5 요구사항과 HDF5 dataset에서 추출되는 deterministic CSV view 요구사항을 정의한다.
• requirement와 model, compared quantity, tolerance, artifact status를 연결하는 Coverage Matrix를 작성한다.

수행하지 않는다:

• C++ 코드를 구현하지 않는다.
• parser를 구현하지 않는다.
• C++ API나 파일 구조를 설계하지 않는다.
• Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않는다.
• reference HDF5 파일이나 deterministic CSV view를 생성하지 않는다.
• 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, 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

### <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 | element 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: references/<feature-id>/<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 reference.h5 datasets and deterministic CSV views>
- unsupported_keyword_policy: unsupported | ignored-with-warning | requires-user-decision

## Artifact Bundle Contract

```text
references/
  <feature-id>/
    <model-id>/
      model.inp
      metadata.json
      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.
• 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:

• 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

{
  "feature_id": "<feature-id>",
  "model_id": "<model-id>",
  "artifact_status": "draft | needs-reference-artifacts | ready-for-implementation-planning | blocked",
  "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>"],
  "hdf5_schema_version": "<version>",
  "csv_view_schema_version": "<version>",
  "csv_view_source": "reference.h5",
  "tolerance_policy": "<absolute/relative/norm policy>",
  "limitations": ["<known limitation>"]
}

Reference HDF5 and CSV View Requirements

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.

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.

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.

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 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	hdf5_dataset	csv_view	tolerance	verification_method	status
		displacement		csv/displacements.csv		reference-comparison	draft
		reaction		csv/reactions.csv		reference-comparison	draft
		element force		csv/element_forces.csv		reference-comparison	draft
		stress		csv/stresses.csv		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, 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, HDF5 schema clarification, CSV view schema clarification>

Implementation Planning Agent

• <tests that should fail before implementation, model order, acceptance criteria>

Reference Verification Agent

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

## 품질 기준

- Reference model의 목적과 검증 대상 requirement가 명확해야 한다.
- `model.inp`는 Abaqus input file이며, 기능별 supported keyword subset을 따라야 한다.
- model data와 history data를 구분해야 한다.
- output request와 required HDF5 dataset/CSV view 사이의 연결이 명확해야 한다.
- `references/<feature-id>/<model-id>/` 구조와 필수 artifact가 명시되어야 한다.
- `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로 추적되어야 한다.