FESADev/docs/nonlinear-static-newton-raphson/io.md

Nonlinear Static Newton-Raphson I/O Definition

1. Metadata

• feature_id: nonlinear-static-newton-raphson
• source_requirement: docs/nonlinear-static-newton-raphson/requirements.md
• source_requirement_sha256: 89C1AB5F1BEDB7C5F6AD0726ED62F0982181EA8746EDE4661183FD3D18A2408E
• source_research: docs/nonlinear-static-newton-raphson/research.md
• source_research_sha256: 4F63D23E03D1A68E5F8563B678FDD6F761F9558165778EF0433133EFAD303570
• source_formulation: docs/nonlinear-static-newton-raphson/formulation.md
• source_formulation_sha256: 878028F7B8EC1B91DA9BF00AF78825F50EB0B71046E840A0EEA595AFFD5E14B9
• source_numerical_review: docs/nonlinear-static-newton-raphson/numerical-review.md
• source_numerical_review_sha256: C00994EF4BB23A237547459E157EE5BDA96B28CAF08F712CD31A8E0ABBF62D2C
• source_reference_model: docs/nonlinear-static-newton-raphson/reference-model.md
• source_reference_model_sha256: B2E6845AB59A32F78261B7A47506C27F7BF4B61401B34BC5DE3DAD4F03D6ADDA
• decision_source: USER-DECISION-004 option 1
• balance_gate_decision: user-approved factor-one global force/moment normalized gate <=1e-8
• repository_policy: AGENTS.md, docs/SOLVER_AGENT_DESIGN.md, docs/PRD.md, docs/ARCHITECTURE.md, docs/ADR.md, docs/TOLERANCE.md
• status: ready-for-coordinator-review
• owner_agent: io-definition-agent
• date: 2026-08-28
• authoritative_output: input sibling <stem>_results.h5
• diagnostic_log: input sibling <stem>_log.txt
• hdf5_schema_version: 1

이 문서는 승인된 Stage 5 I/O 계약만 정의한다. Parser, writer, comparison tool의 C++ API나 파일 소유권은 정의하지 않는다. FESA는 Abaqus와 독립적인 solver이며, 아래 .inp subset과 reference CSV mapping은 Abaqus full compatibility, Abaqus S4/S4R 내부 알고리즘, 적분, stabilization, 상태 갱신 또는 output recovery 동등성을 주장하지 않는다.

FEM wiki 근거는 Abaqus Input File Syntax, Abaqus Output Database and Results Files, Abaqus General and Linear Perturbation Steps, Abaqus Initial and Boundary Conditions, Abaqus Loads and Predefined Fields, Abaqus Beam and Shell Section Definitions를 사용했다. 이 근거는 keyword/data/comment line, model/history data, output request, step/load/boundary/section 용어를 정렬하기 위한 보조 근거이며, 승인된 FESA 요구조건과 정식화가 우선한다.

2. Abaqus Input Scope

• input_format: Abaqus input file (.inp)
• supported Abaqus documentation source/version: 프로젝트 연구 bundle 및 local FEM wiki에 보존된 Abaqus 2024 input syntax/output vocabulary. 저장된 nonlinear reference input은 Abaqus/CAE Learning Edition 2024 생성물이다.
• supported_analysis: no-prior-history baseline에서 시작하는 정확히 하나의 source *STEP, NLGEOM=YES와 하나의 nonlinear *STATIC procedure.
• internal_element_formulation: source S4와 S4R 모두 materially linear, geometrically nonlinear Total Lagrangian FESA-MITC4에 매핑한다.
• ordinary_unit_system: 사용자가 일관되게 선택한 미지정 단위계. FESA는 단위 추론이나 변환을 수행하지 않는다.
• compatibility_disclaimer: 이 문서가 명시한 keyword 위치, parameter, data-line arity, validation rule, output mapping만 지원 범위다.

supported는 syntax가 parsing되고 feature semantic model에 매핑된다는 뜻이다. unsupported는 명확한 diagnostic으로 거부한다. ignored-with-warning은 syntax와 소속 data line을 소비하고 warning을 남기지만 Domain, AnalysisModel, nonlinear procedure, mandatory HDF5 output 또는 reference comparison 의미를 바꾸지 않는다. requires-user-decision 항목은 없다.

keyword	policy	allowed location	required parameters and data grammar	semantic mapping	unsupported behavior
*HEADING	supported	optional top-level first keyword	parameter 없음; 다음 keyword 전까지 text row 0개 이상	raw heading을 source metadata로 보존	parameter, nested location, 두 번째 heading은 input error
*INCLUDE	unsupported	anywhere	허용 data/parameter grammar 없음	file traversal 또는 include expansion 없음	unsupported-keyword; 참조 파일을 열지 않음
*PART / *END PART	supported	top-level model block	NAME=<part-name> 필수; *END PART data 없음	part-local node, element, set, shell section scope	unclosed, nested, duplicate, data-bearing close는 input error
*NODE	supported	part scope	각 row node_label,x,y,z; parameter 없음	양의 source node label과 finite global Cartesian coordinate	arity 오류, duplicate label, nonfinite value, dangling later reference는 input/model error
*NSET	supported	part 또는 assembly scope	NSET=<name> 필수; optional GENERATE; assembly scope는 INSTANCE=<name> 필수; explicit labels 또는 first,last,increment	deterministic node-set membership	mixed-instance set, invalid generate row, duplicate set name, empty set, dangling member는 input error
*ELEMENT	supported	part scope	TYPE=S4 또는 TYPE=S4R; 각 row element_label,n1,n2,n3,n4	four-node source shell connectivity; source type 보존; internal type FESA-MITC4	다른 element type은 unsupported-element-formulation; repeated node, arity 오류, dangling node, mixed element model은 error
*ELSET	supported	part 또는 assembly scope	ELSET=<name> 필수; optional GENERATE; assembly scope는 INSTANCE=<name> 필수; *NSET과 같은 row rule	deterministic element-set membership	mixed-instance set, invalid generate row, duplicate set name, empty set, dangling member는 input error
*MATERIAL	supported	top-level model data	NAME=<material-name> 필수; data 없음	정확히 하나의 supported isotropic *ELASTIC 소유	duplicate material, missing/duplicate elasticity, 다른 material behavior는 input error
*ELASTIC	supported	current *MATERIAL scope	정확히 한 row E,nu; parameter 없음	homogeneous isotropic linear elasticity; G=E/(2(1+nu)) 파생	extra field/row, dependency/temperature data, nonfinite value, E<=0, nu<=-1, nu>=0.5는 error
*SHELL SECTION	supported	part scope	ELSET=<name>와 MATERIAL=<name> 필수; 정확히 한 row thickness[,integration_points]	centered homogeneous single-layer shell section	composite/layer data, offset, orientation, controls, variable thickness, missing reference, conflicting assignment, nonpositive thickness는 error
*ASSEMBLY / *END ASSEMBLY	supported	정확히 하나의 top-level assembly	NAME=<assembly-name> 필수; *END ASSEMBLY data 없음	identity-instance scope와 assembly-level set scope	nested/duplicate assembly, instance transform data, unmatched close는 input error
*INSTANCE / *END INSTANCE	supported	assembly scope	NAME=<instance-name>, PART=<part-name> 필수; transform data 없음	named identity copy; 같은 part의 multiple identity instances 허용	duplicate/dangling instance 또는 translation/rotation data는 unsupported input
*BOUNDARY	supported	top-level model data 또는 sole step의 *STATIC 뒤	parameter 없음; 각 row target,first_dof,last_dof[,value]; omitted value는 exact zero	common load-factor path의 factor-one absolute global DOF target; DOF 1..6	amplitude, local coordinate system, invalid range/arity, unresolved target, nonfinite value, conflicting expanded value는 error
*CLOAD	supported	sole step의 *STATIC 뒤	parameter 없음; 각 row target,dof,magnitude; DOF 1..6	load factor로만 scale되는 fixed-global dead nodal force/moment source	amplitude/follower/local load, invalid arity/DOF, unresolved target, nonfinite magnitude, drilling-direction aggregate moment는 error
*DLOAD	unsupported	anywhere	허용 data/parameter grammar 없음	distributed/body/pressure/edge/follower load object를 만들지 않음	load-like usage는 unsupported-distributed-load; 그 외는 unsupported-keyword
*STEP / *END STEP	supported for nonlinear selector	정확히 하나의 top-level history block	optional NAME; NLGEOM=YES 필수; *END STEP data 없음	canonical nonlinear step identity Step-1	zero/multiple/mixed/unclosed/nested step 또는 non-YES nonlinear selector는 nonlinear increment 전 실패
*STATIC	supported nonlinear procedure	sole step의 첫 procedure keyword	정확히 한 row initial_increment,time_period,minimum_increment,maximum_increment; 네 값 모두 finite positive; time_period는 endpoint 1.0 identity	첫 값은 fixed increment h; 세 번째/네 번째 값은 unused compatibility source; factors는 one 미만 ordinal multiple 뒤 exact factor one	missing/extra rows/fields, nonpositive/nonfinite field, endpoint가 1.0이 아니면 invalid-nonlinear-static-data
*OUTPUT	ignored-with-warning	sole step의 *STATIC 뒤	정확히 FIELD, VARIABLE=PRESELECT 또는 HISTORY, VARIABLE=PRESELECT; FIELD/HISTORY는 value 없는 flag이고 둘 중 하나만 필요; VARIABLE은 정확히 한 번 필요; duplicate, both flags, missing VARIABLE, 다른 value, extra parameter는 input error	stored reference의 *Output, field, variable=PRESELECT와 *Output, history, variable=PRESELECT를 warning no-op으로 수용; FESA mandatory output을 select/suppress할 수 없음	output request는 FESA output을 바꾸지 않음; malformed parameter set은 invalid-keyword-parameter
*NODE OUTPUT	ignored-with-warning	active allowlisted *OUTPUT scope	parameter와 다음 keyword 전 variable data를 소비	legacy nodal request U, RF 등을 수용	HDF5 selection, history output, empty synthetic dataset을 만들지 않음
*ELEMENT OUTPUT	ignored-with-warning	active allowlisted *OUTPUT scope	parameter와 다음 keyword 전 variable data를 소비	legacy element request S 등을 수용	extrapolated stress, averaging, comparison projection을 만들지 않음
*PREPRINT	ignored-with-warning	top-level	parameter를 보존 후 무시; data 불필요	generator control syntax 수용	semantic object 없음
*RESTART	ignored-with-warning	sole step	parameter를 보존 후 무시; restart state/data 없음	legacy restart request syntax 수용	restart write/read/continue 없음
*CONTACT OUTPUT	ignored-with-warning	active allowlisted *OUTPUT scope	parameter와 다음 keyword 전 data를 소비	legacy contact-output request syntax만 수용	contact model/output 없음

*ORIENTATION, *TRANSFORM, amplitudes, follower loads, pressure, gravity, body force, edge load, *DLOAD, composite shell definitions, shell section offsets, material nonlinearity, density, temperature dependency, contact, MPC, penalty, multiple steps, restarts, submodels, transforms, nested assemblies와 위 표에 없는 모든 model-affecting keyword는 fail-closed unsupported input이다. 저장 또는 future linear shell input의 NLGEOM=NO는 docs/linear-static-mitc4-shell/io.md가 계속 관할한다. 이 feature bundle에서 해당 linear case는 shell-s4-linear-limit regression reference일 뿐 nonlinear response evidence가 아니다.

3. Syntax Policy

• Keyword line은 optional leading whitespace 뒤 *로 시작한다. Comment line은 **로 시작하며 semantic effect가 없다.
• Keyword name, parameter name, supported enumerated value, named-reference lookup은 ASCII case-insensitive다. Raw source spelling은 diagnostic/report display용으로 보존한다.
• Data line과 keyword parameter field는 comma-separated다. 주변 whitespace는 parsing 전에 trim한다. 필수 field가 비어 있거나, 허용되지 않은 trailing field가 있거나, numeric token이 malformed이면 input error다.
• 승인된 empty data-field 의미는 *BOUNDARY 네 번째 value 생략뿐이며 exact zero로 매핑한다. *SHELL SECTION의 optional second field는 생략 가능하고, 존재하면 positive base-10 integer여야 한다.
• Continuation line, physical-line continuation, multiline name, quoted case-sensitive name, parameter substitution, include file은 unsupported다. 각 logical keyword/data row는 한 physical line에 완결되어야 한다.
• 이 feature는 public numeric Abaqus line-length compatibility limit를 정의하지 않는다. 승인 input은 single-line ASCII record이며, 읽을 수 없는 physical line은 implicit continuation 없이 parsing 실패다.
• Keyword, parameter, set/material/part/instance name, numeric label의 input text는 ASCII로 취급한다. HDF5 string output은 UTF-8이지만 non-ASCII source label/name은 이 feature 계약 밖이다.
• Node label, element label, explicit set member는 positive base-10 integer다. Source label은 text와 numeric identity로 보존한다. Stable internal index는 diagnostic 또는 comparison row에서 source identity를 대체할 수 없다.
• 모든 real-valued input은 finite double로 parse되어야 한다. NaN, Inf, overflow, nonfinite underflow, locale-dependent numeric format은 reject한다.
• Model data와 history data는 개념적으로 분리한다. Mesh, set, material, section, coordinate, initial shell frame은 model data다. Step, procedure, boundary, load, output request는 history data다.
• 어떤 keyword에도 속하지 않는 standalone data 또는 active keyword block 밖의 data는 input error다. Output-request variable data는 allowlisted output keyword에 종속될 때만 no-op으로 소비한다.
• 모든 parsed keyword, parameter, data row, semantic entity는 normalized file path, 1-based line, raw keyword spelling, source identity까지 추적 가능해야 한다.

4. Model Data Mapping

4.1 Stable Source Identity and Ordering

Identity-instance expansion 뒤 source node와 source element의 stable identity는 다음과 같다.

SourceEntityId { instance_name, source_label }

Name lookup은 case-insensitive지만 raw spelling은 보존한다. Stable internal ID는 input part declaration order, instance declaration order, part-local entity declaration order로 부여한다. Hash iteration, thread scheduling, set spelling, CSV row order는 source identity, internal row order, diagnostic order 또는 result row order를 바꾸면 안 된다.

4.2 Nodes, Elements and Sets

• *NODE는 finite global Cartesian initial midsurface coordinate [X,Y,Z]로 매핑하며 unit dimension은 length다.
• *ELEMENT, TYPE=S4/S4R는 ordered four-node shell connectivity [1,2,3,4]로 매핑한다. Natural corner 순서는 (-1,-1), (+1,-1), (+1,+1), (-1,+1)이며 connectivity를 조용히 reverse하지 않는다.
• Source type S4 또는 S4R는 metadata로 보존한다. 두 type 모두 같은 internal FESA-MITC4 formulation, 2 x 2 x 2 integration, nonlinear state path를 선택한다. Source S4R는 reduced integration, hourglass control 또는 Abaqus S4R internal behavior를 활성화하지 않는다.
• *NSET과 *ELSET은 explicit row order를 보존한다. GENERATE는 inclusive first,last,increment 순서로 expand한다. Assembly-scope set은 하나의 INSTANCE만 참조할 수 있고 mixed instance는 허용하지 않는다.
• Set membership은 Domain commit 전에 source identity로 resolve한다. 같은 scope의 duplicate set definition, dangling member, invalid generate range는 analysis 전 실패한다.

4.3 Material, Section, Coordinates and Units

• *MATERIAL과 *ELASTIC은 finite E>0, -1<nu<0.5를 갖는 homogeneous isotropic materially linear material 하나로 매핑한다.
• *SHELL SECTION은 하나의 element set을 resolved material과 positive finite thickness>0를 갖는 centered homogeneous shell layer로 매핑한다. Optional source integration-point 값은 syntax compatibility로만 보존하며 quadrature, recovery, output, reference comparison에 영향을 주지 않는다.
• Initial nodal director와 right-handed triad는 instance expansion 뒤 승인된 linear MITC4 deterministic incident-element rule로 파생한다. 이 값들은 model data이며 모든 increment의 fixed initial reference를 정의한다.
• 필수 geometry check는 finite coordinate, valid four-node topology, 모든 Gauss/tying/ center/recovery location의 positive reference Jacobian, non-opposed incident normals, valid reciprocal bases, valid initial frames를 포함한다.
• .inp 단위는 user-consistent unspecified다. HDF5는 length, force, force*length, force/length, force/length^2, 1 같은 unit dimension string만 기록하고 SI를 쓰거나 추론하지 않는다.

5. History Data Mapping

5.1 Step and Procedure

Nonlinear procedure는 정확히 하나의 source step이 *STEP, NLGEOM=YES를 포함하고 그 안에 정확히 하나의 supported *STATIC data row가 있을 때만 선택한다. Semantic step name은 canonical Step-1이다. Raw source step name은 provenance로만 보존한다.

Nonlinear *STATIC data row의 의미는 다음과 같다.

• initial_increment는 fixed positive load-factor increment h다.
• time_period는 endpoint 1.0과 정확히 같은 identity여야 한다.
• minimum_increment와 maximum_increment는 positive finite source value여야 하지만 cutback, growth, retry, stopping, convergence, output cadence에는 사용하지 않는다.
• Intended factor identity는 1.0보다 작은 ordinal j*h 값들을 만든 뒤, 마지막에 exact assigned factor 1.0 하나를 붙여 만든다. Cumulative lambda += h, tolerance-based duplicate endpoint detection, growth, cutback, retry는 금지한다.
• reference/shellNL/shellNL.inp의 성공 run에서 expected intended/accepted factor sequence는 0.1,0.2,...,1.0이다.

Factor zero는 no-prior-history step-start committed baseline이다. Accepted frame은 committed increment와 일대일 대응해야 하므로 factor zero는 accepted HDF5 frame이 아니다. Factor zero는 다음 metadata/model dataset으로만 projection한다.

• factor_zero_is_frame=0
• factor_zero_load_factor=0.0
• /model/prescribed_displacement_start와 initial state의 step-start displacement 및 rotation-vector component
• /model/shell/nodal_frame과 /model/shell/nodal_director의 step-start triad/director
• zero scaled *CLOAD contribution과 step-start boundary value

5.2 Boundary Conditions

*BOUNDARY target resolution은 direct node label 또는 node set을 허용한다. Expanded row는 stable source-node identity와 DOF order 1..6를 사용한다.

DOF	component	unit dimension	nonlinear path meaning
1	UX / CSV U1	length	factor-one absolute global displacement target
2	UY / CSV U2	length	factor-one absolute global displacement target
3	UZ / CSV U3	length	factor-one absolute global displacement target
4	URX / CSV UR1	dimensionless rotation	factor-one absolute fixed-initial global rotation-vector target
5	URY / CSV UR2	dimensionless rotation	factor-one absolute fixed-initial global rotation-vector target
6	URZ / CSV UR3	dimensionless rotation	factor-one absolute fixed-initial global rotation-vector target

Step 앞 row와 sole step 내부 row는 모두 같은 semantic step의 factor-one target으로 매핑한다. Cross-step propagation은 없다. Load factor lambda에서 current constrained value는 q_start + lambda * (q_target - q_start)다. Current release에는 prior history가 없으므로 ordinary start value는 승인된 start-state dataset에 명시된 값을 제외하고 zero다. Constrained Newton correction component는 exact zero다.

5.3 Concentrated Loads

*CLOAD target resolution은 boundary와 같다. 같은 node/DOF로 resolve되는 여러 row는 source order로 factor-one global load coefficient에 누적한다. Factor lambda에서 magnitude는 lambda만 곱한다.

DOF	source component	unit dimension	nonlinear meaning
1	F1	force	fixed-global dead nodal force
2	F2	force	fixed-global dead nodal force
3	F3	force	fixed-global dead nodal force
4	M1	force*length	fixed-global source nodal moment admitted only through physical director-tangent work
5	M2	force*length	fixed-global source nodal moment admitted only through physical director-tangent work
6	M3	force*length	fixed-global source nodal moment admitted only through physical director-tangent work

Nonzero aggregated nodal moment M_src마다 preprocessing과 모든 entered trial state에서 abs(dot(d,M_src))/norm(M_src) <= 1e-12를 denominator clamping 없이 만족해야 한다. 실패하면 unsupported-drilling-load다. Source moment vector는 fixed global coordinate에 남으며 FESA는 rejected moment component를 회전, 축소, 변형하거나 numerical drilling channel로 보내지 않는다.

5.4 Output Requests

Abaqus output request keyword는 ignored-with-warning compatibility syntax로만 수용한다. 이 keyword들은 history output을 켜지 않고, frame cadence를 제어하지 않으며, mandatory FESA HDF5 dataset을 select, suppress, rename할 수 없다. Trial Newton state는 HDF5 field/history output이 아니다. Per-iteration evidence는 <stem>_log.txt에 diagnostic text로만 기록한다.

6. Internal Model Contract

이 section은 semantic field를 정의하며 C++ API를 정의하지 않는다.

• Node record: stable internal node ID, SourceEntityId, finite global coordinate, initial director, initial right-handed triad, source location.
• Element record: stable internal element ID, SourceEntityId, preserved source type S4 또는 S4R, internal formulation FESA-MITC4, ordered four-node connectivity, resolved section/material identity, source location.
• Set record: case-insensitive set name, source scope, optional source instance, deterministic expanded source members, stable internal member IDs.
• Material record: case-insensitive material name, finite E, finite nu, derived G, source location, homogeneous isotropic materially linear identity.
• Section record: source ELSET, resolved material, positive thickness, optional ignored source integration-point field, centered single-layer identity.
• Boundary record: source target, expanded node identities, DOF range, finite factor-one absolute target values, step-start values, source location, conflict status.
• Load record: source target, expanded node identities, DOF, finite factor-one source magnitude, deterministic aggregate value, dead fixed-global load identity.
• Step record: raw source name, canonical Step-1, NLGEOM=YES nonlinear procedure identity, fixed increment h, endpoint 1.0, unused third/fourth *STATIC values, intended factor sequence, output-request no-op inventory.
• State contract: committed state와 trial state는 alias될 수 없다. 완전하게 수렴한 candidate만 displacement, rotation vector, Q, director, load factor, frame identity, internal/external force, residual/reaction, physical recovery row를 commit한다. Failed trial, nonconvergence, nonfinite data, solve failure, recovery failure 또는 output failure는 prior committed state와 prior authoritative final result를 보존한다.
• Output request record: keyword, parameter, variable row, source location은 warning diagnostic용으로만 보존한다. Solver 또는 HDF5 selection effect는 없다.

Source identity와 internal index identity는 diagnostics, HDF5 row order, reference comparison 전체에서 구분해야 한다. CSV의 element-label order는 solver identity가 아니며 (instance, source_label) key를 대체하지 않는다.

7. Output HDF5 Schema

7.1 Public Output Names, Log and Lifecycle

승인된 public CLI shape는 다음 하나뿐이다.

fesa.exe <model.inp>

CLI는 input path 해석보다 먼저 argv token을 왼쪽에서 오른쪽으로 scan한다. 어떤 token이든 case-sensitive exact literal substring --output을 포함하면, --output, --output=..., --output-path, prefix/suffix form을 모두 포함해 usage failure다. 이 failure는 input path resolution, parsing, Analysis construction, derived-result path ownership, HDF5 candidate, log creation/truncation, output finalization 전 exit code 2로 끝난다. Stderr에는 ordered diagnostic 하나만 쓴다.

severity=error	code=cli-usage	argument_index=<uint64>	argument=<escaped argv token>	message=literal --output is not supported

여러 token이 --output을 포함해도 첫 matching token만 보고 위 diagnostic 하나만 낸다. Literal --output에 대한 compatibility alias나 deprecation window는 없다. --output을 포함하지 않는 다른 unknown option은 별도 unrecognized-option usage diagnostic을 유지할 수 있다.

Input/output lexical identity는 다음 순서로 정의한다.

1. 단일 input path token이 relative path이면 invocation CWD를 lexical base로 붙인다.
2. .와 .. component만 lexically normalize한다. Symlink, junction, short-name, case-preserving target path는 resolve하지 않는다.
3. Normalized user-addressed final filename의 마지막 extension이 case-insensitive .inp가 아니면 input usage failure다.
4. <stem>은 마지막 extension 하나만 제거한 basename이다. 앞선 dot과 basename case는 보존한다. 예: Beam.Model.INP -> Beam.Model_results.h5, Beam.Model_log.txt.
5. Derived outputs는 normalized user-addressed input path의 sibling이다.

• result final: <input-directory>/<stem>_results.h5
• log final/live file: <input-directory>/<stem>_log.txt

File-vs-directory collision과 same-derived-pair concurrency는 output ownership 문제다. <stem>_log.txt가 directory 또는 truncate 불가능한 non-regular path이면 log create/open/ truncate failure다. <stem>_results.h5가 directory이면 HDF5 output collision으로 fail-closed 한다. 같은 derived pair를 목표로 하는 concurrent invocation은 same-directory implementation-private lock을 nonblocking exclusive ownership으로 먼저 획득해야 한다. Lock 획득 실패 또는 lock path의 directory collision은 exit code 6의 output-busy failure이며 best-effort fatal stderr diagnostic 하나를 시도하고 log/HDF5를 변경하지 않는다. Lock holder 하나만 log truncate, HDF5 candidate, final replace를 시도한다. Candidate filename은 public contract가 아니지만 반드시 same-directory, implementation-private, exclusive-create collision-safe여야 하며 실패한 candidate는 authoritative output이 아니다.

HDF5 result lifecycle과 log lifecycle은 의도적으로 비대칭이다.

• <stem>_log.txt는 CLI usage validation, lexical output derivation, single-writer lock 획득 뒤 replace/truncate된다. Create/open/truncate failure는 Analysis 전 exit code 6으로 abort하며, best-effort fatal stderr diagnostic 하나를 시도한다.
• Log write/flush failure는 즉시 abort한다. Solver는 retry, fallback, continue 또는 result commit을 하지 않는다. Prior authoritative HDF5는 보존하고, 이미 flush된 live-log prefix는 rollback하지 않는다. Failed write 뒤 남은 partial trailing line은 authoritative iteration record가 아니며 tooling은 LF-terminated complete record만 parsing한다.
• Log close는 successful analysis/recovery 뒤, 그리고 HDF5 candidate open/write/final replace 전 수행한다. Close failure는 result commit을 block하고 exit code 6으로 끝낸다.
• <stem>_results.h5는 sibling candidate가 완전히 write, flush, close, reopen, schema-check된 뒤 atomic move/replace에 성공한 경우에만 authoritative다.
• HDF5 failure는 exit code 6을 반환하고 가능한 경우 prior valid final을 보존하며 current-run log를 rollback하지 않는다. HDF5 failure는 log close 성공 뒤 발생하므로 current log는 닫힌 current-run audit으로 남는다.

Newton iteration log는 UTF-8 no BOM, LF-terminated text file이다. Header, trailer, BOM, CRLF는 없다. Entered Newton iteration마다 physical line 하나만 기록하고, 각 line은 fixed field order의 TAB-separated label=value record다. Per-iteration stderr duplication은 정확히 0개다. 각 iteration record는 다음 iteration 진입 전 또는 return 전 flush되어야 한다.

Non-Newton procedure 또는 Newton iteration에 진입하기 전 끝난 controlled failure는 iteration record를 fabricate하지 않는다. 같은 open/truncate/failure lifecycle을 적용하되 successful non-Newton run의 <stem>_log.txt content는 zero-byte empty file이다. Pre-Newton controlled failure도 entered iteration이 없으면 iteration record가 없는 log file만 남긴다.

고정 field order는 다음과 같다.

order	label	value contract
1	record	literal newton-iteration
2	schema	literal nsnr-log-v1
3	increment	entered increment identity, uint64
4	target_factor	finite round-trip numeric load factor
5	iteration	entered Newton iteration identity 1..100
6	last_completed_stage	enum stage completed before outcome; none allowed
7	failing_stage	none for completed gate records, otherwise failing stage enum
8	residual_force_channel	literal residual_force or not-evaluated(reason)
9	residual_force_numerator_norm	`
10	residual_force_denominator_scale	matching `
11	residual_force_branch	matching external scale이 nonzero이면 relative, exact zero이면 zero-scale, 또는 not-evaluated(reason)
12	residual_force_threshold	1e-2 for relative, 1e-3 for zero-scale, or not-evaluated(reason)
13	residual_force_threshold_unit	1, force, or not-evaluated(reason)
14	residual_force_pass	0, 1, or not-evaluated(reason)
15	residual_moment_channel	literal residual_moment or not-evaluated(reason)
16	residual_moment_numerator_norm	`
17	residual_moment_denominator_scale	matching `
18	residual_moment_branch	matching external scale이 nonzero이면 relative, exact zero이면 zero-scale, 또는 not-evaluated(reason)
19	residual_moment_threshold	1e-2 for relative, 1e-3 for zero-scale, or not-evaluated(reason)
20	residual_moment_threshold_unit	1, force*length, or not-evaluated(reason)
21	residual_moment_pass	0, 1, or not-evaluated(reason)
22	correction_translation_channel	literal correction_translation or not-evaluated(reason)
23	correction_translation_numerator_norm	`
24	correction_translation_denominator_scale	`
25	correction_translation_branch	relative, zero-scale, or not-evaluated(reason)
26	correction_translation_threshold	1e-2 for relative, 1e-3 for zero-scale, or not-evaluated(reason)
27	correction_translation_threshold_unit	1, length, or not-evaluated(reason)
28	correction_translation_pass	0, 1, or not-evaluated(reason)
29	correction_rotation_channel	literal correction_rotation or not-evaluated(reason)
30	correction_rotation_numerator_norm	`
31	correction_rotation_denominator_scale	`
32	correction_rotation_branch	relative, zero-scale, or not-evaluated(reason)
33	correction_rotation_threshold	1e-2 for relative, 1e-3 for zero-scale, or not-evaluated(reason)
34	correction_rotation_threshold_unit	1, 1, or not-evaluated(reason)
35	correction_rotation_pass	0, 1, or not-evaluated(reason)
36	combined_pass	logical AND of four pass fields, or not-evaluated(reason)
37	transition	accept, update, fail, or not-evaluated(reason)
38	outcome	accepted, continue, nonconverged, or failed
39	diagnostic_code	none or approved diagnostic code

nsnr-log-v1의 39개 field label, order와 TAB-separated label=value serialization은 변경하지 않는다. Completed gate record는 failing_stage=none이고 네 channel의 identity, numerator/norm, denominator/scale, branch, typed threshold, pass를 모두 finite 또는 enum value로 노출한다.

Residual channel은 required residual/internal/external vector와 그 infinity norm을 모두 finite로 확인한 뒤 matching external scale S_ext^u=||f_ext,f^u||_inf 또는 S_ext^phi=||f_ext,f^phi||_inf 자체로 branch를 선택한다. Matching external scale이 exact zero이면 residual_*_denominator_scale=0, residual_*_branch=zero-scale로 직렬화하고 numerator에 typed absolute 1e-3 force 또는 1e-3 force*length를 inclusive <=로 직접 적용한다. 이 exact 0은 matching external selector를 직렬화하며 divisor 또는 internal-inclusive max가 아니다. Selector predicate는 S_ext==0이고 tolerance band, zero clamp, max(1,...)를 쓰지 않는다. Internal scale 또는 residual numerator가 nonzero여도 이 branch를 relative로 바꾸지 않는다. Matching external scale이 nonzero이면 residual_*_denominator_scale은 retained max(||f_int,f||_inf,||f_ext,f||_inf)이고 residual_*_branch=relative이며, numerator/denominator ratio에 dimensionless 1e-2를 inclusive <=로 적용한다. 이 branch에 typed absolute gate를 OR로 추가하지 않는다.

Correction channel은 기존 계약 그대로 current-trial incremental-solution denominator가 exact zero이면 zero-scale과 typed 1e-3 length 또는 1e-3 dimensionless를, nonzero이면 relative와 dimensionless 1e-2를 사용한다. Empty free channel은 exact-zero numerator/scale의 typed zero-scale branch로 평가한다. 네 channel의 pass는 combined_pass에서 logical AND로만 결합한다.

Early failure record는 entered iteration 하나에 대응한다. 이미 계산된 earlier fields는 실제 finite value를 기록하고, 실패 stage 뒤의 모든 later field는 not-evaluated(reason)을 기록한다. Not-evaluated field에 zero, pass 0, pass 1, fabricated denominator 또는 fabricated threshold를 쓰면 안 된다. last_completed_stage와 failing_stage는 stage enum을 사용하며 recommended enum은 iteration-entered, trial-state, load-boundary, residual, tangent, factorization, correction, convergence-gates, update, recovery, commit, log-write, log-flush, none이다.

Numeric value는 locale-independent C-locale decimal point를 사용하고 finite IEEE-754 double round-trip이 가능해야 한다. NaN, Inf, localized comma, thousands separator, raw whitespace는 금지한다. String value는 raw TAB/LF/CR/control byte/backslash를 포함할 수 없으며 \\, \t, \n, \r, \0, \xHH escape를 사용한다. Record order는 increment, target factor, iteration 순서로 deterministic해야 한다.

Schema version 1의 모든 mandatory HDF5 dataset은 contiguous, uncompressed dataset이다. Chunking, compression filter, extendible dataset, trial-history group은 이 release 계약에 없다.

7.2 Metadata and Common Dataset Attribute Rules

results.h5 schema가 authoritative solver output이다. 실제 final filename은 Section 7.1의 <stem>_results.h5다. 모든 string은 UTF-8이다. 모든 physical real dataset은 IEEE-754 float64를 사용한다. Stable ID는 별도 명시가 없으면 unsigned 64-bit integer다.

/metadata group의 required attributes는 다음과 같다.

attribute	required value or meaning
schema_version	1
feature_id	nonlinear-static-newton-raphson
solver_version	executing solver version string
source_input_identity	lexical normalized user-addressed input path and content identity string; symlink/junction target resolution 없음
unit_system_label	user-consistent-unspecified
coordinate_convention	global-cartesian; shell-local=fixed-initial-reference; positive-thickness=+zeta
analysis_procedure	nonlinear-static-full-newton
internal_formulation	FESA-MITC4-total-lagrangian
integration_rule	2x2x2-gauss; mitc4-edge-midpoint-shear
step_name	Step-1
frame_indexing	accepted-increment-order-zero-based
factor_zero_is_frame	0
factor_zero_load_factor	0.0

모든 numeric model/result dataset은 다음 required attributes를 가진다.

• schema_version=1
• component_names
• component_unit_dimensions
• coordinate_system
• location

Accepted-frame result dataset은 추가로 다음 attributes를 가진다.

• step_name=Step-1
• frame_index=<uint64>
• increment_index=<uint64>
• load_factor=<float64>
• is_factor_one=<0|1>

7.3 Model Datasets

dataset path	shape and dtype	row identity / fields	required attributes and ordering
/model/nodes	[node_count] compound	internal_node_id:uint64, instance_name:utf8, source_label:utf8, coordinates:float64[3]	internal ID ascending; coordinate_system=global-cartesian, component_unit_dimensions=length,length,length, location=nodal-reference
/model/elements	[element_count] compound	internal_element_id:uint64, instance_name:utf8, source_label:utf8, source_element_type:utf8, internal_formulation:utf8, node_internal_ids:uint64[4], shell_section_internal_id:uint64, material_internal_id:uint64	internal element ID ascending; formulation=FESA-MITC4-total-lagrangian
/model/shell/materials	[material_count] compound	internal_material_id:uint64, name:utf8, E:float64, nu:float64	declaration order; component_unit_dimensions=force/length^2,1, location=model-material
/model/shell/sections	[section_count] compound	internal_section_id:uint64, source_file:utf8, source_line:uint64, source_elset:utf8, material_internal_id:uint64, thickness:float64	declaration order; component_unit_dimensions=length, location=model-shell-section, layering=centered-single-layer
/model/shell/nodal_director	[node_count,3] float64	/model/nodes row; [D1,D2,D3]	initial director; coordinate_system=global-cartesian, location=nodal-initial-director, units 1,1,1
/model/shell/nodal_frame	[node_count,3,3] float64	/model/nodes row; axis row [A,B,D], global component column [X,Y,Z]	initial right-handed triad; coordinate_system=global-cartesian, location=nodal-initial-frame, units 1,1,1
/model/nodal_constraint_mask	[node_count,6] uint8	/model/nodes row; DOF [UX,UY,UZ,URX,URY,URZ]	0=free, 1=constrained; constrained reaction comparison identity의 authority
/model/prescribed_displacement_start	[node_count,6] float64	same row/DOF order	factor-zero start values; units [length x3,1 x3], load_factor=0.0
/model/prescribed_displacement_target	[node_count,6] float64	same row/DOF order	factor-one absolute target values; units [length x3,1 x3], load_factor=1.0
/model/shell/midsurface_locations	[4,2] float64	location rows GP1..GP4; columns [XI,ETA]	coordinate_system=shell-natural; (-g,-g),(+g,-g),(+g,+g),(-g,+g), g=1/sqrt(3)
/model/shell/section_positions	[3] float64	rows [BOTTOM,MIDDLE,TOP]; values [-1,0,+1]	coordinate_system=shell-natural; physical z=t*zeta/2; Abaqus section-point identity가 아님

7.4 Accepted Frame Table

Successful nonlinear run 뒤 /steps/Step-1/accepted_frames는 mandatory다.

path	shape and dtype	fields	required meaning
/steps/Step-1/accepted_frames	[frame_count] compound	frame_index:uint64, increment_index:uint64, load_factor:float64, iteration_count:uint64, is_factor_one:uint8	committed increment마다 한 row; frame_index는 <frame> group name과 같음; load factor는 strictly increasing; 마지막 row는 load_factor=1.0, is_factor_one=1

frame_count는 committed increment 수이며 successful run에서는 하나 이상이다. Factor-one row는 정확히 하나다. Factor zero는 이 dataset에 row를 갖지 않고 /frames/0 특별 의미도 갖지 않는다.

7.5 Accepted Frame Result Datasets

/steps/Step-1/accepted_frames.frame_index = <frame>마다 아래 dataset들이 /steps/Step-1/frames/<frame>/ 아래 mandatory다.

quantity	exact dataset path	shape	row identity and component order	units / coordinates / location
committed displacement and rotation vector	/steps/Step-1/frames/<frame>/nodal/displacement	[node_count,6] float64	/model/nodes row; [UX,UY,UZ,URX,URY,URZ]	[length,length,length,1,1,1]; global Cartesian translations and fixed-initial global rotation-vector components; nodal
committed triad	/steps/Step-1/frames/<frame>/nodal/triad	[node_count,3,3] float64	node row; axis row [A,B,D], global component column [X,Y,Z]	dimensionless; global Cartesian; committed Q; director는 row D
committed director	/steps/Step-1/frames/<frame>/nodal/director	[node_count,3] float64	node row; [D1,D2,D3]	dimensionless; global Cartesian; triad axis D와 같아야 함
generalized internal force	/steps/Step-1/frames/<frame>/nodal/generalized_internal_force	[node_count,6] float64	node row; [FI1,FI2,FI3,MI_PHI1,MI_PHI2,MI_PHI3]	[force x3,force*length x3]; work-conjugate to [u,phi]; nodal
generalized external force	/steps/Step-1/frames/<frame>/nodal/generalized_external_force	[node_count,6] float64	node row; [FE1,FE2,FE3,ME_PHI1,ME_PHI2,ME_PHI3]	[force x3,force*length x3]; work-conjugate to [u,phi]; approved physical moment projection 후 fixed-global dead loads; nodal
generalized residual	/steps/Step-1/frames/<frame>/nodal/generalized_residual	[node_count,6] float64	node row; [RU1,RU2,RU3,RPHI1,RPHI2,RPHI3]	[force x3,force*length x3]; nonlinear solution coordinate의 full assembled f_int-f_ext; nodal
reaction / spatial full-residual projection	/steps/Step-1/frames/<frame>/nodal/reaction	[node_count,6] float64	node row; [RF1,RF2,RF3,RM1,RM2,RM3]	[force x3,force*length x3]; global; translation은 full generalized residual과 같고 rotation은 J_l(phi)^(-T) spatial moment conversion. Constrained reaction은 mask를 generalized residual에 먼저 적용한 뒤 변환하며 accepted free residual의 authority는 이 dataset이 아니라 nodal/generalized_residual이다.
shell local frame	/steps/Step-1/frames/<frame>/element/shell/local_frame	[element_count,4,3,3] float64	element row, midsurface location row GP1..GP4, axis row [E1,E2,E3], global component column [X,Y,Z]	dimensionless; physical recovery용 fixed-initial shell local frame; rotating Abaqus output frame이 아님
generalized strain	/steps/Step-1/frames/<frame>/element/shell/generalized_strain	[element_count,4,8] float64	element row, GP1..GP4; [E11,E22,G12,K11,K22,K12,G13,G23]	[1,1,1,1/length,1/length,1/length,1,1]; fixed-reference shell local; midsurface
section resultant	/steps/Step-1/frames/<frame>/element/shell/section_resultant	[element_count,4,8] float64	element row, GP1..GP4; [N11,N22,N12,M11,M22,M12,Q13,Q23]	[force/length x3,force x3,force/length x2]; fixed-reference shell local; midsurface
in-plane stress	/steps/Step-1/frames/<frame>/element/shell/stress	[element_count,4,3,3] float64	element row, GP1..GP4, section position [BOTTOM,MIDDLE,TOP], component [S11,S22,S12]	force/length^2; fixed-reference shell local; direct bottom/middle/top evaluation
physical strain energy	/steps/Step-1/frames/<frame>/global/energy	[1] float64	[PHYSICAL_STRAIN_ENERGY]	force*length; deterministic element reduction; numerical drilling stabilization 제외
global applied-plus-reaction balance error	/steps/Step-1/frames/<frame>/global/equilibrium	[6] float64	[FORCE_1,FORCE_2,FORCE_3,MOMENT_1,MOMENT_2,MOMENT_3]	[force x3,force*length x3]; global Cartesian; formulation §13.4의 applied-plus-constrained-reaction balance error; moment about global origin [0,0,0], current force arms와 spatial physical nodal moments 사용; location=global-balance-error

Trial Newton state, iteration history, line search, cutback attempt, damping, automatic stabilization, numerical drilling stress, drilling energy ratio, S33, S13, S23, nodal stress extrapolation, element-corner stress, averaged stress, Abaqus integration-point number에 대한 HDF5 dataset은 만들지 않는다.

7.5.1 Equilibrium Projection and Schema Compatibility

Schema version 1과 기존 /global/equilibrium path/shape는 유지한다. 기존 계약이 이미 global origin [0,0,0], current force arm과 spatial physical nodal moment를 지정했으므로 이 dataset의 authoritative meaning은 처음부터 formulation §13.4의 global applied-plus-reaction balance error다. Raw full-residual sum, initial-coordinate arm 또는 raw rotation-coordinate covector를 이 path에 쓰는 것은 schema-compatible implementation이 아니다. 이 의미 명확화는 path, shape 또는 component를 바꾸지 않으므로 schema version을 올리지 않는다.

같은 accepted frame의 세 equilibrium quantity는 다음처럼 서로 다른 HDF5 projection으로 재구성된다. 별도 중복 summary dataset은 만들지 않는다.

logical quantity	authoritative HDF5 projection	coordinates / units	disposition
accepted free residual	/model/nodal_constraint_mask==0인 component를 /nodal/generalized_residual에서 선택한다. NSNR-069 scale은 같은 free component의 /nodal/generalized_internal_force와 /nodal/generalized_external_force에서 계산한다.	translation channel은 global force, rotation-coordinate channel은 generalized force-length	blocking-internal
constrained reaction resultant	/model/nodal_constraint_mask를 /nodal/generalized_residual에 먼저 적용해 constrained generalized reaction을 만들고, rotation block만 accepted phi의 J_l(phi)^(-T)로 spatial moment로 변환한다. Current position은 /model/nodes.coordinates + /nodal/displacement[UX,UY,UZ]다. Stable node order로 sum(F_react)와 sum(x cross F_react + M_react)를 계산한다.	global force [3], global spatial force-length moment [3] about [0,0,0]	review-only-summary
applied-plus-reaction balance error	required dataset /global/equilibrium; applied contribution은 accepted /nodal/generalized_external_force의 translation block과 J_l(phi)^(-T)로 변환한 rotational block, reaction contribution은 바로 위 constrained projection을 사용한다. Stable node order로 formulation §13.4의 합을 계산한다.	global force [3], global spatial force-length moment [3] about [0,0,0]	blocking-internal

Componentwise constraint selection은 spatial moment 변환보다 먼저 수행한다. 따라서 partial rotational constraint나 nonzero prescribed rotation에서도 constrained reaction resultant에 free generalized residual이 섞이지 않는다. Local /nodal/reaction display나 full residual sum을 위 세 quantity 중 다른 하나의 substitute로 사용하지 않는다. Nonzero prescribed translation에서는 initial position이 아니라 accepted current position을 force arm으로 사용한다.

7.6 Diagnostics Dataset

/diagnostics는 mandatory이며 row가 0개일 수 있다.

path	shape and dtype	fields	required meaning
/diagnostics	[diagnostic_count] compound	severity:utf8, code:utf8, file:utf8, line:uint64, keyword:utf8, entity_identity:utf8, message:utf8	CLI/input/model/solver/output deterministic diagnostics; ignored keyword warning도 success file에 보존

Diagnostic order는 source file declaration order, 1-based line, stable entity identity, diagnostic code, discovery order를 순서대로 사용한다. Source가 없는 CLI/solver/output diagnostic은 explicit empty source field를 사용한다.

7.7 Output Failure and Atomic Finalization

Writer는 log close 성공 뒤에만 final file과 같은 directory에 implementation-private temporary HDF5 candidate를 만든다. Candidate는 metadata, model datasets, accepted-frame table, 모든 accepted-frame dataset, diagnostics를 모두 쓰고, shape, attribute, finite value, source identity, row order를 검증한다. Checked HDF5 close와 read-only reopen/self-check가 성공한 뒤에만 final <stem>_results.h5를 replace/create한다. 실패한 candidate는 제거하거나 non-authoritative implementation-private artifact로만 남긴다. Controlled failure는 incomplete final result를 노출하면 안 된다. HDF5 failure는 이미 닫힌 current-run log를 rollback하지 않는다.

8. FESA HDF5 to Reference CSV Comparison Mapping

Comparison tooling은 FESA results.h5 schema와 exact read-only Abaqus CSV artifact만 읽는다. CSV는 FESA output이 아니다. HDF5에서 추출한 deterministic CSV view는 debugging/reporting 보조물로만 둘 수 있다.

8.1 Declared Cases and Artifacts

case id	role	exact path	comparison disposition
shellnl-meshfine-s4-final	primary nonlinear input	reference/shellNL-meshfine/shellNL-meshfine.inp	required source input
shellnl-meshfine-s4-final	displacement CSV	reference/shellNL-meshfine/shellNL-meshfine displacements.csv	required blocking/warning comparison
shellnl-meshfine-s4-final	reaction CSV	reference/shellNL-meshfine/shellNL-meshfine reactions.csv	constrained nodes/components only required review
shellnl-meshfine-s4-final	stress CSV	reference/shellNL-meshfine/shellNL-meshfine stresses.csv	optional read-only inspection/order evidence only
shellnl-s4-final	companion nonlinear input	reference/shellNL/shellNL.inp	required source input
shellnl-s4-final	displacement CSV	reference/shellNL/shellNL displacements.csv	required blocking/warning comparison
shellnl-s4-final	reaction CSV	reference/shellNL/shellNL reactions.csv	constrained nodes/components only required review
shellnl-s4-final	stress CSV	reference/shellNL/shellNL stresses.csv	optional read-only inspection/order evidence only
shell-s4-linear-limit	linear control input	reference/shell/shell.inp	existing linear MITC4 contract의 required regression input
shell-s4-linear-limit	displacement CSV	reference/shell/shell displacements.csv	required regression comparison
shell-s4-linear-limit	reaction CSV	reference/shell/shell reactions.csv	optional read-only inspection only
shell-s4-linear-limit	stress CSV	reference/shell/shell stresses.csv	optional read-only inspection/order evidence only

Reference artifact file은 workflow에서 rename, rewrite, normalize, zero-clamp, repair, regenerate하지 않는다. Fine과 coarse nonlinear case는 각각 자기 input/CSV에 독립적으로 비교하며 cross-mesh row mapping이나 interpolation을 만들지 않는다.

8.2 Accepted-State and Frame Mapping

• shellnl-meshfine-s4-final과 shellnl-s4-final은 각각 accepted factor-one HDF5 frame만 비교한다. 해당 frame은 /steps/Step-1/accepted_frames에서 is_factor_one=1이고 load_factor=1.0인 unique row다. 그 frame_index가 /steps/Step-1/frames/<frame>를 선택한다.
• 두 nonlinear case의 required CSV row는 exact Frame value Increment 10: Step Time = 1.000만 가져야 하며, 이는 각 case의 accepted factor-one state로 논리 매핑한다. Required row에 다른 Frame 값이 있으면 schema mismatch다.
• shell-s4-linear-limit CSV에는 Frame column이 없으며 docs/linear-static-mitc4-shell/io.md의 existing linear MITC4 final frame /steps/Step-1/frames/0에 매핑한다.
• Trial Newton state, iteration log line, optional stress inventory row는 reference row가 아니다.

8.3 Nodal Displacement Projection

Required logical key는 다음과 같다.

(case_id, accepted_state, canonical_instance_name, source_node_label, component)

Instance PART-1-1에서 linear/coarse case는 node label 1..49, fine case는 1..729를 각각 정확히 한 번 요구한다. Instance matching은 case-insensitive로 수행하되 report에는 raw spelling을 보존한다. Row order는 identity가 아니다.

CSV column	comparison component	nonlinear HDF5 source	linear regression HDF5 source
U-U1	U1	factor-one nodal/displacement column UX	final nodal/displacement column UX
U-U2	U2	factor-one nodal/displacement column UY	final nodal/displacement column UY
U-U3	U3	factor-one nodal/displacement column UZ	final nodal/displacement column UZ
UR-UR1	UR1	factor-one nodal/displacement column URX	final nodal/displacement column URX
UR-UR2	UR2	factor-one nodal/displacement column URY	final nodal/displacement column URY
UR-UR3	UR3	factor-one nodal/displacement column URZ	final nodal/displacement column URZ

U1/U2/U3는 blocking이다. UR1/UR2/UR3는 모든 case에서 warning-only다. UR warning exceedance는 blocking verdict를 바꾸지 않는다.

8.4 Nonlinear Local Reaction Review Projection

Reaction review row는 input boundary mask로 선택한다.

• coarse shellnl-s4-final: 1,3..9,14..17,22..33 — 24 nodes;
• fine shellnl-meshfine-s4-final: 1,3..9,34..57,82..153 — 104 nodes.

승인 input에서 위 node들은 여섯 global DOF가 모두 constrained다. Comparator는 row eligibility를 CSV zero value나 row position이 아니라 /model/nodal_constraint_mask와 source node identity에서 도출한다. Translation reaction은 factor-one nodal/generalized_residual의 constrained RU1..RU3이고, rotational reaction은 constrained RPHI1..RPHI3를 먼저 선택한 뒤 accepted phi의 J_l(phi)^(-T)로 변환한 spatial physical moment다. Stored all-six-constrained rows에서는 factor-one /nodal/reaction의 대응 column과 동일해야 한다.

CSV columns	coarse family	fine family	disposition
RF-RF1, RF-RF2	coarse.local_reaction_inplane_force	fine.local_reaction_inplane_force	review-only
RF-RF3	coarse.local_reaction_transverse_force	fine.local_reaction_transverse_force	review-only
RM-RM1, RM-RM2	coarse.local_reaction_physical_moment	fine.local_reaction_physical_moment	review-only
RM-RM3	comparison projection 없음	comparison projection 없음	excluded

Raw generalized rotation-coordinate residual은 Abaqus RM CSV column과 직접 비교하지 않는다. Review-only family도 source key, schema, inventory, finite value와 모든 row/common-policy error를 보고한다. 그 precheck 또는 numerical finding은 blocking verdict를 바꾸지 않는다.

8.5 Internal Factor-One Equilibrium Projection

Internal equilibrium은 Abaqus CSV comparison이 아니다. Fine primary와 coarse companion의 각 accepted factor-one HDF5 frame에서 Section 7.5.1의 projection을 사용한다.

family id	exact HDF5 rows/components	gate
coarse.accepted_free_force_residual	75 free RU1/RU2/RU3 rows와 같은 rows의 internal/external force	NSNR-069 force channel
coarse.accepted_free_moment_residual	75 free RPHI1/RPHI2/RPHI3 rows와 같은 rows의 internal/external generalized moment	NSNR-069 moment channel
coarse.global_force_balance	factor-one /global/equilibrium FORCE_1..3	normalized <=1e-8
coarse.global_moment_balance	factor-one /global/equilibrium MOMENT_1..3	normalized <=1e-8
fine.accepted_free_force_residual	1,875 free RU1/RU2/RU3 rows와 같은 rows의 internal/external force	NSNR-069 force channel
fine.accepted_free_moment_residual	1,875 free RPHI1/RPHI2/RPHI3 rows와 같은 rows의 internal/external generalized moment	NSNR-069 moment channel
fine.global_force_balance	factor-one /global/equilibrium FORCE_1..3	normalized <=1e-8
fine.global_moment_balance	factor-one /global/equilibrium MOMENT_1..3	normalized <=1e-8

Global balance의 force scale은 applied/reaction nodal force contribution의 2-norm 합 중 큰 값, moment scale은 current-arm force moment와 spatial physical nodal moment contribution의 2-norm 합 중 큰 값이다. Force와 moment를 분리해 norm(balance_error)/scale<=1e-8을 적용한다. Scale이 exact zero이면 balance error도 exact zero일 때만 pass한다. Absolute floor, max(1,S) 또는 zero clamp는 없다. Accepted free residual은 NSNR-069의 external-channel exact-zero/ nonzero branch를 그대로 재현한다. 이 internal gate에는 docs/TOLERANCE.md, Abaqus value 또는 local reaction error를 적용하지 않는다.

Constrained reaction resultant force [3]와 moment [3]는 Section 7.5.1의 distinct review-only-summary로 함께 계산·보고한다. /global/equilibrium, constrained reaction resultant와 accepted free residual 중 어느 하나를 다른 quantity의 대체 dataset으로 쓰지 않는다.

8.6 External Comparison Families

External tolerance source는 정확히 docs/TOLERANCE.md다. 별도 absolute floor, max(1,S) clamp, row averaging, source-order matching, component calibration 또는 zero clamp는 허용하지 않는다.

family id	case	components	required row count	units / coordinates	disposition
linear.translation	shell-s4-linear-limit	U1,U2,U3 on nodes 1..49	147	length / global	blocking regression
linear.rotation	shell-s4-linear-limit	UR1,UR2,UR3 on nodes 1..49	147	dimensionless / fixed-initial global	warning-only
coarse.translation	shellnl-s4-final	U1,U2,U3 on nodes 1..49	147	length / global	blocking
coarse.rotation	shellnl-s4-final	UR1,UR2,UR3 on nodes 1..49	147	dimensionless / fixed-initial global	warning-only
coarse.local_reaction_inplane_force	shellnl-s4-final	RF1,RF2 on constrained nodes	48	force / global shell plane	review-only
coarse.local_reaction_transverse_force	shellnl-s4-final	RF3 on constrained nodes	24	force / global transverse	review-only
coarse.local_reaction_physical_moment	shellnl-s4-final	RM1,RM2 on constrained nodes	48	force*length / global spatial	review-only
fine.translation	shellnl-meshfine-s4-final	U1,U2,U3 on nodes 1..729	2,187	length / global	blocking
fine.rotation	shellnl-meshfine-s4-final	UR1,UR2,UR3 on nodes 1..729	2,187	dimensionless / fixed-initial global	warning-only
fine.local_reaction_inplane_force	shellnl-meshfine-s4-final	RF1,RF2 on constrained nodes	208	force / global shell plane	review-only
fine.local_reaction_transverse_force	shellnl-meshfine-s4-final	RF3 on constrained nodes	104	force / global transverse	review-only
fine.local_reaction_physical_moment	shellnl-meshfine-s4-final	RM1,RM2 on constrained nodes	208	force*length / global spatial	review-only

Reference-model read-only scale audit value는 다음과 같다. 이 값은 calibration 상수가 아니다.

family id	S=max(abs(reference))	0.01*S
linear.translation	2.37408203e-5	2.37408203e-7
linear.rotation	7.60725743e-6	7.60725743e-8
coarse.translation	2.37408203e-5	2.37408203e-7
coarse.rotation	7.60725743e-6	7.60725743e-8
coarse.local_reaction_inplane_force	1.91663182	1.91663182e-2
coarse.local_reaction_transverse_force	1.17769805e4	1.17769805e2
coarse.local_reaction_physical_moment	1.95418418e4	1.95418418e2
fine.translation	2.57957054e-5	2.57957054e-7
fine.rotation	6.58704994e-6	6.58704994e-8
fine.local_reaction_inplane_force	5.38827419e-1	5.38827419e-3
fine.local_reaction_transverse_force	2.78506128e3	2.78506128e1
fine.local_reaction_physical_moment	4.71557520e3	4.71557520e1

8.7 Row Prechecks

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

1. 각 case의 exact declared input과 해당 disposition에 필요한 CSV가 존재하고 readable이다.
2. Reference CSV header는 surrounding whitespace trim 뒤 필요한 column을 가진다.
3. 두 nonlinear case required row는 exact approved Frame value만 포함한다.
4. HDF5 metadata, model rows, accepted-frame table, factor-one frame, required result dataset이 문서화된 shape, component name, attributes와 finite value를 가진다.
5. Wide CSV row는 이 문서의 component mapping으로 component row로 deterministically expand한다.
6. Source wide key와 expanded component key는 unique하다. Duplicate reference 또는 HDF5 key는 affected family를 tolerance 전에 fail한다.
7. Input node inventory와 source constraint mask로 expected key set을 만든다. CSV zero value나 row position으로 reaction identity를 추론하지 않는다.
8. 각 declared external family에서 FESA와 reference projected key set은 exact equal해야 한다. Missing row와 extra row를 모두 fail한다.
9. Required HDF5/CSV value, derived scale, norm과 metric은 모두 finite여야 한다.
10. Internal free residual은 exact free mask와 force/moment channel을 보존한다. Global balance는 모든 applied source와 constrained reaction을 stable source order로 정확히 한 번 사용한다.
11. Local review row를 global resultant로 collapse하거나 대체하지 않는다. Review-only precheck/error는 deterministic review failure로 기록하지만 blocking verdict를 변경하지 않는다.
12. Warning-only precheck/tolerance failure는 deterministic warning을 만들고 blocking verdict를 변경하지 않는다. Blocking precheck failure만 전체 external comparison을 fail한다.
13. Row omission/synthesis, averaging, source-order matching, clamp, normalization 또는 artifact repair를 허용하지 않는다.

8.8 Stress CSV Disposition

Optional stress CSV identity는 다음과 같다.

(case_id, accepted_state, instance, element_label,
 element_corner_node_label, section_surface, component)

Stored stress CSV는 element-corner node row와 SPOS/SNEG section surface에서 S-S11, S-S22, S-S33, S-S12를 포함한다. reference/shell/shell stresses.csv는 사용자가 변경한 ascending element-label block 1..36 순서를 갖지만 row order는 identity가 아니다. Fine stress CSV의 element 1, SNEG, Node Label=ss 한 행은 optional excluded artifact finding으로만 기록한다. Artifact를 수정하지 않는다.

FESA HDF5는 GP1..GP4와 BOTTOM/MIDDLE/TOP에서 direct [S11,S22,S12]만 emit한다. 따라서 모든 stored stress CSV는 optional read-only inspection/order evidence only다. HDF5 numerical-comparison projection, S33 synthesis, nodal extrapolation, corner averaging, Gauss-to-corner matching 또는 element-label-order matching은 없다.

9. Validation Rules

validation area	required pass condition	failure class
CLI usage	input path 정확히 하나; 어떤 argv token에도 exact literal substring --output 없음; matching 시 path resolution/parsing/Analysis/log/HDF5 전 cli-usage stderr diagnostic 정확히 1개	usage, exit 2
keyword inventory	keyword가 supported, explicit diagnostic의 unsupported, 또는 exact ignored-with-warning allowlist 중 하나	input, exit 3
syntax	ASCII keyword/data grammar, comma fields, finite numeric tokens, continuation/include 없음	input, exit 3
nesting/cardinality	part/assembly/instance/step이 닫힘; nonlinear procedure는 정확히 하나의 NLGEOM=YES step	input, exit 3
source identity	scope 내 duplicate name/label 없음; 모든 reference resolved; instance identity unique	input, exit 3
set expansion	explicit/generated set이 deterministic expand되고 하나의 supported scope/instance에 머묾	input, exit 3
shell element	only S4/S4R; 네 개의 distinct resolved nodes; mixed element model 없음; source type metadata 보존	input/model, exit 3 또는 4
material and section	single isotropic elastic material, centered homogeneous positive-thickness shell section, element마다 정확히 하나의 assignment	input/model, exit 3 또는 4
geometry and coordinates	finite global coordinates, positive reference/current validity checks, required location마다 valid directors/triads/branches	model 또는 solver trial failure, exit 4 또는 5
boundary	DOF 1..6, resolved finite targets, factor-one absolute meaning, conflicting expanded value 없음	input, exit 3
load	resolved finite CLOAD, stable aggregation, fixed-global dead path, unsupported DLOAD/follower/distributed load 없음	input/model, exit 3 또는 4
aggregate moment	exact-zero case 또는 preprocessing 및 모든 entered trial에서 rho_M<=1e-12	model/solver, exit 4 또는 5
nonlinear static data	네 positive finite values, endpoint 1.0, fixed increment sequence with final exact factor one	input, exit 3
Newton iteration	iteration identity 1..100; iteration 100 acceptance 가능; iteration 101 없음; line search/cutback/retry/fallback 없음	solver, exit 5
convergence channels	finite-first 평가 뒤 residual force/moment는 matching external scale exact-zero이면 typed absolute 1e-3, nonzero이면 retained max(internal,external) relative 1e-2; correction translation/rotation은 기존 denominator branch; 네 channel 모두 inclusive <=이고 logical AND	solver, exit 5
nonfinite data	required residual, tangent, correction, state, load, recovery, output value가 acceptance 전 finite	solver/output, exit 5 또는 6
commit/rollback	complete converged candidate만 commit; failure는 prior committed state와 prior authoritative final HDF5 보존	solver/output, exit 5 또는 6
HDF5 schema	exact paths, shapes, attributes, schema version, row identities, finite values, accepted-frame table, diagnostics; /global/equilibrium은 applied-plus-reaction balance error이고 accepted free residual/constrained reaction resultant와 분리됨; final replace는 log close success 뒤에만 허용	output, exit 6
equilibrium projection	accepted free rows는 generalized residual과 exact free mask, constrained reaction은 mask-before-spatial-conversion, global balance는 applied plus constrained reaction/current arm/origin [0,0,0]; factor-one global force와 moment는 각각 dimension-separated normalized <=1e-8; 세 quantity가 같은 accepted state를 공유하되 서로 대체되지 않음	solver/output/reference internal gate
log	UTF-8 no BOM, LF, TAB-separated fixed label=value schema; entered Newton iteration마다 record 하나; no per-iteration stderr duplication; no-Newton procedure는 zero-byte empty log; open/write/flush/close fail-closed	output, exit 6
reference rows	fine primary/coarse companion/linear-control exact artifacts, headers, row keys, component keys, finite values, factor-one frame mapping과 disposition별 precheck	reference precheck
tolerance	external family에만 exact docs/TOLERANCE.md row/RMS policy 적용; U blocking, UR warning-only, local RF/RM review-only 보존; internal global balance/free residual gate와 혼합 금지	reference/internal verification

Downstream test가 다뤄야 하는 approved diagnostic code는 다음을 포함한다.

code	class	meaning
cli-usage	usage/2	argv token이 exact literal substring --output을 포함하며 pre-input/pre-log/pre-output failure 하나를 stderr에 기록
unrecognized-option	usage/2	--output substring을 포함하지 않는 다른 unsupported option
malformed-keyword	input/3	keyword 또는 parameter grammar invalid
invalid-keyword-location	input/3	keyword가 approved scope 밖에 위치
invalid-keyword-parameter	input/3	parameter missing, duplicate, empty 또는 subset 밖
unsupported-keyword	input/3	*INCLUDE 포함 approved subset 밖 keyword
unsupported-distributed-load	input/3	*DLOAD, pressure, gravity, body, edge, follower load 요청
duplicate-entity	input/3	source identity가 scope 안에서 duplicate
unresolved-reference	input/3	connectivity, set, instance, section, material, load, boundary target dangling
unsupported-element-formulation	input/3	shell feature에서 source element type이 S4 또는 S4R가 아님
unsupported-mixed-element-model	input/3	shell과 non-shell product semantics 혼합
invalid-shell-connectivity	input/3	shell connectivity arity, duplicate node 또는 resolved node identity invalid
unsupported-shell-section-option	input/3	composite/layer/offset/orientation/variable-thickness section 의미 등장
invalid-shell-material	model/4	material value가 finite E,nu bound 위반
invalid-shell-thickness	model/4	shell thickness nonfinite 또는 nonpositive
invalid-shell-geometry	model/4	shell geometry, reference Jacobian 또는 topology invalid
opposed-incident-normal	model/4	averaging 전 incident normal pair가 nonpositive
invalid-shell-director	model/4	nodal/interpolated director, triad 또는 branch validity 실패
invalid-shell-jacobian	model/4	required Gauss/tying/center/recovery point의 basis/Jacobian invalid
unsupported-drilling-load	model/4 또는 solver/5	aggregate nodal moment가 current-director admissibility 위반
invalid-nonlinear-static-data	input/3	*STATIC row arity, finite/positive check 또는 endpoint-one identity 실패
unsupported-analysis-procedure	input/3	supported nonlinear static source step으로 매핑되지 않음
nonfinite-newton-data	solver/5	required residual, tangent, correction 또는 trial state nonfinite
tangent-factorization-failed	solver/5	entered iteration의 fresh tangent factorization 실패
correction-solve-failed	solver/5	fresh Newton correction solve 실패
nonlinear-nonconvergence	solver/5	iteration 100 완료 후 네 convergence channel이 모두 통과하지 않음
invalid-accepted-state	solver/5	converged candidate recovery/state identity가 commit 전 실패
log-output-failure	output/6	required live log create/open/truncate, write, flush 또는 close 실패
output-busy	output/6	same derived pair single-writer lock을 획득하지 못했거나 lock path collision 발생
hdf5-output-failure	output/6	candidate HDF5 write, schema validation 또는 atomic finalization 실패

10. Open Issues and Downstream Handoff

Open issues blocking Implementation Planning: 없음.

Downstream handoff to Implementation Planning Agent through Coordinator:

• Public CLI/output naming migration을 보존한다: fesa.exe <model.inp>, lexical sibling <stem>_results.h5, <stem>_log.txt, 그리고 exact literal substring --output을 포함하는 모든 argv token의 pre-input/pre-log/pre-output exit 2와 정확히 하나의 cli-usage stderr diagnostic.
• Supported/unsupported/ignored keyword row와 nonlinear *STATIC rule을 parser acceptance/rejection test로 변환한다.
• Stored reference grammar인 *Output, field, variable=PRESELECT와 *Output, history, variable=PRESELECT를 duplicate/extra parameter 없이 ignored-with-warning으로 수용하고, output request가 FESA output을 바꾸지 못함을 test한다.
• NLGEOM=YES가 nonlinear procedure를 선택하고 shell NLGEOM=NO case가 기존 linear MITC4 contract의 regression으로 남는지 test한다.
• HDF5 schema version 1을 위 accepted-frame schema 그대로 구현한다. Factor-zero non-frame handling, unique factor-one frame selection, triad/director projection, no compression/chunking, no trial-state HDF5 history를 포함한다. /global/equilibrium path/shape는 유지하되 authoritative meaning을 applied-plus-reaction balance error로 검증한다.
• AUDIT-001을 별도 test로 닫는다. Accepted free residual은 generalized residual/internal/external force와 exact free mask, constrained reaction resultant는 mask-before-J_l(phi)^(-T)와 accepted current arm, global balance는 applied plus constrained reaction을 사용한다. Nonzero prescribed translation/rotation case에서도 initial arm, raw rotational covector 또는 raw full-residual sum을 세 quantity의 공통 substitute로 쓰지 않는다.
• 비대칭 lifecycle을 보존한다. Log는 usage validation, lexical path derivation, single-writer lock 뒤 live current-run audit이고, log create/open/truncate는 Analysis 전 abort, write/flush는 즉시 abort, close failure는 HDF5 commit을 block한다. HDF5 final은 log close와 candidate self-check 성공 뒤에만 replace하며 failure는 prior valid final과 current log를 손상하지 않는다.
• Newton log parser/schema test는 UTF-8 no BOM, LF, physical TAB-separated fixed label=value 39-field order, finite round-trip numerics, escaping, completed-gate four-channel metrics, residual matching-external-scale exact-zero/nonzero branch와 retained nonzero-scale denominator, typed thresholds, four-channel AND, early-failure not-evaluated(reason), no-Newton zero-byte log, zero per-iteration stderr duplication, flush-before-next/return을 포함한다.
• Fine primary, coarse companion과 linear control의 exact CSV path, trimmed header, 두 nonlinear case의 exact factor-one Frame, source node/component identity, constrained reaction mask, missing/extra/duplicate row와 nonfinite value를 tolerance 전에 precheck한다. Row order를 identity로 쓰지 않는다.
• External declared family에는 docs/TOLERANCE.md만 적용한다. U1/U2/U3는 blocking, UR1/UR2/UR3는 warning-only, local RF1/RF2/RF3와 spatial physical RM1/RM2는 review-only다. Local RM3와 모든 stress CSV value는 제외한다. Review-only row의 schema/inventory/error report를 생략하거나 blocking으로 되돌리지 않는다.
• Fine/coarse factor-one global force/moment balance는 dimension-separated normalized <=1e-8, accepted free force/moment residual은 NSNR-069으로 blocking 검증한다. 이 internal gate에 Abaqus CSV나 docs/TOLERANCE.md scale을 사용하지 않는다. Constrained reaction resultant는 distinct review-only summary로 보고한다.
• Optional stress CSV는 read-only inventory/order evidence only로 유지한다. Nodal stress extrapolation, corner averaging, S33 synthesis, element-label-order matching을 추가하지 않는다.
• Final HDF5 projection, parser diagnostics, schema tests, reference comparison tests, log lifecycle tests는 Coordinator를 통해 전달한다. 이 문서만으로 parser, C++ API, reference artifact, comparison-result, physics, release 변경을 승인하지 않는다.