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_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`
- status: `pass-for-io-definition`
- owner_agent: `numerical-review-agent`
- date: `2026-08-23`
- artifact_policy: `read-only-existing-files`
- tolerance_policy: `docs/TOLERANCE.md`

이 문서는 logical reference quantity, source identity, component matching, row precheck와
blocking/warning 분류만 정의한다. 최종 HDF5 dataset projection은 I/O Definition Agent 소유다.

## 2. Reference Acceptance Scope

Required scope는 두 stored case다.

- `shellnl-s4-final`: `nlgeom=YES` nonlinear static S4 final accepted state를 비교하는
  primary external reference case.
- `shell-s4-linear-limit`: 같은 S4 mesh의 `nlgeom=NO` read-only linear-limit/reference-identity
  regression case. 이 case는 nonlinear response evidence가 아니며, 현재 stress CSV의 element-label
  ordering을 row-order matching으로 사용하지 않는다.

`shellNL`은 final-state reference comparison에는 충분하지만 weak nonlinear response다. Dominant
`U3`/stress 값이 linear case와 거의 같으므로 finite-rotation objectivity, consistent tangent,
commit/rollback과 convergence lifecycle은 `numerical-review.md`의 blocking internal tests로 검증한다.

## 3. Reference Case Inventory with exact input and required CSV paths

| case id | artifact role | required comparison artifact | exact path | observed status |
| --- | --- | --- | --- | --- |
| `shellnl-s4-final` | nonlinear input | yes | `reference/shellNL/shellNL.inp` | readable; S4, 49 nodes, 36 elements, `NLGEOM=YES` |
| `shellnl-s4-final` | displacement reference | yes | `reference/shellNL/shellNL displacements.csv` | 49 finite unique node rows; one factor-one Frame |
| `shellnl-s4-final` | reaction reference | yes | `reference/shellNL/shellNL reactions.csv` | 49 finite unique node rows; one factor-one Frame |
| `shellnl-s4-final` | stress review evidence | no | `reference/shellNL/shellNL stresses.csv` | 288 finite unique rows; element labels `1..36` in stored ascending blocks |
| `shell-s4-linear-limit` | linear control input | yes | `reference/shell/shell.inp` | readable; S4, 49 nodes, 36 elements, `NLGEOM=NO` |
| `shell-s4-linear-limit` | displacement reference | yes | `reference/shell/shell displacements.csv` | 49 finite unique node rows; no `Frame` column |
| `shell-s4-linear-limit` | reaction review evidence | no | `reference/shell/shell reactions.csv` | 49 finite unique node rows |
| `shell-s4-linear-limit` | stress review evidence | no | `reference/shell/shell stresses.csv` | 288 finite unique rows; element labels `1..36` in stored ascending blocks |

`required comparison artifact=no`인 파일도 이번 review에서 읽기 가능성, row identity,
finite values와 current ordering을 확인했다. 그러나 해당 파일은 missing-required-artifact
판정이나 tolerance family를 만들지 않는다.

두 `.inp`는 같은 node/element/connectivity, material/section, instance, boundary와 center-node
`CLOAD`를 사용한다. Text 차이는 heading identity, `NLGEOM=NO -> YES`, 그리고 `*STATIC`
data `1.,1.,1e-05,1. -> 0.1,1.,0.001,0.1`이다. 따라서 `shellNL`은 실제 nonlinear
selector와 승인된 fixed increment `0.1`을 갖지만, 두 deck 차이를 오직 `NLGEOM` 하나의
isolated effect라고 표현하지 않는다.

Read-only SHA-256 observations:

| path | SHA-256 |
| --- | --- |
| `reference/shellNL/shellNL.inp` | `4BF3ECB0F7F1E8462C573E993DBC97AC5D920C91CF6F23AD4C6891D77FFBADA2` |
| `reference/shellNL/shellNL displacements.csv` | `4E0F99CA9372B1ADF7FAF102F43BC0B887DC743FDEDA378E4342D2CF8E0C0786` |
| `reference/shellNL/shellNL reactions.csv` | `001CB1541A9E94424E5E650509D46BC8724970DF4DE47184D9DB09C7938AB069` |
| `reference/shellNL/shellNL stresses.csv` | `5500E5114B1C44887528E30CEC054A1EB0F68BE3F4B8CE81FA59FC74A881483F` |
| `reference/shell/shell.inp` | `4005851E1AB22FD3A16AC17A8D5DA3E051233F69F37419079F3553AD134ECFCF` |
| `reference/shell/shell displacements.csv` | `C81D94E0B4A849F87AA0F79C83A79B94D5661AC79E44ED826919AB432C87746B` |
| `reference/shell/shell reactions.csv` | `0E34EEC27E700C3C0C744C1DAFD8A3B95EFEF34B8616FE96665876586FE82D41` |
| `reference/shell/shell stresses.csv` | `2B75A5B0DEB045A283C9BB7E9B1153B79F7537FF487214BF4A23316B59B660A7` |

## 4. Source Identity and Component Contract

### 4.1 Accepted-state identity

- Abaqus identifiers are case-insensitive semantic identities. Input spelling
  `Part-1-1` and CSV spelling `PART-1-1` match as one instance while original text is
  retained in artifacts and reports; no file or row is rewritten.
- `shellnl-s4-final` rows require exact CSV `Frame` value
  `Increment     10: Step Time =    1.000`, mapped logically to the accepted factor-one state.
- `shell-s4-linear-limit` rows have no `Frame` column and map to the single final static state.
- Row order is never a matching identity. It may only be used for deterministic reporting after
  source keys are matched.

### 4.2 Nodal displacement contract

Required mapping is `U-U1/U-U2/U-U3 -> U1/U2/U3` and
`UR-UR1/UR-UR2/UR-UR3 -> UR1/UR2/UR3`. U is global length; UR is the
dimensionless fixed-initial global rotation-vector output. Logical key is

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

Both cases require source node labels `1..49` exactly once. U components form one
blocking translation family and UR components form one warning-only rotation family,
preserving the project MITC4 classification.

### 4.3 Nonlinear reaction contract

Reaction comparison applies only to `shellnl-s4-final` and only to the input boundary
`Set-2` nodes:

```text
1,3,4,5,6,7,8,9,14,15,16,17,22,23,24,25,26,27,28,29,30,31,32,33
```

All six global components are constrained at these 24 nodes. Other CSV node rows remain
part of file/schema/finite inventory but are not numerical reaction rows: FESA free entries
are equilibrium residual evidence, not Abaqus free-node zero reactions.

| CSV components | logical quantity | FESA meaning | disposition |
| --- | --- | --- | --- |
| `RF-RF1`, `RF-RF2` | fixed-initial shell-plane reaction force | constrained translational full residual, global force | blocking family |
| `RF-RF3` | fixed-initial transverse reaction force | constrained translational full residual, global force | blocking family |
| `RM-RM1`, `RM-RM2` | tangent-plane spatial reaction moment | `J_l(phi)^(-T)` conversion of the constrained generalized reaction, global force-length | blocking family |
| `RM-RM3` | director/drilling-axis reaction review value | stabilization-dependent; no physical external equivalence target | excluded |

In-plane and transverse force are distinct model-fixed logical projections and therefore
use distinct families. Raw generalized rotation-coordinate residual is not matched directly
to the CSV `RM` value.

### 4.4 Stress review identity and comparison exclusion

Stress rows have read-only identity

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

Every current element has its four connectivity nodes and one `SPOS` plus one `SNEG`
row per node. The files are ordered in contiguous ascending element-label blocks `1..36`;
this exact artifact order is retained and no node/surface secondary reorder is applied.

The identity is nevertheless not the approved FESA recovery location: FESA emits direct
`[S11,S22,S12]` at four midsurface Gauss locations and bottom/middle/top positions, without
nodal extrapolation or averaging, and does not emit `S33`. Consequently no stress column
forms a blocking or warning-only comparison family. Stress files remain optional read-only
review evidence only.

### 4.5 Comparison families

| family id | components and source set | row count | units / coordinates | disposition |
| --- | --- | ---: | --- | --- |
| `linear.translation` | `U1,U2,U3`, nodes `1..49` | 147 | length / global | blocking regression |
| `linear.rotation` | `UR1,UR2,UR3`, nodes `1..49` | 147 | dimensionless / fixed-initial global | warning-only |
| `nonlinear.translation` | `U1,U2,U3`, nodes `1..49` | 147 | length / global | blocking |
| `nonlinear.rotation` | `UR1,UR2,UR3`, nodes `1..49` | 147 | dimensionless / fixed-initial global | warning-only |
| `nonlinear.reaction_inplane_force` | `RF1,RF2`, 24 constrained nodes | 48 | force / fixed-initial global plane | blocking |
| `nonlinear.reaction_transverse_force` | `RF3`, 24 constrained nodes | 24 | force / fixed-initial global transverse | blocking |
| `nonlinear.reaction_physical_moment` | `RM1,RM2`, 24 constrained nodes | 48 | force-length / global spatial | blocking |

## 5. Row Prechecks

Before tolerance, the comparator shall fail the affected comparison if any required condition
below is false.

1. Exact declared input path and every `required comparison artifact=yes` CSV path for the
   case exist and are readable.
2. Required headers are present after trimming surrounding whitespace from header names.
3. `shellnl-s4-final` contains only the exact required `Frame` value for required rows.
4. Wide CSV rows expand to component rows using the component contract in Section 4.
5. Required source row keys are unique. Duplicate wide keys or duplicate expanded component keys fail.
6. Displacement projection requires all 49 source nodes and declared components. Nonlinear
   reaction projection derives the exact 24-node/component set from the input constraint mask;
   it does not infer reaction identity from CSV zero values.
7. FESA and reference required projected row-key sets are exactly equal: missing and extra rows
   both fail.
8. Every required numeric value is finite. Nonfinite required FESA or CSV value fails before tolerance.
9. Optional stress inventory uses `(instance, element label, node label, section point)` and verifies
   the current ascending element-label blocks, connectivity nodes and SPOS/SNEG pair. This inspection
   does not create a stress equality gate.
10. Required rows are not omitted, synthesized, normalized, averaged, sorted into a different identity,
   zero-clamped, or repaired.

Observed read-only inventory used for this contract:

| CSV | observed wide key columns | duplicate wide keys | nonfinite observed values | observed element labels |
| --- | --- | ---: | ---: | --- |
| `reference/shellNL/shellNL displacements.csv` | `Frame`, `Part Instance Name`, `Node Label` | 0 | 0 | N/A |
| `reference/shellNL/shellNL reactions.csv` | `Frame`, `Part Instance Name`, `Node Label` | 0 | 0 | N/A |
| `reference/shellNL/shellNL stresses.csv` | `Frame`, `Part Instance Name`, `Element Label`, `Node Label`, `Section Point` | 0 | 0 | `1..36` |
| `reference/shell/shell displacements.csv` | `Part Instance Name`, `Node Label` | 0 | 0 | N/A |
| `reference/shell/shell reactions.csv` | `Part Instance Name`, `Node Label` | 0 | 0 | N/A |
| `reference/shell/shell stresses.csv` | `Part Instance Name`, `Element Label`, `Node Label`, `Section Point` | 0 | 0 | `1..36` |

## 6. Tolerance and Blocking/Warning Policy

Use exactly `docs/TOLERANCE.md` for every external reference family. This report does not invent
or calibrate tolerance values.

For each comparison family:

- `S = max(abs(reference_value_i))`, using reference values only.
- near-zero band is `0.01*S`.
- if `abs(reference_value_i) <= 0.01*S`, row passes iff `abs(fesa-reference) <= 0.01*S`.
- otherwise row passes iff relative error `<= 0.05`.
- family relative RMS is `RMS(error)/S <= 0.01`.
- no independent absolute-error floor, `max(1, S)` clamp, row omission, averaging, or zero clamp is allowed.
- if `S = 0`, the family passes only when all FESA values are exactly zero; otherwise report
  `zero-reference-scale-nonzero-error`.

Families are separated by the exact case/logical quantities in Section 4.5. Current
reference-only scales provide a reproducible reader/comparator audit:

| family | `S` | `B=0.01*S` |
| --- | ---: | ---: |
| `linear.translation` | `2.37408203e-5` | `2.37408203e-7` |
| `linear.rotation` | `7.60725743e-6` | `7.60725743e-8` |
| `nonlinear.translation` | `2.37408203e-5` | `2.37408203e-7` |
| `nonlinear.rotation` | `7.60725743e-6` | `7.60725743e-8` |
| `nonlinear.reaction_inplane_force` | `1.91663182` | `1.91663182e-2` |
| `nonlinear.reaction_transverse_force` | `1.17769805e4` | `1.17769805e2` |
| `nonlinear.reaction_physical_moment` | `1.95418418e4` | `1.95418418e2` |

Any `blocking` family row or RMS failure fails the reference comparison for the feature.
`warning-only` failures produce deterministic warning evidence but do not change the blocking
verdict. `RM3` and stress artifacts create neither a blocking nor warning-only tolerance family.

## 7. Open Issues and I/O Handoff

Open issues blocking I/O Definition: 없음.

I/O Definition Agent handoff:

- Project only the comparison quantities in Sections 4.2, 4.3 and 4.5 to authoritative FESA
  result datasets without changing source identity or final comparison disposition.
- Preserve `Frame` handling for `shellnl-s4-final` as accepted factor-one state identity; do not expose
  trial Newton history as reference rows.
- Derive constrained reaction identity from the input mask. Compare `RM1/RM2` with the global
  spatial physical reaction moment, not the raw generalized rotation-coordinate covector.
- Preserve approved Gauss direct stress recovery. Do not create element-corner stress,
  extrapolation, averaging or a stress CSV projection for the current optional SPOS/SNEG artifacts.
- Keep `RM3`, `S-S33`, `S-S11`, `S-S22` and `S-S12` out of current comparison families.
- Use the common tolerance policy exactly as written above and in `docs/TOLERANCE.md`.

Reference artifact status: complete for I/O Definition. No declared required input or required
comparison CSV is missing or unreadable. Optional stress CSVs are present and readable as inventory
evidence only. No reference artifact was generated, renamed, repaired, normalized, or modified.