FESADev/docs/mitc4-shell-feast-eigen/requirements-evidence.md

# MITC4 eigen 요구사항의 관찰 evidence와 결정

- Feature ID: `mitc4-shell-feast-eigen`
- Owner: `requirement-agent`
- Input contract revision: `r1`
- 기본 보고서: [requirements.md](requirements.md)
- 관찰일: `2026-09-06`

## 원본 reference 관찰

| Artifact | 실제 경로 | SHA-256 |
| --- | --- | --- |
| Input | [shellNL-eigen-meshfine.inp](../../reference/shellNL-eigen-meshfine/shellNL-eigen-meshfine.inp) | `913b1abc604e62bc5f995bf5523924e17ea03925102a7bd22d39226ba0ea7339` |
| Eigenvalues | [shellNL-eigen-meshfine eigenvalues.txt](../../reference/shellNL-eigen-meshfine/shellNL-eigen-meshfine%20eigenvalues.txt) | `20d97ca3fd51f5b956f2c1ed7565557c68f74e61e41b913748515ef43a0f7f0b` |

| 관찰 항목 | 파일에서 읽은 사실 |
| --- | --- |
| 모델 | `Part-1`, identity instance `Part-1-1`; 729 nodes, 676 `S4` elements |
| 좌표 | x/y 각각 `[-5,5]`, 모든 z=`0`; 26×26 element mesh의 사각 평판 |
| Section | line 1421 `*Shell Section, elset=Set-1, material=Material-1`; data `0.5, 5`; offset/composite 없음 |
| Material | lines 1455~1459: `Material-1`, `*Density`=`2700.`, `*Elastic`=`2.1e+11, 0.3` |
| Constraint | lines 1464~1470: `Set-2`의 DOF 1~6, 값 생략으로 homogeneous constraint |
| Procedure | lines 1475~1477: 유일한 `*Step, name=Step-2, nlgeom=NO, perturbation`; `*Frequency, eigensolver=Lanczos, sim, acoustic coupling=on, normalization=mass`; `10, , , , ,` |
| 선행 이력 | 이전 Step/Static/Initial Conditions/load 없음; 이름 `shellNL`이나 `Step-2`로 preload를 추론하지 않음 |
| 부수 요청 | `*Restart, write, frequency=0`, field/Node PRESELECT, history/Energy ALL. 모델은 acoustic element/coupling constraint를 포함하지 않음 |
| TXT | 10개 row; 각 row에 `Frame: Mode <id>: Value = <lambda> Freq = <f> (cycles/time)` |
| Identity | mode IDs는 정확히 1~10, 유일하며 누락 없음; 모든 Value/Freq finite·positive |
| 반복값 | modes `(2,3)`, `(7,8)`, `(9,10)`의 표시 Value가 각각 같음; mode identity 중복과 구분 필요 |

관찰 Value 목록은 다음과 같다. 원본 표시 정밀도를 확장·보정하지 않는다.

| Mode | Value |
| --- | ---: |
| 1 | 2.19507E+05 |
| 2 | 8.85523E+05 |
| 3 | 8.85523E+05 |
| 4 | 1.85534E+06 |
| 5 | 2.74023E+06 |
| 6 | 2.77515E+06 |
| 7 | 4.14941E+06 |
| 8 | 4.14941E+06 |
| 9 | 6.73379E+06 |
| 10 | 6.73379E+06 |

관찰값으로 `sqrt(Value)/(2*pi)`와 표시 `Freq`를 계산상 대조한 최대 상대차는
`1.6946487122851045e-05`이다. 이것은 quantity 식별을 돕는 교차 확인이며 FESA comparison이나
새 허용오차 판정이 아니다. `Value`는 `omega²`, `Freq`는 cycles/time이라는 공개 정의와
일관된다. 단위계는 원문에 지정되지 않았고 수치만 보고 SI라고 단정하지 않는다.

TXT에는 step 이름이 별도로 없지만 입력은 정확히 한 개 frequency step이며 mode identity와
Value가 완전하다. 따라서 지정 input의 유일한 `Step-2`에 결합하는 deterministic projection은
가능하다. 최종 readiness와 frame/family mapping은 NR·I/O가 소유한다. CSV가 없다는 이유로
reference를 변환하거나 새 metadata/provenance를 요구할 근거는 없다. 사용자 지정 경로를
우선하는 feature-specific artifact 선택이며 공통 reference 문서나 다른 feature 계약은 바꾸지 않는다.

## 중요한 결정

### MFE-OQ-001 — 두 질량 계산 관계: 해결

사용자는 `2026-09-06` 후속 답변에서 “mass matrix는 consistent mass를 계산하고 이를
이용해서 lumped mass를 계산합니다.”라고 명시했다. Consistent 원본 계산과 derived lumped
계산이 모두 필수이며 이전 둘 중 하나의 계산만 선택하는 초안은 대체되었다.
관련 결정은 [MFE-ADR-002](ADR.md#mfe-adr-002--mitc4-질량-이산화), 요구사항은
`FEM-REQ-MITC4-EIGEN-005`, `026`이다. Lumping 알고리즘은 사용자 지정이 없으므로
Research/Formulation이 질량 보존·물리 회전 관성·좌표 변환·drilling 경계를 명시하고 NR가 검토한다.
모든 속도장의 kinetic energy나 두 spectrum의 exact equality를 보존 조건으로 추가하지 않는다.

### MFE-OQ-002 — FEAST와 reference baseline의 질량: 해결

- 상태: **사용자 명시 결정으로 해결**.
- 관련 요구사항: `FEM-REQ-MITC4-EIGEN-008`, `011`, `013`, `017`, `020`.
- Owner: user가 사용 질량을 결정; Research/Formulation이 근거와 수식,
  NR가 검증; Requirement Agent가 본 r1 baseline에 반영.

사용자는 추가 답변에서 “고유치 해석에서는 lumped mass를 사용합니다. 따라서 고유치 해석을
할 때 consistent mass -> lumped mass -> 고유치 해석 입니다”라고 명시했다.
따라서 FEAST와 authoritative reference baseline은 derived lumped mass를 사용하며
동일 lumped mass로 residual·mass normalization·orthogonality를 검증한다.
Consistent는 유도 원본과 내부 mass/energy 검증에 유지한다. Consistent eigen 해석,
두 variant의 외부 비교 및 runtime 질량 선택 API는 현재 요구가 아니다.
이 결정은 수치 tolerance 통과나 정확도 우위의 evidence를 대신하지 않는다.

Drilling은 기존 승인 shell 계약에서 비물리 안정화 좌표이다. 인공 drilling inertia를
추가하거나 두 물리 회전 관성을 생략하는 대안을 새 사용자 옵션으로 발명하지 않는다.
Massless drilling을 그대로 generalized FEAST에 넣을 수 있다는 가정도 하지 않는다.
FEAST의 SPD 조건과 shell 질량 nullspace의 양립은 Research/Formulation이 물리 spectrum과
constraints를 보존하는 방식으로 해결해야 한다. 이 문서는 elimination/projection/condensation
식을 승인하지 않으며, 새로운 물리 근사가 필수라는 evidence가 생기면 해당 owner가 반환한다.

## 질문 없이 정리한 사항

- 무하중 원형상·비감쇠 해석은 실제 단일 `*FREQUENCY`와 선행 이력 부재로 결정한다.
- `.inp`의 Lanczos는 source solver 옵션이다. 사용자가 FESA backend를 FEAST로 명시했으므로
  source option을 유지해 읽되 실제 backend를 명시하는 mapping이 가능하다. Abaqus Lanczos
  동작과의 동등성을 주장하지 않는다. Exact allowlist와 진단은 I/O 소유이다.
- `SIM`은 source architecture 옵션이고 acoustic-free 모델의 `ACOUSTIC COUPLING=ON`은
  실제 acoustic 모델 지원 요청이 아니다. 무해한 조합만 근거와 warning 정책으로 허용한다.
- `NORMALIZATION=MASS`의 내부 modal 의미를 유지한다. 외부 mode shape 비교는 추가하지 않는다.
- TXT의 명시적인 `Value`를 직접 읽고 원본을 보존한다. Matching/family는 tolerance 전에
  고정하며 repeated eigenvalue와 duplicate mode ID를 구분한다.
- 기존 HDF5 의미를 보존하는 eigen quantity 추가는 신규 기능에 필요한 I/O 정의이다.
  비호환 변경이 없는 한 schema 검토를 별도 사용자 승인 질문으로 만들지 않는다.

## 공개 근거

다음은 `2026-09-06`에 확인한 1차 문서이다. 공식 syntax와 backend admissibility 확인에만
사용하며 Abaqus 내부 정식화의 추정 근거로 쓰지 않는다.

1. [Abaqus 2025 — Natural Frequency Extraction](https://docs.software.vt.edu/abaqusv2025/English/SIMACAEANLRefMap/simaanl-c-freqextraction.htm):
   `Eigenvalue Extraction`, `Initial Conditions`, `Loads`, `Output` 절. 무감쇠 eigenproblem의
   `omega²`, 원형상/선행 기하비선형 상태의 구분, 각 모드 출력 의미 확인.
2. [Abaqus 2025 — *FREQUENCY](https://docs.software.vt.edu/abaqusv2025/English/SIMACAEKEYRefMap/simakey-r-frequency.htm):
   `Optional parameters`와 Lanczos data line 절. 요청수 10, blank bounds, source algorithm,
   SIM/acoustic 옵션의 의미와 mass normalization 확인.
3. [Intel oneMKL 2026.0 — Extended Eigensolver Functionality](https://www.intel.com/content/www/us/en/docs/onemkl/developer-reference-c/2026-0/extended-eigensolver-functionality.html):
   real symmetric generalized 문제는 `B` SPD를 요구한다. 이 조건 때문에 massless drilling을
   아무 처리 없이 FEAST에 전달해서는 안 된다.
4. [Intel oneMKL 2026.0 — ?feast_scsrgv](https://www.intel.com/content/www/us/en/docs/onemkl/developer-reference-c/2026-0/feast-scsrgv-feast-hcsrgv.html):
   지정 구간의 eigenpairs, subspace capacity, 결과 count와 status 의미 확인. 구간 선택·확장과
   설치된 MKL 버전 검증은 후속 owner가 정의한다.

## 실행 evidence와 미실행

r0 원본 관찰과 hash는 그대로 유지했다. 아래는 당시 실행한 read-only 조사이며 이번 r1에서
reference 재조사나 변환을 수행하지 않았다. 해당 shell 명령은 exit code `0`이었다.

```powershell
Get-Content -Raw '.codex/skills/fem-requirements-baseline/SKILL.md'
Get-Content -Raw 'docs/SOLVER_AGENT_DESIGN.md'
Get-Content -Raw 'docs/FEATURE_DOCUMENTATION.md'
rg -n -i '^\*(?!\*)|density|frequency|static|step|boundary|shell section' --pcre2 'reference/shellNL-eigen-meshfine/shellNL-eigen-meshfine.inp'
Get-Content -Tail 75 'reference/shellNL-eigen-meshfine/shellNL-eigen-meshfine.inp'
Get-Content -Raw 'reference/shellNL-eigen-meshfine/shellNL-eigen-meshfine eigenvalues.txt'
rg -n 'FEAST|feast|MassMatrix|Density|density|Frequency|Eigenvalue|eigenvalue' include src -g '*.[ch]*'
git status --short
```

추가 read-only `python -B -` here-script는 `pathlib`로 두 파일을 읽고 keyword별 node/element
count, 좌표 범위, regex `Mode\s+(\d+):\s+Value\s*=\s*(\S+)\s+Freq\s*=\s*(\S+)`로
mode/Value/Freq를 추출하여 finite·identity·주파수 교차 확인과 SHA-256을 계산했다.
Exit code `0`, 729 nodes / 676 elements / 10 modes였고 위 표·hash와 일치했다.
파일을 생성하거나 reference 내용을 쓰지 않았다. Source 검색에서 물리 mass/density/eigen
구현을 발견하지 못했고 nonlinear local energy 변수 `density`만 검색되었다. 이는 scoped 검색
관찰이며 제품 미지원의 최종 코드 감사는 아니다.

공통/feature/기존 MITC4·nonlinear 승인 계약을 read-only로 조사했다. 기존 보고서의 완료
표시는 이번 feature 실행 증거로 재사용하지 않는다. C++ build/test, Harness, 외부 solver와
FESA reference comparison은 요구사항 단계의 범위가 아니므로 미실행이다.

r1에서는 관리문서·owned reports·공통 agent 계약을 `Get-Content`로 읽고 사용자 수정
`AGENTS.md`의 GoogleTest 경로를 `rg -n 'GTEST|git|GoogleTest' 'AGENTS.md'`로 확인했다.
명령은 exit code `0`이었다. 실제 GoogleTest dependency 설정/build 확인은 Root·Planning
소유이며 이 문서 갱신에서 새로 실행하지 않았다. 두 사용자 결정으로 `MFE-OQ-001`과
`MFE-OQ-002`를 해결했으며 기존 25개 requirement ID를 보존하고 derived lumped 요구
`026`을 추가했다. 중요한 미결정은 없고 상세 lumping 수식·수치 기준은 후속 owner 소유이다.

변경한 경로는 기본 보고서와 이 상세 보고서 두 개뿐이며 관리문서, source, tests, phase,
공통 정책과 reference artifact는 편집하지 않았다. 정적 링크·필수 metadata·ID/matrix 검사를
완료한 명령과 결과는 Requirement Agent 반환 evidence로 함께 보고한다.