FESADev/docs/nonlinear-static-newton-raphson/reference-model.md

# Nonlinear Static Newton-Raphson Reference Model

## 1. Metadata

- feature_id: `nonlinear-static-newton-raphson`
- source_requirements: `docs/nonlinear-static-newton-raphson/requirements.md`
- source_requirements_sha256: `89C1AB5F1BEDB7C5F6AD0726ED62F0982181EA8746EDE4661183FD3D18A2408E`
- source_research: `docs/nonlinear-static-newton-raphson/research.md`
- source_formulation: `docs/nonlinear-static-newton-raphson/formulation.md`
- source_numerical_review: `docs/nonlinear-static-newton-raphson/numerical-review.md`
- decision_source: `USER-DECISION-004 option 1`
- balance_gate_decision: user-approved factor-one global force/moment normalized gate `<=1e-8`
- status: `pass-for-io-definition`
- owner_agent: `numerical-review-agent`
- date: `2026-08-28`
- artifact_policy: `read-only-existing-files`
- external_tolerance_policy: `docs/TOLERANCE.md`

이 문서는 logical quantity, source identity, component matching, row precheck와
blocking/warning-only/review-only 분류를 정의한다. 최종 HDF5 dataset projection은 I/O
Definition Agent 소유이며 이 문서에는 dataset path를 정의하지 않는다.

## 2. Reference Acceptance Scope

세 stored case를 사용한다.

- `shellnl-meshfine-s4-final`: 사용자가 추가하고 검증을 요청한 729-node/676-element
  mesh-refined nonlinear primary case. External `U1/U2/U3`와 factor-one internal equilibrium은
  blocking이다.
- `shellnl-s4-final`: 49-node/36-element coarse nonlinear companion regression. Fine case와
  별도 reference에 대해 external `U1/U2/U3`와 factor-one internal equilibrium을 blocking으로
  검증한다.
- `shell-s4-linear-limit`: 같은 coarse topology의 `NLGEOM=NO` linear-limit/source-identity
  regression. Nonlinear response evidence로 부르지 않는다.

모든 selected case에서 displacement `U1/U2/U3`는 blocking, `UR1/UR2/UR3`는
warning-only다. Coarse/fine local nodal `RF1/RF2/RF3`와 physical spatial `RM1/RM2`는
common external policy로 exact error/precheck evidence를 만들되 review-only이고 전체 blocking
verdict를 바꾸지 않는다. Local `RM3`와 stress는 numerical comparison에서 제외한다.

Coarse와 fine은 각자의 input/CSV에 독립적으로 비교한다. 두 mesh 사이 node interpolation,
row pairing, averaging, collapse, observed convergence order 또는 direct coarse/fine equality
gate를 만들지 않는다. Fine case 추가는 Abaqus S4와 FESA MITC4의 element formulation,
integration, stabilization 또는 internal behavior equivalence를 의미하지 않는다.

## 3. Reference Case Inventory

### 3.1 Exact input and CSV paths

| case id | purpose | exact path | required disposition | observed status |
| --- | --- | --- | --- | --- |
| `shell-s4-linear-limit` | linear input | `reference/shell/shell.inp` | required | readable; S4, 49 nodes, 36 elements, `NLGEOM=NO` |
| `shell-s4-linear-limit` | displacement reference | `reference/shell/shell displacements.csv` | required blocking/warning | 49 unique finite rows; single final static state |
| `shell-s4-linear-limit` | reaction inventory | `reference/shell/shell reactions.csv` | inspection-only | 49 unique finite rows |
| `shell-s4-linear-limit` | stress ordering inventory | `reference/shell/shell stresses.csv` | optional inspection | 288 rows; element labels `1..36` in contiguous ascending blocks |
| `shellnl-s4-final` | coarse nonlinear input | `reference/shellNL/shellNL.inp` | required | readable; S4, 49 nodes, 36 elements, `NLGEOM=YES` |
| `shellnl-s4-final` | displacement reference | `reference/shellNL/shellNL displacements.csv` | required blocking/warning | 49 unique finite rows; exact factor-one Frame |
| `shellnl-s4-final` | local reaction reference | `reference/shellNL/shellNL reactions.csv` | required review-only | 49 unique finite inventory rows; exact factor-one Frame |
| `shellnl-s4-final` | stress inventory | `reference/shellNL/shellNL stresses.csv` | optional inspection | 288 rows; element labels `1..36` in contiguous ascending blocks |
| `shellnl-meshfine-s4-final` | fine nonlinear input | `reference/shellNL-meshfine/shellNL-meshfine.inp` | required | readable; S4, 729 nodes, 676 elements, `NLGEOM=YES` |
| `shellnl-meshfine-s4-final` | displacement reference | `reference/shellNL-meshfine/shellNL-meshfine displacements.csv` | required blocking/warning | 729 unique finite rows; exact factor-one Frame |
| `shellnl-meshfine-s4-final` | local reaction reference | `reference/shellNL-meshfine/shellNL-meshfine reactions.csv` | required review-only | 729 unique finite inventory rows; exact factor-one Frame |
| `shellnl-meshfine-s4-final` | stress inventory | `reference/shellNL-meshfine/shellNL-meshfine stresses.csv` | optional inspection | 5,408 rows in ascending element blocks; one malformed optional node label `ss` |

`reference/shell/shell stresses.csv`는 사용자 변경 후 element label `1..36` 순서로 저장되어
있음을 확인했다. Row order는 matching identity가 아니며 deterministic inspection display에만
사용한다. Fine stress의 `Element Label=1`, `SNEG`, `Node Label=ss` 한 행은 optional excluded
artifact issue다. 이 파일을 rename, repair, normalize 또는 rewrite하지 않는다.

Coarse와 fine nonlinear input은 homogeneous isotropic material `E=2.1e11`, `nu=0.3`,
shell thickness `0.5`, center node-set load `DOF 3 = -100000`, all-six-DOF perimeter support,
`*STATIC 0.1,1.,0.001,0.1`을 사용한다. Fine case는 같은 physical setup의 refined topology다.

### 3.2 Read-only artifact hashes

| exact path | SHA-256 |
| --- | --- |
| `reference/shell/shell.inp` | `4005851E1AB22FD3A16AC17A8D5DA3E051233F69F37419079F3553AD134ECFCF` |
| `reference/shell/shell displacements.csv` | `C81D94E0B4A849F87AA0F79C83A79B94D5661AC79E44ED826919AB432C87746B` |
| `reference/shell/shell reactions.csv` | `0E34EEC27E700C3C0C744C1DAFD8A3B95EFEF34B8616FE96665876586FE82D41` |
| `reference/shell/shell stresses.csv` | `2B75A5B0DEB045A283C9BB7E9B1153B79F7537FF487214BF4A23316B59B660A7` |
| `reference/shellNL/shellNL.inp` | `4BF3ECB0F7F1E8462C573E993DBC97AC5D920C91CF6F23AD4C6891D77FFBADA2` |
| `reference/shellNL/shellNL displacements.csv` | `4E0F99CA9372B1ADF7FAF102F43BC0B887DC743FDEDA378E4342D2CF8E0C0786` |
| `reference/shellNL/shellNL reactions.csv` | `001CB1541A9E94424E5E650509D46BC8724970DF4DE47184D9DB09C7938AB069` |
| `reference/shellNL/shellNL stresses.csv` | `5500E5114B1C44887528E30CEC054A1EB0F68BE3F4B8CE81FA59FC74A881483F` |
| `reference/shellNL-meshfine/shellNL-meshfine.inp` | `40DF1CE77311C8D799564A21A60F3BDEBB8148D52CAE22B7292FDFAD32018220` |
| `reference/shellNL-meshfine/shellNL-meshfine displacements.csv` | `740819FF8AED0E279961581F7CDBFA12784CFBA3A488C35A652E80103F64433F` |
| `reference/shellNL-meshfine/shellNL-meshfine reactions.csv` | `AEB01C98C596792B0E5F2B86A81945CAB0BEB0C6969CFC6738C6F81DF1F94363` |
| `reference/shellNL-meshfine/shellNL-meshfine stresses.csv` | `6D6213AB5DB9D6B1F5FBD641367D08BACC805967B6C5A95BCE0E1A5395377782` |

## 4. Source Identity and Component Contract

### 4.1 Case and accepted-state identity

- Instance identity는 case-insensitive semantic match다. Artifact spelling `Part-1-1`과
  `PART-1-1`은 같은 instance이지만 file text를 rewrite하지 않는다.
- 두 nonlinear case required rows의 exact CSV Frame은
  `Increment     10: Step Time =    1.000`이며 accepted factor-one state에 대응한다.
- Linear case에는 `Frame` column이 없고 single final static state로 해석한다.
- Row order는 identity가 아니다. Stable key match 후 deterministic reporting order로만 정렬한다.

### 4.2 Nodal displacement and rotation

CSV `U-U1/U-U2/U-U3`는 logical `U1/U2/U3`, `UR-UR1/UR-UR2/UR-UR3`는
logical `UR1/UR2/UR3`에 대응한다. Key는

```text
(case_id, accepted_state, canonical_instance_name, source_node_label, component)
```

이다. Coarse/linear은 labels `1..49`, fine은 `1..729`를 각각 정확히 한 번 요구한다.
U는 global length/blocking, UR은 fixed-initial global rotation-vector/warning-only다.

### 4.3 Local reaction review contract

Reaction source rows는 input `Set-2` constraint mask로 선택한다.

- coarse: `1, 3..9, 14..17, 22..33` — 24 nodes, all six DOFs constrained.
- fine: `1, 3..9, 34..57, 82..153` — 104 nodes, all six DOFs constrained.

다른 CSV node rows는 file/schema/finite inventory지만 local reaction numerical rows가 아니다.
Free FESA entries는 reaction이 아니라 accepted free residual evidence다.

| CSV components | logical quantity | matching FESA meaning | disposition |
| --- | --- | --- | --- |
| `RF-RF1`, `RF-RF2` | in-plane local reaction force | constrained translational full residual, global force | `review-only` |
| `RF-RF3` | transverse local reaction force | constrained translational full residual, global force | `review-only` |
| `RM-RM1`, `RM-RM2` | tangent-plane physical reaction moment | constrained generalized residual converted by `J_l(phi)^(-T)`, global spatial force-length | `review-only` |
| `RM-RM3` | director/drilling-axis row | no approved physical external equivalence target | `excluded` |

Raw generalized rotational residual을 CSV RM에 직접 match하지 않는다. Review-only는 row omission을
허용한다는 뜻이 아니다. Exact row precheck와 common-policy error/RMS를 모두 보고하되 그 결과가
blocking verdict를 변경하지 않는다는 뜻이다.

### 4.4 Distinct factor-one equilibrium quantities

각 nonlinear case에서 같은 accepted factor-one state를 사용한다.

| logical quantity | source identity / projection | components | disposition |
| --- | --- | --- | --- |
| accepted free residual | input mask로 결정한 stable free `(instance,node,global DOF component)` rows; force와 moment channel 분리 | free `UX/UY/UZ`; free `URX/URY/URZ` generalized covectors | `blocking-internal` |
| constrained reaction resultant | constrained source rows만 current arm과 spatial physical moment로 합산 | force `[1,2,3]`; moment `[1,2,3]` | `review-only-summary` |
| applied-plus-reaction balance error | all resolved applied sources plus constrained reactions; global origin `[0,0,0]`; `x=X+u`; physical spatial nodal moments | force `[1,2,3]`; moment `[1,2,3]` | `blocking-internal` |

Constrained reaction resultant force is `sum(F_react)`. Its moment is
`sum(x cross F_react + M_react)`. Balance error adds the corresponding applied force and
`x cross F_appl + M_appl`. Accepted free residual is neither sum. 세 quantity는 exact
source/state identity를 공유하지만 interchangeable하지 않다.

현재 stored case의 constrained prescribed `u=phi=0` 때문에 support current arm과 initial arm,
generalized moment와 spatial moment가 수치적으로 일치한다. 이는 supported general nonzero
prescribed translation/rotation에서 initial arm/raw rotational residual을 재사용할 근거가 아니다.

### 4.5 Stress inventory and exclusion

Stress inspection key는

```text
(case_id, accepted_state, instance, element label,
 element-corner node label, SPOS/SNEG section surface, component)
```

이다. Stored stress는 element-corner SPOS/SNEG rows이고 FESA 승인 recovery는 midsurface Gauss
locations의 direct bottom/middle/top `[S11,S22,S12]`다. Nodal extrapolation/averaging을 만들지
않으며 `S-S11/S-S22/S-S12/S-S33` 어느 것도 external family에 포함하지 않는다.

### 4.6 External comparison families

| family id | components / source rows | rows | units / coordinates | disposition |
| --- | --- | ---: | --- | --- |
| `linear.translation` | U1/U2/U3; nodes `1..49` | 147 | length / global | `blocking` |
| `linear.rotation` | UR1/UR2/UR3; nodes `1..49` | 147 | dimensionless / fixed-initial global | `warning-only` |
| `coarse.translation` | U1/U2/U3; nodes `1..49` | 147 | length / global | `blocking` |
| `coarse.rotation` | UR1/UR2/UR3; nodes `1..49` | 147 | dimensionless / fixed-initial global | `warning-only` |
| `coarse.local_reaction_inplane_force` | RF1/RF2; 24 constrained nodes | 48 | force / global shell plane | `review-only` |
| `coarse.local_reaction_transverse_force` | RF3; 24 constrained nodes | 24 | force / global transverse | `review-only` |
| `coarse.local_reaction_physical_moment` | RM1/RM2; 24 constrained nodes | 48 | force-length / global spatial | `review-only` |
| `fine.translation` | U1/U2/U3; nodes `1..729` | 2,187 | length / global | `blocking` |
| `fine.rotation` | UR1/UR2/UR3; nodes `1..729` | 2,187 | dimensionless / fixed-initial global | `warning-only` |
| `fine.local_reaction_inplane_force` | RF1/RF2; 104 constrained nodes | 208 | force / global shell plane | `review-only` |
| `fine.local_reaction_transverse_force` | RF3; 104 constrained nodes | 104 | force / global transverse | `review-only` |
| `fine.local_reaction_physical_moment` | RM1/RM2; 104 constrained nodes | 208 | force-length / global spatial | `review-only` |

### 4.7 Internal blocking verification families

| family id | exact rows/components | gate |
| --- | --- | --- |
| `coarse.accepted_free_force_residual` | 75 free translation DOFs | NSNR-069 force channel, factor one |
| `coarse.accepted_free_moment_residual` | 75 free rotation DOFs | NSNR-069 moment channel, factor one |
| `coarse.global_force_balance` | 3 global balance-error components | normalized `<=1e-8` |
| `coarse.global_moment_balance` | 3 global balance-error components | normalized `<=1e-8` |
| `fine.accepted_free_force_residual` | 1,875 free translation DOFs | NSNR-069 force channel, factor one |
| `fine.accepted_free_moment_residual` | 1,875 free rotation DOFs | NSNR-069 moment channel, factor one |
| `fine.global_force_balance` | 3 global balance-error components | normalized `<=1e-8` |
| `fine.global_moment_balance` | 3 global balance-error components | normalized `<=1e-8` |

이 internal families에는 Abaqus CSV value 또는 `docs/TOLERANCE.md`를 적용하지 않는다.
Approved analytical/invariant gates이며 exact definitions는 `numerical-review.md` §6.2다.

## 5. Row Prechecks

Tolerance 또는 internal metric 전에 다음을 검사한다.

1. 각 case의 exact declared input과 해당 disposition에 필요한 CSV가 존재하고 readable하다.
2. Header는 surrounding whitespace만 trim하고 required names/components가 모두 있어야 한다.
3. Nonlinear required rows의 Frame은 exact factor-one identity여야 한다.
4. Wide CSV는 Section 4 contract로 component rows에 결정적으로 expand한다.
5. Wide key와 expanded key는 unique해야 한다. Duplicate는 affected family를 tolerance 전에 fail한다.
6. Input node inventory와 source constraint mask로 expected key set을 만든다. CSV zero values 또는
   row position에서 reaction identity를 추론하지 않는다.
7. FESA와 reference projected key sets는 exact equal해야 한다. Missing과 extra rows를 모두 fail한다.
8. Required FESA/CSV/internal values와 derived scales/norms는 모두 finite여야 한다.
9. Internal free residual rows는 exact free mask와 force/moment partition을 보존한다. Global balance는
   모든 applied source와 constrained reaction을 stable source order로 한 번씩만 사용한다.
10. Local review rows는 global resultant로 collapse하거나 대체하지 않는다. Review precheck failure는
    deterministic review failure로 기록하지만 blocking verdict를 변경하지 않는다.
11. Warning-only precheck/tolerance failure는 deterministic warning을 만들고 blocking verdict를
    변경하지 않는다. Blocking precheck failure는 전체 comparison을 fail한다.
12. Row omission/synthesis, averaging, source-order matching, clamp, normalization 또는 artifact repair를
    허용하지 않는다.

Observed read-only nodal CSV audit:

| CSV | wide rows | duplicate keys | nonfinite required values | status |
| --- | ---: | ---: | ---: | --- |
| `reference/shell/shell displacements.csv` | 49 | 0 | 0 | readable |
| `reference/shellNL/shellNL displacements.csv` | 49 | 0 | 0 | readable |
| `reference/shellNL/shellNL reactions.csv` | 49 | 0 | 0 | readable |
| `reference/shellNL-meshfine/shellNL-meshfine displacements.csv` | 729 | 0 | 0 | readable |
| `reference/shellNL-meshfine/shellNL-meshfine reactions.csv` | 729 | 0 | 0 | readable |

## 6. Tolerance and Blocking/Warning Policy

### 6.1 External families

Section 4.6의 모든 external blocking, warning-only와 review-only error report는
`docs/TOLERANCE.md`를 그대로 사용한다.

- Reference-only `S=max(abs(reference_i))`, near-zero band `B=0.01*S`.
- `abs(reference_i)<=B`이면 `abs(fesa-reference)<=B`.
- 그 외 row는 relative error `<=0.05`.
- 모든 row와 `RMS(error)/S<=0.01`이 함께 pass해야 family가 pass한다.
- Independent absolute floor, `max(1,S)`, omission, averaging 또는 zero clamp는 없다.
- `S=0`이면 모든 FESA 값도 exact zero일 때만 pass한다.

Observed reference-only scales는 reader/family audit evidence이며 calibration 값이 아니다.

| family | rows | `S` | `B=0.01*S` |
| --- | ---: | ---: | ---: |
| `linear.translation` | 147 | `2.37408203e-5` | `2.37408203e-7` |
| `linear.rotation` | 147 | `7.60725743e-6` | `7.60725743e-8` |
| `coarse.translation` | 147 | `2.37408203e-5` | `2.37408203e-7` |
| `coarse.rotation` | 147 | `7.60725743e-6` | `7.60725743e-8` |
| `coarse.local_reaction_inplane_force` | 48 | `1.91663182` | `1.91663182e-2` |
| `coarse.local_reaction_transverse_force` | 24 | `1.17769805e4` | `1.17769805e2` |
| `coarse.local_reaction_physical_moment` | 48 | `1.95418418e4` | `1.95418418e2` |
| `fine.translation` | 2,187 | `2.57957054e-5` | `2.57957054e-7` |
| `fine.rotation` | 2,187 | `6.58704994e-6` | `6.58704994e-8` |
| `fine.local_reaction_inplane_force` | 208 | `5.38827419e-1` | `5.38827419e-3` |
| `fine.local_reaction_transverse_force` | 104 | `2.78506128e3` | `2.78506128e1` |
| `fine.local_reaction_physical_moment` | 208 | `4.71557520e3` | `4.71557520e1` |

Blocking family의 precheck/row/RMS failure만 전체 external-reference verdict를 fail한다.
Warning-only는 warning, review-only는 deterministic review finding/error table을 남기지만
blocking verdict를 바꾸지 않는다. `RM3`와 stress는 family를 만들지 않는다.

### 6.2 Internal equilibrium families

- Accepted free force/moment residual은 factor-one accepted trial에서 NSNR-069을 그대로
  재현한다. Nonzero matching external scale이면 infinity-norm relative `<=1e-2`; exact-zero
  scale이면 typed absolute `<=1e-3` force 또는 force-length다.
- Global force/moment balance는 `numerical-review.md` §6.2의 sum-of-contribution scale과
  dimension-separated normalized metric을 사용하며 각각 `<=1e-8`이다.
- Internal gate에 external family tolerance, absolute floor, reference-derived scale 또는 local
  nodal reaction error를 섞지 않는다.

## 7. Open Issues and I/O Handoff

Open issues blocking I/O Definition: 없음.

I/O Definition Agent handoff through Coordinator:

- Fine primary와 coarse companion nonlinear case의 accepted factor-one identity를 보존한다.
- Section 4.4의 `(a)` applied-plus-reaction balance error, `(b)` constrained reaction resultant,
  `(c)` accepted free residual을 separate logical quantities로 최종 projection한다.
- Global moment는 origin `[0,0,0]`, current `X+u` force arm과 spatial physical nodal moment를
  사용한다. General nonzero prescribed translation/rotation에서도 initial arm/raw rotational
  residual을 재사용하지 않는다.
- Local RF/RM은 exact source-key/schema/inventory/finite/error reporting이 있는 review-only다.
  Local rows를 global sum으로 대체하거나 blocking으로 되돌리지 않는다.
- Approved Gauss direct stress recovery를 유지한다. Optional element-corner stress artifact에
  맞춘 extrapolation/averaging 또는 stress comparison projection을 만들지 않는다.
- Common external tolerance와 exact prechecks를 변경하지 않는다.

Reference artifact status: required input/displacement/reaction artifacts are present and readable.
Optional fine stress identity issue는 transparent nonblocking inventory finding이다. 어떤 reference
artifact도 생성, rename, repair, normalize 또는 수정하지 않았다.