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

(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:

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

(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.