Define coupled harmonic convergence screen and evidence controls

experiments/COUPLED_CONVERGENCE_STUDY_2026-09-19.md

@@ -0,0 +1,43 @@
+# Coupled harmonic-surface convergence study
+
+The user has deferred positivity enforcement. This study keeps density an
+independent Q2 field and retains the simultaneous all-m degree-four harmonic
+surface/interior system. The primary milestones are useful convergence at
+higher index and angular momentum, and both enthalpy-pressure virials below
+1e-5. Negative-density measurements remain diagnostic, not acceptance repairs.
+
+Base revision: `ef76e0c`. Work is isolated on
+`research/coupled-convergence-study-20260919`, with separate
+`research/linear-coupling-study-20260919` and
+`research/model-slices-20260919` branches for independent implementations.
+The original programming checkout is unchanged.
+
+First screen: n=2,J=0; n=3,J=0 at forcing tolerances 0.03 and 0.003;
+n=1,J=0.1; n=1.5,J=0.1. All use the same Q2 density, Q3 enthalpy and
+displacement, RT2/Q2 gravity, Q4 geometry, reference mesh, normalization,
+default inverse, 12-update budget, restart 160, and 300-iteration linear
+budget. Only n=3 includes the existing central phase condition. This tests
+whether a tenfold more accurate direction changes the n=3 trajectory, but
+it is not a same-state preconditioner comparison. Capture updates 0,3,7
+for subsequent controlled probes. No input J is identified with a calibrated
+fraction of critical rotation.
+
+Follow-up decisions depend on this screen and source review: frozen-state
+preconditioner/forcing comparisons; small coupled surface/border corrections;
+accepted-state continuation with checked field/coordinate transfer. Linear
+claims require independently applied full-J residuals; nonlinear claims use
+common stopping thresholds plus physical diagnostics, not residual alone.
+Report scalar-border forcing separately from the unbordered equations.
+
+The slice feature will evaluate physical geometry and independent fields,
+show the material surface at true scale, retain signed density, and separate
+outside-domain points from valid interior samples. It must not silently turn a
+reference-coordinate cut into a physical planar cut.
+
+Builds and expensive numerical cases run serially. The existing campaign
+runner records exact source, binary, mesh, arguments, saved states and output
+hashes. Initial evidence directory:
+`../../diagnostics/coupled_convergence_2026-09-19/screen_v1`.
+
+Results and any adaptive extensions will be recorded below before finalizing
+the study. Defaults and the physics-facing API are unchanged.

experiments/convergence_screen_cases_2026-09-19.json

@@ -0,0 +1,150 @@
+[
+  {
+    "id": "n2_J0",
+    "arguments": [
+      "--index",
+      "2",
+      "--angular-momentum",
+      "0",
+      "--surface-prescription",
+      "harmonics",
+      "--surface-degree",
+      "4",
+      "--max-newton",
+      "12",
+      "--restart",
+      "160",
+      "--max-linear",
+      "300",
+      "--linear-tol",
+      "0.03",
+      "--rtol",
+      "1e-8",
+      "--atol",
+      "0",
+      "--strategy",
+      "baseline",
+      "--capture-iterations",
+      "0,3,7",
+      "--no-central"
+    ]
+  },
+  {
+    "id": "n3_J0_control",
+    "arguments": [
+      "--index",
+      "3",
+      "--angular-momentum",
+      "0",
+      "--surface-prescription",
+      "harmonics",
+      "--surface-degree",
+      "4",
+      "--max-newton",
+      "12",
+      "--restart",
+      "160",
+      "--max-linear",
+      "300",
+      "--linear-tol",
+      "0.03",
+      "--rtol",
+      "1e-8",
+      "--atol",
+      "0",
+      "--strategy",
+      "baseline",
+      "--capture-iterations",
+      "0,3,7"
+    ]
+  },
+  {
+    "id": "n3_J0_tight",
+    "arguments": [
+      "--index",
+      "3",
+      "--angular-momentum",
+      "0",
+      "--surface-prescription",
+      "harmonics",
+      "--surface-degree",
+      "4",
+      "--max-newton",
+      "12",
+      "--restart",
+      "160",
+      "--max-linear",
+      "300",
+      "--linear-tol",
+      "0.003",
+      "--rtol",
+      "1e-8",
+      "--atol",
+      "0",
+      "--strategy",
+      "baseline",
+      "--capture-iterations",
+      "0,3,7"
+    ]
+  },
+  {
+    "id": "n1_J0p1",
+    "arguments": [
+      "--index",
+      "1",
+      "--angular-momentum",
+      "0.1",
+      "--surface-prescription",
+      "harmonics",
+      "--surface-degree",
+      "4",
+      "--max-newton",
+      "12",
+      "--restart",
+      "160",
+      "--max-linear",
+      "300",
+      "--linear-tol",
+      "0.03",
+      "--rtol",
+      "1e-8",
+      "--atol",
+      "0",
+      "--strategy",
+      "baseline",
+      "--capture-iterations",
+      "0,3,7",
+      "--no-central"
+    ]
+  },
+  {
+    "id": "n1p5_J0p1",
+    "arguments": [
+      "--index",
+      "1.5",
+      "--angular-momentum",
+      "0.1",
+      "--surface-prescription",
+      "harmonics",
+      "--surface-degree",
+      "4",
+      "--max-newton",
+      "12",
+      "--restart",
+      "160",
+      "--max-linear",
+      "300",
+      "--linear-tol",
+      "0.03",
+      "--rtol",
+      "1e-8",
+      "--atol",
+      "0",
+      "--strategy",
+      "baseline",
+      "--capture-iterations",
+      "0,3,7",
+      "--no-central"
+    ]
+  }
+]