# MITC4 eigen 입력·진단 계약

- Feature ID: `mitc4-shell-feast-eigen2`
- Owner: `io-definition-agent`
- Contract revision: `r1`
- 기본 보고서: [io.md](io.md)

## 문법과 기존 지원 범위

기존 [shell 입력](../linear-static-mitc4-shell/io.md#1-abaqus-input-scope)과
[후속 lexical 계약](../shell-surface-pressure-load/io.md)을 유지한다. 현재
[input_reader.cpp](../../src/fesa/io/abaqus/input_reader.cpp)와
[domain_mapping_context.cpp](../../src/fesa/io/abaqus/domain_mapping_context.cpp)를 대조했다.
LF/CRLF, 종결자 제외 physical line 256 ASCII bytes, printable ASCII/tab, blank와 `**`
comment, keyword parameter continuation은 기존 규칙을 따른다. Inline comment, data
continuation, include/substitution/quoted name을 추가하지 않는다. Keyword·parameter·enum·
name lookup은 ASCII case-insensitive이며 raw spelling/physical source line은 보존한다.
Duplicate parameter는 같은 값이어도 실패한다. Comma split은 빈 field를 보존한다.

Eigen model의 순서는 `HEADING? PREPRINT? PART+ ASSEMBLY MATERIAL+ BOUNDARY* STEP EOF`다.
Part 내부 NODE→ELEMENT→sets→SHELL SECTION, assembly의 identity INSTANCE와 explicit-instance
sets, forward section→material lookup은 기존 shell 범위다. `S4`와 `S4R`는 source type만
구별하고 같은 FESA MITC4 kernel에 대응한다. Node/element positive int64 source label,
instance/name scope, element 네 distinct nodes, section 유일 할당, geometry-derived director,
centered finite thickness>0, homogeneous isotropic `E>0,-1<nu<0.5` 검증은 기존 계약 그대로다.
`*SHELL SECTION`의 optional positive integration-point integer는 기존 명시 예외로
warning 없이 읽고 물리 integration을 바꾸지 않는다. 새 mass integration은 formulation 권위다.

Model/history의 허용 keyword는 기존 topology/material의 `HEADING,PART,END PART,NODE,
ELEMENT,NSET,ELSET,SHELL SECTION,ASSEMBLY,END ASSEMBLY,INSTANCE,END INSTANCE,MATERIAL,
ELASTIC,BOUNDARY`와 아래 DENSITY/STEP/FREQUENCY/no-op 목록뿐이다. Assembly ELSET의 기존
`INTERNAL` flag도 보존한다. 기존 static의 load·output 범위를 이 eigen allowlist로 축소하지 않는다.

## Density

`*DENSITY`는 current MATERIAL 안에서 parameter 없이 최대 한 번, 정확히 한 data row를
갖는다. `rho` 또는 `rho,`만 허용한다. 뒤의 빈 temperature slot은 constant 값이며 원본
`2700.,`를 그대로 수용한다. Nonempty temperature, 추가 field/comma/row, `DEPENDENCIES=0`을
포함한 모든 parameter와 distribution은 거부한다. ELASTIC과 DENSITY의 상대 순서는 자유다.

새 rho의 C-locale token은 아래 full-match이고 binary64 full conversion을 요구한다.

```text
number := [+-]?(?:[0-9]+(?:\.[0-9]*)?|\.[0-9]+)(?:[Ee][+-]?[0-9]+)?
```

Hex/D exponent/locale comma/잘못된 token은 input 오류다. NaN/Inf spelling은 아래 model
nonfinite 진단으로 분류하며 허용 token이 아니다. Overflow/underflow conversion error,
nonfinite, `rho<=0`는 invalid material이다. 모든 활성 `element→section→material→rho`가
정확히 하나로 결정되어야 한다. 누락값·다른 material·global 평균으로 대체하지 않는다.
사용하지 않은 material에 선언된 density도 문법·양성 검증한다. 필수 존재 조건은 활성 material에
적용한다. 단위는 `mass/length^3`, 사용자 일관 단위계이며 자동 SI 추론·변환은 없다.

Density 허용은 새 eigen procedure에 한정한다. 기존 static 입력 지원을 확장하거나 density를
필수화하지 않는다. Procedure 확인 전 raw material을 보존한 뒤 해당 procedure로 검증한다.

## Step와 Frequency

`*STEP`은 정확히 하나이며 optional `NAME`, `NLGEOM=NO`, value 없는 `PERTURBATION`만
허용한다. Data는 없다. 생략 NLGEOM은 NO, 생략 NAME은 source `Step-1`이다. FREQUENCY가
원형상 무응력 linear perturbation procedure를 결정하므로 PERTURBATION 생략도 같은 의미다.
Raw/canonical name과 flag presence를 보존한다. Storage `Step-1`과 source `Step-2`는 별개다.
`NLGEOM=YES`, INC, 선행/다중 step, 다른 procedure와 step description은 거부한다.

| FREQUENCY parameter | 허용/생략 default | FESA 의미 |
| --- | --- | --- |
| `EIGENSOLVER` | `LANCZOS` / LANCZOS | 실제 MKL FEAST 사용; 항상 `source-eigensolver-mapped-to-feast` warning |
| `SIM` | flag 또는 `YES` / YES | Source option만 보존; 명시되면 `source-sim-option-not-applied` warning |
| `ACOUSTIC COUPLING` | `ON` / ON | Structural-only 모델에서 적용 대상 없음; 명시되면 `acoustic-option-inapplicable-structural-only` warning |
| `NORMALIZATION` | `MASS` / MASS | 실제 derived lumped mass로 normalization |

SIM=NO, DISPLACEMENT normalization, AMS/SUBSPACE/FEAST enum, coupling OFF/PROJECTION,
RESIDUAL MODES, DAMPING PROJECTION, PROPERTY EVALUATION, NSET와 모든 미열거 parameter는
실패한다. Acoustic 요소/ASI/TIE/coupling 정의가 존재하면 ON no-op을 적용하지 않고 실패한다.

FREQUENCY data는 한 physical row, 1~7 comma fields다. 첫 field N은 `[0-9]+`, checked
positive int64이며 나머지 존재하는 fields는 전부 empty여야 한다. Fields 2~7은 source의
minimum/maximum frequency, shift, block size, Lanczos step count, acoustic range factor 자리다.
빈칸은 unspecified이며 숫자0이 아니다. Nonempty0도 실패하고 eighth empty field도 실패한다.
원본 `10, , , , ,`는 6 fields, N=10이다. Bounds/shift/FEAST controls는 사용자 입력 기능으로
추가하지 않는다. `N>finite_dimension`과 빈 finite system은 equation 구성 뒤 model 실패다.

공개 Abaqus convention의 근거는 [FREQUENCY](https://docs.software.vt.edu/abaqusv2025/English/SIMACAEKEYRefMap/simakey-r-frequency.htm),
[DENSITY](https://docs.software.vt.edu/abaqusv2025/English/SIMACAEKEYRefMap/simakey-r-density.htm),
[STEP](https://docs.software.vt.edu/abaqusv2025/English/SIMACAEKEYRefMap/simakey-r-step.htm)이다.
2026-09-08 직접 확인했다. 위 allowlist와 warning은 FESA의 지원 차이이며 Abaqus algorithm·
SIM·parser 내부 구현의 동등성을 주장하지 않는다.

## Homogeneous BC와 result-neutral allowlist

BOUNDARY는 model 또는 FREQUENCY 뒤/output 앞에 parameter 없이
`target,first,last[,value]`로 둔다. `1<=first<=last<=6`; value 생략은 exact0, 명시 value는
finite exact0만 허용한다. 빈 fourth field는 생략으로 보지 않는다. 기존 bare source label 또는
unambiguous node-set resolver와 assembly INSTANCE binding을 사용한다. 새로운 dotted target,
local/tangent BC, MPC를 추가하지 않는다. Model BC→step BC 순서의 zero constraint union이며
같은 zero 재선언은 같은 constraint다. Nonzero를 상쇄·override해서 통과시키지 않는다.
Global DOF는 `UX,UY,UZ,URX,URY,URZ`; partial rotation BC를 그대로 유지한다.

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

Parameter 순서는 자유이며 duplicate/extra parameter는 실패한다. OUTPUT root/RESTART/END STEP은
이전 output scope를 닫는다. 모든 허용 no-op keyword마다 `ignored-input-keyword` warning과
`mandatory-eigen-output-unchanged` 이유를 기록한다. 선택·억제·restart state를 생성하지 않는다.
Unknown output variable row/child, restart READ/nonzero frequency는 실패한다.

어떤 위치의 CLOAD/DLOAD/DSLOAD(값0 포함), initial state/stress/temperature, damping,
amplitude, acoustic/beam/solid/mixed model, concentrated/nonstructural mass, composite/offset/
variable thickness, contact/MPC/TIE, transform/orientation/explicit director, surface 등 의미 있는
미지원 입력은 fail-closed다. 이름 `shellNL` 또는 `Step-2`에서 preload를 추정하지 않는다.

## 진단

기존 record `severity,code,file,line,keyword,entity_identity,message`와 CLI category를 유지한다.
File은 absolute lexical normalized path, line은 1-based; entity에 source instance/material/
element/node/step와 DOF 또는 field ordinal을 연결한다. Backend 오류도 Frequency 위치를 붙인다.
Warnings는 기존 SortDiagnostics와 same-key discovery order다. Fatal은 첫 원인을 유지하고
후속 solve/commit을 중단한다. 수치값은 round-trip decimal로 보고하며 임의 tolerance를 붙이지 않는다.

| 실패 | Code | Exit |
| --- | --- | --- |
| Lexical/arity/duplicate parameter/unresolved | 해당 기존 code: invalid-input-character, input-line-too-long, invalid-data-arity, duplicate-entity, unresolved-reference 등 | 3 |
| Density scope/malformed data/options/duplicate | invalid-density-data / unsupported-density-option / duplicate-density | 3 |
| Active rho missing / nonfinite·nonpositive·conversion range | missing-material-density / invalid-material-density | 4 |
| Frequency options/count/data | unsupported-frequency-option / invalid-frequency-data | 3 |
| Multiple/preload/other procedure | unsupported-analysis-procedure | 3 |
| Nonzero prescribed BC | unsupported-eigen-boundary | 3 |
| Other unsupported model semantics | unsupported-keyword / unsupported-element-formulation / unsupported-mixed-element-model | 3 |
| Existing geometry/material/section invalid | 기존 model code; 새 mass point 오류 invalid-shell-mass-geometry | 4 |
| Empty finite system / N>n | empty-eigenproblem / insufficient-finite-modes | 4 |
| Mass-space/conditioning/backend/numerical failure | [mapping의 solver diagnostics](io-mapping.md#실패와-공개-lifecycle) | 5 |
| Log/candidate/self-check/finalization | 기존 output category | 6 |

Usage2/success0와 stderr escaping은 기존 공통 CLI 계약이다. 지원되는 입력의 conditioning
실패를 input subset 축소나 인공 mass/zero clamp로 우회하지 않는다.