FESADev/docs/mitc4-shell-feast-eigen2/io.md

# MITC4 eigen I/O 계약

- Feature ID: `mitc4-shell-feast-eigen2`; Owner: `io-definition-agent`; Contract revision: `r1`.
- 입력 baseline: [requirements r1](requirements.md), [formulation r1](formulation.md).
- 기준: [프로젝트 지침](../../AGENTS.md), [PRD](../PRD.md), [ADR-028](../ADR.md#adr-028),
  [ARCHITECTURE](../ARCHITECTURE.md), [Feature ADR](ADR.md).
- 상태: formulation r1과 독립 NR의 `pass-for-io-definition` 및 최종 controls/reference-model을 반영한 I/O 계약 작성 완료. 구현·실행 검증 기록이 아니다.

## 결정

원본 frequency input의 N과 source step을 보존하며 consistent에서 유도한 lumped mass와
실제 MKL FEAST의 N개 고유쌍을 공식 HDF5로 식별한다. 기존 static schema0/1과 CLI/output
lifecycle는 유지한다. Eigen discriminator·density·modal datasets는 additive다.
N개의 global mass-normalized vectors는 내부 검증을 위해 필수이며 외부 shape gate는 없다.
전체 c개의 내부 validation evidence는 공개 mode N개와 분리한다.

| 상세 문서 | 권위와 내용 |
| --- | --- |
| [io-input](io-input.md) | Supported syntax/defaults, source scope, rho/BC mapping, no-op allowlist, fail-closed diagnostics |
| [io-schema](io-schema.md) | Authoritative HDF5 types/shapes/units, source step·mode identity, all-c evidence, self-check |
| [io-mapping](io-mapping.md) | Domain/AnalysisModel/DOF/state ownership, candidate/failure lifecycle, TXT grammar·prechecks·Value projection |
| [NR controls](numerical-review-controls.md), [reference-model](reference-model.md) | 내부 수치 controls와 외부 modal-frame family; I/O가 tolerance를 선택하지 않음 |

공개 Abaqus convention은 [입력 문서의 공식 출처](io-input.md#step와-frequency)를 직접 대조했다.
Lanczos/SIM은 source compatibility 정보이며 실제 algorithm 동등성을 주장하지 않는다.
ACOUSTIC COUPLING=ON은 acoustic-free 모델에서만 적용 대상 없음으로 처리한다.
물리량은 사용자 일관 units이며 SI로 추론하지 않는다. Meaningful unsupported input은 실패한다.

## 현재 source와의 차이

2026-09-08 지정 source를 읽기 전용으로 직접 확인했다. 아래는 후속 구현 의무이며 현재
동작이 구현되었다는 의미가 아니다. 기존 Feature 문서의 pass·workflow·trace schema는 승계하지 않았다.

| 실제 확인 파일 | 확인 결과와 필요한 연결 |
| --- | --- |
| [input_reader](../../src/fesa/io/abaqus/input_reader.cpp) | ASCII/256-byte/continuation/raw fields와 FNV byte identity 재사용; 새 lexical framework 불필요 |
| [domain_mapping_context](../../src/fesa/io/abaqus/domain_mapping_context.cpp) | RawMaterial에 density 없음, RawStep은 static 전용, DENSITY/FREQUENCY 없음. PERTURBATION/ENERGY OUTPUT도 새 eigen subset 필요. FinalizeStep의 hardcoded Step-1 외에 raw source name·N을 보존해야 함 |
| [material mapper](../../src/fesa/io/abaqus/material_property_mapper.cpp), [step mapper](../../src/fesa/io/abaqus/step_definition_mapper.cpp) | Context 위임 경계다. Density/property와 Frequency semantic 확정은 같은 candidate 흐름에 연결 |
| [model writer](../../src/fesa/io/hdf5/hdf5_model_writer.cpp), [primitives](../../src/fesa/io/hdf5/hdf5_primitives.cpp) | 기존 compounds, UTF-8/fixed-width, user-consistent-unspecified, path+content identity 재사용; material compound 수정 대신 별도 densities |
| [linear writer](../../src/fesa/io/hdf5/hdf5_results_writer.cpp), [nonlinear writer](../../src/fesa/io/hdf5/nonlinear_hdf5_results_writer.cpp), [self_check](../../src/fesa/io/hdf5/hdf5_self_check.cpp) | Static0/1 전용 경로를 eigen에 재사용해 modal 값을 static frame0으로 내면 오류. Dedicated eigen serialization/self-check dispatch 필요 |

## 후속 검증 의무

Requirement prefix는 `FEM-REQ-MITC4-EIGEN2-`다. 아래 검증을 문서 작업 중 실행한 것으로
집계하지 않는다. 수치 기준·oracle는 [NR](numerical-review.md)와 연결된 상세가 권위다.

| ID | 필수 관찰 | Requirement suffix |
| --- | --- | --- |
| IO-T01 | 원본 변경 없이 Step-2/N10/rho2700/t0.5, keyword defaults/no-op warnings·실제 FEAST; S4R source-only 변형 같은 physical path | 001–004,015–016 |
| IO-T02 | 다중 material/section 연결; missing/duplicate/unresolved/0/negative/nonfinite/dependent rho, extra row/field, 잘못된 geometry/section 거부 | 003–004,016 |
| IO-T03 | N blank/0/fraction/overflow, nonblank frequency slots2~7(0 포함), eighth empty slot, duplicate/unknown option, multiple/preload/acoustic/load/nonzero BC 거부 | 001,009,015–016 |
| IO-T04 | Source label/instance/set renumbering·모호함, partial BC·fully constrained·drill-only, 실제 free injection/global 복구; rank cutoff로 tiny positive mass 삭제 금지 | 006–008,014,018 |
| IO-T05 | Additive schema round-trip·source step·units·N/c·mass/backend identity; normalized final phi로 original residual/Gram/energy 재검증; raw negative/zero/positive와 frequency subset | 010–013,017–018 |
| IO-T06 | 실제 FEAST known zero/repeated/cluster/n1/N=n·full capacity, optional abandoned count와 safe fallback, count/reset/budget/index/allocation/Gram/residual 실패; 최종 N과 c 구별 | 008–013,019 |
| IO-T07 | 기존 accepted state/final 준비 후 solve/validation/log/lock/write/flush/close/reopen/self-check/replace failure injection; 기존 final 보존과 최초 실패 final 미생성 | 012,019 |
| IO-T08 | TXT reorder·같은 Value의 다른 mode 허용; missing/extra/duplicate/nonfinite/malformed/step/quantity/unit/mass/backend/schema 오류를 tolerance 전에 거부; Freq 변화는 Value 판정 불변 | 020–021 |
| IO-T09 | Common inclusive row/RMS 경계·양옆, near-zero와 zero-scale; singleton은 row5% pass/RMS1% fail을 구별 | 022 |
| IO-T10 | Density 없는 static 입력과 schema0/1 유지, retained shell/shellNL/linear-limit source identity·U/UR/reaction 분류와 fresh 회귀, 제외 예제0건 | 023–025,027 |
| IO-T11 | Consistent→lumped 원본 연결과 같은 mass의 실제 FEAST/검증; mass oracle·inertia/null·coordinate/NR-MFE-001 및 deterministic assembly/row/diagnostic | 005–008,011,013–014,023,026–027 |

## 최종 대조와 미실행

최종 NR의 B=0 enclosure, 초기 count 최대3회·전체 count512/solve3, fixed a0와
optional upper search 종료·certified fallback, normalized final phi metrics를 대조했다.
별도 per-call control 변경 없이 base_fpm 한 개와 count index49 override로 현재 controls를 표현한다.

입력 계약과 additive schema 선택은 이번 요청 안의 정의 작업이다. 기존 static public 호환성
변경은 없다. 새 mode shape 외부 acceptance, CSV mandate, reference 보조 metadata, full matrix
mandatory dump, lower/empty-prefix 검색 schema를 추가하지 않았다.

현재 source의 density/Frequency/state/writer 연결은 미구현이다. Research G01/G02의 installed
FEAST 동작·workspace와 실제 peak memory, retained regression/새 eigen reference 및 physics
검증은 후속 실행 의무다. Safe enclosure fallback이 runtime 확인을 대신하지 않는다.
문서만 수정하므로 build/test/Harness/FEAST/외부 solver를 실행하지 않았다. Source/test/reference와
제외 네 예제의 원본·복사·cache는 수정·검증에 사용하지 않았다.

정적 검사: owned 문서 4개의 UTF-8·Markdown fence·trailing whitespace·상대 파일 링크
41개와 원본 TXT full grammar/finite Value/unique Mode1..10을 Python read-only 검사로 확인했다.
경로 한정 `git diff --check`도 exit0이었다. Untracked 문서는 별도 내용 검사로 확인했으며
diff 검사만으로 검증했다고 하지 않는다. Build/test와 수치 comparison은 미실행이다.