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

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

Abaqus User Subroutine 검증 모델의 입력 파일은 Abaqus input file이다. 이 프로젝트는 Abaqus 전체 문법 호환 parser 개발을 목표로 하지 않고, 기능별로 필요한 Abaqus keyword subset과 결과 CSV schema를 명확히 정의한다.

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

## I/O Definition Agent 역할

I/O Definition Agent는 Abaqus input file subset, 내부 solver model mapping, output request mapping, comparison CSV 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의 의미 계약을 정의한다.
- `displacements.csv`, `reactions.csv`, `element_forces.csv`, `stresses.csv` schema를 정의한다.

수행하지 않는다:
- parser를 구현하지 않는다.
- Fortran source layout이나 파일 구조를 설계하지 않는다.
- 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: This feature 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 and CSV Schemas

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

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

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

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

## 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, CSV writer tests>

### Reference Verification Agent
- <CSV 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로 작성하고 Fortran source layout이나 helper API를 확정하지 않는다.
- CSV schema는 column name, ID field, component naming, coordinate system, units, step/frame identity, quantity location을 포함해야 한다.