# FESA HDF5 Schema 1.0.0

## 1. 범위

Schema `1.0.0`은 `results-and-pipeline` Phase의 최소 수직 슬라이스를 정의한다.
파일은 활성 `Domain`의 절점, Beam 연결성, 적용된 전단면적과 그 출처, 그리고 전역
좌표계 절점 변위·회전 및 반력·반력모멘트를 저장한다. 단위 변환은 수행하지 않는다.

이 버전에는 재료 전체 속성, 집합, 하중·경계조건, solver 설정, 요소 결과, history,
reference CSV 및 진단 dataset을 저장하지 않는다. 이후 같은 major version에서
dataset을 추가할 수 있지만 아래 required object의 의미, 형상 또는 datatype을
변경해서는 안 된다.

## 2. 공통 규칙

- root attribute `schema_version`은 UTF-8 문자열 `1.0.0`이다.
- 정수 dataset은 명시한 little-endian 고정폭 타입을 사용한다.
- 실수 dataset은 IEEE 754 little-endian 64-bit 타입을 사용한다.
- 문자열 dataset과 attribute는 UTF-8 variable-length string을 사용한다.
- `dense_index`는 해당 dataset 행의 0-based index이며 연속적이다.
- `internal_id`와 결과의 `node_ids`는 FESA semantic model의 nonnegative ID다.
- flat/orphan mesh의 `part_name`과 `instance_name`은 빈 문자열이다.
- 결과의 6개 component 순서는
  `(Ux, Uy, Uz, Rx, Ry, Rz)` 및 `(RFx, RFy, RFz, RMx, RMy, RMz)`다.
- Step과 frame group 이름은 각각 0부터 연속된 decimal index다. 원래 Step 이름은
  Step group의 `name` attribute에 저장한다.

## 3. Required objects

```text
/
├── @schema_version                         UTF-8 = "1.0.0"
├── model
│   ├── nodes
│   │   ├── dense_index                    uint64 [node_count]
│   │   ├── internal_id                    int64  [node_count]
│   │   ├── part_name                      UTF-8  [node_count]
│   │   ├── instance_name                  UTF-8  [node_count]
│   │   ├── local_label                    int64  [node_count]
│   │   └── coordinates                    float64[node_count, 3]
│   ├── elements
│   │   ├── dense_index                    uint64 [element_count]
│   │   ├── internal_id                    int64  [element_count]
│   │   ├── connectivity                   uint64 [element_count, 2]
│   │   └── section_id                     int64  [element_count]
│   └── sections
│       ├── internal_id                    int64  [section_count]
│       ├── shear_area_y                   float64[section_count]
│       ├── shear_area_z                   float64[section_count]
│       └── shear_source                   uint8  [section_count]
└── results
    └── steps
        └── <step_index>
            ├── @name                      UTF-8
            └── frames
                └── <frame_index>
                    ├── @step_time         float64
                    └── nodal
                        ├── node_ids        int64  [result_node_count]
                        ├── displacement    float64[result_node_count, 6]
                        └── reaction        float64[result_node_count, 6]
```

`model/elements/connectivity`는 `model/nodes/dense_index`를 참조한다. 따라서
`internal_id`가 연속적이거나 Domain 저장 순서와 같다고 가정하지 않는다.
`section_id`는 `model/sections/internal_id`를 참조한다.

`shear_source` 값은 다음과 같다.

| 값 | 의미 |
|---:|---|
| `0` | 입력에서 명시된 전단강성으로부터 구성한 값 (`input`) |
| `1` | Phase 1 기본값 `Asy=Asz=5A/6`, `SCF=0` (`phase1_default`) |

## 4. Writer와 reader 계약

- writer는 쓰기 전에 `ResultDatabase` 유효성과 schema version을 검사한다.
- schema `1.0.0`이 표현하지 않는 non-empty frame diagnostics는 파일을 만들기 전에
  `hdf5.unsupported_result_diagnostics`로 거부한다.
- required object 생성·쓰기·flush·close 중 HDF5 오류가 발생하면 성공으로 반환하지
  않고 `DiagnosticStage::results` 오류로 변환한다.
- reader는 schema version, required object, datatype, rank와 shape를 검사한다.
- reader는 model internal ID의 uniqueness, finite coordinates 및 finite positive
  shear area를 검사한다.
- writer와 reader는 모든 nodal result ID가 `model/nodes/internal_id`에 존재하는지
  검사하며, 없는 ID를 성공 결과로 반환하지 않는다.
- reader는 nodal result를 `ResultDatabase`로, model dataset을 HDF5 adapter 전용
  read-only inspection model로 반환한다. `Domain`과 `ResultDatabase`에는 HDF5
  저장 계약을 추가하지 않는다.
- malformed 또는 지원하지 않는 파일은 부분 database를 반환하지 않는다.