FESADev/docs/business-rules.md

# 물리와 판정 규칙

## 식별과 해석 범위

Source의 instance·label·step·point는 내부 배열 index나 equation 번호와 다르다.
다른 instance의 같은 label을 합치거나 결과 위치가 가깝다는 이유로 대응시키지 않는다.
입력 표기 `S4/S4R`은 내부 MITC4로 연결되며 Abaqus 적분법 선택을 뜻하지 않는다.
`LANCZOS` 표기를 수용해도 실제 고유치 계산은 MKL FEAST다.

현재 구조해석은 B33 beam, MITC4 shell, C3D8 solid의 승인된 procedure별 subset이다.
열해석은 DS4 shell의 단일 비연성 과도 열전달이다. 지원하지 않는 조합은 명시적으로
실패하며 가장 비슷한 요소·하중·물성으로 바꾸지 않는다. 현재 subset 밖이라는 사실은
향후 기능 추가를 영구적으로 금지하는 물리 법칙이 아니다.
사용자가 일관된 단위를 제공한다. 입력 숫자에서 SI 단위를 추정하거나 자동 변환하지 않는다.

## 평형과 상태 전이

선형 정적은 지정값 기여를 포함한 `Kff*df=Ff-Kfc*dc`를 풀고 전체 해를 복원한다.
반력은 같은 full residual `K*d-F`의 constrained 성분이다. Free residual은 평형 검증량이며
이를 반력으로 비교하지 않는다. 모든 DOF가 지정된 유효 모델의 빈 free system은 허용한다.
자유 방정식의 특이성을 penalty나 임의 대각 성분으로 없애지 않는다.

비선형·동해석에서 같은 trial의 geometry·힘·접선을 사용한다. 수렴·finite·복구·해당
procedure의 검증을 모두 통과한 candidate만 accepted state와 history를 갱신한다.
실패한 trial은 accepted frame이 아니며 일부 cache·chart·rate만 다음 증분에 남기지 않는다.
전체 해석 또는 결과 저장이 실패하면 기존 최종 HDF5를 보존한다.

## 요소·하중별 구분

- B33는 작은 변형·회전의 직선 Euler beam이다. Endpoint outward action과
  positive-local-x 단면력은 부호·위치가 다르며 공유 node에서 평균하지 않는다.
- MITC4의 physical 응답과 numerical drilling 안정화는 별도다. Drilling energy를
  physical stress로 복구하지 않고 artificial inertia로 질량 영공간을 없애지 않는다.
  Centered shell의 막력 계수는 두께에, 굽힘 계수는 두께 세제곱에 비례한다.
- Shell 정적 압력은 `SPOS=+1`, `SNEG=-1`일 때 oriented area vector `a`에 대해
  `-lambda*p*s*a`다. 양의 압력은 선택한 면의 외향 법선 반대 방향이다. 선형은 reference,
  비선형은 current geometry를 쓰고 Newton tangent는 `Kint-dFext/dq`다. 비대칭 항을 버리지 않는다.
  같은 side의 중복 facet은 경고 후 하나로 처리하고 양쪽 side 충돌은 실패한다.
  중복 DSLOAD 행은 각각 더한다.
- Hex8은 점별 deviatoric energy와 volume-weighted mean volumetric energy를 사용한다.
  이를 center 값·unweighted mean·Fbar로 대체하지 않는다. 질량은 BC 축소 전 reference
  consistent matrix의 row-sum이며 warped 요소의 node별 값을 `rho*V/8`로 통일하지 않는다.
- Shell 고유치의 finite 공간은 실제 BC를 적용한 뒤 analytic mass null과 free 공간의
  교집합을 제거하여 만든다. Partial rotational BC를 full clamp로 바꾸지 않는다.
  Interval 안의 전체 반환 고유쌍을 검증한 뒤 요청한 lowest N만 공개한다. N 밖의 실패를 버리지 않는다.
- 현재 shell HHT는 nodal-lumped-kinetic 질량과 reduced-coordinate 적분을 사용한다.
  Physical acceleration, 공개 auxiliary acceleration, private 적분 이력은 서로 다르다.
  공개 결과의 rate 조합만으로 private history나 restart를 재구성하지 않는다.
- Hex8 HHT의 high+low 상태는 다음 accepted state까지 보존한다. 저장되는 F64는 전체 값의
  반올림 관측값이며 이것을 내부 전체 상태와 같다고 가정하지 않는다.
- DS4는 node당 다섯 두께 온도점을 결합한다. Consistent capacity와 Backward Euler를
  사용하며 음수 온도를 clamp하지 않는다. Raw 초기 온도를 보존하고 지정온도는 첫 양의
  시점부터 적용한다. 반력은 열저장까지 포함한 full residual의 constrained projection이다.
  중앙면 양쪽 flux trace는 서로 다른 위치이며 평균하지 않는다.

## MITC4 drilling의 선택과 인공 모멘트

현재 모델 전체는 한 코드 설정으로 직접 초기 director 스프링 또는 기존 상대 비틀림을
선택한다. 기본값은 직접 스프링이며 선형·비선형 정적·정적 pressure·frequency·HHT에
같이 적용한다. Beam·Hex8·DS4에는 적용하지 않는다. Runtime·section별 선택은 현재 없다.

직접 방식에서 `d0`는 초기 global 단위 director, `phi`는 전체 global rotation vector다.
`gamma=d0·phi`, `Udrill=0.5*kd*sum(gamma²)`, `frot=kd*gamma*d0`,
`Krot=kd*d0*d0^T`다. 병진·절점 간 coupling·drilling force의2차 방향미분은 exact zero다.
Kd는 BC 전 초기 physical rotary 대각8개의 overflow 방지 평균에 `1e-3`을 곱해 고정한다.
Zero 대각도 평균에 포함하며 음수/nonfinite·전부 zero·nonpositive kd는 실패다.
Floor·density 치환·trial 재조정은 없다. 유한 강체 회전의 인공 에너지·모멘트는 허용한다.

직접 HHT hidden 식은 실제 관성의 normalized null `n(phi)`에 대해
`sum_e kd*gamma_ei*(n·d_ei0)-n·Fext_rot`이며 같은 trial의 고차 미분을 사용한다.
공유 node의 외력 항은 한 번만 뺀다. 일정 drilling 접선이 null의 고차 미분을 없애지는 않는다.
기존 방식의 계산은 polar1·관성3차 근사와 기존 판정을 보존하며 정확도 실패를 자동 수정하지 않는다.

내부 spatial `Mdrill=sum[x cross fdrill_trans+Jl(phi)^(-T)*fdrill_rot]`를 source 순서로
누적한다. 선형은 reference 위치/작은 회전, 비선형/HHT는 현재 위치/기존 SO(3) 변환이다.
기존 raw 평형은 그대로이고 보정 평형은 `[raw_force,raw_moment-Mdrill]`다.
직접 방식의 기존 전역 gate만 보정값을 사용하고 기존 방식은 raw를 사용한다.
기존 scale·exact-zero·허용치는 유지하며 인공 모멘트를 분모에 더하지 않는다.
비선형 정적의 전역 수치 gate는 기존 reference 비교기에 있으며 procedure에 새 gate를 만들지 않는다.
Marker 없는 옛 결과의 방식은 미상이다. 선형/HHT 변위 비교기에는 새 평형 수치 family를 만들지 않는다.

## 외부 수치 비교

먼저 source identity·row 집합·component·schema·단위·좌표·위치와 finite 여부를 검사한다.
Missing·extra·duplicate·NaN·Inf는 허용치 계산 전 실패다. Warning-only 비교에도 이 검사는 필수다.

Family는 같은 case·step/frame·논리 물리량·단위 차원·좌표계·판정 영향으로 묶는다.
Reference만으로 `S=max(abs(r_i))`, `B=0.01*S`를 구한다.
`abs(r_i)<=B`인 행은 `abs(f_i-r_i)<=B`, 나머지는 상대오차 `<=0.05`를 요구한다.
모든 행 조건과 `sqrt(mean((f-r)^2))/S<=0.01`을 함께 만족해야 한다.
`S=0`이면 FESA 값도 모두 exact zero여야 한다. 별도 absolute floor나 `max(1,S)`는 없다.

MITC4 정적·비선형·shell HHT의 U는 blocking, UR의 수치 차이는 warning-only다.
Review-only RF/RM이나 외부 비교 대상이 아닌 stress를 통과로 집계하지 않는다.
Hex8 정적 U·constrained RF·점별 S는 각각 blocking이며 free RF를 residual과 비교하지 않는다.

2026-09-10 승인된 `mitc4-eigen-first-implementation`만 source modal frame별 singleton
Value의 행 상대오차와 RMS를 각각 5%로 검사한다. Near-zero·zero-scale·사전검사와 내부
고유쌍 residual·정규화·직교성 `1e-10`은 유지한다. 이 예외를 Hex8 고유치에 확대하지 않는다.
기존 thermal NT11 비교는 불일치를 보존하는 diagnostic/nonblocking이며 외부 수치 PASS가 아니다.

내부 평형 허용치를 하나로 통합하지 않는다. 선형 정적 normalized free residual과
force/moment balance는 `1e-10`이다. 비선형 shell 정적 accepted free residual은 matching
external scale이 nonzero면 상대 `1e-2`, exact-zero면 force 또는 force-length 차원의
absolute `1e-3`이고 factor-one 전역 force/moment balance는 각각 normalized `1e-8`이다.
HHT의 잔차·시간수렴, thermal 잔차 인증은 해당 물리량과 산술 의미를 보존하여 별도로 판정한다.