modify documents

docs/io-definitions/README.md

@@ -4,24 +4,25 @@
 
 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를 정의해야 한다.
+기본 파일명은 `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, comparison CSV schema를 정의한다.
+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의 의미 계약을 정의한다.
-- `displacements.csv`, `reactions.csv`, `element_forces.csv`, `stresses.csv` schema를 정의한다.
+- `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 CSV 결과를 생성하지 않는다.
+- reference HDF5 artifact 또는 reference CSV 결과를 생성하지 않는다.
 - solver 결과와 reference 결과를 비교하지 않는다.
 - release readiness를 승인하지 않는다.
 - 명시적으로 정의되지 않은 Abaqus full compatibility를 주장하지 않는다.
@@ -107,7 +108,43 @@ I/O Definition Agent는 Abaqus input file subset, 내부 solver model mapping, o
 - step: <semantic contract>
 - output_request: <semantic contract>
 
-## Output and CSV Schemas
+## 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 |
@@ -161,13 +198,13 @@ I/O Definition Agent는 Abaqus input file subset, 내부 solver model mapping, o
 ## Open Issues and Downstream Handoff
 
 ### Reference Model Agent
-- <Abaqus input examples and reference artifact schema needs>
+- <Abaqus input examples and HDF5 reference artifact schema needs>
 
 ### Implementation Planning Agent
-- <parser acceptance cases, unsupported keyword diagnostics, CSV writer tests>
+- <parser acceptance cases, unsupported keyword diagnostics, HDF5 writer tests, optional CSV export tests>
 
 ### Reference Verification Agent
-- <CSV schemas, ID matching rules, units, coordinate conventions, tolerance-relevant fields>
+- <HDF5 dataset schemas, optional CSV schemas, ID matching rules, units, coordinate conventions, tolerance-relevant fields>
 ```
 
 ## 품질 기준
@@ -177,4 +214,5 @@ I/O Definition Agent는 Abaqus input file subset, 내부 solver model mapping, o
 - 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을 포함해야 한다.
+- 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을 유지해야 한다.