FESADev/docs/mitc4-shell-feast-eigen/io-input.md

# MITC4 eigen 입력 subset과 진단

- Feature ID: `mitc4-shell-feast-eigen`
- Owner: `io-definition-agent`
- Input contract revision: `r2`
- 기본 보고서: [io.md](io.md)

## I1. 문법과 source identity

기존 [linear shell I/O §1](../linear-static-mitc4-shell/io.md),
[현재 pressure I/O §3](../shell-surface-pressure-load/io.md)의 공통 lexical 계약을 재사용한다.
현재 [input reader](../../src/fesa/io/abaqus/input_reader.cpp)와
[mapping context](../../src/fesa/io/abaqus/domain_mapping_context.cpp)를 읽기 전용 대조했다.
예전 nonlinear 문서의 continuation 미지원 설명보다 후속 승인된 pressure lexical 규칙이 우선한다.

- CRLF/LF를 수용한다. Physical line은 종결자를 제외해 최대 256 ASCII bytes이며 printable
  ASCII와 horizontal tab만 허용한다. `**` comment와 blank line은 semantic effect가 없다.
  Inline comment, data continuation, include, substitution, quoted/escaped 이름은 지원하지 않는다.
- Keyword/parameter/enum/name lookup은 ASCII case-insensitive다. Parameter 순서는 무관하지만
  duplicate name은 값이 같아도 실패한다. Raw spelling, keyword physical lines, data fields와
  normalized lexical input path/1-based line을 보존한다. Keyword terminal comma는 기존
  parameter continuation이며 직후 comment/blank/new keyword/EOF interruption은 실패한다.
- Comma split은 빈 필드를 보존한다. 각 token 주변 space/tab만 trim한다. 아래 명시된
  공란 외에 arbitrary trailing-empty 제거를 적용하지 않는다.
- Source node/element label은 positive decimal int64이고 raw digits와 numeric identity를
  분리한다. Scope 내 같은 numeric label은 duplicate다. Name/target는 기존 shell의
  비어 있지 않은 ASCII 이름·qualification 규칙을 재사용한다. 새 step name도 같은
  name token이며 생략 시 source name은 `Step-1`이다. HDF5 path에 raw name을 삽입하지 않는다.
- 새 `rho` numeric token은 `[+-]?(?:[0-9]+(?:\.[0-9]*)?|\.[0-9]+)(?:[Ee][+-]?[0-9]+)?`다.
  C-locale full consumption과 binary64 finite conversion을 요구한다. NaN/Inf, hex, D exponent,
  overflow/underflow conversion error는 실패한다. N은 `[0-9]+`와 checked int64 범위이며
  값이 양수여야 한다. 기존 keyword의 승인된 numeric parsing은 이 기능 때문에 바꾸지 않는다.

## I2. 지원 keyword와 위치

Eigen input의 문법은 `heading? preprint? part+ assembly material+ model-boundary* step EOF`다.
Comments/blank는 블록 사이에 허용한다. 기존 mesh/set nesting과 forward material/section
resolution은 유지한다. 활성 모델은 S4/S4R shell만 포함한다.

| Keyword | Eigen subset·data | 의미와 validation |
| --- | --- | --- |
| `*HEADING` | Optional 첫 keyword, parameter 없음, text rows | Heading provenance. Duplicate/nesting 오류 거부 |
| `*PART`, `*END PART` | `NAME` 하나; close parameter/data 없음 | Part-local topology. 중첩/중복/미종결 거부 |
| `*NODE` | Part scope, parameter 없음; `label,x,y,z` | Finite initial global midsurface coordinates. 중복·잘못된 arity 거부 |
| `*ELEMENT` | Part scope, `TYPE=S4` 또는 `TYPE=S4R`만; `label,n1,n2,n3,n4` | 같은 MITC4 physical/mass path와 별도 source type. 네 distinct resolved nodes 필요 |
| `*NSET`, `*ELSET` | Part/assembly scope; 해당 `NSET=name` 또는 `ELSET=name`, optional flag `GENERATE`; assembly는 `INSTANCE=name` 필수. 기존 assembly ELSET의 `INTERNAL` flag도 유지 | Explicit positive labels, 또는 `first,last,increment` inclusive generate. 기존 set row trailing comma 허용. Nonpositive/역순/도달 불가능 range·empty·duplicate definition·dangling/cyclic/mixed-instance 거부 |
| `*SHELL SECTION` | Part scope, `ELSET`, `MATERIAL` 필수; 한 row `t[,integration_points]` | Centered homogeneous layer, constant finite t>0, element별 유일 assignment. Optional second field가 있으면 positive decimal integer; 아래 예외 적용 |
| `*ASSEMBLY`, `*END ASSEMBLY` | Top-level 하나, `NAME`; close parameter/data 없음 | Assembly scope, nested/duplicate 거부 |
| `*INSTANCE`, `*END INSTANCE` | Assembly scope, `NAME`, `PART`; data 없음 | Identity instances; 같은 part의 여러 identity instance 허용. Transform/dangling/duplicate 거부 |
| `*MATERIAL` | Top-level model data, `NAME`; data 없음 | Named material 소유. Case-insensitive unique |
| `*ELASTIC` | Current material, parameter 없음; 한 row `E,nu` | 기존 finite E>0, -1<nu<0.5; constant isotropic. Missing/duplicate/dependent 거부 |
| `*DENSITY` | Current material, parameter 없음; I3 | Constant positive volume mass density |
| `*BOUNDARY` | Model data 또는 sole step의 FREQUENCY 뒤·output requests 전; parameter 없음; `target,first,last[,value]` | 1<=first<=last<=6, value 생략은 exact0; 있으면 finite exact0만 허용. 네 번째 empty token은 생략과 다르며 거부 |
| `*STEP`, `*END STEP` | I4; 정확히 하나의 top-level step | Prior/multiple/nested step·preload 없음 |
| `*FREQUENCY` | I4; sole step 첫 procedure | Original configuration, undamped real lowest-N eigenproblem |
| 부수 output keywords | I5의 exact combinations만 | Mandatory output 선택/억제 기능 없음, warning provenance |

`t,5`의 두 번째 값은 [기존 사용자 승인 예외](../linear-static-mitc4-shell/io.md#11-shell-section-data-rule)에
따라 warning 없이 읽는 source provenance다. 별도 physical property를 만들지 않는다.
Stiffness는 기존 2×2×2, mass는 [M5](formulation-mass.md)의 3×3×3이며 이 값으로 바뀌지 않는다.
이 예외를 다른 section/material option에 일반화하지 않는다.

Boundary target는 기존 source resolver의 bare node label 또는 unique node-set name이다.
Assembly NSET의 INSTANCE binding으로 원하는 instance를 지정한다. 여러 instance에서
bare target가 모호하면 거부하며 새로운 dotted boundary qualification을 추가하지 않는다.
Model BC 다음 step BC 순서로 resolve하고 node/component별 exact-zero union을 적용한다.
같은 zero constraint 재선언은 동일 constraint다. Nonzero row를 상쇄·override하여 허용하지 않는다.
원본 `(Part-1-1,Set-2)`의 104 nodes×6 DOF가 모두 고정됨을 확인한다.
Global component 제약만 지원하며 tangent/local/MPC constraint를 새로 추론하지 않는다.

## I3. Density material mapping

`*DENSITY`는 한 material에 최대 한 번, 정확히 한 data row이며 첫 field는 rho다.
`rho` 또는 `rho,`만 허용한다. 후자는 원본 `2700.,`의 빈 temperature slot이며
temperature dependence가 없는 constant 값으로 대응한다. Nonempty temperature/field variable,
두 개 이상의 추가 comma, 추가 data row, `DEPENDENCIES`(0 포함), `PORE FLUID`, `SLURRY`,
distribution 이름과 다른 parameter는 거부한다. Elastic과 Density의 상대 선언 순서는 자유다.
Numeric rho가 finite이며 strict >0이어야 한다. Material scope 밖 Density도 실패다.

모든 활성 shell의 `element -> section -> material -> rho`가 정확히 하나로 결정되어야 한다.
Missing rho를 0이나 기본값으로 채우지 않는다. 서로 다른 material/section의 rho/t를
global 평균으로 바꾸지 않는다. 사용하지 않은 material의 Density가 존재하면 문법·양성 검증은
동일하며, rho 존재의 필수성은 활성 material에 적용한다. Material/section reference 오류는
밀도가 있는 다른 material로 fallback하지 않는다. 단위는 `mass/length^3`, 변환 없음.

Density의 새 입력 허용은 이 eigen procedure에 속한다. 기존 static parser의 Density 지원
범위를 넓히지 않고, density가 없는 기존 static input과 material 생성 경로를 보존한다.
Material의 내부 optional density를 만들더라도 static에 필수값을 요구하지 않는다.

## I4. Step와 Frequency의 exact options

`*STEP` 허용 parameter는 optional `NAME=<name>`, optional `NLGEOM=NO`, optional
value 없는 `PERTURBATION`뿐이며 data는 없다. NLGEOM 생략은 NO다. PERTURBATION이 없어도
FREQUENCY가 원형상 linear perturbation procedure를 결정하고 source flag 유무를 보존한다.
`NLGEOM=YES`, flag NLGEOM, `PERTURBATION=...`, `INC`, 다른 option은 eigen에서 거부한다.
Frequency 외 procedure, step description data, 두 번째 procedure/step, 선행 상태는 지원하지 않는다.

| FREQUENCY parameter | 허용·기본 의미 | Observable mapping |
| --- | --- | --- |
| `EIGENSOLVER` | 생략 또는 `LANCZOS` | Source default=LANCZOS; actual=`MKL FEAST`. Explicit/omitted provenance와 backend mapping warning 기록 |
| `SIM` | 생략, value 없는 flag, `YES` | Source effective=YES. FESA SIM architecture 기능을 만들지 않음. Explicit일 때 no-op warning |
| `ACOUSTIC COUPLING` | 생략 또는 `ON` | Acoustic/ASI/TIE/coupling 정의가 전혀 없는 structural-only 모델에서만 적용 대상 없음. Explicit일 때 no-op warning |
| `NORMALIZATION` | 생략 또는 `MASS` | Source SIM=YES의 mass default를 적용. FESA 실제 ML로 phi^T ML phi=1; 값 변경 warning 없음 |

`SIM=NO`, `NORMALIZATION=DISPLACEMENT`, `AMS/SUBSPACE/FEAST` source enum,
`ACOUSTIC COUPLING=OFF|PROJECTION`, `DAMPING PROJECTION`, `RESIDUAL MODES`,
`PROPERTY EVALUATION`, `NSET` 및 다른 parameter는 지원하지 않는다.
사용자 backend 요구를 Abaqus 문법의 새 `EIGENSOLVER=FEAST` 지원으로 바꾸지 않는다.

Data는 정확히 한 physical row, comma split 후 **1~7 fields**다. 첫 field N은 mandatory
positive decimal integer이며 2~7은 존재하면 모두 empty여야 한다. 생략된 trailing fields도
unspecified다. 원본 `10, , , , ,`는 여섯 fields로 유효하다. Fields 2/3은 frequency bounds,
4는 shift, 5/6은 Lanczos controls, 7은 acoustic range factor의 source slot이다.
공란은 숫자0이 아니다. 어느 slot의 nonempty `0`도 지원하지 않으며, eighth empty field도
arity 오류다. 추가 row는 residual-mode input으로 해석하지 않고 거부한다.
이 제한은 [공식 FREQUENCY syntax](https://docs.software.vt.edu/abaqusv2025/English/SIMACAEKEYRefMap/simakey-r-frequency.htm)의
선택된 부분집합이다. N은 마지막까지 input authority이고 TXT 행수/count scratch/returned m과 다르다.
`N>finite_dimension` 및 빈 finite problem은 equation 구성 뒤 명시적으로 실패한다.

## I5. Result-neutral allowlist와 warning

아래 keyword는 parameter 순서만 자유이며 duplicate/추가 parameter·data row는 거부한다.
동일 조합의 반복 output request는 각 keyword당 warning 한 개를 남기며 결과를 바꾸지 않는다.

| Keyword | 정확한 조합·위치 | Warning code |
| --- | --- | --- |
| `*PREPRINT` | Optional top-level; `ECHO=NO,MODEL=NO,HISTORY=NO,CONTACT=NO` 정확히 네 개, data 없음 | `ignored-input-keyword` |
| `*RESTART` | FREQUENCY/BC 뒤; flag WRITE와 FREQUENCY=0, data 없음 | `ignored-input-keyword` |
| `*OUTPUT` | FREQUENCY/BC 뒤; FIELD 또는 HISTORY flag 하나; optional VARIABLE=PRESELECT; data 없음 | `ignored-input-keyword` |
| `*NODE OUTPUT` | 활성 OUTPUT FIELD 아래; VARIABLE=PRESELECT 하나, data 없음 | `ignored-input-keyword` |
| `*ENERGY OUTPUT` | 활성 OUTPUT HISTORY 아래; VARIABLE=ALL 하나, data 없음 | `ignored-input-keyword` |

새 OUTPUT root는 앞의 output scope를 닫고, RESTART/END STEP도 닫는다. Child scope mismatch는
거부한다. Restart READ/nonzero write frequency, output variables data, element/contact output,
node history request 등 표 밖 조합은 eigen에서는 fail-closed다. 기존 static allowlist를 축소하지 않는다.
Warning message는 raw keyword와 `mandatory-eigen-output-unchanged` 이유를 포함한다.
RESTART frequency0은 write 중단 옵션이고 출력 요청들은 model equations를 바꾸지 않는
output selection이다. FESA는 이 selection을 구현하지 않는다는 차이를 알린다.

FREQUENCY에는 `source-eigensolver-mapped-to-feast` warning을 항상 하나 기록한다.
Explicit SIM에는 `source-sim-option-not-applied`, explicit acoustic ON에는
`acoustic-option-inapplicable-structural-only`를 기록한다.
위 세 code를 포함한 출력 순서는 기존 source tuple의 code 정렬을 따른다. Invalid model은
이 warning을 근거로 acoustic/coupling semantics를 버려서는 안 된다.

## I6. Fail-closed validation과 diagnostics

표 밖 model/history keyword는 eigen analysis 전에 거부한다. 특히 어떤 위치의
`CLOAD/DLOAD/DSLOAD`, initial condition/stress/temperature, damping, acoustic/ASI elements,
TIE/contact/MPC, transform/orientation/explicit director, surface/beam/solid/mixed model,
concentrated/nonstructural mass, composite/offset/variable thickness, amplitudes, restart read와
다중 step은 지원하지 않는다. Zero-valued load/damping 입력도 지원되는 무하중 모델로 바꾸지 않는다.

진단 record는 기존 `severity,code,file,line,keyword,entity_identity,message`를 사용한다.
file은 lexical normalized path, line은 source 1-based다. Material/section/node/element/step,
DOF 또는 invalid parameter/field ordinal을 가능한 한 entity/message에 포함한다.
Numerical scale·threshold·observed value는 binary64 round-trip 가능한 decimal로 보고한다.
Source location 없는 backend failure도 sole Frequency location과 step을 연결한다.
기존 SortDiagnostics 순서와 same-key discovery order를 유지한다.

| Condition | Stable code | CLI exit |
| --- | --- | --- |
| Lexical/arity/duplicate parameter/name/unresolved source | 기존 `invalid-input-character`, `input-line-too-long`, `invalid-data-arity`, `invalid-keyword-parameter`, `unresolved-reference` 등 해당 기존 code | 3 |
| Density scope/data/dependency/duplicate | `invalid-density-data` / `unsupported-density-option` / `duplicate-density` | 3 |
| Active rho missing / numeric nonfinite 또는 nonpositive | `missing-material-density` / `invalid-material-density` | 4 |
| New rho malformed numeric token | `invalid-density-data` | 3 |
| Frequency parameter/count/data mismatch | `unsupported-frequency-option` / `invalid-frequency-data` | 3 |
| Multiple/preload/unsupported procedure | `unsupported-analysis-procedure` | 3 |
| Nonzero base/prescribed BC | `unsupported-eigen-boundary` | 3 |
| Model-affecting exclusion / unsupported element | `unsupported-keyword` / `unsupported-element-formulation` / `unsupported-mixed-element-model` | 3 |
| Invalid geometry/section/material | 기존 model code; mass27-point invalid는 `invalid-shell-mass-geometry` | 4 |
| Global finite n=0 / N>n | `empty-eigenproblem` / `insufficient-finite-modes` | 4 |
| Analytic/null/positive mass or conditioning 실패 | `invalid-eigen-mass-space` / `eigen-mass-conditioning` | 5 |
| Index/storage/allocation/FEAST/count/budget/negative/validation 실패 | [M2 diagnostic mapping](io-mapping.md#m2-backend와-failure-lifecycle) | 5 |
| Candidate/write/close/self-check/replace/log/lock 실패 | 기존 output category와 [M2](io-mapping.md#m2-backend와-failure-lifecycle) | 6 |

`NaN/Inf` rho는 nonfinite model value(4)로 분류하고 그 외 malformed token은 syntax(3)다.
같은 실패를 여러 code로 중복 보고하지 않고 첫 발견 원인을 유지한다. Fatal 뒤 solve/commit을
실행하지 않는다. CLI usage2/success0과 stderr format은 기존 공통 계약을 유지한다.

## 공개 근거와 적용 한계

2026-09-06 공식 Abaqus 2025 문서를 `web.open`으로 확인했다. 사실은 syntax/외부 의미이고,
위 exact subset/default/warning policy는 승인된 FESA 요구에 대한 I/O mapping이다.

| Source | Locator와 사용 |
| --- | --- |
| [DENSITY](https://docs.software.vt.edu/abaqusv2025/English/SIMACAEKEYRefMap/simakey-r-density.htm) | Data lines 1~2와 optional dependencies; constant rho 및 ML^-3 차원. 온도·distribution 지원은 포함하지 않음 |
| [FREQUENCY](https://docs.software.vt.edu/abaqusv2025/English/SIMACAEKEYRefMap/simakey-r-frequency.htm) | Optional parameters와 Lanczos data line 1~7. Source defaults·bounds/shift 공란을 구분; FESA Lanczos 내부 동작의 근거가 아님 |
| [STEP](https://docs.software.vt.edu/abaqusv2025/English/SIMACAEKEYRefMap/simakey-r-step.htm) | NAME/NLGEOM/PERTURBATION. 선행 history 전달은 제외 |
| [RESTART](https://docs.software.vt.edu/abaqusv2025/English/SIMACAEKEYRefMap/simakey-r-restart.htm) | WRITE/FREQUENCY=0 및 no-data. Restart 지원을 주장하지 않음 |
| [OUTPUT](https://docs.software.vt.edu/abaqusv2025/English/SIMACAEKEYRefMap/simakey-r-output.htm) | Output selection root |
| [NODE OUTPUT](https://docs.software.vt.edu/abaqusv2025/English/SIMACAEKEYRefMap/simakey-r-nodeoutput.htm) | FIELD와 VARIABLE=PRESELECT |
| [ENERGY OUTPUT](https://docs.software.vt.edu/abaqusv2025/English/SIMACAEKEYRefMap/simakey-r-energyoutput.htm) | HISTORY와 VARIABLE=ALL; 새 modal energy output 요청으로 확대하지 않음 |
| [Input Syntax Rules](https://docs.software.vt.edu/abaqusv2025/English/SIMACAEMODRefMap/simamod-c-inputsyntax.htm) | Keyword/data/256-byte/continuation convention; FESA bounded 차이와 기존 정책은 I1이 권위 |

질량 정식화·private parser/model·solution algorithm·ODB internals의 동등성을 추론하지 않는다.