# 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 artifact나 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 안에 있는지 확인한다.
- `references/<feature-id>/<model-id>/` artifact bundle 구조와 필수 파일을 정의한다.
- `metadata.json` provenance, 단위, 좌표계, Abaqus version/source, output request, HDF5 schema version, tolerance 정책을 정의한다.
- `results.h5` 또는 feature-specific HDF5 reference result file 요구사항을 정의한다.
- upstream 요구조건이 명시한 경우에만 `displacements.csv`, `reactions.csv`, `element_forces.csv`, `stresses.csv` 같은 optional CSV export 요구사항을 정의한다.
- requirement와 model, compared quantity, tolerance, artifact status를 연결하는 Coverage Matrix를 작성한다.

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

## 문서 템플릿

```markdown
# <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, results.h5 |
| <model-id> | analytical | <closed-form comparison> | draft | model.inp, metadata.json, results.h5 |
| <model-id> | patch test | <element consistency check> | draft | model.inp, metadata.json, results.h5 |
| <model-id> | benchmark | <trusted benchmark comparison> | draft | model.inp, metadata.json, results.h5 |
| <model-id> | regression | <known defect guard> | draft | model.inp, metadata.json, results.h5 |
| <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 HDF5 datasets>
- unsupported_keyword_policy: unsupported | ignored-with-warning | requires-user-decision

## Artifact Bundle Contract

```text
references/
  <feature-id>/
    <model-id>/
      model.inp
      metadata.json
      results.h5
      README.md
```

Required files:
- `model.inp`: Abaqus input file for the reference model.
- `metadata.json`: provenance and model contract metadata.
- `results.h5`: HDF5 reference result artifact containing required metadata, mesh, step/frame, nodal, element, field, and history result datasets.
- `README.md`: short description, generation notes, and limitations.

Optional files:
- `displacements.csv`: nodal displacement export when upstream contracts explicitly require CSV.
- `reactions.csv`: nodal reaction force export when upstream contracts explicitly require CSV.
- `element_forces.csv`: element internal force export when upstream contracts explicitly require CSV.
- `stresses.csv`: stress export when upstream contracts explicitly require CSV.
- `strains.csv`: strain reference results when required.
- `energy_or_residual.csv`: energy, residual, or convergence reference results when required.
- `notes.md`: manual review notes.

For the current `mitc4-linear-static-shell` feature, the required stored Abaqus artifacts are:

```text
references/mitc4-linear-static-shell/<model-id>/
  model.inp
  metadata.json
  abaqus_s4r/results.h5
  abaqus_s4/results.h5
  README.md
```

`abaqus_s4r/results.h5` is the primary pass/fail reference. `abaqus_s4/results.h5` is diagnostic.

## Metadata JSON Contract

```json
{
  "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>",
  "tolerance_policy": "<absolute/relative/norm policy>",
  "limitations": ["<known limitation>"]
}
```

## Reference HDF5 Requirements

- Required when reference comparison is part of the feature acceptance criteria.
- Must include metadata, mesh identity, step/frame identity, node and element IDs, component names, coordinate system, units, output locations, and tolerance source.
- Required quantity datasets must match the paths and component contracts from `docs/io-definitions/<feature-id>-io.md`.

## Optional CSV Export Requirements

CSV exports are not required for the current HDF5-first MITC4 feature unless an upstream document explicitly requires them. When required, they must preserve the same physical meaning and matching keys as the HDF5 datasets.

### 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
- 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
- Required when element internal force is a verification quantity.
- Must include step/frame identity, element id, output location, component, value, and units.

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

## Coverage Matrix

| requirement_id | model_id | compared_quantity | artifact_file | tolerance | verification_method | status |
| --- | --- | --- | --- | --- | --- | --- |
| <req-id> | <model-id> | displacement | results.h5:/results/.../nodal/displacement | <policy> | reference-comparison | draft |
| <req-id> | <model-id> | reaction | results.h5:/results/.../nodal/reaction | <policy> | reference-comparison | draft |
| <req-id> | <model-id> | element force | results.h5:/results/.../element/forces | <policy> | reference-comparison | draft |
| <req-id> | <model-id> | stress | results.h5:/results/.../element/stress | <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, HDF5 schema version이 기록되어 있다.
- 필수 HDF5 artifact가 존재하거나, 기능상 불필요한 파일은 명확한 reason과 함께 제외되어 있다.
- output request가 필요한 HDF5 물리량을 생성할 수 있도록 정의되어 있다.
- reference HDF5 artifact가 없으면 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>

### Implementation Planning Agent
- <tests that should fail before implementation, model order, acceptance criteria>

### Reference Verification Agent
- <HDF5 schema, optional 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 HDF5 dataset 사이의 연결이 명확해야 한다.
- `references/<feature-id>/<model-id>/` 구조와 필수 artifact가 명시되어야 한다.
- `metadata.json`에는 provenance, Abaqus version/source, units, coordinate system, tolerance, HDF5 schema version이 포함되어야 한다.
- reference HDF5 artifact가 없으면 완료 상태가 아니라 `needs-reference-artifacts` 상태로 둔다.
- 모든 `must` requirement는 Coverage Matrix에서 model, compared quantity, tolerance, verification method로 추적되어야 한다.