김경종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 입력 계약과 HDF5 결과/reference schema를 정의해야 한다. CSV는 upstream 요구조건이 명시한 export 또는 comparison helper가 있을 때만 추가로 정의한다.
I/O Definition Agent 역할
I/O Definition Agent는 Abaqus input file subset, 내부 solver model mapping, output request mapping, HDF5 result/reference schema, optional CSV export 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의 metadata, mesh, step/frame, nodal/element field output, history output dataset schema를 정의한다.- upstream 요구조건이 명시한 경우에만
displacements.csv,reactions.csv,element_forces.csv,stresses.csv같은 optional CSV export schema를 정의한다.
수행하지 않는다:
- parser를 구현하지 않는다.
- C++ API나 파일 구조를 설계하지 않는다.
- Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않는다.
- reference HDF5 artifact 또는 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>
## HDF5 Result and Reference Schemas
### results.h5
```text
/metadata
feature_id
solver_version
model_id
hdf5_version
schema_version
units
tolerance
reference_solver
/mesh/nodes
/mesh/elements/<element-family>/connectivity
/results/step_<id>/frame_<id>/nodal/<quantity>
/results/step_<id>/frame_<id>/element/<quantity>
/results/step_<id>/frame_<id>/history
각 dataset은 path, shape, datatype, ID field, component naming, coordinate system, units, output location, step/frame identity, ID matching rule을 명시해야 한다.
Required MITC4 Quantity Datasets
| quantity | default dataset path | id/matching fields | component contract |
|---|---|---|---|
| nodal displacement | /results/step_000/frame_000/nodal/displacement |
node id, component | U1, U2, U3, UR1, UR2, UR3 |
| nodal reaction | /results/step_000/frame_000/nodal/reaction |
node id, component | RF1, RF2, RF3, RM1, RM2, RM3 |
| element force/resultant | /results/step_000/frame_000/element/forces |
element id, Gauss point, component | N11, N22, N12, M11, M22, M12, Q13, Q23 |
| stress | /results/step_000/frame_000/element/stress |
element id, Gauss point, section point, component | S11, S22, S12, S13, S23 |
Optional CSV Export Schemas
CSV output is not required for the current MITC4 HDF5-first feature unless an upstream requirement explicitly asks for it. When CSV export is required, it must preserve the same IDs, components, units, coordinate system, output location, and step/frame identity as the HDF5 datasets.
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:
- duplicate_labels:
- missing_references:
- unsupported_keywords: unsupported | ignored-with-warning | requires-user-decision
- set_expansion:
- coordinate_conventions:
- output_quantity_availability:
Open Issues and Downstream Handoff
Reference Model Agent
Implementation Planning Agent
- <parser acceptance cases, unsupported keyword diagnostics, HDF5 writer tests, optional CSV export tests>
Reference Verification Agent
- <HDF5 dataset schemas, optional 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를 확정하지 않는다.
- HDF5 schema는 dataset path, shape, datatype, ID field, component naming, coordinate system, units, step/frame identity, quantity location을 포함해야 한다.
- Optional CSV schema는 명시적으로 요구된 경우에만 정의하며, HDF5 schema와 동일한 물리 의미와 matching rule을 유지해야 한다.