# Nonlinear Static Newton-Raphson Implementation Report

## Metadata

| key | value |
| --- | --- |
| feature_id | `nonlinear-static-newton-raphson` |
| phase step | `12: execution-closure-and-evidence-docs` |
| owner_agent | `implementation-agent` |
| evidence date | `2026-08-28` |
| repository HEAD before this Step's documentation edits | `d275e844f27107cfab52309025e259f2156345d2` |
| classification | `pass-for-physics-evaluation` |

## Freshness audit (RED)

Before any build or reference command, `NSNR-EVID-001..007` failed as expected.
`implementation-report.md`, `build-test.md`, and `reference-comparison.md` were absent. The
global documents still advertised `--output`, only the prior linear output path, and did not state
the approved nonlinear current-arm/reaction and fine/coarse reference dispositions. This was an
evidence freshness failure, not a solver failure. No report was created until the fresh commands
below completed.

## Approved inputs and preserved Step history

The consumed upstream document SHA-256 values were: requirements
`89C1AB5F1BEDB7C5F6AD0726ED62F0982181EA8746EDE4661183FD3D18A2408E`, research
`4F63D23E03D1A68E5F8563B678FDD6F761F9558165778EF0433133EFAD303570`, formulation
`878028F7B8EC1B91DA9BF00AF78825F50EB0B71046E840A0EEA595AFFD5E14B9`, numerical review
`C00994EF4BB23A237547459E157EE5BDA96B28CAF08F712CD31A8E0ABBF62D2C`, reference model
`B2E6845AB59A32F78261B7A47506C27F7BF4B61401B34BC5DE3DAD4F03D6ADDA`, I/O
`ED23274F4F15F7D1DFF886FA8158961362C75960990271D24A5FD010A8D51FD9`, implementation plan
`CA3EF7D2E95AA1F15757CD138CEF67E06E51195F59FB8DBE676E5772CC1D6C2C`, and corrections
`4DC996E3D4CA2D515D19E5D244C3A112AF0C9429335698E03089B77B5E79346A`.

Steps 0--10 remain unchanged: derived output/log lease; NLGEOM Domain controls; finite rotations;
nonlinear MITC4 kinematics/recovery; residual/tangent; load/BC/convergence gates; tangent solver;
iteration log; transactional state; nonlinear HDF5 v1; and prepared parse-once dispatch/finalization.

## Step 11 RED to GREEN evidence

The preserved Step 11 transcript SHA-256 is
`292FE06B7F97B1CBE267A36D875342B300E82486B76BDCBCD31EE2192A87ACE3`.
Its RED evidence covered: initial-arm/raw rotation balance (`NSNR-PROC-019`), obsolete
`location=global-origin` (`NSNR-HDF5-014`), missing fine inventory (`NSNR-REF-020`), blocking
local RF/RM (`NSNR-REF-021`), obsolete `1e-10` balance rejection (`NSNR-REF-022`), pre-tolerance
row rejection (`NSNR-REF-023`), inclusive `1e-8` boundary (`NSNR-REF-024`), and exact-zero scale
(`NSNR-REF-025`).

The minimal GREEN slice was limited to the nonlinear procedure current-arm/spatial balance
projection, HDF5 location metadata/self-check, and test-private reference comparator/case
inventory. The relevant production files were `nonlinear_static_procedure.cpp`,
`nonlinear_hdf5_results_writer.cpp`, and `hdf5_self_check.cpp`; test changes remained in the
procedure, writer, convergence/log, and reference-comparator tests. This Step made no C++, test,
CMake, Harness, tolerance, or reference-artifact change.

Fresh VERIFY reran the preserved controls. The focused `NonlinearStaticProcedure` and
`NonlinearHdf5ResultsWriter` command passed 7/7, including
`NonzeroPrescribedMotionWritesCurrentArmSpatialAppliedPlusReactionBalance` and
`WritesSchemaV1GlobalBalanceErrorLocation`. The reference command passed the inclusive and
exact-zero global gate tests. This closes `AUDIT-001`: the tests exercise nonzero prescribed
translation and rotation, `x=X+u`, component-mask-before-conversion, independently converted
applied and constrained rotation covectors, and `location=global-balance-error`.

## Requirement and test traceability

| evidence | fresh result |
| --- | --- |
| `NSNR-CTRL-018..021` convergence controls | 6/6 `NonlinearConvergence.*` passed |
| `NSNR-LOG-012` iteration-log contract | 8/8 `NewtonIterationLog.*` passed |
| `NSNR-PROC-019` current-arm balance | passed in focused 7-test procedure/writer run |
| `NSNR-HDF5-014` v1 equilibrium location | passed in focused 7-test procedure/writer run |
| `NSNR-REF-020..025` portfolio, dispositions, prechecks, 1e-8 and zero-scale | 9/9 `NonlinearStaticReference.*` passed twice and in full CTest |
| blocking external/internal final gate | all 302 CTest tests passed; detailed metrics are in `reference-comparison.md` |

## Handoff and open issues

Implementation-owned classification is `pass-for-physics-evaluation`. The only numerical
differences retained are six deterministic local RF/RM review-only findings; they do not alter
the blocking verdict. No warning-only UR family failed. This report does not claim physics or
release readiness, and numerical agreement does not assert Abaqus S4 internal formulation
equivalence.

No Step 12 production behavior changed. Reference inputs and CSV files were read-only and their
pre/post inventory, byte sizes, timestamps, and SHA-256 values were identical.