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 입력 계약과 결과 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를 구현하지 않는다.
C++ API나 파일 구조를 설계하지 않는다.
Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않는다.
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 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로 작성하고 C++ class/function/API를 확정하지 않는다.
CSV schema는 column name, ID field, component naming, coordinate system, units, step/frame identity, quantity location을 포함해야 한다.