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를 정의한다.
FESA HDF5 dataset을 reference/<model-id>/ 아래 Abaqus reference CSV rows와 비교하기 위한 deterministic row schema를 정의한다.

수행하지 않는다:

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

문서 템플릿

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

FESA solver output은 `results.h5`이다. Comparison tooling reads required HDF5 datasets and maps them to deterministic row records that can be matched against Abaqus reference CSV files under `reference/<model-id>/`.

공통 규칙:
- reference_root: `reference/<model-id>/`
- hdf5_schema_version: <version>
- reference_csv_schema_version: <version>
- sort_order: step, frame, id, location, component
- numeric_format: <precision and exponent policy>
- missing_component_policy: 0 | N/A | omitted, feature-specific
- hdf5_dataset_source: HDF5 dataset path를 각 row schema 또는 report에 기록한다.

### displacement rows / `<model-id>_displacements.csv`
| column | type | description |
| --- | --- | --- |
| step | string | step name or index |
| frame | integer | frame or increment id |
| node_id | integer/string | Abaqus node label |
| ux | float | displacement component |
| uy | float | displacement component or 0/N/A |
| uz | float | displacement component or 0/N/A |

### reaction rows / `<model-id>_reactions.csv`
| column | type | description |
| --- | --- | --- |
| step | string | step name or index |
| frame | integer | frame or increment id |
| node_id | integer/string | Abaqus node label |
| rfx | float | reaction component |
| rfy | float | reaction component or 0/N/A |
| rfz | float | reaction component or 0/N/A |

### internal force rows / `<model-id>_internalforces.csv`
| column | type | description |
| --- | --- | --- |
| step | string | step name or index |
| frame | integer | frame or increment id |
| element_id | integer/string | Abaqus element label |
| location | string | element/nodal/integration_point location |
| component | string | force component name |
| value | float | component value |

### stress rows / `<model-id>_stresses.csv`
| column | type | description |
| --- | --- | --- |
| step | string | step name or index |
| frame | integer | frame or increment id |
| element_id | integer/string | Abaqus element label |
| integration_point | integer/string | integration point id or N/A |
| component | string | stress component name |
| value | float | stress value |

## 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 row schema는 column name, stable sort order, ID field, component naming, coordinate system, units, step/frame identity, quantity location을 포함해야 한다.