# I/O 정의 문서 작성 가이드

이 디렉터리는 I/O Definition Agent가 작성하거나 제안한 기능별 입출력 정의 문서를 보관하는 위치다.

FESA 솔버의 입력 파일은 Abaqus input file이다. 다만 초기 FESA는 Abaqus 전체 문법 호환을 목표로 하지 않고, 기능별로 지원할 Abaqus keyword subset과 내부 모델 매핑을 명확히 정의한다.

기본 파일명은 `docs/io-definitions/<feature-id>-io.md` 형식을 사용한다. 각 문서는 Requirement Agent, Formulation Agent, Numerical Review Agent의 산출물을 입력으로 받아 Abaqus `.inp` 입력 계약, authoritative HDF5 result schema, FESA HDF5 to Reference CSV comparison schema를 정의해야 한다.

## I/O Definition Agent 역할

I/O Definition Agent는 Abaqus input file subset, 내부 solver model mapping, output request mapping, HDF5 result schema, reference CSV comparison row schema를 정의한다.

수행한다:
- 기능별 supported Abaqus keyword subset을 정의한다.
- unsupported, ignored-with-warning, requires-user-decision keyword 정책을 정의한다.
- model data와 history data를 내부 solver 개념으로 매핑한다.
- node, element, set, material, section, boundary condition, load, step, output request의 의미 계약을 정의한다.
- `results.h5`의 authoritative HDF5 schema를 정의한다.
- 기능이 선언한 existing Abaqus CSV와 비교하기 위한 최소 source-ID/component mapping을 정의한다.

수행하지 않는다:
- parser를 구현하지 않는다.
- C++ API나 파일 구조를 설계하지 않는다.
- Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않는다.
- Abaqus reference CSV 파일을 생성하거나 수정하지 않는다.
- solver 결과와 reference 결과를 비교하지 않는다.
- release readiness를 승인하지 않는다.
- 명시적으로 정의되지 않은 Abaqus full compatibility를 주장하지 않는다.

## 문서 템플릿

```markdown
# <feature title> I/O Definition

## Metadata
- feature_id: <feature-id>
- source_requirement: docs/requirements/<feature-id>.md
- source_formulation: docs/formulations/<feature-id>-formulation.md
- source_numerical_review: docs/numerical-reviews/<feature-id>-review.md
- source_research: docs/research/<feature-id>-research.md
- status: draft | needs-user-decision | ready-for-implementation-planning
- owner_agent: io-definition-agent
- date: <YYYY-MM-DD>

## Abaqus Input Scope
- input_format: Abaqus input file (`.inp`)
- abaqus_documentation_source: <version/source URL>
- compatibility_disclaimer: FESA supports only the keyword subset defined in this document.

| keyword | support_status | level | required_parameters | mapped_internal_concept | notes |
| --- | --- | --- | --- | --- | --- |
| *HEADING | supported | model | N/A | model title | optional |
| *INCLUDE | supported | model/history | INPUT | include file | path policy required |
| *NODE | supported | model | N/A | node label and coordinates |  |
| *NSET | supported | model | NSET | node set | sorted/unsorted policy required |
| *ELEMENT | supported | model | TYPE | element label, type, connectivity |  |
| *ELSET | supported | model | ELSET | element set |  |
| *MATERIAL | supported | model | NAME | material |  |
| *ELASTIC | supported | model | N/A or TYPE | elastic material data |  |
| <section keyword> | supported | model | ELSET, MATERIAL | section assignment | e.g. *SOLID SECTION |
| *BOUNDARY | supported | model/history | N/A | boundary condition |  |
| *CLOAD | supported | history | N/A | concentrated load | feature-dependent |
| *DLOAD | supported | history | N/A | distributed load | feature-dependent |
| *STEP | supported | history | N/A | analysis step |  |
| <procedure keyword> | supported | history | N/A | analysis procedure | e.g. *STATIC |
| *OUTPUT | supported | history | N/A | output request root |  |
| *NODE OUTPUT | supported | history | N/A | nodal output request |  |
| *ELEMENT OUTPUT | supported | history | N/A | element output request |  |

## Syntax Policy
- case_insensitivity: <policy>
- comma_separated_fields: <policy>
- comment_lines: lines beginning with `**`
- keyword_continuation: <policy>
- include_files: <relative path policy>
- labels: <case/quote/name policy>
- line_length_limit: <policy>
- ascii_assumption: <policy>
- empty_data_fields: <policy>

## Model Data Mapping
- nodes: <node label, coordinate dimension, coordinate system>
- elements: <element label, element type, connectivity>
- node_sets: <set name, sorted/unsorted, expansion rules>
- element_sets: <set name, expansion rules>
- material: <material name and data>
- section: <section assignment>
- coordinates: <global/local coordinate conventions>
- units: <unit system policy>

## History Data Mapping
- steps: <step naming and order>
- procedure: <analysis procedure keyword mapping>
- boundary_conditions: <boundary condition mapping>
- loads: <load keyword mapping>
- output_requests: <node/element output mapping>

## Internal Model Contract
- node_label: <semantic contract>
- element_label: <semantic contract>
- element_type: <semantic contract>
- connectivity: <semantic contract>
- set_membership: <semantic contract>
- material: <semantic contract>
- section: <semantic contract>
- boundary_condition: <semantic contract>
- load: <semantic contract>
- step: <semantic contract>
- output_request: <semantic contract>

## Output HDF5 Schema

- authoritative_file: `results.h5`
- schema_version: <version>
- root_attributes: units, coordinate_system, solver_version, feature_id, model_id
- step_frame_identity: <step/frame naming and ordering>
- row_identity_policy: <node_id | element_id | integration_point | component mapping>

| quantity | dataset_path | shape | dtype | required_attributes | location | notes |
| --- | --- | --- | --- | --- | --- | --- |
| displacement | /steps/<step>/frames/<frame>/field_outputs/U | <nnode, ndim> | float64 | component_names, units | nodal |  |
| reaction | /steps/<step>/frames/<frame>/field_outputs/RF | <nnode, ndim> | float64 | component_names, units | nodal |  |
| element_force | /steps/<step>/frames/<frame>/field_outputs/element_forces | <nrow, ncomp> | float64 | component_names, element_ids, location | element | feature-dependent |
| stress | /steps/<step>/frames/<frame>/field_outputs/S | <nrow, ncomp> | float64 | component_names, element_ids, integration_points | integration_point | feature-dependent |

## FESA HDF5 to Reference CSV Comparison Mapping

FESA solver output은 `results.h5`이다. 기능이 blocking 또는 warning-only로 선언한
quantity에 대해서만 existing CSV path와 다음 mapping을 정의한다.

| field | contract |
| --- | --- |
| reference_input | exact existing `.inp` path |
| reference_csv | exact existing required CSV path |
| hdf5_dataset | authoritative FESA dataset path |
| source_identity | node/element source label used for exact matching |
| components | required CSV columns and corresponding HDF5 components |
| row_precheck | missing/extra/duplicate/nonfinite required rows fail before tolerance |
| behavior | blocking or warning-only |
| tolerance | upstream-approved formula |

Row order alone으로 대응하지 않는다. Canonical filename, reference CSV schema version,
README, metadata, provenance 또는 single-step/final-frame case의 duplicated unit/coordinate/
step-frame columns를 요구하지 않는다.

## Validation Rules
- required_fields: <required input fields>
- duplicate_labels: <policy>
- missing_references: <policy>
- unsupported_keywords: unsupported | ignored-with-warning | requires-user-decision
- set_expansion: <policy>
- coordinate_conventions: <policy>
- output_quantity_availability: <policy>
- hdf5_schema_validation: <required datasets and attributes>
- reference_csv_validation: <stable ordering and required columns>

## Open Issues and Downstream Handoff

### Reference Model Agent
- <Abaqus input examples and reference artifact schema needs>

### Implementation Planning Agent
- <parser acceptance cases, unsupported keyword diagnostics, HDF5 writer tests, comparison row mapping tests>

### Reference Verification Agent
- <HDF5 dataset paths, reference CSV row schemas, ID matching rules, units, coordinate conventions, tolerance-relevant fields>
```

## 품질 기준

- 입력 파일은 Abaqus `.inp`임을 명시해야 한다.
- Abaqus full compatibility를 주장하지 않고 기능별 supported keyword subset을 명시해야 한다.
- model data와 history data의 매핑을 구분해야 한다.
- unsupported keyword 처리 정책을 명확히 해야 한다.
- 내부 모델 계약은 semantic fields로 작성하고 C++ class/function/API를 확정하지 않는다.
- `results.h5`가 authoritative solver output임을 명시해야 한다.
- HDF5 schema는 dataset path, dtype/shape, required attributes, ID field, component naming, coordinate system, units, step/frame identity, quantity location을 포함해야 한다.
- Reference CSV comparison mapping은 exact path, source-ID column, required component columns,
  HDF5 projection, row prechecks와 tolerance를 포함해야 한다.
