Compare commits

..

161 Commits

Author SHA1 Message Date
e7e53ce682 Consolidate numerical research and preserve a reproducible handoff
Document the baseline, hypotheses, measured results, failed approaches,
current policy defaults, and remaining rotating n=3 and virial limitations.
Include the authoritative LaTeX report, Pandoc-generated Markdown, compiled
PDF, source provenance, branch decisions, and consolidation validation.

Organize raw results and miscellaneous artifacts under working/ without
deleting them; version the directory guide, relocation hashes, archive
verifier, and report build/conversion checks. Keep build caches at their
original paths and clearly distinguish retained binaries from the validated
research build. Preserve experimental policies without promoting failed
trials to defaults.
2026-09-20 09:10:27 -04:00
b1fe359760 Document stellar support contract for log density 2026-09-20 07:50:43 -04:00
9dc752068e Document MESA log density and atmosphere analogy 2026-09-20 07:50:43 -04:00
91334b5f69 Clarify finite precision positivity of log density 2026-09-20 07:50:43 -04:00
8fbfc4f191 Clarify local log-matrix scope and independent pressure admissibility 2026-09-20 07:50:43 -04:00
a34e67bd4b Clarify scope of coefficient positivity in log assessment 2026-09-20 07:50:43 -04:00
549b1a761d Assess independent log density coordinates and exact vacuum 2026-09-20 07:50:43 -04:00
6950dc68af Preserve existing quadrature interface formatting during consolidation 2026-09-20 07:49:56 -04:00
d7acb0d399 Record coupled convergence results, virial limitations and validated model slices 2026-09-19 17:09:32 -04:00
2c6523b1ce Preserve slice titles and colorbar labels in saved figure bounds 2026-09-19 17:06:26 -04:00
07799bca34 Space slice colorbar labels in normalized color coordinates 2026-09-19 16:26:13 -04:00
1ed03f5683 Specify matched live field-feedback trial for rotating n3 family 2026-09-19 16:10:38 -04:00
38c7184b5c Add gravity-only attribution for rotating higher-index gain 2026-09-19 16:01:29 -04:00
2aabfc4d35 Plot audited frozen linear histories and checked endpoint gates 2026-09-19 15:52:50 -04:00
e78af98e2b Specify matched n3 gravity-only ablation before attribution 2026-09-19 15:44:52 -04:00
df86e84b76 Record audited nonlinear controls and interior diagnostics 2026-09-19 15:29:16 -04:00
476118cfaa Show local restart progress alongside full convergence threshold 2026-09-19 15:11:43 -04:00
f2c1a369a6 Specify tight frozen-direction trials after gravity-path stall 2026-09-19 15:06:17 -04:00
a458af0a7a Plot audited paired Newton convergence with actual thresholds 2026-09-19 15:00:43 -04:00
d62487f2d1 Add field-feedback controls and document the actual material factorization 2026-09-19 14:48:26 -04:00
cc22383562 Target the combined rotation stall and its physical slice refinement 2026-09-19 14:27:04 -04:00
99eb86fedc Audit frozen slice replays and specify same-state refinement controls 2026-09-19 14:19:59 -04:00
a1df4d9f84 Record control outcomes and specify a matched rotating-state benchmark 2026-09-19 14:16:35 -04:00
6614a5bdf6 Compare physical slice refinement with shared scalar rendering 2026-09-19 14:16:06 -04:00
5f8458c9cc Audit retained convergence evidence and distinguish compatible physical families 2026-09-19 14:07:40 -04:00
f9355bdc8f Document curved slice conformity and refinement limits 2026-09-19 14:04:24 -04:00
1d746b028e Add explicit mass-compatible rotating n3 physical-family control 2026-09-19 13:58:08 -04:00
6d423cba46 Specify gravity-path and matched Schur experiments from the measured n2 stall 2026-09-19 13:56:36 -04:00
9bac57a1df Add physical-plane FEM model slice diagnostics and plots 2026-09-19 13:47:41 -04:00
7793fd9111 Keep restart input provenance separate from destination output records 2026-09-19 13:46:33 -04:00
522a2cfc02 Test normalized unbordered adapter and report its storage scope 2026-09-19 13:46:33 -04:00
2398118b34 Add frozen surface and scalar Schur preconditioner experiment 2026-09-19 13:44:14 -04:00
53faac1cd2 Add checked harmonic snapshot continuation and matched linear trial diagnostics 2026-09-19 13:43:49 -04:00
77130fa603 Define coupled harmonic convergence screen and evidence controls 2026-09-19 13:31:11 -04:00
ef76e0c786 Record density-order study, convergence limits, and log-density implications 2026-09-19 13:12:41 -04:00
c0a496e9d6 Preserve all trial preparation and disposition counts in reports 2026-09-19 12:46:04 -04:00
e054c7464c Check non-density layouts across separately audited orders 2026-09-19 12:16:56 -04:00
903615f10f Separate uncertain density observations from plotted trends 2026-09-19 12:06:37 -04:00
cd71f374f0 Audit trial rejection stages and expose line-search obstruction counts 2026-09-19 11:21:26 -04:00
54102b4f3c Retain unbordered residual and central-border diagnostics in summaries 2026-09-19 11:15:28 -04:00
d34ae09fc4 Audit actual stellar closure quadrature rules and support 2026-09-19 11:09:06 -04:00
c0e8551cbd Summarize audited density-order results and scientific comparisons 2026-09-19 11:04:49 -04:00
241621ce86 Report sliced moment quadrature differences without identity gates 2026-09-19 10:53:34 -04:00
4ff1b10693 Separate surface and interval-witness enthalpy observations 2026-09-19 10:52:33 -04:00
e21f723fdf Exercise rectangular gravity coupling and normalization in order-study checks 2026-09-19 10:51:44 -04:00
8c1cc31874 Audit density-order evidence and distinguish observation from certification 2026-09-19 10:49:37 -04:00
2ca6890a18 Add controlled density-order projection and coupled-solve observations 2026-09-19 10:48:14 -04:00
dd955abca5 Cover both density mass and EOS source in closure quadrature 2026-09-19 10:47:58 -04:00
d6554cae6b Reuse field and closure validation in a focused density-order test target 2026-09-19 10:26:54 -04:00
c7383e12ff Make density approximation order an independent compile-time choice 2026-09-19 10:25:55 -04:00
7ed4d232d0 Record negative density mechanism, interval audits, and resolution options 2026-09-19 10:16:03 -04:00
d1a594808f Integrate frozen negative density over polynomial root intervals 2026-09-19 10:06:10 -04:00
9c22934d52 Add frozen negative density localization and independent EOS projection diagnostics 2026-09-19 09:46:52 -04:00
1148c099e3 Record coupled harmonic surface validation and preconditioner baseline 2026-09-19 09:22:36 -04:00
7b0eb8d92d Add native spherical harmonic surface coordinates to coupled equilibrium 2026-09-19 08:51:42 -04:00
2171b8b76a Record reduced surface study and audit frozen seed chains 2026-09-18 16:14:34 -04:00
21cdbda224 Add frozen smooth-surface restriction study with physical dual maps 2026-09-18 15:45:05 -04:00
6ceda61bdd Preserve completed weak-response study while retaining Q3 baseline 2026-09-18 14:27:15 -04:00
211be17190 Record audited shape-field compensation and cubic surface structure before order trial 2026-09-18 13:45:27 -04:00
2c4a5e05a6 Audit physical compensation artifacts and verify quartic affine displacement representation 2026-09-18 13:31:14 -04:00
d79db9445b Add frozen physical shape-field compensation diagnostics and controlled order study plan 2026-09-18 13:20:03 -04:00
db854c0f7c Record audited damping and eligibility results through six Newton updates 2026-09-18 12:13:53 -04:00
18762298c1 Record independent campaign clocks and matched Newton follow-up cases 2026-09-18 11:40:36 -04:00
25816d4328 Match frozen trial metric validation to production backtracking 2026-09-18 10:49:44 -04:00
422c46bcbf Add bounded coupled damping and prediction-based attempt selection 2026-09-18 10:45:45 -04:00
46249d0758 Record coupled correction benefit cost and nonlinear curvature limits 2026-09-18 10:21:19 -04:00
0c926f40df Generate matched scalar controls for coupled trial attribution 2026-09-18 10:14:09 -04:00
5aa48dcf80 Keep coupled evidence audit linear in state size and repeat raw timing 2026-09-18 10:07:46 -04:00
2d0d32b886 Audit coupled trial artifacts and physical replay independently 2026-09-18 09:52:30 -04:00
0d87b8b919 Add bounded fully coupled second-order trial correction and frozen screen 2026-09-18 09:41:00 -04:00
2944dd5019 Record audited nonlinear obstruction findings and next experiment 2026-09-18 09:10:28 -04:00
db93bf73b6 Record constrained two-direction algebraic control 2026-09-18 08:59:52 -04:00
0b0ab9cd18 Plot audited nonlinear paths and matched direction controls 2026-09-18 08:47:19 -04:00
b8d1c6a5ab Independently audit frozen nonlinear path vectors and provenance 2026-09-18 08:37:54 -04:00
ba057b3983 Add frozen nonlinear path and mixed curvature investigation 2026-09-18 08:26:51 -04:00
690c8ddc9a Clarify frozen endpoint scope and gravity target interpretation 2026-09-18 08:19:26 -04:00
1d98fff171 Record frozen late-state probe and matched direction controls 2026-09-18 08:16:27 -04:00
d82540a13c Record preconditioner conclusions and define next nonlinear obstruction investigation 2026-09-18 08:14:07 -04:00
dc1da62b2c Finalize preconditioner measurements, physical limits, and reproduction record 2026-09-17 18:17:54 -04:00
83afd824ef Record rotating linear gate success and bounded nonlinear follow-through 2026-09-17 18:09:41 -04:00
5298d88ed0 Document higher-index nonlinear limits after Schur refinement 2026-09-17 18:03:56 -04:00
031b02f3da docs: clarify preconditioner experiment results and timing 2026-09-17 17:53:07 -04:00
30a99435a8 Document equal-accuracy gain and preserved virial regression 2026-09-17 17:51:12 -04:00
7b4f674ed5 Enable combined stellar LDU gravity Schur Newton experiment 2026-09-17 17:36:48 -04:00
107c66b192 Record complementary rotating coupling confirmation 2026-09-17 17:35:21 -04:00
bed1893cfb Record measured preconditioner screen and validation limits 2026-09-17 17:18:42 -04:00
87569c03dd Record Newton and virial regressions for consistent gravity preconditioning 2026-09-17 17:11:29 -04:00
74d94bd275 Record equal-accuracy gravity Schur confirmation cases 2026-09-17 17:10:15 -04:00
c2bd8fc9c9 Document verified Schur coverage and MPI fixture limitation 2026-09-17 17:06:26 -04:00
fcb7833844 Wire typed experimental preconditioners into Newton diagnostics 2026-09-17 17:05:44 -04:00
dc8d4b0501 Compile and verify radial coarse basis through existing FEM surface map 2026-09-17 16:55:20 -04:00
b3bd244024 Record matched preconditioner controls and candidate rationale 2026-09-17 16:48:14 -04:00
52474587dd Guard coarse exactness diagnostics and report complete setup work 2026-09-17 16:45:55 -04:00
48cb8c527f Validate coarse preconditioner evidence and fallback comparisons 2026-09-17 16:42:22 -04:00
370dbbf73b Compare cached coupling and checked coarse preconditioner variants 2026-09-17 16:37:32 -04:00
995d49b813 Prototype deterministic coupled shape coarse inverse for frozen benchmarks 2026-09-17 16:35:54 -04:00
fac147774a Reuse prepared gravity force for stellar cross preconditioning 2026-09-17 16:29:39 -04:00
7f7d7b1cfa Recognize zero-sweep gravity benchmark controls 2026-09-17 16:28:42 -04:00
30b94b75b3 Aggregate gravity baseline equivalence assertions 2026-09-17 16:25:39 -04:00
61a44fc853 Validate preconditioner evidence before claiming speedups 2026-09-17 16:24:42 -04:00
bc3c39dcfd Benchmark isolated and coupled gravity Schur refinements 2026-09-17 16:23:13 -04:00
b18f41f88f Add fixed-work mass-consistent gravity Schur refinement 2026-09-17 16:19:51 -04:00
018fc1c992 Record reproducible hard-state preconditioner screen cases 2026-09-17 16:17:21 -04:00
e557e6b481 Add matched frozen-state preconditioner benchmarks 2026-09-17 16:16:46 -04:00
10adf7ec37 Record numerical strategy validation and remaining convergence limits 2026-09-17 12:40:48 -04:00
c82e68dd7e Record gravity relift work before descent rejection 2026-09-17 12:18:11 -04:00
b9e6794999 Update numerical strategy documentation with verified evidence 2026-09-17 12:10:27 -04:00
8b307b43d3 Retain iteration snapshots in numerical strategy campaigns 2026-09-17 11:53:12 -04:00
a2871e11e2 Clear unavailable gravity measurements before each attempt 2026-09-17 11:01:45 -04:00
7e1ab69fcd Add read-only polynomial endpoint certification mode 2026-09-17 10:56:18 -04:00
b21fa40249 Exercise combined polynomial and reduced gravity model steps 2026-09-17 10:29:23 -04:00
01169861c6 Validate compact gravity application probe records 2026-09-17 10:29:23 -04:00
0bf260f04d Record gravity arithmetic diagnostics and bounded model campaign 2026-09-17 10:22:25 -04:00
6a91cfaf06 Scale prepared gravity consistency by uncancelled field contributions 2026-09-17 10:21:49 -04:00
f77c7d2b29 Compare compact gravity applications against full FEM blocks 2026-09-17 10:19:17 -04:00
3307191f2d Keep unrecognized physical runtimes on gravity fallback 2026-09-17 10:17:51 -04:00
071417f0c1 Reject unsupported pressure traces before polynomial state certification 2026-09-17 10:16:21 -04:00
6e812aeca2 Apply canonical gravity blocks without full root work 2026-09-17 10:16:21 -04:00
b7ea1bdcf8 Resolve reduced derivative trend with a recorded four-step diagnostic grid 2026-09-17 10:10:00 -04:00
2e31917269 Distinguish strategy failures and expose the actual trial tangent 2026-09-17 10:09:22 -04:00
5f3eb0b18c Mark unvisited enthalpy repair checks as unresolved 2026-09-17 10:07:33 -04:00
6b10e68ed3 Use nondeprecated subnormal prerequisite for C++23 certificates 2026-09-17 10:07:33 -04:00
485e802453 Make zero-correction strategy fixture independent of equality stopping 2026-09-17 10:07:33 -04:00
4ae2f3f134 Handle null reduced actions with an absolute derivative floor 2026-09-17 09:50:13 -04:00
c393847c6f Integrate typed Newton strategies with checked trial gravity and feasibility 2026-09-17 09:45:05 -04:00
a7d646d049 Check frozen numerical strategies without conflating incomplete evidence with success 2026-09-17 09:44:58 -04:00
237485de51 Expose cached gravity target for prepared trial verification 2026-09-17 09:40:15 -04:00
5e03188816 Test reduced Newton equivalence within the intended root basin 2026-09-17 09:39:04 -04:00
fc944c1bfe Enforce floating arithmetic prerequisites for polynomial certificates 2026-09-17 09:36:58 -04:00
4418b25d45 Preserve nonfinite input rejection at feasible-repair application boundary 2026-09-17 09:36:58 -04:00
97204a3253 Add frozen polynomial positivity probes and tighten certificate diagnostics 2026-09-17 09:36:58 -04:00
dfba40b1f5 Exercise typed stellar numerical strategies and rollback contracts 2026-09-17 09:36:57 -04:00
a7f080f265 Probe FEM gravity strategies and make reduced contracts collective 2026-09-17 09:36:57 -04:00
9e0e1bc42a Integrate polynomial feasibility with typed stellar enthalpy strategy 2026-09-17 09:29:41 -04:00
6628e237d3 Add prepared Schur gravity reduction and contract tests 2026-09-17 09:27:55 -04:00
2fa83db8ab Add prepared gravity subsystem and second-order trial correction 2026-09-17 09:27:55 -04:00
2c084b1c62 Add certified polynomial enthalpy bounds and feasible direction repair 2026-09-17 09:23:54 -04:00
7a07caeee3 experiment: record pressure positivity and shape curvature evidence 2026-09-17 08:55:55 -04:00
4280c532e3 Export enthalpy nodal values on limiting diagnostic elements 2026-09-17 08:41:14 -04:00
9c975422c1 experiment: inspect surface carrier and isolate closure bound crossing 2026-09-17 08:35:49 -04:00
b1dc2acf35 Add preparation-free surface carrier trace diagnostics 2026-09-17 08:35:11 -04:00
9e1b65dbde experiment: replay captured candidates and run focused frozen probes 2026-09-17 08:18:09 -04:00
c10725bece experiment: split frozen operator curvature into shape and field contributions 2026-09-17 08:18:09 -04:00
6753cc5ddc experiment: localize pressure preparation admissibility boundaries 2026-09-17 08:16:37 -04:00
fd08f7b0e9 experiment: capture frozen live Newton trials without changing solver policy 2026-09-17 08:06:37 -04:00
95d9fbafe8 docs: finalize controlled solver campaign and transfer limits 2026-09-16 16:04:49 -04:00
5714a9b222 docs: distinguish conservative screening from virial milestone 2026-09-16 16:02:39 -04:00
9e0ffaf1fe docs: record nonrotating larger-window validation 2026-09-16 16:02:39 -04:00
0848590377 docs: record combined optional-density validation 2026-09-16 16:02:39 -04:00
c88baa19c3 Add a stronger-rotation transfer check for the combined solver 2026-09-16 15:47:23 -04:00
2eab110bef Document matched Krylov safeguard results and limitations 2026-09-16 15:47:15 -04:00
b3a752b16b Record controlled numerical outcomes and remaining operator questions 2026-09-16 15:43:38 -04:00
da38801b31 Define matched live controls for the Krylov safeguard 2026-09-16 15:43:34 -04:00
61174cf192 Safeguard reused FGMRES guesses against the current true residual 2026-09-16 15:43:34 -04:00
21b2c2b38e Define the nonrotating combined-example validation case 2026-09-16 15:20:01 -04:00
5f83bcba74 Use the validated wider Krylov window in the stellar example 2026-09-16 15:18:46 -04:00
4ec1db230f Record matched central-constraint control results 2026-09-16 15:18:46 -04:00
a1d7d4e679 Keep central density as seed data in the n1 sandbox 2026-09-16 15:18:46 -04:00
0470e3b2a1 Gate saved models on solver convergence and the virial milestone 2026-09-16 15:17:38 -04:00
9bd4af6996 Record reproducible plateau campaigns and selected-direction probes 2026-09-16 14:42:41 -04:00
80cc3d83d7 Snapshot optimized solver and audit diagnostics before numerical experiments 2026-09-16 14:34:06 -04:00
297 changed files with 112218 additions and 355 deletions

13
.gitignore vendored
View File

@@ -5,3 +5,16 @@ build/
._DS_Store
.DSStore
.DS_Store
# Local build caches retain absolute source paths; do not relocate them.
cmake-build-*/
__pycache__/
*.pyc
test_summary.html
.cex/
.codex/
# Preserved raw campaigns, scratch files and report build intermediates.
# The directory guide and audit manifests are versioned separately.
/working/*
!/working/README.md

View File

@@ -14,6 +14,12 @@ if (NOT MEAN_FIELD_UNIFORM_POLYNOMIAL_ORDER_INCREMENT MATCHES "^[0-9]+$")
message(FATAL_ERROR "MEAN_FIELD_UNIFORM_POLYNOMIAL_ORDER_INCREMENT must be a non-negative integer")
endif ()
set(MEAN_FIELD_DENSITY_POLYNOMIAL_ORDER 2 CACHE STRING
"Density family order before the uniform increment; other fields retain their registered orders")
if (NOT MEAN_FIELD_DENSITY_POLYNOMIAL_ORDER MATCHES "^[0-9]+$")
message(FATAL_ERROR "MEAN_FIELD_DENSITY_POLYNOMIAL_ORDER must be a non-negative integer")
endif ()
add_compile_options(
-gdwarf-4
-Wno-unused-parameter
@@ -47,6 +53,7 @@ add_library(mean_field)
target_compile_definitions(mean_field
PUBLIC
MEAN_FIELD_UNIFORM_POLYNOMIAL_ORDER_INCREMENT=${MEAN_FIELD_UNIFORM_POLYNOMIAL_ORDER_INCREMENT}
MEAN_FIELD_DENSITY_POLYNOMIAL_ORDER=${MEAN_FIELD_DENSITY_POLYNOMIAL_ORDER}
MEAN_FIELD_ENABLE_PROFILING=$<BOOL:${MEAN_FIELD_ENABLE_PROFILING}>
)
@@ -77,6 +84,8 @@ target_sources(mean_field
libmeanfield/impl/mapping/domain_mapper.cpp
libmeanfield/impl/mapping/transformations.cpp
libmeanfield/impl/deformation/nodal_radial_surface.cpp
libmeanfield/impl/deformation/spherical_harmonic_surface.cpp
libmeanfield/impl/deformation/surface_metric.cpp
libmeanfield/impl/deformation/radial_extensions.cpp
libmeanfield/impl/deformation/safe_newton_step.cpp
libmeanfield/impl/operators/gravity_field.cpp
@@ -152,6 +161,13 @@ target_sources(mean_field
libmeanfield/interface/solver/fields.cppm
libmeanfield/interface/solver/linear_backend.cppm
libmeanfield/interface/solver/newton.cppm
libmeanfield/interface/solver/enthalpy_admissibility.cppm
libmeanfield/interface/solver/gravity_subsystem.cppm
libmeanfield/interface/solver/gravity_reduction.cppm
libmeanfield/interface/solver/coupled_trial_correction.cppm
libmeanfield/interface/solver/stellar_enthalpy_strategy.cppm
libmeanfield/interface/solver/newton_numerics.cppm
libmeanfield/interface/solver/stellar_newton_strategy.cppm
libmeanfield/interface/solver/preconditioning_diagnostics.cppm
libmeanfield/interface/solver/stellar_equilibrium_types.cppm
libmeanfield/interface/solver/stellar_structure.cppm
@@ -224,10 +240,12 @@ target_sources(mean_field
libmeanfield/interface/deformation/descriptors.cppm
libmeanfield/interface/deformation/surface_prescription.cppm
libmeanfield/interface/deformation/nodal_radial_surface.cppm
libmeanfield/interface/deformation/spherical_harmonic_surface.cppm
libmeanfield/interface/deformation/interior_extension.cppm
libmeanfield/interface/deformation/vacuum_extension.cppm
libmeanfield/interface/deformation/radial_extensions.cppm
libmeanfield/interface/deformation/domain_deformation.cppm
libmeanfield/interface/deformation/surface_metric.cppm
libmeanfield/interface/deformation/safe_newton_step.cppm
libmeanfield/interface/models/stellar_model.cppm
libmeanfield/interface/operators/root_manifest.cppm
@@ -337,12 +355,14 @@ add_executable(tests
tests/deformation/contracts.cpp
tests/deformation/surface_scalar_dof_map.cpp
tests/deformation/nodal_radial_surface.cpp
tests/deformation/spherical_harmonic_surface.cpp
tests/deformation/radial_extensions.cpp
tests/deformation/domain_deformation.cpp
tests/deformation/safe_newton_step.cpp
tests/operators/prepared_mass_normalization.cpp
tests/operators/prepared_angular_momentum.cpp
tests/operators/prepared_stellar_equilibrium.cpp
tests/operators/spherical_harmonic_equilibrium.cpp
tests/utils/domain.cpp
tests/field/field_base.cpp
tests/field/field_registry.cpp
@@ -352,6 +372,7 @@ add_executable(tests
tests/preconditioning/backends.cpp
tests/preconditioning/gravity_field.cpp
tests/preconditioning/material_surface.cpp
tests/preconditioning/spherical_harmonic_surface.cpp
tests/preconditioning/stellar_structure.cpp
tests/preconditioning/specification_border.cpp
tests/extensions/fixed_magnetic_specific_energy.cpp
@@ -360,15 +381,49 @@ add_executable(tests
tests/normalization/plan.cpp
tests/normalization/physical_riesz.cpp
tests/normalization/stellar_equilibrium.cpp
tests/normalization/spherical_harmonic_surface.cpp
tests/user-api/stellar_equilibrium.cpp
tests/solver/preconditioning_diagnostics.cpp
tests/solver/stellar_equilibrium_architecture.cpp
tests/solver/stellar_equilibrium_architecture_internal.cpp
tests/solver/stellar_equilibrium_runtime.cpp
tests/solver/enthalpy_admissibility.cpp
tests/solver/plateau_coupled_coarse.cpp
tests/solver/plateau_surface_border_schur.cpp
tests/solver/gravity_subsystem.cpp
tests/solver/gravity_compact_applications.cpp
tests/solver/gravity_reduction.cpp
tests/solver/coupled_trial_correction.cpp
tests/solver/stellar_numerical_strategies.cpp
tests/solver/continuation_snapshot.cpp
)
target_link_libraries(tests PRIVATE mean_field test_mod Catch2::Catch2 Boost::boost)
# Reuse the production contracts and closure Jacobian checks in order studies
# without compiling unrelated integration suites for every field configuration.
add_executable(density_order_contract_tests EXCLUDE_FROM_ALL
tests/test_main.cpp
tests/field/field_registry.cpp
tests/field/field_mfem.cpp
tests/quadrature/policy.cpp
tests/operators/prepared_gravity_source.cpp
tests/normalization/stellar_equilibrium.cpp
tests/operators/prepared_barotropic_closure.cpp)
target_link_libraries(density_order_contract_tests PRIVATE mean_field test_mod Catch2::Catch2 Boost::boost)
# Continuation changes owned runtime state; exercise its transactional boundary
# without rebuilding unrelated geometry and equation-of-state test suites.
add_executable(continuation_contract_tests EXCLUDE_FROM_ALL
tests/test_main.cpp
tests/solver/stellar_numerical_strategies.cpp
tests/solver/continuation_snapshot.cpp)
target_link_libraries(continuation_contract_tests PRIVATE mean_field test_mod Catch2::Catch2 Boost::boost)
add_executable(surface_border_schur_contract_tests EXCLUDE_FROM_ALL
tests/test_main.cpp
tests/solver/plateau_surface_border_schur.cpp)
target_link_libraries(surface_border_schur_contract_tests PRIVATE mean_field test_mod Catch2::Catch2 Boost::boost)
# A deliberately opt-in API workbench. It is compiled explicitly during API
# verification but temporary user experiments do not break the default build.
add_executable(sandbox EXCLUDE_FROM_ALL sandbox.cpp)
@@ -382,6 +437,17 @@ target_link_libraries(geometry_quality_experiment PRIVATE mean_field)
add_executable(polytrope_validation_experiment EXCLUDE_FROM_ALL experiments/polytrope_validation_experiment.cpp)
target_link_libraries(polytrope_validation_experiment PRIVATE mean_field)
# Opt-in plateau measurements; uses the production solver without numerical changes.
add_executable(plateau_diagnostic EXCLUDE_FROM_ALL experiments/plateau_diagnostic.cpp)
target_link_libraries(plateau_diagnostic PRIVATE mean_field)
# Standalone operator validation and timing, without constructing a Newton solve.
add_executable(system_isolation_profile_harness EXCLUDE_FROM_ALL experiments/system_isolation_profile_harness.cpp)
target_link_libraries(system_isolation_profile_harness PRIVATE mean_field)
if (MEAN_FIELD_ENABLE_IPO)
set_property(TARGET system_isolation_profile_harness PROPERTY INTERPROCEDURAL_OPTIMIZATION_RELEASE TRUE)
endif ()
add_executable(mpi_tests
tests/mpi/mpi_test_main.cpp
tests/mpi/distributed_execution.cpp

View File

@@ -0,0 +1,105 @@
# Deferred Removal Registry
This registry records migration-era code that may become removable after the
physics-facing `StellarModel` and `StellarEquilibriumProblem` APIs have replaced
all legacy construction paths. Nothing listed here is currently approved for
removal, and no listed code was removed during the migration.
## `mean_field::models::Model<...>`
- Location: `libmeanfield/interface/models/specifications.cppm`
- Current status: required compatibility storage
- Current consumers: root-manifest tests and the implementation of
`mean_field::model::StellarModel`
- Removal gate: migrate remaining direct consumers to the public
`mean_field::model::StellarModel` type, then move the canonical storage into
an implementation namespace
- Evidence required before removal: no direct consumers found by repository
search and the complete specification/type-contract suite passes
## Legacy structure-based `mean_field::models::StellarModel`
- Location: `libmeanfield/interface/models/stellar_model.cppm`
- Current status: retained legacy API, but no longer used by the authoritative
`StellarEquilibriumProblem` construction path
- Current consumers: direct prepared-operator tests, experiments, and
heterogeneous runtime-model views. Its polytropic initial-seed method now
delegates to the physics-facing Lane-Emden seed generator.
- Removal gate: numerical operators consume compiled specification
contributions directly, initial-seed generation has a physics-facing owner,
and deformation policies have migrated into the typed model
- Evidence required before removal: legacy-adapter equivalence tests pass for
all supported formulations and repository search finds no direct consumers
## `PolytropicStructure` as a mass-owning adapter
- Location: `libmeanfield/interface/models/structure/polytropic.cppm`
- Current status: compatibility adapter for remaining legacy API consumers; it
no longer owns Lane-Emden integration and is not constructed by
`StellarEquilibriumProblem`
- Potentially obsolete responsibility: ownership of the fixed-total-mass
target, which now belongs to `FixedTotalMass`
- Removal gate: migrate remaining callers to `seed::LaneEmden` and the typed
model. Lane-Emden generation is now separate from invariant ownership.
- Evidence required before removal: initial-seed regression tests and
model-driven equilibrium equivalence tests pass
## Legacy combined prepared operators
- Locations:
`libmeanfield/interface/operators/prepared_fixed_angular_momentum_stellar_equilibrium.cppm`
and
`libmeanfield/interface/operators/prepared_central_density_stellar_equilibrium.cppm`
- Current status: retained as migration-era source references, but removed from
the build graph and no longer re-exported by the public `mean_field` module
- Physics-facing replacement:
`PreparedVariadicStellarEquilibriumOperator<Model>`, selected solely by
`StellarEquilibriumProblem<Model, Discretization>`
- Reactivation gate: migrate the source snapshots to the model-driven manifest
constructor; they intentionally do not compile against the authoritative API
- Removal gate: delete the source snapshots after the historical comparison
window closes
- Evidence required before removal: the full variadic residual/Jacobian
equivalence suite and distributed tests pass without either partition being
imported by a user translation unit
## Completed: typed equilibrium-problem adapter removal
- Removed the former typed system's `NumericalModelAdapter`, its
`PolytropicStructure`, and the corresponding legacy model storage.
- The typed problem now owns its compiled surface constraint and constructs the
prepared operator directly from specification-generated contributions.
- Default radial deformation is compiled at the numerical equilibrium-problem
boundary rather than being smuggled through a legacy stellar model.
## `StellarEquilibriumSystem` compatibility vocabulary
- Location: `libmeanfield/interface/operators/stellar_equilibrium_system.cppm`
- Current status: source-compatible aliases and factory forwarding to
`StellarEquilibriumProblem` and `equilibrium::discretize`
- Removal gate: migrate remaining external consumers and provide a documented
deprecation interval
- Evidence required before removal: repository search finds only the explicit
compatibility type-contract test
## Root-oriented public aliases and accessors
- Locations:
`libmeanfield/interface/operators/root_manifest.cppm`,
`libmeanfield/interface/operators/prepared_stellar_equilibrium.cppm`, and
`libmeanfield/interface/operators/prepared_central_density_stellar_equilibrium.cppm`
- Current status: retained for source compatibility
- Physics-facing replacements: `EquilibriumSystemManifest`,
`EquilibriumStateView`, `EquilibriumResidualView`, and
`StellarEquilibriumProblem::GetManifest()`
- Removal gate: all solver and test consumers use equilibrium-system
terminology
- Evidence required before removal: repository search finds no uses of the old
aliases/accessors and all manifest/type-contract tests pass
## Conclusion for this phase
No code examined during this migration is presently truly dead. Each candidate
still has active consumers or carries a compatibility/lifetime responsibility.
The entries above are therefore deferred migration candidates, not deletion
recommendations.

View File

@@ -0,0 +1,548 @@
# MeanField FieldDof Migration Handoff
**Repository:** `/Users/tboudreaux/Programming/4DSTAR/MeanField`
**Prepared:** 2026-08-28
**Primary objective:** make registered field/domain support, rather than raw MFEM true-vector size, define the nonlinear and prepared-operator coordinate systems.
## 1. Scope and relationship to the earlier review
This document is the continuation handoff for the work performed after the earlier **Rotating Polytrope Review** summary. The receiving agent is expected to receive that earlier summary as well, so this document does not reconstruct every pre-migration investigation. It concentrates on:
- the final FieldDof architecture and its invariants;
- the gravity, barotrope, prepared-operator, and root-state migrations completed in this work;
- the canonical `FieldDofMap`/`GridFunction` adapter;
- the replacement and hardening of the domain-mapping system;
- dead-code and file cleanup;
- failures encountered during migration and what they taught us;
- final validation evidence;
- the small amount of cleanup that remains.
## 2. Executive status
The functional FieldDof migration is complete for the currently registered production fields and the coupled stellar-equilibrium operator stack.
The final solver-facing convention is:
```text
registered field + DomainSchema
|
v
FieldDofMap
|
reduced solver coordinates
|
prepared operator/context boundary
|
explicit scatter/gather
|
full MFEM true vectors
|
element kernels / MFEM
```
The complete Catch2 inventory was covered by three sharded runs:
| Validation group | Test cases | Assertion executions | Result |
|---|---:|---:|---|
| `[gravity]` | 58 | 3,746,701 | Pass |
| `[barotrope]` | 88 | 192,694 | Pass |
| `~[gravity]~[barotrope]` | 176 | 136,493 | Pass |
| **Total executions** | **322** | **4,075,888** | **Pass** |
There are 320 unique registered test cases. Two prepared stellar-equilibrium tests carry both `[gravity]` and `[barotrope]`, so the three filters intentionally execute those twice:
- `Prepared Stellar Equilibrium Has A Restoring Jacobian Around An N3 Polytrope`
- `Prepared Stellar Equilibrium Matches The Analytic N1 Lane Emden State Up To The Mixed Projection Floor`
Therefore:
```text
58 gravity + 88 barotrope + 176 remainder - 2 overlap = 320 unique tests
```
No MFEM abort, MPI abort, assertion failure, crash signature, or empty shard was present in the final 24 logs.
The migration is not yet packaged as a clean commit. The worktree is intentionally dirty relative to `HEAD` and contains the migration. Preserve it.
## 3. Git and validation provenance
Important commits:
- `0f3ca8050b78f0c5c1ef98d485b9fbc2ba06183c` — the user-created mid-migration checkpoint.
- `177ae8b38aa34d88c07203376961145c5403ccaa` (`HEAD` when this document was written) — `feat(support): continued migration to new field dof support system`.
The final migration, hardening, deletions, and mapper consolidation are uncommitted changes on top of `177ae8b`.
Final validation logs are under:
```text
${TMPDIR:-/tmp}/meanfield-migration-validation
```
On this machine that resolved to:
```text
/var/folders/v3/xfq17d692dg_gzdwv4yzmrkw0000gp/T/meanfield-migration-validation
```
The authoritative files are:
```text
gravity-final-shard-{0..7}.txt
barotrope-final-shard-{0..7}.txt
migration-remainder-shard-{0..7}.txt
```
Do not confuse these with older repository-root `gravity-shard-*.txt` files from August 24. Those older logs captured intermediate failures and were not evidence for the final state.
### Post-validation rename caveat
After the 24-shard validation completed, the user renamed:
- `DomainMapperStateless` to `DomainMapper`;
- `DomainMapperStatelessOptions` to `DomainMapperOptions`.
The public interface and most implementation state were compiled after the rename, but at handoff time `libmeanfield/impl/mapping/domain_mapper.cpp` had a modification timestamp two minutes newer than the latest test executable. The source-level audit found no remaining `DomainMapperStateless`, `DomainMapperStatelessOptions`, `domain_mapper_new`, or `PolytropicBarotrope` type/file references, and `git diff --check` passed. Nevertheless, run one compile-only check on the exact final tree before committing.
## 4. Final field and domain model
### 4.1 Registered support is the source of truth
Field support is declared in `libmeanfield/interface/field/field_registry.cppm`:
- `Density::Support = DomainSupport<Stellar>`;
- `Enthalpy::Support = DomainSupport<Stellar>`;
- `Gravity::Support = DomainSupport<All>`;
- `Displacement::Support = DomainSupport<All>`;
- `BarotropicConstant::Support = NonSpatialSupport`.
This distinction is now operational. Density and enthalpy solver vectors omit vacuum-only true DOFs. Gravity and displacement currently map over all domains and ordinarily produce identity maps. Global scalars are not routed through spatial `FieldDofMap` factories.
The concrete production schema is `CoreEnvelopeVacuumDomainSchema`. Field support is resolved through the schema's material bindings rather than through hard-coded assumptions such as “stellar attributes are 1 and 2” or “vacuum is attribute 3.” Tests deliberately exercise alternate material bindings to protect this property.
### 4.2 Supported continuous DOFs use union semantics
The active set is the union of DOFs touched by supported elements. It is not computed by removing every DOF that also touches an unsupported element.
This matters for continuous H1 fields. An enthalpy DOF shared by a stellar element and a vacuum element remains part of the stellar field because it participates in supported stellar elements and supplies the physical interface trace.
### 4.3 Parallel support resolution
`resolve_field_dof_support` performs the production parallel resolution:
1. Build a local vector-DOF marker from supported elements.
2. Decode MFEM's signed/oriented DOF indices.
3. Synchronize the marker across shared parallel DOFs.
4. Convert locally owned active vector DOFs to true DOFs.
5. Produce active/inactive markers and sorted index lists.
The synchronization step ensures that a shared interface DOF is active on every rank carrying it when any neighboring supported element activates it.
The implementation deliberately rejects nonconforming `ParFiniteElementSpace` objects. Supporting them correctly would require an explicit constraint/conforming-DOF projection; silently treating local DOFs as ordinary true DOFs was rejected as unsafe.
## 5. `FieldDofMap` contract
`FieldDofMap` is the canonical immutable indexing relation between a full MFEM true vector and a dense reduced field vector.
It stores:
- `full_size()` — MFEM true-vector size;
- `reduced_size()` — supported field-vector size;
- `reduced_to_true()` — canonical forward indices;
- `true_to_reduced()` — inverse indices with `-1` for inactive true DOFs.
Construction requires the reduced-to-true list to be sorted, unique, in range, and strictly increasing. This makes reduced ordering deterministic and consistent with MFEM marker-to-list ordering.
Important operations and semantics:
- `gather(full)` selects supported true DOFs into reduced order.
- `scatter(reduced)` creates a complete full true vector and zeros unsupported entries.
- `scatter_into(reduced, full)` overwrites supported entries while preserving existing unsupported entries.
- `scatter_add(reduced, full, scale)` accumulates into supported entries only.
- All overloads validate exact source and destination sizes.
- Destination-vector overloads do not resize their output, so views into `mfem::BlockVector` remain valid.
- `is_identity()` is exact because canonical ordering guarantees `reduced_to_true[i] == i` whenever all true DOFs are active.
The object intentionally contains no mesh, field, domain, or solver policy after construction. Those semantics belong to the factory step; consumers get a small indexing object.
## 6. Canonical `FieldDofMap`/`GridFunction` adapter
`FieldDofGridFunctionAdapter` was added as the only canonical bridge between reduced field vectors and MFEM `GridFunction` objects.
It binds a `FieldDofMap` to the exact `FiniteElementSpace` from which the map was constructed. Matching vector sizes are not enough: a grid function using another FE-space object is rejected. This prevents silent cross-space corruption when two spaces happen to have equal true-vector sizes.
Operations:
- `gather(GridFunction)` calls `GetTrueDofs` and gathers into reduced coordinates.
- `scatter(reduced, GridFunction)` applies projection semantics and calls `SetFromTrueDofs`.
- `scatter_into(reduced, GridFunction)` preserves unsupported existing true-DOF values.
- `make_field_dof_grid_function_adapter<Field, Schema>(space)` is the typed construction path.
The gravity initialization/solve now uses these adapters for density, displacement, gravity flux, and gravity potential. The returned `GravitySolution` remains an MFEM-facing pair of `ParGridFunction`s, while the solve itself is performed in reduced coordinates.
## 7. Domain mapping replacement and hardening
### 7.1 Architectural replacement
The old stateful mapping implementation was removed. The canonical `DomainMapper` now owns only mapping policy:
- dimension;
- vacuum material attribute;
- the exterior compactification map.
Element field values are supplied explicitly through `ElementMappingData`, and temporary storage is supplied through `DomainMapper::Workspace`. Point, volume, face, and first-variation evaluation are explicit operations. This eliminates hidden displacement state and cross-state cache contamination inside the mapper itself.
The implementation formerly stored in `libmeanfield/impl/mapping/domain_mapper_new.cpp` is now consolidated into:
```text
libmeanfield/impl/mapping/domain_mapper.cpp
```
`domain_mapper_new.cpp` was deleted and removed from CMake.
### 7.2 `GridFunctionMappingEvaluator`
`GridFunctionMappingEvaluator` is the stateful convenience layer for consumers that naturally own MFEM grid functions. It references displacement and compactification grid functions, extracts element-local data, and delegates actual geometry evaluation to `DomainMapper`.
Hardening added in the final stage:
- constructor validation for attached spaces;
- same-mesh validation;
- displacement vector-dimension validation;
- scalar compactification validation;
- mesh/domain-mapper dimension validation;
- exact FE-space binding checks after construction;
- detection of FE-space sequence changes;
- explicit, idempotent `InvalidateCache()`;
- eager `Refresh()` of a currently cached element;
- a validated no-op when `Refresh()` is called before any element is cached;
- lazy reload after space-sequence invalidation;
- correct application of MFEM `DofTransformation::InvTransformPrimal` to element displacement DOFs;
- support for both `byNODES` and `byVDIM` displacement ordering.
The evaluator owns mutable workspace/cache state and is explicitly not thread-safe. Consumers must call `InvalidateCache()` or `Refresh()` after mutating grid-function values. FE-space sequence changes are detected automatically, but arbitrary value changes are not observable without explicit invalidation.
Integrator consumers were updated to invalidate mapping caches at assembly entry. Analysis, physics, coefficient, utility, and integrator consumers now use `GridFunctionMappingEvaluator` rather than the removed stateful mapper API.
## 8. Gravity-system migration
The gravity migration covered kernels, prepared operators, contexts, coupled operators, the reduced solve, tests, and downstream consumers.
### 8.1 Boundary decision: kernels remain full-true-DOF code
Low-level element kernels deliberately continue to accept full MFEM true vectors. Their interface comments now state this boundary explicitly. Examples include:
- mapped H(div) mass and its geometry variation;
- mapped density source and its geometry variation;
- gravity displacement force residual and all Jacobian actions;
- hydrostatic and pressure/rotation kernels used by prepared consumers.
This was a deliberate choice. Element assembly naturally indexes MFEM spaces. Making kernels understand reduced field support would duplicate mapping logic and mix algebra with support policy.
Prepared operators and contexts own the maps and perform the only scatter/gather operations around those kernels.
### 8.2 Prepared gravity components
`PreparedMappedGravitySourceOperator` now owns density, potential, and displacement maps. Its public `Mult` and `MultTranspose` use reduced density/potential coordinates; it expands to full true vectors internally.
`PreparedMappedHDivMassOperator` owns flux and displacement maps. It accepts reduced flux/displacement vectors, maintains full internal work vectors, and exposes both:
- a reduced diagonal for the reduced mass block;
- a full true diagonal for the Schur construction.
Both stellar and compactified-vacuum H(div) contributions are included. Positivity is tested across the complete gravity domain.
### 8.3 Gravity contexts and revision routing
`GravityFieldGeometryContext` owns the displacement map and the geometry-dependent prepared mass/source/divergence operators.
`GravityFieldLinearizationContext` owns density, displacement, gravity-gradient, and gravity-potential maps, together with the full true work vectors required by kernels.
Typed revision stamps control selective invalidation for:
- discretization;
- displacement;
- density;
- gravity gradient;
- gravity potential.
Tests verify first preparation, no-op repeat preparation, selective rebuild/update behavior, and independent contexts without shared cache contamination.
### 8.4 Coupled gravity operator and Jacobian
`GravityFieldOperator`, `GravityFieldJacobianOperator`, and their state/residual offsets now use `reduced_size()` for every registered field block.
The coupled gravity state is:
```text
[ density(reduced), displacement(reduced), gravity-gradient(reduced), gravity-potential(reduced) ]
```
The gravity residual is:
```text
[ gradient-equation(reduced flux), Poisson-equation(reduced potential) ]
```
MFEM divergence operators remain full-space objects. Their operands/actions are explicitly scattered and gathered at the operator boundary.
### 8.5 Reduced solve and preconditioner
`solve_gravity_field` now:
1. validates that the supplied grid functions use the expected FEM spaces;
2. creates typed field/grid-function adapters;
3. gathers density and displacement;
4. builds the reduced block layout;
5. prepares the reduced gravity operator and geometry context;
6. solves the reduced mixed system with MINRES;
7. scatters the reduced flux and potential solution back to `ParGridFunction`s.
The reduced block preconditioner uses:
- `OperatorJacobiSmoother` on the reduced positive H(div) mass diagonal;
- a full-space approximate Schur complement `B diag(M)^{-1} B^T`;
- `HypreBoomerAMG` for the potential Schur block;
- explicit potential scatter/gather around the full-space AMG object.
This split is important. The first attempted reduced preconditioner encountered zero diagonal entries because inactive/full-space structure was being handed to a smoother that requires a positive diagonal. A later attempt produced immediate MINRES non-convergence. The final implementation makes the coordinate space of each preconditioner component explicit and is protected by the positive-diagonal and deformed-MINRES tests.
## 9. Barotrope, pressure, hydrostatic, displacement, and root migration
The FieldDof conversion was propagated beyond gravity so the coupled root operator has one consistent coordinate convention.
Map-aware contexts now include:
- `BarotropicClosureLinearizationContext`;
- `PressureForceLinearizationContext`;
- `HydrostaticEquilibriumContext`;
- `RotationalDisplacementForceLinearizationContext`;
- gravity geometry and linearization contexts.
Map-aware prepared operators include:
- barotropic closure;
- pressure force;
- hydrostatic equilibrium;
- gravity displacement force;
- rotation displacement force;
- composed displacement residual;
- mass normalization;
- mapped gravity source;
- mapped H(div) mass;
- complete stellar equilibrium.
Density and enthalpy are reduced at public prepared-operator boundaries. Displacement, gravity flux, and gravity potential also use `FieldDofMap`, even where their maps are identities today. This avoids hard-coding the current support choice into the coupled algebra.
`PreparedStellarEquilibriumOperator` constructs every block size from maps. Its root state is:
```text
[ density, displacement, gravity-gradient, gravity-potential, enthalpy, Bernoulli constant ]
```
Spatial blocks are in registered FieldDof coordinates; the Bernoulli constant remains a one-entry nonspatial block. The operator extracts reduced views, packs the gravity substate, routes the exact child dependencies, and assembles the residual only when a dependency or child preparation changes.
This removed the earlier ambiguous mixture in which some children expected full MFEM true vectors while others expected reduced field vectors.
## 10. EOS migration
The duplicate `physics::PolytropicBarotrope` implementation was removed.
The canonical EOS is now:
```cpp
mean_field::eos::Polytrope
```
It implements the `EquationOfState` interface and supplies density/pressure/enthalpy conversions and derivatives, including defined surface behavior at zero enthalpy/density and validation of material parameters and physical inputs.
Deleted legacy module:
```text
libmeanfield/interface/physics/barotrope.cppm
```
The file was removed from CMake, and no `PolytropicBarotrope` reference remains in production code, tests, or experiments. Local variables named `barotrope` may still refer to an `eos::Polytrope`; those names are descriptive variables, not the deleted class.
## 11. Dead and legacy code removed
The following dead implementations/modules were deleted:
- `libmeanfield/impl/mapping/domain_mapper_new.cpp` — merged into canonical `domain_mapper.cpp`;
- `libmeanfield/interface/physics/barotrope.cppm` — duplicate EOS implementation;
- `libmeanfield/interface/physics/context.cppm` — obsolete `GravityContext` owning the old assembled gravity solve/preconditioner stack.
CMake was updated so only the canonical mapper, EOS, and gravity context/operator stack are compiled.
Legacy-comparison gravity tests tied to the removed assembled implementation were removed when they ceased to compare two supported production paths. Analytic, variational, operator-identity, projection-floor, and self-consistency tests now provide the regression protection instead.
## 12. File and symbol renaming
Completed:
- canonical implementation file is `libmeanfield/impl/mapping/domain_mapper.cpp`;
- `_new` mapper filename removed;
- `DomainMapperStateless` renamed to `DomainMapper`;
- `DomainMapperStatelessOptions` renamed to `DomainMapperOptions`.
Intentionally not yet completed:
- the `fem::FEM` member remains named `domainMapperStateless`;
- many local variables and diagnostics still say “stateless domain mapper”;
- mapper test titles still begin with `Stateless Domain Mapper`.
These are naming cleanup items, not two competing mapper implementations. The user planned to perform broad identifier renames with IDE tooling. A reasonable final name for the FEM member is `domainMapper`.
## 13. Test infrastructure and tag cleanup
Tests use the typed compile-time tag system in `tests/test_helpers.cppm`:
- `make_tag` creates a Catch2 tag;
- `sub_tag` and `operator&` compose tag sets;
- canonical leaf/composite constants prevent hand-written duplicated tag strings.
New/normalized families include:
- `field_dof_unit` and `field_dof_integration`;
- `mapping_evaluator_unit`;
- gravity unit, integration, operator, prepared, context, kernel, accuracy, analytic, and consistency families;
- barotrope prepared, EOS, context, hydrostatic, pressure/quadrature, and mass-normalization families;
- rotation prepared/context/kernel/analytic families.
Touched gravity and prepared tests were converted to these typed tags. The guiding rule is to compose leaf semantics exactly once so output does not repeat inherited `[physics]` or `[solver]` tags.
### Tests added during the final uncommitted migration
Genuinely new adapter/evaluator/diagonal/schema coverage includes:
- `Domain Schema Builds Exact MFEM Attribute Markers`;
- `Field DOF Grid Function Adapter Gathers Exactly The Supported True DOFs`;
- `Field DOF Grid Function Adapter Scatter Projects And Round Trips Reduced Fields`;
- `Field DOF Grid Function Adapter Scatter Into Preserves Unsupported True DOFs`;
- `Field DOF Grid Function Adapter Is Exact For Identity Vector Field Maps`;
- `Field DOF Grid Function Adapter Rejects Incompatible Maps Spaces And Vectors`;
- `Grid Function Mapping Evaluator Refreshes A Cached Displacement Element`;
- `Grid Function Mapping Evaluator Invalidates A Cached Compactification Element`;
- `Grid Function Mapping Evaluator Rejects Invalid Fields And Rebinding`;
- `Prepared Mapped Hdiv Mass Diagonal Is Positive Across Both Domains`.
The gravity analytic tests formerly prefixed `New ...` were promoted to canonical names after removal of the obsolete comparison path. EOS test titles were similarly changed from `Polytropic Barotrope ...` to `Polytropic EOS ...`.
Important gravity coverage now includes:
- kernel equality, linearity, vacuum exclusion, and centered geometry variations;
- prepared source/mass identities and preparation reuse;
- full-column and simultaneous Jacobian comparisons;
- context selective invalidation and isolation;
- reduced block dimensions and routing;
- deformed MINRES solve;
- uniform sphere, homogeneous/deformed ellipsoid, Ferrers, monopole, and exterior compactification comparisons;
- virial and volume-preserving-deformation self-consistency;
- separation of physical exterior error from the finite-element projection floor.
Important barotrope/root coverage includes:
- EOS identities, derivatives, surface behavior, and invalid inputs;
- reduced barotropic closure under multiple EOS/geometry conditions;
- pressure residual and Jacobian comparisons;
- hydrostatic algebraic/displacement/complete Jacobians;
- mass-normalization routing and differences;
- displacement residual composition and MFEM routing;
- six-by-six stellar-equilibrium layout;
- child invalidation and complete centered differences;
- analytic N=1 and N=3 stellar states.
## 14. Migration failures and lessons
Several failures were valuable because they identified mixed-coordinate boundaries.
### Density-size abort in mapped-source variation
An early gravity shard aborted because a reduced density vector reached `apply_mapped_source_variation`, whose element indexing requires a full density true vector.
Resolution: retain the full-vector kernel contract and scatter in the prepared/context layer. Tests were migrated so directions and states use the correct representation at each boundary.
### Zero diagonal in `OperatorJacobiSmoother`
The first reduced gravity preconditioner attempted to construct a Jacobi smoother from a diagonal containing unsupported/full-space zeros.
Resolution: assemble and smooth the reduced positive mass diagonal, while retaining a separately assembled full true diagonal for the full divergence-based Schur approximation.
### Immediate MINRES non-convergence
After removing the zero-diagonal abort, an intermediate preconditioner arrangement stopped at iteration zero without convergence.
Resolution: use a consistent block preconditioner—reduced mass Jacobi plus full Schur AMG with explicit potential scatter/gather—and add a deformed reduced-system solve test.
### Stale shard files
Repository-root gravity shard files from August 24 showed several old analytic failures and an MPI abort. They were initially easy to mistake for the new run.
Resolution: use labeled logs in the dedicated temporary validation directory and verify modification times before diagnosing failures.
### Cached grid-function values
`GridFunctionMappingEvaluator` caches copies of element-local field DOFs. Mutating a referenced grid function does not automatically change an already cached element.
Resolution: expose/document `InvalidateCache()` and `Refresh()`, harden FE-space change/rebinding detection, update integrator entry points, and add direct mutation/cache tests.
## 15. Known limitations and remaining work
The primary FieldDof migration is complete. Remaining items are cleanup or explicitly bounded future work:
1. **Compile the exact post-rename tree.** `libmeanfield/impl/mapping/domain_mapper.cpp` is newer than the latest test executable.
2. **Finish cosmetic mapper naming.** Rename `domainMapperStateless`, related local variables/messages, and optionally mapper test titles.
3. **Commit the migration.** Review the large dirty worktree carefully and preserve unrelated user artifacts. Do not reset it.
4. **Nonconforming meshes remain unsupported by FieldDof resolution.** Add the correct conforming-constraint projection before lifting the explicit rejection.
5. **`GridFunctionMappingEvaluator` is not thread-safe.** Use one evaluator/workspace per thread if threaded assembly is introduced.
6. **Value mutation requires cache invalidation.** Keep the assembly-entry invalidations when refactoring integrators.
7. **Quadrature `Query.domain` remains legacy metadata.** Physical element selection in migrated prepared closure/pressure paths already comes from field support plus `DomainSchema`; the metadata can be migrated independently with the quadrature subsystem.
8. **The legacy `GravityMomentumIntegrator` exact geometry-Jacobian mode still aborts intentionally.** Its message states that exact geometry variation has not been wired into that legacy integrator. The prepared gravity-displacement path does have the tested exact variation. Do not mistake the old integrator limitation for an incomplete FieldDof conversion.
9. **No monolithic one-process full-suite run was performed.** The three filters cover every registered test case, but a full unsharded invocation would additionally probe process-global/order interaction. Given the suite's runtime, the user accepted complete partitioned coverage as sufficient.
## 16. Recommended immediate continuation
The next agent should:
1. Read this document and the earlier Rotating Polytrope Review summary.
2. Inspect `git status --short`; assume all existing changes belong to the user/migration.
3. Run a compile-only check of `cmake-build-debug-homebrew` after the final mapper rename.
4. Search again for:
```text
DomainMapperStateless
DomainMapperStatelessOptions
domain_mapper_new
PolytropicBarotrope
```
The first item will still appear as the lower-camel FEM member `domainMapperStateless`; the old PascalCase types and `_new` file should not appear.
5. If the user wants the cosmetic rename, use IDE-aware rename for the FEM member and related identifiers, then compile again. The change is broad but mechanical.
6. Review `git diff --check`, the three intended deletions, and CMake source lists.
7. Create a new checkpoint/final migration commit only after the user confirms the desired naming cleanup.
If a final regression rerun is desired after cosmetic renaming, the most efficient confidence gate is:
```bash
./cmake-build-debug-homebrew/tests \
"Field DOF Grid Function Adapter*,Grid Function Mapping Evaluator*,Prepared Mapped Hdiv Mass Diagonal Is Positive Across Both Domains,Reduced Gravity Field Operator Solves Deformed Gravity System With MINRES,Prepared Stellar Equilibrium*"
```
The already completed 24-shard run remains the substantive migration validation.
## 17. Invariants future changes must preserve
- Solver/prepared public spatial states are in registered FieldDof coordinates.
- Low-level MFEM element kernels receive full true vectors.
- Crossing that boundary must be visible as a map or adapter operation.
- Block sizes come from `FieldDofMap::reduced_size()`, never raw `GetTrueVSize()` unless the object is explicitly full-space.
- Field support comes from the field registry plus a `DomainSchema`, not numeric attribute conventions.
- Shared continuous interface DOFs use union-of-supported-elements semantics.
- `scatter` means projection/zero outside support; `scatter_into` means preserve outside support.
- Grid-function adapters validate FE-space identity, not merely equal sizes.
- Mapping evaluator caches must be invalidated after value mutation.
- Prepared contexts own their linearization maps, revisions, and full-vector workspaces.
- Test reference kernels must be passed full true vectors; solver/operator calls must be passed reduced vectors.
These invariants are the durable result of the migration and should be treated as the design contract going forward.

File diff suppressed because it is too large Load Diff

File diff suppressed because it is too large Load Diff

View File

@@ -0,0 +1,96 @@
# Stellar-equilibrium preconditioning campaign — 2026-09-03
## Scope
This campaign established and tested a compile-time composable right-preconditioner for the current bordered stellar-equilibrium Jacobian. The reference problem is the zero-rotation, `n = 3` polytrope with an isobaric surface, fixed total mass, and fixed central density, discretized on `sandbox.smesh` and linearized at the projected Lane–Emden seed.
The complete operator remains matrix-free. Sparse or dense matrices are assembled only for individual surrogate blocks.
## Recommended policy before the nonlinear-solver phase
The best-supported complete-system policy retains:
- an uncalibrated surface Riesz diagonal;
- surface-then-material triangular factorization;
- independent material/surface and gravity subsystems;
- gravity approximate LDU;
- an exact dense Schur correction for the small specification border.
The automatic gravity policy now uses an order-5 fixed matrix-free Chebyshev inverse for the mapped H(div) mass operator and three fixed BoomerAMG cycles for the potential Schur surrogate. The low-level composition API can still select order 4 for a slightly cheaper application, diagonal mass inversion, and any valid fixed-cycle configuration.
Surface scalar calibration, the surface H1 mass-plus-stiffness surrogate, material approximate LDU, and cross-subsystem stellar factorizations remain explicit opt-in experiments. None has earned promotion to the default.
## What the measurements showed
### Material–surface subsystem
The uncalibrated surface-then-material factorization reached a true relative residual of approximately `6.42e-6` in 40 iterations on the manufactured subsystem problem. Operator-action scalar calibration improved that isolated residual to approximately `1.38e-6`, and material LDU with the same calibration reached approximately `1.11e-6`.
That isolated improvement did not transfer to the complete operator. The surface Jacobian spans roughly three orders of magnitude across tested surface modes, so a single scalar cannot be a uniformly accurate inverse. A right-preconditioned-action fit was added because it optimizes the operation actually used by `J M^-1`; it reduced the isolated balanced recovery defect from approximately `1.010` to `0.848` and was stable from one to sixteen probes. It is retained as an experiment, not a default.
The H1 mass-plus-stiffness surface surrogate also remains experimental. Its fit residual and extreme gains showed that this two-term local differential model does not reliably represent the restricted surface Jacobian on the current discretization.
### Gravity subsystem
With a diagonal H(div) mass inverse and one fixed BoomerAMG cycle, gravity approximate LDU was decisively better than block-diagonal or one-sided triangular factorizations. It reached `1.59e-8` after 100 iterations, versus approximately `1e-6` for the triangular policies and `2.84e-3` for block diagonal.
The new backend sweep separated two approximation errors:
- the mapped H(div) mass inverse;
- the scalar potential-Schur inverse supplied by fixed-cycle BoomerAMG.
Two AMG cycles reduced the measured Schur recovery defect from `0.169` to `0.083` and made the diagonal-mass gravity solve converge in 87 iterations. A fixed matrix-free Chebyshev polynomial applied to the exact partially assembled H(div) mass operator improved the coupled gravity iteration count much more strongly. Representative converged results were:
| H(div) mass inverse | AMG cycles | iterations | solve time (s) | true relative residual |
|---|---:|---:|---:|---:|
| diagonal | 2 | 87 | 5.43 | `8.51e-9` |
| Chebyshev order 3 | 2 | 47 | 5.82 | `8.27e-9` |
| Chebyshev order 4 | 2 | 44 | 6.80 | `8.49e-9` |
| Chebyshev order 4 | 3 | 43 | 7.36 | `7.23e-9` |
| Chebyshev order 5 | 3 | 42 | 8.48 | `8.00e-9` |
For the isolated gravity solve, order 3–4 is the useful quality/cost region: order 5 buys only one or two additional iterations at materially higher preconditioner cost. The complete-system comparison below nevertheless shows that order 5 earns its small end-to-end cost there. MFEM 4.9.1 supports Chebyshev orders only in `[1, 5]`; the backend now validates that range and turns an otherwise fatal MFEM abort into an ordinary configuration error.
### Complete bordered stellar operator
On the block-balanced manufactured correction, the original complete default reached a true relative residual of `3.47e-4` in 36 iterations. Identity reached only `0.783`. Every previously tested calibrated or more strongly coupled composition was worse (`0.0107`–`0.0413`) and substantially more expensive.
Holding every other block and factorization fixed, two AMG cycles alone produced only `3.46e-4`. Chebyshev order 3 with two AMG cycles improved this to `2.24e-4`; Chebyshev order 4 with three AMG cycles reached `1.43e-4`; and the final order-5/AMG-3 challenger reached `1.19e-4`. Relative to order 4, order 5 reduced the fixed-budget residual by another 16.7% and the correction error from `2.844` to `2.219`, while increasing the matched total solve time only from `181.16` s to `182.00` s. Relative to the diagonal-mass control, it reduced the fixed-budget residual by 65.6%. This evidence supports promoting Chebyshev-5/AMG-3 as the automatic gravity default, while retaining order 4 as the nearby quality/cost option.
For that default result, 93.8% of the final squared residual was in the gravity-gradient equation and 6.2% was in Poisson balance. Material, surface, and specification-border residuals were negligible globally. This motivated the H(div) Chebyshev work rather than further surface tuning.
The short Arnoldi projection is useful as a diagnostic, but not as a policy oracle. In the complete system the identity operator had a much smaller 12-vector projected condition proxy than the successful default even though its FGMRES result was dramatically worse. True residual reduction and Jacobian applications therefore remain the primary decision metrics.
### Physical Newton right-hand side
The physical experiment solves `J delta = -R(u)` at the same projected Lane–Emden state and evaluates seven damped nonlinear trial states for every correction. All trial states in the first comparison were finite, nonnegative in density, and orientation preserving.
The physical right-hand side exposed a solver-level issue that the manufactured problem does not: all candidates stagnated at the 20-vector restart. The current default reduced the true linear residual only to `0.999800` in 48 iterations; uncalibrated material-then-gravity reached `0.999092` but cost more than three times as much per solve. The right-hand side is dominated by barotropic closure (`3.51e-5`), while its gravity rows are around `1e-11`; the unscaled Euclidean Krylov norm and restart therefore do not provide a physically balanced convergence measure. This is evidence for explicit equation scaling and restart studies in the solver phase, not evidence that the complete preconditioner should adopt the expensive cross factorization.
## Correctness and lifecycle guarantees added
- Fixed and adaptive backend application modes remain distinct; only stationary-linear configurations are Arnoldi admissible.
- The matrix-free Chebyshev backend owns its diagonal and essential-DOF list, uses a deterministic power estimate, is fixed-order linear, and reconstructs itself on geometry refresh.
- Chebyshev configuration validates polynomial order, power-iteration count, a strictly positive random seed, a power-method tolerance in `(0, 1)`, size, and strict positivity of the assembled mass diagonal.
- Gravity composition is generic over a compile-time compatible mass backend, so the new backend propagates through the stellar-structure and specification-border layers without a runtime type registry.
- Prepared composite blocks explicitly prohibit unsafe copying and moving when their factorization stores pointers into their own members.
- Unit tests cover backend compatibility, linearity, positivity, statistics, invalid configuration, and composite ownership. Integration tests cover geometry staleness and explicit refresh without repreparing the physical geometry.
- The focused gravity integration suite passes with both one and two MPI ranks. It applies the Chebyshev-backed block after an ordinary geometry refresh, then forces a discretization revision that reconstructs the underlying matrix-free operator, verifies that stale application and stale inverse access are rejected, refreshes the owner, and verifies finite repeatable post-rebind actions. Full numerical quality comparisons in this campaign remain single-rank.
## Reproducible artifacts
- `preconditioning_p9_surface_calibration_objectives.csv`
- `preconditioning_p10_full_stellar.csv`
- `preconditioning_p10_physical_newton.csv`
- `preconditioning_p4_gravity_chebyshev_sweep_v2.csv`
- `preconditioning_p10_gravity_backend_finalists.csv`
- `preconditioning_p10_gravity_backend_finalists_v2.csv`
The experiment sources are `experiments/material_surface_preconditioning.cpp`, `experiments/gravity_preconditioning.cpp`, and `experiments/full_stellar_preconditioning.cpp`.
## Remaining work
1. In the solver phase, introduce physically meaningful equation/value scaling and compare restarted with unrestarted or larger-restart FGMRES on the physical Newton right-hand side.
2. Validate the selected policy across mesh refinement, nonzero rotation, deformed geometry, and more than one MPI rank.
3. Revisit surface preconditioning only with a richer surrogate or multilevel representation; do not promote a scalar or H1 fit solely from isolated measurements.
4. Treat adaptive inner solves as FGMRES-only and exclude them from fixed-operator Arnoldi studies.

126
docs/profiling_and_mpi.md Normal file
View File

@@ -0,0 +1,126 @@
# Profiling and MPI validation
This guide describes the profiling and distributed-test tools added after
checkpoint `25510008ddf9810eaf9821149734d526c76b087a`.
## Build modes
The profiling macros compile out by default. For a profiling build, enable them
and leave IPO off so profile attribution is easier to interpret:
```bash
./format
cmake -S . -B cmake-build-profile-homebrew-llvm -G Ninja \
-DCMAKE_BUILD_TYPE=Release \
-DMEAN_FIELD_ENABLE_PROFILING=ON \
-DMEAN_FIELD_ENABLE_IPO=OFF
./format
cmake --build cmake-build-profile-homebrew-llvm --target tests mpi_tests -j 6
```
For production timings, use profiling off and IPO on:
```bash
./format
cmake -S . -B cmake-build-release-homebrew -G Ninja \
-DCMAKE_BUILD_TYPE=Release \
-DMEAN_FIELD_ENABLE_PROFILING=OFF \
-DMEAN_FIELD_ENABLE_IPO=ON
./format
cmake --build cmake-build-release-homebrew --target tests mpi_tests experiments -j 6
```
Always run `./format` immediately before a command that can compile.
## Bounded test runner
`tools/profile_tests.py` accepts a Catch2 filter, rank counts, repetitions, and
a per-run timeout. It writes one log per run and updates the summary CSV after
every repetition.
```bash
python3 tools/profile_tests.py \
--executable cmake-build-profile-homebrew-llvm/tests \
--ranks 1 --repeat 1 --timeout 360 \
--output-directory /private/tmp/meanfield-profile \
"Gravity Field Virial Consistency Across Volume Preserving Deformation" \
-- --reporter console
```
MPI sweep:
```bash
python3 tools/profile_tests.py \
--executable cmake-build-release-homebrew/tests \
--ranks 1,2,4 --repeat 3 --timeout 360 \
--output-directory /private/tmp/meanfield-rank-sweep \
"Gravity Field Virial Consistency Across Volume Preserving Deformation"
```
Arguments after `--` go to Catch2. Runner options may appear before or after the
filter. On timeout, the runner sends `SIGTERM` to the entire process group,
waits for `--kill-grace`, and then sends `SIGKILL` if necessary. This prevents
MPI workers from surviving a timed-out launcher.
The CSV records rank count, repetition, status, exit code, wall time, timeout,
log path, and exact command. Profile-region output is in the corresponding log.
## Profile columns
- `Samples`: recorded observations after warmups.
- `Warmups`: discarded warmup observations.
- `Work/rank`: minimum-to-maximum work-unit count across ranks.
- `Avg max ms`: maximum per-rank average duration.
- `Min ms` and `Max ms`: global extrema across all samples and ranks.
- `Total max s`: maximum accumulated duration on any rank.
MPI aggregation first unions label sets across ranks. A region may therefore be
visited on only one rank without causing collective-order divergence.
## MPI regression suite
The dedicated `mpi_tests` executable covers distributed semantics without
replicating the complete serial suite on every process. Registered CTest jobs
use two and four ranks:
```bash
ctest --test-dir cmake-build-release-homebrew \
--label-regex mpi --output-on-failure --timeout 180
```
Or build and run through the convenience target (remember that the target can
compile, so format first):
```bash
./format
cmake --build cmake-build-release-homebrew --target check_mpi
```
The suite checks communicator splitting, global element coverage, mapped H(div)
mass symmetry and linearity, divergence adjointness, a complete distributed
gravity analysis/solve, and profiling with rank-local labels. Catch2 uses a
fixed synchronized seed so all ranks enter tests and collectives in the same
order. Only rank zero emits the report.
The current measurements use multiple MPI ranks on one host. The suite is
appropriate for a multi-node launcher, but inter-host fabric behavior still
needs validation on actual multi-node hardware.
## Known high-level limitation
The reduced gravity and virial paths run on multiple ranks. The complete
spectral equilibrium experiment does not yet do so because logical radial
surface interpolation explicitly requires one rank. Supporting that path needs
distributed ownership and transpose-consistent communication for interpolation
rows whose surface element may be remote. This is a separate architectural
feature, not a failure of the corrected gravity kernels.
## Current reference results
- Prepared spectral Jacobian, one rank: 3.964707 s.
- Gravity virial: 205.843 s (one rank), 118.926 s (two), 65.210 s (four).
- Centrifugal h refinement: 254.984 s, historically 525.601 s.
- Release MPI CTest jobs: 18.12 s (two ranks), 10.11 s (four ranks).
- Full release suite: 410 cases and 5,086,850 assertions passed in 2,807.831 s.
No tolerance or resolution was changed to obtain these results.

View File

@@ -0,0 +1,700 @@
# Extending stellar-model physics
MeanField treats a stellar model as a compile-time collection of independent physics specifications. An EOS, a surface condition, an integral constraint, and a phase condition each describe only their own contribution. The library then infers the model type, generated scalar blocks, residual blocks, Jacobian edges, normalization, and manifest entries from that collection.
The important rule is: **add one declaration and, where needed, one implementation per physics specification—never a specialization for a whole combination of constraints.** A new integral must compose with every already-supported EOS, surface, and other constraint without naming those combinations.
Every downstream layer folds the same canonical specification pack. The symbolic compiler appends generated blocks and Jacobian edges, the manifest and normalization layers project metadata for those exact blocks, the prepared equilibrium operator owns one statically typed runtime slot per specification, and the default preconditioner folds the corresponding border actions. “Variadic” therefore means one inferred C++ type and one inferred block system for each pack, not a runtime list and not a library of hand-written pack combinations.
## The small physics-facing contract
A specification is an ordinary physics class with:
- a `Parameters` aggregate;
- a constructor from `Parameters`; and
- one nested `ModelDefinition` made from a role-specific alias.
The declaration is the single source used by `SpecificationTraits` and `SpecificationContribution`; an extension author does not specialize either trait.
### EOS
The EOS still uses the existing relation vocabulary. `ModelDefinition` only tells the stellar-model compiler which role the object has.
```cpp
class LinearBarotrope final {
public:
struct Parameters final {
double densityPerEnthalpy;
};
using ModelDefinition = mean_field::eos::ConstitutiveLaw<
LinearBarotrope,
"LinearBarotrope">;
using Relations = mean_field::eos::RelationCatalog<
mean_field::eos::DensityFromSpecificEnthalpy>;
explicit constexpr LinearBarotrope(Parameters p) noexcept
: m_densityPerEnthalpy(p.densityPerEnthalpy) {
}
[[nodiscard]] constexpr mean_field::dimensions::DensityValue evaluate(
mean_field::eos::DensityFromSpecificEnthalpy,
mean_field::dimensions::SpecificEnthalpyValue h
) const noexcept {
return mean_field::dimensions::DensityValue{m_densityPerEnthalpy * h.value()};
}
[[nodiscard]] constexpr auto partialDerivative(
mean_field::eos::DensityFromSpecificEnthalpy,
mean_field::eos::WithRespectTo<mean_field::dimensions::quantity::SpecificEnthalpy>,
mean_field::dimensions::SpecificEnthalpyValue
) const noexcept {
return mean_field::eos::PartialDerivative<
mean_field::dimensions::quantity::Density,
mean_field::dimensions::quantity::SpecificEnthalpy>{m_densityPerEnthalpy};
}
private:
double m_densityPerEnthalpy;
};
static_assert(mean_field::eos::EquationOfStateModel<LinearBarotrope>);
static_assert(mean_field::models::ModelSpecification<LinearBarotrope>);
```
The explicit quantity type is what prevents accidental pressure/density/enthalpy interchange.
### Surface condition
A surface condition declares the physical quantity it fixes. Describing a new condition is intentionally separate from implementing its finite-element carrier equation.
```cpp
class IsothermalSurface final {
public:
struct Parameters final {
mean_field::dimensions::TemperatureValue Tsurface;
};
using ModelDefinition = mean_field::surface::BoundaryCondition<
IsothermalSurface,
"IsothermalSurface">;
using PhysicalQuantity = mean_field::dimensions::quantity::Temperature;
using TargetValue = mean_field::dimensions::TemperatureValue;
explicit constexpr IsothermalSurface(Parameters p) noexcept
: m_target(p.Tsurface) {
}
[[nodiscard]] constexpr TargetValue targetTemperature() const noexcept {
return m_target;
}
private:
TargetValue m_target;
};
```
### Integral constraint
An integral says which stellar state variables it reads (`stellar::Reads`), which equations its generated coordinate changes (`stellar::Changes`), how its generated value and residual are normalized, and how they appear in diagnostics. The ordinary declaration uses physics names; the equilibrium compiler translates them to numerical blocks.
```cpp
class PreparedFixedBaryonMass;
class FixedBaryonMass final {
public:
struct Parameters final {
mean_field::dimensions::MassValue Mbaryon;
};
using ScalarDescription = mean_field::stellar::ScalarConstraint<
mean_field::dimensions::quantity::Mass,
mean_field::dimensions::quantity::SpecificEnergy,
mean_field::dimensions::quantity::Mass,
"fixed_baryon_mass.multiplier", "C_b",
"fixed_baryon_mass.residual", "R_Mb">;
using TargetValue = typename ScalarDescription::TargetValue;
using ModelDefinition = mean_field::integral::FixedScalarWithMultiplier<
FixedBaryonMass,
"FixedBaryonMass",
mean_field::stellar::Reads<
mean_field::stellar::state::Density,
mean_field::stellar::state::SurfaceShape>,
mean_field::stellar::Changes<
mean_field::stellar::equation::HydrostaticBalance>,
ScalarDescription>;
using EquilibriumPhysics =
mean_field::operators::LocalSpecificationEquilibriumPhysics<
PreparedFixedBaryonMass>;
explicit FixedBaryonMass(Parameters p) : m_target(p.Mbaryon) {
}
// This conventional accessor lets the generic manifest read the target.
[[nodiscard]] TargetValue target() const noexcept {
return m_target;
}
private:
TargetValue m_target;
};
```
`FixedIntegralWithPhysicalCoordinate` has the same declaration shape, but its generated scalar is a physical state coordinate rather than a Lagrange multiplier. `FixedAngularMomentum`, whose generated coordinate is angular velocity, is the current example.
`stellar::ScalarConstraint` names three independent physical quantities: the
target, the generated Newton coordinate, and the appended constraint residual.
The wrapper derives numerical scale laws and diagnostic unit labels from those
strong quantity types, so a total energy cannot accidentally be normalized as
a specific energy merely because two free-form strings agree. The quantities
need not be the same: `FixedCentralDensity` has a density target and a
specific-enthalpy phase residual. The wrapper contains no assembly logic. The
lower-level `FixedIntegralWithMultiplier` spelling remains available for
unusual compatibility declarations; opting either its normalization or
manifest into typed dimensional metadata requires the complete typed pair. The
current generated-constraint
compiler supports exactly one scalar value and one scalar residual per
generated specification; a distributed or multi-component generated quantity
requires an explicit extension of that compiler boundary and is not obtained by
switching to the lower-level spelling.
If the target and appended residual have different quantity types, the
specification also supplies the physical reference used to report and scale
that residual:
```cpp
[[nodiscard]] mean_field::dimensions::SpecificEnergyValue
residualReference() const noexcept {
return m_enthalpyReference;
}
```
The return type must be exactly the `QuantityValue` for
`ScalarDescription::ConstraintResidualQuantity`. Omitting this accessor, or
returning the target's quantity instead, makes
`CompilableRootManifestFor<Model, Form>` false. Thus a density target cannot
silently provide the scale for an energy-valued equation. The built-in
`FixedCentralDensity` phase condition is the deliberate special case: its
specific-enthalpy reference is derived from the selected EOS when the
constraint is compiled.
When an integral residual also depends on the coordinate generated by that same specification, use `stellar::state::OwnGeneratedCoordinate`. The compiler resolves that relative name to the specification's exact generated type. Prefer the exported `mean_field::stellar::{state,equation}` names and the `stellar::Reads`, `stellar::Changes`, `stellar::ScalarConstraint`, and `stellar::Derivative` wrappers in ordinary physics code. These wrappers are aliases over the compiler's canonical types: they improve readability without introducing a parallel implementation or weakening any compile-time check.
### Phase condition
A phase condition uses the same vocabulary but generates a solver-border coordinate. It fixes a degeneracy; it is not automatically a new physical invariant.
```cpp
class FixedCentralEnthalpy final {
public:
struct Parameters final {
mean_field::dimensions::SpecificEnthalpyValue hcenter;
};
using ScalarDescription = mean_field::stellar::ScalarConstraint<
mean_field::dimensions::quantity::SpecificEnthalpy,
mean_field::dimensions::quantity::SpecificEnthalpy,
mean_field::dimensions::quantity::SpecificEnthalpy,
"fixed_central_enthalpy.border", "lambda_hc",
"fixed_central_enthalpy.residual", "R_hc">;
using TargetValue = typename ScalarDescription::TargetValue;
using ModelDefinition = mean_field::constraint::ScalarPhaseCondition<
FixedCentralEnthalpy,
"FixedCentralEnthalpy",
mean_field::stellar::Reads<
mean_field::stellar::state::SpecificEnthalpy>,
mean_field::stellar::Changes<
mean_field::stellar::equation::HydrostaticBalance>,
ScalarDescription>;
explicit FixedCentralEnthalpy(Parameters p) : m_target(p.hcenter) {
}
[[nodiscard]] auto target() const noexcept {
return m_target;
}
private:
TargetValue m_target;
};
```
Generated arity is inferred by the role alias: a constitutive law or boundary condition generates no scalar pair, while the three scalar constraint aliases each generate one balanced scalar value/residual pair. This zero-or-one-pair rule is the deliberate current generated-constraint boundary, not a claim that arbitrary-rank new fields are already supported. A malformed normalization or manifest remains inspectable but fails its corresponding completeness query.
### Exact residual and Jacobian providers
A declaration determines the complete provider topology. The nested `EquilibriumPhysics` alias above connects that declaration to its numerical formulas.
Most prepared physics classes keep the simple `Physics(const Specification&)`
constructor. A specification which declares both `state::Density` and
`state::SurfaceShape` in `Reads` may instead request the current physical
density-volume integral through
`stellar::DensityVolumeIntegralContext<Specification>`:
- `integrateDensity(rho)` evaluates the distributed, mapped-volume finite-element
integral and returns `dimensions::MassValue`;
- `linearizeDensityIntegral(deltaRho)` returns its exact density action; and
- `linearizeSurfaceShapeIntegral(deltaShape)` returns its exact geometry action.
Both declarations are mandatory because `integral rho dV` depends on the
deformed volume. A density-only declaration is rejected before the context type
can be formed, so it cannot hide a missing geometry column in the inferred
Jacobian. A future fixed/reference-geometry integral would be a separate,
explicitly named service rather than a weakened form of this one.
The context is a small, copyable, non-owning handle. It exposes neither the
physical core nor FEM objects, uses no heap type erasure, and delegates global
reduction and reusable scratch storage to the physical core. Its numerical
methods are valid in `PrepareAfterPhysical` and subsequent residual, Jacobian,
or border-action work, after the core has prepared the current state; a physics
constructor should only retain the handle. This service is deliberately scoped
to the current core's density-volume integral rather than being an untyped
general-purpose backend escape hatch.
`PreparedFixedBaryonMass` is still an ordinary concrete class. It does not need
a model template, block list, offset table, or MFEM access. A representative
context-using shape is:
```cpp
class PreparedFixedBaryonMass final {
public:
using Report = BaryonMassPreparationReport;
using IntegralContext =
mean_field::stellar::DensityVolumeIntegralContext<FixedBaryonMass>;
PreparedFixedBaryonMass(
const FixedBaryonMass &specification,
IntegralContext integrals
) : m_target(specification.target()), m_integrals(integrals) {
}
template <typename State>
[[nodiscard]] Report PrepareAfterPhysical(const State &state) {
// Only names from stellar::Reads plus this specification's generated
// coordinate are visible here.
const auto density = state.density();
const auto multiplier = state.generatedCoordinate();
m_currentMass = m_integrals.integrateDensity(density);
m_massResidual = m_currentMass.value() - m_target.value();
prepareHydrostaticTerm(multiplier);
m_prepared = true;
return {};
}
template <typename Row>
[[nodiscard]] auto AddResidual(
mean_field::stellar::equation::OwnConstraint,
Row &row
) const {
return row.add(m_massResidual);
}
template <typename Row>
[[nodiscard]] auto AddResidual(
mean_field::stellar::equation::HydrostaticBalance,
Row &row
) const {
return row.add(m_hydrostaticTerm);
}
template <typename Direction, typename Row>
[[nodiscard]] auto AddJacobianAction(
mean_field::stellar::Derivative<
mean_field::stellar::equation::OwnConstraint,
mean_field::stellar::state::Density>,
const Direction &direction,
Row &row
) const {
return row.add(
m_integrals.linearizeDensityIntegral(direction.density()).value());
}
template <typename Direction, typename Row>
[[nodiscard]] auto AddJacobianAction(
mean_field::stellar::Derivative<
mean_field::stellar::equation::OwnConstraint,
mean_field::stellar::state::SurfaceShape>,
const Direction &direction,
Row &row
) const {
return row.add(m_integrals
.linearizeSurfaceShapeIntegral(direction.surfaceShape()).value());
}
// Reads is conservative for all changed equations. This particular
// derivative is mathematically absent, so say that explicitly.
template <typename Direction, typename Row>
[[nodiscard]] mean_field::stellar::StructuralZero AddJacobianAction(
mean_field::stellar::Derivative<
mean_field::stellar::equation::HydrostaticBalance,
mean_field::stellar::state::Density>,
const Direction &,
Row &
) const noexcept {
return mean_field::stellar::zeroDerivative;
}
template <typename Direction, typename Row>
[[nodiscard]] mean_field::stellar::StructuralZero AddJacobianAction(
mean_field::stellar::Derivative<
mean_field::stellar::equation::HydrostaticBalance,
mean_field::stellar::state::SurfaceShape>,
const Direction &,
Row &
) const noexcept {
return mean_field::stellar::zeroDerivative;
}
template <typename Direction, typename Row>
[[nodiscard]] auto AddJacobianAction(
mean_field::stellar::Derivative<
mean_field::stellar::equation::HydrostaticBalance,
mean_field::stellar::state::OwnGeneratedCoordinate>,
const Direction &direction,
Row &row
) const {
return row.add(applyMultiplierDerivative(
direction.generatedCoordinate()));
}
[[nodiscard]] bool IsPrepared() const noexcept {
return m_prepared;
}
private:
// Physics data and helper functions; no solver block bookkeeping.
FixedBaryonMass::TargetValue m_target;
IntegralContext m_integrals;
mean_field::dimensions::MassValue m_currentMass{0.0};
double m_massResidual{0.0};
double m_hydrostaticTerm{0.0};
bool m_prepared{false};
};
```
The hydrostatic helper formula above is a placeholder for the extension's actual physics; the integral and its two directional actions are the real typed service contract. The compiler derives these calls from `Reads` and `Changes`:
- it requests one `AddResidual(EquationTag, Row&)` provider for the specification's own constraint equation and for each distinct equation in `Changes`;
- it requests `OwnConstraint` derivatives with respect to every state in `Reads`; and
- it requests each `Changes` equation's derivatives with respect to every state in `Reads` plus `OwnGeneratedCoordinate`.
The compiler, not the physics class, enumerates and invokes this set. Every Jacobian call receives a direction containing exactly one declared state and a row that can modify exactly one declared equation. Named accessors such as `density()`, `specificEnthalpy()`, and `generatedCoordinate()` are available only when that source is the selected derivative. `value()` is the backend-independent accessor for a one-source extension tag that does not yet have a named convenience accessor.
Every provider returns one of two statements:
- return the token from `row.add(scalar_or_vector)` or, for a residual entry, `row.addEntry(index, value)`; or
- return `stellar::structuralZero` for an intentionally zero residual contribution, and conventionally `stellar::zeroDerivative` for an intentionally zero derivative.
This is stronger than a broad callback that is merely callable. Omitting one inferred overload makes `CompleteStellarEquilibriumPhysicsProvider<Physics, Specification, Model>` false at compile time. Within a callback, adding twice is rejected at runtime. Returning `ContributionAdded` without one addition, or returning `StructuralZero` after an addition, is also rejected immediately. Separate specifications may still add to the same assembled equation; additive composition across specification slots is intentional.
The exact row API exposes no assignment, mutable root vector, block offset, or MFEM alias synchronization. Consequently one specification cannot redirect a derivative to another legal row or erase the physical core or another specification's contribution. The lower-level `SpecificationEquilibriumPhysics` spelling remains available when a concrete implementation genuinely depends on the complete `Model` type, but it uses this same exact adapter and guarantees.
For the current isobaric surface, the pressure condition owns selected rows of the specific-enthalpy equation. Exact residual and Jacobian rows automatically suppress contributions on those replaced rows. A constraint computes its ordinary full hydrostatic contribution; it does not reproduce the surface-row mask.
## Composition and model access
Construction order does not affect the inferred type:
```cpp
auto model = mean_field::model::StellarModel(
LinearBarotrope({.densityPerEnthalpy = 2.0}),
IsothermalSurface({.Tsurface = mean_field::dimensions::TemperatureValue{1.0e6}}),
FixedBaryonMass({.Mbaryon = mean_field::dimensions::MassValue{1.0}}),
FixedCentralEnthalpy({.hcenter = mean_field::dimensions::SpecificEnthalpyValue{0.25}})
);
using Model = std::remove_cvref_t<decltype(model)>;
static_assert(Model::template specificationRoleCount<
mean_field::models::SpecificationRole::invariant> == 1);
const auto &eos = model.equationOfState();
const auto &surface = model.surfaceCondition();
const auto &mass = model.specification<FixedBaryonMass>();
```
`equationOfState()` is always available because a valid model has exactly one constitutive law. `surfaceCondition()` and `specificationForRole<Role>()` are available only when that role is unique. Roles such as integral constraints may occur many times; use `SpecificationsForRole<Role>` at compile time and `specification<ExactType>()` at runtime.
Stable names are identities within a role. Two independently developed invariants therefore choose descriptive stable names; they do not coordinate global numeric ordinals. Reusing a stable name in the same role is rejected at compile time, while the same readable name may intentionally appear in two different roles. Manifest lookup always compares the full `(role, stable name)` identity.
### Coupling constraints to one another
Global constraints are not required to be mutually independent. A specification can refer to another specification in the same model using physics-level owner tags:
```cpp
class CoupledVirialCondition final {
public:
using ModelDefinition = mean_field::integral::FixedScalarWithMultiplier<
CoupledVirialCondition,
"CoupledVirialCondition",
mean_field::stellar::Reads<
mean_field::stellar::state::Density,
mean_field::stellar::state::GeneratedCoordinateOf<FixedBaryonMass>>,
mean_field::stellar::Changes<
mean_field::stellar::equation::HydrostaticBalance,
mean_field::stellar::equation::ConstraintOf<FixedBaryonMass>>,
VirialScalarDescription>;
// Parameters, target(), and the two local physics packages follow the
// same pattern as an uncoupled scalar constraint.
};
```
`GeneratedCoordinateOf<FixedBaryonMass>` means “read the scalar coordinate owned by this exact specification type.” `ConstraintOf<FixedBaryonMass>` means “my generated coordinate changes that specification's scalar equation.” `OwnGeneratedCoordinate` and `OwnConstraint` are the corresponding relative names for the declaring specification. These declarations generate ordinary `stellar::Derivative<Equation, State>` calls, so cross-constraint formulas use the same exact residual/Jacobian and preconditioner protocols as every other edge. For a cross-generated direction, the equilibrium view's generic one-source accessor is `value()`; a border-preconditioner direction may use `values()` or `generatedCoordinate<Owner>()`.
The compiler resolves owner references after collecting the complete canonical specification pack, so declaration order is irrelevant. A referenced owner that is absent, does not generate the requested coordinate/residual, or cannot be mapped into the final form makes symbolic compilation fail. It is never converted into a runtime lookup or silently omitted.
## Capability ladder
Description is deliberately easier than executable solver support. Each rung is
an ordinary compile-time capability query, so an unsupported physics component
is rejected at the public overload boundary instead of producing an error deep
inside a constructor or solver body.
For a model declaration, the first two rungs are:
```cpp
static_assert(mean_field::models::SelfDescribingModelSpecification<FixedBaryonMass>);
static_assert(mean_field::models::ModelSpecification<FixedBaryonMass>);
static_assert(mean_field::operators::StellarEquilibriumSpecificationCompilable<FixedBaryonMass>);
static_assert(mean_field::operators::StellarEquilibriumSymbolicallyCompilable<Model>);
static_assert(mean_field::models::CompleteGeneratedScalarDimensionsFor<FixedBaryonMass>);
static_assert(mean_field::models::CompleteGeneratedNormalizationFor<FixedBaryonMass>);
static_assert(mean_field::normalization::CompleteGeneratedPhysicalRieszNormalizationFor<FixedBaryonMass>);
static_assert(mean_field::models::CompleteGeneratedManifestFor<FixedBaryonMass>);
using Form = mean_field::operators::CompiledStellarEquilibriumForm<Model>;
// This example's new surface has no manifest/runtime adapter yet.
static_assert(!mean_field::operators::CompilableRootManifestFor<Model, Form>);
// These become true after the per-specification runtime, EOS core, and surface
// implementations are added. They are intentionally false for this example.
static_assert(!mean_field::operators::StellarEquilibriumPhysicsAvailableFor<
FixedBaryonMass, Model>);
static_assert(!mean_field::operators::hasCompleteStellarEquilibriumRuntime<Model>);
static_assert(!mean_field::operators::hasStellarEquilibriumCoreRuntime<Model>);
```
`Model::hasCompleteEquilibriumDeclaration` reports only that the model's physics declarations are structurally complete and balanced. It deliberately makes no claim about backend support. The clearly named query for block and Jacobian compilation is `StellarEquilibriumSymbolicallyCompilable<Model>`; `StellarEquilibriumSystemCompilable<Model>` remains its compatibility spelling. Only `CompiledStellarEquilibriumSystem<Model>` exposes an equilibrium-system compilation classification. This distinction lets an astronomer write and inspect a new physical declaration even when one of its physics names has not yet been mapped to a numerical block.
Once a model has an executable core, surface runtime, manifest, and all of its
per-specification residual/Jacobian actions, it satisfies
`equilibrium::StellarEquilibriumModel` and can be discretized into a `Problem`.
The remaining solver-facing capabilities are then checked on that inferred
problem type:
```cpp
// The selected discretization prescription has a valid preparation path.
static_assert(mean_field::normalization::NormalizableStellarEquilibriumProblem<Problem>);
using PhysicalRieszDiscretization = mean_field::equilibrium::StellarDiscretizationFor<
mean_field::normalization::PhysicalRieszDiagonal<>>;
using PhysicalRieszProblem = mean_field::equilibrium::StellarEquilibriumProblem<
Model, PhysicalRieszDiscretization>;
// These stronger queries are specifically for the Physical Riesz path.
static_assert(mean_field::normalization::PhysicalRieszStellarEquilibriumProblem<
PhysicalRieszProblem>);
static_assert(mean_field::normalization::NormalizableStellarEquilibriumProblem<
PhysicalRieszProblem>);
static_assert(mean_field::normalization::PhysicalRieszStellarEquilibriumCore<
typename PhysicalRieszProblem::PhysicalCoreType>);
// The EOS-specific material/surface surrogate supports this exact core.
static_assert(mean_field::preconditioning::MaterialSurfacePreconditionerProblem<Problem>);
static_assert(mean_field::preconditioning::StellarStructurePreconditionerProblem<Problem>);
// Every generated border has an action, and the structure block is supported.
static_assert(mean_field::preconditioning::CompleteSpecificationBorderActionsFor<Problem>);
static_assert(mean_field::preconditioning::DefaultStellarPreconditionerAvailableFor<Problem>);
```
The complete ladder is:
1. **Model description:** the object is constructible and has one valid, self-owned definition.
2. **Blocks and Jacobian:** its block lists are valid, generated rows and columns balance, and every declared edge endpoint exists in the final model. The compiler performs two passes, so one constraint may name a block generated by another constraint without depending on declaration order.
3. **Executable equilibrium root:** `StellarEquilibriumCoreRuntime<EOS>` selects the concrete physical `CoreType` for the constitutive law. Surface compilation/runtime, root-manifest construction, and every specification's nested `EquilibriumPhysics` package (or core-authorized library backend entry) are checked separately. For an ordinary nested package, `CompleteStellarEquilibriumPhysicsProvider` proves that every compiler-enumerated residual row and derivative has an exact provider. Each call receives one read-only source and one additive-only row; the current isobaric row-replacement mask is applied by that row. Passing these checks makes one `PreparedVariadicStellarEquilibriumOperator<Model>`; it does not select a hand-written class for the particular constraint pack.
4. **Normalization:** `NormalizableStellarEquilibriumProblem<Problem>` means the prescription stored in the discretization has a valid `prepareNormalization(problem)` operation. `Unnormalized` is the identity path and therefore remains available to a lean alternate core. A Physical Riesz discretization additionally requires `PhysicalRieszStellarEquilibriumCore<Problem::PhysicalCoreType>`, a structural contract for the density, enthalpy, gravity-gradient, gravity-potential, and surface-deformation maps used to assemble the physical Gram diagonals. It also requires complete per-specification physical-scale contributions. A new core can opt in by exposing that physical interface; it does not inherit from or name the Polytrope core.
5. **Material and stellar-structure preconditioner:** `MaterialSurfacePreconditionerProblem<Problem>` checks that the EOS-specific material/surface backend is registered for the problem's exact selected core type. `StellarStructurePreconditionerProblem<Problem>` is the corresponding public capability for the default coupled material/surface-plus-gravity structure block; it currently inherits the same support boundary.
6. **Generated border and full default preconditioner:** `CompleteSpecificationBorderPhysicsProvider` proves the exact border-incident derivatives for one physics action. `CompleteSpecificationBorderActionsFor<Problem>` folds that requirement over the model's specifications. `DefaultStellarPreconditionerAvailableFor<Problem>` is the final conjunction of a discretized equilibrium problem, complete per-specification border actions, and a supported stellar-structure block. `makePreconditioner(problem)` is available only at this rung.
No rung is specialized for a complete EOS/surface/constraint combination. The
model type determines the packs, the compiler folds their declarations, and
each numerical layer folds the corresponding per-component hooks. If a query
fails, implement the missing hook for the individual EOS, surface, integral, or
phase condition; do not weaken the query and do not add a model-pack
specialization.
### Adding another normalization family
A normalization prescription is a compile-time discretization choice, not a
model constraint. Adding one does not add cases to `discretize`, the stellar
operator, or the solver-facing adapter. Its public
`NormalizationCompilation<Prescription, Form>` specialization owns both the
complete coordinate plan and the early runtime-compatibility declaration for
the selected physical core and specification pack. The library independently
validates that the advertised plan covers every inferred value and residual
block exactly once.
Most new policies use only the public problem/manifest interface when they
prepare their diagonal factors. They can reuse
`RuntimePreparedNormalizationCompilation` rather than spelling core or
specification concepts:
```cpp
namespace my_normalization {
class UniformDiagonal final
: public mean_field::normalization::NormalizationPrescriptionTag {
public:
UniformDiagonal(double stateFactor, double residualFactor);
[[nodiscard]] double stateFactor() const noexcept;
[[nodiscard]] double residualFactor() const noexcept;
};
} // namespace my_normalization
namespace mean_field::normalization {
template <typename Form>
requires mean_field::utils::blocks::block_form_is_valid_v<Form>
struct NormalizationCompilation<my_normalization::UniformDiagonal, Form>
: RuntimePreparedNormalizationCompilation<
my_normalization::UniformDiagonal,
Form> { };
} // namespace mean_field::normalization
```
The policy's namespace then provides
`prepareStellarNormalization(const UniformDiagonal&, const Problem&) ->
DiagonalNormalization`. It is found from the exact policy argument carried by
`Problem::NormalizationPrescriptionType`; no central registry or built-in-policy
switch is edited. The generated plan labels every block with
`RuntimePreparedCoordinate<UniformDiagonal>` rather than falsely claiming an
identity or Physical Riesz formula, and the returned diagonal is dimension-checked
against the complete inferred problem. `discretize` rejects a policy
whose compilation omits `runtimeAvailableFor`, and
also rejects a third-party runtime policy whose plan does not name that exact
policy on every coordinate. Thus merely providing a preparation function cannot
bypass or contradict the compile-time plan. The same `discretize` boundary
rejects a policy whose preparation operation is absent or returns the wrong
type, before a solver-facing problem is constructed. A policy that requires private facilities
of a particular physical core writes its own `runtimeAvailableFor<Core,
Specifications>` predicate in the same compilation specialization; Physical
Riesz is the reference example. Ordinary EOS, surface, and constraint authors
do not use this extension point—their dimensional scalar wrappers continue to
generate the appropriate per-block normalization metadata automatically.
## Radial seeds and border preconditioning
The optional numerical hooks also compose per specification. A specification that intentionally leaves a spherical seed unchanged can say so without touching the seed compiler:
```cpp
using RadialProjection = mean_field::seed::projection::Use<
mean_field::seed::projection::NoStateChange>;
```
A specification with a generated coordinate supplies a similarly wrapped physics rule. The rule receives `RadialProjectionScales`, `RadialProjectionState`, and only its own generated coordinate. It does not calculate block offsets or inspect the other constraints. `RadialProfileProjectableModel<Model>` is true only when every specification has a complete rule and exactly one rule supplies the radial mass scale. Thus a newly introduced EOS, surface condition, or constraint cannot be advertised as projectable and then fail deep inside the function body.
For an ordinary generated constraint, no second Jacobian implementation is
needed for border preconditioning. The default adapter projects the same exact
`AddJacobianAction` providers from `EquilibriumPhysics` onto the subset whose
row or source is a generated border. This is why the `FixedBaryonMass`
declaration above needs only its `EquilibriumPhysics` alias: the residual,
Jacobian, and default border preconditioner have one source of numerical
formulas.
An advanced implementation may deliberately provide a different border
approximation. In that case it opts in explicitly:
```cpp
using SpecificationBorderPhysics =
mean_field::preconditioning::LocalSpecificationBorderPhysics<MyPreparedBorderAction>;
```
The action uses the same astronomy-facing `stellar::Derivative<Equation, State>` vocabulary as the equilibrium Jacobian. For example, a phase condition declared with `Reads<SpecificEnthalpy>` and `Changes<HydrostaticBalance>` has two border-incident derivatives:
```cpp
class MyPreparedBorderAction {
public:
explicit MyPreparedBorderAction(const PreparedMyPhaseCondition &physics);
template <typename Direction, typename Row>
[[nodiscard]] auto ApplyJacobianAction(
mean_field::stellar::Derivative<
mean_field::stellar::equation::OwnConstraint,
mean_field::stellar::state::SpecificEnthalpy>,
const Direction &direction,
Row &row
) const {
return row.add(
evaluatePhaseDerivative(direction.specificEnthalpy()));
}
template <typename Direction, typename Row>
[[nodiscard]] auto ApplyJacobianAction(
mean_field::stellar::Derivative<
mean_field::stellar::equation::HydrostaticBalance,
mean_field::stellar::state::OwnGeneratedCoordinate>,
const Direction &direction,
Row &row
) const {
return row.add(
evaluateMultiplierAction(direction.generatedCoordinate()(0)));
}
};
```
The framework derives the full derivative list from `Reads` and `Changes`, then partitions it into structure-to-border, border-to-structure, and border-to-border edges. It invokes only the border-incident edges. Cross-constraint edges are partitioned in exactly the same way, including edges between two generated borders.
A purely structure-to-structure derivative is checked separately. The default
structure preconditioner accepts it only when the selected physical core names
that exact `(specification, coupling)` as a backend capability or the nested
equilibrium provider returns `stellar::StructuralZero`. A custom nonzero term
on even an otherwise familiar base edge therefore makes
`DefaultStellarPreconditionerAvailableFor<Problem>` false instead of being
silently dropped.
Each direction contains exactly one source and each row can update exactly one destination. For this example, asking the first direction for `density()` or the second row to write a gravity-potential equation is ill-formed. An exact-zero border derivative returns `stellar::zeroDerivative`. Missing an incident overload makes `CompleteSpecificationBorderPhysicsProvider<Action, Specification, Problem>` false at compile time; `PreparedSpecificationBorderPhysicsActionFor` additionally checks construction and move requirements. The single-use `row.add(...)` token has the same duplicate and result-consistency checks as equilibrium assembly.
For an explicit approximation, the action constructor receives only the
prepared equilibrium physics for its own specification. It can snapshot
state-dependent coefficients without access to the enclosing problem, physical
core, or other constraints. `LocalSpecificationBorderPhysics<Action>` is the
common wrapper for a concrete local class. `SpecificationBorderPhysics<ActionTemplate>`
is available when the action genuinely needs the inferred `Problem` type; both
names use the same adapter and neither reimplements pack traversal.
The library handles problem binding, operation partitioning, offsets, alias synchronization, surface-row ownership, and aggregation. The preconditioner lifecycle includes the prepared-operator generation, so changing state-dependent contribution data invalidates and rebuilds the border Schur complement even when the caller reuses the same dependency stamps.
These contracts establish structural completeness and safe composition; they do not establish preconditioner quality. The current default structure solve and generated-border Schur approximation are provisional numerical choices. A problem satisfying `DefaultStellarPreconditionerAvailableFor` has every required action and a registered backend, but it may still be poorly conditioned or ineffective for a new regime. Iteration counts, scaled spectra, parameter continuation behavior, and nonlinear convergence must be measured separately for each important physical family.
## What works end to end today
As of the current checkpoint:
- arbitrary well-formed self-described specifications can form distinct canonical `StellarModel` types, subject to the model-pack role and balance contracts;
- generated scalar blocks, residual rows, and Jacobian edges are inferred from `stellar::Reads` and `stellar::Changes`, including named edges between constraints;
- the residual/Jacobian runtime and generated-border preconditioner enumerate those inferred rows and edges and require exact providers or explicit structural zeros;
- generated Physical Riesz declarations and generated manifest metadata are projected generically, while Physical Riesz field diagonals are available to any selected core satisfying `PhysicalRieszStellarEquilibriumCore`;
- the variadic outer layers currently wrap a fixed five-field barotropic physical core: density, surface deformation, gravity gradient, gravity potential, and specific enthalpy;
- each generated constraint currently adds exactly one scalar value block and one scalar residual block around that core;
- the executable equilibrium kernels are registered for `eos::Polytrope` with `surface::Isobaric`;
- the default material/surface and stellar-structure preconditioner kernels are likewise registered for that Polytrope/Isobaric backend and its exact physical core;
- per-specification runtime and prepared border actions exist for `FixedTotalMass`, `FixedAngularMomentum`, and `FixedCentralDensity`; and
- `makePreconditioner(problem)` is exposed only when `DefaultStellarPreconditionerAvailableFor<Problem>` proves both the structure backend and every generated border action are present.
The five-field statement is a real boundary, not merely a missing convenience alias. A scalar constraint over those existing fields can compose without changing the core. A genuinely new distributed field—magnetic induction, temperature, composition, or another PDE state—requires extending the shared physical-field vocabulary and mapping, the selected executable core and discretization, its residual/Jacobian implementation, normalization metadata, manifest, and the applicable structure preconditioner. Supplying a backend block type in `Reads` does not by itself make that field part of the physical core. This work is still per new field/equation family, not per complete combination of constraints.
The nonbarotropic EOS and isothermal-surface mocks in the compile-contract tests are symbolic coverage. They prove that EOS choice, surface choice, and constraint packs produce distinct canonical types and correctly inferred block/Jacobian structures; they are not executable stellar models and do not claim a compatible five-field core or default preconditioner. Their rejection by `equilibrium::StellarEquilibriumModel` and `discretize` is intentional.
A new EOS or surface can therefore be described and type-checked today, but `discretize` will reject it until its per-EOS core or per-surface compilation/runtime support (including carrier/manifest handling) is registered. A new integral or phase condition can obtain its scalar block/Jacobian pair, normalization, and ordinary `target()` manifest structure from `ModelDefinition`, but still needs its residual/Jacobian runtime. The ordinary constraint places that concrete implementation on itself as `EquilibriumPhysics = operators::LocalSpecificationEquilibriumPhysics<MyPreparedPhysics>`; its exact providers are reused automatically by the default generated-border preconditioner. Only a deliberately distinct border approximation adds `SpecificationBorderPhysics`. Neither path specializes a combination-level registry.
The aggregate `StellarEquilibriumRuntimeContribution` registry is not an alternative astronomy-facing API. It can access the complete model, FEM objects, mapper, dependency stamps, and physical core, so an entry is selected only when the exact specification also appears in the selected concrete core type's `BackendSpecifications` list. A raw specialization—or a custom EOS that merely reuses the built-in core type—cannot add itself to that core's list and is therefore ignored. A custom core author may authorize its own backend entries in that single list; if an authorized entry and a nested `EquilibriumPhysics` package both exist for the same specification, the model is rejected as genuinely ambiguous. Ordinary EOS, surface, and constraint authors should use the restricted nested packages and never manage this list.
An alternate executable core may choose the identity `Unnormalized` path without implementing Physical Riesz maps. Selecting `PhysicalRieszDiagonal` for that same core fails `PhysicalRieszStellarEquilibriumProblem` and `NormalizableStellarEquilibriumProblem` cleanly. Likewise, an executable problem whose EOS/core pair has no material-surface backend fails `MaterialSurfacePreconditionerProblem`, while a problem with one missing constraint action fails `CompleteSpecificationBorderActionsFor`; neither failure requires nor invites a combination-specific fallback. These are availability and structural-correctness claims, not evidence that the current preconditioner will deliver acceptable Krylov or nonlinear convergence.
Those remaining hooks are per physics component. Adding `FixedMagneticEnergy` over existing state fields should require work for `FixedMagneticEnergy` itself. Adding a genuinely new magnetic field/equation additionally requires the shared field-family work listed above—not new implementations for `Polytrope + Isobaric + FixedTotalMass + FixedMagneticEnergy`, then another for every other constraint combination. A converged rotating solution and its nonlinear solver remain downstream goals; the compile-time architecture and provisional preconditioner do not, by themselves, establish that convergence result.

View File

@@ -0,0 +1,90 @@
# Optional central-density constraint
The n=1 sandbox now supplies central density only to its Lane–Emden seed. Its
equilibrium model fixes the polytropic EOS, surface pressure, total mass, and
angular momentum. The existing public API already supports this combination;
no operator, normalization, preconditioner, or solver API changes are needed.
`constraint::FixedCentralDensity` remains an explicit, optional model
specification. For n=3 it can select the scale along the nonrotating homology
family. Omitting it remains permitted and may expose a singular or poorly
conditioned problem. Neither the model nor the solver silently inserts a phase
constraint or regularization based on the polytropic index. Seed-only central
density sets an initial condition, not an additional equilibrium equation.
The hypothesis is that fixing the spherical central density together with K, M,
and nonzero J can distort the interior of an n=1 equilibrium. The implemented
constraint fixes central enthalpy and adds a scalar source to the hydrostatic
row; a small bordered residual can therefore coexist with a larger physical
residual after that source is removed. This is separate from the late Krylov
failure: the initial no-phase J=.01 control retained that failure while reducing
the unbordered residual, with negligible change in virial balance.
## Completed matched controls
At n=1, J=.05, the phase comparison uses the same mesh, Lane–Emden seed,
normalization, preconditioner, restart length 40, and stopping controls. Physical
measurements below use quadrature order 18 and each run's last accepted state.
| Measurement | Central constraint, R40 | No central constraint, R40 | No central constraint, R160 |
|---|---:|---:|---:|
| Sampled maximum EOS mismatch / density scale | .00933951 | .000430594 | .000430592 |
| Sampled Bernoulli range | .0145751 | .00130398 | .00130398 |
| Unbordered normalized residual | 4.54227e-6 | 6.03609e-9 | 3.38036e-11 |
| P(h) energy virial error | 3.01617e-7 | 3.06913e-7 | 3.07200e-7 |
| P(h) force virial error | 3.18803e-7 | 3.24099e-7 | 3.24382e-7 |
| Absolute mass error | 1.22944e-11 | 1.23133e-11 | 1.74860e-13 |
| Absolute angular-momentum error | 1.71698e-12 | 1.72180e-12 | 1.54182e-14 |
Removing the phase lowers the sampled maximum EOS mismatch by 21.69 times and
the Bernoulli range by 11.18 times, while preserving virial errors well below
the required 1e-5 milestone. Actual angular velocity changes only from
.185891548249 to .185891547385. These matched observations support removing
the n=1 phase to improve interior consistency. The extrema are quadrature
samples, not pointwise error certificates or errors against an independent
rotating reference solution.
Both R40 runs accept five full Newton steps and then fail the same late linear
convergence gate: after 200 linear iterations their true relative residuals are
about .505 against the requested .03. Phase removal does not cure that failure.
The separate no-phase R160 run accepts seven full Newton steps and meets the
requested nonlinear relative tolerance 1e-8 with absolute tolerance zero. Its
final normalized residual is 3.38036e-11. The larger Krylov restart window and
removal of the physical constraint address different observed problems.
Data provenance in the audit workspace: the phased baseline is
`diagnostics/campaign_2026-09-16/n1_J0p05`; the matched and larger-window controls
are `diagnostics/numerical_campaign_2026-09-16/controls/n1_J0p05_no_central_R40`
and `n1_J0p05_no_central_R160`. Measurements come from `final_physical.csv`;
iteration outcomes and settings come from `newton.csv` and `metadata.txt`.
These controls use the existing diagnostic driver's optional model constraint;
the subsequent combined build and focused tests are recorded below.
Higher-spin and higher-index controls remain separate work. J or angular
velocity in reference units is not itself a measured fraction of critical
rotation. These results do not establish high-rotation robustness or change the
optional n=3 constraint semantics described above.
## Focused regression status
The added user-API regression covers the previously missing explicit-seed,
no-phase context construction and solver borrowing/release path. Existing tests
already cover the square fixed-J root and its Jacobian column. This lifecycle
test performs no Newton solve and makes no physical-convergence claim. Retain
the existing phased n=3 tests; unphased n=3 convergence is not a requirement.
The combined source at `b3a752b` builds the sandbox, tests and diagnostic. All
three context/root tests pass (61 assertions), including the new test
`An Explicit Lane Emden Seed Builds A Fixed Angular Momentum Context Without Fixing Central Density`
(`"[user-api][context][seed]"`) and the existing
`Fixed Angular Momentum User API Generates Rotation And Its Composable Solver Border`
and `Fixed Angular Momentum Root Uses Its Generated Angular Velocity In Every Physical Row`
tests. These checks ran in the original build directory on
`research/combined-20260916`, not as an independent build of this isolated
hypothesis worktree.
The combined diagnostic at `c88baa1` also converges for the matching nonrotating
n=1 model in six full steps: F=1.65157e-13, with every q14/q18 virial check
below 3.731e-7. This is a physical counterpart of the sandbox configuration;
it uses the diagnostic stopping controls recorded in the campaign manifest.
See `NUMERICAL_CAMPAIGN_2026-09-16.md` for the integrated results and raw artifacts.

View File

@@ -0,0 +1,676 @@
# Coupled harmonic-surface convergence study
The clearest measured improvement is the existing gravity-Schur inverse:
at matched saved states and a checked full linear tolerance of .003, total
construction/solve/check cost falls from 53.31 to 31.17 seconds for n=3,J=0,
and from 118.62 to 82.31 seconds for n=1.5,J=.1. These are frozen linear
improvements, not demonstrated complete-model speedups. The new surface/scalar
Schur correction is algebraically effective but is not the best total-cost
candidate in these tests and can worsen finite-step behavior.
The live rotating n=3 comparison also gives a substantive improvement:
existing stellar LDU with gravity refinement reaches a 12.687-times smaller
residual than gravity refinement alone after ten updates, at 14.593% more
Newton time. The energy h-pressure virial improves from 7.184e-5 to 1.811e-5,
but the full virial milestone is still unmet and small-step stagnation returns.
Density remains independent and no positivity enforcement is introduced.
Nonlinear progress is limited by more than Krylov accuracy. The n=2 control
stalls with positive sampled density and both virials below 1e-5. Its gravity
trial-path correction buys an initial improvement but no durable recovery.
At n=3, measured weak coupled direction differences are dominated by changes
in the surface monopole compensated by interior fields. Better treatment of
this coupled response is a stronger next hypothesis than positivity repair.
Physical xz/xy slices are implemented, exported from unchanged saved fields,
checked at two display resolutions and visually inspected. The rotating
n=1.5 model is smoothly oblate but remains unconverged and misses the virial
milestone. Images, linear histories, raw results and audits are linked below.
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 evaluates 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 the specifications written before each adaptive extension are
recorded below. Defaults and the physics-facing API are unchanged.
## Completed nonlinear controls
The retained-artifact audit passes all five screen cases: provenance, complete
output hashes, block accounting, reported full linear gates and independently
recomputed virial accounting. Every case exhausts twelve updates; none meets
its nonlinear stopping threshold. The audit checks the production linear
reports, not a fresh FEM application of every live Newton Jacobian.
| Case | Final normalized residual | Newton seconds | Total Krylov iterations | Energy / force h-pressure virials, q18 |
|---|---:|---:|---:|---:|
| n=2, J=0, eta=.03 | 8.85263e-6 | 742.74 | 1009 | 3.25447e-7 / 2.24560e-6 |
| n=3, J=0, eta=.03 | 8.24392e-4 | 499.89 | 429 | 9.46671e-5 / 6.20929e-5 |
| n=3, J=0, eta=.003 | 5.50731e-4 | 734.09 | 821 | 2.23846e-4 / 1.98912e-4 |
| n=1, J=.1, eta=.03 | 5.83293e-3 | 310.43 | 226 | 3.23282e-4 / 3.36216e-4 |
| n=1.5, J=.1, eta=.03 | 7.22567e-5 | 550.70 | 717 | 5.10711e-5 / 5.20697e-5 |
The nonrotating initial norms are 3.81795e-4 and 3.09931e-3 respectively;
actual stopping thresholds are 3.81795e-12 and 3.09931e-11. The rotating
initial norms are .0857344 and .139488, with thresholds 8.57344e-10 and
1.39488e-9. q14/q18 differences in all six nonrotating h-pressure
virial errors are below 8e-14 absolute. This quadrature agreement does not
establish a physical equilibrium or pointwise accuracy.
After n=2's second update, ten more updates reduce its residual only 2.112%.
Its last alpha is 1/256. Every rejection is insufficient residual decrease;
the final squared norm is 94.770% Poisson and 4.076% gravity-gradient error.
This is a useful globally balanced intermediate model, but a stalled
nonlinear solve and not an established discrete residual floor.
For n=3, the tighter tolerance lowers the endpoint residual by 33.20%, but
requires 46.85% more Newton time and 91.38% more Krylov iterations. It follows
a different nonlinear trajectory, so these are equal-update-budget outcomes,
not a matched-state preconditioner comparison. The control's final squared
norm is 79.927% Poisson, 13.854% gravity gradient, and 6.144% closure. The
tighter case instead has 71.329% closure and 25.876% Poisson. Its smaller
residual coexists with worse virials and a smaller final alpha (1/32 versus
1/4). Linear accuracy alone has not resolved the nonlinear obstruction.
Both n=3 runs continue below their earlier eight-update endpoints; those
endpoints were not demonstrated floors. Their final unbordered norms exceed
bordered norms by only .180% and .229%, although the artificial central force
still needs to be reported and may matter locally.
When the full Jacobian is the derivative of the prepared residual, a direction
with ||J p + F|| <= eta ||F|| obeys
F dot J p <= -(1-eta) ||F||^2.
Thus both eta=.03 and .003 give strict infinitesimal descent. Small accepted
steps despite a passing linear gate motivate measurements of finite-step
curvature, preparation validity and tangent consistency; a faster inner solve
alone need not remove that limitation.
The rotating n=1 case ends at alpha=1/65536, with 26 pressure-preparation
rejections and no metric rejections. The n=1.5 case has seven of each and
ends at alpha=1/64. Its first eight updates reach 7.60346e-5; four further
updates give only a 4.97% reduction. These are distinct obstructions, not
evidence that every difficult model is failing its linear solve.
### Interior checks and residual location
The n=2 endpoint has positive sampled density (minimum 2.93907e-4), and
its density-pressure energy/force virials also pass: 2.49026e-6/5.70105e-7.
It supplies a stalled control independent of a sampled negative-density
obstruction. This is not a pointwise positivity certificate.
| Case | EOS density RMS / sampled density scale | Bernoulli RMS / sampled h scale | Hydrostatic-gradient RMS | Minimum sampled map determinant |
|---|---:|---:|---:|---:|
| n=2, J=0 | 1.87717e-4 | 2.80766e-4 | .0264341 | .982421 |
| n=3, eta=.03 | 3.52140e-4 | 2.30017e-3 | .398054 | .999838 |
| n=3, eta=.003 | 3.69501e-4 | 2.65289e-3 | .479759 | .943956 |
| n=1, J=.1 | 1.26849e-3 | 2.21774e-3 | .104394 | .938419 |
| n=1.5, J=.1 | 1.69365e-4 | 6.32866e-4 | .0366157 | .955286 |
These q18 volume observations are sampled error measures, not mesh-convergence
results. Gradient RMS is in the diagnostic's G=M_reference=R_reference=1
units; it is not a relative percentage. Good virials do not remove these
interior defects. Density-pressure virials are undefined for the two rotating
screens because sampled density is negative; their h-pressure virials remain
defined and are reported without modifying either independent field.
A separate source-derived row map locates the saved normalized Poisson
residual: 84.437% of its squared norm is stellar at n=2 capture seven,
99.9768% for n=3 control, 99.9995% for n=3 tight, and over 99% for both
rotating captures. The n=2 envelope alone contributes 70.602%. The stalled
norm cannot be explained solely by exterior rows. These are algebraic
residual-row shares, not pointwise div(g)-4*pi*rho errors. The mapping and
dependency/provenance caveats are recorded in the evidence directory's
`poisson_regions/README.md`.
Saved nonrotating surface directions also do not support translation as their
dominant component: at capture seven, l=1 contributes only .0086253%,
.0000077557% and .000103632% of squared normalized surface-direction norm for
n=2, n=3 control and n=3 tight. Degrees zero and four dominate. Physical scale
recovery and the small COM drift are documented in `translation_check/README.md`;
this does not prove that the Jacobian has no weak translational response.
## Adaptive follow-up, specified before execution
The completed n=2 control has energy/force enthalpy virials 3.25e-7/2.25e-6
but a residual of 8.85e-6 after twelve updates. At captured update seven,
94.42% of squared residual is Poisson balance and 4.45% gravity-gradient
relation. All observed rejections there are insufficient decrease; pressure
preparation has not failed. This motivates a gravity-path comparison in the
current harmonic space, independently of earlier nodal-surface conclusions.
Restart both raw and gravity-curvature Newton from the same update-three
physical capture, with six updates, eta=.03, and a shared absolute residual
target 1e-12. Initial guesses are installed through an explicit transactional
experiment hook, separate from the read-only diagnostic callback. Coordinate
transfer checks names, sizes, discretization metadata, mesh and saved hashes;
captured/unconverged iterates require an explicit experimental override.
Gravity-curvature correction retains the full coupled equations and Newton
direction and changes only the prepared trial path. Gravity elimination is
deferred until per-iteration reporting distinguishes its reduced and lifted
full linear defects and its completed initial state.
Frozen tests at that same n=2 capture compare gravity refinement, a new
surface-plus-scalar approximate Schur inverse, and their combination at
eta=.003. Repeat the combined candidate at eta=1e-7 to measure attained
accuracy within a 300-iteration budget, not assert an arithmetic floor.
Test the combined candidate at n=3 update seven separately. Each benchmark
also runs a fresh default inverse on the identical RHS and physical Jacobian.
Setup costs and internal Jacobian applications belong to the comparison.
The rotating n=1,J=.1 control initially takes a full update, then its accepted
alpha falls below .001 by update six, with pressure-preparation rejections.
Add a combined inverse benchmark at its update-seven capture and eta=.003,
including the same raw trial grid. This separates the rotation obstruction
from n=2's gravity-dominated merit rejection without changing admissibility.
The n=1.5,J=.1 control reaches 7.60e-5 after eight updates, then needs alpha
1/512 with both pressure and metric rejections. Also compare the combined
inverse at its final saved state, once its original twelve-update budget is
complete. This is the combined higher-index/rotation obstruction; it is not
assumed to be a failed linear solve, since its update-eight linear gate passes.
Source review also identifies the existing `stellar-ldu-gravity-schur` policy
as a distinct control: it introduces material/gravity feedback that the
independent subsystem policy omits. Add frozen n=2 and n=3 comparisons at
the same captures and eta=.003, with n=3 raw trial observations. The existing
material inverse already includes the exact prepared h-to-density closure
derivative, so a large nonlinear closure residual must not be described as
proof of a missing EOS cross derivative. Frozen block defects and finite-step
closure remainders distinguish those possibilities.
The live gravity-path comparison initially accepts an eight-times-larger step
but returns to smaller steps by its third update. Before the frozen campaign,
extend raw trial observations to the eta=1e-7 n=2 benchmark as well: if that
linear accuracy is attained, its trial data can test whether a more accurate
direction relieves curvature. A failed linear gate will remain labeled as
such, regardless of whether a sampled nonlinear trial happens to decrease.
The small Schur block contains all 25 surface parameters and every generated
scalar. Its field inverse is the unbordered structure inverse; restricting an
already scalar-bordered inverse could spuriously constrain the field solve.
Singular/ill-conditioned coarse blocks are reported, never silently repaired.
The implementation is frozen-state only and must be reconstructed for a new
Jacobian. No changed live default is implied by a successful frozen benchmark.
Saved linear directions receive optional raw trial observations on a fixed
alpha grid. The squared-merit screen matches production's sufficient-decrease
formula, but the sparse grid is not a replay of its adaptive line search.
Remainder scalars are direct FEM observations; saved Jp, RHS and correction
allow independent verification of the linear defect and merit slope.
## Additional n=3 linear control, specified before execution
The frozen n=3 combined gravity/surface-scalar candidate passes eta=.003
in 41 iterations versus 99 for baseline, with 37.609 versus 51.077 Krylov
seconds. Its construction raises total setup/solve/check cost to 65.629
versus 53.169 seconds. This favorable iteration count cannot yet be assigned
to the surface correction: the same-state n=3 gravity-only ablation is
missing. Before recommending coarse-setup optimization, add exactly that
control with the same snapshot, RHS, target and 300-iteration cap, and a
fresh baseline. No additional raw trial grid is needed for this attribution.
The isolated branch is `research/n3-linear-ablation-20260919`, with case
manifest `convergence_linear_followup_cases_2026-09-19.json`.
The completed n=1.5,J=.1 frozen pair subsequently gives the first clear
combined-candidate total-cost improvement: 246 to 95 iterations and 117.925
to 101.760 setup/solve/check seconds, with both eta=.003 gates passing and
the same largest sampled acceptable alpha=1/16. Add its matched gravity-only
control to the same follow-up manifest before attributing this 13.71% time
reduction to the new surface block. This two-case attribution hypothesis is
isolated on `research/gravity-coupling-ablation-20260919`; the original n=3
specification branch is retained. These controls add no new nonlinear runs
or trial grids.
## Live n=3 field-feedback follow-up, specified before execution
At the completed frozen n=3 control capture, the existing
`stellar-ldu-gravity-schur` policy reduces 99 to 41 Krylov iterations and
53.190 to 35.200 setup/solve/check seconds. Both eta=.003 gates pass.
Its largest sampled acceptable alpha remains 1/4, with F_trial/F_base
.674223 versus baseline's .702686; its full-step ratio is 2.77979 versus
7.42157. This is promising frozen evidence, not a live speedup or proof
that the policy transfers to rotation or removal of the central border.
Before executing the rotating compatible-family control, pair it with the
same ten-update case using this field-feedback inverse. Only the inverse
changes: both retain n=3, J=.035, K factor=.99, no central phase, all-m L4,
the gravity-curvature trial path, ordinary live eta=.03 and target1e-12.
The forcing tolerance differs from the frozen screen, so this is a practical
generalization test rather than a replay of its direction. The case is added
to `n3_compatible_family_cases_2026-09-19.json` on isolated branch
`research/n3-live-field-feedback-20260919`. No surface-order change is made.
## Completed matched gravity-path test
The retained-artifact audit passes both six-update restarts. Both begin at
F=9.0134584624e-6 and every reported full linear gate passes. Raw Newton ends
at 8.8762959137e-6 in 449.196 Newton seconds; gravity-path Newton ends at
8.6749533568e-6 in 887.543 seconds. The latter endpoint is only 2.2683% lower
at 1.97585 times solver cost. Neither reaches the shared 1e-12 target.
The first gravity-path update accepts alpha=1/16 versus raw's 1/128, giving
90.1683% of its eventual six-step improvement immediately. Its final alpha
is 1/2048, eight times smaller than raw's final 1/256. All rejections are
metric failures, not pressure failures. Preparation time rises 3.72673-fold;
22 auxiliary gravity solves use 866 iterations. Their final prepared defect
passes its own threshold, so the stalled full solve must not be described as
a failed auxiliary gravity correction.
The final gravity-path squared norm remains 85.0361% Poisson, with larger
hydrostatic (6.4051%) and mass (1.8661%) shares than raw. Its q18 h-pressure
energy/force virials are 7.29743e-7/1.22487e-6; raw's are
3.27166e-7/2.25835e-6. Both meet the global milestone while local nonlinear
progress remains poor. There is no demonstrated durable cure or speedup,
and no default strategy change is warranted by this pair.
Full control tables, timing scopes and audit hashes are retained in the
evidence directory's `CONTROL_RESULTS.md` and `CONTROL_RESULTS.json`.
## Compatibility of the rotating n=3 target
This is a separate physical-model issue, not an explanation of the measured
n=2 stall. The driver derives K from a nonrotating Lane–Emden model with
M=R=1 and retains M=1 when J changes. At n=3 that mass/K combination is
critical: the nonrotating mass M_LE(K) is independent of central density.
For nonnegative finite-energy density with the exact EOS P=K rho^(4/3), the
sharp gravitational-energy bound gives
|W| <= 3 integral(P) (M/M_LE(K))^(2/3).
The bound holds for nonradial densities as well. Its relation to Lane–Emden
mass is given in equations (1.14)–(1.15) and Theorem 3.1 of Cheng, Cheng and
Lin, [Expanding solutions near unstable Lane-Emden stars](https://arxiv.org/html/2305.10218#S3.SS1).
The paper uses G=1; restoring G in W leaves the displayed mass-ratio form.
Our inference from this bound and the isolated steady virial identity is:
at M=M_LE(K), W+3 integral(P)>=0, while nonzero angular momentum at finite
moment of inertia requires T>=J^2/(2I)>0. Thus 2T+W+3 integral(P)=0 is
impossible. A rotating n=3 family needs M>M_LE(K); at fixed M=1 this means
K below the exact continuum nonrotating critical value. This necessary condition
does not itself construct a rotating equilibrium or choose its rotation rate.
Fixing an additional central density cannot repair incompatible physical
specifications; a central artificial force could instead mask them.
The exact continuum statement must not be applied uncritically to the
present discrete equations: independent rho and P(h), weak EOS consistency,
negative density, gravity approximation and central forcing can bypass its
assumptions. Numerical Lane–Emden integration also makes the driver's K only
approximately critical. Independent Lane–Emden integration gives
M_LE=0.9999999918534539 for the recorded K, allowing only
T/|W| <= 2.7155e-9 under those continuum assumptions. Thus the recorded numerical
parameters permit negligible, rather than literally zero, rotational support.
A small discrete virial in such a case would require careful interpretation.
The initial screen keeps its original mass/K parameters. A separate physical
family control is specified in [N3_COMPATIBLE_FAMILY_2026-09-19.md](N3_COMPATIBLE_FAMILY_2026-09-19.md)
and isolated on `research/n3-compatible-family-20260919`: reduce K by one
percent, leave M=1, omit the central border and prescribe J=.035. This tests
a necessary physical compatibility condition, not a preconditioner speedup
or a guarantee of equilibrium or a particular fraction of critical rotation.
## Completed frozen linear comparisons
All eleven retained-artifact audits pass, including independent arithmetic
checks of saved corrections, fresh full-J actions and endpoint defects.
This does not independently reassemble J or certify every recurrence norm.
Each arrow is independent baseline → candidate at the same frozen state and requested tolerance within that case. The true relative defect is ‖Jp+F‖/‖F‖, from the fresh endpoint check. The ordinary relative tolerance is 0.003; the explicitly marked tight case requests 1e−7. A speedup is reported only when both endpoints pass the requested true gate. Times are seconds, with rounding only for display.
| Case | Iterations B→C | True relative defect B→C | True gate B/C | Total seconds B→C | Candidate construction | Full J calls B→C | Equal-gate speedup |
|---|---:|---:|:---:|---:|---:|---:|---:|
| `n2_late_gravity` | 105→83 | 2.62169821e-03→2.53227246e-03 | pass/pass | 51.1251→50.2194 | 1.7656 | 106→84 | 1.018× |
| `n2_late_surface` | 105→300 | 2.62169821e-03→5.67029124e-03 | pass/fail | 51.6185→244.6878 | 21.2548 | 106→657 | not applicable |
| `n2_late_combined` | 105→109 | 2.62169821e-03→2.60837250e-03 | pass/pass | 51.4773→117.3489 | 24.4227 | 106→273 | 0.439× |
| `n2_late_tight_combined` | 300→300 | 1.87757546e-04→1.21976551e-04 | fail/fail | 145.5541→283.3130 | 24.7723 | 303→657 | not applicable |
| `n3_late_combined` | 99→41 | 2.82583089e-03→2.77409778e-03 | pass/pass | 53.1688→65.6294 | 27.7166 | 100→139 | 0.810× |
| `n1_rotating_late_combined` | 63→28 | 2.97251190e-03→2.02497346e-03 | pass/pass | 29.9344→44.3827 | 22.3112 | 64→111 | 0.674× |
| `n1p5_rotating_late_combined` | 246→95 | 2.99226031e-03→2.99968978e-03 | pass/pass | 117.9250→101.7603 | 23.2647 | 248→245 | 1.159× |
| `n2_late_ldu_gravity` | 105→78 | 2.62169821e-03→2.80557346e-03 | pass/pass | 51.4910→60.0450 | 2.0900 | 106→79 | 0.858× |
| `n3_late_ldu_gravity` | 99→41 | 2.82583089e-03→2.65862364e-03 | pass/pass | 53.1904→35.2005 | 2.6098 | 100→42 | 1.511× |
| `n3_late_gravity` | 99→46 | 2.82583089e-03→2.59308753e-03 | pass/pass | 53.3147→31.1652 | 2.1394 | 100→47 | 1.711× |
| `n1p5_rotating_late_gravity` | 246→137 | 2.99226031e-03→1.99325392e-03 | pass/pass | 118.6171→82.3113 | 1.7997 | 248→138 | 1.441× |
`gravity` means gravity-Schur on the independent base; `surface` means surface/border Schur on the independent base; `combined` means surface/border Schur on the gravity-Schur base; `ldu_gravity` means stellar LDU plus gravity Schur. The rotating cases are identified by their input case names; this note does not reconstruct their physical metadata from external artifacts.
**Cost scope.** Total = preconditioner construction + normalization binding + Krylov setup + Krylov solve + one fresh true-residual check. Construction includes coarse-Schur setup. Internal Schur Jacobian work is already included in inverse/Krylov time and must not be added again. Total excludes initial model/context setup, separate diagnostic inverse/Jacobian action checks, nonlinear trial sampling, and output observers. These are cold one-right-hand-side measurements, so they do not establish a benefit from future cache reuse or amortization. The independent baselines were freshly timed for each pair; variation across those timings is visible, but there are no statistical repeats or confidence intervals.
Full J calls count outer Krylov actions + coarse-Schur setup actions + full J actions inside Schur inverse applications + the fresh endpoint check. They exclude separate diagnostic checks and lower-level component operator work. Therefore they are a useful work counter, not a replacement for elapsed time. Restart bookkeeping can make outer J actions exceed the iteration count.
Gravity-only saves 41.54% for n=3 and 30.61% for rotating n=1.5. The n=2
saving is only 1.77%, too small for a robust timing claim from one pair.
LDU improves n=3 over default but is slower than gravity-only. The new coarse
wrapper pays 20-26 seconds of setup and an additional full J per inverse
application. Fewer outer iterations can therefore cost substantially more.
The tight n=2 endpoints improve within the budget, but neither passes 1e-7.
All n=2 directions with raw-trial samples have the same largest sampled
passing alpha=1/256; approximately
90.18% of the small-step squared Taylor remainder is Poisson. Its measured
quadratic scaling supports finite curvature over that range. More accurate
linear solutions have not enlarged the sampled usable step range. These
finite-budget endpoints are not demonstrated residual floors.
The rotating n=1 candidate leaves the pressure-preparation restriction
unchanged. The rotating n=1.5 candidate leaves its largest sampled acceptable
alpha at 1/16. Gravity-only n=3/n=1.5 followups omit raw trials and establish
linear cost benefits only. Full cost, gate, setup and trial tables are in
[FINAL_INTERPRETATION.md](../../../diagnostics/coupled_convergence_2026-09-19/linear_analysis/FINAL_INTERPRETATION.md).
The [linear histories](../../../diagnostics/coupled_convergence_2026-09-19/figures/linear_rates/frozen_linear_rates.pdf)
distinguish reported recurrence histories from checked endpoint defects.
## Measured weak coupled response
At the common n=3 frozen state, baseline, combined and LDU directions all
pass eta=.003 and have merit slopes within 8e-6 relative of -||F||^2. Nevertheless,
combined increases the normalized surface-direction norm from .0681146 to
.113440 and reduces the largest sampled passing alpha from 1/4 to 1/16.
LDU reduces that norm to .0287899, retains alpha=1/4 and improves its trial
residual ratio from .702686 to .674223. Full-step ratios are 7.42157,
14.7443 and 2.77979, respectively.
Saved-vector analysis measures complete direction differences of 58.44% and
61.89% of baseline norm but action differences of only .3197% and .3364%
of ||F||. Response per unit difference norm is 183-184 times smaller than
along the baseline direction, in the same normalized metric. This measures
two weak directions, not a condition number or an exact nullspace.
Roughly 43% of each squared normalized difference is surface, 34% potential
and 14% density. Of the surface difference alone, 97.67% and 96.77% are l=0.
The signed monopole is -.057083 for baseline, -.104359 for combined and
-.00681011 for LDU. This is a coupled radial-size/field response, not mainly
translation or high-degree roughness. Freezing the monopole is premature:
radius is physical and this control already has a central phase constraint.
Combined lowers its final surface/scalar defect/||F|| from 4.64933e-4 to
1.07519e-6 while worsening trials. LDU permits 9.45535e-4 there but has the
better quarter-step result. Per-application coarse recovery alone does not
select a good finite Krylov direction. The n=3 combined coarse matrix's
reported reciprocal condition is 1.31320e-9, not the conditioning of full J.
These coarse validation scalars are producer FEM observations, separate from
the independently audited endpoint vectors.
For e_i=Jp_i+F, the common gate bounds ||J(p_c-p_b)|| by ||e_c||+||e_b||;
it does not bound ||p_c-p_b|| without inverse information. This motivates
coupled step control and a better approximate field response. The measured
weak directions come from the centrally constrained nonrotating control;
their magnitude and modal structure must be rechecked in the unbordered
rotating family before treating them as its demonstrated mechanism. Full identities,
modes and provenance are in the
[direction comparison](../../../diagnostics/coupled_convergence_2026-09-19/n3_direction_difference/README.md).
## Physical slices and display refinement
The optional diagnostic exports physical xz/xy cuts, independent density and
enthalpy, and the actual deformed material boundary. Other planes and offsets
are available. Element-owned triangles preserve DG traces; exterior points
remain masked. Deformation is not exaggerated and signed values are retained.
[MODEL_SLICES.md](MODEL_SLICES.md) documents use and geometric limitations.
Four replay cases export final n=2,J=0 and n=1.5,J=.1 states at four/eight
subdivisions. All four retained-artifact audits pass, including source-state
provenance and unchanged source fields. Both planes were rendered at common
axes/color ranges on a 512-by-512 scalar raster and inspected visually.
| Model / plane | Area change | Signed 2D density integral change | Signed 2D h integral change | Boundary length change |
|---|---:|---:|---:|---:|
| n=2 / xz | .12333% | .07667% | .07036% | .03065% |
| n=2 / xy | .12333% | .07667% | .07036% | .03065% |
| n=1.5, J=.1 / xz | .12495% | .00319% | .08797% | .03165% |
| n=1.5, J=.1 / xy | .12395% | .01249% | .07838% | .03088% |
These relative absolute changes concern displayed straight triangles, including
any overlaps, not exact curved-FEM integrals or 3D mass/virials. Sampled chord
errors decrease about fourfold; axial surface extents agree. Broad shape and
central concentration are stable. Small seams from independently triangulated
curved faces remain a documented display limitation.
The rotating meridional cut has equatorial extent approximately +/-1.12084
and polar extents -.988807 and +.988480. It is smoothly oblate; the equatorial
cut is approximately circular. The north/south difference is retained.
Its refined meridional sampled density minimum is -8.59e-4, without clipping.
The n=2 outline is near spherical at radius 1.0049. Neither image establishes
equilibrium; only n=2 meets the recorded virial milestone. Exact comparisons
are in [SLICE_REFINEMENT_SUMMARY.json](../../../diagnostics/coupled_convergence_2026-09-19/SLICE_REFINEMENT_SUMMARY.json).
## Completed rotating n=3 field-feedback comparison
Both compatible-family runs complete ten accepted updates and pass the
retained-artifact audit. They share n=3, J=.035, K factor=.99, no central
constraint, all-m L4/Q2, the gravity-curvature trial path and eta=.03. The
initial completed residual is .101333855231 and the nonlinear target is
1e-12. Only the inverse differs. Neither converges to that target.
| Quantity | Gravity-Schur | Stellar LDU + gravity-Schur |
|---|---:|---:|
| Final normalized residual | 1.64730591e-4 | 1.29842469e-5 |
| Newton seconds | 918.881 | 1052.972 |
| Linear seconds / iterations | 348.441 / 534 | 335.399 / 410 |
| Trial preparation seconds | 477.771 | 621.957 |
| Final accepted alpha | 1/16 | 1/64 |
| Energy h-pressure virial | 7.18429e-5 | 1.81141e-5 |
| Force h-pressure virial | 5.23757e-5 | 2.90028e-6 |
| Energy density-pressure virial | 6.96335e-5 | 3.51558e-5 |
| Force density-pressure virial | 5.01663e-5 | 1.41415e-5 |
| Absolute mass error | 5.45536e-5 | 3.37148e-6 |
| EOS density RMS / sampled density scale | 3.99773e-4 | 4.00529e-4 |
| Bernoulli RMS / sampled h scale | .00408345 | .00372207 |
| Hydrostatic-gradient RMS (model units) | .656446 | .588702 |
| T/abs(W) | .00497575 | .00497421 |
LDU produces a 12.687-fold lower residual after the same update budget, at
14.593% more Newton time. Total linear time decreases 3.743%, while trial
preparation rises 30.179%. These are evolving trajectories, not a speedup
to a common converged model. Every reported full linear gate passes. All
rejected trials fail sufficient decrease; neither run has a pressure or
geometry rejection. q18 sampled density remains positive in both, without
any positivity repair. This is not a global positivity certificate.
The LDU trajectory makes its major gain by update seven, reaching
1.30261014e-5 with a full step. Three further updates reduce that only .3213%,
at alpha=1/64. Its final squared residual is 36.500% Poisson, 34.432%
hydrostatic, 20.234% surface and 6.742% mass. The gravity-only endpoint is
80.254% hydrostatic and 10.967% mass. Field feedback is a useful live
improvement in this configuration, but does not remove the small-step stall.
The q14/q18 energy h-pressure virials differ by less than 8e-14 in both
runs; this is a quadrature check, not a mesh-convergence result.
The LDU force h-pressure virial passes 1e-5, but **the model does not meet the
virial milestone overall**: energy h-pressure and both density-pressure
virials fail. Its signed h-force result is -2.90028e-6; signed h-energy is
+1.81141e-5. Their gap is about 2.10144e-5, consistent with the separately
reported gravity-energy discrepancy. Changing from h-pressure to
rho-pressure shifts the signed virials by about +1.70418e-5. Reporting only
the passing force/h diagnostic would conceal these consistency errors.
The gravity-energy discrepancy remains about 2e-5 in both trajectories,
and EOS density RMS barely changes despite the large algebraic improvement.
This motivates separate checks of gravity/pressure consistency and spatial
discretization after improving the coupled solve. It does not prove a mesh
error floor: neither state solves the discrete equations, and this pair does
not vary mesh or field order. The finite-element closure tests a projected
EOS relation; a small algebraic closure norm alone is not pointwise EOS
accuracy. No exterior-only cause is inferred from these energy diagnostics.
At fixed density, gravity and rotation, any pressure-only change shifts both
signed virials equally. Their 2.10144e-5 separation therefore implies a best
possible maximum absolute error of at least 1.05072e-5 under such a shift.
Pressure repair alone cannot make both diagnostics pass in this frozen state.
This is not a bound on a newly solved or refined model.
A useful pressure-consistency identity for the present polytrope is
P(rho)-P(h)=(h/n)[rho-rho_EOS(h)]+D, with D>=0 for nonnegative fields.
Current DGQ2 closure tests do not generally contain the H1Q3 h field, so even
zero weak closure does not cancel the linear integrated pressure term.
Compatible test-space inclusion would cancel it under the same quadrature,
but the convex remainder, quadrature difference and finite residual remain;
near vacuum that remainder is not uniformly quadratic. This is an untested
consistency hypothesis, not evidence for a particular order change or a
reason to derive density from h. The derivation and scope are in the
[pressure-moment note](../../../diagnostics/coupled_convergence_2026-09-19/PRESSURE_MOMENT_NOTE.md).
Angular velocities are .401764 and .401388 in model units. Neither is a
calibrated fraction of critical rotation. The compatible physical inputs
make this a meaningful rotating test; changing K and removing the central
border are shared by both runs and are not counted as a preconditioner gain
against the earlier n=3,J=0 screen.
Final xz/xy slices were rendered and inspected for both runs. They show strong
central concentration and modest oblateness. These n=3 exports use four
subdivisions only; the separate n=2/n=1.5 display-refinement check must not be
misrepresented as a refinement test of these n=3 images. The complete results,
trial accounting, states and physical metrics are in
[N3_COMPATIBLE_RESULTS.md](../../../diagnostics/coupled_convergence_2026-09-19/N3_COMPATIBLE_RESULTS.md)
and its adjacent JSON.
## Architecture and interpretation for the next investigation
The library fields, orders, all-m L4 surface, normalization and physics-facing
API remain unchanged. No clipping, logarithmic density, derived-density
replacement or new positivity acceptance gate was introduced. The new coarse
inverse is an experiment-only frozen policy. It uses generated row/column
partitions and an explicitly unbordered base inverse; compile-time concepts
check structural contracts, while generation/dimension/rank checks guard facts
known only after preparation. Changed Jacobians require reconstruction.
Checked restart support is separated from read-only diagnostic observation.
The context's explicit diagnostic initializer validates compatible finite
physical coordinates, prepares and refreshes before commit, clears stale
warm starts and rolls back on failure. An unconverged snapshot requires an
explicit experimental override. None of this silently accepts an invalid
model or changes the physical equations.
The current evidence supports the following order of work:
1. Retain gravity-Schur as the frozen linear-cost comparator and stellar
LDU plus gravity as the better live candidate in the tested rotating n=3
configuration. That live result is conditional on its gravity-curvature
trial path; it does not establish the best raw-Newton default. Candidate
iteration counts alone are insufficient. Do not promote the new surface
wrapper on this evidence.
2. Investigate the weak coupled radial-size/field response and finite-step
curvature. A coupled trust region or regularized step with a physical
displacement scale is a plausible swappable experiment. Keep radius free,
keep surface/interior simultaneous and evaluate the full residual and both
virials. The data do not yet select a regularization strength or prove
this remedy works.
3. Improve the approximate material response in controlled stages: exact local
DG density mass inversion and stronger enthalpy mass inversion are narrower
candidates before a more expensive EOS-aware material/gravity Schur solve.
The existing material inverse already includes the h-to-density derivative;
claiming it is missing would be incorrect. This remains an independent
density formulation. See [FIELD_COUPLING_REVIEW_2026-09-19.md](FIELD_COUPLING_REVIEW_2026-09-19.md).
4. Define a compatible n=3 rotating family and calibrate dimensionless rotation
before targeting 50% critical. At fixed M and K, n=3 homology changes J with
scale; changing input J alone is not a calibration of critical fraction.
This physical parameter issue is separate from the n=2 numerical stall.
A projected surface-equipotential equation and native lower harmonic degree
were reviewed as possible future operator studies but were not implemented
or tested here. They change the discrete system. In particular, a surface
potential derivative must respect the actual ALE pullback/field transport;
substituting an effective-gravity derivative without that analysis would not
be sound. The present mechanical surface equation and pressure-query guards
are retained.
## Validation, artifacts and reproduction
Release builds of the diagnostic and targeted test executables pass. The
new coarse inverse passes 70 assertions in nine cases, including typed
normalization/partition behavior and algebraic recovery. The transactional
initializer passes 71 assertions in three real-FEM cases. Pure slice geometry
controls pass; all 14 slice plotting/comparison tests pass, including after
the final label/bounds fixes. The artifact auditor passes 11 controls, and
both convergence plotters pass 11 tests each with actual rendering enabled.
No unrelated full-suite claim is made.
All 24 campaign cases pass retained-artifact verification: five initial
nonlinear controls, two matched gravity-path restarts, eleven frozen inverse
comparisons, four unchanged-state slice replays and two live n=3 controls.
A passed artifact audit can describe a failed linear gate or an unconverged
model; it certifies the stated records and accounting, not scientific success.
The [study index](../../../diagnostics/coupled_convergence_2026-09-19/STUDY_INDEX.json)
records producer revisions and hashes of all six audit files.
Numerical campaigns and heavy builds/audits/rendering were serialized.
Each campaign retains exact arguments, clean producer commit, private copied
executable, build settings, mesh/input hashes, logs, saved states and output
hashes. Source-provenance commits differ because followups were declared and
committed as evidence accumulated. Later documentation/plotting edits do not
change the copied numerical executables. Timings have no statistical confidence
intervals and are not portable hardware benchmarks.
The integration branch is `research/coupled-convergence-study-20260919`.
Separate retained branches cover the linear coarse inverse, slice exporter,
n=3 compatible family, gravity-only attribution and live field feedback.
The original programming checkout is unchanged. The report and case manifests
are tracked; large artifacts are outside the source checkout in the evidence
folder. Production defaults, physical field orders and positivity handling
remain unchanged.
Campaign manifests in this directory are `convergence_screen_cases_2026-09-19.json`,
`convergence_gravity_path_cases_2026-09-19.json`,
`convergence_linear_cases_2026-09-19.json`,
`convergence_linear_followup_cases_2026-09-19.json`,
`convergence_slice_cases_2026-09-19.json` and
`n3_compatible_family_cases_2026-09-19.json`. Run `run_plateau_campaign.py`
from the matching clean source revision, supplying that manifest, source,
build, mesh and a new output directory. Predecessor paths in restart/replay
manifests must resolve to their recorded saved states. The runner deliberately
refuses to overwrite campaigns or use modified tracked source.
Review artifacts:
- [Rotating n=3 meridional slice](../../../diagnostics/coupled_convergence_2026-09-19/figures_n3_v2/n3_J0p035_K0p99_ldu_xz.png)
and [equatorial slice](../../../diagnostics/coupled_convergence_2026-09-19/figures_n3_v2/n3_J0p035_K0p99_ldu_xy.png).
These are preliminary four-subdivision images of the unconverged feedback
model, with corresponding PDFs in the same folder.
- [Refined n=1.5 rotating slice](../../../diagnostics/coupled_convergence_2026-09-19/figures_slices_v2/n1p5_rotating_xz_s8.png)
and [same-state display comparison](../../../diagnostics/coupled_convergence_2026-09-19/figures_slices_v2/n1p5_rotating_xz_s4_s8.pdf).
- [Eleven frozen linear histories](../../../diagnostics/coupled_convergence_2026-09-19/figures/linear_rates/frozen_linear_rates.pdf),
[n=2 trial-path comparison](../../../diagnostics/coupled_convergence_2026-09-19/figures/convergence/n2_paired_convergence.pdf)
and [n=3 tolerance comparison](../../../diagnostics/coupled_convergence_2026-09-19/figures/convergence/n3_paired_convergence.pdf).
- [Audited nonlinear controls](../../../diagnostics/coupled_convergence_2026-09-19/CONTROL_RESULTS.md),
[live n=3 comparison](../../../diagnostics/coupled_convergence_2026-09-19/N3_COMPATIBLE_RESULTS.md),
[implementation validation](../../../diagnostics/coupled_convergence_2026-09-19/validation/validation.json)
and [final slice test log](../../../diagnostics/coupled_convergence_2026-09-19/figures_n3_v2/slice_tests.log).

View File

@@ -0,0 +1,283 @@
# Bounded coupled second-order trial correction
Branch `research/coupled-trial-correction-20260918`, based on the completed
nonlinear obstruction investigation at `2944dd5`. The configured worktree
retains its existing name, `worktrees/preconditioner-improvement`, so that
build reuse does not disturb the preceding branch or immutable executables.
## Hypothesis
At the recorded n = 1.5, J = 0 endpoint, tenfold tighter linear accuracy did
not improve the useful trial range. The full directional derivative was
consistent with the prepared residual. Gravity-only correction reduced the
remainder norm but increased its adverse projection through hydrostatic,
EOS and surface balance. The next hypothesis is that correcting the entire
trial remainder can preserve the intended Newton response over larger steps.
For the captured base residual F0 and verified Newton direction p, preserve
L(alpha) = F0 + alpha J0 p. At a prepared candidate y, solve
J(y) c = -(F(y) - L(alpha)),
then prepare and evaluate y+c. All equations, normalization factors and
ordinary full-residual acceptance thresholds remain unchanged. A separate
auxiliary true-defect check is required; the base Newton report is never
replaced by a correction report. The locally second-order argument requires
sufficient residual smoothness and a bounded inverse, neither of which is
assumed to hold uniformly in this model.
## Implementation contracts
- A third, defaulted compile-time trial-path policy composes with the
established enthalpy and gravity policies. Existing two-policy recipes
retain their types and behavior. The new policy is incompatible with the
eliminated-gravity path until a corresponding reduced-manifold contract
is designed; unsupported combinations fail at compile time.
- The auxiliary solve has its own backend, a finite iteration budget and an
independent application of the complete candidate Jacobian. Its initial
options are relative tolerance 0.03, absolute tolerance 1e-14, at most160
iterations and restart160.
- Limit the correction norm to alpha||p|| by default. The initial work limit
is one actual auxiliary solve per Newton iteration, and one solve per
selected candidate. Runtime expert controls change these bounds explicitly.
- Select correction only after a prepared candidate fails the existing
acceptance predicate. Reuse the exact configured metric for selecting
between original and corrected candidates. An already acceptable step
incurs no coupled solve; an unprepared candidate cannot invoke one.
- Recheck the same selected admissibility policy and actual geometry after
correction. Retain the original candidate if the auxiliary solve fails,
the norm cap rejects it, preparation/admissibility fails, or its metric
worsens. Restoring a fallback includes fresh operator preparation, not
merely copying state vectors.
- The exported numerical core and trial transaction are shared by production
and frozen diagnostics. The physics-facing model API is unchanged.
## Initial screen
The committed `coupled_trial_screen_2026-09-18.json` records complete controls
and immutable input paths. All heavy builds and numerical cases run serially.
Evidence is written to `diagnostics/coupled_trial_2026-09-18/` in the task
workspace; individual campaign directories are immutable.
Use the previously saved late eta0.03 direction, independently reapplying the
full Jacobian at the restored base before using it. This avoids conflating a
new linear solve with the new trial map. Test both raw and gravity-corrected
starting candidates at alpha1/16,1/64,1/256,1/1024. The middle two previously
prepared but failed the merit test. The largest failed pressure preparation;
the smallest already decreased the residual and must not trigger correction.
The seed control uses its saved eta0.03 direction and alpha1 with the
gravity-corrected path. Its candidate already passes; it should preserve that
result without auxiliary coupled work. Each frozen alpha is an independent
trial with a fresh per-iteration budget, not a simulated live line search.
Record inputs/factors/layout, F0,p,J0p, the actual auxiliary RHS and J(y)c,
candidate and returned state/residual vectors, true defects, norm-cap gates,
selection/fallback decisions, restoration invariants and complete work.
Useful frozen progress is a prerequisite for a bounded nonlinear campaign.
Any accepted model must also be checked for virial balance and internal
admissibility; a lower residual alone is insufficient.
## Result and present recommendation
The opt-in implementation is complete and tested. It creates a newly
Armijo-acceptable frozen candidate at alpha = 1/256 for both trial paths,
but does not establish a production convergence or speed improvement. Do not
enable it by default on the strength of these measurements.
The nominal fourfold increase over the previously accepted alpha = 1/1024
overstates the realized displacement. The coupled correction largely reverses
the original Newton direction. Its own nonlinear curvature is much larger
than the checked auxiliary linear error, and the useful candidate remains
internally nonphysical despite passing enthalpy-based virial checks.
Each frozen alpha has a fresh one-attempt budget. In a live search that spends
the default budget at the unsuccessful 1/64 trial, the later 1/256 trial
cannot use this correction. Thus these independent samples are not a measured
live line-search speedup. The existing seed protocol projects radial profiles
and regenerates fields and shape; it cannot faithfully resume the arbitrary
saved late state. No diagnostic mutation of accepted state was used to bypass
that restriction, and no new initialization API was added.
## Numerical results
The common late state has ||F0|| = 1.3966991043973936e-5 and the saved outer
direction again passes the full-J gate with relative defect 0.02955918315.
All four distinct auxiliary solves pass the independent 0.03 relative gate
and the norm cap. No auxiliary failure or relaxed acceptance threshold
explains the outcomes below.
| Prepared path | alpha | Before correction: ||F||/||F0|| | Corrected: ||F||/||F0|| | Selection | Auxiliary iterations | Added transaction time |
|---|---:|---:|---:|---|---:|---:|
| Raw | 1/64 | 1.80726810 | 1.03360191 | Improved, still fails Armijo | 34 | 27.33 s |
| Raw | 1/256 | 1.00250966 | 0.99746464 | Passes Armijo | 52 | 37.59 s |
| Gravity-corrected | 1/64 | 1.08032296 | 1.09566246 | Worse; original restored | 55 | 47.60 s |
| Gravity-corrected | 1/256 | 1.00202482 | 0.99810801 | Passes Armijo | 62 | 43.53 s |
At 1/16, both raw preparations fail at the pressure-force thermodynamic-domain
check, before any coupled solve. At 1/1024, the original candidates already
pass Armijo and receive no coupled solve: their residual ratios are
0.9991695118 (raw) and 0.9993941386 (gravity-corrected).
The Lane–Emden seed's gravity-corrected full step likewise remains acceptable
without a coupled solve. All frozen probes preserve accepted buffers,
normalization factors and direction buffers; the final residual and Jp at
the restored base agree exactly with the initially captured values.
Raw timings above come from the uncontended repeat. An initially launched
artifact audit accidentally rebuilt a gravity-index set for every vector
entry and overlapped the first raw case. It was stopped, the checker was
made linear in state size, and the raw case was repeated. Its trial vectors
and residuals reproduce the first run. The original evidence is retained;
its raw timing is excluded. All 50 saved vector files are byte-identical in
the repeat. See `AUDIT_RUN_NOTES.md` in the evidence folder.
The added times include refresh, solve, independent verification, candidate
preparation, and any fallback restoration. They do not include the original
trial preparation or captured base action. At 1/256 the full candidate-path
costs are 43.86 s (raw) and 63.45 s (gravity-first), versus 6.30 s and 18.59 s
for their already acceptable 1/1024 controls. Outer Newton work, previous
rejected trials, base capture and physical postprocessing are separate.
Timings are single observations, not statistical performance estimates.
## Why a verified solve does not ensure useful correction
For the actual candidate y, let b = L - F(y), delta = J(y)c - b and
E = F(y+c) - F(y) - J(y)c. The exact saved-vector identity is
F(y+c) - L = delta + E.
The auxiliary gate bounds delta. It does not bound E. At alpha = 1/256,
||E|| is about 11.28 times the verified defect for the raw path and 254 times
for the gravity-first path. For the two gravity-first attempts,
||E||/||c||^2 is 13.5756 and 13.5358; the raw 1/256 value is 13.5271.
This is evidence that the correction's own quadratic curvature, rather
than inaccurate solution of its linear equation, dominates its remaining
nonlinear error.
On the gravity-first path at 1/256, the affine-target remainder actually
grows from 8.87747e-8 to 6.23769e-7 (7.03 times), despite the improved merit.
The raw path reduces that remainder by about 3.165 times. Gravity completion
before the coupled solve therefore does not help this particular comparison.
The correction/direction cosines are -0.9999330 (raw) and -0.9999942
(gravity-first). The realized displacement norms at 1/256 are only 1.7596
and 1.2342 times their respective raw-direction 1/1024 displacement norms.
On the gravity-first path, ||c||/||b|| increases from 480.8 to 2418.1 when
alpha decreases fourfold. These samples do not demonstrate a stable small
second-order correction regime. They do not identify a null mode either.
Tightening the auxiliary tolerance is consequently a weak next target.
Near collinearity is insufficient to conclude that scalar damping is
equivalent: small transverse displacements can have large Jacobian action.
The final scalar controls below address that attribution directly.
## Matched scalar controls
For each selected 1/256 candidate z, compute
t = dot(z-x,p)/dot(p,p), then freshly prepare x+t*p through the existing
`--replay-candidate` path. The input generator validates and hashes the
source artifacts before writing normalized candidates. No new linear solve,
repair, or acceptance threshold is introduced.
| Coupled candidate being matched | Scalar t | Scalar ||F||/||F0|| | Coupled ||F||/||F0|| | Scalar residual decrease | Coupled residual decrease |
|---|---:|---:|---:|---:|---:|
| Raw + coupled | 0.00171818301767 | 0.9988437736 | 0.9974646400 | 0.115623% | 0.253536% |
| Gravity-first + coupled | 0.00120521815790 | 0.9990306561 | 0.9981080052 | 0.096934% | 0.189199% |
Both scalar controls prepare and pass the ordinary Armijo criterion at t.
Their normalized base and full base residual reproduce the coupled screen
byte for byte. The replay uses the independent preconditioner configuration
because that is the existing replay interface; no inverse or linear solve is
used in evaluating these candidates. The equation operator and normalization
are the same. The campaign executable is byte-identical to both screens.
The coupled candidate produces 2.19 times the residual decrease of the
matched scalar control on the raw path, and 1.95 times on the gravity-first
path. Thus the small transverse changes have measured nonlinear benefit.
The result cannot be dismissed as scalar damping alone, but it is a small
absolute gain bought with an extra full coupled solve. This does not measure
an entire Newton iteration or prove amortized speedup. The scalar replay
records preparation and residuals; it is not an additional physical-model
certification or quadrature study.
The next bounded question is whether damping or otherwise limiting the
already computed correction can retain this transverse benefit while
reducing its own nonlinear curvature, using additional preparations instead
of additional full solves. Test that together with a work-aware attempt
trigger; simply increasing the attempt budget can spend multiple outer-solve
equivalents on rejected candidates. Keep normalization, equations, physical
validation and true-defect gates fixed during that comparison. This follow-up
is not implemented here.
## Physical validation
Every available selected state is freshly prepared and evaluated at
quadrature orders 14 and 18, using the existing field reconstruction,
rotation, Piola transforms and physical diagnostics. This postprocessing is
separate from timed trial selection and does not change acceptance.
At alpha = 1/256 and quadrature order 18:
| Quantity | Raw + coupled | Gravity-first + coupled |
|---|---:|---:|
| Enthalpy-pressure energy virial error | 4.05889e-6 | 4.06134e-6 |
| Enthalpy-pressure force virial error | 2.56495e-6 | 2.56840e-6 |
| Absolute mass error | 3.13178e-6 | 3.13420e-6 |
| Angular momentum Jz | 0 | 0 |
| Minimum sampled density | -8.28793e-4 | -8.24696e-4 |
| Negative density samples | 9600 | 9600 |
| Negative-density mass fraction | 2.89684e-5 | 2.89654e-5 |
| Scaled EOS density mismatch RMS | 1.28264e-4 | 1.28231e-4 |
Enthalpy-pressure virial errors are below 1e-5, with order-14 to order-18
differences near 1.83e-9. However, pressure inferred from the negative density
is undefined for this EOS, so the corresponding density-pressure virials
are undefined too. A finite enthalpy-pressure virial is not a substitute for
internal admissibility or pointwise EOS agreement. Negative-density volume
fractions also change with quadrature (about 2.83% to 1.87% on the
gravity-first candidate). No internally correct, converged stellar model,
continuum accuracy, or mesh-convergence claim follows from this trial.
## Tests and reproduction
- The Release `tests` and `plateau_diagnostic` targets build successfully.
- Fifteen focused correction/transaction cases pass in serial (584
assertions) and on two MPI ranks (586 assertions per rank). These include
analytic mixed curvature, a lying backend, bounded real FGMRES failure,
norm caps, stale preparation, zero remainders, nonfinite/overflow handling,
empty-rank collectives, budgets, rollback and exceptions.
- Thirty-five relevant stellar/Newton/gravity regression cases pass with
356,933 assertions, including typed polynomial composition, optional
borders, original-report preservation and observer/rollback behavior.
- The independent checker passes 27 synthetic tests. The completed screen
and uncontended repeat pass artifact, provenance and physical-replay
consistency checks. Its observational mechanism statistics distinguish
the checked linear defect from the correction's own nonlinear remainder.
Their final audits pass 2,105 and 885 checks; the separate scalar-control
audit passes 68 hash, projection, shared-base and replay checks.
- Full stellar MPI operation remains outside this validation; its existing
interpolation restriction is unchanged.
Evidence root:
`/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/coupled_trial_2026-09-18`.
`tests_provenance.json` records the test executable and log hashes. The
campaign directories contain complete commands, source revisions, immutable
executables and hashes of mesh, inputs and outputs. All three campaign
executables are byte-identical (SHA256 begins `620d625636bc77b1`).
Source checkpoints: implementation `0d87b8b`; initial campaign/checker
`2d0d32b`; checker fix and raw timing repeat `5aa48dc`; scalar-control
generator `0c926f4`. The original checkout and its unrelated quadrature
formatting change are preserved.
From this worktree, reproduce the initial screen with
`experiments/run_plateau_campaign.py`, the committed
`coupled_trial_screen_2026-09-18.json`, the configured Release build,
`sandbox.smesh`, and a new output directory. Use
`coupled_trial_raw_repeat_2026-09-18.json` for the raw repeat. Run
`check_coupled_trial.py CAMPAIGN --output OUTSIDE_CAMPAIGN.json` afterward.
`make_coupled_scalar_controls.py SCREEN FRESH_OUTPUT` generates the two
normalized scalar inputs and `cases.json` for the existing campaign runner.
All runs use one FEM rank; the seed and outer direction inputs are saved
from the preceding investigation and are hashed into the new evidence.

View File

@@ -0,0 +1,359 @@
# Damped fully coupled trial correction
This investigation branches from `46249d0` onto
`research/damped-coupled-trial-20260918`. It tests two separate mechanisms:
bounded damping of one fully coupled correction, and reserving that correction
solve for a trial whose merit is reasonably close to its affine prediction.
The previous full-step policy remains available and the default solver is unchanged.
The combined opt-in policy gives useful measured progress, but does not yet
establish convergence. On the matched six-update n=1.5,J=0 trajectory it reaches
F=1.24583e-5 versus 1.49720e-5 for gravity correction alone: 16.79% lower residual
for 22.08% more Newton iteration time. After their identical first update, the
residual reductions are 22.85% versus 7.29%, giving 2.53 times greater decrease
per iteration-second over that bounded interval. Both runs hit the six-update
cap. Endpoint enthalpy-based virials remain below 1e-5, while negative density
and local EOS defects remain unresolved. The default solver remains unchanged.
## Algorithm and architecture
At accepted state x, capture F0=F(x), the actual Newton direction p and J0 p.
For outer step alpha and prepared candidate y (raw or gravity-corrected), set
L=F0+alpha J0 p and solve J(y)c=L-F(y). The unscaled c must satisfy both the
existing independent full-J defect check and the existing norm cap.
The optional search prepares y+beta c with beta=1,1/2,1/4,1/8, always starting
from y. One auxiliary solve supplies all four candidates. The first improving
candidate passing ordinary outer acceptance ends the search. Otherwise the
lowest-merit admissible improvement is retained; an earlier selected candidate
is freshly prepared, and complete failure restores y with its current inverse.
No accepted-state buffer is written by this transaction.
For the optional attempt selector, D=M(F0)-M(L) must be finite and positive.
The solve is eligible when (M(F(y))-M(F0))/D <= k, with default k=1. A deferral
spends no auxiliary budget. This is a bounded-work heuristic, not a convergence
guarantee. It requires a deterministic metric of the supplied residual with
fixed parameters; the default normalized residual metric satisfies this contract.
Algorithms are selected by types: `FullCoupledStep`/`BacktrackedCoupledStep`
and `EveryRejectedCoupledAttempt`/`NearAcceptanceCoupledAttempt`. Runtime
iteration counts, reduction factors and tolerances are validated collectively.
`BacktrackedCoupledCurvatureCorrection` composes damping and near-acceptance
selection in the existing typed `NewtonNumerics` recipe. The original
`CoupledCurvatureCorrection` remains the full-step/every-rejected control.
Neither changes the physics-facing model specification or central-density policy.
An auxiliary report describes c, not beta c. For a damped candidate the exact
remainder identity is
F(y+beta c)-L = (1-beta)(F(y)-L) + beta (J(y)c-(L-F(y))) + E_beta,
E_beta = F(y+beta c)-F(y)-beta J(y)c.
Scaling c therefore does not imply solving the original auxiliary RHS to its
original tolerance. The actual freshly prepared residual decides acceptance.
## Reproduction and evidence
The versioned `damped_coupled_screen_2026-09-18.json` compares none/full/damped/near
for the late n=1.5,J=0 snapshot on raw and gravity-corrected paths, plus a seed
control. No central constraint is imposed. Each sequence captures once, shares
one auxiliary-solve budget, tests every halving from alpha=1 through 1/4096 and
stops at its first accepted candidate. The prior independent-alpha screen did
not represent this shared budget and omitted some intermediate step lengths.
The campaign runner builds a clean committed revision, copies an immutable
executable and hashes mesh, inputs and outputs. The experiment calls the same
production transaction and production gravity correction as Newton. It records
every candidate evaluation, fresh selected-state replay and unchanged accepted
buffers/normalization. Only the accepted trial is replayed for quadrature-14 and
quadrature-18 physical observations, outside the timed selection phase.
Operation timings include raw preparation, gravity correction and the coupled transaction.
They exclude setup, ordinary initial/final metric calls, final restoration, accepted
commit refresh, artifact output and physical replay; search wall time
also includes artifact output. Callback vector copies remain in the measured
transaction. The no-correction control captures the same tangent for a comparable
screen, so capture cost is reported separately and is not ordinary Newton work
for that control. Builds, timed numerical cases and artifact audits do not overlap; numerical
cases run one at a time.
## Frozen sequential trial results
The independent artifact audit passed all nine cases in `screen_v1` (see
`screen_v1_audit.json` in the evidence directory below). This audits the recorded transaction algebra and true-defect certificates
from saved vectors, provenance, and recorded restoration evidence; it does not
certify a converged or physically admissible stellar model.
### What improved
The late-state screen uses the same saved state and Newton direction, a halving
line search beginning at alpha=1, one shared correction-solve budget, and the
first accepted trial. The initial full residual norm is 1.3966991044e-5.
| Path | Policy | Accepted alpha | Residual decrease | Search operation time |
| --- | --- | ---: | ---: | ---: |
| Raw | No coupled correction | 1/512 | 0.116541% | 49.04 s |
| Raw | Full correction, every rejection eligible | 1/512 | 0.116541% | 69.00 s |
| Raw | Damped correction, every rejection eligible | 1/512 | 0.116541% | 95.33 s |
| Raw | Damped correction, near-acceptance eligibility | 1/256 | 0.253536% | 80.11 s |
| Gravity-prepared | No coupled correction | 1/512 | 0.047127% | 116.06 s |
| Gravity-prepared | Full correction, every rejection eligible | 1/512 | 0.047127% | Excluded: clock anomaly |
| Gravity-prepared | Damped correction, every rejection eligible | 1/512 | 0.047127% | 168.80 s |
| Gravity-prepared | Damped correction, near-acceptance eligibility | 1/256 | 0.189199% | 128.75 s |
These are original-screen operation timings, excluding artifact writes,
initialization, physical replay, and the separately measured base capture.
The three timing repeats below use the identical diagnostic binary. The excluded
original gravity/full timing is retained as evidence, without rescaling.
The demonstrated accepted-step gain comes from **eligibility timing**. The near
gate defers the prepared rejections at 1/32, 1/64, and 1/128, preserving the sole
solve for 1/256. Both accepted corrections use beta=1 and stop after one
candidate. Damping is therefore not responsible for their accepted improvement.
Without this gate, the correction budget is spent at 1/32, and the eventual
accepted state equals the corresponding baseline. Gravity damping does improve
the rejected 1/32 candidate at beta=1/2, but it remains unacceptable.
The nominal accepted alpha improves **twofold, not fourfold**. The earlier
independent-alpha screen omitted 1/512 and did not reproduce a shared-budget
search. The present residual decreases and costs describe one frozen search;
they establish neither sustained convergence nor a nonlinear speedup. They also
do not establish that the chosen eligibility threshold is effective at other
states, polytropic indices, or rotation rates.
### Seed control
The seed's independently verified outer defect is 0.0281993. Its first trial,
alpha=1, already passes after existing gravity preparation: the residual falls
from 2.736592176e-4 to 1.614841549e-5, a 94.0991% decrease. The new policy performs
zero coupled solves, beta evaluations, or deferrals. This confirms nonintervention
at this sampled seed; it is not a complete trajectory or performance control.
### Physical interpretation
All selected snapshots replay exactly, with accepted buffers, direction,
normalization factors, residual, and Jacobian action restored. The q18
enthalpy-pressure energy virial errors are 4.059–4.068e-6 for the late candidates
and 4.3646e-6 for the seed candidate. Force virial errors are 2.565–2.572e-6 and
2.8455e-6, respectively. Raising quadrature from q14 to q18 changes either
enthalpy-based virial diagnostic by only 1.828–1.834e-9. Mass errors are
3.13–3.71e-6, Jz is zero, and sampled mapping determinants remain above 0.9858.
However, every selected snapshot retains negative density: q18 minima range
from -8.25e-4 to -8.64e-4. Density-derived pressure is not defined everywhere,
and its reported virial diagnostics are NaN. The q18 negative-density mass
fraction is about 2.90e-5, **29–30% larger** than its q14 estimate. The sampled
density-minimum magnitude increases 15–17%, and the maximum scaled EOS mismatch
increases about 17%; the RMS scaled EOS mismatch changes about 0.21%.
Thus the enthalpy-based global virial diagnostic meets 1e-5 and is stable under
this quadrature comparison, while local density/EOS defects remain unresolved.
This comparison is neither a mesh-convergence study nor a pointwise positivity
certificate. Frozen Armijo acceptance must not be presented as model convergence
or complete physical validation.
## Timing repeats
The first gravity/full case had inconsistent elapsed clocks: 531.747 s UTC
versus 236.576 s Python monotonic, with a 325.024 s C++ auxiliary solve. It is
excluded from performance comparisons. The runner now records child user/system
CPU time, UTC elapsed time and monotonic elapsed time independently. A temporary
idle-sleep guard covers each subsequent campaign; no phase time is rescaled.
| Repeat | Search operation time | Total elapsed / child CPU | Result |
| --- | ---: | ---: | --- |
| Gravity/full | 149.17 s | 227.30 / 226.58 s | Same baseline endpoint; 53 auxiliary iterations |
| Raw/none | 45.76 s | 123.67 / 123.57 s | Same alpha=1/512 endpoint |
| Raw/near | 74.90 s | 153.11 / 153.05 s | Same alpha=1/256, beta=1 endpoint |
UTC and monotonic times differ by at most 0.0053 s in these repeats. Every saved
vector file has the same hash as its original run (68, 55 and 54 files,
respectively), and the independent vector audit passes all three. The raw
progress per operation-second ratio is 1.332 initially and 1.329 in the paired
repeat. These support about 33% greater fractional residual decrease per measured
operation-second at this frozen state, despite an approximately 7% timing shift
between campaigns. The gravity near/none ratio is 3.619 in the
one original pair; it has not received an additional paired timing repeat.
These ratios use fractional residual decrease, not merit decrease. They compare
one fixed state/direction and exclude ordinary outer linear solve, commit
refresh, initialization and physical replay. They are not Newton speedup factors.
The correction also changes the actual displacement, so a factor-two nominal
alpha is not a factor-two displacement claim.
## Matched live Newton follow-up
The paired six-update runs use the same seed, mesh, n=1.5,J=0 specification,
no central constraint, gravity-Schur preconditioner, restart 160 and outer true
defect tolerance 0.03. Only the trial policy changes: `curvature` versus
`curvature-backtracked-coupled`. Initial physical observations and layout hashes
match exactly, as do the first accepted residual, alpha, linear diagnostics and
block residuals. First-step state vectors were not saved, so these are recorded
diagnostic matches rather than a separate bitwise state comparison.
| Accepted update | Control alpha | Control F | New alpha | New F | Cumulative Newton seconds, control / new |
| ---: | ---: | ---: | ---: | ---: | ---: |
| 1 | 1 | 1.614842e-5 | 1 | 1.614842e-5 | 39.25 / 39.11 |
| 2 | 1/16 | 1.579569e-5 | 1/8 | 1.614552e-5 | 173.68 / 194.99 |
| 3 | 1/16 | 1.553144e-5 | 1/4 | 1.595479e-5 | 248.91 / 249.76 |
| 4 | 1/16 | 1.514564e-5 | 1/2 | 1.574591e-5 | 324.13 / 305.06 |
| 5 | 1/32 | 1.499075e-5 | 1/2 | 1.273240e-5 | 419.19 / 431.45 |
| 6 | 1/32 | 1.497197e-5 | 1/8 | 1.245830e-5 | 502.21 / 613.09 |
Both runs complete six accepted updates and report nonconvergence at the
iteration limit (exit 3). The original strict residual tolerance is unchanged.
The combined policy produces 16.79% lower final residual, at 22.08% more
iteration time. Excluding the identical first update, residual decreases from
that common value are 7.285% in 462.95 s (control) and 22.851% in 573.98 s (new),
a 2.530 ratio of residual decrease per second over this fixed interval. This is
a bounded progress-rate comparison, not a speedup to a converged model.
The new method initially lags. First recorded crossings of fixed residual
thresholds illustrate the tradeoff without interpolating between states:
| F threshold | Control Newton seconds | New Newton seconds |
| ---: | ---: | ---: |
| 1.60e-5 | 173.68 | 249.76 |
| 1.55e-5 | 324.13 | 431.45 |
| 1.50e-5 | 419.19 | 431.45 |
| 1.40e-5 | Not reached within six updates | 431.45 |
Total process elapsed/child CPU times are 561.92/561.22 s (control) and
671.98/671.86 s (new). UTC and monotonic elapsed times differ by 0.0014 s and
-0.0318 s, respectively. The total process includes initialization, endpoint
physical diagnostics and artifact output; the iteration totals exclude these.
There is one live timing pair, not a statistical performance distribution.
### What the live corrections actually did
The control uses 354 outer Krylov iterations; the new run uses 341 outer plus
163 auxiliary iterations across three correction solves. The new gate defers
five trials, and auxiliary preparation adds 11 preparations, including one
best-candidate replay. Auxiliary solve/preparation/verification/refresh counters
are 84.35/64.03/0.67/4.77 s; these are nested work already included in iteration
time and must not be added to it. Ten beta candidates are evaluated.
At update 2 (zero-based iteration 1), alpha=1/8 has an eligible excess ratio
0.35155. The unscaled solve passes its true defect gate (relative 0.02570) and
cap (correction/cap=0.63369). Beta=1 worsens the merit; beta=1/2 passes ordinary
acceptance. It reduces residual by only 0.01795%, versus 2.18426% from the
control's next ordinary backtrack at alpha=1/16. Thus an accepted rescue need
not have the best immediate progress. It realizes only 0.1533% of the nominal
affine predicted merit decrease, despite satisfying Armijo by a factor 28.7.
Unlike the successful frozen rescues, this accepted live correction genuinely
uses damping. It changes the following trajectory: updates 3 and 4 accept
ordinary alpha=1/4 and 1/2 trials, and update 5 achieves a large residual drop.
At updates 5 and 6 the auxiliary searches keep their best improvements at
beta=1/8 and 1/4, respectively, but both still fail outer acceptance. The next
ordinary trial is accepted instead. Therefore three `kept` diagnostic events
mean only **one committed coupled rescue**. No later rejected correction is
carried into the accepted state.
A minimum realized-versus-predicted decrease guard is a plausible separate
investigation, not an established improvement: it would reject the initially
weak rescue that precedes this better final trajectory. A beta-aware prediction
F(y)+beta J(y)c would distinguish a damped candidate from the full target L
without another FEM action. Any guard must control final candidate admission
and fallback, not just beta-loop stopping. Comparing with one ordinary further
backtrack is another useful control, at one extra preparation cost. Neither
change is implemented or claimed beneficial here.
### Live endpoint physics
| q18 observation | Control | New |
| --- | ---: | ---: |
| Enthalpy-pressure energy virial error | 4.22590e-6 | 3.78554e-6 |
| Enthalpy-pressure force virial error | 2.71367e-6 | 2.31894e-6 |
| Absolute mass error | 3.41685e-6 | 2.53899e-6 |
| Absolute J error | 0 | 0 |
| Minimum sampled mapping determinant | 0.989275 | 0.989068 |
| Minimum density | -7.73185e-4 | -7.85522e-4 |
| Negative-density mass fraction | 2.89683e-5 | 2.88557e-5 |
| Scaled RMS EOS density mismatch | 1.27948e-4 | 1.27721e-4 |
| Scaled maximum EOS density mismatch | 9.63952e-4 | 9.73858e-4 |
Both endpoints meet the primary enthalpy-based virial milestone at q14 and q18;
the quadrature change is about 1.83–1.84e-9. Density-derived pressure and its
virials remain undefined because of negative samples. The new endpoint improves
the global measures while its sampled density minimum and maximum EOS defect
are slightly worse. No positivity, mesh convergence, or complete local-physics
claim follows from the virial result. The separate conservative solver/defined-
virial checker returns its expected nonpassing result for both endpoints.
### Implication and next experiment
Keep the new policy opt-in. The implementation and its cost bounds are tested;
the combined policy now has evidence of beneficial nonlinear trajectory changes
as well as frozen-step improvement. It has not yet demonstrated sustained
convergence or any higher-n/rotating result. The next useful test is a longer
matched n=1.5 trajectory from the same seed, preserving the physical diagnostics
and work accounting, before expanding to higher n and J. Do not promote the
policy or tune a new quality threshold solely from the early marginal rescue.
## Validation
Production and experiment targets build successfully with the configured release
Clang/C++23 module build. Existing duplicate-library linker warnings remain.
- Core correction tests: 23 serial cases / 1,129 assertions; the same 23 cases
on two MPI ranks pass 1,134 assertions per rank.
- Broader Newton, numerical-strategy, gravity and FGMRES regression tests:
35 cases / 357,016 assertions. Together the serial groups cover 58 cases.
- Python artifact-checker tests: 25 frozen-search cases, 27 prior cases and
4 live-checker regressions, all 56 passing.
- Actual frozen campaigns: nine original cases and three repeats, all passing
the independent recorded-vector/provenance audit.
- Matched live pair: 1,083 scalar-decision/provenance checks pass. These check
recorded true-defect observations rather than independently reapplying FEM.
Coverage includes smaller-beta acceptance after full-step rejection, preparation
failure followed by success, first-accepted stopping, best-candidate replay,
complete rejection, later-candidate/replay exceptions, restoration, near-gate
budget preservation, zero predicted decrease, already accepted originals, invalid
and rank-mismatched options, rank-local rejection, and typed recipe composition.
Real-FEM production tests cover the original and new policies on raw and gravity
paths, preservation of the outer linear report, and checkpoint restoration.
The checker reconstructs the affine prediction, auxiliary RHS, unscaled full-J
defect and cap, beta state updates and remainder identity from saved vectors.
It verifies shared budget use and first-accept stopping, checks recorded fresh
selected-state replay and restoration evidence, and checks accepted-state and
normalization invariants and input/output hashes. It does
not independently rerun FEM or physical quadrature.
## Evidence and reproduction
Evidence root (outside the source tree):
`/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/damped_coupled_2026-09-18`
The original frozen screen binds to source `25816d4`; the repeats and matched
Newton cases bind to `1876229`. Their diagnostic binary hashes are recorded in
each campaign's `provenance.json`. The repeats use the same binary hash as the
screen. Test provenance and logs are in the evidence root. Tests were compiled
at `422c46b`; the subsequent source change `25816d4` only hardened the frozen
experiment's finite-metric guards.
Versioned cases:
- `damped_coupled_screen_2026-09-18.json`
- `damped_coupled_repeat_2026-09-18.json`
- `damped_coupled_newton_2026-09-18.json`
Use `run_plateau_campaign.py` with a clean committed source, its configured build,
`--mesh`, `--cases`, and a fresh `--output`. The build copies an immutable
executable before any case runs. Case manifests currently name the retained
absolute snapshot paths; relocate those explicitly when reproducing elsewhere.
After timed cases finish, run:
```sh
python3 experiments/check_damped_coupled_trial.py EVIDENCE/screen_v1 --output EVIDENCE/screen_v1_audit.json
python3 experiments/check_damped_coupled_trial.py EVIDENCE/repeat_v1 --output EVIDENCE/repeat_v1_audit.json
python3 experiments/check_damped_coupled_newton.py EVIDENCE/newton_v1 --output EVIDENCE/newton_v1_review.json
```
`TIMING_NOTE.md`, `repeat_comparison.json`, the per-case run records and all raw
CSVs/vectors preserve the timing exclusion and reproducibility evidence.

View File

@@ -0,0 +1,446 @@
# Independent density order: controlled study
Branch: `research/density-order-study-20260919`.
Parent: `7ed4d23`, the completed negative-density investigation.
The separate log-coordinate assessment is on `research/log-density-assessment-20260919` at `90580b2`.
**Finding:** Q3 removes the resolved n=1 density undershoot, and Q4 substantially
improves higher-index density accuracy. Neither provides positivity at higher n
or resolves the n=3 coupled-solver stall in the common eight-step budget. All
n=1 and n=1.5 controls converge and remain well virialized. Density remains an
independent unknown. Log density was assessed mathematically and in small 1D
controls, not implemented in the coupled stellar solver.
## Question and controls
Does increasing only the independent density approximation order reduce the
observed unphysical undershoots, improve internal EOS consistency, and preserve
virial accuracy at acceptable coupled-solver cost?
The density field remains an independent unknown in every equilibrium solve.
The frozen EOS projections are observations of approximation spaces; none is
installed as a replacement field or used to alter a solver state.
The baseline is discontinuous tensor Q2 density. The alternatives are Q3 and
Q4 in the same Gauss-Legendre nodal family. Enthalpy remains continuous Q3;
gravity retains its RT2/Q2 pair; displacement remains Q3; the mesh and geometry
are unchanged. The surface uses the existing degree-four spherical harmonics
with all azimuthal orders and simultaneous interior/surface solution.
The active density block has 832 times `(p+1)^3` coefficients: 22,464 at Q2,
53,248 at Q3 and 104,000 at Q4. Other field blocks retain their dimensions.
The central-density constraint is present only in the n=3 cases.
## Implementation and mathematical scope
`MEAN_FIELD_DENSITY_POLYNOMIAL_ORDER` selects the base density order at build
time; its default remains two. The existing uniform order increment still
applies, and is zero throughout this study. The field registry supplies the
selected order to typed field spaces, quadrature form queries, adapters,
normalization and compiled block layouts. The physics-facing API is unchanged.
Under the study's default policy the closure selects a rule covering both its
density mass form and EOS source form. Their nominal degrees differ once density can have higher order
than enthalpy. Selecting the greater resolved rule preserves policy overrides
and the Q2 baseline. Adjacent requested orders may use the same MFEM Gauss rule,
so a missing nominal bound does not by itself prove actual underintegration.
Q3 is a useful n=1 control because the linear EOS image of Q3 enthalpy lies in
the density space. For n=3, a general Q3 enthalpy cubed is Q9. For n=1.5 it is
nonpolynomial. Raising density order therefore does not promise positivity for
the higher-index models.
There is also a discrete consistency benefit at Q3 and above. On each cell,
Q3 enthalpy belongs to the DG density test space, even through the common
curved VALUE mapping. If `a` represents that enthalpy in the density basis and
`R` is the physical closure residual, the implemented polytropic EOS gives
`sum_q w_q h_h rho_h - (n+1) sum_q w_q P(h_h) = a^T R`.
A zero closure residual therefore enforces this enthalpy-weighted EOS moment
cell by cell under the closure quadrature. Q2 does not generally enforce it.
This algebraic property does not establish positivity or virial balance;
other quadrature rules and finite residuals introduce their own defects, and
the central-density border does not change this identity.
## Frozen and coupled observations
Frozen observations retain the saved enthalpy and geometry from the n=1 and
n=1.5 nonrotating equilibria and the n=3 initial seed. Each target space receives
an independently assembled physical-volume-weighted L2 projection, with one
common q26 quadrature, and a nodal interpolant of `rho_EOS(h_h)`. The latter is
explicitly not the original independently tabulated Lane-Emden seed.
The squared EOS error has a higher degree than the projection equations. A
separate shared q30 evaluation checks it against q26 without changing or
re-solving the projected fields. Both rules are also used on coupled final
states. At fractional n this is a numerical sensitivity check rather than a
polynomial exactness argument.
The coupled runs retain the same production quadrature policy, whose resolved
rule can change when density order changes. Actual closure rules are saved for
each case. The frozen common-rule controls isolate approximation order more
strictly; the coupled comparison measures the complete consistent
discretization, including its policy-selected quadrature adjustments.
Density order does not enter the pressure-force rule or its enthalpy
admissibility guard: their field operands are enthalpy and the displacement
gradient. Pressure-preparation rejection counts therefore measure changed
reached states and coupled directions, rather than a density-order change in
pressure sampling. The current preparation order evaluates displacement and
pressure before the barotropic closure. Closure therefore cannot preempt that
pressure stage in these runs; all rejection sources are nevertheless retained
separately rather than interpreting a stage count as total admissibility.
Coupled runs use the original Lane-Emden initialization, the same normalization
and default preconditioner, an FGMRES restart of 160, at most 200 linear
iterations per step, relative linear tolerance 0.03, and at most eight Newton
steps. Nonlinear relative tolerance is 1e-8 and absolute tolerance is zero.
Cases cover n=1,1.5,3 without rotation and the established n=1,J=0.01 rotating
control. A failure within this budget is a recorded trajectory outcome, not a
proof that the discretization has no root.
The initializer tabulates Lane–Emden density and enthalpy before constructing
either FEM field, then interpolates them independently into their spaces
(`libmeanfield/impl/seed/lane_emden.cpp`, lines 231–236, and
`libmeanfield/impl/seed/stellar_equilibrium_projection.cpp`, lines 164–180).
Gravity uses the represented density; it does not replace enthalpy. Thus the
production density seed is `I_p(rho_LE_tabulated)`, whereas the frozen nodal
and L2 controls are `I_p(rho_EOS(h_h))` and `Pi_p(rho_EOS(h_h))`.
Nonlinear EOS evaluation does not commute with either radial or FEM
interpolation. Increasing density order does not remove the discrepancy
between the tabulated density target and the EOS image of represented Q3
enthalpy. Source structure supports unchanged seeded enthalpy across these
orders; no cross-run bitwise identity of the initial states is asserted.
For n=3, the existing central-density phase condition constrains central
enthalpy to its EOS value at the requested central density; it does not directly
pin the independent DG density's point value. Bordered convergence is assessed
alongside the residual with artificial central forcing removed and the
normalized size of that forcing. That unbordered diagnostic retains the scalar
constraint rows. A small bordered residual or virial alone cannot establish
that the artificial forcing has vanished.
All expensive builds, numerical cases and artifact audits run serially.
Reported solver costs must exclude the post-solve observer and distinguish
Newton steps, Krylov work, preparation and preconditioner refresh.
The normalized residual and its relative stopping threshold belong to each
order's discrete system. Changing density order changes its test space,
diagonal Riesz weights and initial interpolant as well as possibly its resolved
quadrature. A smaller final residual across orders is not a physical-error
ranking. Krylov totals also reflect different Newton trajectories, warm starts
and per-action costs; they do not by themselves measure preconditioner quality.
Physical diagnostics and measured Newton time are therefore reported alongside
the iteration counts and density block sizes.
Timings are single observations on this workstation, with serial workloads;
they are not repeated benchmark means or estimates with error bars.
Density sign regions are integrated by isolating polynomial roots of degree
two through four along reference-cell lines. The observer also checks surface
traces, EOS mismatch, signed and negative mass, moments and unchanged source
fields. It separates resolved negative witnesses from values at reconstruction
uncertainty. Tangential sampling and mapped integration remain numerical
observations, not global sign certificates.
Here `M = integral rho_h dV` is signed mass,
`M_- = -integral min(rho_h,0) dV`, and `V_-` is the volume where density is
negative. Reported fractions are `M_-/abs(M)` and `V_-/V`; the denominator of
the mass fraction is not the integral of absolute density. EOS L2 error means
`sqrt(integral (rho_h-rho_EOS(h_h))^2 dV)` in the model's units, without an
additional relative normalization.
If the stored-state observer encounters negative enthalpy, complete EOS error
integrals are marked undefined while density integrals remain reported. No
density is clipped. Both virial definitions from pressure evaluated at enthalpy
and, where admissible, at density are retained; the required virial tolerance
remains 1e-5.
The summary enthalpy minimum and EOS-availability flag refer to integration
nodes. Surface enthalpy samples and the enthalpy at exported negative-density
witnesses are reported separately. Sliced mass and volume are cross-checked
against the physical observer; first moments and inertia are only compared,
because their additional coordinate factors need not be integrated exactly by
the fixed eight-point normal rule. Tangential refinement alone cannot establish
accuracy in that normal direction.
## Results
### Frozen approximation controls
The frozen campaign completed all three cases and its final artifact audit
passed. The following uses the common-q26 L2 projection; EOS L2 errors use the
separate unsliced q30 measurement. Negative measures use the finest root-sliced
tangential rule. These are approximation controls, not new equilibrium solves.
| Frozen model | Density order | M_- / abs(M) | Negative volume fraction | EOS L2 error |
|---|---:|---:|---:|---:|
| n=1 equilibrium | Q2 | 6.09585e-8 | 3.27346e-4 | 1.25266e-4 |
| n=1 equilibrium | Q3 | 1.05e-31 (unresolved roundoff) | 2.49e-16 | 1.56e-15 |
| n=1 equilibrium | Q4 | 1.25e-31 (unresolved roundoff) | 2.73e-16 | 1.60e-15 |
| n=1.5 equilibrium | Q2 | 2.24299e-5 | 1.49181e-2 | 3.67965e-4 |
| n=1.5 equilibrium | Q3 | 9.33602e-6 | 1.04476e-2 | 1.12325e-4 |
| n=1.5 equilibrium | Q4 | 3.18362e-6 | 6.83440e-3 | 4.80663e-5 |
| n=3 seed | Q2 | 2.92063e-5 | 1.21064e-1 | 1.06409e-2 |
| n=3 seed | Q3 | 2.63486e-6 | 3.73200e-2 | 6.86223e-4 |
| n=3 seed | Q4 | 1.02066e-8 | 1.69628e-2 | 3.84980e-5 |
The n=1 control matches the representability argument: Q3 and Q4 contain the
linear EOS image of Q3 enthalpy, and no resolved negative witnesses remain.
Higher-order density does not guarantee positivity for either higher-index
case. The n=3 Q4 negative mass is about 2,862 times smaller than Q2, yet negative
density still occupies about 1.70% of the sampled stellar volume.
The difference between n=1.5 and n=3 is consistent with surface regularity.
Where enthalpy vanishes linearly, the fractional-index density behaves as
distance-to-surface raised to 1.5 and has a singular second derivative. For
n=3, cubing the represented enthalpy gives a polynomial Q9 target. Increasing
density order can therefore improve the integer-index approximation very
rapidly without resolving the conditioning of the coupled nonlinear equations.
At n=1.5, changing the error rule from q26 to q30 changes the Q4 EOS L2 norm by
about 0.18%; the corresponding fixed eight-point root-sliced norm differs by
about 2.2%. This is why the unsliced q30 values are used above. Tangential
refinement gives stable negative masses but cannot establish convergence of
the fractional EOS error in the normal direction. The integral-index norms
agree across q26/q30 to arithmetic accuracy, except for relative comparisons of
n=1 Q3/Q4 errors that are already at roundoff.
### Coupled results
All nine n=1 and n=1.5 controls converged with full Newton steps and no rejected
trials. Their energy and force virial errors from `P(h)` are all below 6.6e-7.
The following times sum Newton iterations and exclude initialization and the
post-solve density observer.
| Model | Density | Newton updates | Krylov iterations | Newton seconds | M_- / abs(M) | EOS L2 error, q30 |
|---|---:|---:|---:|---:|---:|---:|
| n=1, J=0 | Q2 | 5 | 212 | 147.5 | 6.09585e-8 | 1.25266e-4 |
| n=1, J=0 | Q3 | 6 | 286 | 204.3 | unresolved roundoff | 3.13581e-16 |
| n=1, J=0 | Q4 | 6 | 286 | 215.1 | unresolved roundoff | 3.51021e-16 |
| n=1, J=0.01 | Q2 | 6 | 296 | 196.1 | 6.11256e-8 | 1.25327e-4 |
| n=1, J=0.01 | Q3 | 6 | 305 | 217.8 | unresolved roundoff | 7.26203e-16 |
| n=1, J=0.01 | Q4 | 6 | 304 | 229.1 | unresolved roundoff | 3.90198e-16 |
| n=1.5, J=0 | Q2 | 6 | 335 | 222.0 | 2.24535e-5 | 3.67965e-4 |
| n=1.5, J=0 | Q3 | 6 | 329 | 241.7 | 9.35454e-6 | 1.12195e-4 |
| n=1.5, J=0 | Q4 | 7 | 397 | 303.7 | 3.20115e-6 | 4.80640e-5 |
For n=1, Q3/Q4 remove the resolved undershoot and reduce the EOS mismatch to
roundoff. Q3 and Q4 also agree in their virial diagnostics to about 1e-14. The
nonrotating Q3/Q4 total times are 39%/46% above Q2, but both took an extra
Newton step: their fifth residuals were 1.91e-12 and 1.80e-12 against thresholds
of about 1.55e-12 and 1.54e-12. Q2's fifth residual narrowly passed its own
threshold. Those total-time differences should not be interpreted as pure
per-iteration order overhead. The rotating control takes six updates at every
order; Q3/Q4 cost about 11%/17% more there.
For n=1.5, Q3 reduces negative mass by 2.40 times and EOS L2 error by 3.28 times
for 8.9% more Newton time. Q4 reduces them by 7.01 and 7.66 times, respectively,
for 36.8% more time. Its sixth residual, 2.26e-12, narrowly missed its 1.93e-12
threshold; the seventh update cost 58.8 seconds. Negative volume fractions
remain 1.493%, 1.046% and 0.685% at Q2, Q3 and Q4. These are converged discrete
roots with a resolved density defect, not merely incomplete Newton iterates.
Density/EOS consistency is not the only internal accuracy measure. At n=1.5,
`hydrostatic_gradient_rms` is 0.00727475, 0.00731970 and 0.00729901 at Q2/Q3/Q4.
It is the unscaled volume RMS of `grad(h) + g_h - grad(Psi)` in model
acceleration units, using the independent gravity-gradient field `g_h`.
It is neither a relative error nor the normalized algebraic residual. Thus
density enrichment has not appreciably improved this local balance diagnostic.
None of the three n=3 cases converged within eight updates. Their endpoints
must not be treated as equally accurate equilibrium models or their times as
time to solution.
| Density | F_final / F_initial | Smallest accepted alpha | Krylov iterations | Newton seconds | Energy virial, P(h) | Force virial, P(h) |
|---|---:|---:|---:|---:|---:|---:|
| Q2 | 0.430062 | 1/64 | 221 | 301.6 | 1.77163e-4 | 1.34597e-4 |
| Q3 | 0.985301 | 1/256 | 452 | 478.8 | 8.07504e-6 | 2.28169e-5 |
| Q4 | 0.987949 | 1/512 | 458 | 508.2 | 1.37586e-5 | 2.84372e-5 |
Q3 reaches the energy-virial milestone alone; its force virial and nonlinear
residual still fail their respective criteria. Q4's better approximation
space does not produce a better virial endpoint than Q3. Q2 recovers larger
steps during this window, while Q3/Q4 make only about 1–1.5% residual progress.
This is evidence of a stalled short trajectory, not a proof against eventual
convergence with a longer run or different initialization.
All recorded n=3 linear solves meet their true-residual tolerance. Q2 has four
pressure-force rejections and four insufficient-decrease rejections; Q3 and
Q4 each have five and nine. No other rejection stages occur in these runs.
Both enriched cases first accept only 1/256 of their Newton direction. The
unchanged pressure quadrature makes this a change in reached states and
directions, not a change in pressure sampling. Increasing density order alone
has not removed pressure-admissibility and insufficient-decrease failures.
This campaign records those failures but does not independently localize the
nonlinear mechanism responsible for insufficient decrease.
The n=3 endpoint negative-mass fractions are 2.22117e-6, 9.13593e-7 and
5.21562e-7, with negative volume fractions 3.440%, 2.931% and 2.619%.
EOS L2 errors are 9.78088e-3, 8.99701e-4 and 5.08742e-4. These still-unconverged
fields show much less improvement than the frozen projections; their
different trajectories prevent interpreting those ratios as equilibrium
convergence rates.
The unbordered n=3 residuals remain 1.33327e-3, 7.18640e-4 and 7.26009e-4.
Normalized central-border forcing is 3.17039e-5, 1.27669e-5 and 1.20966e-5.
Thus neither a physical root nor vanishing artificial forcing has been
demonstrated. Signed multipliers and both virial definitions are retained in
the full tables.
The initializer distinction also matters. At n=3, the production Q4 seed has
an observed EOS L2 mismatch of about 5.26e-4 under q18, while the frozen Q4
projection of represented enthalpy has 3.85e-5 under q30. These are different
fields and quadratures, not a controlled improvement ratio. Together with the
initializer's source structure, they show why refining the density space need
not make the independently interpolated seed close to the weak closure
manifold. A closure-consistent initial guess is a separate hypothesis; it
could populate an independent density unknown without deriving it from
enthalpy during the subsequent coupled solve.
The actual closure rules also differ only at Q4 in this study:
| Model index | Q2 rule: achieved order / points per cell | Q3 rule | Q4 rule |
|---|---:|---:|---:|
| n=1 | 17 / 729 | 17 / 729 | 19 / 1,000 |
| n=1.5 | 19 / 1,000 | 19 / 1,000 | 21 / 1,331 |
| n=3 | 23 / 1,728 | 23 / 1,728 | 25 / 2,197 |
All 832 stellar elements use the listed rule in each case. Q2/Q3 therefore
share closure sampling, while Q4's coupled accuracy/cost includes the policy-selected
quadrature enrichment as well as the larger space.
### Implications and recommendation
Q3 is the economical consistency control for n=1: it contains the EOS image
and Q4 adds no resolved accuracy benefit there. Q4 is a useful higher-index
accuracy reference, but neither higher order is a positivity mechanism or a
demonstrated n=3 convergence remedy. The production default remains Q2; these
are isolated, reproducible research variants.
The next density-representation experiment should test a pointwise exponential
with an independently chosen vacuum reference, retaining density as an
independent unknown and solving surface and interior together. Judge it by
EOS consistency, accepted Newton steps, both virial diagnostics and cost—not
positivity alone. A separate conservative, closure-consistent seed control
would distinguish initialization effects from representation effects. Neither
of these further stellar experiments was performed here.
The complete tables and checked PNG/PDF figure are in
`../../diagnostics/density_order_2026-09-19/final_analysis/` relative to the
worktree. `trial_stages.csv` retains every source/disposition count, including
accepted trials; `coupled_outcomes.csv` retains all endpoint diagnostics.
[Comparison figure](../../../diagnostics/density_order_2026-09-19/final_analysis/density_order_comparison.png)
and [coupled-result table](../../../diagnostics/density_order_2026-09-19/final_analysis/coupled_outcomes.csv).
## Relation to the independent log-density hypothesis
The separate `LOG_DENSITY_ASSESSMENT_2026-09-19.md` in the log-density worktree
contains the derivation, primary-source MESA comparison and reproducible
one-dimensional controls. It does not contain a coupled stellar log solve.
Exponentiating polynomial nodal coefficients cannot remove the observed
between-node undershoots: the current negative fields can already have positive
nodal values. A pointwise representation `rho = rho_scale * exp(u_h)` changes
the trial family and gives positive interior density in exact arithmetic while
keeping density independent. A finite polynomial log field cannot also have an
exact zero-density trace.
For the present vacuum polytrope, the more suitable hypothesis is
`rho = rho_ref * exp(u_h)`, where a reference chosen independently of live
enthalpy is positive inside and vanishes at the surface with the correct
leading exponent. That exponent is a polytropic assumption to test, not a
universal prescription for the future general EOS. Geometry dependencies of
the reference and all mapped operators must be differentiated consistently.
The log-coordinate closure derivative is a density-weighted mass matrix.
Consequently normalization, local solves and globalization must account for
its small response near vacuum. Exponentiation alone does not fix those
conditioning issues, nor does it make the separately represented enthalpy
admissible in every Newton trial. Floating-point underflow also needs an
explicit rejection/range policy; silently clipping density would change the
equations. A typed physical-density evaluator and its directional action would
allow polynomial and log representations to be exchanged internally without
exposing representation details in the physics-facing API.
## Validation
All three builds passed the same 48 focused contract tests with the same RNG
seed. They cover field registration and spaces, quadrature policy, prepared
closure values and derivatives, gravity coupling, physical mass diagonals, and
the normalized complete operator.
| Density order | Test cases passed | Assertions passed |
|---|---:|---:|
| Q2 | 48 | 9,766 |
| Q3 | 48 | 9,822 |
| Q4 | 48 | 9,894 |
The final frozen artifact audit and all three coupled artifact audits pass.
All twelve coupled cases completed with their declared outcome. The audit helper
has nine passing small tests; the comparison helper has seven, including a check
that separately audited orders retain the same mesh and non-density blocks.
The independent log-coordinate control has four passing small tests.
No ESTER comparison or moderately rotating n=3 validation is part of this
study. The n=1,J=0.01 case is a rotation control; its numerical J value is not a
fraction of critical rotation.
## Reproduction and retained evidence
Raw campaigns, immutable diagnostic executables, input/output hashes, build
logs and test logs are retained under
`../../diagnostics/density_order_2026-09-19/` relative to this worktree.
Every campaign records its source commit, mesh hash, complete CMake cache,
arguments and runtime environment. The mesh SHA256 is
`ce11ae99e21e6c3bbfbee402acd2e191c1da0d8261d2227b4203f73f2f337a74`.
Producer commits are `241621c` for frozen controls, `c0e8551` for coupled Q2,
`cd71f37` for coupled Q3 and `e054c74` for coupled Q4. Later changes to reporting
scripts and this document do not replace those immutable executables or their
recorded provenance. The final comparison generator is from `c0a496e`.
The log control's source and CSV hashes were separately verified in
`log_reference_validation.json`.
The committed presets are `density_order_frozen_cases_2026-09-19.json` and
`density_order_coupled_cases_2026-09-19.json` in `experiments/`. Frozen replay
requires the earlier harmonic-surface campaign retained alongside these data;
the runner verifies the saved state, layout, metadata and original provenance.
For example, the Q3 configuration uses:
```sh
/Applications/CLion.app/Contents/bin/cmake/mac/aarch64/bin/cmake -S . -B cmake-build-release-density-q3 -G Ninja \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_CXX_COMPILER=/opt/homebrew/opt/llvm/bin/clang++ \
-DCMAKE_C_COMPILER=/opt/homebrew/opt/llvm/bin/clang \
-DCMAKE_MAKE_PROGRAM=/opt/homebrew/bin/ninja \
-DBoost_DIR=/opt/homebrew/anaconda3/lib/cmake/Boost-1.82.0 \
-DMEAN_FIELD_DENSITY_POLYNOMIAL_ORDER=3 \
-DMEAN_FIELD_UNIFORM_POLYNOMIAL_ORDER_INCREMENT=0 -DBUILD_TESTING=ON
```
Build `plateau_diagnostic` and `density_order_contract_tests` with two compile
workers. The focused test filter includes all non-normalization cases in that
target plus the reference-mass-diagonal comparison and complete normalized
operator test:
```sh
env OMPI_MCA_btl=self,sm cmake-build-release-density-q3/density_order_contract_tests \
--catch2 --reporter compact --rng-seed 1218739852 \
'~[normalization],Direct Reference Mass Diagonals Match Full True DOF Assembly,Normalized Stellar Equilibrium Preserves Physical Residuals Jacobians And Frozen Solve Coordinates'
```
The same fixed seed is used for the other density orders. Campaign runtime settings are
`OMPI_MCA_btl=self,sm`, `OPENBLAS_NUM_THREADS=1`, `OMP_NUM_THREADS=1` and one MPI
rank. The campaign runner uses a fresh output directory for each invocation;
its `--timeout 1800` applies per case. Use the order-specific build directory
and the coupled preset with `experiments/run_plateau_campaign.py`; all other
arguments are preserved in each `provenance.json` and `*_run.json`.
`experiments/audit_density_order.py` checks the retained evidence independently
of the producer's summary tables. It validates saved polynomial algebra,
bindings, sums, trial histories and declared gates, but cannot reconstruct the
full FEM integrals because local matrices, RHS vectors and all mapped weights
are not exported. `experiments/summarize_density_order.py` consumes only passing
audit JSON files and emits comparison tables and scientific figures. It keeps
undefined values and unresolved sign witnesses explicit.

View File

@@ -0,0 +1,124 @@
# Field coupling review: higher-index harmonic models
Date: 2026-09-19. This is a read-only source and mathematical review supporting the current native spherical-harmonic convergence experiments. No solver changes or numerical runs were performed for this review. Proposed mass-inverse and closure-path changes below are **unimplemented and have no demonstrated convergence or performance benefit**. The stellar LDU policies already exist; matched frozen tests, including the newly planned n2/n3 controls, must establish their usefulness here.
The relevant current configuration uses independent Q2 density, H1 Q3 enthalpy and a simultaneous native harmonic surface. Conclusions from the earlier unrestricted nodal-shape campaigns do not establish the bottleneck of this configuration. Density and enthalpy remain separate nonlinear unknowns throughout this discussion.
## What is measured, and what is not
The completed n3, J=0 baseline trajectories have different final nonlinear residual distributions after twelve updates:
| Outer linear tolerance | Final full residual | Leading shares of squared nonlinear residual |
|---|---:|---|
| 0.03 | 8.2439198751e-4 | Poisson 79.9270%; gravity-gradient relation 13.8543%; closure 6.14387% |
| 0.003 | 5.5073074058e-4 | Closure 71.32895%; Poisson 25.87622%; gravity-gradient relation 1.65855% |
These are observations from `diagnostics/coupled_convergence_2026-09-19/screen_v1`, relative to the workspace containing this worktree. Both cases exhausted the nonlinear update budget, and every recorded linear solve passed its requested gate. They follow different trajectories: the tighter run's smaller final residual is not a same-state comparison of preconditioners or evidence of a residual floor.
A large **nonlinear closure residual** does not demonstrate a large closure **linear defect**. It can reflect nonlinear EOS curvature, changes in geometry, or the distribution of the accepted linear error. The current frozen benchmark should separate these with `preconditioner_blocks.csv` and `linear_direction_trial_blocks.csv`: compare the closure row of `Jp+F` with the closure component of `F(x+alpha p)-(F+alpha Jp)`. The latter trial vectors are not saved; the exported block remainder norms remain producer observations rather than independently reassembled FEM evidence.
No claim below identifies one of these mechanisms as the demonstrated cause of the n3 trajectory.
## Source facts: exact equations and current inverse
The registry declares density an independent L2 field and enthalpy an independent H1 field; the latter has base order three. See `libmeanfield/interface/field/field_registry.cppm:29–42` and `:293–317`.
On fixed geometry, the closure row is
\[
F_\rho=\int_{\Omega_*}v_\rho[\rho-\rho_{\rm EOS}(h)]\,dV,
\qquad
\delta F_\rho=M_\rho\delta\rho-C\delta h,
\]
where `C` is the cross-mass operator weighted by `d rho_EOS/dh`. Preparation caches both the closure mismatch and that derivative on the actual mapped production quadrature. The exact action applies the density mass term minus the weighted enthalpy term. See `libmeanfield/impl/operators/prepared_barotropic_closure.cpp:647–675` and `:918–931`.
The hydrostatic enthalpy block is a mapped H1 mass matrix, accompanied by a cross-mass action from the gravity potential. Surface-condition rows are subsequently replaced. See `libmeanfield/impl/operators/prepared_hydrostatic_equilibrium.cpp:710–749` and `libmeanfield/interface/preconditioning/material_surface.cppm:1432–1437`.
The baseline is not diagonal in all physical fields. Its default material policy is `SurfaceThenMaterialTriangular`, with diagonal density, enthalpy and surface inverses. Writing `a` for surface parameters, one application computes
\[
\delta a=D_a^{-1}b_a,\qquad
\delta h=D_h^{-1}(b_h-A_{ha}\delta a),\qquad
\delta\rho=D_\rho^{-1}(b_\rho-A_{\rho a}\delta a-A_{\rho h}\delta h).
\]
The `h -> rho` action is the **exact prepared EOS cross derivative**. Surface-to-material actions also use the prepared closure and hydrostatic operators. The approximation is in the diagonal mass solves and surface surrogate, together with the missing reverse material-to-surface recovery. References:
- Default policy: `libmeanfield/interface/preconditioning/material_surface.cppm:679–694`.
- Exact cross actions: the same file, `:783–819`.
- Triangular application: `:997–1009`.
- Density/enthalpy diagonal assembly: `:1425–1438` and `libmeanfield/impl/operators/prepared_barotropic_closure.cpp:717–743`.
At the next level, `IndependentStellarSubsystems` applies material/surface and gravity inverses separately. It omits their direct cross actions within the structure inverse. The surrounding generated scalar-border completion is still present, so this does not mean the complete preconditioner lacks every global coupling. See `libmeanfield/interface/preconditioning/stellar_structure.cppm:347–351`, `:861–869`, and `experiments/plateau_preconditioner_benchmark.hpp:133–137`.
The live `gravity-schur` recipe retains that same independent structure policy and material block. It changes only gravity factorization: fixed correction sweeps target the gravity-only consistent Schur operator `B R B^T`, using the existing surrogate inverse for corrections. It does not insert EOS/material feedback into that target. See `experiments/plateau_newton_preconditioner.hpp:60–65`, `experiments/plateau_preconditioner_benchmark.hpp:110–137`, and `libmeanfield/interface/preconditioning/gravity_field.cppm:298–326`.
The surface/scalar Schur experiment also depends on the quality of its remaining field inverse `B = R_F P0 E_F`; exact coarse-row recovery does not make that field inverse exact. See `experiments/plateau_surface_border_schur.hpp:147–158`.
## Near-vacuum derivative: derivation and limits
For `s=(n+1)K`, the implemented positive-enthalpy relation gives
\[
\rho=(h/s)^n,\qquad
\chi=\frac{d\rho}{dh}=\frac ns(h/s)^{n-1}.
\]
The derivative is finite and constant for n=1, and tends to zero at the surface for n>1. Relative to its central value, a profile with `h/h_c=t` has `chi/chi_c=t^(n-1)`: at `t=0.1`, that ratio is 0.1 for n=2 and 0.01 for n=3. These are analytical scaling examples, not measurements of the present endpoints. Source: `libmeanfield/interface/eos/polytropic.cppm:145–164`.
Neither current material diagonal divides by `chi`. In particular, `M_rho` remains the mapped density mass matrix. Vanishing `chi` therefore does **not**, by itself, prove that this local material block is singular. It changes the spatial distribution of the thermodynamic coupling; its interaction with approximate mass solves and gravity feedback is a hypothesis requiring frozen evidence.
Relative curvature satisfies `rho''/rho'=(n-1)/h` for positive h. A direction large relative to local h can consequently have an appreciable nonlinear closure remainder even with an accurate linear solve. At fixed geometry, the exact n=3 closure remainder is
\[
F_\rho(x+\alpha p)-F_\rho(x)-\alpha(Jp)_\rho
=-\int v_\rho\frac{3h(\alpha\delta h)^2+(\alpha\delta h)^3}{(4K)^3}\,dV.
\]
Moving geometry adds geometric and mixed terms. The formula is a derivation from the implemented EOS, not a diagnosis of the measured dominant mode.
## Conditional field-inverse improvements
1. **Use the existing two-way stellar LDU as a matched control.** `ApproximateStellarBlockLDU` first solves material, propagates its density/surface response into gravity, then propagates the gravity response back into material. Those cross actions include the exact density source, geometry response, potential-to-hydrostatic action, and gravity-gradient-to-mechanical action. See `libmeanfield/interface/preconditioning/stellar_structure.cppm:371–384`, `:453–478`, and `:484–511`. This is an inexpensive implementation choice because the policy already exists. It still approximates the field Schur complement; additional inverse and cross-operator applications must be included in cost comparisons.
2. **Strengthen mapped mass inverses if frozen linear defects implicate them.** Independent DG density permits an exact local mapped-mass factorization per element; Q2 hexahedral cells have 27 density coefficients. Retain the exact EOS cross action and strengthen the H1 enthalpy mass inverse with a fixed stationary application. H1 connectivity precludes treating its inverse as independent element solves without assembly/overlap handling. The replaced surface rows also require explicit lifting or a free-node formulation before assuming symmetry and using an SPD solver. Cache factors by the relevant geometry generation and retain typed application-contract checks. These changes are not implemented here; no speedup is assumed.
3. **Consider an EOS-aware field Schur only if simpler controls warrant it.** With surface parameters and generated scalars held fixed, let `m=(rho,h)` and let `g` denote the mixed gravity fields. The exact algebraic elimination is
\[
A_{mm}=\begin{bmatrix}M_\rho&-C\\0&H\end{bmatrix},\qquad
S_g=A_{gg}-A_{gm}A_{mm}^{-1}A_{mg}.
\]
The additional term carries potential -> enthalpy -> density -> gravity feedback missing from gravity-only refinement. The signed operators must come from the actual Jacobian, including boundary rows and normalization. This Schur operator is not guaranteed positive definite, so the existing positive Poisson surrogate cannot simply be declared its exact inverse. This would eliminate correction variables only inside a preconditioner; density remains an independent nonlinear unknown.
The current material prepared implementation specializes its stored inverse types to diagonal backends. A mass upgrade needs an explicit typed prepared-backend extension rather than relabeling the existing diagonal recipe. None of these choices requires additional physics-facing parameters or changed equations.
## Conditional affine-target closure trial path
This is a separate nonlinear hypothesis, to consider only if the frozen trial observations identify closure remainder as a substantial obstacle. It is not an implemented or demonstrated remedy.
Keep the full Newton unknowns and direction. Freeze the accepted normalized residual `F0` and full action `J0 p`, and define the closure target
\[
L_\rho(\alpha)=R_\rho[F_0+\alpha J_0p].
\]
At an admissible prepared raw trial `y=x0+alpha p`, solve
\[
A_{\rho\rho}(y)c_\rho=L_\rho(\alpha)-F_\rho(y),
\]
then alter only density. `A_rhorho(y)` is the current mapped DG mass block with the actual row/value normalization. It is not the density diagonal approximation. Closure is affine in density at fixed h and geometry, so a fresh preparation can verify the resulting closure residual against `L_rho` separately from the inner linear solve.
The target must be the **affine prediction**, not zero closure: it makes the correction zero at alpha=0 and preserves the original Newton tangent. With a locally Lipschitz Jacobian, a bounded mass inverse and sufficiently accurate auxiliary solution, the correction is `O(alpha^2)` up to arithmetic error. At exact vacuum with `1<n<2`, the positive-part power law is C1 with a Hölder derivative; its second derivative is singular. A uniform quadratic remainder must not be claimed there: `O(alpha^n)` can occur instead. The n=3 polynomial case does not have that particular regularity obstruction.
This operation neither makes density a derived state variable nor guarantees its positivity. It also changes total mass, rotational inertia and mechanical balance. It cannot repair a pressure-preparation rejection when enthalpy and geometry remain unchanged; production independently rejects negative sampled h (`libmeanfield/impl/operators/prepared_barotropic_closure.cpp:632–644`, with the pressure guard also retained).
**Correct composition order:** correct density, freshly prepare, then correct gravity against the original frozen target `G0+alpha Jg0 p` using the changed density source. Gravity-only changes leave h, geometry and closure unchanged, so they preserve the closure target. They can still alter hydrostatic and surface residuals. Full residual acceptance, admissibility, independently checked auxiliary defects and transactional restoration remain mandatory.
The existing strategy lifecycle supports such an experiment but does not provide this ordering automatically. `PreparedNewtonStrategy::PrepareTrial` invokes gravity first, and third-slot `TryImproveTrial` follows afterward (`libmeanfield/interface/solver/stellar_newton_strategy.cppm:508–521`). Inserting closure there would need another gravity correction, or a deliberate typed composite preparation policy ordering closure before gravity. Reuse the fresh affine-target verification pattern in the same file at `:192–245`; keep the full Newton solve and original direction capture authoritative.
The prepared closure currently exposes complete actions, exact diagonal assembly and its mapped rule visitor, but no reusable exact DG mass inverse (`libmeanfield/interface/operators/prepared_barotropic_closure_operator.cppm:73–118`). A future policy must supply that inverse or a separately verified equivalent. The decision to build it remains pending the actual frozen linear-defect and trial-remainder data.

View File

@@ -0,0 +1,29 @@
# Compact gravity applications
Branch: `research/gravity-compact-application-20260917`.
This change removes work from applications inside a gravity-only Krylov solve. It does not change equations, coordinates, tolerances, gravity completion, line search, or the verified true-defect gate. Full root preparation and inverse refresh remain mandatory.
## Selection and coordinates
`PreparedGravitySubsystem` accepts a final compile-time application policy. Its default, `AutomaticGravityApplications`, uses a compact action only when a registered capability is present and the supplied local partition exactly equals the typed canonical partition. A collective minimum selects the same path on every rank. `RootRestrictedGravityApplications` keeps the original full-root injection/application/restriction as a test reference and fallback. Existing construction and user-facing stellar specifications are unchanged.
The built-in operator capability requires the known physical stellar core and checks the compiled specification contributions: none may modify gravity rows. It reuses `GravityFieldOperator::ApplyGravityUnknowns`, the existing affine action on gradient and potential at fixed material state and geometry. This applies `[M B^T; B 0]`, including existing reduced/full boundary maps, without invoking zero density or displacement variations. Its compact packing is always gradient followed by potential; the typed root layout chooses the row and value locations independently.
Normalization is unchanged: the action is `D_r A_G D_x^-1`, and the inverse action is `D_x P_G D_r^-1`. Factors are gathered from the frozen normalization on refresh, after the new root preparation is ready. Root generations and child inverse currentness invalidate stale applications. No pointers into normalization buffers survive a refresh.
The direct inverse capability recognizes the standard normalized physical preconditioner and independent material/gravity factorization with the exact gravity block identities. It invokes the already-prepared physical gravity block. Unknown custom inverse recipes and other structure factorizations retain the full-root restriction. The capability's application contract is included in the wrapper's compile-time contract; a potentially flexible branch cannot be advertised as stationary. Selecting a compact inverse is a preconditioning choice, not an assertion that it is the exact gravity inverse. Full-root restriction equivalence must be measured for actual fixtures; the same exact gravity true-defect gate is always used.
`GravityCompactOperatorAccess` and `GravityCompactInverseAccess` are explicit extension contracts. Custom code opts in by specializing them; similarly named getters alone never enable a shortcut. A registered operator promises the exact gravity principal block, canonical partition, and full diagonal factors. A registered inverse promises a current compact physical action with a declared application contract. These are lower-level numerical extension points, not required model inputs.
## Verification
`tests/solver/gravity_compact_applications.cpp` compares compact and explicit root-reference actions for nontrivial directions, nonuniform row/state factors, and both standard and optional-central-border typed forms. It checks factor refresh, stale root and child inverse rejection, unknown inverse fallback, and collective fallback when only rank zero supplies a noncanonical map. Existing generic tests retain empty-local-rank and true-defect failure coverage.
`plateau_gravity_application_diagnostics.hpp` supplies `plateau_diagnostics::ProbeGravityApplications(subsystem, outputDirectory)`. Call after preparing the full normalized operator, refreshing its inverse, and preparing/refreshing the subsystem. It writes `gravity_applications.csv` with three deterministic nontrivial global directions, selected paths, relative/absolute compact-versus-full errors, and separate application times. It neither prepares a candidate nor changes accepted state. The reference policy also allows direct solve comparisons outside the probe. `check_numerical_strategies.py` automatically checks this CSV when present; `--require applications` explicitly requires it. Its default-fixture operator/inverse comparison uses `error <= 2e-12 * max(1, reference_norm)` and rejects nonfinite measurements. Fallback paths are reported without failing selection.
The integration campaign compiled and passed the compact mock tests in serial and on two ranks, and the real-FEM serial comparisons both with and without the central-density border. The frozen n=1.5 helper measured exactly zero operator and inverse output differences for all three dense directions. On that fixture compact operator applications took about 0.018 seconds versus 0.244 seconds for the root reference; inverse applications took about 0.160 versus 0.205 seconds. The first matched gravity solve took 7.25 seconds versus 18.36 seconds before the compact change, with the same 40 iterations and numerical result at the same true-defect tolerances. These are fixture measurements, not universal speedup guarantees.
`gravity_applications.csv` records selected paths and separate operator/inverse application times. The backend's `LinearSolveReport` also has application timing fields, but the current `numerical_strategy_inner.csv` records only aggregate inner solve time. Neither per-application speedup nor aggregate inner timing alone measures a complete Newton step; reduced outer work also includes full-system actions.
Full stellar MPI comparisons remain unvalidated: the larger two-rank integration selection encountered the existing logical radial surface interpolation restriction to one rank. Low-level distributed application and collective-fallback tests passed. The measured default inverse equivalence does not establish equivalence for arbitrary custom compact preconditioners. End-to-end models continue to require the existing strict convergence and virial checks.

View File

@@ -0,0 +1,169 @@
# Fixed-work mass-consistent gravity Schur refinement
This optional preconditioner policy leaves the exact full Newton Jacobian,
normalization, nonlinear merit, and defaults unchanged. It is selected through the
existing typed prescription:
```cpp
preconditioning::GravityFieldBlock(
backend::MatrixFreeChebyshev{.order = 5, .powerIterations = 20},
backend::HypreBoomerAMG<backend::FixedCycles>{backend::FixedCycles{.cycles = 3}},
preconditioning::GravityConsistentSchurLDU{
.correctionSweeps = 1,
.relaxation = 0.5
}
)
```
The numbers above specify a benchmark candidate, not a recommended production
setting. `GravityApproximateLDU` remains the default. The new policy composes with
all existing stellar-structure policies and specification-border handling.
## Algebra and sign
Write the mixed gravity block in its existing reduced field coordinates as
\[
D=\begin{bmatrix}M&B^T\\ B&0\end{bmatrix},\qquad
D\begin{bmatrix}q\\\phi\end{bmatrix}
=\begin{bmatrix}f\\g\end{bmatrix}.
\]
Let \(R\) denote the prepared mass inverse action used by flux recovery, and let
\(Q\) denote the existing reduced potential inverse action. The latter uses AMG
on the assembled diagonal-mass Schur surrogate. In particular, increasing the
accuracy of \(R\) does not automatically change the operator targeted by \(Q\).
The positive mass-consistent Schur action and its signed right-hand side are
\[
S_R=B R B^T,\qquad r=B R f-g.
\]
The new policy starts with the existing potential answer \(\phi_0=Q r\), performs
exactly the requested number of corrections
\[
\phi_{j+1}=\phi_j+\omega Q(r-S_R\phi_j),
\]
and uses the existing flux recovery \(q=R f-R B^T\phi_k\). For stationary linear
\(R\), this gives
\[
Bq-g=r-S_R\phi_k.
\]
Thus the corrected residual targets the Poisson row of the same approximate
mixed factorization used for recovery. The gradient-row residual still depends
on the quality of \(R\); this is not an exact inverse of \(D\). Even a converged
Schur refinement would invert the mass-approximated block only, unless \(R=M^{-1}\).
For fixed linear child inverses the potential error propagates with
\(I-\omega Q S_R\). A positive finite \(\omega\) does not prove contraction.
Neither the toy test nor the implementation establishes spectral bounds for the
stellar models. Benchmarking must measure full-J true defects and cost.
## Work, lifetime, and sparse actions
Each additional sweep costs one application each of \(R\), \(Q\), \(B\), and
\(B^T\). No Krylov iteration, convergence test, nonlinear preparation, or full-J
application occurs inside the refinement. Two potential-sized work vectors are
allocated once for positive sweep counts. The existing statistics count every
child application, and `schurRefinementSweeps` records completed corrections.
With positive sweeps, the prepared policy reuses the cached assembled divergence
already required by the Schur surrogate. The same sparse matrix and reduced DOF
maps supply both its forward and transpose actions throughout the factorization.
The cache precedes the borrowed operator in owner lifetime and is rebound after
discretization invalidation. Geometry-only refresh retains the computational-mesh
divergence while rebuilding the geometry-dependent mass inverse and Schur
surrogate.
With zero sweeps, the policy keeps the old matrix-free divergence binding and the
old LDU arithmetic, including operation order. This separate path permits exact
baseline comparison. Positive-sweep comparisons include both the refinement and
the equivalent sparse implementation of the coupling; sparse/matrix-free
equivalence is tested independently.
The policy preserves the existing compile-time application contract: it is
stationary linear exactly when both child backends declare that contract. A
tolerance-driven child remains flexible. Fixed work must not be mistaken for
linearity of an arbitrary child solver. Keeping the default fixed-cycle children
allows the specification border to retain its cached structural responses.
Sweep counts must be nonnegative; relaxation must be finite and positive. The
distributed prepared block validates these conditions collectively and requires
identical choices on every rank before constructing collective child solvers.
No upper bound on relaxation is claimed to ensure stability.
## Validation and comparison scope
The added unit tests check rational answers for a noncommuting dense mass/Schur
example, preservation of an exact Schur fixed point, zero-sweep bitwise baseline
equivalence, linearity, repeated-application independence, fixed work statistics,
and invalid options. Contraction is asserted only for the selected dense fixture.
The added FEM integration test compares sparse and matrix-free reduced divergence
and transpose actions on three dense vectors, compares the full refined action
against the matrix-free coupling implementation, and checks zero-sweep exact
equivalence using identical child inverses. It repeats these checks after geometry
and discretization revisions and tests stale rejection and cache rebuilding.
It also contains collective option-mismatch checks for multiple ranks, but those
checks have not executed successfully in the actual FEM fixture; see the MPI
limit below.
No benchmark result or production improvement is claimed by this implementation
note. Compare the new policy against the default using the same mass backend,
AMG cycles, material inverse, full-J operator, saved right-hand sides, and
scalar-border sources. Evaluate independent and two-way stellar-structure
policies separately so a coupling change is not mistaken for a gravity-inverse
improvement.
### Executed coverage and MPI limit
The retained `tests_v1` executable built from commit
`dc8d4b0501e2775b0d1938005e142411319d78b1` passed the focused serial selection:
**20 cases and 441,978 assertions**, including the new real-FEM Schur refinement
and cached stellar cross-action checks. Its SHA-256 is
`e11a49ebadc85206fad5a998b5cc6ee3ac074b498d09b3578d9ef5e0c5d0c04b`.
The same executable passed **13 cases and 213 assertions per rank** on two ranks
with selection
`[gravity_block][unit],[preconditioning][stellar_structure][unit],[coupled_shape_coarse]`.
This verifies the selected algebra and distributed coarse tests. It does not
establish distributed FEM Schur assembly, refresh, or option-mismatch handling.
The broader two-rank selection aborted before reaching the new Schur FEM test.
The existing `Prepared Gravity Block Diagonal Is Legacy Equivalent And Allocation
Stable` fixture constructs `PreparedMappedHDivMassOperator`, whose constructor
requires both a stellar element and a compactified vacuum element **on each
rank**. Rank 1 has no vacuum element in the production partition of
`sandbox.smesh`, so construction calls `MPI_ABORT` at that pre-existing check.
`fem::setup_fem` currently calls `GeneratePartitioning(rankCount, 1)` internally;
there is no partition override in the existing setup interface. A lightweight,
read-only reconstruction of the mesh dual graph and installed METIS 4 partition
call, using MFEM's descending adjacency order, reproduced the following split:
| Mesh | Rank | Core | Envelope | Vacuum |
| --- | ---: | ---: | ---: | ---: |
| `sandbox.smesh` | 0 | 0 | 220 | 384 |
| `sandbox.smesh` | 1 | 448 | 164 | 0 |
| Existing one-level refined mesh | 0 | 0 | 1,673 | 3,072 |
| Existing one-level refined mesh | 1 | 3,584 | 1,399 | 0 |
The refined mesh therefore has the same obstruction; it was inspected through
its partition graph, not subjected to another FEM run. Selecting only the new
test cannot remove its shared geometry-construction prerequisite. A deliberate
partition distributing every material across both ranks could exercise that
fixture, but adding a partition-injection seam is outside this preconditioner
experiment. Production mesh setup and partitioning remain unchanged.
The precise current validation claim is **serial FEM plus two-rank algebra/coarse
coverage**. Actual FEM Schur refinement, its distributed sparse-cache lifecycle,
and its collective option-rejection branches remain unvalidated on multiple
ranks. Logs, executable hashes, and commands are retained in the workspace under
`diagnostics/preconditioner_improvement_2026-09-18/tests_v1/`, specifically
`provenance.json`, `serial.log`, `mpi2.log`, `mpi2_units.json`, and
`mpi2_units.log`.

View File

@@ -0,0 +1,37 @@
# Gravity work accounting on direction rejection
The combined polynomial-enthalpy and reduced-gravity strategy checks descent
twice: once when selecting the enthalpy repair, and again after lifting the
repaired retained direction into gravity coordinates. A successful gravity
relift performs real auxiliary work even when the second check rejects the
direction before line search.
Previously, the successful-relift diagnostics were copied only after the second
check. Its early rejection could therefore leave solve counts, iteration counts,
timings, and the last inner residual at their earlier linear-solve snapshot.
The snapshot now occurs immediately after successful direction capture and
before the final descent check. Linear-report coordinates retain their existing
meaning; this changes no tolerance, direction, state, or acceptance decision.
The immutable `b21fa40` rotating `positivity-reduced` artifact records 20 gravity
solves and a positive final merit slope. Those counters can omit a successful
last relift: they do not distinguish rejection during enthalpy repair from
rejection after relifting. Its `direction_repairs` count also includes a chosen
positive repair fraction whose candidate subsequently fails descent. Historical
artifacts must retain these qualifications rather than being retroactively
interpreted as complete work counters.
The final `c82e68d` replay passes 30 provenance, trajectory, state, and report
checks. Its accepted-state file is bitwise identical; trial records and all
non-timing Newton fields match exactly. With the corrected source, its solve
and iteration counts remain 20 / 681. This establishes that the actual case
returns during enthalpy repair, before another gravity relift. The positive
slope therefore identifies a non-descent repair family. This replay does not
exercise the separate post-relift non-descent branch found by source review.
The source fix builds and passes the complete targeted regression selection
(43 serial cases / 1,886 assertions and 37 supported cases per MPI rank).
`models_v3_direction/direction_regression_comparison.json` records pinned old
and new source revisions, immutable executable/input hashes, every comparison,
and the conditional failure localization. It emits no localization if its
checks fail. The numerical controls and acceptance decisions are unchanged.

View File

@@ -0,0 +1,88 @@
# Gravity prepared-residual arithmetic experiment
This hypothesis branch changes only the arithmetic assessment used after a
gravity correction has passed its inner true-residual gate. It does not change
that inner tolerance, the full-system lifted Newton gate, nonlinear merit
acceptance, physical equations, or virial validation.
For fixed retained state, write the normalized gravity residual as
`G = A_q q + A_phi phi + b`. Its norm can be tiny while the separate terms are
large. Estimating arithmetic from `||G||` and the combined correction action
therefore misses cancellation and the floating-point addition of corrected
gravity coefficients.
Before changing the candidate, the workspace now measures the normalized
gradient and potential actions separately, for both the old state and its
correction. It infers the fixed source as `b = G_old - A_q q - A_phi phi`.
Selection uses the compiled field block types, and applications reuse the
prepared gravity operator. Scratch vectors are allocated with the workspace.
The assessment uses `256 epsilon` times the sum of those five contribution
norms and the norms of the old, desired, and freshly prepared gravity residuals.
This is an explicit arithmetic estimate, **not a rigorous forward-error bound**:
it does not bound cancellation inside each individual field action. The factor
does not create an absolute residual floor, so a common scaling of the gravity
equations scales the assessment equally.
Two separate requirements remain:
1. The discrepancy between the affine prediction and freshly prepared gravity
residual must fit the arithmetic estimate.
2. The prepared residual's distance from its target must not exceed the
**measured** inner true residual plus that estimate.
Diagnostics retain the raw affine discrepancy, raw target defect, arithmetic
estimate, and resulting target threshold separately. Nonfinite or negative
norm inputs fail the assessment. Each gravity attempt clears its correction
norm and prepared-assessment measurements before the raw candidate preparation.
An early preparation or inner-solve failure therefore leaves unmeasured values
as NaN, rather than reusing the preceding attempt's values. Initial gravity
completion follows the same rule. A failure in the corrected preparation can
still retain that attempt's measured correction norm.
The last completed inner solve's true defect and cumulative solve/iteration/
failure/time counters have a different lifetime: a candidate that fails before
calling the inner solver does not erase them. A line-search candidate rejected
before invoking the gravity strategy does not begin an auxiliary attempt and
leaves all last-attempt diagnostics intact. Diagnostic consumers must distinguish
these meanings. Diagnostics also report whether compact gravity operator and
inverse applications were selected.
`lastLinearReportSpace` labels the retained `lastLinearSolve` report from the
outer strategy's `Solve`. A later positivity-direction relift can fail while
that outer report remains converged in reduced coordinates. The evaluation then
reports `linear_solve_failure`; the auxiliary failure is reflected by the gravity
failure counter and last completed inner true defect. Changing only the report
space would incorrectly relabel the retained reduced-system norms. The full
lifted Newton gate precedes feasibility repair; a repaired direction must pass
its relift, descent check, and nonlinear acceptance, but is not claimed to solve
the original Newton equations.
Three focused tests, appended to `tests/solver/gravity_reduction.cpp`, cover
large cancelling contributions, rejection of defects beyond either gate,
nonfinite measurements, and scaling over twenty-four orders of magnitude.
All three passed with 28 assertions in serial and 28 assertions per rank on two
ranks. The subsequent production n=1, J=0 curvature control converged and passed
all eight virial checks, with no prepared-consistency failure. The n=1.5, J=0
curvature run likewise had no prepared-consistency failures: all 14 auxiliary
gravity solves passed, but the outer linear iteration cap stopped the model
before nonlinear convergence. These runs reassess the original auxiliary
rejection; the synthetic arithmetic tests alone do not establish stellar
convergence or validate the estimate as a rigorous error bound.
## Reporting regression
Branch `research/gravity-trial-diagnostics-20260917` moves this reset to a shared
attempt-entry helper, used by both trial strategies and initial completion.
Existing production rollback fixtures now assert finite measurements after a
completed curvature assessment, and unavailable prepared/correction fields after
a failed initial inner solve while retaining its finite true defect and counters.
No new stellar fixture or numerical behavior is introduced. The source-level
success-then-early-failure path is covered by the unconditional shared reset;
a separate expensive campaign is not justified for this reporting change.
The final `c82e68d` build passes the targeted serial suite: 43 cases and
1,886 assertions, including these added checks. The supported two-rank suite
passes 37 cases per rank (1,108 / 949 assertions). Full stellar MPI fixtures
retain their existing one-rank interpolation restriction. Immutable final
build/test evidence is in `tests_v4` of the numerical-strategies campaign.

View File

@@ -0,0 +1,126 @@
# Reduced gravity linearization
This branch supplies the linear algebra for the gravity-reduced nonlinear
formulation. It does not change the physics equations, normalization, default
Newton strategy, or model specification API. Gravity completion and accepted/trial
state ownership belong to the nonlinear context; the reduced operator has no
preparation or state-mutation entry point.
## Contract
Write the full normalized root equations as `F(u,z)=0`, `G(u,z)=0`, where `z`
contains the gravity gradient and potential. The typed gravity partition selects
those physical blocks from the compiled form. All other root coordinates and
rows, including optional specification borders, stay in the retained system.
Row and column orderings need not agree.
At a prepared state, `GravityReducedOperator` applies
```
S p = F_u p - F_z (G_z^{-1} G_u p).
```
`TryLiftTangent` returns `[p, -G_z^{-1} G_u p]`. On the gravity manifold this
is the derivative of the completed state with respect to retained coordinates.
`TryCondenseRightHandSide` and `TryLiftCorrection` also support a nonzero gravity
right-hand side:
```
b_reduced = b_F - F_z G_z^{-1} b_G,
delta_z = G_z^{-1} (b_G - G_u delta_u).
```
Consequently a small remaining gravity defect is retained in the Newton
equations rather than silently dropped. These formulas require an invertible
gravity block; they do not regularize a singular full stellar problem or remove
the n=3 homology.
The production gravity subsystem owns its inner backend and selected gravity
preconditioner, using a supported compact action or full-root restriction.
The reduced operator borrows it, allocates workspaces once, and checks
its preparation generation through `IsCurrent()` before and after actions. Each
inner solve starts from zero to avoid importing a previous Krylov direction into
the next action. A successful backend report is checked against the requested
true-residual threshold. The `Try` APIs return numerical failures without
replacing the caller's output; the MFEM `Mult` adapter throws the typed
`GravityReductionFailure` because a void action cannot return failure data.
The outer owner must translate this into a failed numerical attempt.
`GravityReducedPreconditioner` injects a retained residual into the full root,
applies the supplied full inverse, and extracts retained coordinates. The
retained block of the exact full inverse is exactly `S^{-1}`. For an approximate
inverse this provides an interchangeable preconditioner without assembling a
second approximate physics operator. Its stationary/flexible application
contract is propagated at compile time. It never rebinds the full inverse to a
reduced matrix.
## Accuracy and cost
The Schur formula is exact; an iterative inner solve evaluates it approximately.
Tolerance-stopped inner Krylov is not necessarily a linear map of its right-hand
side. FGMRES permits varying preconditioners, not arbitrary errors in its
operator. The nonlinear owner must choose sufficiently tight inner tolerances,
verify the lifted correction against the full Jacobian and full right-hand side,
and refuse an inaccurate correction. This gate is also necessary when the state
has only approximately completed gravity.
An action costs one gravity solve and two full Jacobian applications outside the
inner solve. Projection preconditioning costs one full inverse application.
The compact gravity applications reduce work inside the inner solve; they do
not remove these surrounding full-system actions. The measured improvement to
one inner solve therefore does not establish a cheaper reduced outer step.
All scratch vectors persist across applications. Objects borrow stable
addresses, are not reentrant, and must not outlive their prepared subsystem or
full inverse.
## Verification
The focused test source `tests/solver/gravity_reduction.cpp` covers:
- Central finite differences of a genuinely curved, analytically completed
gravity manifold; freezing gravity produces a detectably different derivative.
- Tangent lifting and vanishing gravity action.
- Schur condensation/lifting versus a direct monolithic solve, including a
nonzero gravity right-hand side and a coupled optional border.
- The exact inverse projection identity and compile-time propagation of both
stationary and flexible inverse contracts.
- Reduced and monolithic Newton convergence to the same known equilibrium.
- Numerical failure propagation without partially published results, true-defect
gate enforcement, stale preparation rejection, and dimension checks.
- Linearity, repeatability, and input/output alias safety with an exact inner
solve.
These algebraic tests establish the reduction contract. They do not establish
FEM convergence, a faster implementation, or an additional virial-qualified
stellar equilibrium. Separately, the integrated serial n=1, J=0 reduced control
converged in six full steps and passed all eight virial checks, but took longer
than the curvature control. Supported low-level two-rank tests passed; full
stellar MPI operation remains unvalidated because of the existing single-rank
logical radial surface interpolation restriction.
## Resolved FEM difference sampling
The first frozen n=1.5 probe completed all gravity solves and preparations. Its
central-difference errors at steps 0.01, 0.001, and 0.0001 were respectively
`1.7761e-9`, `1.9661e-11`, and `7.1208e-11`. Only the first exceeded twenty times
the recorded arithmetic scale. The observed first-interval order was about
1.956, but the conservative checker correctly left the trend unresolved because
the finer endpoint did not meet its resolution criterion.
The diagnostic now uses the explicit, validated step array `{0.1, 0.03, 0.01,
0.001}` and records it in the summary. The larger steps test whether truncation
dominates sufficiently to reveal a central-difference trend; retaining 0.001
also preserves an independent small-step accuracy check. This adds one central
pair, hence at most four extra gravity correction solves under the existing
two-correction completion budget. The inner tolerance, prepared completion gate,
and checker thresholds are unchanged. There is no assumption that larger steps
will prepare successfully or automatically pass the trend check.
The updated frozen n=1.5 probe passed all 124 algebraic and invariant checks.
Absolute central-difference errors on that grid were approximately `1.7784e-7`,
`1.5987e-8`, `1.7761e-9`, and `1.9661e-11`, resolving the expected second-order
trend without relaxing thresholds. These remain finite-range empirical
derivative checks. The recorded arithmetic scale is heuristic, and a gravity
residual bound by itself is not a bound on its amplified effect in the retained
equations. The result establishes no such unmeasured amplification bound and
does not reinterpret floor-limited differences as derivative failures.

View File

@@ -0,0 +1,92 @@
# Prepared gravity subsystem and curvature correction
This branch introduces solver components; the complete equilibrium equations,
normalization, and model specification remain the source of truth.
## Block and lifetime contracts
`MakeGravityBlockPartition<Form>(layout)` selects the gravity-gradient and
gravity-potential blocks by their compiled value and residual types. Its
constraints reject forms lacking those blocks. The complement is retained in
root order, including any generated angular-momentum or central-density border.
There are no string identifiers or fixed root offsets in this selection.
`GravityBlockPartition` also has a checked explicit-index constructor for
algebraic tests and other compiled adapters. Local partitions may be empty;
gravity and retained local systems must be square. A globally empty gravity
system is rejected by the prepared linear backend. Gather/injection require
preallocated, nonoverlapping storage.
`PreparedGravitySubsystem` owns gravity operator/preconditioner workspaces and the
existing prepared linear backend. It borrows the full normalized operator,
inverse, and communicator at stable addresses. It is neither movable nor
copyable. Preparation records the root preparation generation. After candidate
preparation the caller must refresh its physical inverse and explicitly refresh
the subsystem; stale applications and solves fail. The subsystem does not
prepare a candidate, change an accepted state, or commit a step.
The exact gravity action is the principal restriction of the root Jacobian.
The default automatic policy uses the existing compact physical gravity action
when a declared compile-time capability and collectively checked canonical
partition permit it. Otherwise it injects, applies, and restricts the full root
operator. The selected preconditioner similarly uses a supported compact
physical gravity block or the supplied root inverse's restriction. Neither
choice asserts an exact gravity inverse. Both paths retain the same diagonal
normalization and boundary maps, persistent scratch storage, and the backend's
independently checked true-defect gate. `RootRestrictedGravityApplications`
remains an explicit reference policy. Equality tests and measured application
costs are recorded in
[`GRAVITY_COMPACT_APPLICATIONS_2026-09-17.md`](GRAVITY_COMPACT_APPLICATIONS_2026-09-17.md).
Attempted solves, completed inner iterations, failed calls, completed solve time,
and the last completed solve report are available without history allocation.
Contract exceptions count as failed calls but do not trigger new collectives to
measure elapsed time during unwinding.
The existing FGMRES backend now admits ranks with zero local equations while
requiring a nonempty global system. `GetConfiguration()` returns its immutable
prescription so another prepared operator can reuse the same backend options.
## Curvature correction
`PreparedGravityCurvatureCorrection` captures `G(x)` and `J_G(x) p` before any
candidate preparation. For a prepared candidate `x + alpha p` it solves
```
G_z(x + alpha p) delta_z = G(x) + alpha J_G(x) p - G(x + alpha p).
```
Only the compact gravity correction is returned. The caller may inject it only
after a converged inner report, then must prepare and evaluate the complete
candidate again before applying its usual acceptance rules. In particular,
improving gravity does not certify the hydrostatic, material, or shape residual.
For smooth equations with uniformly bounded inverse gravity block, the right
side and correction are second order in `alpha`. This preserves the base and
Newton tangent even when the base does not lie on the gravity solution manifold.
It differs from projecting the candidate to `G=0`, which can introduce a finite
correction at zero step when the base gravity residual is nonzero. Inexact inner
tolerances control cancellation of the remainder; they cannot replace the outer
equilibrium and virial checks.
The owner captures a new base for each new Newton direction and invalidates the
cache when that direction is discarded. The stored base generation is exposed
for diagnostics; preparing trials intentionally does not invalidate the captured
base arrays. Reusing those arrays after replacing the base or direction violates
the caller's explicit lifecycle contract.
## Test coverage
`tests/solver/gravity_subsystem.cpp` covers typed forms with/without a central
border, noncontiguous and differently ordered row/value maps, invalid maps and
overlapping storage, exact restricted solves, true-defect failure, nonfinite
inputs, stale operator/inverse preparation, locally empty MPI partitions,
globally empty rejection, preserved backend options, zero affine curvature at
an off-manifold base, and the second-order correction at curved trial geometry.
The integration campaign compiled these components and passed their serial and
supported two-rank tests, including locally empty partitions. Real stellar
serial fixtures also passed compact/reference comparisons with and without the
central-density border. Full stellar MPI operation remains unvalidated because
the existing logical radial surface interpolation is restricted to one rank.
Algebraic tests alone do not establish a virial-qualified stellar equilibrium;
the separate model campaign applies the unchanged physical acceptance checks.

View File

@@ -0,0 +1,110 @@
# Krylov correction safeguard: observed outcome
Retain the true-residual initial-guess safeguard as a limited inner-solver
robustness improvement. The matched n=1 solution is unchanged, and the capped
n=1.5 run uses fewer linear iterations and avoids its control's late linear
failure. It does not resolve the n=1.5 nonlinear plateau or establish full
physical validation.
Tested guard revision: `1911a26a9a283eed7e53b03fc3481ee894e61bfb`.
Matched control revision: `9bd4af699650e2a6bbe795c618e6ef3fbcb48e12`.
The underlying numerical snapshot is `80cc3d8`; the safeguard implementation is
`ed75830`. Both live comparisons use restart 160, omit the central constraint,
allow eight Newton attempts and 200 linear iterations, and require a true linear
residual/RHS <=0.03. Newton stopping uses atol=0 and rtol=1e-8.
The production candidate safeguards a supplied linear initial guess using its
true residual under the current operator. It retains the guess when
`||b-Jp_guess|| <= ||b||`, otherwise starts at zero. A nonzero guess costs one
extra operator action, included in reported counts and solve time. Zero guesses
do not incur an extra action. This is neither Krylov basis recycling nor a
guarantee of fewer iterations: a smaller initial residual can still excite a
harder set of modes.
The retained `(1-alpha)p` heuristic from damped Newton remains intact, as does
the existing backend API. The safeguard only declines a guess that increases
the current true defect. It also handles a nonfinite operator action on an
otherwise finite guess by choosing the finite zero guess, collectively across
the communicator. Existing input checks still reject nonfinite supplied vectors.
There is no public API or policy-option change, and no change to physical
specifications, normalization, preconditioner, tolerances or nonlinear acceptance.
The reported initial residual belongs to the effective guess after safeguarding;
it does not expose the raw residual of a discarded guess.
## Matched live evidence
At n=1, J=0.05, both runs converge in seven full steps and 292 linear iterations
to F=3.38036278e-11. Saved state, initial/final physical tables, layout, block
residuals and trial histories are byte-identical. Every non-time Newton history
field also matches. All eight q14/q18 energy/force virials with P(h) and P(rho)
pass 1e-5; the largest is 3.73465327e-7. Full steps leave zero guesses, so this
is a regression control, not evidence that the safeguard accelerates cold solves.
At n=1.5, J=0, initial physical tables and the first two numerical histories
match exactly, including block records through the third attempt's before-state.
The first reset then changes the effective initial defect/RHS from the control's
1.50970280 to 1, and reduces linear iterations from 71 to 65. Both accept alpha=1/64
after four trials. Resulting F is 1.75410130e-4 guarded versus 1.75953185e-4 control.
Later trajectories differ; their discarded raw guesses cannot be inferred from
the effective initial-residual reports.
| Capped n=1.5 outcome | Control | Guard |
|---|---:|---:|
| Accepted Newton steps | 7 | 8 |
| Termination | Eighth linear solve fails | Newton iteration cap |
| Final F | 1.75134755e-4 | 1.74946086e-4 |
| Last accepted alpha | 1/2048 | 1/8192 |
| Total linear iterations | 672 | 561 |
| First seven attempts' linear iterations | 472 | 467 |
| Sum of linear solve times | 303.52 s | 242.92 s |
| Sum of Newton-attempt times | 487.15 s | 447.25 s |
| Process time, including diagnostics | 550.36 s | 508.16 s |
The guard passes every linear gate within this cap; the last true residual/RHS is
0.02995827. Most of the total iteration reduction comes from avoiding the last
200-iteration failure. The seventh guarded solve costs 94 iterations versus 80
in the control, so improvements are not uniform. These are different later
linear systems and single timings, not a same-matrix or reproducible speedup
measurement. The inactive n=1 control itself varied by approximately 5% in time.
Both n=1.5 endpoints remain unconverged and have similar unresolved local errors.
Guarded q18 P(h) energy/force virial errors are 2.24342463e-6 / 2.35159576e-6;
changes from control are +9.04e-9 / +2.02e-8. The q14/q18 difference is 1.84e-9.
Full P(rho) virials remain undefined from sampled DG density negativity. The
negative-density mass fraction changes only from 2.89327559e-5 to 2.89305795e-5;
no negative enthalpy is sampled. Peak/RMS EOS and Bernoulli errors improve slightly.
Mass error increases from 3.50011e-6 to 3.52971e-6. Center-of-mass displacement
worsens from 1.67437e-6 to 4.57477e-6 of the unit reference radius and remains an
explicit follow-up metric. Sampled signs and extrema are not pointwise bounds.
The standalone solver-and-virial checker passes n=1 and fails n=1.5, preserving
strict stopping and pressure-validity distinctions. P(h) virial success alone
does not validate the interior. Severe damping first occurs with a cold guess
on the second n=1.5 attempt, so adverse warm starts cannot be the entire cause.
## Regression checks and reproduction
All five unique focused tests pass on one MPI rank: two backend tests with
41 assertions and three Newton integration tests with 356243 assertions
(356284 total). Both backend tests also pass on two MPI ranks, with 41 assertions
on each rank. Coverage includes beneficial-guess retention, restart/reporting,
rank-0-only adverse guesses, finite coefficients whose operator action overflows,
collective fallback, and the existing Newton correction-reuse integration.
The exact filters are `[solver][linear][fgmres][warm-start]` and
`[solver][newton][warm-start],[solver][newton][fgmres]`, with Catch RNG seed 20260916.
Only the backend filter is used in the two-rank check. Test binary SHA-256:
`258f749ce85e14136b8f7a5fe28e3a49f8007c6bfe37fedd81e27119a8be1d23`.
Reproduce guarded live cases with `run_plateau_campaign.py` and
`plateau_krylov_cases.json`; compare the corresponding restart-160 cases in
`plateau_control_cases.json` at the control revision. Mesh SHA-256:
`ce11ae99e21e6c3bbfbee402acd2e191c1da0d8261d2227b4203f73f2f337a74`.
Guard executable SHA-256:
`a16dfd624e74e89a0b6f78d0cd3742e58274b09580f09b3583d3a37fa4004d46`.
Raw runs, exact commands, logs, copied binaries, hashes and full analysis are
retained outside git under the campaign's `controls/`, `guard/`, `guard_checks/`
and `guard_analysis.md`. Recorded CMake caches are identical. Dynamic libraries
are not frozen and inherited thread settings are not captured. Direct frozen
MFEM probes bypass this production safeguard and cannot validate its behavior.

View File

@@ -0,0 +1,43 @@
# Larger Krylov window
This branch changes only the sandbox example's existing FGMRES restart setting
from 40 to 160. It adds no public API and does not change the general backend
default. The warm-start safeguard is a separate hypothesis and branch.
## Matched evidence
The common diagnostic executable at commit `9bd4af6` ran n=1, K=2/pi, M=1,
J=0.05, with no central-density constraint, on the unchanged `sandbox.smesh`.
Both runs used nonlinear rtol=1e-8, atol=0, linear tolerance=0.03, and at most
200 linear iterations. Only the restart window differed.
| Result | Restart 40 | Restart 160 |
| --- | ---: | ---: |
| Accepted full Newton steps | 5 | 7 |
| Final normalized residual | 6.03609e-9 | 3.38036e-11 |
| Strict convergence | No: sixth linear solve fails | Yes |
| Total linear iterations, including failed attempt | 370 | 292 |
| Largest final virial error among four definitions, q=14/18 | 3.73183e-7 | 3.73466e-7 |
The first four steps coincide exactly. The larger window first changes the
fifth linear solve. This is live nonlinear evidence, supplemented by the earlier
frozen-system comparisons. Single wall-time samples (291 versus 272 seconds,
including physical diagnostics) do not establish a general speedup.
## Limits and validation
The larger window requires more Krylov storage. It is a useful example setting,
not a universal default: n=1.5 without the central constraint still stalls with
this window, and eventually fails a linear gate. The n=3 frozen control also
needs a stronger numerical treatment. This change does not establish a fraction
of critical rotation and does not alter the convergence or virial tolerances.
Removing the n=1 example's central-density constraint is independently supported
on `research/central-constraint-20260916`; combine the two changes for the intended
example. The combined sandbox compiles at `b3a752b`. Its nonrotating physical
counterpart in the diagnostic at `c88baa1` reaches strict convergence in six
full steps, with F=1.65157e-13 and all eight q14/q18 virial checks below
3.731e-7. The diagnostic uses its recorded stopping controls; this is not a
claim that the literal sandbox executable was used for the physical measurements.
Raw results and exact build/mesh/executable provenance are retained in the
workspace's `diagnostics/numerical_campaign_2026-09-16/controls` directory.

View File

@@ -0,0 +1,371 @@
# Independent log density: positivity, vacuum, and closure
Branch: `research/log-density-assessment-20260919`.
Parent: `7ed4d23`.
Scope: mathematical review and a small uniform one-dimensional profile control.
No stellar equilibrium, production operator, field order, normalization, or
preconditioner was changed. This is separate from the density-only Q2/Q3/Q4 study.
## Assessment
Log density is compatible with **density remaining an independent physical
unknown**. It need not make density a function of enthalpy or restrict the
eventual EOS to a barotrope. The important choice is what gets exponentiated:
1. Exponentiating the existing nodal coefficients and then evaluating the usual
density polynomial does **not** guarantee a nonnegative field. It is only a
coordinate change on positive coefficient vectors. The measured negative
density fields already have positive nodal coefficients.
2. Evaluating `rho = rho_scale * exp(u_h(x))` pointwise guarantees strictly
positive density in exact arithmetic wherever `u_h` is finite. Floating-point
evaluation also needs checks for underflow and overflow. This is a different
approximation family from polynomial density. Every density-dependent
operator must use it.
3. A finite polynomial `u_h` cannot represent an exact zero-density vacuum
surface with that raw exponential. A vanishing reference factor can encode
the surface, but its asymptotic behavior becomes part of the representation.
The small control below shows that a raw exponential can satisfy all the chosen
weak density moments while retaining an incorrect positive surface trace. Thus
positivity and a small closure residual do not by themselves settle the vacuum
or pointwise EOS question. Log density merits a separate formulation hypothesis;
it is not a completed remedy for the current zero-pressure polytropic boundary.
## Three distinct representations and their derivatives
Let `q` denote geometry parameters, `h` enthalpy coefficients, and `z` the other
unknowns. All variations below are at fixed reference coordinates; physical
volume and other mapped geometry contributions must also be differentiated.
### Logarithms of polynomial nodal coefficients
Suppose the existing density field is
\[
\rho_h(\xi)=\sum_j r_j\varphi_j(\xi),\qquad
r_j=\rho_*\exp(u_j),\quad \rho_*>0.
\]
For the existing residual vector `F(r,q,h,z)`, keeping its residual coordinates
unchanged gives
\[
\widetilde F(u,q,h,z)=F(g(u),q,h,z),\qquad
J_u=J_r\,\operatorname{diag}(r_j).
\]
This retains the original roots whose coefficient vectors are positive. The
Gauss-Legendre nodal basis has sign-changing basis functions, so positive `r_j`
does not imply nonnegative `rho_h`. In particular, taking logarithms of the
already-positive coefficients at the measured n=1.5 root and applying this
coordinate change would reproduce its negative polynomial exactly. Requiring
positive coefficients alone does not remove that root.
### A pointwise exponential of an independent FE field
Instead choose
\[
u_h=\sum_j u_j\psi_j,\qquad
\rho(\xi)=\rho_*\exp(u_h(\xi)).
\]
Now density is nonpolynomial, but remains independently parameterized by `u`.
For a fixed positive scale,
\[
\delta\rho=\rho\,\delta u_h.
\]
Keeping the current density-moment tests as an explicit discretization choice
would give, for the present barotropic closure,
\[
R_i=\int_{\Omega(q)}\varphi_i[\rho_*e^{u_h}-\rho_{\rm EOS}(h_h)]\,dV,
\]
\[
\frac{\partial R_i}{\partial u_j}
=\int\varphi_i\rho\psi_j\,dV,
\qquad
\frac{\partial R_i}{\partial h_k}
=-\int\varphi_i\rho'_{\rm EOS}(h_h)\chi_k\,dV.
\]
With equal log trial and closure test bases, the density block is a
density-weighted mass matrix. Positive quadrature weights and full column rank
make it positive definite for strictly positive sampled density. Its magnitude
can nevertheless become very small near vacuum.
This is not the same residual obtained by minimizing the squared pointwise EOS
error in the nonlinear trial family. Differentiating that least-squares
objective introduces an additional `rho` in the test factor. That choice need
not retain the constant density moment. The test space, residual and derivatives
must therefore be chosen explicitly rather than inferred from the word “log.”
For a general EOS, density can remain independent alongside temperature,
internal energy and composition, as appropriate to the chosen physics. For
example, an auxiliary pressure closure `P_aux - P(rho,T,X)` has log-density
variation `-P_rho * rho * delta u_h`. No inversion to `rho(h)` is required by the
log representation itself. The current barotropic Bernoulli equation is a
separate modeling choice and does not automatically generalize to varying
entropy or composition.
In the current formulation, enthalpy is also an independent trial field. The
prepared pressure operator rejects nonfinite or negative enthalpy at its own
integration points (`libmeanfield/impl/operators/prepared_pressure_force.cpp`,
lines 788–800). Pointwise-positive density alone therefore does not make a
Newton candidate admissible. Any coupled log-density experiment must still test
the enthalpy directions and pressure-preparation obstruction; the frozen
density controls below establish no improvement in that separate guard.
### A vanishing reference factor
Let
\[
\rho(\xi)=\rho_{\rm ref}(\xi,q)\exp(u_h(\xi)),\qquad
\rho_{\rm ref}>0\text{ in the interior},\quad
\rho_{\rm ref}=0\text{ on the intended vacuum surface}.
\]
Finite `u_h` now preserves both interior positivity and the prescribed zero
trace. Its directional variation is
\[
\delta\rho=\rho\,\delta u_h+e^{u_h}\delta\rho_{\rm ref}.
\]
The second form is usable at a zero of the reference; division by
`rho_ref` to form a logarithmic derivative is not. A reference fixed in mesh
coordinates has no explicit shape derivative at fixed reference coordinates,
but mapped volume, physical positions and force transformations still change.
A reference defined from physical distance or updated with the accepted shape
has additional dependencies that must be represented and differentiated.
For a surface profile `rho ~ A s^n` and a reference `rho_ref ~ B s^m`,
\[
u\sim\log(A/B)+(n-m)\log s.
\]
The amplitude is bounded at the surface only when the leading exponent matches.
A reference proportional to `s` is not a uniformly regular log coordinate for
the n=1.5 or n=3 profiles. Choosing `rho_ref` from the current `rho_EOS(h)` would
also introduce enthalpy dependence; it is not necessary for independent density
and would need to be distinguished from a reference chosen independently of
the live thermodynamic state. A fixed reference based on a model index is a
reasonable polytropic experiment, not yet a general-EOS prescription.
## Exact vacuum versus a finite-density outer boundary
For the leading vacuum profile `rho=A s^n`, raw log density is
`log(A/rho_scale)+n log(s)`. It tends to negative infinity, and its derivative
is `n/s`. Moving density DOFs to interior Gauss points avoids evaluating the
logarithm at zero, but does not give a finite polynomial the correct limit.
Exponentiating that polynomial leaves a positive trace on the boundary.
Imposing an additional exact `rho=0` condition on a finite raw log field is
incompatible; it can lead to coefficients diverging rather than a finite root.
The current weak closure can instead converge with a nonzero density trace,
because matching volume moments does not enforce that trace. These are two
different failure mechanisms, not a proof that the volume moment equations
themselves are overdetermined.
A physical outer boundary with specified positive density avoids this particular
singularity. Such a boundary needs its own atmospheric/pressure prescription and
EOS interpretation. Replacing a vacuum boundary by a numerical density floor
would change the problem, not merely regularize coordinates. General EOS models
can have different surface asymptotics, so the choice should follow the boundary
physics rather than be hidden inside the linear solver.
## Uniform surface-cell control
`log_density_reference_model.py` compares independent approximations to `t^n`
on `[0,1]`, for n=1,1.5,3. All densities below are normalized to the exact
inner-edge value, which is one. Physical curvature, tangential variation,
gravity, rotation and stellar equilibrium are absent.
The raw log interpolant is the Q2 interpolant of `n log(t)` at the actual three
Gauss-Legendre nodes. It is exponentiated at evaluation points, not interpolated
again as density. The conservative exponential control solves only three small
moment equations:
\[
\int_0^1\varphi_i(t)e^{u_2(t)}dt
=\int_0^1\varphi_i(t)t^n dt,\qquad i=0,1,2.
\]
The tests are an L2-orthonormal polynomial basis; the right-hand moments are
analytical. A three-coordinate Newton calculation fits these moments using a
64-point rule and verifies them with an independently generated 128-point rule.
This is a frozen toy fit, not a new stellar solve or a global existence proof.
| n | Raw log interpolation: surface density | Raw log interpolation: relative L2 error | Moment-fitted exponential: surface density | Moment-fitted exponential: relative L2 error |
|---|---:|---:|---:|---:|
| 1 | 0.0615032 | 0.0669374 | 0.0673707 | 0.0578060 |
| 1.5 | 0.0152527 | 0.0924952 | 0.0229264 | 0.0517531 |
| 3 | 0.000232645 | 0.181788 | 0.00141091 | 0.0333959 |
The moment fits take 3,4,5 tiny Newton updates, respectively; verified relative
moment defects are at most `2.38e-14`. They are strictly positive everywhere in
the cell, preserve mass to the reported arithmetic tolerance, and still have
nonzero EOS error and an incorrect positive vacuum trace. This gives a concrete
example in which positivity and weak closure convergence coexist with a boundary
representation error.
For comparison, the exact Q2 density projections have relative L2 errors
`0`, `0.00952381`, and `0.05`, respectively. Thus positivity does not imply that
the raw log family is a more accurate approximation at the same degree: the
moment-fitted exponential improves this norm for the cubic profile, but worsens
it for the n=1 and n=1.5 profiles. All these statements concern the one-dimensional
profiles, not the actual stellar fields.
A constant shift of the interpolated log field can enforce the exact cell mass:
`u_new=u+log(M_target/M_current)`. It leaves the positive surface trace and
nonconstant moment errors. The script records this distinct control; it is not
used to alter a stellar state. A matched factor `t^n exp(0)` reproduces the target
and its zero surface exactly by construction. That result demonstrates the role
of the factor, not the general adequacy of an a priori reference profile.
The smooth exponential controls have 64/128-point moment differences below
`3e-16`. For the matched fractional factor `t^1.5`, the same quadratures differ
by about `1.60e-10` in the largest orthonormal moment despite the represented
function being exactly the target. That is integration error, not density
approximation error. The script records it rather than replacing quadrature
values by the known integral silently.
## Conditioning and conservation
For `rho=A Delta^n t^n`, using fixed reference polynomial bases on a cell of
physical width `Delta` gives
\[
J_u=A\Delta^{n+1}H_n,\qquad
(H_n)_{ij}=\int_0^1 t^n\varphi_i\varphi_j\,dt.
\]
The ordinary density mass matrix in this orthonormal reference basis is
`Delta I`. Relative to it, the log-coordinate response carries the extra factor
`A Delta^n`. Halving width therefore decreases the response scale by `2^-n`.
This does not by itself worsen the condition number of the isolated cell matrix,
but can increase scale disparities across cells and coupled blocks.
The small weighted matrices for the exact reference profiles have condition
numbers approximately `7.87298`, `16.8523`, and `94.5609` for n=1,1.5,3. These
are measurements of 3-by-3 matrices for one-dimensional quadratic trial/test
spaces, not estimates of the stellar Jacobian's condition number. For the fitted exponential controls the
corresponding numbers are `6.65377`, `13.7153`, and `74.9786`.
The first-order identity `delta rho/rho=delta u` makes a log step a relative
density step. That can be useful across large density contrasts, but large log
steps create exponential changes. Underflow can produce zero from finite log
coefficients, so finite-value checks alone do not ensure positivity. A raw
exponential implementation must also detect or reject underflow and nonpositive
reconstructed density in the material interior, including underflow when
multiplying by its reference scale or factor. Prescribed zero-density traces
from a vanishing reference factor remain intentional. Overflow and weak
response near vacuum also need explicit checks and meaningful globalization;
silently clamping the exponential would change the equations. A vanishing
factor removes the singular log profile when it matches the asymptotics, but
retains the density-weighted sensitivity near vacuum.
With the explicit constant test retained, a converged weak exponential closure
preserves its target cell mass under the closure quadrature. Exponentiation
alone does not ensure this; neither does positivity. Mass measured under a
different rule, higher moments, inertia and virial balance still require their
own consistency checks. A nonlinear change of trial family also does not
automatically preserve a discrete variational identity coupling gravity,
pressure and shape. Any integration must retain the true full residual and
Jacobian tests and measure the physical consequences.
## Architecture implications and recommended boundary of this work
The natural internal abstraction is a typed independent-density representation
with a physical-value evaluator and exact directional action. A log coordinate
has no density units; its positive reference scale does. It should not be passed
through APIs that assume its coefficients are physical density coefficients.
The same representation must feed gravity source/force, centrifugal force,
mass, angular momentum, diagnostics and exported profiles. Their dependency
generation, quadrature, cache invalidation and normalization must agree.
The implementation must preserve density's stellar-only support. Physical
density and its directional action must remain identically zero in exterior
and vacuum domains; the positive reconstruction applies only in the material
domain. An inactive log coefficient stored as zero must not be exponentiated
into `rho_scale` outside the star. Domain support must therefore be part of the
representation contract shared by operators, diagnostics and exports. This
intentional exterior vacuum is distinct from underflow inside the material and
from the intended zero trace of a vanishing reference factor at its boundary.
The current registry represents density as an independent scalar L2 field, and
the prepared source and force operators read it as a polynomial grid function.
The current field relationship catalog supports independent and differential
relationships, not a nonlinear physical-value representation. Therefore a
pointwise log field requires an explicit extension; setting a flag or
exponentiating the accepted coefficient buffer is insufficient. Relevant local
contracts are in `field_registry.cppm`, `field_base.cppm`,
`prepared_gravity_source.cpp`, `prepared_barotropic_closure.cpp`,
`normalization/stellar_equilibrium.cppm`, and
`preconditioning/material_surface.cppm`.
For the currently intended exact-vacuum polytrope, the companion density-only
order study supplies the polynomial baseline, including cost and pointwise
error. If log density remains attractive, the next bounded
question is whether a physically justified vanishing reference can provide a
regular independent coordinate without importing a restrictive EOS assumption.
For a genuinely finite-density outer boundary, raw pointwise log density is a
different, potentially simpler candidate. Neither has been implemented or
validated against a coupled star here; no logarithmic formulation, n=3
convergence result, speedup, or virial improvement is claimed.
## Primary-source context
The analogy to 1D stellar codes is supported by MESA's current
[`star_utils.f90`](https://github.com/MESAHub/mesa/blob/main/star/private/star_utils.f90):
`get_rho_and_lnd_from_xh` reconstructs a zone's density with `exp(lnd)`, while
`store_rho_in_xh` stores `log(rho)`. Its documented
[`T(tau)` atmosphere treatment](https://docs.mesastar.org/en/latest/atm/t-tau.html)
sets surface pressure and temperature at a selected optical depth. An ordinary
atmosphere match with positive gas pressure therefore avoids requiring
`log(0)` at an exact vacuum interface; this is the relevant inference for our
boundary choice, not a claim about every MESA mode. These zonewise logarithmic
variables support investigating independent log density, but do not establish
positivity between nodes of our high-order FEM reconstruction or resolve its
exact zero-density free surface.
Vijaywargiya and Fu, *Two Finite Element Approaches for the Porous Medium
Equation That Are Positivity Preserving and Energy Stable* (2024), formulate a
pointwise exponential log-density method and explicitly discuss the infinite
logarithm at zero density. Their compact-support implementation treats that
issue through a degree-of-freedom deactivation strategy. Its time discretization,
mass lumping and PDE-specific guarantees do not establish a corresponding
method for steady stellar equilibrium. This is a relevant precedent and vacuum
caution, not a proposed algorithm to transplant.
[Primary paper](https://link.springer.com/article/10.1007/s10915-024-02642-x).
Fu and Xu, *High-order space-time finite element methods for the
Poisson-Nernst-Planck equations: Positivity and unconditional energy stability*,
derive positive, conservative schemes through entropy variables and a specific
space-time discretization. The conservation and stability results belong to
that complete formulation, not to exponentiating coefficients in an arbitrary
existing solver. [Author preprint](https://arxiv.org/abs/2105.01163).
The representation identities, vacuum asymptotics and one-dimensional controls
above are independent derivations rather than imported numerical evidence.
## Reproduction
From this checkout:
```text
/opt/homebrew/anaconda3/envs/general/bin/python experiments/log_density_reference_model.py --self-test
/opt/homebrew/anaconda3/envs/general/bin/python experiments/log_density_reference_model.py --output ../../diagnostics/log_density_2026-09-19/reference_v1
```
The output directory must be fresh. It contains summary CSV/JSON and sampled
profile CSV, with script and artifact SHA256 hashes. The retained invocation log
is `../../diagnostics/log_density_reference_v1.log`. Four tiny test methods pass:
Gauss moments, positive coefficient interpolation still admitting undershoot,
moment-fit/vacuum behavior, and the weighted Jacobian directional derivative
and small spectral identities. The production code was neither built nor run
for this assessment.

184
experiments/MODEL_SLICES.md Normal file
View File

@@ -0,0 +1,184 @@
# Physical slices of the deformed FEM model
This optional experiment displays the independent density, enthalpy and actual
material boundary of a prepared state. It changes no solver equations, fields,
orders, positivity handling or public library API.
## Use
Add `--model-slices` to a normal `plateau_diagnostic` invocation. It writes
`initial_slices` and `final_slices`, each with `xz` and `xy` subdirectories.
Optional settings:
- `--slice-plane both|xz|xy|yz` (default `both`, meaning xz and xy).
- `--slice-offset VALUE` (default zero). This is the physical coordinate normal
to the plane: y for xz, z for xy, x for yz. `both` applies the same offset to
both planes.
- `--slice-subdivisions N` (default 6, allowed 2–32). Begin with 4–8 and compare
two resolutions for a plot whose small features matter. Work grows with the
number of reference subcells; 32 is an explicit upper bound, not a suggested
default.
Existing harmonic snapshots can be observed through the checked density replay
path, using the matching binary, mesh and physical specifications:
```sh
plateau_diagnostic --index 3 --angular-momentum 0 \
--surface-prescription harmonics --surface-degree 4 \
--mesh /absolute/path/to/saved/input.smesh \
--density-snapshot /absolute/path/to/saved \
--model-slices-only --max-newton 0 --slice-subdivisions 6 \
--output /absolute/path/to/new_observation
```
`--model-slices-only` writes `frozen_slices` and the replay's normal physical
metrics/provenance, skipping the expensive density-region observations. It does
not perform Newton iterations. `--model-slices` can also accompany an existing
frozen density diagnostic. Replay checks still apply; a size match alone does
not establish compatibility of a saved state.
Render one plane with Python, NumPy and Matplotlib:
```sh
python experiments/plot_model_slices.py /absolute/path/to/new_observation/frozen_slices/xz \
--reference-outline --title 'n=3 rotating trial; unconverged' \
--output /absolute/path/to/new_figures/n3_trial_xz
```
The helper writes PNG and PDF and refuses to overwrite either. Both axes use
the same physical length scale. The solid curve is the deformed material
boundary; the optional dashed curve is the undeformed boundary intersected
with the same plane. No deformation magnification is applied. A two-sided
color scale centered at zero retains the sign when a field has both signs;
the displayed ticks are the actual values, and each color half may have a
different range. All-positive or all-negative data use a linear color scale.
No density or enthalpy values are clipped, replaced by an EOS evaluation, or
logged. Extrema in panel titles are sampled extrema.
Field values are linearly interpolated within each supplied triangle at the
centers of a 512-by-512 scalar grid, then mapped to colors. This avoids Gouraud
shading's interpolation of RGBA colors, which can change an unchanged affine
field's appearance under triangle refinement. `--pixels N` changes this display
resolution (32–2048). Uncovered pixels remain masked; a pixel covered by more
than one approximate triangle takes the first supplied triangle, with no
cross-element averaging. No global triangulation or global point-location
topology is inferred. Pixels can miss subpixel features and straddle a boundary;
the separately drawn physical outline remains the geometric reference.
Final-state plots use the surrounding run's convergence flag when available;
replayed or initial states are labeled as not assessed by the image. Give a
descriptive title, including the physical parameters and any known failure,
when plotting a stalled or otherwise unconverged state. A plausible picture
does not establish virial balance or an unbordered equilibrium.
## Geometry and field contract
Only stellar hexahedra are visited. Each is split into a configurable reference
lattice and consistent tetrahedra within that element. Intersections solve
`mapped_position[normal] = offset` on the actual curved map along each crossed
edge, using a safeguarded bracketed root calculation. This is a physical-plane
cut, not a deformed image of a reference-plane selection. The mapped Jacobian
must remain valid at every evaluation. Exterior compactification is not used.
Density and enthalpy are evaluated directly from their existing FEM fields at
the resolved reference coordinates. Output triangles keep their owning element
and separate vertex records. The plotter uses this supplied connectivity and
never triangulates a global point cloud; consequently it does not connect
disconnected material across vacuum or average the two DG traces on an
interface. A plane exactly coincident with an internal element face uses the
trace from its positive-normal side.
The material boundary is found from stellar/nonstellar faces and evaluated from
the stellar side. Its curve is computed separately from the volume coloring.
The undeformed outline is independently intersected with the physical plane;
projecting reference positions of the deformed cut would be a different curve.
An exactly coplanar surface patch is reported as unsupported instead of being
silently drawn as a unique intersection curve.
The tetrahedral subdivisions are conforming inside each parent hexahedron,
but their face diagonals are not made globally consistent across differently
oriented neighboring elements. Boundary faces are triangulated independently
as well. On a curved shared face, these choices can produce slightly different
chord approximations: small gaps or overlaps between neighboring element fills,
or a mismatch between the colored edge and the independently drawn outline.
Deterministic ownership of a coincident planar face does not remove this curved
interface approximation. These image artifacts must not be interpreted as
physical gaps, jumps in geometry or an additional density feature.
Curved cuts are displayed using straight triangles and boundary chords. Field
colors are piecewise linear on those triangles, not exact values throughout
their interiors. Root tolerances, maximum physical-plane residuals, sampled
centroid/midpoint chord errors, counts, bounds and time are recorded in each
plane's `metadata.csv`. The chord errors and bounds are sampled diagnostics,
not rigorous global enclosures. Tangencies or multiple crossings contained
between subdivision vertices can be missed; compare subdivisions for image
stability. This visualization does not certify pointwise positivity or exclude
small unsampled features.
Before interpreting an actual FEM image, export the same saved state and plane
at two subdivision counts, for example 6 and 12 (or 4 and 8 for a first bounded
check). Compare the outlines, element-interface seams, sampled chord errors and
the visible density/enthalpy structure at the same axes and color ranges. The
pure geometry and plotting controls below do not test differently oriented
neighboring curved hexahedra and do not replace this export refinement check.
Globally consistent face triangulation would remove the diagonal mismatch;
it is not implemented in this bounded diagnostic.
The comparison helper enforces a common plane/orientation/offset, increasing
subdivision counts, shared physical axes and shared per-field color scales:
```sh
python experiments/compare_model_slices.py \
/absolute/path/to/coarse/final_slices/xz \
/absolute/path/to/fine/final_slices/xz \
--source-state /absolute/path/to/original/accepted_state.txt \
--reference-outline --title 'Same rotating trial; unconverged' \
--output /absolute/path/outside/source/slice_refinement
```
It writes a side-by-side PNG/PDF and JSON containing triangle-area sums, signed
piecewise-linear 2D density/enthalpy integrals, surface bounds, segment-length
sums, exported geometric diagnostics and their absolute/relative changes. Area
and field integrals include any overlapping triangles; segment-length sums
include any duplicate segments. These are measures of the displayed slice,
not exact curved-FEM integrals, 3D mass or virial diagnostics. Near-zero signed
integrals make relative changes sensitive, so also inspect absolute changes.
The two panels use the same scalar raster grid and bounds; its pixel resolution
and overlap ownership are recorded. Quantitative integrals are computed from
the supplied triangles, independently of the display raster.
`--source-state` is the caller's declaration of the common saved state and its
SHA256 is recorded. The caller must verify that both exports used that state,
mesh, field orders and physical specifications. The current export CSVs do not
bind themselves to a snapshot, and this helper does not establish provenance
from matching plane metadata. Output artifacts must be outside the source
checkout and existing files are not overwritten.
## Checks
Every export runs pure geometric controls: unit-cube section area, integration
of a signed affine field, a curved shear for which the reference-plane cut is
wrong, surface segment intersection, and deterministic one-sided treatment of
a coincident internal face. The same controls can run without FEM:
```sh
c++ -std=c++20 -O0 experiments/model_slice_geometry_tests.cpp -o /tmp/model_slice_checks
/tmp/model_slice_checks
python -m unittest discover -s experiments -p test_plot_model_slices.py -v
python -m unittest discover -s experiments -p test_compare_model_slices.py -v
```
The Python controls cover signed independent fields, supplied connectivity for
disconnected material, equal axes, PNG/PDF rendering, and rejection of a
cross-element triangle, an off-plane field/outline, and shape exaggeration.
They are geometry and plotting controls, not a substitute for a coupled-model
validation run. The exporter checks that its density, enthalpy and displacement
source buffers remain bitwise unchanged.
The comparison controls use an affine signed density and independent enthalpy
on a unit square at two subdivisions. They check exact area/integrals/perimeter,
explicit counting of duplicated triangles, shared axes/color normalizations,
and rejection of a mismatched offset or reversed refinement. They do not run a
FEM model. An additional affine control verifies that coarse and fine scalar
rasters agree, and the disconnected-material control verifies masked vacuum.

View File

@@ -0,0 +1,58 @@
# Explicit rotating n=3 physical-family control
Branch `research/n3-compatible-family-20260919`; parent `6d423cb`.
This changes experimental physical inputs, not solver equations or production
defaults. It must not be presented as a preconditioner speedup comparison.
The driver normally chooses K for a nonrotating mass-one Lane–Emden star.
The sharp gravitational-energy inequality and the steady virial identity
require, for n=3 and a nonnegative exact-EOS density,
beta = T/|W| <= [1 - (M_LE(K)/M)^(2/3)]/2.
At exactly M=M_LE(K), nonzero rotation is impossible. An independent DOP853
Lane–Emden integration with five tolerance/step/start controls gives the
actual driver's K=0.36393905995216302 a Lane–Emden mass
0.9999999918534539. Thus the numerical K is slightly on the permissible
side, but beta cannot exceed approximately 2.71552e-9. The control-to-control
mass spread is 1.95e-14; this is a numerical sensitivity observation, not a
rigorous interval enclosure. The intended moderate rotation cannot be reached
while retaining that essentially critical mass/K combination.
The optional experiment flag `--n3-K-factor f` multiplies K by a positive
factor, with index required to be exactly three when f differs from one.
The default is one. The analytic seed central density is multiplied by
f^(3/2), keeping its radius equal to the unchanged reference radius. Its
mass becomes approximately f^(3/2), while the target mass remains one.
This is a deliberately off-constraint initial guess, not a density rescaling
during Newton. The public EOS and independent density formulation are unchanged.
The seed's Bernoulli scalar continues to use the target mass; its discrepancy
is part of the initial nonlinear residual and is not hidden by this control.
The bounded first case uses f=.99, J=.035, no central border, the existing
gravity-Schur preconditioner and gravity-curvature trial path, 10 updates,
eta=.03 and absolute nonlinear target 1e-12. The necessary beta bound is then
0.00500000269. This does not guarantee existence, convergence, or identify
a fraction of critical rotation. J already breaks the nonrotating n=3
homology, so this case does not add an extra central-density phase condition.
Before execution, the favorable frozen n=3 field-feedback result motivates
one matched live companion using `stellar-ldu-gravity-schur`. It changes only
the inverse and retains the original ten-update budget, eta=.03, trial path
and physical specifications. The pair is versioned on
`research/n3-live-field-feedback-20260919`; the main convergence report records
the preceding evidence. No success or speedup is assumed from the frozen
eta=.003, J=0, phase-constrained benchmark.
The energy inequality's assumptions are not automatically satisfied by the
discrete independent rho/P(h) fields, approximate gravity, or a central
artificial forcing. This compatibility argument selects a sensible continuum
target; it is not a new density limiter or a substitute for numerical tests.
Primary source: Cheng, Cheng and Lin, equations (1.14)–(1.15) and Theorem 3.1,
[Expanding solutions near unstable Lane–Emden stars](https://arxiv.org/html/2305.10218#S3.SS1).
The displayed beta bound is our consequence of their inequality and
2T+W+3 integral(P)=0. Their G=1 convention matches this diagnostic.
Independent integration evidence is retained in
`../../diagnostics/n3_mass_compatibility_2026-09-19/`.

View File

@@ -0,0 +1,184 @@
# Negative density: location, mechanism, and implications
Branch: `research/negative-density-diagnosis-20260919`.
Parent: `1148c09` (native spherical harmonic surface validation).
Scope: frozen-state observations and independent reconstructions only. No equilibrium equation, field order, surface parameterization, preconditioner, normalization, or Newton strategy was changed. No new equilibrium was solved in this investigation.
## Main finding
At the measured converged n=1.5 endpoint, the negative density is an undershoot of the **quadratic discontinuous density representation required by the weak EOS closure**. An independently assembled elementwise projection of the nonnegative EOS target sampled by the closure reproduces the stored coefficients within **1.40e-14**, while the negative density is of order 1e-4. This identifies a property of the measured discrete root, rather than an unfinished density-equation solve.
The negative region is in the outermost stellar cells. All 96 surface-adjacent cells contain it; all stored density DOF values remain positive. The initial n=1.5 seed is already negative there before Newton, through a related but distinct interpolation mechanism. A nonrotating n=3 seed has a negative pocket inside the same outer cell layer. A thinner negative layer also exists in the converged n=1 control, despite being missed by q18 and q26 volume sampling.
The practical implication is that a better preconditioner or tighter solve cannot remove the negative polynomial at this same root. We need to assess the density representation/closure before treating convergence as physical validation. This does not prove that the previous Newton plateaus, or the separate hydrostatic-gradient error, have the same cause.
## What the code actually solves
Density and enthalpy are **separate unknowns**. The current defaults are discontinuous L2/Q2 density and continuous H1/Q3 enthalpy; the uniform order increment is zero in these runs. The surface is the existing L=4 all-m candidate, solved simultaneously with the interior in the saved equilibrium runs.
On each stellar element, the density equation is
\[
R_i=\sum_q w_q\,\varphi_i(q)\left[\rho_h(q)-\rho_{\rm EOS}(h_h(q))\right],\qquad
\rho_{\rm EOS}(h)=\left[\frac{h}{(n+1)K}\right]^n\quad(h\ge0).
\]
The weights include the physical deformation. Consequently, a zero density residual gives
\[
M\boldsymbol\rho=\boldsymbol b(h),\qquad
M_{ij}=\sum_q w_q\varphi_i\varphi_j,\quad
b_i=\sum_q w_q\varphi_i\rho_{\rm EOS}(h).
\]
This is a quadrature-defined weighted L2 projection. It is not pointwise EOS equality, and its unique polynomial need not be nonnegative. The local mass matrices were independently assembled and solved with Cholesky; no regularization or clipping was used.
In particular, the implemented dependency is not “negative density produces negative enthalpy.” Preparation requires finite density and rejects sampled negative enthalpy. Pressure is evaluated from enthalpy. Hydrostatic balance constrains `h + phi - centrifugal_potential - C`; density affects it indirectly through the coupled problem. At every negative-density q18/q26 volume sample in this study, enthalpy was positive. The surface traces have exactly zero enthalpy even where the density trace is negative.
Source locations:
- [Independent density and enthalpy declarations](../libmeanfield/interface/field/field_registry.cppm), `Density` and `Enthalpy`.
- [Prepared closure](../libmeanfield/impl/operators/prepared_barotropic_closure.cpp), state checks and `weightedResidual` assembly around lines 603–652; `BuildResidual` around line 681.
- [Pressure preparation](../libmeanfield/impl/operators/prepared_pressure_force.cpp), pressure from enthalpy around line 787.
- [Hydrostatic preparation](../libmeanfield/impl/operators/prepared_hydrostatic_equilibrium.cpp), Bernoulli imbalance around line 863.
- [Seed initialization](../libmeanfield/impl/seed/stellar_equilibrium_projection.cpp), independent `ProjectCoefficient` calls around lines 164–178.
These relative links are repository references. The implementation paths and line numbers refer to the recorded diagnostic branch; the numerical findings are tied to immutable producer commits below.
## Cases and controls
Four frozen states were examined on the existing modest mesh:
| State | Origin | Central-density constraint | Purpose |
|---|---|---|---|
| n=1, J=0 equilibrium | Saved converged harmonic campaign | Absent | Lower-index control |
| n=1.5, J=0 seed | Original Lane–Emden initialization | Absent | Determine whether Newton creates the defect |
| n=1.5, J=0 equilibrium | Saved converged harmonic campaign | Absent | Identify the endpoint closure mechanism |
| n=3, J=0 seed | Original Lane–Emden initialization | Present | Assess relevance to the target index |
The n=3 state is **not a converged n=3 model**, and no rotating n=3 model was tested. Its normalized seed residual is about 3.10e-3. The two saved equilibria retain their previous normalized residuals, approximately 1.53e-12 and 1.30e-12.
The independent projection used the production closure query and separate q18/q26 rules. The production operator's actual rules and assembled residual were exported separately. Independent versus production closure residual differences have L2 norms of roughly 1.2e-17 to 2.1e-17 across the four states. Constant reconstruction errors were also checked independently. These checks distinguish a correct projection reconstruction from an accidental reuse of the production inverse.
For the n=1.5 equilibrium, the production-rule projected density differs from the saved field by only 2.25e-15 in the physical L2 norm. Raising projection quadrature to q26 changes its coefficients by at most 2.36e-7; the negative density persists. Quadrature error in the EOS projection is therefore far too small to account for the measured undershoot.
### Location and sampling limits
The q26 volume samples locate n=1.5 equilibrium negativity at physical radii approximately 0.99839–0.99993 in unit-reference-radius coordinates. All negative samples belong to the 96 cells touching the stellar/nonstellar interface; none occur in the other 736 stellar cells at these quadrature points. The surface is slightly deformed, so a global radius is not the same as distance from the local surface.
For the n=3 seed, q26 samples locate a negative pocket at radii approximately 0.93615–0.97070, with positive enthalpy about 0.0302–0.0682 there. Its surface density trace is positive even though the density becomes negative farther into the same cell. Thus checking only the surface or density DOFs would miss this defect.
| State | Minimum density at q26 samples | Minimum density DOF value | Minimum density on sampled surface traces |
|---|---:|---:|---:|
| n=1 equilibrium | +9.14281e-4 | +1.70519e-2 | -1.14780e-4 |
| n=1.5 seed | -7.46708e-4 | +2.90301e-3 | -9.26358e-4 |
| n=1.5 equilibrium | -5.59609e-4 | +2.83809e-3 | -7.21193e-4 |
| n=3 seed | -8.48632e-5 | +3.26982e-6 | +2.49230e-4 |
All 2,400 sampled surface trace points are negative in the n=1 and n=1.5 cases; none are negative on the n=3 surface itself. These counts include coincident cell-edge points and are not surface-area fractions or global minimum certificates.
Ordinary quadrature of the sign indicator is not reliable for the volume of a thin negative layer. For the n=1.5 equilibrium, the negative mass estimate changes from 2.89e-5 at q18 to 2.18e-5 at q26; its estimated negative volume nearly halves. The field is unchanged. We therefore added a separate diagnostic that solves the density polynomial's zero crossings along reference-cell lines and integrates its negative intervals directly.
### Integrated negative regions
Define negative-mass magnitude as `integral_{rho<0} |rho| dV`, divided below by the absolute total stellar mass. Volume fractions use the entire stellar volume. The finest interval results are:
| Frozen state | Negative mass / stellar mass | Negative volume / stellar volume | Physical radius range of measured negative intervals / reference radius | Inward reference-cell depth range |
|---|---:|---:|---:|---:|
| n=1 equilibrium | 6.09585e-8 | 0.0327346% | 0.999643–0.999886 | 0–0.0007655 |
| n=1.5 seed | 3.66771e-5 | 1.83795% | 0.993813–1.000019 | 0–0.0329556 |
| n=1.5 equilibrium | 2.24535e-5 | 1.49252% | 0.994917–1.001222 | 0–0.0286204 |
| n=3 seed | 2.88372e-5 | 12.0835% | 0.934409–0.978469 | 0.114925–0.349767 |
The inward coordinate is zero on each surface face and one on the opposite face of that cell; it is not a fraction of the whole stellar radius. Physical radii are measured from the center and do not identify the local surface location. Small deviations above unit radius arise in the represented surface, including the curved reference mesh.
Each state has measured negative intervals in all 96 surface-adjacent cells and none on the sampled lines through the other 736 stellar cells. The n=1/n=1.5 intervals reach the surface; the n=3 intervals form an interior pocket. All 24,576 exported finest negative intervals per state lie above the independent auditor's coefficient-uncertainty threshold.
The minimum-density witnesses in this integration are approximately -1.14756e-4, -9.26332e-4, -7.21171e-4, and -8.54870e-5 respectively. These are different tangential samples from the earlier surface-trace table, not certified global minima. Enthalpy at the first three witnesses is zero on the surface; at the n=3 pocket minimum it is +0.0455581.
Tangential rules with 8, 12, and 16 points per direction agree on negative integrals to roundoff in these cases; the two finest negative-mass integrals differ by at most 1.0e-14 relative. Full mass and volume agree with the independently sampled q18/q26 observations within 1.77e-13 relative. Each root-partitioned interval uses eight integration points. Eight analytic C++ controls and a separate decimal-arithmetic audit check roots, signs, minima, weights, sums, source identity, and provenance. The auditor also has four synthetic test methods, including deliberate corruptions.
This is strong convergence evidence for the measured integrals, not a rigorous three-dimensional sign certificate or a bound on every integration error. Tangential locations remain sampled; a sufficiently narrow angular pocket could be missed. Near-double roots below reconstruction uncertainty are not certified. The auditor verifies saved mapped integrals and their agreement with separate whole-volume observations; it is not a second FEM mapping implementation.
![Representative frozen density traces](../../../diagnostics/negative_density_2026-09-19/figures/surface_density_traces.png)
The lines connect saved samples along representative surface-cell traces. The n=1.5 endpoint and independent closure projection overlap; the n=3 panel is an initial seed. The displayed samples illustrate location and are not global extrema.
## Why positive data can produce a negative polynomial
The density DOFs are values at interior Gauss–Legendre points. Positive values at those points do not imply that the interpolating polynomial is positive everywhere in the element. This explains why simply constraining the existing density coefficients would not address the observed defect.
The initial seed and the converged closure use different approximation operations:
1. The seed interpolates an independently tabulated, nonnegative Lane–Emden density into its nodal density space.
2. At equilibrium, the weak EOS closure determines the weighted L2 projection of the separately represented enthalpy's EOS density.
Both operations can undershoot. The nonrotating seeds establish that neither rotational distortion nor an accepted Newton update is necessary for the defect. Its occurrence throughout the outer cell layer points to a radial approximation mechanism, rather than an isolated bad angular mode. This does not establish independence from mesh quality or deformation in more difficult runs. In a simple one-dimensional surface cell, take positive enthalpy proportional to inward distance and normalize the density to `t^n`, with `0 <= t <= 1`. The exact quadratic L2 projections are
\[
p_{1.5}(t)=-\frac{2}{105}+\frac{16}{35}t+\frac47t^2,
\qquad
p_3(t)=\frac1{20}-\frac35t+\frac32t^2.
\]
The first is negative for `0 <= t < 0.0396969`. The cubic-density example has an **interior negative pocket**, `0.118350 < t < 0.281650`, and minimum -0.01 at `t=0.2`. Both retain the exact cell mean. The n=3 example is a smooth cubic, so the problem is not restricted to fractional powers or a nonsmooth EOS derivative. Three-point Gauss–Legendre interpolation also undershoots: it agrees with the cubic example exactly, and produces a slightly deeper surface undershoot for n=1.5. All interpolated DOF values are positive.
This independently explains the two observed kinds of location, without Newton, gravity, surface deformation, rotation, or exterior-domain approximation. It is a mechanism control, not a quantitative prediction for the curved three-dimensional mesh. The n=1 leading-order example is linear and exact. In the actual discretization, Q3 enthalpy need not lie in the Q2 density space; its projection uses the curved physical-volume weights. The toy model omits that higher-order reference-cell variation. Geometry weights alone would not spoil exact reproduction of an EOS density already in Q2. The n=1 endpoint is nevertheless reproduced by the same independent projection to roundoff.
For this fixed-slope toy model, refining the surface-cell width by a factor of two reduces undershoot amplitude by `2^-n` and negative mass per unit area by `2^-(n+1)`. It does not remove the negative fraction of that cell. Seven exact/algebraic self-tests verify the projections, roots, positive DOFs, mean preservation, and refinement laws.
## Why virial balance does not exclude the defect
The constant test function in the density space preserves the EOS density's cell integral under the projection quadrature. Positive and negative pointwise errors can therefore cancel in mass even when they remain locally substantial. Pressure is computed from `h`, while gravitational and other density-dependent terms use the independent density representation. A small enthalpy-based virial error is compatible with this discrepancy.
The n=1.5 endpoint still has enthalpy-based energy and force virial errors approximately 6.55e-7 and 6.01e-7, respectively. Its density-based pressure and virial are undefined wherever density is negative. Neither successful algebraic convergence nor the enthalpy virial establishes pointwise EOS consistency. Negative-mass fractions describe the defect; they are not virial-error estimates and must not be compared directly with the 1e-5 virial tolerance.
The newly detected n=1 face layer also means that the earlier statement “no negative density at the sampled volume points” must remain qualified. Positive volume-quadrature observations are not a positivity certificate, and density-based virials computed from those samples do not prove that the complete field admits a physical density EOS everywhere.
## Candidate resolutions, not implemented here
**A small controlled order/refinement study is the next inexpensive discriminator.** Change density order alone while retaining the surface, enthalpy, gravity, and displacement choices. Q3 density can represent Q3 enthalpy's linear n=1 EOS exactly on compatible reference cells, making the n=1 layer a clean control. For n=3, Q3 density exactly represents the leading linear-enthalpy surface model, but a generic Q3 enthalpy cubed is Q9; Q3 density is not a positivity guarantee. For n=1.5 the composition remains nonpolynomial. Local refinement should reduce the defect but does not generally enforce its sign.
There is no declared stability contract requiring density order to equal gravity-potential order: the existing RT/L2 pairing constraint belongs to gravity flux and potential. The available uniform-order build option would raise multiple fields together and confound a density-only study. Any eventual independent choice should remain in the field registry and preserve its compile-time checks.
**Pointwise EOS-derived density is the preferred architectural candidate for the barotropic model.** Evaluate physical `rho(h)` consistently wherever density is required, as pressure is already evaluated from enthalpy. This removes the particular independent-density projection undershoot, conditional on admissible enthalpy, and gives zero density wherever the surface enthalpy is zero. It also removes an independent field/closure pair. It is a formulation change: gravity sources and forces, centrifugal forces, mass, angular momentum/inertia, the central-density condition, diagnostics, and output must all use the same constitutive density and correct derivatives.
The compiler's state blocks and dependency graph, normalization and preconditioner blocks must change together through a typed formulation choice. Replacing density values in a cache while leaving density-column dependencies intact would be incorrect. This can remain an internal numerical choice without adding complexity to the user's EOS/mass/rotation specification. Enthalpy admissibility still needs to hold; composing the EOS does not by itself prevent an enthalpy polynomial from undershooting. Its convergence, cost, and virial quality require measurement; none is established by this investigation.
Some weak quantities could remain unchanged at fixed enthalpy and geometry: with matched quadrature, the existing projection already preserves the constant mass moment and any gravity-source moments whose test functions lie in the density space. The benefit is a consistent constitutive density throughout the model, not a guarantee that every source term changes or that virial balance automatically improves.
**A positivity-constrained conservative projection is an alternative if an independent polynomial density is needed.** A local weighted projection could enforce nonnegativity and preserve the constant EOS moment. It cannot retain every original Q2 closure moment when the unique unconstrained solution is negative. Nor does preserving cell mass automatically preserve inertia, forces or virial balance. The altered residual and derivatives through its active constraints would need consistent coupling; sampling positivity constraints only guarantees the chosen samples unless a stronger polynomial certificate is supplied.
Mean-preserving scaling constructions are well established for time-dependent high-order DG methods, but their time-step and admissibility hypotheses do not supply a convergence theorem for this steady stellar system. [Zhang and Shu's review](https://www.math.purdue.edu/~zhan1966/research/paper/review.pdf) describes that construction. [Xu and Shu's stationary analysis](https://bpb-us-w2.wpmucdn.com/sites.brown.edu/dist/0/348/files/2022/10/On-the-conservation-of-Positivity-preservin-discontinuous-Galerkind-methods-for-stationary-hyperbolic-equations.pdf) further illustrates why preserving cell averages alone can fail to preserve a stationary discrete balance. Those are methodological references, not ready-made stellar solvers.
### Changes that would not resolve the identified mechanism
- A stronger preconditioner or tighter Newton tolerance would reproduce the same negative density at this root.
- Exact algebraic elimination `rho = M(q)^-1 b(h,q)` also reproduces that polynomial. Its correct derivative is `delta rho = M^-1(delta b - delta M rho)`; eliminating a block does not make this a pointwise EOS formulation.
- A basis change alone leaves the represented polynomial unchanged. Nonnegative coefficients in the current nodal basis are already present.
- Clipping density in diagnostics would conceal the error. Clipping or rescaling it after solving would alter the solved equations and density-dependent physical quantities.
## Implication for the n=3 rotating target
This is useful progress: the investigation isolates a concrete density-representation defect that exists before Newton and remains at a converged root, including a directly relevant n=3 control. It also exposes a validation blind spot in ordinary quadrature sampling. It does not yet establish a valid n=3 equilibrium, explain every nonlinear plateau, or solve the hydrostatic-gradient discrepancy.
Any chosen resolution still needs an accurate n=3 nonrotating anchor, the intended central-density normalization for its homology freedom, then a rotating sequence to the agreed moderate-rotation target. Global virial error <=1e-5 remains required, together with EOS-consistent internal fields and resolution checks suitable for comparison with ESTER.
## Reproducibility and validation
Initial spatial/projection producer: `9c22934d52b369f96364e781d6a4843939ec9523`.
Root-interval producer: `d1a594808f960bbaeeb6df8a8ce6a95458765b19`.
Evidence directory: `../../diagnostics/negative_density_2026-09-19` relative to this checkout.
- `campaign/` contains four serial observations, immutable binary, source/build/mesh provenance, exact commands, input/output hashes, and retained CSVs.
- `campaign_audit.json` verifies the saved algebra, independent production/projection residual agreement, physical-observer agreement, sums, coefficient errors, and hash bindings.
- `regions_campaign/` contains the same four states, observed serially with the root-interval diagnostic. All four completed successfully; no Newton steps were taken.
- `regions_campaign_audit_v1.json` and its log record the independent interval audit. Ninety-six consumed files are hash-bound. Observed state vectors, full density coefficients, and block layouts are byte-identical between the two campaigns.
- `audit_self_checks.json` verifies acceptance of a valid case and rejection of missing hash coverage and a nonmaximal coefficient corruption that does not change the reported maximum error.
- `cli_scope_checks.json` records rejection of accidental Newton execution and incomplete snapshot options.
- `reference_model/` and `reference_model.log` record the independent one-dimensional controls and seven passing self-tests.
- `figures/surface_density_traces.png` displays representative stored-field and independent-projection traces; the n=3 panel is an initial seed, not a solution.
The exact case arguments are committed in `negative_density_cases_2026-09-19.json` and `negative_density_region_cases_2026-09-19.json`. Each campaign contains its private executable, exact command records, build settings and source commit. Both use `sandbox.smesh`, SHA-256 `ce11ae99e21e6c3bbfbee402acd2e191c1da0d8261d2227b4203f73f2f337a74`, with uniform field-order increment zero. Run `audit_negative_density.py` on `campaign/` and `audit_negative_density_regions.py` on `regions_campaign/`; the latter binds automatically to its sibling `campaign/`. The analytic control and region auditor each expose `--self-test`.
The numerical observations are single-rank. No production test suite was rerun because production code was unchanged; the compiled diagnostic, independent mathematical controls, actual-operator residual comparisons, frozen-state invariants and artifact audits are the validation specific to this investigation.

View File

@@ -0,0 +1,484 @@
# Nonlinear step obstruction after gravity preconditioning
The completed frozen-state investigation supports a consistent directional
Jacobian and a narrow range of useful trial steps at the n = 1.5, J = 0
endpoint. Tightening the full-J forcing tolerance tenfold costs about 70%
more linear work without improving the useful sampled step. Compared with
the seed, the late direction is 17.35x larger despite a 19.59x smaller
residual; strongly cancelling shape and field responses amplify otherwise
moderate corrected-path curvature.
Gravity correction cuts the remainder norm but can increase its adverse
merit projection through the retained equations. A bounded fully coupled
trial correction is the next recommended experiment. This branch implements
diagnostics and records evidence; it makes no production numerical-policy,
physics API, normalization or acceptance-threshold changes.
Three immutable probes cover 144 trial-path observations and 60 successful
auxiliary gravity solves. Their independent final audits pass 20,899 checks;
the new checker passes fourteen synthetic tests. No new model is accepted.
## Recorded decision from the completed preconditioner investigation
The completed report is `PRECONDITIONER_IMPROVEMENT_2026-09-18.md`, committed
at `dc1da62` on `research/preconditioner-benchmarks-20260918`. Its immutable
campaigns live under the task workspace's
`diagnostics/preconditioner_improvement_2026-09-18/` directory.
- Consistent gravity Schur refinement solves the saved n = 1.5, J = 0 linear
system in 132 iterations and 72.3727 s, versus 231 iterations and 100.9943 s
for the independent control. Both satisfy the same independently verified
relative full-J defect of 0.03: a measured 1.39548x speedup.
- Combining this refinement with stellar LDU solves the saved rotating
n = 1, J = 0.1 system in 142 iterations and 96.8236 s. The independent and
gravity-only controls still fail after 600 iterations. Their finite
time-to-convergence is unknown, so no rotating speedup ratio is reported.
- Prepared geometry reuse makes the existing stellar LDU application 8.0425x
cheaper without improving its convergence by itself. Retain this
implementation optimization independently of policy selection.
- The tested nine-mode shape correction does not improve the n = 1.5 case.
It remains an experimental negative result, not a rejection of all coarse
spaces.
- The easy n = 1, J = 0 model preserves all eight virials below 3.74e-7,
while the stronger inverse costs about 4% more. Defaults remain unchanged.
- Neither hard nonlinear model is physically acceptable. Negative sampled
density makes density-pressure virials undefined. In rotation, a smaller
nonlinear residual accompanied a larger enthalpy-pressure virial error.
Residual decrease is not a substitute for virial and field-admissibility
validation. No angular momentum has been calibrated to critical rotation.
## New investigation and controls
Branch: `research/nonlinear-step-obstruction-20260918`, based on `dc1da62`.
The configured worktree is reused to avoid an unrelated full rebuild; the
preceding branch and copied campaign executables retain their exact source
and binary identities. This branch adds experimental diagnostics only.
Start with the n = 1.5, J = 0 endpoint of
`newton_v1/n1p5_J0_curvature_gravity_schur`. All twelve outer linear solves and
all 31 auxiliary gravity solves passed, but the final nonlinear residual was
1.3966991e-5 against a target of 2.7365922e-12. The final accepted alpha was
1/512. Every trial prepared successfully; all nineteen rejections were
residual-decrease failures, and geometry never limited the step.
That campaign did not retain every raw Newton direction. The new late-state
probe computes a fresh direction at its saved final endpoint; it does not
claim to replay the preceding iteration's rejected trials. A plateau in a
bounded twelve-step run is also not proof that all subsequent steps must
fail. The fresh trial measurements can test that possibility.
The final squared-residual shares are approximately 42.42% hydrostatic,
26.23% closure, 15.87% surface, 10.43% gravity, and 5.05% mass. This motivates
examining retained-equation curvature after the gravity correction, rather
than assuming the earlier gravity or pressure-preparation failure persists.
The last auxiliary prepared defect, approximately 3.33e-14, measures agreement
with the affine gravity target, not satisfaction of the gravity equations.
The final gravity-block residual norm is approximately 4.51e-6.
Keep the complete physical equations, fixed normalization, optional
central-density specification (absent here), mesh, and acceptance thresholds
unchanged. Use one gravity Schur refinement at relaxation 0.5 and the same
restart length 160. Fresh cold solves and independently applied full-J true
defects determine direction quality. Trial probes never commit a model.
## Questions and discriminating evidence
1. **Does the prepared trial path have the expected tangent?** For frozen
residual F and computed direction p, measure Jp and actual prepared
differences. The curvature-corrected path should preserve that tangent
because its gravity correction is second order in alpha. A discrepancy
that remains first order above arithmetic noise would implicate the
linearization or preparation path.
2. **Does the inexact linear direction cause the obstruction?** Compare
directions at the same saved state with forcing tolerances 0.03 and 0.003,
subject to a recorded finite iteration budget. A tighter requested
tolerance counts only if its independent true gate passes. Failed solves
are recorded and do not substantiate this comparison.
3. **Which nonlinear terms oppose the linear prediction?** Split p into its
actual surface coordinates and all remaining coordinates. Compare raw
and gravity-corrected trials for full, shape-only and fields-only
directions. Form mixed remainders by vector subtraction. Signed
projections against the full linear prediction distinguish adverse
curvature from large but cancelling terms.
4. **Is the behavior specific to the late state?** Use the same-polytrope
Lane–Emden seed as an early-state control, where the previous production
run accepted its first full Newton step. Record preparation and enthalpy
feasibility separately from the residual metric.
For phi = ||F||^2/2 and ||Jp + F|| <= eta ||F||,
phi'(0) = <F,Jp> <= -(1-eta) ||F||^2.
At eta = 0.03 the slope must be strongly negative if J differentiates the
prepared path. The production sufficient-decrease test therefore ought to
accept sufficiently small resolved steps. The investigation measures whether
large adverse higher-order terms explain how small those steps become.
Each block's vector remainder R = F_trial - F - alpha Jp must satisfy
||F_trial||^2 = ||F + alpha Jp||^2
+ 2 <F + alpha Jp, R> + ||R||^2.
For the corrected trial map, its mixed remainder includes interactions
introduced by gravity correction; it is not identified solely with the raw
physical shape Hessian. Below-floor differences are unresolved, not evidence
of exact linearity.
The EOS provides an additional interpretation limit: rho(h) is proportional
to max(h,0)^1.5 here. At an exact zero with a positive enthalpy direction,
the closure remainder can scale as alpha^1.5 while its first derivative is
correct. A superlinear slope different from two does not alone establish a
Jacobian defect; the direct tangent check is whether R/alpha decreases in a
resolved regime. The strong zero-pressure boundary row is already expressed
as h-h(P_surface), with derivative delta h, so it does not inherit a vanishing
dP/dh boundary row.
The paired directions also permit a conditioning diagnostic without another
operator solve: w = p_tight - p_loose and Jw = Jp_tight - Jp_loose. A large
change in direction with a small action demonstrates a weak response in that
direction, not a proved nullspace or a particular symmetry. Measure the
shape/fields action cancellation as well. Fixed-K, fixed-M n = 1.5 does not
have the familiar exact n = 3 mass-preserving homology; no additional gauge
or central-density constraint is justified by that analogy.
## Execution and validation
Run a late-state probe first, then use its evidence to choose the matched
tighter-direction and early-state controls. All model jobs and builds run
serially. The campaign runner records clean source commits, exact commands,
input/output and executable hashes, and refuses existing output directories.
The diagnostic saves the frozen vectors, layout and normalization, checks
restoration and accepted-buffer invariance, and reports failed preparations
and inner solves without inventing values for missing trials.
## Late-state results at forcing tolerance 0.03
The first campaign, `late_v1`, completed in 696.63 s using executable source
`ba057b3983ff6006e460a1fa80e3e6523ceeb4a5`. Its independent review
`late_v1_review.json` passes 162 provenance checks and 6,238 saved-vector,
arithmetic, layout, failure-semantics, and restoration checks. The checker
and its fourteen focused synthetic tests are committed at `b8d1c6a`.
All saved base residual and Jacobian-action restoration differences are zero;
accepted physical/normalized/residual buffers and normalization factors remain
bitwise identical. There are no accepted model commits or positivity repairs.
The cold gravity-Schur solve takes 84 iterations and 47.9374 s. A separate full
Jacobian application verifies relative defect 0.0295592 against the requested
0.03 gate. The base norm is 1.3966991044e-5, the direction norm is 0.0794897,
and the merit slope is -1.94906e-10. Thus the computed direction is a strong
local descent direction for this fixed normalized residual.
| Alpha | Raw residual / base | Gravity-corrected residual / base |
| --- | ---: | ---: |
| 1, 1/4, 1/16 | pressure preparation fails | blocked by raw preparation |
| 1/64 | 1.807268 | 1.080323 |
| 1/256 | 1.002510 | 1.002025 |
| 1/1024 | 0.999170 | 0.999394 |
| 1/4096 | 0.999764 | 0.999779 |
| 1/16384 | 0.999940 | 0.999940 |
These are sampled trial residuals, not a production line search or a claim
that one of these alphas is optimal. The three smaller decreasing steps
also satisfy the ordinary sufficient-decrease metric. Full and fields-only
large steps fail with `thermodynamic_domain` at `pressure_force`; shape-only
steps prepare across the grid. Eighteen auxiliary gravity solves pass, and
all 36 prepared raw/corrected paths pass their applicable gates. The absence
of pressure rejections in the preceding trajectory is consistent with these
new observations at a different endpoint and direction.
### The measured tangent is consistent
For both full paths, independently recomputed vector remainders have resolved
order approximately two from alpha 1/64 through 1/16384. Shrinking alpha by
four shrinks ||R||/alpha approximately fourfold. Raw ||R||/alpha^2 stabilizes
near 0.085426; corrected stabilizes near 0.005807. No persistent first-order
directional discrepancy is detected over this range. This verifies the
sampled direction and scales, not every Jacobian column or arbitrary states.
Despite this consistency, corrected ||R||/(alpha ||Jp||) is still 1.63 at
alpha 1/256, 0.406 at 1/1024, and 0.0254 at 1/16384. The first-order residual
response is so small that formally second-order terms can dominate it well
before pressure preparation fails.
### The direction couples large cancelling responses
||J p_shape|| = 0.7730368 and ||J p_fields|| = 0.7730377, while
||J p|| = 1.396089e-5. The cancellation factor
(||J p_shape||+||J p_fields||)/||J p|| is 110,743, and the image cosine is
-0.999999999838. All are measured in the unchanged diagonal normalization.
The full directional gain ||Jp||/||p|| is 1.7563e-4; the shape-only gain
is 15.933. Their ratio supplies a lower bound of approximately 9.07e4 on
the normalized two-norm condition number if this finite-dimensional Jacobian
is nonsingular. It is not an estimate of that condition number, a discovered
nullspace, or evidence identifying a particular physical symmetry. In
particular, it does not justify imposing an additional central-density
constraint on this n = 1.5 model.
### Smaller remainder does not guarantee better merit
At alpha 1/1024, gravity correction reduces ||R|| by about 14.7x, but raises
the adverse projection <F+alpha Jp,R> from 2.49849e-14 to 7.20763e-14, a
factor of 2.88. This explains why its residual is slightly worse than the
raw residual at this small step, despite its much smaller remainder.
The corrected adverse projection splits approximately as follows:
| Retained residual block | Share of signed total projection |
| --- | ---: |
| Hydrostatic balance | 43.52% |
| Barotropic closure | 32.33% |
| Surface balance | 19.53% |
| Total mass | 4.63% |
Gravity contributes only arithmetic-scale terms. The raw hydrostatic
projection is small and favorable; correction makes it the largest adverse
contribution. The same signed full-predictor projection decomposes into
1.18% corrected shape-direction remainder, 47.75% corrected fields-direction
remainder, and 51.07% mixed remainder. Even the corrected shape-direction
trial changes gravity-field values. These terms sum by vector identity;
the mixed term includes interactions introduced by the correction. They
must not be identified with the pure shape/field Hessian of the raw operator.
## Matched direction-accuracy control
The tighter late-state solve passes its requested 0.003 true-defect gate:
143 iterations, 81.6901 s, verified relative defect 0.00294840. The physical
base, normalized base, F, RHS, both normalization-factor files and layout match
the looser experiment byte-for-byte. Its individual audit passes 146 producer
and hash checks and 6,238 vector/invariant checks, with zero restoration drift
and bitwise unchanged accepted buffers/factors. All eighteen auxiliary solves
pass. The final controls campaign audit also passes: 349 provenance checks,
6,238 tight-case vector/invariant checks and 7,912 seed-case checks.
| Quantity | Eta = 0.03 | Eta = 0.003 |
| --- | ---: | ---: |
| Verified relative full-J defect | 0.0295592 | 0.00294840 |
| Cold linear iterations | 84 | 143 |
| Cold linear seconds | 47.9374 | 81.6901 |
| Normalized direction norm | 0.0794897 | 0.0796012 |
| Corrected residual ratio at alpha 1/64 | 1.080323 | 1.080567 |
| Corrected residual ratio at alpha 1/256 | 1.002025 | 1.002037 |
| Corrected residual ratio at alpha 1/1024 | 0.999394139 | 0.999394272 |
For w = p_tight-p_loose, ||w|| = 7.06262e-4, or 0.8885% of ||p_loose||.
The direction cosine is 0.99996157. ||Jw|| = 4.10794e-7 and
||Jw||/||w|| = 5.81645e-4. Thus improving linear accuracy tenfold has not
substantially changed the large cancelling direction or its useful sampled
step range. Both full paths again have resolved approximately quadratic
remainders; the corrected remainder actually grows about 0.272% at alpha
1/1024. The tighter solve costs about 70% more iterations and diagnostic
solve time. These are single diagnostic timings, not repeated performance
benchmarks; the accuracy and iteration comparison is the principal control.
### A smaller direction in this two-vector span offers little
A supplementary algebraic experiment solves
minimize ||s||, s in span(p_loose,p_tight),
subject to ||F+Js|| <= 0.03 ||F||.
It uses an orthonormal direction basis, QR/SVD of its two-column action, a
scalar secular solve and a convex KKT check. Complete saved-vector arithmetic
independently checks the candidate and its action; no new FEM operation is
performed. The two-dimensional reduced action condition is 3.3594 and the
KKT relative residual is 1.97e-14, so the small result is resolved within this
algebraic problem.
| Direction | Norm |
| --- | ---: |
| Original loose direction | 0.0794897230590 |
| Original tight direction | 0.0796012421522 |
| Best feasible scalar scaling of tight | 0.0772247555310 |
| Minimum norm in their span | 0.0772243033891 |
The additional reduction beyond ordinary scalar damping is only 0.00058549%.
The candidate's defect using the complete saved actions is 0.0299999999970.
That tiny inward margin is not a certificate that a fresh FEM application
would pass exactly at the boundary. No candidate trial is evaluated, and no
nonlinear improvement is claimed. This deprioritizes selection in this
particular two-vector span; it does not rule out a richer Krylov subspace or
a trust-region method with an explicit non-Newton acceptance contract.
The clean algebraic evidence is `minimum_norm_pair_v4/assessment.json`, with
input/output hashes and reproduction instructions. The preliminary v1
preflight correctly refused the tight case's unflushed layout. A v2 run
produced unexpected NumPy floating-status warnings in two-column BLAS
products despite finite results; v3 replaces those products with explicit
two-column arithmetic and enables floating exceptions. The clean rerun gives
the same result. `analyze_nonlinear_direction_pair.py` preserves that
reproduction logic in this branch at `db93bf7`; v4 reruns that version with
additional RHS-hash and immutable-directory checks.
`minimum_norm_pair_v4_binding_review.json` passes 61 additional checks
binding this assessment and its reproduced vectors to the final audited
producers. That closes the assessment's pending provenance qualification;
its explicit lack of a fresh FEM action or nonlinear trial remains.
## Initial-state control
The initial n = 1.5, J = 0 model has base residual 2.7365921762e-4.
Its cold solve passes in 26 iterations and 15.0205 s, with verified relative
defect 0.0281993. The raw full step prepares and reduces the residual to
1.7298999698e-4. Gravity correction reduces it to 1.61484154945e-5: a 94.10%
decrease, reproducing to roundoff the recorded residual norm of the preceding
production campaign's first accepted step. The late model's best sampled
corrected decrease is only 0.06059%, at alpha 1/1024.
Both normalization-factor vectors are byte-identical across these states.
The following comparison therefore uses the same normalized coordinates,
although it samples different states and directions:
| Quantity | Initial model | Late model, eta = 0.03 |
| --- | ---: | ---: |
| ||F|| | 2.736592e-4 | 1.396699e-5 |
| ||p|| | 0.00458195 | 0.0794897 |
| ||p||/||F|| | 16.7433 | 5691.26 |
| Shape/fields action cancellation factor | about 332.1 | about 110,743 |
| Corrected ||R||/(alpha^2 ||p||^2), alpha = 1/64 | 0.656881 | 0.926040 |
| Corrected ||R||/(alpha^2 ||F||), alpha = 1/64 | 0.0503939 | 418.937 |
At the common alpha 1/64 both full corrected remainders are resolved above
the heuristic floor. The late direction is 17.35x larger despite a 19.59x
smaller residual; ||p||/||F|| increases about 340x. By contrast, sampled
curvature per unit direction increases only 1.41x. The relative quadratic
remainder coefficient ||R||/(alpha^2 ||F||) grows approximately 8,313x.
This describes the observed amplification; it does not estimate a full
Hessian norm or identify a physical nullspace.
For these two sampled corrected paths at the common alpha, the main change
is not orders-of-magnitude growth in remainder per squared unit-direction
step. This does not isolate intrinsic raw-operator or shape-Hessian curvature.
A much larger, strongly cancelling Newton direction is
being asked to eliminate a much smaller residual. Small second-order errors
relative to the individual shape/field responses become large relative to
the desired combined response. All 48 seed paths prepare, all 24 auxiliary
gravity solves pass, and restoration differences are zero. Corrected full
vector remainders show resolved order approximately two from alpha 1 through
1/256. Smaller corrected seed remainders are excluded from order claims by
the heuristic screen including the gravity arithmetic allowance.
## Implications and next intervention
The measured evidence favors a bounded, fully coupled second-order trial
correction as the next isolated intervention. Keep the verified Newton
direction and capture the entire affine target L = F0+alpha J0p. For a
prepared trial y, solve J(y)c = -(F(y)-L), prepare y+c, and evaluate the
complete unchanged residual. This targets the closure, hydrostatic, surface
and mass terms that a gravity-only correction leaves or introduces.
For a locally bounded inverse and a smooth residual, c is second order in
alpha and preserves the original tangent. The observed weak response makes
that boundedness assumption uncertain here. The experiment should therefore
limit correction norm and work, try at most one correction at a selected
prepared trial, and keep the uncorrected candidate available as a fallback.
Recheck geometry and the selected enthalpy-admissibility policy after the
correction, since it can change both shape and enthalpy. Keep that policy
identical for the corrected candidate, fallback and control: this campaign
uses sampled enthalpy without polynomial repair. Adding a polynomial
certificate requires a separate, matched admissibility control. This does
not bypass the pressure preparation failures at large alpha; it tests whether the prepared range can
deliver substantially more useful progress.
Architecturally, implement this as a distinct, defaulted compile-time trial
path policy composed by `PreparedNewtonStrategy`, not as another gravity
specialization. Capture F0 and J0p in `CaptureDirection` before trial mutation;
compose correction in `PrepareTrial`; explicitly refresh the full inverse
after changing the prepared state. The ordinary full-residual acceptance
test and accepted-state commit remain in `stellar_context.cppm`. The public
physics model and existing equations/normalization need no new arguments.
Independently verify the auxiliary full defect ||J(y)c+F(y)-L|| against its
own declared solve tolerance. Preserve and report the base Newton direction's
original full-J gate separately; an auxiliary success must not replace it.
Compare full cost per useful accepted step, including extra solves,
preparations and rejected attempts. Removing a correction residual at high
cost is not itself a solver improvement. Use the same late snapshot, inverse,
forcing tolerance and virial/field diagnostics as the control; a subsequent
short nonlinear run is necessary before claiming convergence improvement.
Tenfold tighter forcing and minimum-norm selection in the two measured
directions are lower priorities after their negative controls. Broader
Krylov-space regularization remains untested. A trust step that intentionally
misses the current Newton gate would need an explicit distinct contract;
solving a shifted system accurately cannot be reported as passing the
original full-J gate.
Continuation in n and then angular momentum remains a separate path for
testing basin dependence, not a demonstrated cure for this local weak
response. A production continuation driver needs a typed checkpoint/state
transfer initializer: the current ordinary initializer requires a radial
seed, whereas the experimental physical snapshot loader is not a general
rotating-model restart API. Record the EOS K(n) path, mass, angular momentum,
mesh and normalization. Nothing here establishes a need for an extra n = 1.5
central-density constraint, a translation gauge, or pseudo-arclength.
No new equilibrium has been accepted in this investigation. The input late
state still has the previously measured negative sampled density and
undefined density-pressure virials, even though its enthalpy-pressure
virials pass 1e-5. Both internal admissibility and the virial milestone remain
required. These n = 1.5, J = 0 controls make no new claim about higher n,
rotating convergence, or any percentage of critical rotation.
## Reproduction and artifact scope
The campaign manifests are `nonlinear_step_late_case_2026-09-18.json` and
`nonlinear_step_controls_2026-09-18.json`. Each records every probe, linear,
and gravity-solve option. Run them serially through `run_plateau_campaign.py`
with the configured Release build, the original `sandbox.smesh`, and a new
output directory. The existing evidence root is the task workspace's
`diagnostics/nonlinear_step_2026-09-18/` directory. Its campaign directories
are immutable; reviews, analysis and figures are kept alongside them.
`late_v1` was built at `ba057b3`; `controls_v1` at `b8d1c6a`, which only adds
the independent checker and tests. Both copied executables have SHA-256
`5f5c4ed0dae351097ec1f632fa4132e490b35c6b8ec3aab689c5a6535b77c634`.
The mesh SHA-256 is
`ce11ae99e21e6c3bbfbee402acd2e191c1da0d8261d2227b4203f73f2f337a74`.
The recorded physical snapshot, frozen normalized state, residual, factors,
and layout provide an exact binding for the paired tolerance control.
The checker reads every saved trial state/residual and recomputes the vector
remainders, signed projections, mixed interactions and norm identities.
It also checks the complete path grid, failed-preparation semantics, budgets,
hashes, input binding, gravity affine-target gates, counters, frozen-state
restoration and accepted-buffer invariants. A failed linear gate remains a
valid finite directional Taylor experiment, but cannot support a claimed
Newton-forcing comparison. Its fourteen synthetic tests include intentional
vector corruption, a hidden first-order error, noninteger superlinear order,
unresolved arithmetic-scale differences, missing hashes/invariants and
failed preparation/inner/prepared-gravity gates.
Example independent review commands, replacing E with the evidence-directory
path and keeping reviews outside the immutable campaigns:
```text
python3 experiments/check_nonlinear_step.py E/late_v1 --output E/late_v1_review.json
python3 experiments/check_nonlinear_step.py E/controls_v1 --output E/controls_v1_review.json
python3 -m unittest discover -s experiments -p test_nonlinear_step_checker.py -v
```
The final comparison is saved as
`figures_v1/nonlinear_step_comparison.png`, `.pdf` and `.json`. Its JSON
records source reviews/hashes and numerical comparisons. Reproduce it with
`plot_nonlinear_step.py --audited-campaign E/late_v1 E/late_v1_review.json
--audited-campaign E/controls_v1 E/controls_v1_review.json --output E/figures_new`,
using a Python installation with NumPy and Matplotlib. This run used the
existing `/opt/homebrew/anaconda3/envs/general/bin/python`; no dependencies
were installed. The final PNG was visually inspected.
Final numerical audits comprise 162 + 349 provenance checks and 6,238 +
6,238 + 7,912 case checks, totaling 20,899. These are arithmetic/provenance
checks, not independent physical validation tests. The supplementary
two-direction assessment has 61 additional binding checks. All three probes
restore the original residual and actions exactly, preserve accepted buffers
and factors bitwise, and perform no accepted-state commits.
Input-snapshot equality is additionally recorded in `late_v1_input_binding.json`:
all 178,073 supplied physical coefficients match exactly. The generic checker
verifies the supplied file's provenance hash and physical/normalized factors;
that separate coefficient check binds the actual imported values themselves.
Reported operator norms use the configured diagonal normalization, not exact
physical L2 norms. The subtraction/gravity allowance is a conservative
heuristic resolution screen, not a certified bound on FEM assembly error.

View File

@@ -0,0 +1,333 @@
# Targeted numerical campaign — September 16, 2026
This campaign tests separate explanations for the Newton plateau while keeping
the public model API unchanged. The original optimized source is preserved in
`research/baseline-20260916` at `80cc3d8`; `main` is unchanged. Hypothesis branches
and complete numerical artifacts are retained, including unsuccessful changes.
## Decisions
| Hypothesis | Current decision | Evidence |
| --- | --- | --- |
| The extra central constraint distorts n=1's local equilibrium | Retain the example correction | Removing it reduces peak EOS error about 22-fold while preserving virial balance |
| Restart 40 loses useful Krylov information | Retain restart 160 in the example | The matched n=1 rotating model reaches strict convergence; restart 40 fails its late linear gate |
| One-way material-to-gravity completion is enough | Do not promote | Both windows still fail at n=3; correction grows and admissibility worsens |
| Rejecting a harmful reused initial guess helps | Retain as limited linear-solver robustness | All eight n=1.5 linear gates pass; the nonlinear plateau remains |
Normalization, the nonlinear stopping tolerances, and the default production
preconditioner have not been changed. The general FGMRES default remains intact;
the example selects its existing restart option. No new physics-facing options
or automatic n-dependent central constraint are introduced.
## Physical model and comparable controls
All runs use the same 1216-element `sandbox.smesh` and the release build's
unchanged FEM spaces. Mesh SHA-256 is
`ce11ae99e21e6c3bbfbee402acd2e191c1da0d8261d2227b4203f73f2f337a74`.
The diagnostic chooses a Lane–Emden reference with M=R=G=1 and derives K and
the seed density for each index. Its n=1 model has K=2/pi and seed density pi/4.
At n=1 and n=1.5 the new controls omit the central constraint; n=3 retains it.
That is an experiment choice, not an automatically imposed library policy.
Controls use nonlinear relative tolerance 1e-8, zero absolute tolerance,
linear relative tolerance 0.03, and a 200-iteration linear cap. A small virial
error and successful algebraic stopping are recorded separately. J=0.05 or
the resulting angular velocity is not a measured fraction of critical rotation.
The common diagnostic revision is `9bd4af6`. The later shared-tools revision
`0470e3b` adds a result checker, source-relative input hashing, and hashes for
saved output states/metadata. It does not alter the stellar solve.
## Removing the n=1 central constraint
The matched J=0.05, restart-40 controls isolate this model change. The initial
physical measurements agree exactly, and their first five accepted step
lengths and linear iteration counts are identical. Both then fail the sixth
linear gate at essentially the same true relative defect, about 0.505.
| Final measurement, quadrature 18 | Central constraint | No central constraint |
| --- | ---: | ---: |
| Peak absolute EOS density mismatch | 7.30451e-3 | 3.32568e-4 |
| Peak EOS mismatch / sampled density scale | 9.33951e-3 | 4.30594e-4 |
| Bernoulli sampled range | 1.45751e-2 | 1.30398e-3 |
| Residual with artificial border source removed | 4.54227e-6 | 6.03609e-9 |
| P(h) energy virial error | 3.01617e-7 | 3.06913e-7 |
Mass, J, and angular velocity are essentially unchanged. The formerly fixed
central enthalpy coefficient falls from 1 to 0.983383508. The peak and range
improvements are localized: volume RMS errors barely change. Quadrature 14
independently shows the same trend. These sampled extrema are not certified
pointwise bounds.
The example now supplies density through the existing Lane–Emden seed policy
instead of constraining the final n=1 model. The added context regression
checks that explicit seeding works without a central constraint. For n=3 the
constraint remains optional; omission is not promised to overcome homology.
## Larger Krylov window: live n=1 success
At J=0.05, changing only restart 40 to 160 gives:
| Quantity | Restart 40 | Restart 160 |
| --- | ---: | ---: |
| Accepted Newton steps | 5, all full | 7, all full |
| Final normalized residual | 6.03609e-9 | 3.38036e-11 |
| Strict configured convergence | No | Yes |
| Total linear iterations, including failed attempts | 370 | 292 |
| End-to-end seconds, including diagnostics | 290.80 | 271.95 |
The first four accepted steps coincide exactly. The fifth solve first crosses
the smaller restart boundary. The final strict threshold is about 2.15e-10.
These are single timing observations, not a general speedup benchmark. A larger
Krylov window also requires more storage.
All four final virial definitions, at both quadrature orders, are below
3.735e-7. The P(h) energy result at q18 is 3.07200e-7. Mass and J errors are
1.75e-13 and 1.54e-14. No sampled density or enthalpy is negative. Local EOS and
Bernoulli errors remain essentially those of the improved unphased model.
The center-of-mass offset falls from 7.66e-6 to 2.69e-8 during the final
corrections, after virial and local EOS metrics have mostly stabilized. This
motivates examining weak position-related directions; it does not identify a
specific null mode or establish a need for an additional gauge.
## Higher index: the larger window is not sufficient
For n=1.5, J=0, no central constraint, restart 160, seven linear solves meet
their true-residual tolerance. Nonetheless, Newton step lengths shrink to
1/2048 and F remains 1.75135e-4. The eighth linear solve fails at relative
defect 0.07910. The first severe damping occurs with a zero initial guess,
before a reused correction can explain the difficulty. Later reused guesses
start with defects about 1.5–2.0 times the RHS norm.
Recorded rejected trials fail the merit test; their geometry remains valid.
Smaller reported starting-step caps include line-search history and must not
be mistaken for geometric admissibility limits. Gravity-gradient and Poisson
rows hold about 99.69% of the squared normalized endpoint residual. Those rows
include both interior and exterior contributions, so this does not locate the
physically important interior error.
P(h) energy/force virials pass at approximately 2.23e-6/2.33e-6, but Bernoulli
and hydrostatic consistency worsen. P(rho) is undefined at some samples because
of small negative DG density values; negative mass fraction is about 2.89e-5.
The corresponding pressure sensitivity budget is about 3.76e-7 in virial units.
This endpoint is not classified as a validated equilibrium.
## Rejected one-way gravity completion
The tested candidate `8c1f823` changes only the structure factorization to
material-then-gravity triangular completion. It retains exactly the default
material component, Chebyshev order 5 gravity mass inverse and three-cycle
AMG potential inverse. It includes density and shape couplings and rebuilds
the scalar border. Its baseline is `9bd4af6`.
Both runs reconstruct the identical n=3 constrained seed. Snapshot, layout,
initial physical measurements, and frozen RHS block norms agree exactly.
Both cold Krylov windows are measured; each policy's restart-160 correction
is then tested without committing any nonlinear step.
| Frozen result | Baseline | Candidate |
| --- | ---: | ---: |
| Restart-40 true residual / RHS, 200 iterations | 0.0563080 | 0.0715826 |
| Restart-160 true residual / RHS, 200 iterations | 0.0402590 | 0.0381781 |
| Restart-160 solve seconds | 98.92 | 117.71 |
| Selected normalized correction norm | 0.75764 | 1.54083 |
| Sampled thermodynamic step bound | 0.15244 | 0.09135 |
Neither clears the 0.03 linear gate. The candidate's alpha=0.1 trial is
inadmissible; the baseline's is admissible and lowers F by 3.40%. The
candidate's best sampled admissible trial, alpha=0.01, lowers F by about 1.01%.
The unchanged seed virial is not evidence about the uncommitted trial states.
Completion contracts the central-border column's Poisson defect about 4.8-fold
but worsens the Bernoulli column's Poisson defect. Those columns have zero
shape component, so this mixed response already occurs for density-source
completion. The experiment does not rule out better gravity subsolves or
two-way material/gravity feedback.
There is also direct evidence of a weak normalized direction. Baseline
restart-40 and restart-160 corrections have cosine -0.985 despite the same
state and Jacobian. If e_i=Jp_i+F, then
J(p_2-p_1)=e_2-e_1, giving a response bound
||J(p_2-p_1)||/||p_2-p_1|| <= 2.77e-4. The candidate adds still more amplitude
in essentially the restart-160 direction. This is not a measured singular
value or an identification of homology, translation, or surface error.
## Warm-start safeguard
The tested source is `1911a26`. The guard checks
the current true defect of a nonzero supplied correction and falls back to
zero only if that defect norm is nonfinite or exceeds ||b||. The unchanged
input contract still rejects nonfinite coefficients in the supplied guess.
It retains finite supplied guesses whose current defect is no larger than that
of a zero guess and leaves the damped-Newton history policy in place. A smaller
initial defect does not guarantee faster subsequent Krylov convergence.
It adds no public options. A nonzero guess costs one extra measured operator
action; zero guesses do not.
Five focused tests pass on one rank (356284 assertions). The two pure-backend
tests also pass on two MPI ranks (41 assertions on each rank), including a bad
guess or overflow confined to one rank. These results establish behavior of
the safeguard. The matched n=1 run then reproduces the control byte-for-byte:
accepted state, physical CSVs, trial records and all non-timing Newton columns.
Its eight virial checks pass, and it reaches the identical strict convergence.
At the first shared n=1.5 damped state, the guard changes the effective initial
defect/RHS from 1.5097 to 1 and reduces linear iterations from 71 to 65. The
same alpha=1/64 is accepted, with a slightly smaller nonlinear residual. Later
comparisons follow different trajectories and are not same-matrix comparisons.
| n=1.5 capped-run result | Control | Guard |
| --- | ---: | ---: |
| Successful linear solves | 7, then an eighth failure | All 8 |
| Total linear iterations | 672 | 561 |
| Iterations in first seven attempts | 472 | 467 |
| Final normalized residual | 1.75135e-4 | 1.74946e-4 |
| Final accepted step | 1/2048 | 1/8192 |
| End-to-end seconds | 550.36 | 508.16 |
Most of the total iteration reduction comes from avoiding the final 200-step
failure. The guard reaches the nonlinear iteration cap instead. Its residual
is only 0.108% lower, so this is not a nonlinear-plateau cure or a claim of
mesh-independent solver performance. The timings are single observations.
P(h) energy/force virials remain near 2.24e-6/2.35e-6, changing only about
9.0e-9/2.0e-8. EOS and Bernoulli errors improve slightly and the negative-density
budget barely changes. The conservative solver-plus-eight-check screen remains
unsatisfied: strict convergence is absent and P(rho) cannot be evaluated. P(h)
meets the primary virial milestone; this does not validate the local solution.
The center-of-mass offset increases from 1.67e-6 to 4.57e-6, so it would
be incorrect to claim that all physical metrics are unchanged. Both endpoints
remain unconverged. These limits motivate retaining the guard as a modest
improvement to the inner solver while pursuing the operator/weak-direction work.
## Validation and reproducibility
`experiments/run_plateau_campaign.py` builds a committed source revision and
retains exact case commands, build settings, mesh and binary hashes, an
immutable executable, snapshots, CSV diagnostics, and observed exit codes.
Cases run serially. A campaign exit of zero means observations completed;
a model exit of three remains recorded as nonconvergence. Timing samples are
not repeated benchmarks, and dynamically loaded dependencies are not frozen.
`experiments/check_plateau_physics.py RESULT_FOLDER` gates strict recorded
convergence and all eight defined, finite virial errors at 1e-5: energy/force,
P(h)/P(rho), and quadrature 14/18. This conservative joint screen is stricter
than the primary physical milestone. In particular, the undefined P(rho) at
n=1.5 does not by itself prove physical virial failure; the defined P(h)
virials pass. The checker separately reports sign, conservation,
EOS, and Bernoulli measurements. It does not certify pointwise correctness or
assign arbitrary local-error tolerances. The checker distinguishes the
converged n=1 case, the n=1 algebraic failure despite good virials, undefined
P(rho) at n=1.5, and the failing n=3 seed virial.
The combined source at `b3a752b` builds the sandbox, tests and diagnostic.
Three context/root tests pass (61 assertions): explicit seeding without a
central constraint, the generated angular-velocity/composable border, and
propagation of that angular velocity into physical rows. Together with the
five safeguard/Newton tests this is eight distinct focused C++ tests, with
two backend tests additionally repeated on two MPI ranks. It is not a rerun
of the entire historical suite. Later combined commits change documentation
and case manifests only; the final live campaign records `c88baa1`.
## Final combined physical checks
The combined executable has the same SHA-256 as the guarded executable. The
nonrotating n=1 case is the physical counterpart of the sandbox model, using
the diagnostic stopping controls. It converges in six full Newton steps,
with F=1.65157e-13 and 307 total linear iterations. Its worst virial error
among all eight checks is 3.73092e-7; the largest q14/q18 change is 1.29e-13.
At q18 the absolute mass error is 8.88e-15, J error is zero, and no negative
density or enthalpy is sampled.
Local consistency errors remain: peak/RMS EOS mismatch divided by sampled
density scale is 4.23549e-4/8.56537e-5, Bernoulli RMS is 1.13917e-4, and
hydrostatic gradient RMS is 5.48097e-3. These are measurements, not newly
invented acceptance tolerances. The literal sandbox executable was compiled;
its physical counterpart was run through the diagnostic for these measurements.
The J=0.1 transfer case doubles the previous target angular momentum and allows
12 Newton attempts, while retaining the numerical implementation and tolerances.
It is a physical transfer test, not a one-variable solver-policy comparison.
It does **not** converge: all 12 linear solves pass (507 total iterations), but
F plateaus at 6.25389278e-3 and the last accepted step is 4.76837e-7. The process
stops at its nonlinear iteration cap. Its 527.62 seconds include diagnostics;
summed Newton-attempt time is 462.33 seconds.
This endpoint also fails the primary virial milestone. At q18, the P(h) energy
and force virial errors are 4.75186e-4 and 8.18118e-4; q14 agrees to within
4.54e-14. Absolute mass and J errors are 6.42266e-4 and 2.13748e-4. Actual angular
velocity is 0.3431369602 in reference units, not a critical-rotation fraction.
P(rho) is undefined at negative-density samples; the negative mass fraction is
1.07284e-5. Peak/RMS scaled EOS mismatch is 1.02932e-2/5.75843e-4, and raw
Bernoulli RMS is 9.92365e-4. This is an unresolved failed model.
All 30 rejected trials fail pressure-force preparation before residual
measurement, unlike the merit-only n=1.5 plateau. The final sampled minimum
enthalpy is 1.82998e-10, with no sampled negative enthalpy; the minimum sampled
mapping determinant is 0.870965. Finite negative enthalpy is the leading
inference for rejected trials: pressure preparation explicitly rejects h<0,
and geometry preflight includes the pressure quadrature rules. However, the
recorded rejection also permits a nonpositive determinant/mapped-weight cause,
and the CSV omits the exact rejection code. An accepted state's sampled minima
do not certify its rejected trials. The present evidence supports locating an
admissibility obstruction, not declaring its exact sample or cause established.
Later supplied guesses are retained with defect/RHS near 0.03, so discarding
bad warm starts does not address this final obstruction.
## Retained Git history
The original checkout is left on `research/combined-20260916`, with the adopted
changes committed. The starting optimized source is committed on the baseline
branch; historical untracked caches and data are preserved. Separate hypothesis
branches remain available for inspection or reruns.
| Branch | Recorded revision / purpose |
| --- | --- |
| `research/baseline-20260916` | `80cc3d8`: preserved incoming source |
| `research/experiment-harness-20260916` | `9bd4af6`: common driver; `0470e3b`: checker; `899cb18`: screening clarification |
| `research/central-constraint-20260916` | `5167744`: hypothesis evidence; `2e19c2c`: combined validation notes |
| `research/krylov-window-20260916` | `937d2f2`: example restart 160; `1f9184b`: combined validation notes |
| `research/gravity-coupling-20260916` | tested `8c1f823`, outcome `db0ddd3`: rejected completion retained here |
| `research/krylov-20260916` | tested `1911a26`, outcome `7127383`: guarded warm guesses |
| `research/combined-20260916` | C++ build/context tests `b3a752b`, final live cases `c88baa1` |
## Next discriminating work
1. At a frozen stalled state, split a correction into shape-only and remaining
field components. Measure full, pure-shape, pure-field and mixed Taylor
remainders at common admissible step lengths. Fixed-shape gravity is affine
in the fields, so its field-only remainder should be at roundoff.
2. Characterize the weak correction differences with physical moments and
controlled symmetry/shape tangents before adding a gauge or regularization.
3. Separate interior, exterior, and interface gravity error. Exterior accuracy
matters through its effect on the interior; current aggregate block norms
cannot establish where the plateau lives.
4. For the stronger-rotation pressure-preparation failures, record the specific
rejection reason and offending enthalpy/mapping sample. Geometry preflight
already includes pressure quadrature; negative h is the leading inference,
but the existing CSV cannot exclude a mapping/preflight discrepancy. Locate
the obstruction before selecting a positivity or surface treatment.
5. If residual normalization is changed, first rescore identical physical trial
states. This separates a changed merit from a changed Newton correction.
High-rotation continuation and a measured critical-rotation fraction remain
future validation work. These results do not establish the 50% or 99% targets.
## Artifact index
The complete campaign is retained at
`/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/numerical_campaign_2026-09-16`.
Each of `controls`, `baseline_n3`, `gravity`, `guard`, and `combined` contains its copied
case manifest, source/build provenance, executable, run records and diagnostics.
Use its retained `cases.json` with `run_plateau_campaign.py` at the recorded
source revision and a new output directory to repeat the observation. The
runner invocation and build requirements are in `plateau_diagnostic_README.md`.
- [Detailed controls](</Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/numerical_campaign_2026-09-16/control_analysis.md>)
- [Gravity-coupling comparison](</Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/numerical_campaign_2026-09-16/coupling_comparison.md>)
- [Gravity-coupling interpretation](</Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/numerical_campaign_2026-09-16/coupling_interpretation.md>)
- [Warm-start comparison](</Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/numerical_campaign_2026-09-16/guard_analysis.md>)
- [Final combined physical validation](</Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/numerical_campaign_2026-09-16/combined_validation.md>)
- [Combined context/root test manifest](</Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/numerical_campaign_2026-09-16/combined_checks/manifest.json>)
- [Focused safeguard test manifest](</Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/numerical_campaign_2026-09-16/guard_checks/manifest.json>)

View File

@@ -0,0 +1,169 @@
# Optional Newton strategies: implementation and validation
The experiments start from `7a07cae`. Each hypothesis has an isolated, build-configurable branch; the integration branch combines the implementations behind explicit typed policies. The default physical model, normalization, preconditioner prescription, and ordinary Newton path remain available. Central density is still an optional model specification.
## Selection and ownership
`Newton(options)` retains its existing meaning. An expert numerical configuration can supply a third constructor argument:
```cpp
namespace nl = mean_field::solver::nonlinear;
auto numerics = nl::NewtonNumerics{
nl::PolynomialEnthalpy{},
nl::GravityCurvatureCorrection{}
};
auto configuration = nl::Newton(options, nl::NormalizedResidualMetric{}, numerics);
auto solve = mean_field::solver::make(context, configuration);
auto report = solve.evaluate();
```
The enthalpy choices are `SampledEnthalpy` and `PolynomialEnthalpy`. Gravity choices are `MonolithicGravity`, `GravityCurvatureCorrection`, and `EliminatedGravity`. Their combinations are concrete C++ types. Unregistered policy types are rejected by concepts. Block identities come from the compiled equation form; mesh sizes, FE eligibility, arithmetic values, and distributed preparation generations are checked at runtime.
The context owns each prepared workspace. Strategy dispatch is static; only destruction of the selected context-owned strategy storage is erased. The existing MFEM operator and solver application interfaces still use virtual dispatch. Workspaces are constructed when a solve selects them and are destroyed before their borrowed operator/backend dependencies. Reduced gravity recovers the outer backend prescription through `GetConfiguration()`; custom backends need that capability only when selecting elimination. Polynomial direction repair currently requires the normalized residual metric, because its derivative supplies the line-search slope.
## 1. Polynomial enthalpy feasibility
The implementation transforms the actual nodal polynomial to a tensor Bernstein representation using outward-rounded interval arithmetic. Adaptive subdivision either certifies nonnegativity, proves negativity through a negative polynomial value, or reports unresolved bounds. A negative Bernstein coefficient alone is never classified as a negative polynomial. Exact zero traces are retained algebraically.
The production adapter works in physical enthalpy coordinates; a general diagonal normalization need not preserve the polynomial encoded by normalized coefficients. It supports conforming scalar H1 hexahedral elements with the supported closed nodal tensor bases and runtime polynomial order. The stellar adapter requires a specific-enthalpy carrier and the recognized `eos::SpecificEnthalpyFromPressure` surface relation at compile time; it collectively checks zero prescribed surface pressure and the EOS reference `h(P=0)=0` at runtime. Unsupported spaces and surface prescriptions fail explicitly. Unsafe fast-math compilation is rejected. Gradual underflow and immutable FE spaces remain prerequisites.
An invalid or uncertifiable initial polynomial is rejected before a residual-based convergence declaration. For a valid base, a certified initial enthalpy field provides an immutable anchor. The repair family is
\[
p_h(\beta)=(1-\beta)p_h+\beta(h_{\rm anchor}-h),\qquad 0\le\beta\le1.
\]
Shared true DOFs and prescribed zero traces are preserved. Bernstein inequalities provide a sufficient lower bound on the repair fraction, and the full linear residual model selects a fraction within that feasible interval. The actual represented candidate is certified again after normalization and state addition. A non-descent repair fails explicitly. Backtracking uses the repaired direction's merit derivative and still evaluates the complete nonlinear residual.
This is a conservative feasible-direction method, not the solution of a constrained Newton optimization problem. It may be too restrictive or have no descent direction. It does not prove positivity of the independently represented density field. Unchanged feasible directions require one extra Jacobian action; a model-selected enthalpy repair requires three. Combining it with elimination also relifts gravity and recomputes the actual merit derivative.
## 2. Gravity curvature correction
Write the normalized state as retained variables `u` and gravity variables `z`, with gravity equations `G(u,z)`. The gravity partition includes both gradient and potential equations and retains their boundary rows. Given a base `x`, Newton direction `p`, and trial `y=x+alpha*p`, solve
\[
G_z(y)\,\delta z=-\{G(y)-G(x)-\alpha G'(x)p\}.
\]
The right side removes only the nonlinear remainder. It vanishes on an affine gravity path even when the base gravity residual is nonzero; it is second order in the trial length when the operator is smooth. The base residual and Jacobian action are captured before trial preparation. The candidate inverse is refreshed before solving. Only the candidate's gravity coordinates change.
A fresh complete preparation checks the intended gravity target and evaluates the full merit. Its consistency allowance is `256 epsilon` times the sum of separately measured gradient, potential, source, correction-action, and residual norms. The fresh affine-prediction discrepancy must fit this allowance; the target defect must fit the measured inner true defect plus that allowance. This is a heuristic arithmetic estimate, not a rigorous forward-error bound. Separate field contributions account for cancellation hidden by the small total gravity residual. The inner true-residual gate, lifted full-Jacobian gate, and full nonlinear convergence/merit criteria retain their original tolerances. A failed inner solve, failed preparation, or unacceptable corrected merit does not commit a state. Trial observers must publish the corrected physical and normalized vectors together. The tangent is distinct from the secant of this curved trial path.
## 3. Gravity elimination
The nonlinear trial path completes gravity at fixed retained variables. The initial state is also explicitly completed before defining the nonlinear convergence reference. Retained coordinates include density, enthalpy, shape, and all model specification borders; optional central-density borders remain optional.
For the partitioned Jacobian, the reduced action is
\[
S=F_u-F_zG_z^{-1}G_u.
\]
Right-hand-side condensation includes any remaining gravity defect, and lifting reconstructs the corresponding full correction. The retained projection of the supplied full inverse preconditions the reduced system. Every lifted outer Newton correction must satisfy the original full normalized Jacobian residual tolerance. A later enthalpy feasibility repair changes that correction and is instead checked for its relift, strict merit descent, and nonlinear acceptance; it is not claimed to retain the Newton forcing tolerance. Candidate gravity completion is separately checked after fresh nonlinear preparation.
Tolerance-stopped inner Krylov solves approximate a linear Schur action. Flexible outer preconditioning does not make this action exact. Tight inner tolerances, directional derivative checks, and the full lifted residual gate control this limitation. Inner failure propagates explicitly. Operator actions never prepare or mutate the physical state.
The reference implementation restricts the full operator and supplied inverse. The default automatic application policy can instead reuse the existing physical gravity action and gravity inverse, with the same diagonal normalization. Compile-time capabilities recognize the physical runtime, specification couplings, block identities, and preconditioner factorization. A collective runtime comparison requires the canonical partition on every rank. Unknown runtimes or incompatible partitions use the reference path. The explicit `RootRestrictedGravityApplications` policy remains available for comparisons. This changes block applications, not the nonlinear equations.
## Interpreting reports
The complete nonlinear residual remains the merit and convergence authority. Gravity residual reduction alone does not establish a stellar equilibrium. The existing physical checker separately requires solver convergence and all eight energy/force, enthalpy/density, and quadrature-order virial measurements to pass `1e-5`; it also reports local EOS, force, sign, and conservation diagnostics.
For elimination, a successful linear backend report describes the reduced system; the lifted full-system true residual is a separate diagnostic. An inner failure propagated by the outer `Solve` describes the gravity subsystem. A later feasibility-relift or trial-completion failure can leave the previously stored outer report converged in reduced coordinates; its auxiliary failure is recorded separately. The report-space label always belongs to the retained outer report. Nested gravity solve times overlap the outer reduced solve time, and backend solve time excludes some condensation/lifting work. Use complete iteration and campaign wall times for performance comparisons, not a sum of these overlapping measurements.
## Reproducibility and evidence
Branches:
- `research/polynomial-positive-newton-20260917`
- `research/gravity-curvature-correction-20260917`
- `research/gravity-reduced-newton-20260917`
- `research/gravity-compact-application-20260917` (equivalent block applications)
- `research/gravity-prepared-roundoff-20260917` (prepared-equation consistency)
- `research/polynomial-endpoint-certification-20260917` (read-only final polynomial checks)
- `research/gravity-trial-diagnostics-20260917` (per-attempt reporting)
- `research/gravity-direction-diagnostics-20260917` (work accounting on rejected repaired directions)
- `research/numerical-strategies-20260917` (combined production integration)
The campaign runner builds a committed clean source revision, copies an immutable executable, and records source, mesh, executable, input-state, and output hashes. Serial execution keeps timing comparisons interpretable. Each new run uses a fresh output directory. Frozen probes preserve accepted buffers and verify restoration; they never certify a final physical model.
### First frozen and production observations (`4ae2f3f`)
The first immutable build is retained in the workspace under `diagnostics/numerical_strategies_2026-09-17/frozen_v1`, with its source and executable hashes. Its production observations are in `models_v1`, referencing the same frozen executable.
- **n=1, J=0, polynomial policy:** six accepted full Newton steps; final normalized residual `1.65157289693e-13`. No direction repair. All eight virials pass; maximum `3.73091953522e-7`. This reproduces the earlier converged control. It is a solver/virial milestone, not a pointwise continuum-accuracy certificate.
- **n=1, J=0.1, captured iteration 2:** the base certifies nonnegative; the original full trial is proved negative. Whole-mesh certification takes about 3–4 ms. The sufficient repair fraction is `0.9152726503`; repaired trial polynomials certify and prepare, but tested step lengths `1, 0.5, 0.125` all increase the full residual. The linear model predicts its best step near `0.00825`, with only about 0.46% residual reduction. This is evidence of an overly conservative coupled direction, not evidence that all feasible descent is impossible.
- **Late rotating capture:** the accepted polynomial is already proved negative. The policy returns `invalid_base` and preserves accepted buffers exactly. The first artifact's unvisited repair-report fields incorrectly defaulted to a certificate; the separate certificate file is correct, and commit `5f3eb0b` fixes the report defaults to `unresolved`.
- **n=1.5, J=0, frozen shape-curvature capture:** base residual `1.78804469158e-4`; raw full trial `2.18913190375e-3`; curvature-corrected full trial `1.40702031008e-4`. Gravity remainder drops from `2.18656200516e-3` to `1.37482284578e-12`. Retained coordinates and accepted buffers are unchanged. Correction order measured over the smallest resolved steps is `1.999898`.
- **Reduced frozen action:** Schur action and retained lifted full action differ by `6.71e-19`; minimum central-difference relative error is `1.39e-6`. The original difference grid has only one point sufficiently above the checker's arithmetic floor, so its trend result is honestly **incomplete**. The next build uses larger differences without relaxing thresholds.
- **Production curvature run:** intentionally stopped after six trial rejections at iteration zero, despite converged inner solves. Review identified that the fresh-equation consistency allowance omitted large cancelling gravity contributions. This incomplete run is preserved, including the explicit interruption record; it is not a convergence result.
### Verified implementation (`0bf260f` C++ source, `b21fa40` campaign manifest)
The serial targeted suite passed **40 test cases and 1,842 assertions**. Coverage includes interval polynomial certification and repair, compile-time policy/normalization contracts, gravity block restriction, curvature algebra, Schur condensation/lifting, real stellar compact/full applications with and without the central-density border, explicit auxiliary failure, rollback, FGMRES, and observer exception safety. The checker suite passed **18 Python tests**.
Three separately tagged prepared-arithmetic tests also passed (28 assertions) in serial and on two ranks, bringing this revision to 43 verified serial cases. The original supported two-rank subset passed **34 cases per rank**, with 1,080 assertions on rank zero and 921 on rank one. Running the larger serial selection on two ranks also exposed five failures, all at the existing logical radial surface interpolation restriction to one MPI rank (three new full-stellar fixtures and two existing fixtures). Those failures are retained in `tests_v2/mpi2.log`; full stellar MPI operation is not validated by these results. The low-level distributed gravity and positivity tests pass.
The updated frozen n=1.5 capture passed **all 124 algebraic and invariant checks**. Those probes use inner relative/absolute tolerances `1e-9`/`1e-13` and a 160-iteration cap; production uses `1e-10`/`1e-14` and a 300-iteration cap. The full production outer forcing tolerance is `0.03`, with a cap of 200 outer Krylov iterations per Newton solve, restart 160, and nonlinear relative tolerance `1e-8` (zero absolute tolerance). Larger finite-difference steps resolve the second-order central-difference trend without relaxing checker tolerances; relative Schur errors at steps `0.1`, `0.03`, and `0.01` are approximately `1.26e-2`, `1.13e-3`, and `1.26e-4`, with `1.39e-6` at `0.001`. Restoration and retained-state invariants remain exact.
Three dense directions give **zero difference** between compact and root-restricted gravity operator and inverse outputs on the actual stellar FEM system. Operator applications take about `0.018 s` versus `0.244 s` (approximately 14 times faster), but inverse applications improve only from approximately `0.205 s` to `0.160 s`. The first matched tight gravity solve takes `7.25 s` versus `18.36 s` previously, with the same 40 iterations and numerical result. The approximately 2.5-fold inner-solve improvement must not be described as a 14-fold improvement to Newton or to the complete model campaign.
### Final build and regression (`c82e68d`)
The final `tests` and `plateau_diagnostic` targets build successfully. The targeted serial suite passes **43 cases and 1,886 assertions**, including the per-attempt reporting regressions. The supported two-rank subset passes **37 cases on each rank**, with **1,108 / 949 assertions**. The full-stellar MPI restriction above still applies. `tests_v4` retains the immutable executable, source and binary hashes, build log, test commands, and complete outputs; serial execution took `441.75 s`. The preceding `tests_v3` build was intentionally interrupted when review found the omitted-relift reporting path, with an explicit interruption record and no test result claimed.
### Agreement between converged controls
The n=1 polynomial, curvature, and eliminated endpoints agree in every stored physical block. The largest absolute individual-coefficient difference over all pairs is `2.632e-11` (surface coefficients); density and enthalpy relative coefficient differences are at most `1.18e-11`. Radius spread is `6.095e-13`, density-pressure virial-error spread `1.652e-13`, and the q18 EOS maximum spread is `1.493e-12`. There is no evidence here of materially different discrete equilibria. The apparent EOS maximum difference between earlier summaries was q14 (`3.7882e-4`) versus q18 (`4.2355e-4`) sampling, shared by all three endpoints. These coefficient comparisons are not continuum error estimates. Hash-verified details are in `n1_endpoint_comparison/`.
### Independent endpoint certificates (`c82e68d`)
All three available unguarded endpoints certify nonnegative enthalpy: n=1 curvature, n=1 elimination, and the unconverged n=1.5 curvature state. Each check covers all 832 stellar elements with no subdivision, takes approximately `3.46–3.59 ms`, and has a lower enclosure of exactly zero. The known-negative rotating capture is correctly rejected with a negative witness in element 450 at reference coordinates `(0.41015625, 1, 0.00390625)`; its approximately `3.87 ms` check visits 1,365 subcells. Enclosure bounds are not measured extrema.
All four executed diagnostics pass eight buffer/preparation invariants each; the helper performs no preparation, Jacobian action, or linear solve. Context construction and the wrapper's restoration are outside those helper counters/timings. The timed-out n=1.5 reduced model has no final snapshot and is explicitly `endpoint_unavailable`, with no certificate attempted. The assessment completes with exit 2 solely because that requested endpoint is unavailable; the negative control passes and there is no process/provenance/invariant failure. The n=1.5 curvature certificate does not turn its nonconverged, density-invalid state into a physical pass. Full provenance and classifications are in `endpoint_certificates_v1/assessment.json`.
### Physical validation caveats
Enthalpy certification applies to the represented enthalpy polynomial. It does not constrain the independently projected density polynomial or prove continuum accuracy. Pressure-from-enthalpy diagnostics extend the EOS as zero for nonpositive enthalpy; their finite-value flag alone therefore cannot establish enthalpy admissibility. Unguarded solver endpoints need a separate polynomial certificate. For the converged n=1 curvature control at quadrature order 18, the maximum scaled EOS density mismatch is `4.23549e-4` (RMS `8.56537e-5`), scaled mean-subtracted Bernoulli RMS is `1.13918e-4`, and the raw hydrostatic-gradient RMS is `0.00548097`. These are mesh/sample diagnostics with different meanings and units, not a uniform accuracy norm. No refinement study or local acceptance tolerance is claimed here.
The n=1.5 initial density is already negative at some diagnostic quadrature samples. At quadrature order 18, its minimum is approximately `-5.79e-4`, negative mass fraction `4.51e-5`, and 9,600 of 832,000 samples are negative. The initial diagnostic file is byte-identical to four earlier runs, establishing that this predates the new strategies. The nonnegative radial seed is projected into its independent order-two density space; the projection does not preserve positivity. Pressure-from-density virials are undefined for that state. A small pressure-from-enthalpy virial alone does not pass the full physical gate, and nonlinear convergence is reported separately. This work does not silently clip or replace density to improve the diagnostic.
### Updated production results
| Model and policy | Accepted steps | Final normalized residual | Maximum of eight virials | Newton wall time | Outcome |
|---|---:|---:|---:|---:|---|
| n=1, J=0, curvature | 6 | `6.51136e-14` | `3.73092e-7` | 273.71 s | Solver and virial pass; enthalpy polynomial certified |
| n=1, J=0, eliminated | 6 | `8.98743e-14` | `3.73092e-7` | 869.67 s | Solver and virial pass; enthalpy polynomial certified |
| n=1.5, J=0, curvature | 6 | `1.48794e-5` | Undefined density-pressure entries | 711.72 s | Outer linear iteration limit; not converged |
| n=1.5, J=0, eliminated | 5 | `4.47888e-6` (last accepted) | Unavailable | 1821.79 s completed steps | External 2400 s cap; sixth attempt interrupted |
| n=1, J=0.1, polynomial | 3 | `7.13059e-3` | Undefined density-pressure entries | 265.03 s | Outer linear iteration limit; not converged |
| n=1, J=0.1, polynomial + curvature | 1 | `8.40387e-3` | Undefined density-pressure entries | 127.05 s | Outer linear iteration limit; not converged |
| n=1, J=0.1, polynomial + eliminated | 1 | `2.72634e-2` | Undefined density-pressure entries | 149.83 s | Direction fails descent check before second line search |
The n=1.5 curvature run reduced the seed residual from `2.73659e-4` to `1.48794e-5` (about 18-fold), but stopped on the seventh Newton attempt (zero-based iteration 6), after six accepted steps, when 200 outer Krylov iterations reached only `0.059017` relative defect against the required `0.03`. Accepted step lengths were `1, 1/16, 1/32, 1/16, 1/16, 1/16`. All 14 auxiliary gravity solves / 583 inner iterations passed, and no prepared-consistency failure occurred. Thus the original auxiliary rejection was fixed, while difficult globalization and outer linear conditioning remain. The q18 enthalpy-pressure virial is `4.34868e-6`; this does not establish nonlinear convergence or make the undefined density-pressure checks pass.
The n=1.5 eliminated run reached the 2,400-second external wall cap during its sixth attempted step. Its five accepted steps used lengths `1, 1/2, 1/4, 1/128, 1/2048`, with 5, 25, 29, 44, and 57 outer iterations. The last accepted residual was `4.47887932690e-6`, about 61-fold below the seed but still about 1.64 million times above the nonlinear target. The last step improved the residual by only 0.00565%. All five completed lifted corrections passed the full-Jacobian gate. Nineteen completed trial records contain five acceptances, twelve merit rejections, and two pressure-force preparation rejections; none reports an auxiliary-solve rejection. The last accepted gravity residual is approximately `3.27e-14`, while retained closure, shape, hydrostatic, and mass residuals remain of order `1e-6`. This supports stagnation in the retained equations/globalization despite completed gravity, rather than the anticipated inner-tolerance/full-gate obstruction.
Completed Newton-step times total `1821.79 s`, including `1343.99 s` in the backend and `361.69 s` in trial preparation. The remaining process time includes initialization and interrupted work; it cannot be assigned to a completed sixth solve. No final snapshot or cumulative auxiliary report was emitted, so its final physical validation and total inner-solve counts are unavailable. This is an external timeout, not a solver-reported convergence failure or an equilibrium result.
At n=1, prescribed J=0.1, polynomial positivity alone accepted three steps (`1, 1, 1/64`) and stopped at residual `7.13059e-3`. The fourth linear solve exhausted 200 iterations with relative true defect `0.0331634` against `0.03`. One direction repair used fraction `0.9152726503`; all six line-search rejections were for the full residual merit, with no pressure-preparation rejection. Total outer Krylov iterations were 428 (including the failed fourth solve) and campaign time `331.79 s`. The q18 enthalpy-pressure energy/force virials were `2.39722e-3` / `2.77991e-3`, both above the milestone; negative independent density made the density-pressure virials undefined.
Adding curvature correction reduced the first-step residual from `0.0330653` to `0.00840387` using a bitwise-identical first Newton tangent. It then exhausted 200 outer iterations on its second step at relative defect `0.0826534`. Its one auxiliary gravity solve (45 iterations, `8.07 s`) passed both checks; no enthalpy repair was reached. The q18 enthalpy-pressure energy/force virials were `5.44539e-4` / `6.15376e-4`, and density-pressure entries remained undefined. Thus the initial curvature improvement is real, but neither trajectory converged or passed physical validation.
The combined polynomial + eliminated rotating run accepted one full step to `0.0272634`. Its next reduced solve and lifted full-Jacobian check passed (relative defect `0.0101847`), but the direction check rejected a non-descent proposal before line search: the stored merit derivative was `+1.02028e-4` at repair fraction `0.487323`. This is distinct from the outer-iteration limits above. The old report records 20 gravity solves / 681 inner iterations with no failures, but can omit a successful final relift when its subsequent descent check returns early. Those counters alone cannot localize the rejection before versus after that relift. The source-level reporting gap is corrected in `c82e68d`; the original counters alone remain ambiguous, and the replay below resolves the actual failure path. The q18 enthalpy-pressure energy/force virials are both approximately `0.0298894`; density-pressure entries are undefined. No equilibrium milestone is reached.
The final `c82e68d` replay passes all 30 provenance, trajectory, state, and report comparisons. The accepted-state file is bitwise identical; trial records and all non-timing Newton fields match exactly. The corrected diagnostic still records 20 auxiliary solves / 681 iterations, establishing that the failed enthalpy repair returned **before** another gravity relift. The nonzero repair counter includes the rejected proposal; it does not mean two repaired steps were accepted. This corrects the initial provisional interpretation that rejection followed a relift. The replay validates unchanged behavior and the location of this failure; it does not exercise a post-relift non-descent branch. The complete replay took `223.13 s`, with `150.20 s` in Newton and `122.98 s` of overlapping auxiliary work. Details and pinned source hashes are in `models_v3_direction/direction_regression_comparison.json`.
Both nonrotating n=1 controls took six full steps and required no relaxed tolerance. The eliminated run performed 107 inner gravity solves / 3,875 inner iterations, spending 702.21 seconds in those solves; the curvature control performed six solves / 115 iterations, spending 20.92 seconds there. Complete campaign times, including initialization and physical diagnostics, are 941.87 and 336.92 seconds respectively. Nested times overlap outer solve times. Elimination is a verified alternative formulation, but it is not currently a performance improvement for this control.
### What these experiments establish
These remain optional research strategies. Polynomial certification cheaply detects an obstruction that quadrature sampling can miss, but its anchor-based repair family can leave little decrease or fail the full-merit descent check. Gravity curvature correction removes the measured second-order remainder and improves a matched rotating first step. Neither result establishes that the complete coupled system will converge. The outer iteration caps identify a linear-solver/preconditioner problem to investigate; they do not by themselves isolate its cause.
Elimination has a verified Schur action and agrees with the converged control, but is currently expensive because of nested gravity solves. Completing gravity does not remove the pressure-preparation or retained-equation plateau in the harder unguarded run. No demonstrated tolerance mismatch justifies loosening the accuracy gates. Independent density admissibility and local discretization accuracy remain separate validation gaps. None of these J values has been mapped to a fraction of critical rotation, so this campaign makes no claim of reaching the 50% or 99% targets.
### Artifact locations and reproduction
The complete evidence is stored in [the task evidence directory](/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/numerical_strategies_2026-09-17). `frozen_v1` and `models_v1` preserve the earlier trials, including the intentional interruption; `tests_v2`, `frozen_v2`, and `models_v2` contain the earlier verified build's tests and campaigns. `models_v2_rotation` completes the rotating cases using that same immutable executable; `tests_v4` contains final regression results and `models_v3_direction` the final reporting replay. `endpoint_certificates_v1` preserves independent endpoint and negative-control results, including the explicit unavailable case. Each campaign retains an immutable executable and hashes. `DENSITY_VALIDATION_INTERPRETATION.md` records density provenance. `TOLERANCE_COUPLING_REVIEW.md` distinguishes the fixed inner tolerance from the outer full-Jacobian forcing gate; it is a risk analysis, not evidence that the observed models failed for that reason.
The committed production cases are in `experiments/numerical_strategy_cases_2026-09-17.json`. The original b21 campaign did not request per-iteration state snapshots; the final manifest enables the existing capture option at every attempted iteration to record the accepted base at each attempted iteration, including when that iteration later times out. This adds recording, not a numerical change. The immutable case manifest stored with each campaign remains the authority for reproducing that specific run. Run `experiments/run_plateau_campaign.py --help` for its clean-revision, fresh-output invocation, and use `experiments/check_plateau_physics.py` on every completed model. Frozen checks use `experiments/check_numerical_strategies.py`; their pass status is an algebraic result and is not an equilibrium acceptance criterion.

View File

@@ -0,0 +1,25 @@
# Polynomial enthalpy admissibility and feasible direction repair
This branch adds a sufficient polynomial nonnegativity certificate and an interchangeable enthalpy direction repair. It does not alter the EOS or declare a constrained residual minimum an equilibrium.
`TensorBernsteinPolynomial<Dimension>` encodes spatial dimension in its type and accepts polynomial order through the mesh's runtime nodal points. A cached one-dimensional Lagrange-to-Bernstein transformation is applied by tensor contractions. Every nontrivial arithmetic operation in the transformation and de Casteljau subdivision encloses its result using `nextafter`; a polynomial is certified only when all coefficient lower bounds in every leaf are nonnegative. The implementation assumes ordinary IEEE binary64 arithmetic, gradual underflow, and no unsafe fast-math transformations. The underlying mathematical FE is the Lagrange polynomial at the supplied floating-point nodal coordinates.
A negative control coefficient is not a negative polynomial witness. Such cells are refined. A negative upper interval bound at a tensor corner proves a negative polynomial value. Cells that remain ambiguous at the work budget return `unresolved`, including some truly nonnegative polynomials with tangential interior zeros. No negative tolerance is accepted as nonnegative. Exact endpoint interpolation preserves identically zero tensor faces without manufacturing a small negative error interval.
The production adapter supports conforming scalar nodal H1 hexahedra with closed Gauss-Lobatto, closed uniform, or closed Gauss-Legendre points. Unsupported element types are rejected explicitly. Its reduced field map and MFEM prolongation preserve shared true DOFs; no elementwise coefficient clipping occurs. The prepared object assumes the finite-element space and topology remain unchanged. Mesh adaptation requires a new object.
Given a certified base `h`, a certified anchor `a`, and proposed direction `p`, the repaired full candidate is `(1-beta)*(h+p)+beta*a`. Thus the altered enthalpy direction is `(1-beta)*p+beta*(a-h)`. Zero-trace reduced rows are fixed to zero. The adapter constructs a sufficient convex cone from a subdivision on which the anchor has nonnegative Bernstein bounds, and computes the largest required fraction across all coefficients and MPI ranks. This is the minimum sufficient fraction for those conservative coefficient inequalities, not the least fraction for the complete nonnegative polynomial set. A caller can choose any larger fraction through one, then verify the actual rounded full candidate. The original direction is left unchanged when verification fails.
This changes the enthalpy direction while allowing the stellar strategy to retain the other field directions. It is a feasible direction repair, not a constrained Newton optimizer. Full residual acceptance, actual descent checks, and the original physical convergence requirements remain necessary. Invalid or unresolved bases are rejected explicitly; this mechanism is not a feasibility-restoration solver. A certified checkpoint or initial seed is required as anchor. A frozen repaired full candidate and certified base define a nonnegative exact-arithmetic segment for backtracking; every floating-point candidate must nevertheless pass the same check.
Collective adapter calls must occur in the same order on all ranks. Sign status, polynomial bounds, and repair fraction are globally combined. Witness element indices, coordinates, and work counters remain rank-local. Unequal repair fractions and work budgets are rejected collectively.
Tests cover nodal-positive/interior-negative cubics, a positive polynomial with negative coarse Bernstein coefficients, exact zero faces, very small negative pockets, unresolved tangential zeros, arbitrary runtime degree, nonfinite input, finite-element ordering, true-DOF sharing, invalid bases, immutable failure output, and prescribed trace handling. The compiled production module passed serial tests and supported low-level two-rank tests. Full stellar MPI operation remains unvalidated because the existing logical radial surface interpolation is restricted to one rank.
`PreparedStellarEnthalpyStrategy<State>` resolves the enthalpy block from the compiled form type and captures the accepted physical enthalpy at the start of each `evaluate()` as its anchor. The anchor remains fixed during that evaluation. Every full-state check denormalizes the state; pointwise positivity is not invariant under a general diagonal Riesz normalization. The strategy minimizes the full normalized linear-residual norm over the sufficient one-dimensional repair interval, verifies the actual normalized root candidate after rounding, and rejects a non-descent result. Unrelated blocks of the normalized correction are retained bit for bit. It does not prepare an operator or change an accepted state. A valid unaltered full candidate costs one Jacobian action for its true merit slope; an altered direction costs three actions (family model plus the actual rounded chosen direction). The anchor's certificate is cached only when coefficients agree exactly on every rank.
A standalone extraction of the scalar/tensor certification engine was compiled with the system C++20 compiler and exercised before module integration. It certified a strictly positive quadratic with negative coarse coefficients and a three-dimensional zero-face bubble; it proved a negative pocket of depth 1e-10; it returned unresolved for an exact tangential zero. The subsequent integrated frozen probes certified the earlier rotating base, detected a negative full trial, and rejected the already-negative late rotating base with `invalid_base` while preserving accepted buffers. The n=1, J=0 polynomial-policy control converged and passed all eight virial checks; feasible repaired rotating candidates in the frozen probe did not pass full residual acceptance.
Arithmetic requirements are enforced at compilation: `__FAST_MATH__` and a positive `__FINITE_MATH_ONLY__` are rejected, and static assertions require IEC 559 binary64 with subnormal support. Runtime floating-point modes must retain gradual underflow; the application must not enable flush-to-zero after construction. The existing Release build was inspected: `-O3 -g -DNDEBUG -std=c++23 -flto=thin -arch arm64`; no unsafe floating-point flags were present in the generated build commands.
The stellar strategy explicitly supports only state-independent pressure-to-specific-enthalpy surface relations. That dependency is checked from the compiled relation type. Its constructor collectively rejects nonzero prescribed surface pressure with an unsupported-prescription error before checking seed coefficients, and verifies that the EOS's enthalpy reference satisfies h(P=0)=0. This prevents a valid positive-pressure model from being mislabeled an invalid numerical base. The focused regression validates zero pressure and collective rejection when only one MPI rank supplies positive pressure.

View File

@@ -0,0 +1,40 @@
# Prepared gravity-to-material preconditioner action
The stellar-structure gravity-to-material coupling used
`PreparedDisplacementResidualOperator::ApplyGravityGradientJacobianAction`, which
delegates to the standalone gravity-gradient force column. That column evaluates
the legacy geometry kernel during each application. The full stellar Jacobian
instead uses the already prepared complete gravity-force action, including its
cached tensor path.
The cross preconditioner now calls that same prepared gravity-force action with
zero density and displacement variations. These zero vectors are allocated and
initialized once with the cross operator. For a fixed prepared state,
\[
D F_{\mathrm{gravity\ force}}[0,0,\delta q]
= (D_q F_{\mathrm{gravity\ force}})\delta q.
\]
The existing domain-deformation adjoint then maps this mechanical action into the
shape row. Gravity-potential coupling into hydrostatic equilibrium and pressure
boundary-row replacement remain unchanged. Pressure and rotational complete
actions are not invoked: they have no gravity-gradient column.
This is a preconditioner execution-path change. It changes no equation,
quadrature selection, cross-block approximation, factorization policy, default,
or full Newton-Jacobian implementation. Prepared and legacy force evaluations
may differ by floating-point evaluation order; numerical equality is tested with
the existing `2e-12` scaled norm criterion.
The material-to-gravity cross action already uses the same prepared gravity
Jacobian as the full stellar operator and is unchanged. This patch does not
optimize other material/surface policies or standalone partial-column APIs.
The existing stellar-structure FEM integration test now compares three dense
gravity directions against both the legacy partial-column calculation and the
restricted full Jacobian, checking surface and enthalpy rows separately. It
repeats after density and shape changes, checks repeated application after full-J
scratch use, and verifies that these applications do not reprepare the force.
The tests are supplied for the coordinated build; no timing improvement is
claimed before measurement on the frozen benchmark state.

View File

@@ -0,0 +1,392 @@
# Preconditioner improvement: frozen systems and nonlinear checks
This experiment changes preconditioning only. The physical equations,
complete Newton Jacobian construction, normalization rules, mesh, and linear
acceptance gate are unchanged. Within each frozen comparison, the numerical
Jacobian, right-hand side, and normalization factors are held fixed; nonlinear
runs rebuild them along their respective trajectories. The date in branch
and artifact names is an experiment identifier; provenance files contain the
actual UTC execution times.
The strongest equal-accuracy timing result is a 1.39548x frozen linear solve
speedup for n = 1.5, J = 0. The combined material/gravity inverse also passes
a saved rotating system that the default cannot solve within 600 iterations.
Neither result establishes convergence of the hard nonlinear models. The
easy n = 1, J = 0 physical regression retains all virial errors below 3.74e-7,
but takes approximately 4% longer with the stronger inverse.
## Reproduction and scope
Integration branch: `research/preconditioner-benchmarks-20260918`, based on
`10adf7e`. Hypotheses are retained separately on
`research/gravity-consistent-schur-20260918`,
`research/preconditioner-cached-cross-actions-20260918`, and
`research/coupled-shape-coarse-20260918`.
The experiment workspace is
`/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d`.
Evidence is stored under `diagnostics/preconditioner_improvement_2026-09-18`
in that workspace. Each campaign retains its clean source commit, build
configuration, copied executable and hash, mesh hash, exact commands,
input/output hashes, and logs. Runs are serial, without overlapping builds or
FEM jobs during timing.
Frozen comparisons start FGMRES from zero on the same saved state and
right-hand side. Each role constructs a fresh inverse, including its own
specification border responses. The restart length is 160, the initial cap is
200 iterations, and the required relative full-J true defect is 0.03. The
independently applied full Jacobian decides acceptance; the Krylov recurrence
flag alone does not. All accepted/trial state buffers, normalization factors,
preparation generation, and a deterministic full-J probe must remain
unchanged.
Costs include inverse construction, normalized binding, Krylov setup, Krylov
solve, and full-J verification. Extra diagnostic applications and artifact I/O
are recorded separately. A speedup to convergence is reported only if both
methods meet the same true gate. Less work spent on a failed solve is not a
time-to-convergence improvement. A frozen linear pass is not nonlinear or
physical convergence.
## Existing two-way coupling: negative controls
`screen_v1` uses source `018fc1c`, before the cached cross-action
optimization.
| Saved state | Inverse | Iterations | Full-J relative defect | Complete verified cost (s) |
|---|---|---:|---:|---:|
| n = 1.5, J = 0 plateau | independent | 200 | 0.0590170471860 | 87.9302 |
| same | stellar LDU | 200 | 0.0600668598825 | 599.5473 |
| n = 1, J = 0.1 plateau | independent | 200 | 0.0826534298794 | 86.9409 |
| same | stellar LDU | 200 | 0.0720550396371 | 594.2053 |
All four solves fail the 0.03 gate. Stellar LDU incurs 6.82–6.83 times the
total cost; it slightly worsens the n = 1.5 result and reduces the rotating
defect by 12.82%. Mean inverse application time rises from approximately 0.19
s to 2.7 s, while full-J actions remain approximately 0.23 s. The uncached
gravity-to-material force column explains the application-cost anomaly.
Poisson contributes 95.53% of the squared n = 1.5 baseline defect and 98.28%
with stellar LDU. For the rotating state those fractions are 85.00% and
98.10%; LDU reduces the gradient-row norm by 94.16% but the Poisson norm by
only 6.35%. These are global normalized block diagnostics, not proof of an
exclusively exterior error. No exterior weighting is changed.
The independent artifact audit passes 65 provenance checks and 93 checks per
case. Both saved states and the normalization data exactly match their
producer artifacts. The two independent baselines reproduce the earlier failed
solves.
## Candidate mechanisms
1. **Prepared cross action.** Reuse the complete prepared gravity force with
zero density and displacement directions to apply its gravity-gradient
column. This is the same mathematical coupling with cached geometry; it does
not strengthen the inverse. See `PRECONDITIONER_CACHED_CROSS_ACTION_2026-09-18.md`.
2. **Consistent gravity Schur refinement.** Keep the existing AMG action, but
apply a fixed number of corrections against `B R B^T`, where `R` is the same
mass inverse used in flux recovery. Fixed work preserves linear stationarity
for stationary child inverses. Damping does not guarantee contraction; it
must earn its additional cost. See `GRAVITY_CONSISTENT_SCHUR_2026-09-18.md`.
3. **Experimental coupled shape coarse inverse.** Use nine fixed geometric
modes, complete their material/gravity responses, and construct a checked
low-rank correction to the normalized inverse. Modes do not depend on the
Newton right-hand side or previous Krylov results. A rank/overlap guard
explicitly falls back to the underlying inverse when the correction cannot
be trusted. Coarse setup and storage are counted, and actual FEM subspace
identities are independently checked before solving.
## First candidate screen
`candidates_v1` uses source `dc8d4b0` and the same n = 1.5, J = 0 plateau
state. Every fresh independent control reproduces relative defect
0.059017047186 at 200 iterations. Complete control costs remain between 87.53
and 88.25 s.
| Candidate | Iterations | Full-J relative defect | Gate | Complete verified cost (s) |
|---|---:|---:|---|---:|
| Cached stellar LDU | 200 | 0.0600668598779 | fail | 117.4845 |
| Consistent gravity Schur, k = 1, omega = 0.5 | 132 | 0.0292091549685 | pass | 72.3981 |
| Cached stellar LDU + consistent gravity Schur | 121 | 0.0285619160766 | pass | 84.7104 |
| Nine-mode coupled shape coarse correction | 200 | 0.0668657989082 | fail | 97.0564 |
At the same iteration cap, the cached LDU reduces total execution time by a
factor of 5.1032 relative to the old path, while mean inverse application time
drops by a factor of 8.0425. This is an execution improvement, not a
convergence improvement. Saved inputs and the full-J probe agree exactly; the
final normalized correction changes by only 2.7051e-11 relatively. Both LDU
solves fail, and the cached version remains 34.2% more expensive than the
independent control on this state.
Gravity refinement is the first candidate to cross the original gate. It
lowers the Poisson-row defect by 55.4% and the gradient-row defect by 15.0%.
The squared Poisson share drops from 95.53% to 77.59%; surface and hydrostatic
defects grow, so the improvement is judged by the verified global norm. Work
changes from 400 to 396 mass-inverse applications, 200 to 264 AMG Schur
applications, and 200 to 132 outer inverse applications. At this iteration
cap, the default does not pass the same gate, so dividing its failed 88 s
attempt by 72.4 s is not a convergence speedup. The combined LDU saves another
eleven iterations relative to gravity refinement alone but takes 17% more time
overall.
The coarse candidate has all nine modes active, minimum overlap lower bound
0.79465, and no fallback. Its extra construction costs 8.6012 s, including
mode completion and eighteen setup Jacobian applications; it stores 28,491,680
bytes in persistent vectors. The actual FEM subspace check passes.
Nevertheless, its 200-iteration defect worsens by 13.3%. This is a negative
numerical result for these modes on this state, not evidence about every
possible coarse space or rapidly rotating model. The prototype remains
confined to experiments.
## Validation status
The integrated library and experiment driver compile with the repository's
Release/ThinLTO configuration. Source `dc8d4b0` passes 20 focused serial test
cases (441,978 assertions), including FEM equivalence, geometry/discretization
refresh, fixed-work algebra, and coarse inverse tests. Distributed unit and
coarse tests pass on two ranks (13 cases and 213 assertions per rank).
The broad real-FEM MPI run aborts because the existing METIS partition gives
one rank no compactified vacuum element, which the mapped mass constructor
requires. The failing log is retained; this campaign does not claim
distributed FEM Schur validation. See the gravity refinement note for the
exact scope and evidence.
The evidence checker passes 22 lightweight tests. Independent reviews of the
cached LDU and gravity-only cases validate provenance, state/operator
invariants, true gates, and child-work accounting. Reviews are stored outside
immutable campaign directories.
Source `fcb7833` adds owning experiment-only Newton recipes through the
existing ADL preparation interface. They use the same concrete prepared
inverses as the frozen benchmark and the existing context refresh/border
lifecycle. The driver supports default, gravity-Schur, stellar-LDU, and
combined stellar-LDU/gravity-Schur recipes for ordinary Newton, positivity,
curvature, and positivity-curvature runs. The combined Newton recipe was
added at `7b4f674`; the driver builds successfully at `5298d88`. This adds no
public physics-facing solver API.
## Equal-accuracy confirmation
`confirmation_v1` uses source `87569c0`, a restart length of 160, and a
maximum of 600 iterations for both roles. The target remains a freshly
verified relative defect of 0.03.
| State | Inverse | Iterations | Full-J relative defect | Gate | Complete verified cost (s) |
|---|---|---:|---:|---|---:|
| n = 1.5, J = 0 plateau | independent | 231 | 0.0290033752814 | pass | 100.9943 |
| same | gravity Schur k = 1, omega = 0.5 | 132 | 0.0292091549685 | pass | 72.3727 |
| n = 1, J = 0.1 plateau | independent | 600 | 0.0739197073237 | fail | 257.9399 |
| same | gravity Schur k = 1, omega = 0.5 | 600 | 0.0408505998829 | fail | 321.5918 |
For n = 1.5, the frozen linear solve speedup to the same requested accuracy is
**1.39548x**, with 28.34% less complete cost and 42.86% fewer iterations. The
candidate repeats its earlier 132 iterations, with timing close to the earlier
72.3981 s. Both endpoints finish slightly below the same stopping threshold;
neither tolerance nor the full-J check was relaxed.
Rotation behaves differently. Refinement reduces the 600-step defect by
44.74%, but costs 24.68% more and still fails the gate. The remaining gradient
and Poisson defects contribute 0.02664 and 0.03018 to the global relative
norm. The older rotating LDU control reduced the gradient contribution to
0.001813 while leaving a large Poisson contribution. This supports one
complementary LDU+Schur follow-up; it neither proves a gradient floor nor
permits multiplying the separate gains.
All 73 provenance checks and 186 case checks pass. The reproducible figure and
plotting provenance are in `confirmation_v1_figures`; reported Krylov
histories are shown separately from independently verified final points.
Plotting used an existing compatible Python environment and installed no
dependencies.
## Easy nonlinear and physical regression
The first two `newton_v1` cases use source `bed1893`, the same n = 1, J = 0
model with no central-density constraint, positivity strategy, and identical
tolerances. Both converge in six accepted full steps, with no repairs or
rejections. Initial physical diagnostics and layout are byte-identical; all
linear true gates pass.
| Measure | Independent | Gravity Schur k = 1, omega = 0.5 |
|---|---:|---:|
| Total linear iterations | 307 | 258 |
| Summed Newton iteration time (s) | 191.068 | 199.375 |
| Summed linear solve time (s) | 125.035 | 132.028 |
| Complete diagnostic-run wall time (s) | 251.720 | 261.285 |
| Final nonlinear residual | 1.65157e-13 | 1.05839e-13 |
Both final residuals are below the shared 1.81187e-12 nonlinear target. Fewer
iterations do not produce an easy-case speedup: Newton time rises by 4.35% and
full run time by 3.80%. The full run includes physical validation and artifact
I/O; it is not presented as pure solver cost.
All eight virial errors (four definitions at quadrature orders 14 and 18) lie
between 2.61811e-7 and 3.73092e-7 for both models, comfortably below 1e-5. The
maximum endpoint coefficient difference is 2.679e-11; the radius difference is
3.48e-14. The independent paired audit also checks mass, sampled
density/enthalpy admissibility and local EOS metrics. At quadrature order 18,
the density EOS mismatch, scaled by the sampled maximum density, has RMS
8.5654e-5 and maximum 4.2355e-4. The small virial error therefore does not
establish pointwise accuracy to 1e-5 or spatial mesh convergence. This
preserves the existing physical regression; it does not add independent
ESTER validation.
## Higher-index nonlinear follow-through
The n = 1.5, J = 0 curvature case uses the same initial physical state, layout,
mesh, normalization, and stopping settings as the historical independent
preconditioner run. Gravity refinement completes all twelve permitted Newton
steps, with all twelve independently checked linear defects below 0.03. The
historical run stopped after six accepted steps because its next linear solve
failed. The new run therefore removes that immediate linear obstruction.
It does not establish nonlinear convergence. The final residual is
1.3966991e-5 against a target of 2.7365922e-12, only 6.13% below the historical
endpoint. After the first full step, accepted step lengths are mostly 1/16 or
1/32; the final two are 1/64 and 1/512. All nineteen rejected trials fail the
residual-decrease test. All 31 auxiliary gravity solves pass. This evidence
points to the remaining nonlinear step obstruction, rather than another
failed outer or auxiliary gravity solve.
The run spends 415.038 s in outer linear solves and 590.003 s in preparation,
including 178.937 s in auxiliary gravity solves. Summed Newton time is
1075.368 s and complete diagnostic-run wall time is 1138.002 s. These are
costs of an unconverged trajectory, not a nonlinear speedup.
The enthalpy-pressure energy and force virials pass 1e-5, with quadrature-18
errors 4.06909e-6 and 2.57118e-6. Density-pressure virials remain undefined:
the sampled density minimum is -8.14767e-4, with 9600 negative samples and
negative mass fraction 2.89597e-5. Negative density also occurred in the
historical case. Sampled enthalpy stays positive, but this curvature-only run
does not provide a global polynomial positivity certificate. Thus the virial
numbers alone do not make this an acceptable physical model. The independent
audit records these failures separately from successful linear solves and
artifact verification.
## Rotating nonlinear follow-through
The n = 1, J = 0.1 positivity-curvature run accepts one full trial step after
a positivity repair modifies its search direction. Its first raw linear
solve passes in thirteen iterations with relative true defect 0.023583;
that defect does not certify the subsequently repaired direction. The second
reaches 200 iterations with defect 0.0315391 and fails the unchanged 0.03 gate,
before a second trial can be tested. There are no line-search rejections. This case
therefore retains a linear obstruction as well as an unconverged nonlinear
state.
The final nonlinear residual is 0.00896796 against a target of 8.58812e-10.
Summed Newton time is 139.198 s, including 113.338 s in outer linear solves
and 18.544 s in preparation; full diagnostic-run wall time is 201.245 s.
Enthalpy-pressure virials are approximately 0.0108 and fail the physical
milestone. Density-pressure virials are undefined, with sampled density
minimum -0.00692627 and 2015 negative samples at quadrature order 18. The
enthalpy positivity policy passes its checks, but does not establish density
admissibility.
The historical rotating run starts from matching physical diagnostics and
uses matching physics and linear controls, but permits eight Newton steps
instead of twelve. Its endpoint is not used for a controlled timing claim.
All 67 full-campaign provenance checks pass; physical and solver failures are
retained as experimental outcomes, not treated as successful convergence.
## Complementary rotating coupling
`rotation_coupling_v1`, built from `5298d88`, combines cached stellar LDU with
one consistent gravity Schur correction at relaxation 0.5. On the saved
rotating plateau state it passes the unchanged 0.03 gate in 142 iterations,
with relative true defect 0.0299068971 and complete verified cost 96.8236 s.
Its fresh independent control reproduces the original 200-iteration defect
0.0826534298794 and costs 85.8991 s. The earlier independent control still
failed at 600 iterations, so there is no measured finite baseline
time-to-convergence with which to form a speedup ratio.
The independent audit verifies byte-identical saved states, right-hand side,
normalization factors, layout, and deterministic Jacobian probe against the
earlier rotating campaigns. Its fresh baseline correction and exact residual
also match the original 200-iteration control byte for byte. The combination
reduces the Poisson defect norm by 63.33% and the gradient defect norm by
94.47%. Surface and hydrostatic defects increase; acceptance still uses the
complete norm. Mean inverse application cost rises from 0.18409 to 0.43046 s,
so iteration reduction alone must not be presented as an application speedup.
This combination succeeds where either isolated change failed on this frozen
rotating problem. The follow-through in `rotation_newton_v1`, source
`83afd82`, demonstrates the limit of that result. With the historical
eight-step budget and otherwise matching controls, its first raw linear
solve passes in twelve iterations at relative true defect 0.0171651. A
positivity repair changes the search direction; the accepted full trial
reduces the nonlinear residual from 0.0858812 to 0.00685562. At this new state,
the next linear solve reaches 200 iterations with defect 0.0339685 and fails.
There is no second trial and no nonlinear convergence.
Summed Newton time is 172.396 s, including 141.631 s in outer linear solves;
full diagnostic-run wall time is 234.738 s. The quadrature-18 enthalpy-pressure
energy and force virial errors are 0.00712711 and 0.00709672. Both fail 1e-5.
Density-pressure virials are undefined, with 1975 negative density samples
and negative mass fraction 4.04801e-5. The successful frozen linear solve
therefore does not certify a physically acceptable rotating solution, or
even passage through every linear system along a new Newton trajectory.
The historical independent endpoint has a larger nonlinear residual,
0.00840387, but a smaller enthalpy energy virial error, 0.000544539. Both
physical endpoints fail. This is direct evidence that improvement in the
normalized nonlinear residual need not improve virial balance along distinct
trajectories. The combined run passes all 38 current-case artifact checks and
32 historical-control checks, including matching initial diagnostics,
layout, physics and solver settings.
Production defaults remain unchanged: the stronger inverse is an optional
typed policy, and the coarse candidate remains an experiment.
Here J = 0.1 denotes the angular-momentum input, not a measured fraction of
critical rotation. This campaign establishes neither a 50% nor a 99% critical
rotating equilibrium.
## Integration decision and reproducibility
Keep the prepared cross-action optimization: it preserves the mathematical
action and removes the demonstrated cost of rebuilding geometry inside the
two-way stellar inverse. Keep consistent gravity Schur refinement as an
optional typed policy. The measured setting is one sweep at relaxation 0.5;
use it alone for the tested n = 1.5 state and combine it with stellar LDU for
the tested rotating state. These are measured choices for these states, not
universal parameter recommendations. The nine-mode coarse prototype has not
earned promotion, and no production default is changed.
The production policy and cross-action files, with their tests, match their
isolated hypothesis branches. Changes are committed on the integration
branch; the original working checkout and its unrelated quadrature formatting
edit are preserved. No central-density constraint or physics-facing API
requirement was added.
The retained campaign source revisions and tracked recipes are:
| Evidence directory | Source | Recipe in `experiments/` |
|---|---|---|
| `screen_v1` | `018fc1c` | `preconditioner_screen_cases_2026-09-18.json` |
| `candidates_v1` | `dc8d4b0` | `preconditioner_candidates_2026-09-18.json` |
| `confirmation_v1` | `87569c0` | `preconditioner_confirmation_2026-09-18.json` |
| `newton_v1` | `bed1893` | `preconditioner_newton_cases_2026-09-18.json` |
| `rotation_coupling_v1` | `5298d88` | `preconditioner_rotation_coupling_2026-09-18.json` |
| `rotation_newton_v1` | `83afd82` | `preconditioner_rotation_newton_2026-09-18.json` |
Use `run_plateau_campaign.py` with the selected recipe, a build configured
from the recorded `provenance.json`, and a fresh output directory. It requires
a clean committed source tree, checks the build's source directory, copies
the executable before running cases, records hashes, and refuses to overwrite
an earlier campaign. The exact build and execution commands are retained in
each campaign. The mesh is versioned as `sandbox.smesh`; saved-state input
paths and hashes identify the earlier producer artifacts.
For frozen campaigns, `check_preconditioner_benchmark.py` independently checks
the artifacts. Place its `--output` outside the campaign directory to retain
the original evidence unchanged. The Newton audits and their source scripts
are retained alongside the campaigns, with solver and physical failures
reported separately from artifact-integrity checks. Six lightweight audit
tests cover failed solves, raw versus repaired directions, incorrect policy
labels, hash failures, incomplete producers, and unmatched Newton budgets.
The final comparison figure, script, and input hashes are in
`final_comparison_figures/` under the evidence directory. It shows reported
Krylov histories and independently verified endpoints separately, includes
setup and verification cost, and labels the unequal rotating iteration caps
and failed controls explicitly.

View File

@@ -0,0 +1,378 @@
# Pressure-preparation obstruction and shape curvature — September 17, 2026
The rotating plateau has a demonstrated local enthalpy-positivity obstruction:
the same interior polynomial sample approaches zero, while the surface trace
remains exactly zero. The late accepted polynomial is already negative between
production quadrature points. Separately, the n=1.5 full step is admissible but
nonlinear shape/field curvature raises its residual to 12.24 times the base.
The measured small-step behavior supports second-order curvature rather than a
first-order Jacobian defect along these directions. No production solver fix
or additional virial-qualified model is claimed.
## Scope and controlled source
This campaign adds experiment-only diagnostics to the preserved combined solver
at `95d9fba`. It changes no production operator, admissibility rule, normalization,
preconditioner, solver policy, or physics-facing API. The central-density
constraint remains optional. The working campaign branch is
`research/diagnostic-campaign-20260917`; pressure and shape helpers are retained
on separate hypothesis branches:
| Purpose | Branch | Retained revision |
|---|---|---|
| Preserved combined solver | `research/combined-20260916` | `95d9fba` |
| Pressure and surface diagnostic helper | `research/pressure-obstruction-20260917` | `c6572d3` |
| Shape/field diagnostic helper | `research/shape-curvature-20260917` | `b24e6e0` |
| Integrated captures and focused probes | `research/diagnostic-campaign-20260917` | tested `fd08f7b`, `9e1b65d`, `4280c53` |
The primary checkout remains on the diagnostic campaign branch. `main` remains
at `75cc638`. Existing untracked files were preserved. Source additions in this
campaign are confined to `experiments/`.
The capture executable records source `fd08f7b`. It copies observer spans without
calling the prepared operator during Newton. A first-trial direction is
reconstructed from candidate minus base divided by alpha; the exact candidate
is also saved. A zero candidate-reconstruction error does not prove recovery of
every bit of the original internal correction. Roundoff estimates and direct
candidate replay distinguish that limitation from the original rejection.
Raw artifacts, copied executables, manifests, input/output hashes and analysis
are retained under:
`/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/pressure_shape_2026-09-17`.
## Trajectory fidelity
The full twelve-attempt n=1, J=0.1 replay exactly reproduces every non-timing
Newton column, every trial and block record, the initial/final physical CSVs,
layout, and accepted-state bytes from the September 16 combined run. Its
accepted-state SHA-256 is
`ba55e7295c05f0c9ac5f32490f74d87556502d1744aa42deb7964729b2be2018`.
The n=1.5 replay reproduces the first three guarded attempts exactly, including
all ten trials and all 42 block records. There is no archived three-step endpoint
for an independent final-state comparison with that shortened run.
Seven selected iterations save finite 178073-entry vectors. Independently
reconstructing each candidate gives zero componentwise round-trip error. The
late n=1 capture nevertheless has a direction-roundoff scale estimate of
1.40534e-8, about 4.88e-7 of its direction norm, because its first trial alpha is
1.90735e-6. The onset capture uses alpha=1 and has an estimate of 2.68e-14.
Exact candidate replay remains authoritative for the historical rejection.
## Pressure-preparation diagnosis
The exact saved first candidates from iterations 2, 3, 4, 7 and 11 all reproduce
`thermodynamic_domain / pressure_force / outside_domain` (enum values 2 / 6 / 5).
The production pressure source reaches this branch for finite negative enthalpy.
These are enthalpy-domain failures rather than inverted geometry. No new Krylov
solve is involved in the frozen replays.
All iteration labels below are zero-based. Physical quantities use the model
units M=R_reference=G=1; h values below are not normalized residual entries. The pressure limiter stays at local
stellar element 459, pressure quadrature point 50; the closure limiter is point
36 of its different production rule on the same element.
| Iteration | Pressure-point h | Direction dh there | Pressure alpha bound | Closure alpha bound | Live accepted alpha |
|---:|---:|---:|---:|---:|---:|
| 2 | 9.63674e-4 | -1.31441e-2 | 7.33159e-2 | 7.27489e-2 | 6.25e-2 |
| 3 | 1.42165e-4 | -2.11119e-3 | 6.73390e-2 | 7.15585e-2 | 6.25e-2 |
| 4 | 1.02159e-5 | -1.89704e-3 | 5.38520e-3 | 1.01581e-2 | 3.90625e-3 |
| 7 | 7.04574e-8 | -1.86569e-3 | 3.77648e-5 | 4.90600e-3 | 3.05176e-5 |
| 11 | 1.07227e-9 | -1.86493e-3 | 5.74963e-7 | 4.87083e-3 | 4.76837e-7 |
The pressure step budget falls by **127,514 times**. These are physical enthalpy
values and corrections evaluated with unchanged normalization at the same
production points. For consecutive captured states, the next h
agrees with `h + accepted_alpha * dh` to 2.01e-18. At the late state, the closure
bound is about 8,472 times looser than the pressure bound. The shrinking pressure
h explains the vanishing admissible steps along these measured directions; it
does not yet explain why the computed directions keep decreasing h there.
The element touches the stellar surface. Its limiting pressure point has
reference Cartesian radius 0.997553 and lies near the negative rotation pole
(about 8.66 degrees from the negative z axis at onset). This is an interior
quadrature point in a surface-adjacent element, not a surface boundary row.
Topology establishes adjacency, not distance to the deformed surface.
Both onset and late probes bracket the production enthalpy bound with 0.99 and
1.01 times that bound. Enthalpy-only steps reproduce the crossing rejection;
shape-only steps prepare successfully. Across the two 19-trial grids, no
geometry rejection occurs. Affine limiting-point h predictions agree with
independent point evaluations within 1.05e-17. Preparation success alone does
not imply merit acceptance.
At onset the closure bound is slightly tighter. The original large candidate
crosses both bounds, and pressure is prepared first, so its rejection stage
cannot identify the tighter family. The supplemental candidate at
alpha=0.07303236911639208 lies strictly between the two bounds. Its predicted
closure h is -5.01979e-6 while the limiting pressure h remains +3.72619e-6.
The production replay confirms that sequence: pressure preparation passes and
closure preparation rejects with `thermodynamic_domain / barotropic_closure /
outside_domain` (2 / 3 / 5). This distinguishes the first reported failure stage
from the tightest sampled bound.
The supplemental trace inspection uses the actual compiled surface carrier map.
All **866 surface enthalpy coefficients and directions are exactly zero** at
onset and late plateau. The exported indices also establish exact zero surface
enthalpy in all five captured physical bases and their five exact first-trial
candidates. Their contributions to h and dh at both limiting interior points
are exactly zero. The surface condition exists and is satisfied here; boundary
leakage does not explain this wall.
The limiting element is cubic, with 64 enthalpy FE nodes. At onset, a step of
1.01 times the sampled union bound leaves all 64 nodal h values nonnegative,
while closure and pressure interior samples have h=-1.28819e-5 and -2.11e-6,
respectively. At the late state, **even the full unit step leaves all nodes
nonnegative**, but h at the pressure limiting point is -1.86493e-3. This
establishes interior polynomial undershoot along these corrections. Nodal
positivity or exact zero surface trace is insufficient to prevent it. It does
not establish an interpolation implementation bug. The onset full unit step
also makes five nodes negative, so that larger step must not be described as
an exclusively between-node failure.
A final offline check reconstructs the two local tensor-Q3 polynomials from
those 64 physical FE nodal values. It reproduces all nodal values exactly and
both production limiting-point h/dh values within 6.94e-18. The same interior
sampling grid has 495,264 points per inspected state, including uniform spacing
1/64 and logarithmic distances from 1e-12 to 1e-1 from the zero-trace z=0 face.
| Local polynomial state | Minimum sampled h | Reference-element location | Interpretation |
|---|---:|---|---|
| Onset base | positive on this grid | — | No negativity detected; not a positivity certificate |
| Onset accepted alpha=0.0625 | positive on this grid | — | Same limited conclusion |
| Onset alpha=0.99 times production bound | -2.36406e-5 | (0.0130467, 0.515625, 0.01) | Negative between production samples |
| Late captured base | **-2.87114e-5** | (0.0130467, 0.515625, 0.01) | Existing pointwise violation before the next step |
The late base has 2,401 negative samples on that grid. This conclusion uses only
the captured base polynomial and is independent of direction-reconstruction
roundoff. A separate line evaluation at the pressure point's x,y coordinates
and reference z=0.005 gives h=-1.54933e-5. An independent 60-digit Decimal
reconstruction gives -1.5493345386780819e-5 at that point; its input hashes,
formula and production-point checks are retained in
`tensor_q3_independent_check.json`. The negative magnitudes are many orders
above interpolation-check discrepancies. They prove the existence of negative
values in this element; the sampled minimum is not a certified global minimum.
For the onset direction, the finer sampled step bound is 0.0665364 versus the
production union bound 0.0727489. For the late base, a positivity-preserving step
bound from an everywhere-admissible base cannot be asserted because the base
already has negative h. **Passing production quadrature preparation currently
does not ensure internal pointwise enthalpy positivity.** The inspected late
state is nonconverged and already fails the virial milestone; this finding does
not assert that the previously converged nonrotating/low-J controls share the
same defect. No new quadrature or EOS rule was installed.
## Shape and field curvature
Let p be the captured correction, p_s its actual surface-deformation block,
and p_f all remaining fields and scalars. The diagnostic prepares the same
frozen base before every Jacobian action and measures
`R_d(alpha) = F(x + alpha*p_d) - F(x) - alpha*J*p_d`.
The mixed component is the vector `R_full - R_shape - R_fields`, formed before
any norm. Each case uses six common alphas separated by decades; the largest
is capped by geometry and both enthalpy rules so all three directions can be
compared at the same step. Directions are not renormalized separately.
| Frozen case | Common alpha | ‖Ftrial‖/‖F0‖ | ‖L‖/‖F0‖ | ‖R‖ / alpha² | Gravity fraction of ‖R‖² |
|---|---:|---:|---:|---:|---:|
| n=1, J=0.1, iteration 2 | 0.058199106 | 0.94307844 | 0.94180757 | 0.062255721 | 99.8390% |
| n=1.5, J=0, iteration 1 | 1 | 12.243161 | 0.02576812 | 0.0021890295 | 99.7747% |
| n=3 constrained seed | 0.12194828 | 1.0237652 | 0.87826014 | 0.11177311 | 90.7812% |
For n=1.5 at iteration 1, the exact first candidate is preparation-admissible,
with positive minimum Jacobian 0.896116. Its residual norm reproduces the original
merit-rejected trial within 1.43e-17. The full-step linear prediction would leave
only 2.5768% of the starting residual, whereas the actual trial has **12.243 times**
the starting residual. At alpha=0.1, the actual ratio is still 1.02052 versus the
linear prediction 0.900070; at 0.01 it falls to 0.991209. This directly measures
curvature-driven merit rejection separately from the rotating enthalpy wall.
At this n=1.5 base, gravity-gradient shape and field action norms are 0.115959
and 0.116055, with cosine -0.999999831; their combined action norm is only
1.16990e-4. Poisson actions likewise nearly cancel (cosine -0.999996055).
Truncating just the shape block would destroy this measured first-order
cancellation. A full-step second-order remainder of 2.18903e-3 survives, with
99.7747% of its squared norm in the two gravity residual blocks.
The remainder divided by alpha squared stabilizes as alpha decreases, while
resolved gravity remainder slopes approach two. With shape held fixed, gravity
is affine in its other fields in the source, and the measured fields-only gravity
remainders remain at arithmetic scale. The n=1.5 maximum is 2.96e-14, 1.042 times
the diagnostic's heuristic floor; the strict below-floor flag is therefore false,
but that floor is not a certified assembly-error bound. This slight excess is
not evidence of nonlinear fixed-shape gravity. The smallest steps that reach the
arithmetic floor are excluded from slope claims.
| Frozen case | 2⟨L,R_shape⟩ | 2⟨L,R_fields⟩ | 2⟨L,R_mixed⟩ | ‖R_full‖² | Total curvature cost |
|---|---:|---:|---:|---:|---:|
| n=1, J=0.1, iteration 2 | -1.952454e-08 | -3.042692e-10 | 9.736527e-08 | 4.446556e-08 | 1.220020e-07 |
| n=1.5, J=0, iteration 1 | -7.601828e-10 | 1.587389e-12 | 1.185527e-09 | 4.791850e-06 | 4.792277e-06 |
| n=3 constrained seed | 1.458147e-09 | -9.452314e-08 | -9.285962e-09 | 2.762978e-06 | 2.660627e-06 |
Here `L = F0 + alpha*Jp` and the exact scalar identity is
`||Ftrial||² = ||L||² + 2<L,Rfull> + ||Rfull||²`.
The three signed projection terms add to `2<L,Rfull>`; the last squared term
contains cross terms between remainder components. Positive values worsen the
linear squared-merit prediction. At the n=1.5 full step, the dominant cost is
the squared remainder itself, not the small signed projections onto the nearly
zero linear prediction. At alpha=0.1, both shape and mixed projections are adverse.
At the admissible rotating onset step, curvature modestly worsens the prediction
but still allows residual decrease; its larger historical steps instead fail
enthalpy preparation.
These observations support genuine nonlinear shape/field curvature along the
measured directions, with no detected first-order Jacobian inconsistency there.
They do not certify every Jacobian column. The gravity-block aggregates include
both stellar and exterior domains and do not establish where the nonlinear
remainder originates. No physical importance is assigned to exterior accuracy
beyond its influence on the interior solution.
The n=3 seed retains its explicit central-density constraint. Its saved
restart-160 correction has true relative linear defect 0.0402590212946322,
exactly matching the earlier failed linear solve and exceeding the 0.03 gate.
No new solve was substituted. At the common cap the trial residual is 2.3765%
above the base despite a predicted 12.174% decrease. The mixed component is large,
but its signed projection is favorable; the positive squared-remainder term
outweighs all favorable projections. At one tenth the cap, the residual decreases
and net curvature slightly improves the linear prediction. This prevents a
blanket attribution of every failed step to an adverse mixed projection.
## Consequences and next experiments
The two mechanisms should be tested and treated separately.
1. **Pressure/closure feasibility.** A production-rule enthalpy step cap would
avoid known inadmissible trials. It would not, by itself, remove a wall where
the same h tends to zero while dh stays negative: the existing accepted steps
are already 72.5–92.8% of the sampled union bound. The next discriminating
numerical experiment is a tighter frozen linear solve, with local h-direction
and component defects measured explicitly, to test how strongly the local
direction depends on linear accuracy. A
persistent negative direction would still permit nonlinear-path or basin
effects; it would not prove that no admissible discrete root exists.
Preserve EOS admissibility and use quadrature/interior polynomial checks when
testing a positivity representation or constrained step; clipping nodal values
cannot prevent the demonstrated between-node undershoot. Test interior
polynomial positivity at accepted states as a separate validation check.
Increasing quadrature coverage can detect the violation earlier, but detection
alone is not a convergence remedy. A trial starting from the late base also
needs feasibility restoration if positivity is to be maintained everywhere.
Clipping h would
change the equations and would not establish internal correctness.
2. **Shape/field nonlinear balance.** Test a trial-only gravity completion at
fixed candidate shape and density, solving the linear mixed-gravity subsystem
there before reevaluating every coupled residual. Gravity completion changes the trial path and reduces the gravity defect by
construction. The test is whether that produces a better coupled trial,
interior solution and virial after every residual is reevaluated.
It is a hypothesis, not an implemented production change; other residuals,
pointwise interior checks and virial must all be measured. Shape-only damping
is poorly motivated by the strong first-order cancellation in these cases.
3. **Where the merit is spent.** Before changing normalization or exterior
weighting, partition the dominant gravity remainder by stellar/exterior
contribution and measure its effect on interior hydrostatic balance. These
whole-block probes do not justify demanding exterior accuracy for its own
sake, nor do they justify dropping exterior residuals that influence the star.
The present data do not single out preconditioner failure for the rotating or
n=1.5 captured steps: their current true linear defects still satisfy the 0.03
forcing gate. That gate is a global norm criterion, not proof that the local
enthalpy direction is adequate near a vanishing h. The n=3 frozen correction
fails that gate and is reported separately. No production preconditioner,
normalization, EOS admissibility or line-search rule has been altered here.
## Verification and reproducibility limits
The driver was built in Release with Homebrew Clang 22.1.8, IPO enabled,
profiling disabled and uniform polynomial order increment zero. Runs were
serial, on one MPI rank, using the same 1216-hex mesh (832 stellar, 384 vacuum)
and the unchanged production quadrature rules. Mesh SHA-256:
`ce11ae99e21e6c3bbfbee402acd2e191c1da0d8261d2227b4203f73f2f337a74`.
Case manifests and copied immutable executables retain the tested sources even
while the experiment branch acquires later diagnostic additions. Performance
was not compared in this campaign.
Two instrumented trajectory runs reached their requested iteration caps
(expected model exit 3). All eight focused cases and both supplemental cases
completed successfully (exit 0), with matching binary and input/output hashes.
The n=1.5 rejected-candidate residual norms agree with their historical values
to 1.43e-17 and 1.84e-18; the two norm implementations have different reduction
orders, so those numbers are roundoff comparisons rather than byte comparisons.
All captured base residual vectors reproduce exactly.
All ten frozen cases restore their final base residual exactly. Each shape case
has 22 admissible preparation events, for 66 total; all accepted normalized
states, physical states and residuals are unchanged. Direction partitions are
exact. The largest Jacobian partition error is 8.33e-17. Aggregate signed-merit
and projection identities agree to better than 6.8e-15 relative. All 38 pressure
crossing trials have complete, unique records and no geometry rejection.
Independent audits check vector copies, quadrature-bound identity, CSV coverage,
all surface coefficient statistics and nodal identities.
Implicit neighboring capture state/residual inputs are covered by the capture
output hashes as well as independent checks; the runner's explicit-input hashes
alone do not cover that auxiliary-read path. Late reconstructed directions retain
the subtraction-roundoff limitation documented above. The late recomputed true
linear defect differs from its historical value by 2.25e-9, while both remain
below 0.03; exact-candidate replay is independent of that reconstruction.
No production/library or public-header code changed relative to `95d9fba`;
the existing production C++ suite was not rerun for these experiment-only
changes. Validation instead includes compilation of the diagnostic executables,
exact trajectory comparisons, production candidate replays, independently
recomputed CSV identities, input/output hashes, and frozen-state restoration.
A zero diagnostic process exit means the observations completed. It does not
mean a stellar equilibrium converged.
This campaign establishes no additional virial-qualified model. The captured
rotating endpoint is exactly the previous nonconverged endpoint: its P(h)-based
virial errors remain approximately 4.75e-4 and 8.18e-4, above the required 1e-5.
The n=1.5 capture is intentionally only a three-step prefix; its eventual
convergence and pointwise accuracy are not inferred from these probes. J=0.1
is an angular-momentum input, not 10% of critical rotation. Critical-rotation
fractions were not computed.
## Reproduction and retained analyses
The three case manifests are `plateau_capture_cases_2026-09-17.json`,
`plateau_focused_cases_2026-09-17.json`, and
`plateau_supplemental_cases_2026-09-17.json` in `experiments/`. Their tested source
commits are respectively `fd08f7b`, `9e1b65d`, and `4280c53`. Each artifact folder
contains `provenance.json`, exact per-case commands, case input/output hashes,
logs and the copied executable. The midpoint candidate also retains a derivation
record and SHA-256. No raw state files or binary build products are committed.
Run a new numerical campaign with a compatible configured build and a fresh
output directory:
```sh
python3 experiments/run_plateau_campaign.py \
--source . --build cmake-build-release-homebrew --mesh sandbox.smesh \
--cases experiments/plateau_focused_cases_2026-09-17.json \
--cmake /Applications/CLion.app/Contents/bin/cmake/mac/aarch64/bin/cmake \
--jobs 8 --output /absolute/path/to/new-results
```
Use the corresponding tested source checkout for exact source reproduction.
The supplied case manifests reference the retained absolute capture paths;
relocating artifacts requires changing those paths consistently. The runner
checks committed source, rebuilds, records provenance and refuses reused output
directories. Replaying the copied executables with the recorded arguments and a
new output path is another way to retain the exact tested binary.
The portable analysis scripts under `experiments/plateau_analysis/` take the
artifact root containing `captures/`, `focused/`, and `supplemental/`:
```sh
python3 experiments/plateau_analysis/analyze_pressure.py /absolute/path/to/artifact-root
python3 experiments/plateau_analysis/analyze_shape.py --campaign /absolute/path/to/artifact-root
python3 experiments/plateau_analysis/audit_focused_outputs.py /absolute/path/to/artifact-root
python3 experiments/plateau_analysis/audit_surface_outputs.py /absolute/path/to/artifact-root
python3 experiments/plateau_analysis/sample_pressure_polynomial.py /absolute/path/to/artifact-root
```
They do not run the solver or alter raw case data. They regenerate compact
Markdown/JSON analyses alongside those data. See `pressure_analysis.md`,
`shape_analysis.md`, `pressure_polynomial_analysis.md`, `capture_validation.md`,
and `focused_method_validation.md`
in the retained artifact root for the detailed per-case checks.

View File

@@ -0,0 +1,82 @@
# Frozen pressure-obstruction diagnostic
`plateau_pressure_obstruction_diagnostics.hpp` exports the experiment-only helper
`experiment::plateau_diagnostics::ProbePressureObstruction(state, fem, n, normalizedBase, normalizedDirection, output)`.
Include it after `import mean_field` and call it inside the existing context
diagnostics guard. The output directory must exist and its four
`pressure_obstruction_*.csv` files must not already exist. The helper is limited
to one MPI rank and the current registered polytropic field orders. No public
configuration, model equation, solver acceptance rule, or accepted state changes.
The caller supplies an owned or borrowed frozen normalized state and correction;
the helper copies both before mutating workspaces. It restores the frozen state
before each candidate, and restores that state, inverse freshness, and the
caller's correction on return. It never calls `CommitPreparedTrial` or changes
accepted coefficients. The outer `WithState` guard remains responsible for
restoring the context's actual accepted state when a loaded frozen state differs
from it. Fatal restoration errors are propagated instead of silently claiming a
clean context.
## Bound and location
The existing `MeasureEnthalpyStep` scans the exact production pressure-force and
barotropic-closure quadrature rules. For scalar pullbacks, sampled enthalpy along
a fixed direction obeys `h_q(alpha) = h_q(0) + alpha * dh_q`. Each family reports
its smallest `-h/dh` for negative `dh`, and their minimum is the union bound.
Zero means that a sampled zero-enthalpy point is decreasing; infinity means no
sampled upper bound. Neither means that all other preparation checks pass.
`pressure_obstruction_summary.csv` retains the complete existing scan, including
point counts, negative samples, both limiting points and both bounds.
`pressure_obstruction_limits.csv` adds the limiting element's Cartesian reference
and frozen physical positions. Element-local integration coordinates are recorded
separately. The exact topological flag `element_touches_stellar_surface` locates
the element relative to the tagged stellar/vacuum interface. It is not a physical
distance or a certificate that the failure occurs at the boundary. Radii are
measured about the coordinate origin and are not normalized by a critical radius.
The scanner uses a pointwise polynomial contraction; optimized production may
use tensor contractions. These sample the same polynomial but need not agree
bitwise. Trials avoid alpha equal to the bound. Full-direction factors are
0.5, 0.9, 0.99, 1.01, 1.1, and 2 times the union bound, plus distinct fixed
steps 1, 1/2, 1/4, 1/8, and 1/16. Fixed steps coincident with the boundary are
omitted. The helper also tests enthalpy-only and shape-only components at the
same factors 0.9, 0.99, 1.01, and 1.1, retaining their original amplitudes.
This is at most 19 candidate preparations plus frozen-state restorations. For a
zero or infinite bound, a smaller fixed grid replaces the relative-bound grid.
## Exact rejection and interpretation
`pressure_obstruction_trials.csv` records the full root preparation reason and
stage enums, an explicit reason name, the EOS error enum, and whether that EOS
code is applicable. Nonthermodynamic failures can carry a default EOS code;
do not interpret it without the applicability flag. Missing determinant data
remain NaN. Successful preparation records normalized and physical residual
norms, with normalized residual blocks in `pressure_obstruction_blocks.csv`.
The physical whole-vector norm combines units and is for reproduction, not a
physical acceptance metric. The helper does not run the line-search merit test.
For this production pressure operator, `thermodynamic_domain` at the pressure
stage identifies a finite sampled negative enthalpy; `inverted_geometry`
identifies the mapping's nonpositive-determinant/weight branch. Other mapping
statuses and nonfinite input/results have separate reasons. Thus the exact
failure payload resolves the ambiguity of the earlier observer's generic
`inadmissible_state` plus `pressure force` label. The recorded reason identifies
the selected preparation failure, not necessarily every defect in the candidate.
Both predicted and independently re-evaluated enthalpy at the two frozen limiting
points are saved for every candidate. This is not a rescan for the most negative
trial point: the most negative point need not be the earliest-crossing point.
If full and enthalpy-only trials cross the same pressure thermodynamic boundary
while shape-only remains admissible, that isolates the enthalpy obstruction from
shape geometry along this correction. It does not establish the spatial cause
of the Newton direction or suggest permitting negative enthalpy.
If the caller reconstructs the correction from a recorded trial as
`(candidate - base) / alpha`, cancellation at tiny alpha can perturb the direction
and bound. Preserve that provenance and replay the original candidate directly
as an independent control. This helper diagnoses only its supplied direction.
Implementation review only: no compilation or numerical runs have been performed
for this helper at the time of this note. Root integration and validation remain
pending.

View File

@@ -0,0 +1,175 @@
# One-hour reduced smooth surface study — 2026-09-18
Outcome: independent smooth surface parameters remove the immediate full-step obstruction and reduce cold linear solve times by 2–5 times in this screen. They do not remove the original shape-force imbalance. A three-step seed chain reaches P(h) virial errors below 7e-7 while retaining substantial excluded force and imperfect interior fields.
Authorized wall-clock window: 19:30:15–20:30:15 UTC. Branch:
research/reduced-smooth-surface-20260918, parent 6ceda61.
Keep Q3 displacement/surface, Q4 reference geometry, Q2 DG density/potential,
Q3 enthalpy and RT2 gravity. No central-density constraint. n=1.5,J=0.
No production API, operator or extension change. Single MPI rank.
Frozen affine embedding q=q0+B a. The base q0 is never projected. Construct
real spherical harmonics through degree L at actual surface radial nodes;
orthonormalize the Q3 interpolants using q14 prepared physical surface area.
Thin QR of S B and R^-1 B supplies separate normalized state and dual test
maps. Solve Qf^T Jnormalized Qx p=-Qf^T Fnormalized. The projected full inverse
Qx^T Mnormalized^-1 Qf is an approximation, not an exact reduced inverse.
All other unknowns/equations remain active. Cold FGMRES, eta=.03, max200,
restart160, same gravity-Schur preconditioner (one sweep, relaxation.5).
Priority: fresh full-space direction at the prior Q3 six-update endpoint,
then L4 there, then L2 and L8 (L6 optional); analytic-seed L4 only if time
permits. Stop launching FEM cases by20:20; reserve remaining time for independent
artifact audit and reporting. No convergence claim from frozen steps. Cases,
builds, and full numerical audits run serially. A library-only Q3 warm rebuild
may overlap editing experiment-only headers; no production source changes.
Raw independent trial alphas 1,1/4,1/16,1/1024. Preserve original and reduced
residuals, separate linear gates, full/reduced slopes, excluded shape forces,
and exact restoration checks. Observational merit criterion is
norm(Ftrial)<=(1-1e-4 alpha)*norm(Fbase), evaluated separately in both spaces.
No trial accepted, no SOC, no positivity repair. q14/q18 physical measurements
at base and the first/largest prepared trial only; all trial residuals saved.
Direction physical observer q10/q14 reused from the preceding audited study.
Acceptance of an observation requires algebra/transpose/full-rank control tests,
true reduced gate classification, finite vectors, source/input/output hashes,
and exact saved-state restoration. Reduced success is not full success.
Virial1e-5, interior physical errors, density sign, and omitted force remain
separate measurements. No selected norm reduction can certify a physical root.
## Implementation
Experiment-only headers:
- `reduced_surface_basis.hpp`: scalar radial-amplitude FE trace basis and
quadrature-defined physical surface mass metric, explicit rank/orthogonality
checks, and raw data for independent verification.
- `reduced_surface_operators.hpp`: two separate QR maps, reduced operator,
projected flexible preconditioner and deterministic algebra checks.
- `reduced_surface_diagnostics.hpp`: frozen solve, both original/reduced gates,
excluded-force decomposition, raw trials and restoration invariants.
- `audit_reduced_surface.py`: independent artifact algebra and corruption tests.
For physical state factors S and residual factors R, the shape maps obey
S B = Qx Tx, R^-1 B = Qf Tf,
Qf^T (R Fphysical) = Tf^-T B^T Fphysical.
The separate state/test QR maps therefore preserve physical dual pairing despite nonuniform normalization and distinct shape row/value offsets. The area whitening measures scalar radial amplitude, not the norm of the generated three-dimensional displacement. The latter is measured separately over the stellar volume. Changing the area whitening changes coordinates without changing the raw harmonic span.
The diagnostic executable adds experiment-only flags --reduced-surface-probe
and --surface-degree (0 means full-space control); no production-facing API is
modified. Degrees are runtime experimental choices while operator/inverse
compatibility and the inherited preconditioner application contract remain
compile-time constrained. Actual mesh dimensions and normalization factors are
necessarily checked at runtime. Existing physical observers are reused.
Evidence root: `../../diagnostics/reduced_surface_2026-09-18` relative to this
checkout. The preceding study remains on its two committed research branches.
## Results: late-state comparison
At the common six-update n=1.5, J=0 Q3 endpoint, the normalized original residual is 1.4971971e-5. The unrestricted control reproduces the previous fresh direction. Its unit trial is rejected at pressure preparation (thermodynamic domain); alpha=1/4 and 1/16 prepare but increase the original norm. Only alpha=1/1024 passes among the sampled values. Intermediate steps were not tested.
| Shape space | Independent parameters | Krylov iterations | Cold solve seconds | Original relative linear defect | Reduced relative linear defect | Original residual after unit trial |
|---|---:|---:|---:|---:|---:|---:|
| Full Q3 trace | 866 | 61 | 32.184 | 0.02767 | 0.02767 | Pressure preparation rejected |
| L2 harmonics | 9 | 12 | 6.447 | 0.15121 | 0.01719 | 2.263903e-6 |
| L4 harmonics | 25 | 21 | 11.249 | 0.16187 | 0.01608 | 2.432960e-6 |
| L8 harmonics | 81 | 29 | 15.745 | 0.19207 | 0.01409 | 2.964119e-6 |
All reduced directions pass their independent 3% linear gate, and all four trial alphas prepare and decrease both norms. None of the reduced directions passes the original full Newton gate. Original unit-step residual decreases are 84.88%, 83.75%, and 80.20%. Thus the benefit is measurable in the original residual, but it comes from solving a restricted set of shape equations. These directions do not meet the requested 3% accuracy for the original Newton system; they could be interpreted as much looser inexact full-system steps.
These are one-shot cold linear solve timings, not end-to-end Newton timings or repeated performance statistics. The remaining non-shape unknowns and equations stay active: full dimension 178073, L4 dimension 177232. The full operator and full inverse are still applied inside the reduced wrappers. The dimension change is less than 0.5%; fewer Krylov iterations provide most of the measured speedup.
### Curvature and physical motion
| Shape space | Volume displacement direction L2 norm (q14) | Unit-trial original Taylor remainder |
|---|---:|---:|
| Full | 3.96028e-3 | Inadmissible; alpha=1/4 remainder1.85956e-4 |
| L2 | 4.86622e-7 | 1.84872e-10 |
| L4 | 9.14977e-5 | 2.21090e-7 |
| L8 | 1.46119e-4 | 7.19540e-7 |
L4 cuts physical displacement motion by 43.28 times relative to the full direction. L2 is nearly a field-only relaxation; admitting higher harmonics introduces substantially more compensated shape/field motion and nonlinear curvature. The degree dependence is not monotone improvement of a physical solution. This supports the approximation-space compatibility hypothesis without proving that every omitted mode is unphysical or identifying a continuum gauge.
After the L4 unit trial, excluded shape forces account for 98.38% of the remaining original squared residual. A single trial does not establish a new residual floor. Because q0 is retained, this late-state test also retains its existing roughly 1.1% nodal radius spread; restricting subsequent increments cannot remove the general fine-scale part of that inherited geometry.
### Physical measurements
The table below compares the common base with unit trials, all using independent q18 evaluation. Pressure is evaluated through enthalpy, P(h). These energy- and force-based virial diagnostics must not be confused with the density-pressure diagnostic, which remains undefined where the interpolated density is negative.
| Measurement | Base | L2 unit | L4 unit | L8 unit |
|---|---:|---:|---:|---:|
| P(h) energy virial error | 4.22590e-6 | 8.66263e-7 | 8.11913e-7 | 8.15910e-7 |
| P(h) force virial error | 2.71367e-6 | 5.94930e-7 | 6.41398e-7 | 6.24187e-7 |
| Mass error relative to 1 | 3.41685e-6 | 8.81237e-10 | 2.39038e-8 | 5.67517e-8 |
| EOS density mismatch RMS | 1.82986e-4 | 1.82925e-4 | 1.82990e-4 | 1.83010e-4 |
| Hydrostatic gradient RMS | 1.06811e-2 | 1.06631e-2 | 1.07065e-2 | 1.06864e-2 |
| Minimum sampled density | -7.73185e-4 | -7.24527e-4 | -7.27628e-4 | -7.33640e-4 |
| Negative-density mass fraction | 2.89683e-5 | 2.89242e-5 | 2.89458e-5 | 2.89452e-5 |
Both P(h) virial balances are comfortably below 1e-5. Their q14-to-q18 differences are about 1.83e-9. Local EOS and hydrostatic errors remain essentially unchanged; the negative density has not been repaired. Negative-density mass estimates are quadrature-sensitive (about 2.23e-5 at q14 versus2.89e-5 at q18), so their magnitude is diagnostic rather than a precision estimate. All quoted gradient errors are the existing interior observers in code units, including the broken DG-potential gradient comparison where applicable.
The full-control physical.csv sample is alpha=1/4, its first prepared trial, which fails the norm screen. It is not a selected full-space update and must not be compared as an equivalent accepted unit step.
## Seed continuation
The planned analytic-seed L4 probe was followed by two externally replayed physical unit candidates, an adaptive extension recorded before launching the chain. Each predecessor passed preparation, the reduced independent linear gate, and both conservative norm-decrease screens. All three observed unit trials satisfy the same conditions. This is a cold-solve experimental reduced-Newton chain, not the production accepted/warm trajectory. The first physical shape is retained, and each subsequent base is its preceding saved candidate.
| Unit steps from seed | Original norm | Retained norm | Excluded shape norm | P(h) energy virial q18 | Hydrostatic gradient RMS q18 | Nodal radius spread / mean |
|---|---:|---:|---:|---:|---:|---:|
| 0 | 2.736592e-4 | 2.590732e-4 | 8.815010e-5 | 2.410694e-5 | 1.528098e-3 | 0.003424% |
| 1 | 8.624827e-5 | 9.387845e-6 | 8.573583e-5 | 2.180785e-6 | 5.724618e-3 | 0.081116% |
| 2 | 8.473526e-5 | 3.147803e-6 | 8.467677e-5 | 8.660498e-7 | 7.177698e-3 | 0.152605% |
| 3 | 8.465191e-5 | 7.357283e-8 | 8.465188e-5 | 6.769653e-7 | 7.255981e-3 | 0.154699% |
The retained norm falls by about 3521 times. The original norm falls by only 3.23 times overall; after the first step, improvements are 1.75% and 0.0984%. At the final trial, excluded shape force accounts for 99.999924% of the original squared norm. These three updates show a pronounced separation between progress in the retained equations and the remaining force; they do not establish an asymptotic residual floor or convergence of the retained problem to arbitrary tolerance.
Linear solves take 18/20/18 iterations and 10.574/11.341/9.594 seconds. Reduced relative defects are 2.940%, 2.122%, 2.323%; original relative defects are 31.45%, 98.18%, 99.90%. All full-system 3% gates fail.
The final P(h) force virial is 5.769064e-7, mass error 3.79142e-9, sampled minimum density -4.07472e-4, and negative-density mass fraction 2.89249e-5. EOS density mismatch RMS scaled improves from 1.72399e-4 at seed to 1.25532e-4, but the hydrostatic-gradient error grows 4.75 times. Radius spread includes the reference geometry's initial interpolation error; this nodal statistic is not a full surface norm. The restricted chain produces much less shape distortion than the older unrestricted six-update state, but does not eliminate nonrotating drift or establish pointwise correctness.
This is the decisive limitation of a permanently truncated surface space: good virial balance and a small retained norm coexist with substantial original shape force and imperfect interior fields. The late-state trial benefits from fine-scale balance already developed by the unrestricted trajectory. Smooth parameters relieve the immediate curvature/step obstruction; they do not by themselves establish a compatible approximation of all original equations.
![Original and retained residual observations](../../../diagnostics/reduced_surface_2026-09-18/reduced_surface_results.png)
## Interpretation and next design
The evidence supports separating independent surface parameters from the interpolation used to carry volume displacement. An internal typed discretization prescription can select a nested smooth surface space while preserving the physics-facing API. State injection, physical dual restriction, normalization, and excluded-force monitoring should be distinct interfaces. A reduced inverse can initially wrap the existing full inverse; later optimizations should preserve the same contracts.
A fixed small harmonic space is not yet justified for production. It changes which shape forces are enforced, and smaller reduced residuals do not certify the full equations. The next controlled study should test whether the excluded mechanical imbalance decreases under mesh or field enrichment at a spherical state, while measuring interior EOS/hydrostatic error. That can distinguish approximation error from an inconsistent force/operator coupling before a low-degree space is promoted to production. Degree and mesh sensitivity, the pressure/EOS representation, and compatibility of the volume extension with global radial dilation remain separate questions. This study makes no rotation or n>1.5 convergence claim and changes no production field order or volume lift.
## Verification and reproducibility
Implementation commit 21cdbda22486e408adc52b65b25413f9380c7c30, on research/reduced-smooth-surface-20260918, parent 6ceda61. The diagnostic includes 19 C++ algebra checks (maximum error 2.22e-16) and 22 independent Python algebra/corruption tests. Actual-case audits independently reconstruct the raw nodal harmonics, quadrature-defined scalar trace Gram matrix, both QR maps, physical dual identity, full/reduced defects and norm decomposition, all trial remainder/norm classifications, and exact saved-state restoration. Individual artifact audits do not independently reimplement the FEM physics observers.
The observation flags use norm(Ftrial)<=(1-1e-4 alpha)norm(Fbase). This is a deliberately conservative norm-decrease screen, stricter than the production baseline squared-merit criterion, not an exact replay of production AcceptStep. Physical measurements cover the base and the first prepared trial only. No probe commits a production accepted state, and no SOC or positivity repair is enabled.
All builds, FEM cases and large artifact audits were serial. Raw commands, mesh/input/output and executable hashes, compiler settings, runtime and CPU details are in each campaign provenance and run JSON. The source checkout stays on the isolated branch; the original checkout and its pre-existing edits are untouched. Full regression tests were not rerun because production sources are unchanged; verification is scoped to the new diagnostic contracts, actual cases and snapshot chain.
All seven case audits pass: 2,098 saved-artifact checks in total. The snapshot-chain audit passes 107 checks with all three individual reviews bound. Both physical-state and residual handoffs are bitwise identical; normalized-state round trips differ by at most 1.39e-17 per entry. Layout, state/residual factors and raw harmonic basis hashes match exactly. Shape-base increments remain in the original raw span to relative errors below 9.4e-16. Twelve small chain-auditor tests include corruption and JSON-serialization regressions.
The chain auditor initially failed while serializing a NumPy boolean; it also emitted warnings during its small BLAS matrix product. The checker was corrected to emit native JSON scalar types and use an explicitly checked elementwise contraction with finite-value guards. The corrected audit passes without warnings. No FEM state, recorded observation, producer binary or numerical source changed in response to this checker issue.
### Archived campaigns
Evidence directory (relative to the source checkout):
../../diagnostics/reduced_surface_2026-09-18/
| Campaign | Cases | Case audit |
|---|---|---|
| core_v1 | late_full_control, late_L4 | core_audit_v1.json |
| orders_v1 | late_L2, late_L8 | order_audit_v1.json |
| seed_v1 | seed_L4 | seed_audit_v1.json |
| seed_chain_v1 | seed_L4_step2 | seed_step2_audit_v1.json |
| seed_chain_v2 | seed_L4_step3 | seed_step3_audit_v1.json |
seed_chain_audit_v1.json binds the three seed stages. TEST_PLAN.md records the original scope and the conditional extension. late_summary.json and seed_summary.json collect the displayed values. plot_results.py regenerates the figure from the immutable case CSVs. COMPLETED_STUDY.json records final source and evidence hashes.
To reproduce, build plateau_diagnostic from producer commit 21cdbda using the compiler/MFEM configuration in core_v1/provenance.json. Replay each recorded run command, substituting a fresh output directory. All cases use the same saved sandbox.smesh and one MPI rank. Late cases bind the prior Q3 accepted_state.txt by hash. Replay the seed stages in order using physical_candidate_a0 from the previous stage; the case manifests and input-state hashes specify these links. The runner requires a clean tracked source checkout and records the executable and all case output hashes.
No order changes were made during this study. Optional L6, rotational models, higher indices, mesh/enrichment sweeps and production integration were outside this bounded experiment. All seven FEM probes finished by 20:09:58 UTC, before the 20:20 launch cutoff and 20:30:15 study deadline.

View File

@@ -0,0 +1,352 @@
# Shape–field weak response investigation — 2026-09-18
## Prespecified scope
Follow up the large, nearly cancelling shape/field Newton direction for n=1.5,
J=0 without a central-density constraint. This study distinguishes within-element
physical field transport from surface variation and tests the specific hypothesis
that the Q3 displacement/Q4 reference geometry mismatch contributes to weak
response. Cancellation by itself is not evidence of a gauge or bad element orders.
The baseline branch is `research/shape-field-weak-response-20260918`, based on
`db854c0f7cdf5137e377273499f0ac5b6053b752`. The isolated order variant is
`research/shape-field-displacement-q4-20260918`. Preserve original checkout,
immutable executables, source revisions, mesh/input hashes and serial run records.
## Observation and controls
The diagnostic prepares a frozen state with fixed normalization, independently
verifies its full-J linear defect, saves every value-block Jacobian contribution,
and checks restoration of accepted buffers and operator action. Three small raw
Taylor trials test the same original operator. Physical observations use independent
grid functions and the prepared displacement; no accepted state is modified.
At common quadrature orders 10 and 14, record physical scalar pullback changes,
transport `grad(f).v`, and Eulerian changes `delta f - grad(f).v`. Density and
potential gradients are broken/local: facet jumps and RT Piola variations are not
included, so these observations cannot certify a pure relabelling nullspace.
Surface radial parameters are unweighted nodal samples. An independent affine
identity projection checks ambient displacement representation, separately from
the actual r-squared radial extension. Small-span SVDs describe only the sampled
block directions, never the full Jacobian rank.
Baseline frozen cases: the recorded n=1.5 seed and late directions at eta=0.03,
and a fresh cold solve at the six-update coupled endpoint. Then a fresh six-update
baseline with gravity-Schur inverse, gravity-curvature globalization, restart 160,
maximum 200 Krylov iterations, eta=0.03, and a fresh final direction. Match this
live run with the Q4 variant from the same analytic seed, including a Q4 seed
probe. Cases, builds and expensive audits run serially. A failed linear gate or
preparation remains a failure; do not silently relax controls.
## Order intervention (conditional on baseline observation)
Only change `Displacement::vectorOrder` from `3 + uniform increment` to
`4 + uniform increment` on the variant branch; keep uniform increment zero.
The loaded reference geometry remains Q4, density/potential L2 Q2, gravity RT
index 2, and enthalpy H1 Q3. The shared displacement collection means the scalar
surface trace also becomes Q4. This introduces shape modes and changes derived
quadrature orders and cost; it is not a pure interpolation-error intervention.
Document exact source line, date, rationale, DOFs, and compiled quadrature changes.
Use a separate build directory and new analytic seeds: existing coefficient
snapshots cannot be transferred unchanged between orders.
## Decision criteria
Compare verified linear accuracy, accepted step lengths, within-variant growth
of weak-direction indicators, common physical norms, virials, positivity/EOS
metrics and elapsed cost. Across orders, coefficient norms and discrete residuals
are not physical error measures. Q10/Q14 agreement diagnoses integration
sensitivity, not convergence certification. Virial <=1e-5 remains required but
cannot replace internal pointwise checks. Six updates are a bounded mechanistic
comparison, not evidence of high-n/high-rotation convergence.
## Results
The baseline branch retains Q3 displacement. The separate Q4 branch is an
isolated numerical experiment, not a recommendation to change the default.
### Reproducible baseline
Evidence root: `../../diagnostics/shape_field_weak_response_2026-09-18` relative
to this checkout. Frozen probes `baseline_probes_v1` use source `d79db94`; the
six-update control `q3_live_v1` uses `2c4a5e0`. Both include immutable binaries,
mesh/input hashes, commands, clean-source provenance, and independent elapsed
and CPU clocks. All full-J linear gates passed. Independent audits
`baseline_probes_audit_v2.json` and `q3_live_audit_v1.json` pass; accepted buffers,
factors and restored actions agree exactly. Q3 curved/tensor/geometry regression:
5 cases, 21,368 assertions passed.
The first checker version omitted the new cache-preservation invariant from its
schema. Version 2 requires it. A small finite synthetic matrix reproduced
NumPy/Accelerate matmul warnings; direct finite-checked contractions avoid that
backend path, without changing tolerances. Raw FEM artifacts remain unchanged.
The artifact checker passes 38 tiny algebra/corruption fixtures. The angular
analyzer independently checks its degree-8 recurrence, orthogonality, cubic
symmetries, rank, and file binding on analytic fixtures.
| Observation | Seed | Old late state (12 updates) | Fresh control (6 updates) | Coupled endpoint (6 updates) |
|---|---:|---:|---:|---:|
| Normalized residual | 2.73659e-4 | 1.39670e-5 | 1.49720e-5 | 1.24583e-5 |
| Sampled block-span minimum singular response | 5.80574e-2 | 1.43543e-4 | 8.16558e-4 | 6.94894e-4 |
| Sampled surface radius span / nodal mean | 3.42403e-5 | 1.24122e-2 | 1.09849e-2 | 1.11125e-2 |
The largest sampled singular response remains approximately 22.1–22.6. The SVD
uses the six nonzero disjoint value-block pieces of each p, normalized by their
coefficient norms. The direction-dependent subspace changes between observations;
the comparison combines changes in the operator and the probe subspace. It is
not a full-J spectrum or rank test. In particular,
comparing the 12-step late state with six-step endpoints does not demonstrate a
causal benefit of the coupled correction: the matched six-step control has a
slightly stronger minimum response than the coupled endpoint.
Late q14 Eulerian/pullback change norm ratios are density 0.05769, enthalpy
0.18870, potential 0.01288, versus seed 0.3243, 0.3080, 0.1993. This is substantial
transport compensation but not physically invisible motion. Broken DG gradients
omit jumps. The maximum q10/q14 relative difference in the three original cases'
Eulerian squared integrals is 1.69e-5, an integration sensitivity observation.
The radius observations expose a validation gap: the old late state has nodal
radii 0.997674–1.010093, while its q18 P(h)-based virial error is 4.06909e-6.
The fresh six-step control has q18 virial error 4.22590e-6 and reproduces the old
six-step residual trajectory. Its sampled hydrostatic-gradient RMS increases
from 0.00152810 to 0.0106811 despite the lower residual and virial error.
Neither is converged or physically certified;
negative density samples remain. Virial success can coexist with appreciable
nonrotating surface asphericity at these unfinished states.
`q3_surface_modes_v1.json` contains unweighted fits, not surface-integral power.
The 12-step late direction is 99.9995107% cubic-invariant in sampled squared
norm, but degree <=8 spherical harmonics leave 0.893679 of its nodal norm.
Degree <=2 leaves 0.981646. Thus most of the nodal direction is unresolved by
degree <=8 fits and is nearly cubic-invariant. This is consistent with
mesh/discretization coupling, without identifying its source: cubic symmetry
also exists in the bulk and gravity discretizations. These are not surface-area
spectra or evidence that the surface discretization alone causes the problem.
The affine control on the actual stellar mesh gives Q3 relative value error
9.01277e-5 and gradient error 1.23472e-3. This warrants the isolated Q4 comparison,
but adding surface modes could also worsen weak response.
### Structural interpretation and a rejected shortcut
At J=0, bulk Bernoulli rows are unweighted moments. Their direct shape derivative
at fixed reference-field coefficients is `integral(q * B * div(v))`; the EOS
shape column similarly contains its local closure imbalance. Thus pointwise
near-equilibrium shape information increasingly relies on gravity and mechanical
coupling. Small projected residuals alone do not prove small pointwise imbalance.
Current shape rows are the prescribed lift's transpose applied to volume force.
For regular surface h~s, density~s^n and pressure~s^(n+1), weakening near-surface
coupling as n increases is plausible. DG jumps and the independent RT field
prevent concluding exact discrete redundancy from the continuum identities.
Relevant assembly: `libmeanfield/impl/operators/prepared_hydrostatic_equilibrium.cpp`
(lines 864–911, 1354–1397), `operators/kernels/barotropic_closure_kernels.cpp`
(line 655), and `operators/prepared_stellar_equilibrium.cpp` (lines 806–811).
A naive replacement of mechanical shape rows by surface Bernoulli moments is
rank deficient at the desired pointwise B=0, J=0 root with the current trace
spaces. The actual closed stellar surface has 96 quads, 192 edges, 98 vertices.
Continuous surface Qp has 96*p*p+2 degrees of freedom; broken Q(p-1) potential
traces supply only 96*p*p. Q3 surface therefore has 866 rows versus 864 DG Q2
stellar trace coefficients, after eliminating enforced h=0 trace variations.
C adds no independent trace dimension; the direct shape measure term vanishes
with B. Surface-only Q4 widens this hypothetical deficit to 1538-864=674.
This concerns that proposed replacement, not a proven deficiency of the current
mechanical Jacobian. Any boundary formulation requires a compatible trace/test
space and explicit rank/stability analysis.
An invertible linear/tangent coordinate or preconditioner change preserves the
exact mapped physical Newton correction at a fixed state. It can improve
coordinate-dependent singular values and inexact linear solves. A nonlinear
coordinate map or retraction can also change finite trial curvature; none of
these observations alone removes weak physical response. Shape representation,
step control, and operator formulation remain distinct hypotheses.
### Q4 intervention
Applied 2026-09-18 at approximately 17:45 UTC on
`research/shape-field-displacement-q4-20260918`, branched from baseline `211be17`.
Changed `libmeanfield/interface/field/field_registry.cppm`,
`Displacement::vectorOrder`, from `3 + uniformPolynomialOrderIncrement` to
`4 + uniformPolynomialOrderIncrement`; configured uniform increment stays zero.
The dated source comment records the rationale. Eleven expectations and their
comments in six test files change to enforce the new displacement degree and
derived quadrature, while assertions for all other field orders stay fixed.
The purpose is to remove measured ambient affine representation error and test
its effect on the weak direction. The shared scalar surface increases from 866
to 1538 parameters, so this also adds shape modes. Derived pressure-force order
increases by one, gravity-force order by two, and geometry-inspection request
from 18 to 24, including the geometry-admissibility sampling; common physical
diagnostic quadratures remain 10/14 (weak-direction
observations) and 14/18 (state metrics). The surface metric, normalization and
preconditioner also change with their FE space. Equal relative linear tolerance
does not imply equal physical error or an identical line-search norm. The default
r-squared radial lift stays
unchanged and is not made globally affine by this ambient enrichment.
Use the separate `cmake-build-release-displacement-q4` directory with the same
LLVM 22.1.8, Release/IPO, MPI and library configuration. Rebuild all affected
modules and registered-space tests together. Q4 cases start from the analytic
seed; no coefficient snapshot is transferred between orders. The fixed
200-iteration linear budget and eta=0.03 remain unchanged. A 3600-second process
limit bounds each Q4 numerical case; no silent control relaxation is permitted.
### Completed Q3/Q4 comparison
Q4 source is `4be1a23c3ec2650af6a2a49528a8f5248cb001c3`. Its only production
change is the compile-time displacement degree at
`libmeanfield/interface/field/field_registry.cppm:163`; all instrumentation and
analysis remain in `experiments/`. No physics-facing API changed. Build and
dependency configuration values match the Q3 build. The Q4 regression campaign
passed 22 cases and 380,856 assertions: registry/quadrature contracts, field
spaces, curved geometry, surface/radial/domain Jacobians, Lane–Emden projection,
and prepared pressure/gravity force Jacobians. Cases, builds and full artifact
audits were serialized.
`q4_v1` contains the completed seed and live campaigns. The independent audit
`q4_audit_v1.json` passes 101,282 and 101,310 checks respectively, including raw
vector algebra, runner hashes, physical-integral identities, and exact buffer,
normalization, residual and Jacobian-action restoration. An artifact audit pass
does not turn a failed solve into a successful solve. The endpoint direction is
explicitly classified `finite_direction_failed_true_gate`.
The analytic seed has identical physical volume diagnostics in both variants.
Q4 reduces the ambient affine relative value error from 9.01277e-5 to
2.11629e-16 and gradient error from 1.23472e-3 to 3.24701e-15. Nevertheless,
the seed Newton direction's stellar displacement L2 grows from 0.00121967 to
0.0385749, a factor of 31.63. The seed linear solve grows from 26 to 67 iterations;
both meet the same independently checked eta=0.03 criterion. All three raw small
Q4 seed trials prepare and exhibit a quadratic residual remainder. This is not
evidence of a missing first-order derivative in the tested direction.
The fixed six-iteration-budget comparison gives:
| Measurement | Q3 displacement / surface | Q4 displacement / surface |
|---|---:|---:|
| Surface parameters | 866 | 1538 |
| Total root unknowns | 178073 | 178745 |
| Accepted updates | 6 | 3 |
| Termination | Nonlinear iteration limit | Fourth linear solve exhausted 200 iterations |
| First three accepted-step time | 269.31 s | 505.65 s |
| Residual after three updates / own initial residual | 0.056755 | 0.906188 |
| Final residual / own initial residual | 0.054710 | 0.906188 |
| All Newton-iteration time, including failed attempt | 547.34 s | 638.42 s |
| Outer Krylov iterations, including failed attempt | 354 | 492 |
| Endpoint probe time, excluded above | 93.07 s | 222.45 s |
| q18 P(h) potential-energy virial error | 4.22590e-6 | 8.89666e-5 |
| q18 P(h) force virial error | 2.71367e-6 | 8.27467e-6 |
| q18 mass error | 3.41685e-6 | 1.96178e-5 |
| q18 scaled EOS density mismatch RMS | 1.27948e-4 | 1.61156e-4 |
| q18 hydrostatic-gradient RMS | 0.0106811 | 0.325413 |
| q18 gravity versus broken potential-gradient RMS | 0.0121494 | 0.326881 |
| Negative density mass fraction | 2.89683e-5 | 4.19384e-5 |
These are differing stopped endpoints, not equal-accuracy or converged solutions.
The three-update comparison isolates the accepted-count difference in the table,
but all the previously listed order/space/quadrature/scaling confounders remain.
Iteration time excludes initialization, final physical measurements and the
diagnostic probe; total live-process times were 705.76 s and 944.98 s.
The stdlib helper `compare_shape_order_runs.py` binds the small comparison inputs
to runner hashes and reproduces `q3_q4_comparison_v1.json`.
Q3 accepts steps 1, 1/16, 1/16, 1/16, 1/32, 1/32. Q4 accepts approximately
0.1770, 0.04425, 0.04425. Its fourth linear solve and independently repeated cold
endpoint solve both stop after 200 iterations with relative full-J defect
0.0868564, above 0.03. The finite failed direction remains a directional
observation only. It is not used as an equally accurate Newton comparison.
Q4 also changes the observed physical character of the seed direction: the q14
Eulerian/pullback norm ratios for density, enthalpy and potential become
13.0825, 13.4289 and 13.2393. Thus the added deformation is not largely cancelled
by scalar transport, unlike the late Q3 direction. These are broken scalar
observations, not a complete distributional or RT transport analysis. The
largest q10/q14 relative change in Q4 endpoint Eulerian squared integrals is
4.35e-5; this is an integration sensitivity check, not discretization convergence.
`q4_surface_modes_v1.json` passes its independent angular analysis. At the stopped
Q4 endpoint, sampled radii span 0.927235–1.049839, or 12.2559% of their nodal
mean. The Q3 endpoint's observed span is 1.09849%. These are different nodal
sample sets, not common-point or full-surface extrema. In particular, zero
initial radius variation at Q4 nodes does not make the curved reference surface
an exact sphere: the same physical mesh sampled at Q3 nodes has a small nonzero
span. The Q4 seed direction's degree <=8 nodal fit leaves 0.982810 of its norm;
its sampled squared norm is 99.9999989% cubic-invariant. The corresponding failed
endpoint direction leaves 0.988475 of its norm. This remains fine angular
structure, without identifying which discretization component causes it.
The saved figure `surface_order_comparison_v2.png` uses a common color scale and
labels the different sample and accepted-update counts. Version 1 is retained
as an unused layout draft; version 2 fixes the caption/colorbar overlap.
### Conclusions and the next isolated hypotheses
**Do not promote the Q4-only change.** It repairs ambient affine representation
but worsens useful nonlinear progress, linear cost, interior gradient checks,
and potential-energy virial balance in this case. This rules out order matching
alone as a sufficient repair under the tested configuration. It does not show
that the Q3 representation error contributes nothing, nor that a compatible
enrichment of the other fields could not help.
The leading hypothesis is an unfavorable combination of surface freedom and
the resolving power of the coupled field equations. The observed directions
have strong fine angular structure, and adding surface freedom produced much
larger physical motion without useful residual reduction. Normalization and
preconditioning remain possible contributors; full-J residual accuracy does
not bound physical correction error for a weak operator. More Krylov work might
recover a linear solution, but the first three gate-passing Q4 directions already
gave poor accepted progress. No exact nullspace or discrete stability theorem
has been established for the present mechanical operator.
The next direct experiment should separate independent surface parameters from
ambient displacement interpolation. A fixed map `q=q0+B*a` with small smooth
bases of increasing degree can test this hypothesis around the same frozen
state. Inject physical variations and restrict the existing dual shape force
with `B^T`; the reduced blocks are the corresponding Galerkin restrictions.
Pull back the surface metric and preconditioning surrogate consistently, then
apply state/residual normalization. Do not transpose an already normalized value
basis and assume it is the physical dual restriction. A surface-mass-orthonormal
basis is a controlled choice. The deformation contract already separates
parameter count from boundary-displacement size; the default problem constructor,
PhysicalRiesz surface metric, and material-surface preconditioners still contain
nodal assumptions that must be changed together.
That reduced solve changes the approximation/test space. Its excluded original
shape forces and full original residual must remain visible. A frozen `q0`
retains its existing surface distortion; success there would justify a later
analytic-seed sequence with increasing surface resolution, not certify a smooth
physical root. Suggested first frozen bases use spherical degrees 2/4/6/8
(9/25/49/81 parameters). High-rotation work must demonstrate adequate shape
resolution rather than enforce a low-mode answer. This experiment has not been
implemented here.
Existing `experiments/README.md`, `gravity_completed_rigid_motion.cpp`, and the
surface-mode/reachability/frequency probes provide relevant mode construction
and gravity-completion infrastructure to reuse. The proposed addition is the
fully coupled restricted Newton solve with a consistent dual restriction and
excluded-force checks. Historical CSVs in the original checkout were not rerun
or incorporated into this controlled order comparison.
A separate extension test addresses the virial dilation mode. Q4 ambient fields
can represent the reference position X, but the production logical-radius-squared
extension E0 does not generate X from its surface trace b. At a retained logical
radius 1/8 vertex, lifting b gives only one eighth of the required affine value;
this remains true with Q4 interpolation. A fixed rank-one correction
`E(z)=E0(z)+(X-E0(b))*ell(z)`, with `ell(b)=1`, preserves the supplied trace and
gives `E(b)=X`. Its exact transpose is
`E0^T*f + ell^T*((X-E0(b))^T*f)`; its Jacobian is constant. With an interior
state displacement `u=E(z)`, direction `b+z` then generates current physical
dilation `X+u`. Reference-coordinate access, MPI weights, and adjoint virtual
work require explicit tests. Keep the fixed-infinity vacuum policy unchanged.
This would place the discrete dilation test in the mechanical force space; it
does not automatically enforce the potential-energy virial using the separate
mixed potential. The Q4 endpoint demonstrates why both independent virials are
needed. The rank-one lift also does not remove the observed fine angular modes,
so it is a separate structural control, not a presumed cure. It remains
unimplemented and must not be bundled with surface reduction in a causal test.
All reported states remain nonconverged and include negative density samples;
P(rho)-based virials are undefined there. The required 1e-5 virial milestone and
internal pointwise validation have not been achieved by this order intervention.
No claim about higher-n or rapidly rotating convergence follows from this study.

View File

@@ -0,0 +1,164 @@
# Native spherical harmonic surface candidate
Branch: `research/spherical-harmonic-surface-20260919`.
Parent: `2171b8b76ad78856323fdbcf3d2c537d9039201f`.
The preferred research candidate is degree 4 with **all real azimuthal orders**: 25 independent surface coefficients. This is a discretization choice, not a change to the physical model. The coefficients and interior fields belong to the same Newton system, including their full cross derivatives. The existing nodal radial prescription remains selectable for comparisons. The immediate physical target is rotation through 50% critical; this integration does not establish that target or choose a converged harmonic cutoff for it.
## Coordinates and configuration
For reference boundary nodes with radial directions `rhat_i`, the scalar radial displacement is
q_i = sum_{l=0..L, |m|<=min(l,M)} a_lm Y_lm(rhat_i).
Omitting `M` retains every order. The real basis has unit integral of its square over solid angle, includes the Condon–Shortley phase, and uses negative orders for sine and positive orders for cosine. Coefficients have units of length; zero coefficients preserve the reference mesh. The catalog is ordered by increasing degree, then increasing signed order. Degree zero is a genuine one-parameter monopole.
| Choice | Independent surface parameters |
|---|---:|
| L=4, all m | 25 |
| L=4, maximum absolute m=2 | 19 |
| L=4, m=0 only | 5 |
| L=8, all m | 81 |
No odd-degree or azimuthal modes are silently removed. Restricting to `m=0` constrains the **shape** about the fixed global z axis; it does not impose axisymmetry on the three-dimensional interior fields. The reference center is configurable, but changing the frame is not part of a Newton update.
```cpp
auto discretization = equilibrium::makeStellarDiscretization(
std::move(finiteElements),
normalization::PhysicalRieszDiagonal{dimensions::LengthValue{radius}, G},
deformation::SphericalHarmonicSurface{
deformation::SphericalHarmonicSurfaceOptions{.maximumDegree = 4}
}
);
```
Set `maximumAzimuthalOrder = 0` in the options for the axisymmetric shape comparison. Mode counts and actual sampled independence are checked at compilation onto the mesh. Unresolved modes are rejected, not silently discarded. Prescription/extension compatibility and the coupled operator types remain compile-time constrained; degree, mesh rank and sample dimensions are runtime data.
The sandbox selects this candidate explicitly. Existing two-argument discretization calls retain their nodal behavior. Surface choice lives on the numerical discretization, so the physics-facing EOS, surface-pressure and mass/angular-momentum specification is unchanged.
## Mathematical and architectural changes
- `SphericalHarmonicSurface` satisfies the existing surface-prescription contract and composes with the existing interior and fixed-infinity vacuum extensions. Its cached reference basis has exact forward and transpose actions and a zero derivative of the pullback.
- `StellarDiscretizationFor` owns typed surface/interior/vacuum prescriptions. The modern equilibrium compiler no longer constructs a hardcoded nodal surface.
- Normalization and the default material/surface inverse assemble a diagonal of the pulled-back reference vector trace mass matrix for modal coordinates. The state/residual Gram factors remain a primal/dual pair. The nodal assembly path is preserved.
- Reference metric assembly checks the FEM identity and an explicit canonical trace-layout capability. The erased bridge supports older volume-only deformation operators without claiming that arbitrary trace layouts can use this metric.
- The calibrated diagonal surface inverse supports the actual ordered parameters. The old nodal H1 surrogate explicitly rejects harmonic coordinates; implementing a projected H1 or a dense small surface Schur block is a later preconditioner experiment.
The mesh geometry and field orders are unchanged: Q4 reference geometry, Q3 displacement. Harmonic nodal samples are interpolated through the existing FE trace. Consequently the resulting surface is not an exact analytic harmonic graph between nodes, and the original reference-mesh interpolation error remains.
This differs deliberately from yesterday's frozen reduced-space diagnostic. That experiment retained a general nodal base `q0`, area-whitened its radial basis, and used separate normalized QR maps. The native prescription uses fixed raw reference coordinates from the seed onward. Equality of corresponding **physical** residuals and Jacobians is the validation criterion; identical Krylov trajectories under different diagonal metrics are not expected.
The implementation currently requires one MPI rank, consistent with the existing radial volume extension. Replicated global coefficients are not passed to distributed Newton inner products.
## Validation and reproducibility
New tests cover the harmonic catalog and analytic low-order functions, derivative/transpose/pullback identities, genuine sampled alias rejection, equivalence to the same nodal geometry, coupled physical residual/Jacobian equivalence and centered differences with generated rotation, normalization before physical preparation, independent boundary integration of the metric, and default/calibrated inverse recovery. Unsupported metric layouts, a different current FEM and the unsupported H1 combination are rejected explicitly.
The live preset is `spherical_harmonic_surface_cases_2026-09-19.json`. Native use of the diagnostic driver is explicit:
--surface-prescription harmonics --surface-degree 4
Optionally add `--surface-maximum-order 0`. Legacy frozen nodal probes are excluded from native mode. Known harmonic snapshot metadata is rejected by legacy loaders; undocumented external snapshots still require the caller to supply compatible coordinates.
Every live case retains q14/q18 virial, EOS, positivity and hydrostatic observations. Additional artifacts contain the exact sampled basis, ordered coefficients, full nodal shape force and its component outside the harmonic span. The excluded force uses the Euclidean nodal-dual norm and is not the solver's normalized residual. Both geometry and force pullback equivalence are checked in the observer.
Evidence directory: `../../diagnostics/spherical_harmonic_surface_2026-09-19` relative to this checkout. Builds, tests, live cases and independent artifact audits run serially. Source reviews can run concurrently.
## Implementation validation
- All 10 new harmonic cases passed: 4,273,672 assertions in 174.514 seconds. The large assertion count includes array-element checks; the substantive evidence is the independent analytic, adjoint, coupled finite-difference and nodal-equivalence tests.
- All 64 selected existing regression cases passed: 2,795,921 assertions in 643.882 seconds. These cover nodal/radial/domain deformation, normalization, material/surface preconditioning, modern equilibrium problems and the user API.
- The two-rank invocation exited successfully. It exercised the explicit harmonic rejection paths; tests requiring serial physical preparation were skipped. This does not establish distributed harmonic-solver support.
- The independent artifact auditor passed its valid fixture and rejected six deliberate corruptions (catalog, radial displacement, excluded force, norm, nonfinite data and coefficient count).
Clang initially exhausted its source-location budget when the new interfaces included all of MFEM. Narrowing their includes and moving the non-template metric assembly into an implementation file resolved the test-build failure without changing compiler flags or numerical behavior. The test executable, sandbox and live diagnostic driver all built successfully.
A small modal residual or good virial balance alone is not proof of a physically accurate rotating model.
## Live coupled results
All five cases used the same mesh, cold Lane–Emden initialization, no central-density constraint, the baseline line search and a six-update budget. The stopping criterion was `||F|| / ||F_initial|| <= 1e-8` with zero absolute tolerance. Each linear solve used restart 160, at most 200 iterations and a true relative residual gate of 0.03. All 29 accepted updates took a full step with one trial, and all passed that linear gate. Surface coefficients, thermodynamic fields, gravity and global multipliers were solved in the same coupled system throughout.
The runs below establish native integration and a baseline for the next preconditioner investigation. They do **not** test 50% critical rotation. `J=0.01` is the driver's angular-momentum input in its unit-mass/unit-reference-radius/unit-G convention, not a calibrated fraction of critical rotation.
| Case | Shape parameters | Newton updates | Final normalized residual | Final / initial residual | Outcome | Newton time (s) | Process wall time (s) |
|---|---:|---:|---:|---:|---|---:|---:|
| n=1, J=0 | 25 | 5 | 1.52715e-12 | 9.64952e-9 | Converged | 146.00 | 210.55 |
| n=1.5, J=0 | 25 | 6 | 1.29965e-12 | 5.01751e-9 | Converged | 221.40 | 290.70 |
| n=1, J=0.01 | 25 | 6 | 3.86299e-13 | 4.29274e-10 | Converged | 197.23 | 265.89 |
| n=1, J=0.01, m=0 | 5 | 6 | 3.08442e-13 | 3.42757e-10 | Converged | 164.90 | 232.54 |
| n=1.5, J=0, gravity-Schur | 25 | 6 | 2.19823e-11 | 8.48662e-8 | Update budget exhausted | 189.54 | 257.49 |
Process time includes setup and diagnostic observations; Newton time is the sum of the recorded iteration timers. These are single-run observations, not repeated timing benchmarks. The gravity-Schur variant used one correction sweep with relaxation 0.5. Its failure to meet the requested tolerance within six updates is not evidence of a plateau: its last update still reduced the residual by about 40 times.
### Virial balance and internal correctness
The following are the final q18 measurements. All enthalpy-based energy and force virial errors also pass 1e-5 at q14. The energy form uses the potential binding energy; the force form uses the force binding integral. Both are normalized by the magnitude of the potential binding energy in the existing observer.
| Case | Energy virial, P(h) | Force virial, P(h) | Energy virial, P(rho) | Force virial, P(rho) |
|---|---:|---:|---:|---:|
| n=1, J=0 | 3.87036e-7 | 2.65938e-7 | 4.26994e-7 | 3.05896e-7 |
| n=1.5, J=0 | 6.55153e-7 | 6.00565e-7 | Undefined | Undefined |
| n=1, J=0.01 | 3.86528e-7 | 2.65956e-7 | 4.26535e-7 | 3.05963e-7 |
| n=1, J=0.01, m=0 | 3.86668e-7 | 2.65918e-7 | 4.26626e-7 | 3.05876e-7 |
| n=1.5, gravity-Schur | 6.55158e-7 | 6.00559e-7 | Undefined | Undefined |
The n=1 cases have no negative density at the sampled interior quadrature points. For baseline n=1.5, however, the minimum sampled density is **-4.07687e-4**, the negative-density mass fraction is **2.89318e-5**, and the negative-density volume fraction is **0.0186652**. The fractional polytropic density EOS is undefined at those samples. Its density-derived pressure integral and both density-based virial measures are therefore undefined, not successful tests. The gravity-Schur endpoint has essentially the same defect.
| Case | Scaled EOS density mismatch RMS | Hydrostatic gradient RMS, initial | Hydrostatic gradient RMS, final | Minimum deformation determinant |
|---|---:|---:|---:|---:|
| n=1, J=0 | 7.79532e-5 | 1.15196e-3 | 3.96736e-3 | 0.998938 |
| n=1.5, J=0 | 1.25551e-4 | 1.52810e-3 | 7.27475e-3 | 0.998671 |
| n=1, J=0.01 | 7.80099e-5 | 1.47640e-3 | 3.96661e-3 | 0.997774 |
| n=1, J=0.01, m=0 | 7.79615e-5 | 1.47640e-3 | 3.95930e-3 | 0.997774 |
These pointwise diagnostics are not the assembled weak residual. The n=1.5 hydrostatic gradient RMS worsens by **4.76 times** while the native residual converges. This reproduces the main physical caveat from yesterday's projected-space experiment; the new implementation has not resolved it. Mass errors are below 5.3e-14 for the four converged cases, and angular-momentum errors are below 3.6e-16.
Quadrature sensitivity is small for the enthalpy energy virial: q18 versus q14 differs by at most 7.7e-14 for these n=1 cases and about 1.83e-9 for n=1.5. The n=1.5 negative-density mass fraction, in contrast, changes by about 30% between these quadratures. Good integral virial stability must not be used as evidence that the positivity defect is resolved or fully measured.
### What the restricted surface balance leaves out
The final full nodal mechanical force is almost entirely orthogonal to the selected harmonic span. Its Euclidean norm is approximately **9.22e-6** for n=1, J=0 and **8.99e-6** for n=1.5, J=0. In the latter case, the retained modal force norm is only **3.61e-14**. The independent audit reproduces the basis pullback and excluded-force projection from saved vectors.
This is convergence of the selected Galerkin shape problem, not convergence of the former unrestricted nodal shape problem. Orthogonality of the remaining force is expected at a modal root; the absolute excluded force still needs a degree/mesh convergence study and an appropriate physical or dual-norm interpretation. Its dimensional Euclidean norm cannot be compared directly with either the normalized nonlinear residual or the dimensionless virial tolerance.
All signed m modes remain available and coupled in the all-m representation. For example, the final real `(l,m)=(4,4)` coefficient is 8.97263e-5 for n=1, J=0 and 9.23867e-4 for n=1.5, J=0, in radial-length units. The latter is comparable to that case's `(4,0)` coefficient, 1.09313e-3. Nonaxisymmetric corrections in these nominally spherical models are a reason to investigate mesh/discretization imprint under refinement, not evidence of a physical nonaxisymmetric branch. L=4 is a preferred starting resolution, not a validated universal cutoff.
## Implications for the next preconditioner study
| Case | Krylov iterations by Newton update | Total Krylov iterations | Linear-solve time (s) |
|---|---|---:|---:|
| n=1, J=0 | 19, 23, 28, 74, 68 | 212 | 89.79 |
| n=1.5, J=0 | 25, 26, 26, 84, 87, 87 | 335 | 150.06 |
| n=1, J=0.01 | 18, 20, 22, 48, 92, 96 | 296 | 129.96 |
| n=1, J=0.01, m=0 | 18, 20, 22, 27, 65, 67 | 219 | 97.29 |
| n=1.5, gravity-Schur | 18, 20, 18, 22, 70, 58 | 206 | 116.25 |
The m=0 comparison reduces total Krylov iterations by **26.0%** and Newton time by **16.4%** for this low-rotation case, with nearly identical virial measures. It is a useful selectable control. Restricting m also changes the admissible shape, so this is not a pure preconditioner speedup. All m remain the preferred 3D candidate.
Gravity-Schur reduces Krylov work in the six-update comparison but changes the inexact Newton trajectory and does not reach the common stopping tolerance within that budget. Its lower time is not a demonstrated time-to-convergence improvement. Late iteration counts increase substantially even in the 25-parameter system; the recorded initial-linear-residual/RHS ratios remain essentially one, so this observation is not explained by an increasingly poor recycled initial guess.
The next focused experiment should measure the **coupled surface Schur operator** at identical saved states. With surface coefficients `a` and all remaining unknowns `u`, the target is
S = J_aa - J_au J_uu^{-1} J_ua.
The field response must include gravity, thermodynamics and the relevant mass/angular-momentum borders. The existing diagonal boundary metric supplies coordinate scaling but does not model this response. Twenty-five coefficients make a small dense reference Schur matrix feasible as a diagnostic, although its field solves may be expensive. First verify the inner field-block solve defects and determine whether that block has a usable inverse. Measure the Schur singular values, conditioning, spectrum, scaling and setup cost before choosing a reusable approximation; eigenvalues alone do not characterize weak inverse response for a nonsymmetric operator. Compare default diagonal, calibrated diagonal and any new Schur approximation at the same state, then confirm complete nonlinear time to a common tolerance. A block elimination inside the preconditioner still serves the simultaneous coupled Newton solve; it does not introduce a separate surface-relaxation algorithm.
No new gauge constraint, field order, positivity modification or rotation-criticality model is introduced by this integration. Possible weak directions must be measured before deciding that any mode is a gauge or should be removed. Increasing n or J remains subject to the recorded local validation defects as well as the 1e-5 virial milestone.
## Evidence binding
Implementation and live producer source: `7b0eb8d92d0f550f1fe3fb19cd8eecc52dc80c56`. The tracked source was clean during the campaign. The report-only follow-up commit does not alter the producer.
- Mesh SHA256: `ce11ae99e21e6c3bbfbee402acd2e191c1da0d8261d2227b4203f73f2f337a74`.
- Copied live binary SHA256: `855d9b6bc8af326d689840b7eb8bf9c4f85d5f2584ef30c225247803a86ded36`.
- `implementation_validation.json` records build/test evidence and executable hashes.
- `campaign/provenance.json` records the branch, source commit, toolchain, mesh, binary and exact case arguments. Each case's run record binds output hashes and timing.
- `campaign_audit.json` records a successful independent audit of all five cases, saved algebra and scalar identities. This is an artifact-consistency result, not a model-validity certificate or a fresh FEM integration.
- `results_summary.json` contains the compact quantities used in this report; the original CSVs, logs and accepted states remain available in `campaign/`.
To repeat the artifact audit from this checkout:
/opt/homebrew/anaconda3/envs/general/bin/python experiments/audit_spherical_harmonic_surface.py ../../diagnostics/spherical_harmonic_surface_2026-09-19/campaign --output ../../diagnostics/spherical_harmonic_surface_2026-09-19/campaign_audit.json
The preferred surface candidate is now integrated and tested. Acceptance of a physical higher-n or 50%-critical model remains separate from this implementation milestone.

View File

@@ -0,0 +1,698 @@
# Final optimization batch: pressure, gravity source, preparation, and fixed divergence
Build the targets explicitly; sandbox is excluded from the default build:
```sh
cmake --build cmake-build-release-homebrew \
--target system_isolation_profile_harness sandbox tests --parallel
```
Run from the repository root with a new output directory:
```sh
./cmake-build-release-homebrew/system_isolation_profile_harness \
--system final-optimizations --check full --implementation both \
--samples 5 --iterations 10 --warmup 2 \
--prepare-samples 3 --prepare-iterations 1 \
--output final_optimizations_01
```
This group measures:
- `pressure-displacement`: tensor evaluation of displacement gradients and
tensor gradient transpose, compared with the previous optimized pointwise
application (`cached_pointwise_reference`). The general prepared action
and stateless kernel remain correctness references.
- `pressure-preparation`: batched displacement and enthalpy evaluation and
tensor assembly of the enthalpy derivative matrix, compared with the
previous blocked matrix assembly and pointwise displacement evaluation.
- `gravity-source-displacement`: tensor density/displacement evaluation and
potential-test transpose, compared with the previous pointwise application.
- `hydrostatic-preparation`: batched displacement and scalar evaluation and
tensor assembly of the algebraic matrices, compared with the previous
pointwise/dense preparation.
- `gravity-schur-preparation`: reuse of the fixed divergence matrix during
Schur assembly, compared with assembling divergence on every call. This
timing excludes mass-diagonal preparation and AMG setup, which are unchanged.
Preparation timings change state/revisions before each measured call and
verify that pressure/hydrostatic preparation actually rebuilds. Schur timings
cycle through mass diagonals prepared from three displacement states.
Cold hydrostatic preparation and cold divergence-cache assembly are reported
separately. These medians measure the incremental benefit of this batch;
they do not reuse the slower baselines from earlier batches.
Full harness checks compare prepared and stateless derivatives, residuals,
algebraic actions, enthalpy diagonals, multiple states and directions, zero
source directions, and finite differences. Hydrostatic checks also reject
folded geometry and recover afterward. Schur checks compare cached and
fresh assembly, change and restore the mass diagonal, check exact inverse
scaling, clear the cache, and invalidate it with `Mesh::NodesUpdated()`.
New unit coverage checks the scalar gradient transpose against dense
reference gradients and adjoint products for multiple H1/L2 orders/bases,
preparation-mode switches, rejection/recovery, and production gravity-block
cache reuse/invalidation.
The divergence cache belongs to each prepared gravity block. It retains one
assembled sparse matrix for the block's lifetime. Every refresh still forms
a fresh weighted transpose and Schur matrix using the current mass diagonal.
A discretization revision clears the cache; mesh, node, FE-space sequences,
and quadrature-policy identity are also checked collectively before reuse.
Raw computational-coordinate edits must call `Mesh::NodesUpdated()`.
A standalone cache must be cleared after changing a quadrature policy in
place. Physical displacement changes do not invalidate fixed divergence.
The tensor paths retain the existing mapper validation, quadrature, DOF
transformations, and fallbacks for unsupported elements/rules. Metadata
reports `pressure_tensor_elements`, `source_tensor_variation_elements`, and
`hydro_preparation_tensor_elements`, plus divergence assembly counts. A zero
tensor count indicates fallback, not measured tensor acceleration.
The new individual selectors are `gravity-source-displacement`,
`hydrostatic-preparation`, and `gravity-schur-preparation`.
`pressure-displacement` includes its preparation benchmark. This batch is
selected together with `final-optimizations`.
Return `summary.txt`, `metadata.txt`, `timings.csv`, and `checks.csv`.
After the checks pass, run the rebuilt sandbox with the same preflight
setting as the previous run, and capture its Newton timings and profiles.
Compare the residual, accepted step, trial count, determinant minimum, Krylov
iterations, and true linear residual along with the wall times. The previous
reference was 24.174 s for Newton 0, 8.00964 s trial preparation, 2.14648 s
accepted refresh, and 13.6571 s linear solve (26 J and 24 preconditioner calls).
These source and test changes have not been compiled or executed by the agent.
---
# Application optimization batch: closure, rotation, primal mass, and trial preparation
Build both `system_isolation_profile_harness` and `sandbox` explicitly in
`cmake-build-release-homebrew`; sandbox is excluded from the default build.
Run from the repository root:
```sh
./cmake-build-release-homebrew/system_isolation_profile_harness \
--system application-optimizations --check full --implementation both \
--samples 5 --iterations 10 --warmup 2 \
--prepare-samples 3 --prepare-iterations 1 \
--output application_optimizations_01
```
The group measures these changes against the implementations immediately before
this batch:
- `barotropic-closure`, `barotropic-enthalpy`, and `barotropic-displacement`:
tensor interpolation and transpose versus the cached pointwise path. The
dedicated enthalpy and displacement baselines retain their dedicated entry
points, so these ratios measure tensor acceleration without counting the
earlier removal of zero-block work again.
- `rotation-force`: tensor density/displacement interpolation and force
transpose versus the cached pointwise complete action.
- `hdiv-mass`: the new CPU application versus retained MFEM partial assembly
(`mfem_pa_reference`), with identical prepared coefficients, quadrature,
restrictions, orientation handling, and true-DOF transfers. The new integrator
contracts only its marked domain, uses scratch sized to the actual order,
and specializes the current RT2/nine-point-per-axis case. Other supported
CPU orders use the same algorithm with runtime dimensions. Other backends
retain MFEM's application. Mass-only runs use primal preparation.
- `geometry-inspection`: the production trial-geometry validator with cached
computational-mesh inverse Jacobians and tensor gradients, versus the original
`GridFunction::GetVectorGradient` loop. Every volume element, inspection
point, and determinant check is retained. The first cold inspection is
reported separately; paired medians measure reuse with changing displacement.
- `gravity-source-preparation`: reuses the mesh weight already computed during
mapping evaluation, versus recomputing `ElementTransformation::Weight()`.
Both paths rebuild on every measured call; the harness checks preparation
counters and compares forward, transpose, and displacement actions.
The scalar tensor plans now include nodal H1 and L2 hexes. Basis reconstruction,
native DOF permutations, and Cartesian quadrature ordering are verified before
a plan is enabled. Unsupported elements/rules retain the dense implementation.
Metadata reports `closure_tensor_elements`, `rotation_tensor_elements`,
`fast_mass_elements`, and `geometry_inspection_tensor_elements` so a fallback
cannot be mistaken for acceleration.
Full checks include general prepared and independent stateless comparisons,
existing finite differences, mass symmetry/linearity/positive energy/zero input,
changing geometries, fold rejection, and non-finite geometry rejection. The
unit-test additions also cover both global vector orderings, curved-mesh cache
invalidation, explicit cache clearing, tetrahedron fallback, and L2 basis
variants. These tests are supplied for the user to compile and run.
The inspector stores nine doubles (72 bytes) per eligible inspection point,
plus shared reference tables and reusable element scratch. It refreshes fixed
geometry when the mesh, nodes, or finite-element-space sequence changes.
Raw coordinate edits must call `Mesh::NodesUpdated()`, as with MFEM's geometry
cache, or clear a standalone inspector with `ClearCache()`. Displacement is
read anew for every inspection. Its mutable scratch is intended for sequential
calls, consistent with the prepared operators.
Use a new output directory and return `summary.txt`, `metadata.txt`,
`timings.csv`, and `checks.csv`. Application timings use `--samples` and
`--iterations`; inspection/source preparation timings use `--prepare-samples`
and `--prepare-iterations`. This group omits unrelated force-preparation
benchmarks. Individual systems remain selectable. After checks pass, rebuild
sandbox too and compare its printed Newton timings and convergence against the
previous run.
---
# Runtime optimization batch: tensor applications, geometry cache, normalization
Build both `system_isolation_profile_harness` and `sandbox` explicitly in
`cmake-build-release-homebrew`; sandbox is excluded from the default build.
Run from the repository root:
```sh
./cmake-build-release-homebrew/system_isolation_profile_harness \
--system runtime-optimizations --check full --implementation both \
--samples 5 --iterations 10 --warmup 2 \
--prepare-samples 3 --prepare-iterations 1 \
--output runtime_optimizations_01
```
This group checks and measures:
- `normalization-diagonals`: H(div), potential, density, enthalpy, and surface
reference-mass diagonals, comparing volume partial assembly and direct surface
diagonal integration to full true-DOF matrix assembly. Both diagonal norms
are recorded, and the surface diagonal must have positive entries. These use
the preparation sample/iteration counts.
- `geometry-preparation`: complete H(div) preparation with the fixed-mesh
geometry cache enabled versus disabled, changing displacement between paired
samples. Both use the same optimized operator. Mass and displacement actions
are checked outside the timer. The initial cold-cache preparation is reported
separately; median timings measure reuse. Cache hit/miss/point counts are saved.
- `hdiv-displacement`: tensor interpolation/transpose versus the **previous
optimized pointwise** implementation (`cached_pointwise_reference`).
- `gravity-force`: tensor application versus the **previous optimized pointwise**
application. General prepared paths and finite differences remain independent
checks. The older gravity preparation comparison is omitted from this group.
The metadata includes `tensor_variation_elements` and
`gravity_tensor_elements`. The current hex mesh should use tensor paths on all
eligible elements. General geometries and quadrature retain the existing paths;
these counts distinguish real acceleration from a correct fallback.
Individual systems remain selectable, including the two new setup systems.
Use a new output directory for every run. Upload `summary.txt`, `metadata.txt`,
`timings.csv`, and `checks.csv`. Preparation timings use `--prepare-samples`
and `--prepare-iterations`; application timings use `--samples` and
`--iterations`.
## Preflight option
```sh
./cmake-build-release-homebrew/sandbox --skip-preflight
```
Library option: `NewtonOptions.backtracking.geometryPreflight = false`.
The default remains `true`; sandbox also accepts `--preflight`. Skipping avoids
both the predictive geometry scan and its lazy rule construction. Trial mapping
validation, finite-value checks, backtracking, and accepted-state restoration
remain active. Skipped scans have zero reported time and an empty optional
geometry estimate; `geometryLimitedIterations` counts only predictive limits.
A skipped scan can trade its time for extra rejected trials on a large step.
## Geometry and normalization contracts
The mapper caches only fixed computational-mesh positions, Jacobians, inverse
Jacobians, and weights. It recomputes displacement and compactification mapping
data on each call. Cache keys use element and actual reference coordinates, so
copied or changed quadrature rules cannot reuse the wrong point; quadrature
weights are applied by each caller. Mesh and node sequence changes invalidate
the entries. After raw coordinate changes, call `Mesh::NodesUpdated()`, as for
MFEM's geometric-factor cache, or `DomainMapper::ClearGeometryCache()`. Clear
the cache before destroying a mesh that the mapper will outlive. Cache entries
consume memory proportional to the distinct element/quadrature points visited,
and the mapper cache, like the element transformations it uses, is not thread-safe.
Normalization retains full matrix assembly for nonconforming, variable-order,
and unsupported element spaces. In particular, it does not substitute the
approximate partial-assembly diagonal for `diag(P^T A P)` on hanging-node meshes.
Supported conforming hex volume spaces use MFEM partial assembly followed by
exact true-DOF diagonal assembly. The surface path integrates only diagonal
entries over marked boundary elements, using the same quadrature and physical
shape functions as full assembly. This includes the internal star/vacuum
interface, which MFEM's exterior boundary partial-assembly restriction omits.
The direct surface path supports conforming scalar H1 spaces without general
DOF transformations; other spaces retain full assembly.
The new tests in existing test sources cover scalar/RT tensor transposes and
adjoint products, integrated RT bases, retained-table lifetime, general fallback,
geometry cache invalidation, changed displacement/compactification, exact
normalization diagonals, nonconforming fallback, and Newton acceptance/fold
rejection with preflight skipped. Compilation and execution are left to the user.
---
# System isolation profile harness
This executable checks and times individual operators without constructing a
stellar model, preconditioner, or Newton solver. Available systems are:
- `hdiv-displacement`: optimized versus retained prepared H(div) derivative.
- `hdiv-mass`: new CPU primal application versus retained MFEM partial assembly.
- `mass-normalization`: cached scalar mass row versus retained quadrature action.
- `angular-momentum`: cached scalar angular-momentum row versus retained quadrature action.
- `hydrostatic-displacement`: tensor evaluation versus the previous cached pointwise derivative; checks also compare the general mapping variation.
- `stellar-derivatives`: mass normalization, angular momentum, and hydrostatic displacement.
- `barotropic-closure`: complete density/enthalpy/displacement closure action.
- `barotropic-enthalpy`: tensor versus cached dense dedicated enthalpy coupling.
- `barotropic-displacement`: tensor versus cached pointwise dedicated displacement coupling.
- `pressure-displacement`: direct pressure displacement contraction versus the old matrix products.
- `pressure-enthalpy`: local-matrix application after blocked versus original matrix preparation.
- `gravity-force`: complete density/displacement/gravity-gradient force derivative.
- `rotation-force`: complete density/displacement force derivative at fixed rotation.
- `linear-derivatives`: the seven closure/force comparisons above, plus pressure/gravity/rotation preparation timings.
- `preparation-optimizations`: pressure displacement and enthalpy, gravity force, rotation force, their preparation comparisons, then hydrostatic displacement.
- `geometry-inspection`: cached fixed geometry and tensor gradients versus the original geometry scan.
- `gravity-source-preparation`: cached mesh weights versus repeated weight evaluation.
- `application-optimizations`: the closure, rotation, primal mass, inspection, and source comparisons described above.
- `all`: all application and preparation comparisons, including geometry inspection and normalization diagonals.
A failure stops the affected group before its benchmarks.
The default remains `hdiv-displacement`. Scalar systems prepare a shared gravity
context to supply their frozen state, but do not solve for gravity. Hydrostatic
only runs do not construct that shared context.
## Preparation and hydrostatic optimization comparison
The current changes fuse gravity/rotation residual assembly with element-cache
preparation, block pressure enthalpy-matrix assembly, and use tensor contractions
for supported hydrostatic displacement elements. From the repository root,
after the user builds the release targets:
```sh
./cmake-build-release-homebrew/system_isolation_profile_harness \
--system preparation-optimizations --check full --implementation both \
--samples 5 --iterations 10 --warmup 2 \
--prepare-samples 3 --prepare-iterations 1 \
--output preparation_optimizations_01
```
Return the four output files. The new preparation medians are
`pressure-preparation.*`, `gravity-force-preparation.*`, and
`rotation-force-preparation.*`. Every timed pair gets fresh dependency revisions
with the same frozen physical state. Order alternates between samples.
Preparation counters must increase once per call; an accidental no-op is an error.
Shared gravity-context preparation and residual copying/norms are outside these
timers. These are warm re-preparation timings; they include geometry rebuilding
and do not measure first-construction cost or a complete Newton iteration.
Initial and unchanged-state preparation remain separately reported.
Preparation uses its own sample/iteration counts to avoid accidentally repeating
multi-second work with the application iteration count. Set `--prepare-samples 0`
to skip preparation timings. Both implementations remain available through
`--implementation`; correctness checks can still prepare references in an
optimized-only timing run. Independent reference operators require additional
memory in the harness, not in the production solver.
Checks compare prepared residuals and pressure enthalpy actions against the
original preparation at five states, as well as the existing derivative and
finite-difference checks. Hydrostatic timings use
`cached_pointwise_reference`, isolating this change from the earlier fast-path
optimization. Metadata reports `hydrostatic-displacement.tensor_elements`.
On the standard mesh this should equal the stellar element count.
Focused regression cases:
```sh
./cmake-build-release-homebrew/tests '*Tensor reference*,*Pressure*Force*,*Gravity Displacement Force*,*Rotational Displacement Force*,*Prepared Hydrostatic*'
```
For a nonlinear EOS check, repeat with `--polytropic-index 3` and a new output
directory. No stellar seed or Newton convergence is required.
## First comparison of closure and force derivatives
Explicitly build the harness target: it is excluded from the default build.
From `/Users/tboudreaux/Programming/4DSTAR/MeanField`, use:
```sh
cmake --build cmake-build-release-homebrew \
--target system_isolation_profile_harness tests sandbox --parallel 2
./cmake-build-release-homebrew/system_isolation_profile_harness \
--system linear-derivatives --check full --implementation both \
--samples 5 --iterations 10 --warmup 2 \
--output linear_derivatives_01
```
Return `summary.txt`, `checks.csv`, `metadata.txt`, and `timings.csv`.
Use a new output directory for every run. Individual system names above let you
isolate a failure or time one operator without constructing the others.
The group defaults to a polytrope with n=1 and K=1. To exercise a nonlinear EOS
without creating a stellar seed, add `--polytropic-index 3`; this option applies
only to the closure/force group and does not change the FEM mesh.
The complete closure comparison measures the contraction change. The two
coupling comparisons include savings from omitting absent columns, exactly as
the preconditioner now does. Their reference still executes the old complete
action with explicit zeros. Pressure measures both displacement and enthalpy derivatives.
Gravity and rotation measure their combined derivatives; their individual
stateless column methods remain available as independent checks.
Full validation covers undeformed and deformed geometry, a density/enthalpy-only
update, a gravity/rotation update, and a rotation-only update to zero angular
velocity. Nonzero rotation uses a tilted axis and an offset center. Each state
compares every requested direction and an exact zero direction. Column checks
compare old/new complete actions; gravity and rotation also compare their
independent stateless columns. Prepared gravity/rotation residuals are also
compared with independently assembled stateless residuals at every validation
state. Centered differences of primal residuals use two step sizes. Grouped runs check the complete closure FD;
individual coupling runs check that coupling's FD. Unchanged dependency
revisions must preserve preparation counts.
The scaled comparison uses the same unit-floor metric as the stellar group.
An additional relative comparison is reported for non-negligible outputs,
with tolerance 2e-10 for references and 2e-6 for finite differences. Full
validation may take several minutes because it prepares many states; its time
is reported separately and excluded from application samples.
`--check reference` checks one state plus zero input and unchanged revisions;
`--check none` skips correctness checks.
Initial, repeated, and unchanged preparation times are separate. The gravity
context is counted once, separately from gravity force preparation.
Application comparisons retain the earlier reference derivatives. The pressure
enthalpy comparison uses independently prepared local matrices, and the separate
preparation benchmarks compare original versus optimized preparation.
Gravity/rotation metadata reports fast-element counts; on the standard
3D mesh these should equal the stellar element count. Their fast paths require
VALUE/GRAD displacement with byNODES global ordering; gravity also requires an
H(div) reference table. Other configurations retain the previous implementation.
Closure and pressure use their direct contractions in 3D and retain their
previous general-dimensional calculations otherwise.
Focused regression cases, including material/surface coupling tests:
```sh
./cmake-build-release-homebrew/tests '*Barotropic Closure*,*Pressure*Force*,*Gravity Displacement Force*,*Rotational Displacement Force*,*Material*Surface*'
```
## First comparison of the scalar rows and hydrostatic derivative
After compiling the updated release executable, run from the repository root:
```sh
./cmake-build-release-homebrew/system_isolation_profile_harness \
--system stellar-derivatives --check full --implementation both \
--samples 5 --iterations 20 --warmup 2 \
--output stellar_derivatives_01
```
Return `summary.txt`, `checks.csv`, `metadata.txt`, and `timings.csv`. To isolate
one system, replace `stellar-derivatives` with `mass-normalization`,
`angular-momentum`, or `hydrostatic-displacement`. The scalar benchmarks apply
the complete row (density/displacement and, for angular momentum, Omega).
The hydrostatic benchmark applies only its displacement derivative.
Full checks compare four states: undeformed, deformed, changed density, and
changed rotation including negative Omega. They use several directions, with
an element-scale perturbation in the second displacement direction. The
rotation axis is tilted and its center is displaced from the origin. Checks
cover separate scalar columns and zero inputs, the mass transpose identity,
lazy row construction, reuse on rotation/target-only updates, and invalidation
on geometry/density updates. Two centered differences perturb density,
displacement and Omega together for the scalar rows; the hydrostatic difference
holds the other fields and rotation fixed. Finite differences use the existing
primal residual preparation, which has not been replaced by the new row code.
For these three systems, errors are
`norm(actual-reference) / max(1, norm(actual), norm(reference))`; the unit floor
also makes zero scalar columns testable. Reference tolerance is 2e-11 and finite
difference tolerance is 2e-6. Lifecycle checks use exact counts. `--check reference`
checks one state and all requested directions; `--check none` performs no
correctness checks. These runs do not establish stellar accuracy or MPI correctness.
Preparation is reported separately for the shared gravity context and each
selected operator, on initial construction and on re-preparation. Scalar rows
are built lazily in production on first Jacobian use. The harness explicitly
times `PrepareJacobianRows()` before warmup, including in reference-only runs,
so that repeated-application medians do not hide that cost in one sample.
`explicit_row_prepare_seconds` records this first-use cost. When both paths are
timed, the summary also reports the break-even application count and the
reference/optimized ratio for 1, 10 and 25 calls including one row assembly.
A break-even value of -1 means no measured per-application saving. These ratios
exclude the common state/context preparation costs, which are reported separately.
Hydrostatic comparison uses the same augmented geometry cache for both paths;
it does not independently measure the previous preparation time.
Metadata reports scalar row eligibility and the hydrostatic fast-element count.
On the standard mesh both scalar flags should be 1 and the hydrostatic count
should equal the stellar element count. The optimized scalar rows retain two
local vectors per operator; hydrostatic adds nine doubles (72 bytes) per eligible
quadrature point. Reference tables are shared across operators with matching
elements and quadrature rules. Old mapping caches remain for reference/fallback.
The user-run `stellar_derivatives_01` comparison passed all checks and measured
885x and 1349x repeated scalar applications, and 1.94x hydrostatic displacement.
These exclude common preparation. The closure/force changes described below
have not been compiled or executed by the coding agent.
## H(div) comparison
From the repository root, run:
```sh
./cmake-build-release-homebrew/system_isolation_profile_harness \
--system hdiv-displacement \
--check full \
--implementation both \
--samples 5 --iterations 3 --warmup 1 \
--output hdiv_isolation_01
```
The output directory must not exist. This uses `sandbox.smesh`, the production
quadrature policy and registered element orders, and one MPI rank on the CPU.
It performs no equilibrium solve. Directions and gravity coefficients are
deterministic; the geometry is a small nonuniform polynomial displacement with
shear and cross terms. `--deformation 0` selects the undeformed timing state;
the default is `0.7`, multiplying displacements whose coefficients are of order
0.01–0.04. This argument is not a fractional stellar radius or rotation rate.
Full validation checks two geometries (zero and the selected deformation), all
configured directions against the retained prepared derivative, and the first
direction against the independent stateless kernel. It also checks the selected
geometry against centered differences of the primal mass operator at two step
sizes. Those differences hold the gravity coefficients fixed. A failed check
stops the run before timing and returns status 3. Execution errors return 2;
successful requested checks and timing return 0. With `--check none`, status 0
means execution completed, not that correctness was checked.
Return `summary.txt`, `checks.csv`, `metadata.txt`, and `timings.csv` for analysis.
There is no need to run the full stellar model for this first comparison.
## Timing and interpretation
- `metadata.txt`: mesh path, geometry parameter, build/compiler information,
problem sizes, domain element counts, quadrature count, and how many elements
use the new derivative path. For the standard 3D Kelvin case, the last count
should equal the total element count.
- `summary.txt`: finite-element setup, operator construction, initial and repeat
preparation, validation time, median application times and their ratio.
- `timings.csv`: every measured sample, application count, seconds per
application, and the last output norm. Warmup is excluded. A/B execution order
alternates between samples. Output norms and file writes are outside the
application timer. Each sample cycles through the same direction sequence.
- `checks.csv`: numerical errors, tolerances, and pass/fail status. The derivative
comparison tolerance is 2e-11; centered differences use 2e-6 to allow subtraction
error. A numerical failure is not permission to relax a tolerance.
For `hdiv-displacement`, `prepared_reference` is the previous prepared application
algorithm, retained in the same executable and using the same prepared state,
quadrature and field maps. This is the relevant application speedup comparison.
Both paths include true/local vector transfers and element assembly. Preparation
has already constructed the new cache in either case: this comparison does not
measure the old preparation cost or old peak memory use.
For `hdiv-mass`, `optimized` is the new CPU contraction and
`mfem_pa_reference` is the retained MFEM application using the same PA data.
This ratio measures the primal mass improvement from the latest batch. Full
checks still compare the independent stateless kernel, which reevaluates mapping.
Mass-only runs use primal preparation and report zero variation-cache elements.
The new tangent cache adds 12 doubles per eligible quadrature point (96 bytes),
plus shared reference displacement tables. Existing frozen mapping data remains
available for the reference/fallback implementation. Initial preparation may
therefore increase; compare preparation plus the application's actual number of
repeated calls when judging the total benefit. The earlier `hdiv_isolation_01`
user run measured a 3.13x median application speedup on the standard mesh; this
is separate from the new scalar/hydrostatic optimizations.
For a longer optimized-only profiling window after correctness passes:
```sh
./cmake-build-release-homebrew/system_isolation_profile_harness \
--system hdiv-displacement --implementation optimized --check none \
--samples 10 --iterations 20 --warmup 3 \
--output hdiv_optimized_profile_01
```
Use a separate directory for each run. Avoid concurrent builds or other heavy
jobs while collecting comparisons. To inspect another resolution, use
`--refinements N`; to change the number of direction/flux pairs, use
`--directions N`. These are local operator tests, not demonstrations of final
stellar accuracy or distributed correctness.
## Derivative implementation
For computational-mesh coordinates X, the mapped H(div) mass tensor is
\[
M = J^T J / \det J, \qquad J = \partial x_{physical}/\partial X.
\]
The fast path contracts shared reference displacement gradients before applying
the cached mesh inverse. In the stellar domain, delta J is grad(delta u). For
Kelvin compactification, the existing Kelvin radial-factor calculation supplies
the fixed scale and its gradient:
\[
\delta J = a\,\nabla_X\delta u + \delta u (\nabla_X a)^T.
\]
Only `a * J_mesh^-1` and `grad_X(a)` are added to the point cache. The directional
mass action on a computational H(div) vector g is evaluated as
\[
\delta M g = \frac{\delta J^T(Jg) + J^T[\delta Jg -
\operatorname{tr}(J^{-1}\delta J)Jg]}{\det J}.
\]
This avoids computing unused inverse-mapping, inverse-element, physical-position,
and quadrature-weight derivatives, and avoids constructing the full mass-tensor
derivative. The fixed computational-mesh Piola factors, signed DOFs, primal/dual
DOF transformations, quadrature weights and true/local transfers are retained.
There is no change to equations, integration order, or solver tolerances.
The specialization requires three dimensions, an H(div) reference table, and
VALUE/GRAD displacement elements. Compactified elements additionally require
the concrete Kelvin map and a differentiable compactification element. Other
maps use the retained general implementation; merely declaring a map affine
does not select the Kelvin specialization.
## Compile and regression checks
Configure the release build with
`CMAKE_CATCH_DISCOVER_TESTS_DISCOVERY_MODE=PRE_TEST`, so compiling test targets
does not execute them to enumerate cases. Discovery occurs when the user runs
CTest. Configure/build commands are:
```sh
cmake -S . -B cmake-build-release-homebrew \
-DCMAKE_CATCH_DISCOVER_TESTS_DISCOVERY_MODE=PRE_TEST
cmake --build cmake-build-release-homebrew \
--target system_isolation_profile_harness tests sandbox --parallel 2
```
Focused regression cases for the user to run:
```sh
./cmake-build-release-homebrew/tests '*Prepared Hdiv*,*Prepared Mapped Hdiv*,Kelvin Prepared Jacobian Factors*'
```
Focused scalar/hydrostatic regression cases for the user to run after building:
```sh
./cmake-build-release-homebrew/tests '*Prepared Mass Normalization*,*Prepared Angular Momentum*,*Prepared Hydrostatic*'
```
These existing suites now also check retained-reference agreement, lazy row
construction, selective row invalidation, reuse across unrelated updates, and
angular-momentum rejection/recovery after rows have already been built. Existing
finite differences, transpose pairing and context lifecycle tests remain active.
## Closure and force implementation
All changes preserve quadrature, equations, field maps, signed element DOFs,
primal/dual transformations, and true/local transfers. There is no tolerance
based dropping of closure or vacuum terms.
- Closure couplings have supported-coordinate entry points for enthalpy alone
and displacement alone. The preconditioner calls these rather than executing
a complete action with known zero columns. The complete action still includes
every column. Its geometric scalar remains
`weightedResidual * tr(K * du/dxi)`, evaluated with a small direct contraction.
- Pressure uses the existing physical test gradients G and computes H=du/dx.
Its displacement contribution is `p*w*(G*H-tr(H)*G)`. This avoids constructing
the inverse-Jacobian variation and the matrix of all gradient variations.
- Gravity evaluates the existing expression
`w_ref * [F*(delta_rho*g + rho*delta_g) + rho*(du/dxi)*(J_mesh^-1*g)]`.
The last term contracts the reference gradients with a vector directly.
Density interpolation and test-basis transpose are done per element; H(div)
reference interpolation keeps the existing mesh Piola factor.
- Rotation uses shared reference value/gradient tables, bulk interpolation and
transpose application, and a cached 3x3 centrifugal acceleration derivative.
The force variation is
`w * [(delta_rho + rho*delta_log_w)*a + rho*delta_a]`.
The acceleration derivative is rebuilt with the existing preparation lifecycle.
The new paths add per-element scratch buffers reused between elements and
shared reference tables for rotation; they do not add large per-point dense
Jacobian blocks. Existing data and reference paths are retained. Reference
applications do not increment production column/complete application counters.
## Scalar and hydrostatic derivatives
For the supported stellar VALUE/GRAD displacement field, let `B_a` be the
reference basis, `K` the inverse deformed element Jacobian, and `w` the mapped
quadrature weight. An element displacement direction satisfies
```
delta x_c = sum_a B_a delta u_ac
delta log(w) = sum_acj K_jc (dB_a/dxi_j) delta u_ac
```
The mass row integrates `w delta rho + rho w delta log(w)`. The moment-of-inertia
row integrates `w r_perp^2 delta rho + rho w [r_perp^2 delta log(w) +
2 r_perp dot delta x]`. Angular momentum applies `Omega delta I + I delta Omega`.
The local coefficient vectors are assembled with signed element DOFs and dual
DOF transformations, then paired with prolonged true-DOF directions. The final
scalar retains the existing MPI sum. Keeping these as local duals avoids
double-counting shared true DOFs. Mass transpose uses the transpose prolongation.
Hydrostatic displacement contracts
`w [(h + Phi - Psi - C) delta log(w) - grad(Psi) dot delta x]`, then applies the
existing enthalpy test-basis transpose and assembly. It does not construct a
full mapping variation or repeatedly evaluate reference shapes. Only 3D interior
VALUE/GRAD elements use its fast path. Scalar row caching supports interior
VALUE/GRAD elements (mass in dimensions 1-3; angular momentum is already 3D).
Unsupported configurations retain the original general application. Density or
geometry changes invalidate scalar rows; Omega/target-only updates reuse them.
The equations, quadrature rules and solver tolerances are unchanged.
These include comparison with the stateless derivative, the general exterior-map
fallback, primal-to-linearization transitions, candidate rejection/recovery,
and Kelvin factor checks. The harness adds independent finite differences and
multiple direction pairs. Compilation alone does not validate their outcomes.
## Preparation and tensor implementation details
Gravity forms the residual quadrature force from the already computed
`rho * w_ref * F * g_ref`; rotation uses `rho * w * acceleration`.
Each then applies the cached displacement test-basis transpose. The optimized
preparation visits geometry once, retains element DOF transforms and true/local
assembly, and synchronizes candidate rejection before collective assembly.
`PrepareReference` retains the separate stateless residual pass. Switching
preparation implementations invalidates the relevant cached result even if
physical dependency revisions are unchanged.
Pressure retains the same local enthalpy matrix and its application. It packs
`-P'(h) * w * grad(test)` once per element and accumulates 32-row by 8-column
matrix tiles with contiguous row access. The original per-quadrature assembly
remains available through `PrepareReference`. EOS, mapping and finite-result
checks remain active; no quadrature points or matrix entries are dropped.
The scalar reference-table cache now owns small one-dimensional value/gradient
tables and a copied lexicographic-to-native DOF map for H1 hexahedra.
Cartesian quadrature ordering and the reconstruction of the existing full
values/gradients are checked once before publishing tensor support. Unsupported
elements/rules use the existing path. Evaluation contracts x, y and z in turn
and produces displacement values and reference gradients, then the hydrostatic
operator applies the same inverse-Jacobian contraction, physical coefficients,
test-basis transpose and assembly. Scratch is reused for one element; no dense
per-element displacement Jacobian is added. The immutable tables own all tensor
data, including when the FE, quadrature rule or cache that created them is gone.

View File

@@ -0,0 +1,222 @@
#!/usr/bin/env python3
"""Read-only, two-direction inexact-Newton selection; no new FEM evaluation.
Usage: python analyze_nonlinear_direction_pair.py LOOSE_CASE TIGHT_CASE NEW_OUTPUT_DIRECTORY
The reports remain preliminary until the separate paired campaign audit passes.
"""
import argparse
import csv
import hashlib
import json
import math
from pathlib import Path
import platform
import sys
import numpy as np
def sha(path):
return hashlib.sha256(path.read_bytes()).hexdigest()
def vector(path):
values = np.loadtxt(path, dtype=float)
assert values.ndim == 1 and int(values[0]) == values.size - 1
values = values[1:]
assert np.all(np.isfinite(values))
return values
def norm(value):
# A distinct summation path checks the small dense model against all saved
# coefficients, without asking the FEM operator for any new action.
wide = np.asarray(value, dtype=np.longdouble)
return float(np.sqrt(np.sum(wide * wide, dtype=np.longdouble)))
def write_vector(path, value):
with path.open("w") as stream:
stream.write(f"{value.size}\n")
np.savetxt(stream, value, fmt="%.17g")
def combine(columns, weights):
# Explicit two-column arithmetic also provides an independent reconstruction
# path from the tall QR factors; no large dense product is needed here.
return columns[:, 0] * weights[0] + columns[:, 1] * weights[1]
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("loose", type=Path)
parser.add_argument("tight", type=Path)
parser.add_argument("output", type=Path)
args = parser.parse_args()
np.seterr(divide="raise", over="raise", invalid="raise")
output = args.output.resolve()
for campaign in (args.loose.resolve().parent, args.tight.resolve().parent):
if output == campaign or campaign in output.parents:
parser.error("Keep analysis outside the immutable campaigns")
if output.exists():
parser.error("Choose a new output directory")
prefix = "nonlinear_step_"
shared = ["physical_base.txt", "normalized_base.txt", "residual.txt", "rhs.txt",
"state_factors.txt", "residual_factors.txt", "layout.csv"]
shared_hashes = {}
for suffix in shared:
a, b = args.loose / (prefix + suffix), args.tight / (prefix + suffix)
assert sha(a) == sha(b), f"Same-state comparison failed: {suffix}"
shared_hashes[suffix] = sha(a)
inputs = {}
for label, directory in [("loose", args.loose), ("tight", args.tight)]:
names = [prefix + name for name in shared + ["direction_full.txt", "action_full.txt"]]
names += ["metadata.txt"]
inputs[label] = {name: {"path": str((directory / name).resolve()),
"sha256": sha(directory / name)} for name in names}
p = np.column_stack([vector(d / (prefix + "direction_full.txt"))
for d in [args.loose, args.tight]])
a = np.column_stack([vector(d / (prefix + "action_full.txt"))
for d in [args.loose, args.tight]])
f = vector(args.loose / (prefix + "residual.txt"))
f_norm = norm(f)
assert p.shape == a.shape == (f.size, 2) and f_norm > 0
eta = 0.03
# A negligible inward margin prevents formatting/roundoff at the active
# inequality from turning an algebraically feasible saved vector into a fail.
safe_eta = eta * (1.0 - 1.0e-10)
q, r = np.linalg.qr(p, mode="reduced")
for i in range(2):
if r[i, i] < 0:
q[:, i] *= -1
r[i, :] *= -1
r_condition = float(np.linalg.cond(r))
assert np.isfinite(r_condition) and r_condition < 1.0e10
q_action = np.empty_like(a)
q_action[:, 0] = a[:, 0] / r[0, 0]
q_action[:, 1] = (a[:, 1] - r[0, 1] * q_action[:, 0]) / r[1, 1]
b = q_action / f_norm
f_unit = f / f_norm
# Work with QR/SVD of the action itself, never normal equations: the two
# input directions can be almost parallel and squared conditioning obscures
# whether a small norm reduction is actually resolved.
u, t = np.linalg.qr(b, mode="reduced")
left, sigma, vt = np.linalg.svd(t, full_matrices=False)
action_basis = np.column_stack([combine(u, left[:, i]) for i in range(2)])
beta = action_basis.T @ f_unit
perpendicular = f_unit - combine(action_basis, beta)
perpendicular_norm = norm(perpendicular)
assert sigma[-1] > 0 and perpendicular_norm < safe_eta
sigma_scaled = sigma / sigma[0]
squared = sigma_scaled * sigma_scaled
def solve(target):
def residual(mu):
retained = beta * mu / (squared + mu)
return math.hypot(perpendicular_norm, norm(retained))
lo, hi = 0.0, 1.0
while residual(hi) < target:
hi *= 2
for _ in range(120):
mid = (lo + hi) / 2
if residual(mid) <= target:
lo = mid
else:
hi = mid
mu = lo
y = -(sigma_scaled / (squared + mu)) * (beta / sigma[0])
z = vt.T @ y
coefficients = np.linalg.solve(r, z)
return z, coefficients, mu, residual(mu)
z, coefficients, mu, projected_defect = solve(safe_eta)
exact_z, _, _, _ = solve(eta)
candidate = combine(p, coefficients)
candidate_action = combine(a, coefficients)
candidate_defect = f + candidate_action
candidate_norm = norm(candidate)
verified_defect = norm(candidate_defect) / f_norm
assert verified_defect <= eta
reconstruction_error = norm(candidate - combine(q, z))
action_reconstruction_error = norm(candidate_action - combine(q_action, z))
# Stationarity and the active boundary provide a convex KKT certificate
# within this two-dimensional subspace; they say nothing about global rank.
mu_physical = mu * sigma[0] ** 2
reduced_residual = t @ z + u.T @ f_unit
kkt = t.T @ reduced_residual + mu_physical * z
kkt_scale = norm(t.T @ reduced_residual) + mu_physical * norm(z)
originals = []
for i, label in enumerate(["loose", "tight"]):
ai = a[:, i] / f_norm
norm_ai = norm(ai)
center = -float(np.dot(f_unit, ai)) / norm_ai ** 2
ray_minimum_defect = norm(f_unit + center * ai)
assert ray_minimum_defect < safe_eta
radius = math.sqrt(safe_eta ** 2 - ray_minimum_defect ** 2) / norm_ai
ray_scale = max(0.0, center - radius)
original_norm = norm(p[:, i])
original_defect = norm(f + a[:, i]) / f_norm
assert original_defect <= (0.03 if i == 0 else 0.003)
ray_norm = ray_scale * original_norm
originals.append({"label": label, "norm": original_norm,
"relative_saved_action_defect": original_defect,
"candidate_norm_reduction_fraction": 1 - candidate_norm / original_norm,
"best_feasible_positive_ray_scale": ray_scale,
"best_feasible_positive_ray_norm": ray_norm,
"extra_fractional_norm_reduction_over_ray": 1 - candidate_norm / ray_norm})
assert candidate_norm <= min(x["best_feasible_positive_ray_norm"] for x in originals) * (1 + 1e-10)
assert norm(kkt) <= 1e-9 * kkt_scale
assert abs(projected_defect - verified_defect) < 1e-10
assert reconstruction_error < 1e-12 * candidate_norm
pair_difference = p[:, 1] - p[:, 0]
difference_action = a[:, 1] - a[:, 0]
output_vectors = {"candidate_normalized.txt": candidate,
"candidate_saved_action.txt": candidate_action,
"candidate_saved_defect.txt": candidate_defect}
output_hashes = {}
args.output.mkdir(exist_ok=False, parents=True)
for name, value in output_vectors.items():
write_vector(args.output / name, value)
output_hashes[name] = sha(args.output / name)
assert np.array_equal(vector(args.output / name), value)
report = {
"status": "preliminary_pending_independent_paired_campaign_audit",
"scope": "Algebraic selection in span of two saved same-state normalized directions. No new FEM action or nonlinear trial.",
"python": sys.executable, "python_version": platform.python_version(), "numpy_version": np.__version__,
"script_sha256": sha(Path(__file__)), "inputs": inputs, "shared_hashes": shared_hashes,
"size": int(f.size), "base_residual_norm": f_norm, "eta": eta, "safe_eta": safe_eta,
"originals": originals,
"pair": {"cosine": float(np.dot(p[:, 0], p[:, 1])) / (norm(p[:, 0]) * norm(p[:, 1])),
"difference_norm": norm(pair_difference),
"difference_relative_to_loose": norm(pair_difference) / norm(p[:, 0]),
"difference_action_norm": norm(difference_action),
"difference_directional_gain": norm(difference_action) / norm(pair_difference)},
"reduced_problem": {"direction_R_condition_2": r_condition,
"action_T_singular_values_relative_to_F": sigma.tolist(),
"action_T_condition_2": float(sigma[0] / sigma[-1]),
"irreducible_relative_defect_in_span": perpendicular_norm,
"orthogonality_error": norm((q.T @ q - np.eye(2)).ravel()),
"scaled_ridge_parameter": mu,
"KKT_relative_residual": norm(kkt) / kkt_scale,
"safety_margin_norm_increment": candidate_norm - norm(exact_z)},
"candidate": {"original_direction_coefficients": coefficients.tolist(),
"orthonormal_coordinates": z.tolist(), "norm": candidate_norm,
"relative_defect_projected": projected_defect,
"relative_defect_full_saved_vectors": verified_defect,
"direction_reconstruction_error": reconstruction_error,
"action_reconstruction_error": action_reconstruction_error,
"output_sha256": output_hashes},
}
(args.output / "assessment.json").write_text(json.dumps(report, indent=2, allow_nan=False) + "\n")
print(json.dumps({k: report[k] for k in ["status", "originals", "pair", "reduced_problem", "candidate"]}, indent=2))
if __name__ == "__main__":
main()

View File

@@ -0,0 +1,366 @@
#!/usr/bin/env python3
"""Describe saved radial surface directions by unweighted nodal angular fits.
These are projections of the sampled coefficient values, not surface-integral
harmonic coefficients. Cubic symmetry can suggest a mesh-related pattern, but
does not establish its cause, physical accuracy, or a nullspace of the solver.
No FEM operations or full-state vector reads are performed.
"""
import argparse
import csv
import hashlib
import itertools
import json
import math
import os
from pathlib import Path
import sys
for _name in ("OPENBLAS_NUM_THREADS", "OMP_NUM_THREADS", "MKL_NUM_THREADS", "VECLIB_MAXIMUM_THREADS"):
os.environ[_name] = "1"
import numpy as np
SURFACE_FILE = "weak_shape_physical_surface_nodes.csv"
DEGREES = (0, 2, 4, 6, 8)
EPS = np.finfo(float).eps
NODE_TOLERANCE = 2e-10
def digest(path):
return hashlib.sha256(Path(path).read_bytes()).hexdigest()
def contract(subscripts, *arrays):
# Direct contraction avoids the Accelerate matmul flag defect documented
# in audit_shape_field_weak.py; finite results remain an explicit check.
if any(not np.isfinite(a).all() for a in arrays):
raise ValueError("Nonfinite contraction input")
result = np.einsum(subscripts, *arrays, optimize=False)
if not np.isfinite(result).all():
raise ValueError("Nonfinite contraction output")
return result
def norm(array):
result = math.sqrt(float(contract("i,i->", array, array)))
if not math.isfinite(result):
raise ValueError("Nonfinite norm")
return result
def harmonics(points, maximum_degree=8):
"""Continuous-L2-normalized real Y_lm, including Condon--Shortley phase.
Recurring on normalized associated Legendre functions avoids separately
generating large factorials and then cancelling them in normalization.
Negative m denotes sine, positive m cosine, with sqrt(2) for nonzero m.
"""
if maximum_degree < 0 or maximum_degree > 8:
raise ValueError("This bounded diagnostic supports degrees zero through eight")
z, phi = points[:, 2], np.arctan2(points[:, 1], points[:, 0])
radial = np.hypot(points[:, 0], points[:, 1])
legendre = {(0, 0): np.full(len(points), 1 / math.sqrt(4 * math.pi))}
for m in range(maximum_degree + 1):
if m:
legendre[m, m] = -math.sqrt((2 * m + 1) / (2 * m)) * radial * legendre[m - 1, m - 1]
if m < maximum_degree:
legendre[m + 1, m] = math.sqrt(2 * m + 3) * z * legendre[m, m]
for degree in range(m + 2, maximum_degree + 1):
a = math.sqrt((4 * degree * degree - 1) / (degree * degree - m * m))
b = math.sqrt(((2 * degree + 1) * ((degree - 1) ** 2 - m * m)) /
((2 * degree - 3) * (degree * degree - m * m)))
legendre[degree, m] = a * z * legendre[degree - 1, m] - b * legendre[degree - 2, m]
labels, columns = [], []
for degree in range(maximum_degree + 1):
for m in range(-degree, degree + 1):
value = legendre[degree, abs(m)]
if m:
value = math.sqrt(2) * value * (np.sin(-m * phi) if m < 0 else np.cos(m * phi))
labels.append({"degree": degree, "m": m})
columns.append(value)
matrix = np.column_stack(columns)
if not np.isfinite(matrix).all():
raise ValueError("Nonfinite harmonic basis")
return matrix, labels
def fit(matrix, values, column_scale=False):
"""Tall-matrix SVD with explicit reconstruction/orthogonality checks."""
if not np.isfinite(matrix).all() or not np.isfinite(values).all():
raise ValueError("Nonfinite fit input")
scales = np.sqrt(contract("ij,ij->j", matrix, matrix)) if column_scale else np.ones(matrix.shape[1])
scales = np.where(scales > 0, scales, 1.)
scaled = matrix / scales
u, singular, vh = np.linalg.svd(scaled, full_matrices=False)
if not all(np.isfinite(a).all() for a in (u, singular, vh)):
raise ValueError("Nonfinite SVD")
cutoff = EPS * max(matrix.shape) * singular[0]
rank = int(np.count_nonzero(singular > cutoff))
scores = contract("ij,i->j", u[:, :rank], values)
coefficients = contract("ji,j->i", vh[:rank], scores / singular[:rank]) / scales
projected = contract("ij,j->i", matrix, coefficients)
remainder = values - projected
reconstruction = contract("ij,jk->ik", u * singular, vh)
factorization_error = norm((reconstruction - scaled).ravel())
factorization_limit = 4096 * EPS * max(norm(scaled.ravel()), 1.)
if factorization_error > factorization_limit:
raise ValueError("SVD reconstruction failed")
# The retained singular directions define the actual numerical projection;
# omitted singular directions need not be resolved by the node set.
orthogonality = norm(contract("ij,i->j", u[:, :rank], remainder))
magnitude = norm(values)
limit = 8192 * EPS * max(magnitude, norm(projected), 1e-300)
if orthogonality > limit:
raise ValueError("Projection orthogonality failed")
error = norm(remainder)
return {"sample_count": len(values), "column_count": matrix.shape[1], "rank": rank,
"full_column_rank": rank == matrix.shape[1], "rank_cutoff": float(cutoff),
"singular_values": singular.tolist(), "column_scaling": "unit nodal L2" if column_scale else "none",
"column_scales": scales.tolist(),
"retained_condition_ratio": float(singular[0] / singular[rank - 1]) if rank else None,
"basis_coefficients": coefficients.tolist(), "nodal_l2_remainder": error,
"relative_nodal_l2_remainder": error / magnitude if magnitude else None,
"explained_nodal_squared_norm_fraction": 1 - (error / magnitude) ** 2 if magnitude else None,
"svd_reconstruction_error": factorization_error, "retained_projection_orthogonality_error": orthogonality}
def cubic_columns(points):
squared = points * points
c4 = np.sum(squared * squared, axis=1) - 3 / 5
# On the unit sphere, the reflection/permutation-invariant polynomial ring
# through degree eight is spanned by 1, e2, e3, e2^2. C4 is an affine
# replacement for e2; e3's spherical mean is 1/105. These columns are not
# individually harmonic or orthogonal, except the pure l=4 C4 column.
e3 = np.prod(squared, axis=1) - 1 / 105
return np.column_stack((np.ones(len(points)), c4, e3, c4 * c4))
def symmetry_projection(points, values):
"""Project onto all signed-permutation invariants if nodes form orbits.
A permutation of the entire node set preserves the unweighted metric.
Without that closure, a nodal group average is not a justified orthogonal
projection; invariant polynomial fits remain separately available.
"""
buckets = {}
for i, point in enumerate(points):
key = tuple(np.rint(point / NODE_TOLERANCE).astype(np.int64))
buckets.setdefault(key, []).append(i)
shifts = tuple(itertools.product((-1, 0, 1), repeat=3))
transforms = []
maximum_error = 0.
for permutation in itertools.permutations(range(3)):
for signs in itertools.product((-1, 1), repeat=3):
image_indices = []
for point in points[:, permutation] * np.asarray(signs):
key = tuple(np.rint(point / NODE_TOLERANCE).astype(np.int64))
candidates = []
for shift in shifts:
for index in buckets.get(tuple(key[k] + shift[k] for k in range(3)), ()):
distance = float(np.max(np.abs(point - points[index])))
if distance <= NODE_TOLERANCE:
candidates.append((distance, index))
if len(candidates) != 1:
return {"status": "unavailable_node_cloud_not_uniquely_closed", "node_tolerance": NODE_TOLERANCE,
"matching_node_count_at_failure": len(candidates),
"scope": "No full cubic projection claimed; polynomial invariant fits remain valid."}
distance, index = candidates[0]
maximum_error = max(maximum_error, distance)
image_indices.append(index)
if len(set(image_indices)) != len(points):
raise ValueError("Cubic transformation did not define a nodal permutation")
transforms.append(image_indices)
indices = np.asarray(transforms, dtype=int)
projected = np.mean(values[indices], axis=0)
error = norm(values - projected)
magnitude = norm(values)
idempotency = norm(np.mean(projected[indices], axis=0) - projected)
cross = abs(float(contract("i,i->", projected, values - projected)))
if idempotency > 4096 * EPS * max(magnitude, 1e-300) or cross > 4096 * EPS * max(magnitude ** 2, 1e-300):
raise ValueError("Cubic nodal projection identities failed")
return {"status": "closed_48_element_group", "node_tolerance": NODE_TOLERANCE,
"maximum_node_matching_error": maximum_error, "nodal_l2_remainder": error,
"relative_nodal_l2_remainder": error / magnitude if magnitude else None,
"invariant_nodal_squared_norm_fraction": 1 - (error / magnitude) ** 2 if magnitude else None,
"projection_idempotency_error": idempotency, "projection_cross_term": cross,
"scope": "All signed coordinate permutations in the saved Cartesian axes; unweighted nodal group average."}
def read_surface(path):
with path.open(newline="") as stream:
reader = csv.DictReader(stream)
required = {"parameter", "volume_scalar_true_dof", "unit_radial_x", "unit_radial_y", "unit_radial_z",
"reference_radius", "physical_radius", "base_parameter", "physical_direction_parameter"}
if not reader.fieldnames or len(set(reader.fieldnames)) != len(reader.fieldnames) or not required <= set(reader.fieldnames):
raise ValueError("Missing or duplicate surface CSV columns")
rows = list(reader)
if not rows or any(None in r or any(v is None for v in r.values()) for r in rows):
raise ValueError("Empty or malformed surface CSV")
data = {k: np.asarray([float(r[k]) for r in rows]) for k in required}
if any(not np.isfinite(a).all() for a in data.values()):
raise ValueError("Nonfinite surface data")
if not np.array_equal(data["parameter"], np.arange(len(rows))):
raise ValueError("Noncontiguous surface parameter indices")
identifiers = data["volume_scalar_true_dof"]
if np.any(identifiers < 0) or np.any(identifiers != np.floor(identifiers)) or len(set(identifiers)) != len(rows):
raise ValueError("Invalid or repeated surface degree of freedom")
if np.any(data["reference_radius"] <= 0) or np.any(data["physical_radius"] <= 0):
raise ValueError("Nonpositive surface radius")
discrepancy = np.abs(data["physical_radius"] - data["reference_radius"] - data["base_parameter"])
if np.any(discrepancy > 2048 * EPS * (data["physical_radius"] + data["reference_radius"] + np.abs(data["base_parameter"]))):
raise ValueError("Physical radius identity failed")
points = np.column_stack([data["unit_radial_" + axis] for axis in "xyz"])
lengths = np.sqrt(contract("ij,ij->i", points, points))
unit_error = float(np.max(np.abs(lengths - 1)))
if unit_error > 5e-10:
raise ValueError("Surface radial directions are not unit length")
# Remove decimal-rounding length error before the spherical recurrence.
return points / lengths[:, None], data["physical_direction_parameter"], unit_error, data
def analyze(path):
path = Path(path).resolve()
if path.is_dir():
path /= SURFACE_FILE
points, values, unit_error, surface_data = read_surface(path)
source_hash = digest(path)
binding = {"status": "input_hash_only"}
run_path = path.parent.parent / (path.parent.name + "_run.json")
if run_path.exists():
run = json.loads(run_path.read_text())
if run.get("output_hashes", {}).get(path.name) != source_hash:
raise ValueError("Surface file does not match runner output hash")
binding = {"status": "runner_surface_hash_checked", "run_path": str(run_path), "run_sha256": digest(run_path),
"scope": "Only this surface artifact binding; no independent audit of the complete FEM campaign."}
matrix, labels = harmonics(points)
harmonic_fits = [{"maximum_degree": degree, **fit(matrix[:, :(degree + 1) ** 2], values)} for degree in DEGREES]
cubic = cubic_columns(points)
invariant_fits = [{"maximum_degree": degree, **fit(cubic[:, :count], values, True)}
for degree, count in ((0, 1), (2, 1), (4, 2), (6, 3), (8, 4))]
return {"surface_file": str(path), "surface_sha256": source_hash, "binding": binding,
"sample_count": len(points), "maximum_original_unit_length_error": unit_error,
"base_surface_radius": {
"scope": "unweighted nodal statistics; extrema bound observed asphericity, not full-surface extrema",
"reference_minimum": float(np.min(surface_data["reference_radius"])),
"reference_maximum": float(np.max(surface_data["reference_radius"])),
"physical_minimum": float(np.min(surface_data["physical_radius"])),
"physical_maximum": float(np.max(surface_data["physical_radius"])),
"physical_mean": float(np.mean(surface_data["physical_radius"])),
"physical_span_over_mean": float(np.ptp(surface_data["physical_radius"]) / np.mean(surface_data["physical_radius"])),
"maximum_absolute_base_parameter": float(np.max(np.abs(surface_data["base_parameter"])))},
"direction_nodal_l2": norm(values), "direction_maximum_absolute": float(np.max(np.abs(values))),
"harmonic_basis": {"normalization": "continuous unit-sphere L2 orthonormal real Y_lm with Condon--Shortley phase",
"ordering": labels, "negative_m": "sine", "positive_m": "cosine"},
"harmonic_fits": harmonic_fits,
"cubic_invariant_basis": ["1", "x^4+y^4+z^4-3/5", "x^2*y^2*z^2-1/105", "(x^4+y^4+z^4-3/5)^2"],
"cubic_invariant_fits": invariant_fits, "full_cubic_nodal_projection": symmetry_projection(points, values)}
def self_test():
# Product quadrature integrates products through l=8 exactly, independently
# checking the recurrence's normalization, phase and degree organization.
z, weights = np.polynomial.legendre.leggauss(9)
phi = np.arange(18) * (2 * math.pi / 18)
points = np.asarray([(math.sqrt(1 - q * q) * math.cos(t), math.sqrt(1 - q * q) * math.sin(t), q) for q in z for t in phi])
quadrature = np.repeat(weights, len(phi)) * (2 * math.pi / len(phi))
matrix, labels = harmonics(points)
gram = contract("ki,k,kj->ij", matrix, quadrature, matrix)
assert np.max(np.abs(gram - np.eye(81))) < 8e-14
assert np.max(np.abs(matrix[:, 2] - math.sqrt(3 / (4 * math.pi)) * points[:, 2])) < 1e-15
assert np.max(np.abs(matrix[:, 3] + math.sqrt(3 / (4 * math.pi)) * points[:, 0])) < 1e-15
for degree in range(9):
columns = matrix[:, degree * degree:(degree + 1) ** 2]
assert np.max(np.abs(np.sum(columns * columns, axis=1) - (2 * degree + 1) / (4 * math.pi))) < 2e-14
cubic = cubic_columns(points)
assert fit(matrix[:, :9], cubic[:, 1])["relative_nodal_l2_remainder"] > .8
assert fit(matrix[:, :25], cubic[:, 1])["relative_nodal_l2_remainder"] < 1e-13
for degree in DEGREES:
values = matrix[:, degree * degree]
result = fit(matrix[:, :(degree + 1) ** 2], values)
assert result["rank"] == (degree + 1) ** 2 and result["relative_nodal_l2_remainder"] < 1e-13
assert fit(matrix[:, :1], np.zeros(len(points)))["relative_nodal_l2_remainder"] is None
assert fit(np.column_stack((matrix[:, 0], matrix[:, 0])), matrix[:, 0])["rank"] == 1
cloud = []
for seed in ((1, 2, 3), (1, 3, 5), (2, 3, 7), (1, 4, 9)):
for permutation in itertools.permutations(seed):
for signs in itertools.product((-1, 1), repeat=3):
point = np.asarray(permutation, dtype=float) * signs
cloud.append(point / np.linalg.norm(point))
cloud = np.asarray(cloud)
cubic = cubic_columns(cloud)
invariant = contract("ij,j->i", cubic, np.asarray((.4, 2., -7., .6)))
assert fit(cubic, invariant, True)["relative_nodal_l2_remainder"] < 1e-13
assert symmetry_projection(cloud, invariant)["relative_nodal_l2_remainder"] < 1e-13
antisymmetric = cloud[:, 0]
result = symmetry_projection(cloud, invariant + antisymmetric)
assert abs(result["nodal_l2_remainder"] - norm(antisymmetric)) < 1e-12
assert symmetry_projection(cloud[:-1], invariant[:-1])["status"] == "unavailable_node_cloud_not_uniquely_closed"
# Bind the analysis to a tiny real CSV and reject corruption in both parser
# and runner certificate, without reading any campaign artifacts.
import tempfile
with tempfile.TemporaryDirectory() as tmp:
root = Path(tmp)
folder = root / "case"
folder.mkdir()
path = folder / SURFACE_FILE
columns = ["parameter", "volume_scalar_true_dof", "unit_radial_x", "unit_radial_y", "unit_radial_z",
"reference_radius", "physical_radius", "base_parameter", "physical_direction_parameter"]
with path.open("w", newline="") as stream:
writer = csv.writer(stream)
writer.writerow(columns)
for i, (point, value) in enumerate(zip(cloud, invariant)):
writer.writerow([i, i, *point, 1., 1., 0., value])
run = root / "case_run.json"
run.write_text(json.dumps({"output_hashes": {SURFACE_FILE: digest(path)}}))
assert analyze(folder)["binding"]["status"] == "runner_surface_hash_checked"
run.write_text(json.dumps({"output_hashes": {SURFACE_FILE: "0" * 64}}))
try:
analyze(folder)
except ValueError as exc:
assert "runner output hash" in str(exc)
else:
raise AssertionError("Corrupted source hash passed")
path.write_text(path.read_text().replace(",1.0,1.0,0.0,", ",nan,1.0,0.0,", 1))
try:
read_surface(path)
except ValueError as exc:
assert "Nonfinite" in str(exc)
else:
raise AssertionError("Nonfinite source passed")
print("Tiny harmonic, invariant, symmetry, rank and artifact-binding fixtures passed")
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("inputs", nargs="*", help="Probe directories or saved surface-node CSV files")
parser.add_argument("--output", type=Path)
parser.add_argument("--self-test", action="store_true")
args = parser.parse_args()
if args.self_test:
if args.inputs or args.output:
parser.error("Self-test does not consume campaign inputs or create an output")
self_test()
return 0
if not args.inputs or not args.output:
parser.error("Provide surface inputs and a fresh output JSON")
output = args.output.resolve()
if output.exists() or any(output.is_relative_to(Path(p).resolve() if Path(p).is_dir() else Path(p).resolve().parent) for p in args.inputs):
parser.error("Use a fresh output outside the immutable input directories")
cases = []
for path in args.inputs:
try:
cases.append({"analysis_pass": True, **analyze(path)})
except (ValueError, OSError, KeyError, np.linalg.LinAlgError) as exc:
cases.append({"input": str(Path(path).resolve()), "analysis_pass": False, "error": str(exc)})
result = {"schema_version": 1, "passed": all(c["analysis_pass"] for c in cases),
"analyzer_sha256": digest(__file__), "numpy_version": np.__version__,
"scope": "Unweighted nodal projections of the physical radial direction. Not area-weighted harmonic power, not a continuum symmetry or solver-nullspace certificate.",
"cases": cases}
output.parent.mkdir(parents=True, exist_ok=True)
output.write_text(json.dumps(result, indent=2, allow_nan=False) + "\n")
print(f"{'PASS' if result['passed'] else 'FAIL'}: {len(cases)} surface analyses; {output}")
return 0 if result["passed"] else 1
if __name__ == "__main__":
sys.exit(main())

View File

@@ -0,0 +1,926 @@
#!/usr/bin/env python3
"""Audit frozen density-order controls and short coupled campaigns.
Run only after the serial FEM workload. Saved polynomial algebra, sums, input
binding and reported gates are checked; mapped weights and local M,b are not
exported, so this is not an independent FEM projection/integration. No sampled
result is promoted to a global positivity or converged-physics certificate.
"""
from __future__ import annotations
import argparse
from collections import defaultdict
from decimal import Decimal, localcontext
import json
import math
from pathlib import Path
import tempfile
import unittest
import audit_negative_density_regions as common
EPS = 2.220446049250313e-16
ORDERS = (14, 22, 30)
CONTROLS = ("eos_nodal_interpolation", "eos_l2_q26")
BOUNDS = common.NEGATIVE_BOUNDS
SUMS = common.SUM_FIELDS + (
"negative_mass_uncertainty_scale", "first_moment_x", "first_moment_y", "first_moment_z", "inertia_z",
"negative_enthalpy_samples", "resolved_negative_intervals", "uncertain_negative_intervals",
"resolved_witness_negative_volume", "resolved_witness_negative_mass", "uncertain_negative_volume",
"uncertain_negative_mass")
EOS_SUMS = ("target_mass", "eos_squared_integral", "signed_eos_integral")
require, close, rows, metadata, keyed, digest = (
common.require, common.close, common.rows, common.metadata, common.keyed, common.digest)
class Campaign(common.Campaign):
def run(self, name):
if name not in self.runs:
r = json.loads(self.record(self.path / f"{name}_run.json").read_text())
require(r["id"] == name and r["exit_code"] in (0, 3) and r["inputs_unchanged"] is True,
f"Incomplete/changed run {name}")
expected = [str(self.path / "plateau_diagnostic"), *self.cases[name]["arguments"],
"--mesh", self.provenance["mesh"], "--output", str(self.path / name)]
require(r["command"] == expected, f"Manifest/command mismatch: {name}")
for path, value in r["input_state_hashes"].items():
require(digest(self.record(Path(path))) == value, f"Changed input: {path}")
self.runs[name] = r
return self.runs[name]
def vector(path):
with path.open() as stream:
size = int(next(stream))
result = [float(line) for line in stream]
require(size == len(result) and size > 0 and all(map(math.isfinite, result)), f"Invalid vector {path}")
return result
def numeric(row, omit=("control",)):
return {k: float(v) for k, v in row.items() if k not in omit}
def enthalpy_observations(records, key):
values = [row[key] for row in records]
require(all(map(math.isfinite, values)), "Nonfinite saved enthalpy observation")
return {"samples": len(values), "minimum_enthalpy": min(values) if values else None,
"negative_enthalpy_samples": sum(value < 0 for value in values)}
def poly_value(coefficients, x):
value = coefficients[-1]
for coefficient in reversed(coefficients[:-1]):
value = value * x + coefficient
return value
def decimal_roots(coefficients):
"""Bracket derivative-separated real roots using 60-digit arithmetic.
Unlike the producer's compensated binary arithmetic, the saved decimal
coefficients define this independent polynomial. Exact repeated roots may
move under serialization; shallow intervals retain their uncertainty label.
"""
c = list(coefficients)
while len(c) > 1 and c[-1] == 0:
c.pop()
if len(c) == 1:
return []
if len(c) == 2:
root = -c[0] / c[1]
return [root] if 0 <= root <= 1 else []
derivative = [i * c[i] for i in range(1, len(c))]
cuts = sorted(set([Decimal(0), Decimal(1), *decimal_roots(derivative)]))
result = [point for point in cuts if poly_value(c, point) == 0]
for left, right in zip(cuts, cuts[1:]):
fl, fr = poly_value(c, left), poly_value(c, right)
if not fl or not fr or (fl < 0) == (fr < 0):
continue
for _ in range(100):
middle = (left + right) / 2
fm = poly_value(c, middle)
if not fm:
left = right = middle
break
if (fm < 0) == (fl < 0):
left, fl = middle, fm
else:
right = middle
result.append((left + right) / 2)
return sorted(set(result))
def independent_partition(coefficient_strings):
with localcontext() as context:
context.prec = 60
c = [Decimal(v) for v in coefficient_strings]
cuts = sorted(set([Decimal(0), Decimal(1), *decimal_roots(c)]))
# A repeated exact root can acquire a pocket at the last Decimal digit
# after the derivative root is rounded. It has no distinct binary64
# endpoints and cannot correspond to an exported interval.
negative = [(float(a), float(b)) for a, b in zip(cuts, cuts[1:])
if float(a) < float(b) and poly_value(c, (a + b) / 2) < 0]
critical = decimal_roots([i * c[i] for i in range(1, len(c))])
return negative, [float(x) for x in critical]
def interval_line(line, gauss_nodes):
first = line[0]
coefficient_keys = [f"c{i}" for i in range(5)]
c = [float(first[k]) for k in coefficient_keys]
degree = int(first["degree"])
require(degree in (2, 3, 4) and all(c[i] == 0 for i in range(degree + 1, 5)), "Wrong polynomial degree")
require(all(all(row[k] == first[k] for k in coefficient_keys) for row in line), "Inconsistent line polynomial")
scale = math.fsum(map(abs, c))
tolerance = 2048 * EPS * scale
expected, critical = independent_partition([first[k] for k in coefficient_keys])
parsed = sorted([numeric(row) for row in line], key=lambda r: r["t_left"])
for index, r in enumerate(parsed):
common.finite(r)
require(r["axis"] in (0, 1, 2) and r["orientation"] in (-1, 1), "Invalid interval axis")
for coordinate in (r["u"], r["v"]):
require(min(abs(coordinate - node) for node in gauss_nodes) < 2e-14, "Interval is not at its Gauss node")
a, b = r["t_left"], r["t_right"]
require(0 <= a < b <= 1 and (index == 0 or parsed[index - 1]["t_right"] <= a), "Overlapping/outside interval")
close(r["reconstruction_tolerance"], tolerance, "Coefficient-scaled interval tolerance", atol=1e-30)
require(r["negative_volume"] > 0 and r["negative_mass"] >= 0, "Invalid negative measure")
require(r["resolved_negative_witness"] in (0, 1) and
bool(r["resolved_negative_witness"]) == (r["minimum_density"] < -tolerance), "Witness classification changed")
samples = [a, b, (a + b) / 2, a + .25 * (b - a), a + .75 * (b - a)]
samples += [x for x in critical if a < x < b]
# Evaluate the decimal polynomial at the saved endpoints/critical points;
# ordinary binary Horner could invent signs in the shallow Q4 tails.
with localcontext() as context:
context.prec = 60
exact = [Decimal(first[k]) for k in coefficient_keys]
values = [float(poly_value(exact, Decimal.from_float(x))) for x in samples]
allowance = tolerance + 128 * EPS * scale
require(max(values) <= allowance, "Positive interior of alleged negative interval")
require(abs(r["minimum_density"] - min(values)) <= allowance, "Polynomial/FE minimum disagrees")
for endpoint in (a, b):
if endpoint not in (0., 1.):
require(abs(float(poly_value(exact, Decimal.from_float(endpoint)))) <= allowance, "Interval endpoint is not a root")
require(r["negative_mass"] / r["negative_volume"] <= -min(values) + allowance,
"Negative mass exceeds polynomial minimum times volume")
# Only lines whose every exported pocket has a resolved FE witness demand
# one-to-one root matching. Rounded near-tangent tails are retained, not
# silently recast as a sign certificate or discarded from the integrals.
resolved = all(r["resolved_negative_witness"] for r in parsed)
if resolved:
require(len(parsed) == len(expected), "Missing/extra resolved negative interval")
for r, (left, right) in zip(parsed, expected):
for got, wanted in ((r["t_left"], left), (r["t_right"], right)):
if wanted in (0., 1.):
require(got == wanted, "Missing cell endpoint")
else:
derivative = abs(math.fsum(i * c[i] * wanted ** (i - 1) for i in range(1, 5)))
# Coefficient-scaled function uncertainty divided by the
# root slope. Saturating the slope prevents an unbounded
# location allowance at a multiple root.
allowance = max(128 * EPS, tolerance / max(derivative, math.sqrt(tolerance * scale)))
close(got, wanted, "Independent polynomial root", rtol=0, atol=allowance)
return parsed, resolved
def measure_check(r):
allowed = list(BOUNDS) if r["negative_intervals"] == 0 else []
if r["negative_enthalpy_samples"]:
allowed += EOS_SUMS
if r["mass"] == 0:
allowed += ["negative_mass_fraction"]
common.finite(r, allowed)
require(r["degree"] in (2, 3, 4) and r["interval_order"] == 14 and r["tangential_order"] in ORDERS,
"Unexpected density/quadrature degree")
require(r["volume"] > 0 and 0 <= r["negative_volume"] <= r["volume"] and r["negative_mass"] >= 0,
"Invalid region measure")
close(r["negative_volume_fraction"], r["negative_volume"] / r["volume"], "Negative volume fraction")
if r["mass"]:
close(r["negative_mass_fraction"], r["negative_mass"] / abs(r["mass"]), "Negative mass fraction")
require(r["maximum_reconstruction_error"] <= r["maximum_reconstruction_tolerance"], "Reconstruction gate failed")
require(r["eos_defined_everywhere_sampled"] == (r["negative_enthalpy_samples"] == 0), "EOS definition flag")
for key in ("negative_intervals", "resolved_negative_intervals", "uncertain_negative_intervals",
"negative_enthalpy_samples", "tangent_lines", "integration_points"):
require(r[key] >= 0 and r[key].is_integer(), f"Invalid count {key}")
require(r["resolved_negative_intervals"] + r["uncertain_negative_intervals"] == r["negative_intervals"],
"Negative classification counts")
for quantity in ("mass", "volume"):
close(r[f"resolved_witness_negative_{quantity}"] + r[f"uncertain_negative_{quantity}"],
r[f"negative_{quantity}"], "Resolved/uncertain measure decomposition")
if r["negative_intervals"] == 0:
require(r["negative_volume"] == r["negative_mass"] == 0 and all(math.isnan(r[k]) for k in BOUNDS),
"Empty-negative-region convention")
else:
require(0 <= r["negative_interval_t_minimum"] < r["negative_interval_t_maximum"] <= 1 and
0 <= r["negative_radius_minimum"] <= r["negative_radius_maximum"], "Negative region bounds")
if not r["negative_enthalpy_samples"]:
require(r["eos_squared_integral"] >= 0 and r["target_mass"] >= 0, "Invalid EOS integral")
close(r["signed_eos_integral"], r["mass"] - r["target_mass"], "Signed EOS integral",
rtol=2e-10, atol=256 * EPS * max(abs(r["mass"]), r["target_mass"]))
else:
require(all(math.isnan(r[k]) for k in EOS_SUMS), "Undefined EOS integral fabricated")
def audit_measures(get, expected_controls, n, K):
summary = keyed(rows(get("density_order_summary.csv")),
lambda r: (r["control"], int(r["degree"]), int(r["tangential_order"])))
require(set(summary) == {(c, d, q) for c, d in expected_controls for q in ORDERS}, "Missing order/control summary")
elements = keyed(rows(get("density_order_elements.csv")),
lambda r: (r["control"], int(r["degree"]), int(r["tangential_order"]), int(r["element"])))
support = {element for _, _, _, element in elements}
require(set(elements) == {(*key, e) for key in summary for e in support}, "Element support differs between controls")
totals = {key: numeric(row) for key, row in summary.items()}
elemental = {key: numeric(row) for key, row in elements.items()}
for key, total in totals.items():
measure_check(total)
subset = [elemental[(*key, e)] for e in support]
for r in subset:
measure_check(r)
require(r["tangent_lines"] == (key[2] // 2 + 1) ** 2 and r["witness_element"] == r["element"] and
r["axis"] in (0, 1, 2) and r["orientation"] in (-1, 1), "Element axis/count mismatch")
require(r["integration_points"] % 8 == 0 and
8 * r["tangent_lines"] <= r["integration_points"] <= 8 * (key[1] + 1) * r["tangent_lines"],
"Interval quadrature count mismatch")
for field in SUMS:
scale = math.fsum(abs(r[field]) for r in subset)
close(math.fsum(r[field] for r in subset), total[field], "Element/global " + field,
atol=128 * EPS * max(scale, 1e-25))
if total["eos_defined_everywhere_sampled"]:
for field in EOS_SUMS:
close(math.fsum(r[field] for r in subset), total[field], "Element/global " + field,
atol=128 * EPS * math.fsum(abs(r[field]) for r in subset))
for field in ("minimum_density", "minimum_enthalpy"):
close(min(r[field] for r in subset), total[field], "Element/global minimum")
witness = elemental[(*key, int(total["witness_element"]))]
for field in ("minimum_density", "witness_h", "witness_t", "witness_u", "witness_v", "witness_x", "witness_y", "witness_z"):
close(witness[field], total[field], "Global witness binding", atol=1e-15)
nonempty = [r for r in subset if r["negative_intervals"]]
if nonempty:
for field, operation in zip(BOUNDS, (min, max, min, max)):
close(operation(r[field] for r in nonempty), total[field], "Global negative bound")
for field in ("maximum_reconstruction_error", "maximum_reconstruction_tolerance"):
close(max(r[field] for r in subset), total[field], "Global reconstruction maximum")
lines, pieces = defaultdict(list), defaultdict(list)
for row in rows(get("density_order_intervals.csv")):
key = row["control"], int(row["degree"]), int(row["element"])
require((*key[:2], 30, key[2]) in elements, "Interval unsupported element/control")
lines[(*key, row["u"], row["v"])].append(row)
resolved_lines = 0
gauss_nodes = [x for x, _ in common.gauss_rule(16)]
for key, line in lines.items():
parsed, resolved = interval_line(line, gauss_nodes)
resolved_lines += resolved
element = elemental[(*key[:2], 30, key[2])]
require(all(r["axis"] == element["axis"] and r["orientation"] == element["orientation"] for r in parsed),
"Interval geometry differs from element")
pieces[key[:3]].extend(parsed)
for control, degree in expected_controls:
for element in support:
saved = pieces[(control, degree, element)]
total = elemental[(control, degree, 30, element)]
require(len(saved) == total["negative_intervals"], "Finest interval coverage")
for field in ("negative_mass", "negative_volume"):
close(math.fsum(r[field] for r in saved), total[field], "Interval/element " + field)
for resolved, prefix in ((True, "resolved_witness"), (False, "uncertain")):
subset = [r for r in saved if bool(r["resolved_negative_witness"]) == resolved]
count_field = "resolved_negative_intervals" if resolved else "uncertain_negative_intervals"
require(len(subset) == total[count_field], "Interval resolved/uncertain count")
for quantity in ("mass", "volume"):
close(math.fsum(r[f"negative_{quantity}"] for r in subset), total[f"{prefix}_negative_{quantity}"],
"Interval classification sum")
if saved:
close(min(r["t_left"] for r in saved), total["negative_interval_t_minimum"], "Finest left bound")
close(max(r["t_right"] for r in saved), total["negative_interval_t_maximum"], "Finest right bound")
surface = defaultdict(list)
for row in rows(get("density_order_surface.csv")):
key = row["control"], int(row["degree"])
require(key in expected_controls and int(row["element"]) in support, "Surface unsupported control")
r = numeric(row)
common.finite(r, ("rho_eos", "error") if r["h"] < 0 else ())
require(r["u"] in (0, .25, .5, .75, 1) and r["v"] in (0, .25, .5, .75, 1), "Surface sampling changed")
require(r["eos_defined"] == (r["h"] >= 0) and r["resolved_negative"] == (r["rho"] < -r["reconstruction_tolerance"]),
"Surface classification contradiction")
if r["h"] >= 0:
close(r["rho_eos"], (r["h"] / ((n + 1) * K)) ** n, "Surface EOS", atol=1e-30)
close(r["error"], r["rho"] - r["rho_eos"], "Surface EOS difference", atol=1e-30)
else:
require(math.isnan(r["rho_eos"]) and math.isnan(r["error"]), "Undefined surface EOS fabricated")
surface[key].append(r)
result = {}
for control, degree in sorted(expected_controls):
key = control, degree
traces = surface[key]
require(traces, "Missing surface samples")
unique = {(r["face"], r["u"], r["v"]) for r in traces}
require(len(unique) == len(traces) == 25 * len({r["face"] for r in traces}), "Surface coverage")
witnesses = [row for element in support for row in pieces[(control, degree, element)]]
result[f"Q{degree}/{control}"] = {
"summary": {str(q): totals[(control, degree, q)] for q in ORDERS},
"summary_enthalpy_scope": "Integration nodes only; EOS availability flags do not cover boundary samples or density-minimum witnesses.",
"surface": {"samples": len(traces), "minimum_density": min(r["rho"] for r in traces),
"negative_samples": sum(r["rho"] < 0 for r in traces),
"resolved_negative_samples": sum(r["resolved_negative"] for r in traces),
"enthalpy": {**enthalpy_observations(traces, "h"),
"scope": "Saved one-sided 5-by-5 face samples; counts are not volume or area fractions."}},
"negative_interval_witness_enthalpy": {**enthalpy_observations(witnesses, "witness_h"),
"scope": "One saved density-minimum witness per exported negative interval on order30 tangential lines; this is not an enthalpy-extremum search."},
"negative_mass_q30_minus_q22": totals[(control, degree, 30)]["negative_mass"] - totals[(control, degree, 22)]["negative_mass"],
"negative_volume_q30_minus_q22": totals[(control, degree, 30)]["negative_volume"] - totals[(control, degree, 22)]["negative_volume"]}
return result, support, totals, {"negative_lines": len(lines), "fully_resolved_negative_lines": resolved_lines}
def audit_selfchecks(table):
expected = {"positive_constant": (0., 0.), "negative_constant": (1., 2.),
"linear_crossing": (.25, .03125), "quadratic_interior_pocket": (math.sqrt(6) / 15, math.sqrt(6) / 2250),
"cubic_interior_pocket": (.5, 1 / 96), "quartic_two_pockets": (.5, 19 / 15360),
"quartic_double_roots_nonnegative": (0., 0.),
**{f"reconstruct_t_power_{d}": (0., 0.) for d in (2, 3, 4)}}
table = keyed(table, lambda row: row["case"])
require(table.keys() == expected.keys(), "Self-check coverage")
for name, (length, mass) in expected.items():
r = numeric(table[name], ("case",))
common.finite(r)
require(r["passed"] == 1, "Producer root self-check failed")
for key, value in (("negative_length", length), ("expected_negative_length", length),
("negative_mass", mass), ("expected_negative_mass", mass)):
close(r[key], value, "Independent analytic self-check " + name, atol=2e-18)
def audit_projection(get, support, n, K, totals):
elements = keyed(rows(get("density_order_projection_elements.csv")), lambda r: (int(r["degree"]), int(r["element"])))
require(set(elements) == {(d, e) for d in (2, 3, 4) for e in support}, "Projection element coverage")
by_element = defaultdict(list)
vectors = {(d, c): vector(get(f"density_order_Q{d}_{c}_coefficients.txt")) for d in (2, 3, 4) for c in CONTROLS}
seen = defaultdict(set)
degree_nodes = {degree: [x for x, _ in common.gauss_rule(degree + 1)] for degree in (2, 3, 4)}
for row in rows(get("density_order_nodes.csv")):
r = numeric(row, ())
common.finite(r)
degree, element, local, glob = (int(r[k]) for k in ("degree", "element", "local_dof", "global_dof"))
require((degree, element) in elements and r["h"] >= 0, "Invalid nodal projection support/enthalpy")
require(0 <= local < (degree + 1) ** 3 and glob not in seen[degree], "Duplicate/invalid DG dof")
require(glob == element * (degree + 1) ** 3 + local, "Serial DG element ordering changed")
seen[degree].add(glob)
nodes = degree_nodes[degree]
for coordinate in (r["xi"], r["eta"], r["zeta"]):
require(min(abs(coordinate - x) for x in nodes) < 2e-14, "Wrong interpolation nodes")
close(r["target_rho"], (r["h"] / ((n + 1) * K)) ** n, "Nodal EOS target", atol=1e-30)
require(r["interpolation_coefficient"] == r["target_rho"], "Interpolation is not EOS at the node")
for control, field in zip(CONTROLS, ("interpolation_coefficient", "projection_coefficient")):
require(0 <= glob < len(vectors[(degree, control)]) and vectors[(degree, control)][glob] == r[field],
"Node/coefficient vector disagreement")
by_element[(degree, element)].append(r)
result = {}
for (degree, element), row in elements.items():
r = numeric(row, ("basis_family",))
common.finite(r)
node_rows = by_element[(degree, element)]
require(len(node_rows) == r["dofs"] == (degree + 1) ** 3 and
{int(v["local_dof"]) for v in node_rows} == set(range((degree + 1) ** 3)), "Nodal element coverage")
require(len({(v["xi"], v["eta"], v["zeta"]) for v in node_rows}) == len(node_rows), "Duplicate tensor nodes")
require(r["quadrature_request"] == 26 and r["quadrature_achieved"] == 27 and
r["quadrature_points"] == 14 ** 3 and "L2" in row["basis_family"], "Projection rule/basis changed")
require(r["rhs_norm"] > 0 and 0 <= r["normal_defect_norm"] and r["normal_relative_defect"] < 1e-10,
"Reported local normal solve gate failed")
close(r["normal_relative_defect"], r["normal_defect_norm"] / r["rhs_norm"], "Normal defect ratio")
require(0 <= r["constant_coefficient_error"] < 1e-10 and 0 <= r["constant_sample_error"] < 1e-10,
"Constant reconstruction failed")
close(r["projection_mass"], r["target_mass"], "Local projection mass", rtol=2e-11)
require(r["projection_eos_squared"] >= 0 and r["interpolation_eos_squared"] >= 0 and
r["projection_eos_squared"] <= r["interpolation_eos_squared"] + 512 * EPS * r["target_mass"] ** 2 / r["volume"],
"Reported orthogonal projection exceeds interpolation error")
for field, operation, source in (("interpolation_coefficient_minimum", min, "interpolation_coefficient"),
("projection_coefficient_minimum", min, "projection_coefficient"),
("projection_coefficient_maximum", max, "projection_coefficient")):
require(r[field] == operation(v[source] for v in node_rows), "Projection coefficient extrema")
for degree in (2, 3, 4):
data = [numeric(row, ("basis_family",)) for (d, _), row in elements.items() if d == degree]
totals26 = {k: math.fsum(r[k] for r in data) for k in
("volume", "target_mass", "interpolation_mass", "projection_mass", "interpolation_eos_squared", "projection_eos_squared")}
for control, key in zip(CONTROLS, ("interpolation_mass", "projection_mass")):
fine = totals[(control, degree, 30)]
close(totals26[key], fine["mass"], "Q26/sliced mass", rtol=2e-9, atol=1e-13)
close(totals26["volume"], fine["volume"], "Q26/sliced volume", rtol=2e-9, atol=1e-13)
for control in CONTROLS:
require(all(value == 0 for i, value in enumerate(vectors[(degree, control)]) if i not in seen[degree]),
"Control density outside stellar support is nonzero")
result[f"Q{degree}"] = {**totals26, "maximum_reported_relative_normal_defect": max(r["normal_relative_defect"] for r in data),
"active_density_dofs": len(seen[degree]), "full_density_storage": len(vectors[(degree, CONTROLS[0])])}
return result
def audit_error_quadrature(get, controls, support, totals, frozen):
table = keyed(rows(get("density_order_error_quadrature.csv")),
lambda r: (r["control"], int(r["degree"]), int(r["quadrature_request"]), int(r["element"])))
require(set(table) == {(c, d, q, e) for c, d in controls for q in (26, 30) for e in support},
"Independent error-rule coverage")
projection = keyed(rows(get("density_order_projection_elements.csv")),
lambda r: (int(r["degree"]), int(r["element"]))) if frozen else {}
results = {}
for control, degree in sorted(controls):
result = {}
for order in (26, 30):
records = []
for element in support:
r = numeric(table[(control, degree, order, element)])
common.finite(r, EOS_SUMS if r["negative_enthalpy_samples"] else ())
require(r["quadrature_achieved"] == order + 1 and r["quadrature_points"] == (order // 2 + 1) ** 3,
"Independent error quadrature changed")
require(r["volume"] > 0 and r["negative_enthalpy_samples"] >= 0 and
r["eos_defined_everywhere_sampled"] == (r["negative_enthalpy_samples"] == 0), "Independent error validity")
if r["negative_enthalpy_samples"]:
require(all(math.isnan(r[k]) for k in EOS_SUMS), "Undefined independent EOS integrals fabricated")
else:
require(r["target_mass"] >= 0 and r["eos_squared_integral"] >= 0, "Invalid independent EOS integrals")
close(r["signed_eos_integral"], r["mass"] - r["target_mass"], "Independent signed EOS error",
atol=256 * EPS * max(abs(r["mass"]), r["target_mass"]))
if frozen and order == 26:
p = numeric(projection[(degree, element)], ("basis_family",))
label = "interpolation" if control == CONTROLS[0] else "projection"
for field, source in (("volume", "volume"), ("target_mass", "target_mass"),
("mass", label + "_mass"), ("eos_squared_integral", label + "_eos_squared")):
require(r[field] == p[source], "Q26 error/projection assembly binding")
records.append(r)
valid = all(r["eos_defined_everywhere_sampled"] for r in records)
global_values = {key: math.fsum(r[key] for r in records) for key in
("volume", "mass", "negative_enthalpy_samples")}
global_values.update({key: math.fsum(r[key] for r in records) if valid else math.nan for key in EOS_SUMS})
global_values["eos_defined_everywhere_sampled"] = valid
global_values["minimum_density"] = min(r["minimum_density"] for r in records)
global_values["minimum_enthalpy"] = min(r["minimum_enthalpy"] for r in records)
global_values["eos_rms"] = math.sqrt(global_values["eos_squared_integral"] / global_values["volume"]) if valid else math.nan
result[str(order)] = global_values
for key in ("mass", "volume"):
close(global_values[key], totals[(control, degree, 30)][key], "Unsliced/sliced " + key, rtol=2e-9, atol=1e-13)
result["eos_squared_q30_minus_q26"] = result["30"]["eos_squared_integral"] - result["26"]["eos_squared_integral"]
result["sliced_eos_squared_minus_q30"] = totals[(control, degree, 30)]["eos_squared_integral"] - result["30"]["eos_squared_integral"]
results[f"Q{degree}/{control}"] = result
return results
def bind_density(state, full_density, block, degree, support):
"""Bind the supported serial, discontinuous tensor element ordering.
Frozen nodal exports separately validate this global/local indexing rule.
No general parallel/continuous-field gather convention is assumed here.
"""
width = (degree + 1) ** 3
require(len(full_density) % width == 0 and max(support) < len(full_density) // width, "Full DG density dimensions")
active = [element * width + j for element in sorted(support) for j in range(width)]
selected = set(active)
require(all(v == 0 for i, v in enumerate(full_density) if i not in selected), "Density outside support nonzero")
offset, size = int(block["offset"]), int(block["size"])
require(size == len(active) and state[offset:offset + size] == [full_density[i] for i in active],
"Accepted/observed density does not bind to its full DG storage")
def physical(get, filename, meta):
table = keyed(rows(get(filename)), lambda r: (int(r["quadrature"]), r["metric"]))
result = {}
for q in sorted({q for q, _ in table}):
m = {name: float(row["value"]) for (order, name), row in table.items() if order == q}
require(not any(math.isinf(v) for v in m.values()), "Infinite physical observation")
for key in ("mass", "volume", "binding_energy", "kinetic_energy", "minimum_density", "minimum_enthalpy"):
require(math.isfinite(m[key]), "Nonfinite physical " + key)
require(m["complete_volume_measurement"] == 1, "Incomplete physical volume observation")
close(m["polytropic_index"], float(meta["n"]), "Physical index")
close(m["polytropic_constant"], float(meta["K"]), "Physical K")
passes = {}
for prefix, pressure, defined_key in (("", "pressure_integral", "pressure_from_density_defined_everywhere"),
("enthalpy_", "enthalpy_pressure_integral", "pressure_from_enthalpy_defined_everywhere")):
require(m[defined_key] in (0, 1), "Invalid pressure definition flag")
for force, energy in (("", "binding_energy"), ("force_", "force_binding_energy")):
key = prefix + force + "virial_"
if m[defined_key]:
terms = 2 * m["kinetic_energy"], m[energy], 3 * m[pressure]
expected = math.fsum(terms) / abs(m["binding_energy"])
close(m[key + "signed"], expected, "Virial scalar identity", atol=2e-14)
close(m[key + "error"], abs(m[key + "signed"]), "Virial absolute identity")
passes[key + "within_1e5"] = m[key + "error"] <= 1e-5
else:
require(math.isnan(m[key + "signed"]) and math.isnan(m[key + "error"]), "Undefined virial fabricated")
passes[key + "within_1e5"] = None
if "mass_absolute_error" in m:
close(m["mass_absolute_error"], abs(m["mass"] - float(meta["M"])), "Physical mass error", atol=1e-15)
close(m["angular_momentum_absolute_error"], abs(m["angular_momentum_z"] - float(meta["J"])), "Physical J error", atol=1e-15)
result[str(q)] = {"metrics": m, "virial_milestones": passes,
"undefined_metrics": [k for k, v in m.items() if math.isnan(v)]}
return result
def audit_closure_rules(table, support):
rules = keyed(table, lambda row: int(row["element"]))
require(set(rules) == support, "Closure quadrature support differs from the stellar elements")
counts = defaultdict(int)
for row in rules.values():
require(set(row) == {"element", "quadrature_order", "quadrature_points"}, "Closure rule schema changed")
achieved, points = int(row["quadrature_order"]), int(row["quadrature_points"])
require(achieved > 0 and points > 0 and achieved % 2 == 1, "Invalid achieved tensor Gauss rule")
per_axis = (achieved + 1) // 2
require(points == per_axis ** 3, "Achieved order and tensor Gauss point count disagree")
counts[(achieved, points)] += 1
return {"scope": "Actual IntegrationRule achieved order and point count; the requested policy order is not exported.",
"stellar_elements": len(rules),
"distinct_achieved_orders": sorted({order for order, _ in counts}),
"distinct_point_counts": sorted({points for _, points in counts}),
"rules": [{"achieved_order": order, "quadrature_points": points,
"points_per_axis": (order + 1) // 2, "elements": count}
for (order, points), count in sorted(counts.items())]}
def audit_line_search(table, history, initial_residual, strategy):
require(strategy == "baseline", "Trial audit currently covers the recorded baseline policy only")
# Reviewed against LineSearchTrialDisposition in solver/newton.cppm and
# PreparationStageName/line-search dispatch in solver/stellar_context.cppm.
dispositions = {0: "accepted", 1: "inadmissible_state", 2: "non_finite_state",
3: "non_finite_residual", 4: "insufficient_decrease", 5: "auxiliary_solve_failure"}
stages = {"generated geometry", "gravity", "barotropic closure", "hydrostatic equilibrium",
"displacement residual", "pressure force", "gravity displacement force", "rotational displacement force",
"displacement composition", "mass normalization", "model specification", "unspecified preparation", "unknown preparation"}
grouped, source_counts, disposition_counts, joint_counts = defaultdict(list), defaultdict(int), defaultdict(int), defaultdict(int)
saved = []
for raw in table:
r = {**numeric(raw, ("source",)), "source": raw["source"]}
iteration, trial, code = int(raw["iteration"]), int(raw["trial"]), int(raw["disposition"])
require(iteration >= 0 and trial >= 0 and code in dispositions, "Invalid trial index/disposition")
require(math.isfinite(r["alpha"]) and 0 < r["alpha"] <= 1, "Invalid trial step length")
require(not saved or (iteration, trial) > (int(saved[-1]["iteration"]), int(saved[-1]["trial"])), "Trial log is not sequential")
require(trial == len(grouped[iteration]), "Missing/repeated trial within an iteration")
if grouped[iteration]:
require(r["alpha"] < grouped[iteration][-1]["alpha"], "Backtracking trial did not shorten the step")
require(grouped[iteration][-1]["disposition"] != 0, "Trial recorded after acceptance")
source = r["source"]
if code == 0:
require(source == "", "Accepted trial has a rejection source")
elif code == 4:
require(source == "residual metric", "Insufficient decrease source mismatch")
elif code == 1:
require(source in stages or source == "enthalpy polynomial", "Inadmissible-state source mismatch")
elif code == 2:
require(source in stages or source == "candidate state", "Nonfinite-state source mismatch")
elif code == 3:
require(source in stages or source in ("normalized residual", "residual metric"), "Nonfinite-residual source mismatch")
else:
require(False, "Baseline monolithic trial unexpectedly reports an auxiliary solve failure")
if code in (0, 4):
require(math.isfinite(r["F"]) and r["F"] >= 0 and math.isfinite(r["min_jacobian"]) and r["min_jacobian"] > 0,
"Metric-evaluated trial lacks finite residual/valid geometry")
elif source != "residual metric":
require(math.isnan(r["F"]), "Rejected preparation has a fabricated residual metric")
require(math.isfinite(r["min_jacobian"]) or math.isnan(r["min_jacobian"]), "Invalid optional trial geometry")
grouped[iteration].append(r)
saved.append(r)
source_counts[source] += 1
disposition_counts[dispositions[code]] += 1
joint_counts[(source, code)] += 1
history_by_iteration = keyed(history, lambda row: int(row["iteration"]))
require(set(grouped) <= set(history_by_iteration), "Trials lack an after-iteration record")
previous = initial_residual
accepted_alphas = []
for iteration, row in sorted(history_by_iteration.items()):
trials = grouped[iteration]
require(len(trials) == row["trials"], "Trial/iteration count mismatch")
accepted = [r for r in trials if r["disposition"] == 0]
require(len(accepted) == int(row["accepted"]), "Trial/iteration acceptance mismatch")
for trial in trials:
if trial["disposition"] in (0, 4):
limit = previous * math.sqrt(1 - 1e-4 * trial["alpha"])
allowance = 128 * EPS * max(previous, trial["F"])
if trial["disposition"] == 0:
require(trial["F"] <= limit + allowance, "Accepted baseline trial fails recorded merit inequality")
else:
require(trial["F"] >= limit - allowance, "Rejected baseline metric satisfies decrease away from rounding")
if accepted:
require(accepted[0] is trials[-1], "Accepted trial was not the last attempt")
close(accepted[0]["alpha"], row["alpha"], "Accepted alpha binding")
close(accepted[0]["F"], row["F"], "Accepted residual binding")
accepted_alphas.append(row["alpha"])
else:
require(row["alpha"] == 0, "Failed iteration has a nonzero accepted step")
close(row["F"], previous, "Failed iteration residual restoration")
previous = row["F"]
return {"scope": "Recorded baseline trial stages and metric inequalities; rejected preparation has no evaluated residual metric. Geometry may shorten the backtracking ladder.",
"disposition_enum": {str(code): name for code, name in dispositions.items()},
"total_trials": len(saved), "counts_by_source": dict(sorted(source_counts.items())),
"counts_by_disposition": dict(sorted(disposition_counts.items())),
"source_disposition_counts": [{"source": source, "disposition": dispositions[code], "disposition_code": code, "count": count}
for (source, code), count in sorted(joint_counts.items())],
"pressure_force_rejections": sum(r["source"] == "pressure force" and r["disposition"] != 0 for r in saved),
"residual_metric_rejections": sum(r["source"] == "residual metric" and r["disposition"] != 0 for r in saved),
"residual_metric_insufficient_decrease_rejections": sum(r["source"] == "residual metric" and r["disposition"] == 4 for r in saved),
"minimum_accepted_alpha": min(accepted_alphas) if accepted_alphas else None, "trials": saved}
def audit_case(campaign, name):
get = lambda filename: campaign.artifact(name, filename)
record = campaign.run(name)
meta = metadata(get("metadata.txt"))
scope = metadata(get("density_order_scope.txt"))
require(scope["source_fields_bitwise_identical"] == "1" and scope["trial_preparations"] == "0" and scope["mpi_ranks"] == "1",
"Observer changed source fields/state")
n, K = float(meta["n"]), float(meta["K"])
for key in ("n", "K"):
close(float(scope[key]), float(meta[key]), "Scope model")
degree = int(meta["density_order"])
require(degree in (2, 3, 4) and degree == int(scope["source_density_degree"]), "Source degree binding")
for key, expected in (("enthalpy_order", 3), ("gravity_potential_order", 2), ("gravity_flux_order", 2), ("displacement_order", 3)):
require(int(meta[key]) == expected, "Non-density field order changed: " + key)
settings = campaign.provenance["build_settings"]
require(int(settings["MEAN_FIELD_DENSITY_POLYNOMIAL_ORDER:STRING"]) == degree and
int(settings["MEAN_FIELD_UNIFORM_POLYNOMIAL_ORDER_INCREMENT:STRING"]) == 0, "Build/order metadata contradiction")
frozen = scope["projection_controls"] == "1"
require(meta["density_order_projection"] == str(int(frozen)) and meta["density_order_final"] == str(int(not frozen)),
"Control mode mismatch")
require(meta["surface_prescription"] == "harmonics" and int(meta["surface_degree"]) == 4 and int(meta["surface_maximum_order"]) == -1,
"Surface prescription changed in density-only study")
audit_selfchecks(rows(get("density_order_root_selfchecks.csv")))
controls = {(c, d) for c in CONTROLS for d in (2, 3, 4)} if frozen else {("stored_density", degree)}
measures, support, totals, intervals = audit_measures(get, controls, n, K)
closure_rule_file = "production_closure_rules.csv" if frozen else "final_closure_rules.csv"
closure_rules = audit_closure_rules(rows(get(closure_rule_file)), support)
closure_rules["source_artifact"] = closure_rule_file
error_quadrature = audit_error_quadrature(get, controls, support, totals, frozen)
timing_rows = keyed(rows(get("density_order_timings.csv")), lambda r: r["phase"])
require(set(timing_rows) == {"setup_and_projection", "independent_error_quadrature", "region_observation_and_output", "observer_total"},
"Observer timing scope changed")
timing = {phase: float(row["seconds"]) for phase, row in timing_rows.items()}
require(all(math.isfinite(v) and v >= 0 for v in timing.values()), "Invalid observer timing")
close(math.fsum(value for phase, value in timing.items() if phase != "observer_total"), timing["observer_total"],
"Observer phase-time partition", atol=1e-8)
layout = rows(get("layout.csv"))
blocks = keyed(layout, lambda r: (r["kind"], r["block"]))
state = vector(get("observed_state.txt" if frozen else "accepted_state.txt"))
for kind in ("value", "residual"):
ordered = sorted([r for r in layout if r["kind"] == kind], key=lambda r: int(r["offset"]))
end = 0
for r in ordered:
require(int(r["offset"]) == end and int(r["size"]) > 0 and math.isfinite(float(r["scale"])), "Invalid block layout")
end += int(r["size"])
require(end == len(state), "Layout/state dimensions")
require(int(blocks[("value", "density")]["size"]) == len(support) * (degree + 1) ** 3 and
int(blocks[("residual", "barotropic_closure")]["size"]) == len(support) * (degree + 1) ** 3,
"Active density/closure dof count")
result = {"artifact_passed": True, "kind": "frozen" if frozen else "coupled", "n": n, "K": K,
"J": float(meta["J"]), "density_degree": degree, "state_size": len(state), "stellar_elements": len(support),
"block_sizes": {f"{kind}/{block}": int(row["size"]) for (kind, block), row in blocks.items()},
"measures": measures, "interval_audit": intervals, "unsliced_error_quadrature": error_quadrature,
"closure_quadrature": closure_rules,
"observer_timings": timing,
"run": {k: record[k] for k in ("exit_code", "seconds", "utc_elapsed_seconds", "utc_minus_monotonic_seconds", "child_cpu_seconds")}}
if frozen:
require(record["exit_code"] == 0, "Frozen observer did not complete")
invariant = {r["metric"]: float(r["value"]) for r in rows(get("density_invariants.csv"))}
common.finite(invariant)
require(all(invariant[k] == 1 for k in ("accepted_physical_unchanged", "accepted_normalized_unchanged", "accepted_residual_unchanged")),
"Frozen accepted-state invariant")
result["invariants"] = invariant
result["projection"] = audit_projection(get, support, n, K, totals)
result["physical"] = physical(get, "density_physical.csv", meta)
# The runner binds all replay metadata. Add an exact state-content test,
# which also distinguishes a replay from the observer's untouched seed.
inputs = record["input_state_hashes"]
previous = [Path(path) for path in inputs if Path(path).name == "accepted_state.txt"]
if previous:
require(len(previous) == 1 and state == vector(previous[0]), "Frozen snapshot changed")
density = vector(get("observed_density_coefficients.txt"))
bind_density(state, density, blocks[("value", "density")], degree, support)
else:
result["initial_physical"] = physical(get, "initial_physical.csv", meta)
result["physical"] = physical(get, "final_physical.csv", meta)
density = vector(get("density_order_stored_density_coefficients.txt"))
bind_density(state, density, blocks[("value", "density")], degree, support)
result["density_storage_size"] = len(density)
history = [numeric(row, ()) for row in rows(get("newton.csv"))]
accepted = [row for row in history if row["accepted"] == 1]
require(len(accepted) == int(meta["accepted_steps"]) and bool(int(meta["converged"])) == (record["exit_code"] == 0),
"Convergence/exit/accepted-count contradiction")
for i, row in enumerate(history):
require(row["iteration"] == i and row["accepted"] in (0, 1), "Iteration ordering")
for key in ("F", "seconds", "linear_seconds", "prepare_seconds", "refresh_seconds"):
require(math.isfinite(row[key]) and row[key] >= 0, "Invalid iteration metric")
if row["accepted"]:
require(0 < row["alpha"] <= 1 and row["linear_status"] == 0 and
row["linear_true"] <= float(meta["linear_tol"]) * (1 + 1e-10), "Accepted step without reported linear gate")
if row["linear_rhs_norm"] > 0:
close(row["linear_initial_over_rhs"], row["linear_initial_residual"] / row["linear_rhs_norm"], "Initial linear defect ratio")
final_f = result["physical"]["18"]["metrics"]["normalized_bordered_residual"]
initial_f = result["initial_physical"]["18"]["metrics"]["normalized_bordered_residual"]
result["line_search"] = audit_line_search(rows(get("trials.csv")), history, initial_f, meta["strategy"])
if history:
close(history[-1]["F"], final_f, "Final residual/log binding")
threshold = max(float(meta["atol"]), float(meta["rtol"]) * initial_f)
if int(meta["converged"]):
require(final_f <= threshold * (1 + 1e-10), "Reported nonlinear convergence threshold fails")
result["newton"] = {"converged": bool(int(meta["converged"])), "failure": meta.get("failure"),
"accepted_steps": len(accepted), "initial_residual": initial_f, "final_residual": final_f,
"threshold": threshold, "iterations": history,
"iteration_seconds": math.fsum(r["seconds"] for r in history),
"linear_iterations": sum(int(r["linear_iterations"]) for r in history)}
fine = totals[("stored_density", degree, 30)]
physical18 = result["physical"]["18"]["metrics"]
for region_key, physical_key in (("mass", "mass"), ("volume", "volume")):
close(fine[region_key], physical18[physical_key], "Sliced/physical " + region_key, rtol=2e-9, atol=1e-13)
# Position factors raise the normal polynomial degree beyond the
# eight-point sliced rule's exactness. Tangential refinement does not
# test that error, so moment differences are observations, not identities.
radius = float(meta["R_reference"])
require(math.isfinite(radius) and radius > 0, "Invalid reference radius")
moment_comparisons = {"scope": "Order14 normal slicing versus unsliced q18; first moments and inertia may have normal quadrature error."}
values = [("inertia_z", physical18["moment_of_inertia_z"], 2)]
for j, axis in enumerate("xyz"):
values.append((f"first_moment_{axis}", physical18[f"center_of_mass_{j}"] * physical18["mass"], 1))
for key, reference, power in values:
require(math.isfinite(fine[key]) and math.isfinite(reference), "Nonfinite moment observation")
difference = fine[key] - reference
mass_radius_scale = abs(physical18["mass"]) * radius ** power
moment_comparisons[key] = {"sliced": fine[key], "physical_q18": reference, "difference": difference,
"difference_over_mass_radius_power": difference / mass_radius_scale if mass_radius_scale else None}
result["sliced_vs_physical_moments"] = moment_comparisons
return result
class SelfTests(unittest.TestCase):
def test_trial_sources_and_sequential_binding(self):
trial_rows = [dict(iteration="0", trial="0", alpha="1", disposition="1", source="pressure force", F="nan", min_jacobian="nan"),
dict(iteration="0", trial="1", alpha="0.5", disposition="4", source="residual metric", F="1.1", min_jacobian=".8"),
dict(iteration="0", trial="2", alpha="0.25", disposition="0", source="", F=".8", min_jacobian=".9")]
history = [dict(iteration=0., trials=3., accepted=1., alpha=.25, F=.8)]
result = audit_line_search(trial_rows, history, 1., "baseline")
self.assertEqual(result["pressure_force_rejections"], 1)
self.assertEqual(result["residual_metric_rejections"], 1)
self.assertEqual(result["minimum_accepted_alpha"], .25)
for index, key, value in ((0, "F", "1"), (1, "F", ".7"), (1, "trial", "2"),
(2, "alpha", ".5"), (2, "source", "pressure force"), (2, "F", ".7")):
altered = [dict(row) for row in trial_rows]
altered[index][key] = value
with self.subTest(key=key), self.assertRaises(AssertionError):
audit_line_search(altered, history, 1., "baseline")
failed = [dict(iteration=0., trials=0., accepted=0., alpha=0., F=1.)]
self.assertIsNone(audit_line_search([], failed, 1., "baseline")["minimum_accepted_alpha"])
def test_actual_closure_rule_support_and_tensor_counts(self):
rows = [{"element": "2", "quadrature_order": "19", "quadrature_points": "1000"},
{"element": "5", "quadrature_order": "21", "quadrature_points": "1331"}]
result = audit_closure_rules(rows, {2, 5})
self.assertEqual(result["distinct_achieved_orders"], [19, 21])
self.assertEqual(result["distinct_point_counts"], [1000, 1331])
for altered in (rows[:1], rows + [rows[0]],
[{**rows[0], "element": "3"}, rows[1]],
[{**rows[0], "quadrature_order": "20"}, rows[1]],
[{**rows[0], "quadrature_order": "0"}, rows[1]],
[{**rows[0], "quadrature_points": "1001"}, rows[1]]):
with self.assertRaises(AssertionError):
audit_closure_rules(altered, {2, 5})
def test_separate_enthalpy_observations(self):
self.assertEqual(enthalpy_observations([], "h"),
{"samples": 0, "minimum_enthalpy": None, "negative_enthalpy_samples": 0})
self.assertEqual(enthalpy_observations([{"h": -1e-18}, {"h": 0.}, {"h": 1.}], "h"),
{"samples": 3, "minimum_enthalpy": -1e-18, "negative_enthalpy_samples": 1})
with self.assertRaises(AssertionError):
enthalpy_observations([{"witness_h": math.nan}], "witness_h")
def test_independent_roots(self):
cases = ((["0", ".1875", "-1", "1", "0"], [(.25, .75)]),
([".025634765625", "-.34375", "1.34375", "-2", "1"], [(.125, .375), (.625, .875)]),
([".03515625", "-.375", "1.375", "-2", "1"], []))
for c, expected in cases:
self.assertEqual(independent_partition(c)[0], expected)
def test_resolved_narrow_quartic(self):
delta = 2. ** -20
c = [.25 - delta ** 2, -1, 1.25 - delta ** 2, -1, 1]
actual = independent_partition([str(v) for v in c])[0]
self.assertEqual(len(actual), 1)
for got, expected in zip(actual[0], (.5 - delta, .5 + delta)):
close(got, expected, "Narrow quartic root", atol=1e-11)
def test_density_state_binding(self):
full = [0.] * 81
full[27:54] = [i / 10 for i in range(27)]
state = [99., *full[27:54], 88.]
block = {"offset": "1", "size": "27"}
bind_density(state, full, block, 2, {1})
for target, position in ((full, 0), (state, 3)):
original = target[position]
target[position] = .12345
with self.assertRaises(AssertionError):
bind_density(state, full, block, 2, {1})
target[position] = original
def test_unsliced_error_binding(self):
import csv
with tempfile.TemporaryDirectory() as directory:
path = Path(directory) / "density_order_error_quadrature.csv"
records = [dict(control="stored_density", degree=3, element=0, attribute=1,
quadrature_request=q, quadrature_achieved=q+1, quadrature_points=(q//2+1)**3,
volume=1, mass=.25, target_mass=.25, eos_squared_integral=.001,
signed_eos_integral=0, minimum_density=0, minimum_enthalpy=.1,
negative_enthalpy_samples=0, eos_defined_everywhere_sampled=1) for q in (26, 30)]
def write():
with path.open("w", newline="") as stream:
writer = csv.DictWriter(stream, fieldnames=list(records[0]))
writer.writeheader()
writer.writerows(records)
totals = {("stored_density", 3, 30): {"volume": 1., "mass": .25, "eos_squared_integral": .002}}
write()
result = audit_error_quadrature(lambda _: path, {("stored_density", 3)}, {0}, totals, False)
self.assertEqual(result["Q3/stored_density"]["sliced_eos_squared_minus_q30"], .001)
for key, value in (("quadrature_achieved", 29), ("signed_eos_integral", .1),
("eos_defined_everywhere_sampled", 0), ("mass", .3)):
original = records[1][key]
records[1][key] = value
write()
with self.subTest(key=key), self.assertRaises(AssertionError):
audit_error_quadrature(lambda _: path, {("stored_density", 3)}, {0}, totals, False)
records[1][key] = original
def fixture(self):
node = common.gauss_rule(16)[3][0]
return {k: str(v) for k, v in dict(control="stored_density", degree=3, element=0, axis=0, orientation=1,
u=node, v=node, t_left=.25, t_right=.75, c0=0, c1=.1875, c2=-1, c3=1, c4=0,
negative_volume=.5, negative_mass=1/96, minimum_density=-.033009119061284215,
witness_h=1, reconstruction_tolerance=2048 * EPS * 2.1875, resolved_negative_witness=1).items()}
def test_valid_and_corrupted_interval(self):
r = self.fixture()
critical = independent_partition([r[f"c{i}"] for i in range(5)])[1]
c = [float(r[f"c{i}"]) for i in range(5)]
r["minimum_density"] = str(min(poly_value(c, x) for x in critical if .25 < x < .75))
nodes = [x for x, _ in common.gauss_rule(16)]
interval_line([r], nodes)
for key, value in (("t_right", ".8"), ("negative_mass", "2"), ("minimum_density", "-.5"),
("resolved_negative_witness", "0"), ("witness_h", "nan"), ("u", ".5")):
with self.subTest(key=key), self.assertRaises(AssertionError):
interval_line([{**r, key: value}], nodes)
def test_hash_corruption(self):
with tempfile.TemporaryDirectory() as directory:
folder = Path(directory)
(folder / "case").mkdir()
item = folder / "case/value.txt"
item.write_text("original")
campaign = object.__new__(Campaign)
campaign.path, campaign.ledger = folder, {}
campaign.runs = {"case": {"output_hashes": {"value.txt": digest(item)}}}
campaign.artifact("case", "value.txt")
item.write_text("changed")
with self.assertRaises(AssertionError):
campaign.artifact("case", "value.txt")
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("campaigns", nargs="*", type=Path)
parser.add_argument("--output", type=Path)
parser.add_argument("--self-test", action="store_true")
args = parser.parse_args()
if args.self_test:
test = unittest.TextTestRunner(verbosity=2).run(unittest.defaultTestLoader.loadTestsFromTestCase(SelfTests))
if not test.wasSuccessful():
raise SystemExit(1)
if not args.campaigns:
return
if not args.campaigns or args.output is None:
parser.error("Supply one or more completed campaigns and --output")
report = {"artifact_passed": True, "auditor_sha256": digest(Path(__file__)),
"scope": __doc__, "limitations": ["Local projection M,b and mapped weights are not exported.",
"Complete negative partitions are checked only on lines with exported negative intervals; no global positivity claim.",
"Shallow unresolved witnesses remain recorded; root position tests have coefficient-scaled allowances.",
"Tangential convergence does not establish accuracy of the fixed eight-point normal rule; sliced first moments and inertia are compared observationally with q18.",
"Density order alone changes among field spaces; production closure quadrature may also change under the unchanged order-aware policy. Only actual exported rules are reported.",
"Coupled timing and convergence gates are producer observations, not independent equation evaluations."],
"campaigns": {}, "consumed_sha256": {str(Path(common.__file__).resolve()): digest(Path(common.__file__))}}
comparable = defaultdict(list)
for path in args.campaigns:
campaign = Campaign(path)
records = {}
for name in campaign.cases:
try:
records[name] = audit_case(campaign, name)
key = records[name]["kind"], records[name]["n"], records[name]["J"]
comparable[key].append((str(path), name, records[name]))
except (AssertionError, KeyError, ValueError, OSError, StopIteration) as error:
records[name] = {"artifact_passed": False, "error": str(error)}
report["artifact_passed"] = False
report["campaigns"][str(campaign.path)] = {"producer_commit": campaign.provenance["commit"],
"mesh_sha256": campaign.provenance["mesh_sha256"], "cases": records}
report["consumed_sha256"].update(campaign.ledger)
# A cross-order comparison must leave every non-density block dimension
# fixed. Different state-vector lengths are expected for density alone.
for key, records in comparable.items():
reference = {k: v for k, v in records[0][2]["block_sizes"].items()
if k not in ("value/density", "residual/barotropic_closure")}
for _, name, record in records[1:]:
actual = {k: v for k, v in record["block_sizes"].items()
if k not in ("value/density", "residual/barotropic_closure")}
if actual != reference:
report["artifact_passed"] = False
record["cross_order_error"] = "Non-density layout changed in " + str(key) + "/" + name
args.output.parent.mkdir(parents=True, exist_ok=True)
args.output.write_text(json.dumps(common.clean(report), indent=2, allow_nan=False) + "\n")
print("PASS" if report["artifact_passed"] else "FAIL", args.output)
raise SystemExit(0 if report["artifact_passed"] else 1)
if __name__ == "__main__":
main()

View File

@@ -0,0 +1,244 @@
#!/usr/bin/env python3
"""Audit frozen density observations and summarize their physical location.
This checks saved arithmetic and provenance, not a second FEM implementation.
The projection and production closure are independently assembled in C++.
"""
import argparse
import csv
import hashlib
import json
import math
from pathlib import Path
import numpy as np
def digest(path):
return hashlib.sha256(path.read_bytes()).hexdigest()
def rows(path):
with path.open() as stream:
return list(csv.DictReader(stream))
def vector(path):
value = np.loadtxt(path)
if value.ndim != 1 or int(value[0]) != len(value) - 1 or not np.all(np.isfinite(value)):
raise ValueError(f"Invalid saved vector: {path}")
return value[1:]
def require(condition, message):
if not condition:
raise AssertionError(message)
def close(left, right, label, rtol=2e-10, atol=1e-15):
require(math.isfinite(left) and math.isfinite(right) and math.isclose(left, right, rel_tol=rtol, abs_tol=atol),
f"{label}: {left} != {right}")
def require_complete_hashes(record):
required = {'metadata.txt', 'density_summary.csv', 'density_elements.csv', 'density_radial_bins.csv',
'density_physical.csv', 'negative_density_samples.csv', 'negative_density_projection_elements.csv',
'production_closure_rules.csv', 'production_closure_residual_full.txt',
'projection_production_closure_residual_full.txt', 'observed_density_coefficients.txt',
'density_invariants.csv', 'density_element_topology.csv', 'density_surface_traces.csv'}
required.update(f'negative_density_projection_{control}_coefficients.txt' for control in ('production', 'q18', 'q26'))
require(required <= record['output_hashes'].keys(), 'Run record omits a consumed artifact hash.')
def clean(value):
if isinstance(value, dict):
return {str(k): clean(v) for k, v in value.items()}
if isinstance(value, list):
return [clean(v) for v in value]
if isinstance(value, float) and not math.isfinite(value):
return None
return value
def numeric(row, omit=()):
return {key: float(value) for key, value in row.items() if key not in omit}
def audit_case(folder):
meta = dict(line.split('=', 1) for line in (folder / 'metadata.txt').read_text().splitlines() if '=' in line)
n, K = float(meta['n']), float(meta['K'])
summary = {(int(r['quadrature']), r['field']): numeric(r, ('quadrature', 'field'))
for r in rows(folder / 'density_summary.csv')}
element_rows = rows(folder / 'density_elements.csv')
for (order, field), totals in summary.items():
matching = [numeric(r, ('quadrature', 'field', 'element', 'attribute', 'surface_layer'))
for r in element_rows if int(r['quadrature']) == order and r['field'] == field]
for key in ('samples', 'negative_samples', 'negative_h_samples', 'joint_negative_samples',
'volume', 'mass', 'negative_mass', 'negative_volume', 'negative_h_volume', 'closure_squared_integral'):
close(math.fsum(r[key] for r in matching), totals[key], f"element sum {order}/{field}/{key}")
close(min(r['minimum_density'] for r in matching), totals['minimum_density'], 'element minimum')
close(max(r['maximum_density'] for r in matching), totals['maximum_density'], 'element maximum')
radial = [numeric(r, ('quadrature', 'field', 'radial_bin_left', 'radial_bin_right'))
for r in rows(folder / 'density_radial_bins.csv')
if int(r['quadrature']) == order and r['field'] == field]
for key in ('volume', 'mass', 'negative_mass', 'negative_volume'):
close(math.fsum(r[key] for r in radial), totals[key], f"radial sum {order}/{field}/{key}")
physical = {r['metric']: float(r['value']) for r in rows(folder / 'density_physical.csv')}
observed18, observed26 = summary[(18, 'state')], summary[(26, 'state')]
for key, physical_key in [('minimum_density', 'minimum_density'), ('minimum_h', 'minimum_enthalpy'),
('volume', 'volume'), ('mass', 'mass'), ('negative_mass', 'negative_density_mass_magnitude'),
('negative_samples', 'negative_density_samples'), ('negative_h_samples', 'negative_enthalpy_samples')]:
close(observed18[key], physical[physical_key], f"physical observer {key}")
close(observed18['negative_volume'] / observed18['volume'], physical['negative_density_volume_fraction'],
'physical negative volume fraction')
negative = rows(folder / 'negative_density_samples.csv')
require(len(negative) == observed26['negative_samples'], 'Sparse negative sample count does not bind to complete observation.')
for r in negative:
rho, h = float(r['rho']), float(r['h'])
require(rho < 0 and int(r['quadrature']) == 26, 'Unexpected negative sample record.')
close(float(r['radius']), math.sqrt(sum(float(r[d]) ** 2 for d in ('x', 'y', 'z'))), 'negative sample radius')
close(float(r['rho_from_h']), (h / ((n + 1) * K)) ** n if h > 0 else 0., 'negative sample EOS')
close(math.fsum(float(r['weight']) for r in negative), observed26['negative_volume'], 'negative export volume')
close(math.fsum(-float(r['weight']) * float(r['rho']) for r in negative), observed26['negative_mass'], 'negative export mass')
projection_rows = rows(folder / 'negative_density_projection_elements.csv')
production = {int(r['element']): r for r in projection_rows if r['control'] == 'production'}
actual_rules = {int(r['element']): r for r in rows(folder / 'production_closure_rules.csv')}
require(production.keys() == actual_rules.keys(), 'Projection support differs from the actual closure.')
for element, r in production.items():
rule = actual_rules[element]
# MFEM may report the achieved odd Gauss degree for an even requested
# degree. Equal points and this exact one-degree alias are intentional.
requested, achieved = int(r['quadrature_order']), int(rule['quadrature_order'])
require(achieved in (requested, requested + 1) and r['quadrature_points'] == rule['quadrature_points'],
f"Production quadrature mismatch in element {element}.")
actual = vector(folder / 'production_closure_residual_full.txt')
reconstructed = vector(folder / 'projection_production_closure_residual_full.txt')
require(actual.shape == reconstructed.shape, 'Full closure residual layout mismatch.')
difference = actual - reconstructed
rhs_norm = math.sqrt(math.fsum(float(r['rhs_norm']) ** 2 for r in production.values()))
allowance = 2048 * np.finfo(float).eps * rhs_norm
defect_norm = float(np.linalg.norm(difference))
require(defect_norm <= allowance, f"Independent closure residual mismatch {defect_norm}, allowance {allowance}.")
saved = vector(folder / 'observed_density_coefficients.txt')
coefficient_comparison = {}
for control in ('production', 'q18', 'q26'):
projected = vector(folder / f'negative_density_projection_{control}_coefficients.txt')
require(projected.shape == saved.shape, 'Projected coefficient layout mismatch.')
delta = projected - saved
matching = [r for r in projection_rows if r['control'] == control]
maximum = float(np.max(np.abs(delta)))
close(maximum, max(float(r['coefficient_maximum_difference']) for r in matching), 'coefficient error summary')
close(float(np.linalg.norm(delta)), math.sqrt(math.fsum(float(r['coefficient_difference_norm']) ** 2 for r in matching)),
'coefficient difference norm assembled from disjoint elements')
for row in matching:
require(float(row['constant_coefficient_error_maximum']) < 1e-10 and
float(row['constant_sample_error_maximum']) < 1e-10,
'Independent constant reproduction failed.')
coefficient_comparison[control] = dict(maximum_absolute_difference=maximum,
l2_coefficient_difference=float(np.linalg.norm(delta)),
relative_l2_coefficient_difference=float(np.linalg.norm(delta) / np.linalg.norm(saved)))
invariants = {r['metric']: float(r['value']) for r in rows(folder / 'density_invariants.csv')}
require(all(invariants[k] == 1 for k in ('accepted_physical_unchanged', 'accepted_normalized_unchanged',
'accepted_residual_unchanged')), 'Accepted state changed during observation.')
topology = {int(r['element']): r for r in rows(folder / 'density_element_topology.csv')}
affected = {int(r['element']) for r in negative}
layers, attributes = {}, {}
for r in negative:
element, weight = int(r['element']), float(r['weight'])
require(r['surface_layer'] == topology[element]['surface_layer'], 'Negative sample topology mismatch.')
for table, key in ((layers, int(r['surface_layer'])), (attributes, int(r['attribute']))):
item = table.setdefault(key, {'volume': 0., 'negative_mass': 0.})
item['volume'] += weight
item['negative_mass'] -= weight * float(r['rho'])
traces = rows(folder / 'density_surface_traces.csv')
surface = [r for r in traces if float(r['inward_coordinate']) == 0.]
for r in traces:
require(all(math.isfinite(float(r[key])) for key in r), 'Nonfinite surface trace observation.')
h = float(r['h'])
close(float(r['rho_from_h']), (h / ((n + 1) * K)) ** n if h > 0 else 0., 'surface trace EOS')
result = dict(n=n, K=K, source=meta['density_source'], normalized_residual=invariants['prepared_residual_norm'],
state={str(q): summary[(q, 'state')] for q in (18, 26)},
controls={field: {str(q): summary[(q, field)] for q in (18, 26)} for field in ('eos_pointwise', 'production', 'q18', 'q26')},
coefficient_comparison=coefficient_comparison,
closure_residual_check=dict(actual_norm=float(np.linalg.norm(actual)), independent_difference_norm=defect_norm,
arithmetic_allowance=allowance, rhs_norm=rhs_norm),
affected_elements=len(affected), stellar_elements=len(topology),
surface_elements=sum(int(r['surface_layer']) == 0 for r in topology.values()),
negative_volume_by_surface_layer=layers, negative_volume_by_attribute=attributes,
density_dof_minimum=min(float(r['density_dof_minimum']) for r in topology.values()),
surface_trace=dict(samples=len(surface), negative_samples=sum(float(r['rho']) < 0 for r in surface),
minimum_density=min(float(r['rho']) for r in surface),
maximum_abs_enthalpy=max(abs(float(r['h'])) for r in surface)),
full_trace_minimum_density=min(float(r['rho']) for r in traces),
physical_q18=physical, artifact_passed=True)
return clean(result)
def plots(campaign, output):
import matplotlib
matplotlib.use('Agg')
import matplotlib.pyplot as plt
output.mkdir(parents=True, exist_ok=True)
fig, axes = plt.subplots(1, 2, figsize=(11, 4.4), constrained_layout=True)
for ax, name, title in zip(axes, ('n1p5_equilibrium', 'n3_seed'), ('n = 1.5 converged state', 'n = 3 initial state')):
table = rows(campaign / name / 'density_surface_traces.csv')
centers = [r for r in table if float(r['tangent_u']) == .5 and float(r['tangent_v']) == .5]
witness = min(centers, key=lambda r: float(r['rho']))
line = [r for r in centers if r['face'] == witness['face']]
line.sort(key=lambda r: float(r['distance_from_face']))
x = [float(r['distance_from_face']) for r in line]
for key, label, style in [('rho_from_h', 'Positive EOS density from h', 'k-'),
('rho', 'Stored quadratic density', 'o-'),
('rho_projected_production', 'Independent closure projection', '--')]:
ax.plot(x, [float(r[key]) for r in line], style, label=label, markersize=3)
ax.axhline(0., color='0.55', linewidth=.8)
ax.set_title(title)
ax.set_xlabel('Distance inward from surface / reference radius')
ax.set_ylabel('Density (model units)')
depth_limit = .08 if name == 'n1p5_equilibrium' else .5
ax.set_xlim(0., x[-1] * depth_limit)
shown = [float(r[k]) for r in line if float(r['inward_coordinate']) <= depth_limit
for k in ('rho', 'rho_from_h', 'rho_projected_production')]
span = max(shown) - min(shown)
ax.set_ylim(min(shown) - .08 * span, max(shown) + .08 * span)
ax.grid(alpha=.18)
axes[0].legend(fontsize=8)
fig.savefig(output / 'surface_density_traces.png', dpi=180)
plt.close(fig)
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('campaign', type=Path)
parser.add_argument('--output', type=Path, required=True)
parser.add_argument('--plots', type=Path)
args = parser.parse_args()
campaign = args.campaign.resolve()
provenance = json.loads((campaign / 'provenance.json').read_text())
require(digest(campaign / 'plateau_diagnostic') == provenance['binary_sha256'], 'Producer binary changed.')
require(digest(Path(provenance['mesh'])) == provenance['mesh_sha256'], 'Input mesh changed.')
results = {}
for case in provenance['cases']:
name = case['id']
run = json.loads((campaign / (name + '_run.json')).read_text())
require(run['exit_code'] == 0 and run['inputs_unchanged'], f'Incomplete frozen diagnostic: {name}')
require_complete_hashes(run)
for relative, value in run['output_hashes'].items():
require(digest(campaign / name / relative) == value, f'Changed output: {name}/{relative}')
for path, value in run['input_state_hashes'].items():
require(digest(Path(path)) == value, f'Changed input: {path}')
results[name] = audit_case(campaign / name)
payload = dict(source_commit=provenance['commit'], artifact_passed=True, auditor_sha256=digest(Path(__file__)),
scope='Saved algebra, projection/production agreement and provenance; sampled spatial localization is not a sign certificate.',
cases=results)
args.output.write_text(json.dumps(clean(payload), indent=2, allow_nan=False) + '\n')
if args.plots:
plots(campaign, args.plots)
print('PASS', args.output)
if __name__ == '__main__':
main()

View File

@@ -0,0 +1,481 @@
#!/usr/bin/env python3
"""Audit root-split density artifacts against the original frozen campaign.
Saved polynomial algebra and aggregation are checked independently. Mapped
quadrature weights are not exported, so this is not an independent FEM integral
or a global positivity certificate. Tangential convergence remains an observation.
Run after the serial numerical campaign, never alongside a timed FEM run.
"""
from __future__ import annotations
import argparse
from collections import defaultdict
import csv
from decimal import Decimal, localcontext
import hashlib
import json
import math
from pathlib import Path
import tempfile
import unittest
EPS = 2.220446049250313e-16
PREFIX = "density_negative_regions_"
ORDERS = (14, 22, 30)
SUM_FIELDS = ("tangent_lines", "negative_intervals", "integration_points", "volume", "mass",
"negative_volume", "negative_mass")
NEGATIVE_BOUNDS = ("negative_radius_minimum", "negative_radius_maximum",
"negative_interval_t_minimum", "negative_interval_t_maximum")
CONSUMED = ("metadata.txt", "layout.csv", "observed_state.txt", "observed_density_coefficients.txt",
"density_invariants.csv", "density_physical.csv")
def require(condition, message):
if not condition:
raise AssertionError(message)
def close(a, b, label, rtol=3e-11, atol=1e-25):
require(math.isfinite(a) and math.isfinite(b) and math.isclose(a, b, rel_tol=rtol, abs_tol=atol),
f"{label}: {a:.17g} != {b:.17g}")
def digest(path):
with path.open("rb") as stream:
return hashlib.file_digest(stream, "sha256").hexdigest()
def rows(path):
with path.open(newline="") as stream:
reader = csv.DictReader(stream)
require(reader.fieldnames is not None and len(set(reader.fieldnames)) == len(reader.fieldnames),
f"Missing or duplicate CSV columns: {path}")
result = list(reader)
require(all(None not in row and None not in row.values() for row in result), f"Malformed CSV: {path}")
return result
def metadata(path):
entries = [line.split("=", 1) for line in path.read_text().splitlines() if "=" in line]
require(len({key for key, _ in entries}) == len(entries), f"Duplicate metadata: {path}")
return dict(entries)
def keyed(table, key):
result = {key(row): row for row in table}
require(len(result) == len(table), "Duplicate artifact rows")
return result
def numeric(row):
return {key: float(value) for key, value in row.items()}
def finite(row, allowed_nan=()):
for key, value in row.items():
require(math.isfinite(value) or (key in allowed_nan and math.isnan(value)),
f"Unexpected nonfinite value in {key}")
class Campaign:
def __init__(self, path):
self.path = path.resolve()
self.ledger = {}
self.provenance = json.loads(self.record(self.path / "provenance.json").read_text())
p = self.provenance
require(digest(self.record(self.path / "plateau_diagnostic")) == p["binary_sha256"], "Producer binary changed")
require(digest(self.record(Path(p["mesh"]))) == p["mesh_sha256"], "Producer mesh changed")
require(json.loads(self.record(self.path / "cases.json").read_text()) == p["cases"], "Case manifest changed")
self.cases = keyed(p["cases"], lambda case: case["id"])
self.runs = {}
def record(self, path):
path = path.resolve()
self.ledger[str(path)] = digest(path)
return path
def run(self, name):
if name not in self.runs:
r = json.loads(self.record(self.path / f"{name}_run.json").read_text())
require(r["id"] == name and r["exit_code"] == 0 and r["inputs_unchanged"] is True,
f"Incomplete or changed case: {name}")
expected = [str(self.path / "plateau_diagnostic"), *self.cases[name]["arguments"],
"--mesh", self.provenance["mesh"], "--output", str(self.path / name)]
require(r["command"] == expected, f"Recorded command differs from manifest: {name}")
for path, expected_hash in r["input_state_hashes"].items():
require(self.ledger.get(str(self.record(Path(path)))) == expected_hash, f"Changed source input: {path}")
self.runs[name] = r
return self.runs[name]
def artifact(self, name, relative):
r = self.run(name)
require(relative in r["output_hashes"], f"Consumed artifact lacks producer hash: {name}/{relative}")
path = self.record(self.path / name / relative)
require(self.ledger[str(path)] == r["output_hashes"][relative], f"Changed output: {name}/{relative}")
return path
def vector_size(path):
with path.open() as stream:
size = int(next(stream).strip())
require(size > 0, "Empty saved vector")
count = 0
for line in stream:
require(math.isfinite(float(line)), "Nonfinite saved vector")
count += 1
require(size == count, "Saved vector size differs from its header")
return size
def gauss_rule(count):
"""Independent Legendre recurrence on [0,1], used only for node binding."""
result = []
for j in range(1, count + 1):
z = math.cos(math.pi * (j - .25) / (count + .5))
for _ in range(30):
previous, current = 1., z
for degree in range(2, count + 1):
previous, current = current, ((2 * degree - 1) * z * current - (degree - 1) * previous) / degree
derivative = count * (z * current - previous) / (z * z - 1)
update = current / derivative
z -= update
if abs(update) < 2e-16:
break
result.append(((1 + z) / 2, 1 / ((1 - z * z) * derivative * derivative)))
return sorted(result)
def polynomial_intervals(c, b, a):
"""Direct high-precision quadratic formula differs from producer q/a,c/q."""
with localcontext() as context:
context.prec = 70
c, b, a = [Decimal(str(x)) for x in (c, b, a)]
points = [Decimal(0), Decimal(1)]
if a == 0:
roots = [] if b == 0 else [-c / b]
else:
discriminant = b * b - 4 * a * c
roots = [] if discriminant < 0 else [(-b - discriminant.sqrt()) / (2 * a),
(-b + discriminant.sqrt()) / (2 * a)]
points = sorted(set(points + [t for t in roots if 0 < t < 1]))
value = lambda t: c + t * (b + t * a)
return [(float(left), float(right)) for left, right in zip(points, points[1:])
if value((left + right) / 2) < 0]
def interval_check(row, rule):
r = numeric(row)
finite(r)
left, right = r["t_left"], r["t_right"]
require(r["tangential_order"] == 30 and 0 <= left < right <= 1, "Invalid finest negative interval")
require(r["axis"] in (0, 1, 2) and r["orientation"] in (-1, 1), "Invalid interval axis")
a, b, c = (r[key] for key in ("coefficient_a", "coefficient_b", "coefficient_c"))
scale = max(abs(a), abs(b), abs(c))
require(scale > 0, "Zero polynomial cannot have a negative interval")
allowance = 4096 * EPS * scale
evaluate = lambda t: math.fsum((c, b * t, a * t * t))
for endpoint in (left, right):
if 0 < endpoint < 1:
require(abs(evaluate(endpoint)) <= allowance, "Interior interval endpoint is not a root")
for fraction in (.125, .25, .5, .75, .875):
require(evaluate(left + fraction * (right - left)) <= allowance, "Negative interval contains a positive value")
candidates = [left, right]
if a and left < -b / (2 * a) < right:
candidates.append(-b / (2 * a))
minimum = min(map(evaluate, candidates))
require(minimum <= allowance, "Claimed negative interval has positive minimum")
close(r["minimum_density"], minimum, "Direct FE and polynomial interval minimum", rtol=0, atol=allowance)
require(r["negative_volume"] > 0 and r["negative_mass"] > 0, "Nonpositive negative-region integral")
require(r["negative_mass"] / r["negative_volume"] <= -minimum + allowance,
"Negative mean density exceeds the polynomial's maximum magnitude")
weights = []
for coordinate in ("u", "v"):
nearest = min(rule, key=lambda pair: abs(pair[0] - r[coordinate]))
close(nearest[0], r[coordinate], "Tangential Gauss node", rtol=0, atol=4e-15)
weights.append(nearest[1])
close(weights[0] * weights[1], r["tangential_weight"], "Tangential Gauss weight", rtol=2e-12)
radii = [math.sqrt(math.fsum(r[f"{side}_{component}"] ** 2 for component in "xyz"))
for side in ("left", "right")]
require(0 <= r["radius_minimum"] <= r["radius_maximum"], "Invalid radius bounds")
tolerance = 2e-13 * max(1., r["radius_maximum"])
require(r["radius_minimum"] <= min(radii) + tolerance and r["radius_maximum"] >= max(radii) - tolerance,
"Sampled radius bounds exclude a saved endpoint")
return r, minimum < -allowance
def measure_check(r):
empty = r["negative_intervals"] == 0
finite(r, NEGATIVE_BOUNDS if empty else ())
require(r["volume"] > 0 and 0 <= r["negative_volume"] <= r["volume"], "Invalid measured volume")
require(r["negative_mass"] >= 0, "Invalid negative mass")
for key in SUM_FIELDS[:3]:
require(r[key] >= 0 and r[key].is_integer(), f"Noninteger count: {key}")
close(r["negative_volume_fraction"], r["negative_volume"] / r["volume"], "Negative volume fraction")
require(r["mass"] != 0, "Zero total mass requires an explicitly unsupported fraction convention")
close(r["negative_mass_fraction"], r["negative_mass"] / abs(r["mass"]), "Negative mass fraction")
require(0 <= r["maximum_reconstruction_error"] <= r["maximum_reconstruction_tolerance"], "Q2 reconstruction failed")
require(all(0 <= r[key] <= 1 for key in ("witness_t", "witness_u", "witness_v")), "Witness outside reference cell")
if empty:
require(r["negative_mass"] == 0 and r["negative_volume"] == 0 and
all(math.isnan(r[key]) for key in NEGATIVE_BOUNDS), "Empty negative region has nonempty observations")
else:
require(r["negative_mass"] > 0 and r["negative_volume"] > 0 and
0 <= r["negative_interval_t_minimum"] < r["negative_interval_t_maximum"] <= 1 and
0 <= r["negative_radius_minimum"] <= r["negative_radius_maximum"], "Invalid nonempty negative bounds")
def audit_selfchecks(table):
expected = {"positive_quadratic": (0., 0.), "negative_constant": (1., 2.),
"linear_crossing": (.25, .03125), "double_root_nonnegative": (0., 0.),
"near_linear_positive": (0., 0.), "near_double_negative": (2. ** -19, 4 * 2. ** -60 / 3),
"gauss_q2_t_power_1p5": (.04548403175047501373888, .0005262295634284655),
"gauss_q2_t_power_3": (math.sqrt(6) / 15, math.sqrt(6) / 2250)}
indexed = keyed(table, lambda r: r["case"])
require(indexed.keys() == expected.keys(), "Analytic selfcheck coverage changed")
for name, (length, mass) in expected.items():
r = indexed[name]
require(r["passed"] == "1", "Producer arithmetic selfcheck failed")
for key, target in (("negative_length", length), ("negative_mass", mass)):
close(float(r[key]), target, f"Independent selfcheck {name}/{key}", rtol=3e-12, atol=1e-27)
close(float(r["expected_" + key]), target, "Producer selfcheck expected value", rtol=3e-12, atol=1e-27)
def audit_case(current, original, name):
new = lambda filename: current.artifact(name, filename)
old = lambda filename: original.artifact(name, filename)
meta, prior_meta = metadata(new("metadata.txt")), metadata(old("metadata.txt"))
for key in ("n", "K", "J", "rho_c", "M", "R_reference", "density_source", "surface_prescription",
"surface_degree", "surface_maximum_order", "central_phase"):
require(key in meta and key in prior_meta and meta[key] == prior_meta[key], f"Changed model metadata: {key}")
require(meta["density_diagnostic"] == "1" and meta["density_region_integral"] == "1", "Wrong diagnostic mode")
require(current.run(name)["input_state_hashes"] == original.run(name)["input_state_hashes"], "Changed frozen inputs")
for filename in ("observed_state.txt", "observed_density_coefficients.txt", "layout.csv"):
require(digest(new(filename)) == digest(old(filename)), f"Source is not byte-identical: {filename}")
state_size = vector_size(new("observed_state.txt"))
density_size = vector_size(new("observed_density_coefficients.txt"))
layout = rows(new("layout.csv"))
for kind in ("value", "residual"):
blocks = sorted((int(r["offset"]), int(r["size"])) for r in layout if r["kind"] == kind)
end = 0
for offset, size in blocks:
require(offset == end and size > 0, "Invalid saved block layout")
end += size
require(end == state_size, "Layout does not cover the observed state")
require(density_size % 27 == 0, "Full density storage is not Q2 tensor sized")
invariants = {r["metric"]: float(r["value"]) for r in rows(new("density_invariants.csv"))}
previous_invariants = {r["metric"]: float(r["value"]) for r in rows(old("density_invariants.csv"))}
finite(invariants)
for key in ("accepted_physical_unchanged", "accepted_normalized_unchanged", "accepted_residual_unchanged"):
require(invariants[key] == previous_invariants[key] == 1, "Accepted-state observation/restoration failed")
close(invariants["prepared_residual_norm"], previous_invariants["prepared_residual_norm"], "Frozen residual", atol=1e-14)
scope_file = new(PREFIX + "scope.txt")
scope = metadata(scope_file)
require(scope["source_fields_bitwise_identical"] == "1" and scope["trial_preparations"] == "0" and
scope["mpi_ranks"] == "1", "Region observer invariants failed")
for key in ("n", "K"):
close(float(scope[key]), float(meta[key]), "Observer model binding")
text = scope_file.read_text()
for phrase in ("no density or EOS clipping", "All stellar cells are included", "tangential integration is sampled",
"not global extrema or polynomial sign certificates", "Near-double-root"):
require(phrase in text, "Missing observer scope limitation")
audit_selfchecks(rows(new(PREFIX + "selfchecks.csv")))
totals = keyed([numeric(r) for r in rows(new(PREFIX + "summary.csv"))], lambda r: int(r["tangential_order"]))
elements = keyed([numeric(r) for r in rows(new(PREFIX + "elements.csv"))],
lambda r: (int(r["tangential_order"]), int(r["element"])))
topology = keyed(rows(old("density_element_topology.csv")), lambda r: int(r["element"]))
require(totals.keys() == set(ORDERS), "Missing quadrature levels")
require(elements.keys() == {(order, element) for order in ORDERS for element in topology}, "Stellar support differs")
original_summary = keyed(rows(old("density_summary.csv")), lambda r: (int(r["quadrature"]), r["field"]))
physical = {r["metric"]: float(r["value"]) for r in rows(new("density_physical.csv")) if r["quadrature"] == "18"}
denominator_differences = {}
for order, total in totals.items():
require(total["interval_order"] == 14, "Changed interval quadrature")
measure_check(total)
subset = [elements[(order, element)] for element in topology]
for r in subset:
measure_check(r)
top = topology[int(r["element"])]
require(r["interval_order"] == 14 and r["tangent_lines"] == (order // 2 + 1) ** 2 and
r["attribute"] == int(top["attribute"]) and r["surface_face_count"] == int(top["surface_face_count"]),
"Element integration layout or topology differs")
require(r["witness_element"] == r["element"] and r["axis"] in (0, 1, 2) and
r["orientation"] in (-1, 1) and r["integration_points"] % 8 == 0 and
8 * r["tangent_lines"] <= r["integration_points"] <= 24 * r["tangent_lines"], "Element count/axis contradiction")
require((r["surface_face"] >= 0) == (r["surface_face_count"] > 0), "Surface axis metadata inconsistent")
if r["surface_face_count"] == 0:
require(r["axis"] == 0 and r["orientation"] == 1, "Non-surface slicing convention changed")
for key in SUM_FIELDS:
close(math.fsum(r[key] for r in subset), total[key], f"Global element sum {order}/{key}")
close(min(r["minimum_density"] for r in subset), total["minimum_density"], "Global minimum")
witness = elements[(order, int(total["witness_element"]))]
for key in ("minimum_density", "witness_h", "witness_t", "witness_u", "witness_v", "witness_x", "witness_y", "witness_z"):
close(witness[key], total[key], "Global witness binding", atol=1e-15)
nonempty = [r for r in subset if r["negative_intervals"]]
for key, function in (("negative_radius_minimum", min), ("negative_radius_maximum", max),
("negative_interval_t_minimum", min), ("negative_interval_t_maximum", max)):
if nonempty:
close(function(r[key] for r in nonempty), total[key], "Negative-region bounds")
for key in ("maximum_reconstruction_error", "maximum_reconstruction_tolerance"):
close(max(r[key] for r in subset), total[key], "Reconstruction maximum")
denominator_differences[str(order)] = {}
for key in ("mass", "volume"):
for old_order in (18, 26):
reference = float(original_summary[(old_order, "state")][key])
close(total[key], reference, f"Independent full {key}, q{order}/original q{old_order}", rtol=2e-9, atol=1e-13)
denominator_differences[str(order)][f"{key}_relative_to_q{old_order}"] = (total[key] - reference) / abs(reference)
close(physical[key], float(original_summary[(18, "state")][key]), "Repeated q18 physical measure")
interval_rows = rows(new(PREFIX + "intervals.csv"))
by_element, by_line = defaultdict(list), defaultdict(list)
unresolved = 0
rule = gauss_rule(16)
for row in interval_rows:
r, resolved = interval_check(row, rule)
unresolved += not resolved
element = int(r["element"])
require((30, element) in elements, "Interval on an unsupported element")
for key in ("attribute", "axis", "orientation", "surface_face"):
require(r[key] == elements[(30, element)][key], "Interval geometry metadata mismatch")
by_element[element].append(r)
by_line[(element, r["u"], r["v"])].append((row, r, resolved))
for line in by_line.values():
first = line[0][0]
for row, _, _ in line:
require(all(row[key] == first[key] for key in ("coefficient_c", "coefficient_b", "coefficient_a")), "One line has multiple polynomials")
expected = polynomial_intervals(first["coefficient_c"], first["coefficient_b"], first["coefficient_a"])
actual = sorted((r["t_left"], r["t_right"]) for _, r, _ in line)
require(all(actual[i][1] <= actual[i + 1][0] for i in range(len(actual) - 1)), "Overlapping negative intervals")
if all(resolved for _, _, resolved in line):
require(len(expected) == len(actual), "Missing or extra resolved negative interval")
a, b, c = [float(first[k]) for k in ("coefficient_a", "coefficient_b", "coefficient_c")]
uncertainty = 4096 * EPS * max(abs(a), abs(b), abs(c))
for got, wanted in zip(actual, expected):
for x, y in zip(got, wanted):
if y in (0., 1.):
require(x == y, "Negative interval misses the physical cell endpoint")
continue
# Near a double root, position uncertainty scales as the
# square root of coefficient uncertainty, not machine eps.
allowance = max(64 * EPS, uncertainty / max(abs(b + 2 * a * y), math.sqrt(abs(a) * uncertainty)))
close(x, y, "Independent Decimal root", rtol=0, atol=allowance)
for element in topology:
r = elements[(30, element)]
pieces = by_element[element]
require(len(pieces) == r["negative_intervals"], "Finest interval export coverage mismatch")
for key in ("negative_mass", "negative_volume"):
close(math.fsum(piece[key] for piece in pieces), r[key], "Finest interval-to-element sum")
if pieces:
allowance = r["maximum_reconstruction_tolerance"] + 128 * EPS * max(abs(r["minimum_density"]), 1e-30)
close(min(piece["minimum_density"] for piece in pieces), r["minimum_density"], "Finest negative minimum", rtol=0, atol=allowance)
for interval_key, element_key, function in (("t_left", "negative_interval_t_minimum", min),
("t_right", "negative_interval_t_maximum", max), ("radius_minimum", "negative_radius_minimum", min),
("radius_maximum", "negative_radius_maximum", max)):
close(function(p[interval_key] for p in pieces), r[element_key], "Finest interval bounds")
comparison = {}
for key in ("negative_mass", "negative_volume", "negative_mass_fraction", "negative_volume_fraction"):
comparison[key] = {"q14": totals[14][key], "q22": totals[22][key], "q30": totals[30][key],
"q30_minus_q22": totals[30][key] - totals[22][key],
"relative_q30_minus_q22": ((totals[30][key] - totals[22][key]) / totals[30][key]
if totals[30][key] else None)}
return {"artifact_passed": True, "n": float(meta["n"]), "state_size": state_size,
"density_storage_size": density_size, "stellar_elements": len(topology),
"finest_exported_negative_intervals": len(interval_rows), "finest_negative_lines": len(by_line),
"intervals_below_coefficient_uncertainty": unresolved,
"finest_affected_elements": len([v for v in by_element.values() if v]),
"finest_negative_elements_not_touching_surface": sum(bool(by_element[e]) and int(topology[e]["surface_face_count"]) == 0 for e in topology),
"denominator_comparisons": denominator_differences, "quadrature_comparison": comparison,
"summary": {str(k): v for k, v in totals.items()}}
class SelfTests(unittest.TestCase):
def test_decimal_roots(self):
self.assertEqual(polynomial_intervals("-.25", "1", "0"), [(0., .25)])
self.assertEqual(polynomial_intervals(".25", "-1", "1"), [])
roots = polynomial_intervals(".05", "-.6", "1.5")
close(roots[0][0], .2 - math.sqrt(6) / 30, "Cubic root")
close(roots[0][1], .2 + math.sqrt(6) / 30, "Cubic root")
def fixture(self):
rule = gauss_rule(16)
u, weight = rule[3]
r = dict(tangential_order=30, element=1, attribute=1, axis=0, orientation=1, surface_face=2,
u=u, v=u, tangential_weight=weight * weight, t_left=0, t_right=.25,
coefficient_c=-.25, coefficient_b=1, coefficient_a=0,
negative_volume=.25 * weight * weight, negative_mass=.03125 * weight * weight,
minimum_density=-.25, witness_h=1, radius_minimum=math.sqrt(2 * u * u),
radius_maximum=math.sqrt(.25 ** 2 + 2 * u * u), left_x=0, left_y=u, left_z=u,
right_x=.25, right_y=u, right_z=u)
return {k: str(v) for k, v in r.items()}, rule
def test_valid_interval(self):
r, rule = self.fixture()
self.assertTrue(interval_check(r, rule)[1])
def test_corrupt_interval(self):
for key, value in (("t_right", ".3"), ("negative_mass", "1"), ("u", ".5"),
("minimum_density", "-.5"), ("witness_h", "nan")):
with self.subTest(key=key):
r, rule = self.fixture()
r[key] = value
with self.assertRaises(AssertionError):
interval_check(r, rule)
def test_hash_coverage(self):
with tempfile.TemporaryDirectory() as directory:
folder = Path(directory)
(folder / "case").mkdir()
(folder / "case/file.txt").write_text("original")
campaign = object.__new__(Campaign)
campaign.path, campaign.ledger = folder, {}
campaign.runs = {"case": {"output_hashes": {"file.txt": digest(folder / "case/file.txt")}}}
campaign.artifact("case", "file.txt")
(folder / "case/file.txt").write_text("changed")
with self.assertRaises(AssertionError):
campaign.artifact("case", "file.txt")
with self.assertRaises(AssertionError):
campaign.artifact("case", "unrecorded.txt")
def clean(item):
if isinstance(item, dict):
return {str(k): clean(v) for k, v in item.items()}
if isinstance(item, list):
return [clean(v) for v in item]
return None if isinstance(item, float) and not math.isfinite(item) else item
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("campaign", type=Path, nargs="?")
parser.add_argument("--original", type=Path, help="Original negative-density campaign; defaults to sibling campaign")
parser.add_argument("--output", type=Path)
parser.add_argument("--self-test", action="store_true")
args = parser.parse_args()
if args.self_test:
result = unittest.TextTestRunner(verbosity=2).run(unittest.defaultTestLoader.loadTestsFromTestCase(SelfTests))
if not result.wasSuccessful():
raise SystemExit(1)
if args.campaign is None:
return
if args.campaign is None or args.output is None:
parser.error("campaign and --output are required for artifact auditing")
current = Campaign(args.campaign)
original = Campaign(args.original or args.campaign.resolve().parent / "campaign")
require(current.path != original.path, "A distinct source campaign is required")
require(current.provenance["mesh_sha256"] == original.provenance["mesh_sha256"], "Campaign meshes differ")
require(current.cases.keys() <= original.cases.keys(), "Region case has no original source case")
report = {"schema": "negative_density_regions_audit_v1", "artifact_passed": True,
"auditor_sha256": digest(Path(__file__)), "producer_commit": current.provenance["commit"],
"original_commit": original.provenance["commit"],
"scope": "Independent saved quadratic algebra, aggregation and source binding; not independent mapped FEM integration or global positivity certification.",
"tolerances": {"aggregation_relative": 3e-11, "aggregation_absolute": 1e-25,
"root_coefficient_roundoff_factor": 4096, "whole_measure_relative": 2e-9,
"whole_measure_absolute": 1e-13},
"cases": {name: audit_case(current, original, name) for name in current.cases}}
report["consumed_sha256"] = {**original.ledger, **current.ledger}
args.output.write_text(json.dumps(clean(report), indent=2, allow_nan=False) + "\n")
print("PASS", args.output)
if __name__ == "__main__":
main()

View File

@@ -0,0 +1,517 @@
#!/usr/bin/env python3
"""Audit saved reduced-surface algebra; a reduced gate is not a full solve.
No FEM action, preparation, or physical quadrature is independently repeated.
The dual residual restriction is checked against the physical basis and saved
normalization, rather than assumed to be the state injection's transpose.
"""
import argparse
import json
import math
from pathlib import Path
import sys
from audit_shape_field_weak import (Audit, EPS, RTOL, checked_einsum as einsum,
digest, finite, integer, layout, near, norm,
np, rows, table, vector, vector_near)
from analyze_shape_surface_modes import harmonics
P = "reduced_surface_"
MAPS = ("basis_physical", "state_basis", "residual_basis", "state_transform", "residual_transform")
VECTORS = ("base", "physical_base", "residual", "direction", "physical_direction", "action", "defect",
"state_factors", "residual_factors", "reduced_residual", "reduced_direction", "reduced_action",
"reduced_defect", "excluded_residual", "excluded_defect", "restored_residual", "restored_action")
ALPHAS = (1., .25, .0625, 1 / 1024)
def matrix(path):
with Path(path).open() as stream:
dimensions = [int(x) for x in stream.readline().split()]
values = np.loadtxt(stream, ndmin=1)
if len(dimensions) != 2 or min(dimensions) <= 0 or values.ndim != 1 or values.size != math.prod(dimensions) or not np.isfinite(values).all():
raise ValueError(f"Invalid finite row-major matrix: {path}")
return values.reshape(dimensions)
def close_array(audit, label, actual, expected, scale=0.):
audit.check(label, vector_near(np.asarray(actual).ravel(), np.asarray(expected).ravel(), scale))
class Coordinates:
def __init__(self, summary, maps):
self.n = integer(summary["full_size"])
self.s = integer(summary["shape_size"])
self.k = integer(summary["mode_count"])
self.vo = integer(summary["shape_value_offset"])
self.ro = integer(summary["shape_residual_offset"])
self.identity = summary["identity_control"] == 1
self.maps = maps
if not (0 < self.k <= self.s <= self.n and 0 <= self.vo <= self.n - self.s and 0 <= self.ro <= self.n - self.s):
raise ValueError("Invalid coordinate dimensions")
def restrict(self, values, residual=True):
if self.identity:
return values.copy()
offset = self.ro if residual else self.vo
basis = self.maps["residual_basis" if residual else "state_basis"]
middle = einsum("ij,i->j", basis, values[offset:offset + self.s])
return np.concatenate((values[:offset], middle, values[offset + self.s:]))
def inject(self, values, residual=False):
if self.identity:
return values.copy()
offset = self.ro if residual else self.vo
basis = self.maps["residual_basis" if residual else "state_basis"]
middle = einsum("ij,j->i", basis, values[offset:offset + self.k])
return np.concatenate((values[:offset], middle, values[offset + self.k:]))
def excluded(self, values):
return values - self.inject(self.restrict(values), residual=True)
def validate(self, factors, residual_factors, audit):
if self.identity:
audit.check("identity:full_mode_count", self.k == self.s)
return
b, px, qf, tx, tf = (self.maps[k] for k in MAPS)
audit.check("maps:dimensions", b.shape == px.shape == qf.shape == (self.s, self.k) and tx.shape == tf.shape == (self.k, self.k))
sx = factors[self.vo:self.vo + self.s]
rf = residual_factors[self.ro:self.ro + self.s]
close_array(audit, "maps:state_QR", sx[:, None] * b, einsum("ij,jk->ik", px, tx))
close_array(audit, "maps:dual_QR", b / rf[:, None], einsum("ij,jk->ik", qf, tf))
for name, basis, transform in (("state", px, tx), ("residual", qf, tf)):
close_array(audit, "maps:" + name + "_orthonormal", einsum("ij,ik->jk", basis, basis), np.eye(self.k))
close_array(audit, "maps:" + name + "_triangular", np.tril(transform, -1), np.zeros((self.k, self.k)), norm(transform.ravel()))
audit.check("maps:" + name + "_nonsingular", np.all(np.abs(np.diag(transform)) > 64 * EPS * max(norm(transform.ravel()), 1e-300)))
def basis_package(folder, coords, physical_base, required, audit):
first = folder / (P + "basis_raw.txt")
if not first.exists():
raise ValueError("Missing physical harmonic basis package")
def get(name):
path = folder / (P + name + ".txt")
required.add(path.name)
return matrix(path)
raw, gram, orthogram, transform, samples = (get(k) for k in
("basis_raw", "gram_raw", "gram_orthonormal", "coefficient_transform", "basis_samples_raw"))
weights_path = folder / (P + "basis_weights.txt")
required.add(weights_path.name)
weights = vector(weights_path)
audit.check("basis:positive_quadrature", len(weights) == len(samples) and np.all(weights > 0))
close_array(audit, "basis:quadrature_gram", gram, einsum("ni,n,nj->ij", samples, weights, samples))
close_array(audit, "basis:physical_from_raw", coords.maps["basis_physical"], einsum("ij,jk->ik", raw, transform))
actual = einsum("ij,ik,kl->jl", transform, gram, transform)
close_array(audit, "basis:transformed_gram", orthogram, actual)
close_array(audit, "basis:mass_orthonormal", actual, np.eye(coords.k))
node_path, mode_path, meta_path = (folder / (P + n + ".csv") for n in ("basis_nodes", "basis_modes", "basis_metadata"))
required.update(p.name for p in (node_path, mode_path, meta_path))
nodes, modes = rows(node_path), rows(mode_path)
audit.check("basis:node_indices", [integer(r["parameter"]) for r in nodes] == list(range(coords.s)))
node_base = np.array([finite(r["base_parameter"]) for r in nodes])
reference_radius = np.array([finite(r["reference_radius"]) for r in nodes])
physical_radius = np.array([finite(r["physical_radius"]) for r in nodes])
close_array(audit, "basis:frozen_base_parameters", node_base, physical_base[coords.vo:coords.vo + coords.s])
close_array(audit, "basis:physical_radius", physical_radius, reference_radius + node_base)
audit.check("basis:positive_radii", np.all(reference_radius > 0) and np.all(physical_radius > 0))
points = np.array([[finite(r["unit_radial_" + axis]) for axis in "xyz"] for r in nodes])
lengths = np.sqrt(einsum("ij,ij->i", points, points))
close_array(audit, "basis:unit_directions", lengths, np.ones(coords.s))
maximum_degree = max(integer(r["degree"]) for r in modes)
expected, labels = harmonics(points / lengths[:, None], maximum_degree)
audit.check("basis:mode_indices", [integer(r["column"]) for r in modes] == list(range(coords.k)))
audit.check("basis:mode_order", [(integer(r["degree"]), integer(r["m"])) for r in modes] == [(l["degree"], l["m"]) for l in labels])
close_array(audit, "basis:independent_harmonics", raw, expected)
text_keys = {"metric_scope", "scalar_finite_element_collection", "displacement_finite_element_collection"}
metadata = {k: r["value"] if k in text_keys else finite(r["value"])
for k, r in table(meta_path, lambda r: r["metric"]).items()}
for key, value in {"maximum_degree": maximum_degree, "modes": coords.k, "surface_parameters": coords.s,
"quadrature": 14, "surface_quadrature_points": len(weights), "accepted_buffers_unchanged": 1,
"prepared_state_unchanged": 1, "normalization_factors_unchanged": 1,
"vector_displacement_metric_claimed": 0, "base_projection_performed": 0,
"trial_preparations": 0, "radial_trace_validation_actions": 1}.items():
audit.check("basis:metadata:" + key, metadata[key] == value)
audit.check("basis:metric_scope", metadata["metric_scope"] == "scalar_radial_amplitude_FE_trace_mass_on_current_physical_surface")
audit.check("basis:reported_error_bounds", 0 <= metadata["maximum_gram_orthogonality_error"] <= 1e-10 and
0 <= metadata["maximum_sample_reconstruction_error"] <= 1e-10 and 0 <= metadata["adjoint_relative_error"] <= 1e-12)
for j, row in enumerate(modes):
pivot, relative = finite(row["pivot_norm"]), finite(row["relative_pivot"])
audit.check(f"basis:independent_mode:{j}", pivot > 0 and relative > metadata["rank_relative_pivot_threshold"] > 0)
audit.close(f"basis:pivot_transform:{j}", pivot * transform[j, j], 1.)
audit.close(f"basis:relative_pivot:{j}", relative, pivot / math.sqrt(gram[j, j]))
audit.close("basis:surface_area", metadata["physical_surface_area"], math.fsum(weights))
return {"status": "nodal_basis_and_saved_quadrature_gram_checked", "metadata": metadata,
"scope": "Saved FE trace samples and weights are checked algebraically; physical quadrature is not rerun."}
def provenance(folder, required, audit):
run_path = folder.parent / (folder.name + "_run.json")
source_path = folder.parent / "provenance.json"
if not run_path.exists() and not source_path.exists():
return {"status": "unavailable", "bound": False}
if not run_path.exists() or not source_path.exists():
raise ValueError("Incomplete campaign provenance")
run, source = json.loads(run_path.read_text()), json.loads(source_path.read_text())
audit.check("provenance:required_hashes", required <= set(run["output_hashes"]))
for name, expected in run["output_hashes"].items():
audit.check("provenance:output:" + name, digest(folder / name) == expected)
for name, expected in run.get("input_state_hashes", {}).items():
audit.check("provenance:input:" + name, digest(name) == expected)
command = run.get("command", run.get("cmd"))
if command is None:
raise ValueError("Missing recorded command")
case = next(c for c in source["cases"] if c["id"] == folder.name)
expected = [str(folder.parent / "plateau_diagnostic"), *case["arguments"], "--mesh", source["mesh"], "--output", str(folder)]
audit.check("provenance:command", command == expected)
audit.check("provenance:binary", digest(command[0]) == source["binary_sha256"])
audit.check("provenance:mesh", digest(source["mesh"]) == source["mesh_sha256"])
if "--probe-state" in command:
path = Path(command[command.index("--probe-state") + 1])
if not path.is_absolute():
path = Path(source["source"]) / path
audit.check("provenance:base_input_bound", str(path.resolve()) in run.get("input_state_hashes", {}))
close_array(audit, "provenance:physical_base_input", vector(path), vector(folder / (P + "physical_base.txt")))
audit.check("provenance:successful_probe_exit", run["exit_code"] == 0)
return {"status": "runner_hashes_checked", "bound": True, "source_commit": source["commit"],
"run_sha256": digest(run_path), "provenance_sha256": digest(source_path)}
def inspect(folder):
folder = Path(folder).resolve()
audit, required, observations = Audit(), set(), {}
try:
def get(name):
path = folder / (P + name + ".txt")
required.add(path.name)
return vector(path)
summary_path = folder / (P + "summary.csv")
trials_path = folder / (P + "trials.csv")
layout_path = folder / (P + "layout.csv")
required.update(p.name for p in (summary_path, trials_path, layout_path))
summary = {k: finite(r["value"]) for k, r in table(summary_path, lambda r: r["metric"]).items()}
audit.check("identity:boolean", summary["identity_control"] in (0, 1))
maps = {}
for name in MAPS:
path = folder / (P + name + ".txt")
if summary["identity_control"]:
audit.check("identity:matrix_absent:" + name, not path.exists())
else:
required.add(path.name)
maps[name] = matrix(path)
coordinates = Coordinates(summary, maps)
n, s, k, vo, ro = coordinates.n, coordinates.s, coordinates.k, coordinates.vo, coordinates.ro
degree = integer(summary["maximum_degree"])
audit.check("prescribed_basis_size", (degree == 0 and k == s) if coordinates.identity else (degree in (2, 4, 6, 8) and k == (degree + 1) ** 2))
audit.check("reduced_size", summary["reduced_size"] == n - s + k)
audit.check("schema_version", summary["schema_version"] == 1)
audit.check("reported_algebra_selfcheck", summary["algebra_self_check_passed"] == 1)
blocks = layout(layout_path, n)
audit.check("layout:value_shape", ("surface_deformation", vo, s) in blocks["value"])
audit.check("layout:residual_shape", ("surface_shape_balance", ro, s) in blocks["residual"])
data = {name: get(name) for name in VECTORS}
for name, values in data.items():
audit.check("size:" + name, len(values) == (n - s + k if name.startswith("reduced_") else n))
sx, rf = data["state_factors"], data["residual_factors"]
audit.check("normalization:positive", np.all(sx > 0) and np.all(rf > 0))
coordinates.validate(sx, rf, audit)
for key, value in {"accepted_buffers_bitwise_identical": 1, "normalization_factors_bitwise_identical": 1,
"direction_buffers_bitwise_identical": 1, "restored_residual_error": 0,
"restored_action_error": 0, "probe_exception": 0, "accepted_commits": 0}.items():
audit.check("invariant:" + key, summary[key] == value)
audit.check("restoration:residual_exact", np.array_equal(data["residual"], data["restored_residual"]))
audit.check("restoration:action_exact", np.array_equal(data["action"], data["restored_action"]))
close_array(audit, "normalization:base", data["physical_base"], data["base"] / sx)
close_array(audit, "normalization:direction", data["physical_direction"], data["direction"] / sx)
close_array(audit, "injection:direction", data["direction"], coordinates.inject(data["reduced_direction"]))
for name in ("residual", "action", "defect"):
# Forming R(F+Jp) and RF+RJp rounds differently when F and Jp
# cancel. The allowance must scale with the operands, not only
# with the potentially zero defect being checked.
scale = norm(data["residual"]) + norm(data["action"]) if name == "defect" else 0.
close_array(audit, "restriction:" + name, data["reduced_" + name], coordinates.restrict(data[name]), scale)
close_array(audit, "defect:full", data["defect"], data["residual"] + data["action"], norm(data["residual"]) + norm(data["action"]))
close_array(audit, "defect:reduced", data["reduced_defect"], data["reduced_residual"] + data["reduced_action"],
norm(data["reduced_residual"]) + norm(data["reduced_action"]))
for name in ("residual", "defect"):
excluded = coordinates.excluded(data[name])
close_array(audit, "excluded:" + name, data["excluded_" + name], excluded, norm(data[name]))
audit.close("pythagoras:" + name, norm(data[name]) ** 2,
norm(data["reduced_" + name]) ** 2 + norm(excluded) ** 2, norm(data[name]) ** 2)
eta = summary["linear_relative_tolerance"]
absolute = summary["linear_absolute_tolerance"]
audit.check("linear:controls", 0 < eta < 1 and absolute >= 0 and integer(summary["linear_maximum_iterations"]) > 0)
gates, slopes = {}, {}
for label, prefix in (("full", ""), ("reduced", "reduced_")):
fn, dn = norm(data[prefix + "residual"]), norm(data[prefix + "defect"])
audit.check(label + ":nonzero_rhs", fn > 0)
passed = dn <= max(absolute, eta * fn)
audit.check(label + ":reported_gate", summary[label + "_verified_gate"] in (0, 1) and bool(summary[label + "_verified_gate"]) == passed)
audit.close(label + ":relative_defect", summary[label + "_relative_defect"], dn / fn)
gates[label] = {"verified_gate": passed, "residual_norm": fn, "defect_norm": dn, "relative_defect": dn / fn}
slopes[label] = float(einsum("i,i->", data[prefix + "residual"], data[prefix + "action"]))
audit.close(label + ":reported_norm", summary[label + "_base_norm"], fn)
audit.close(label + ":reported_slope", summary[label + "_merit_slope"], slopes[label], fn * norm(data[prefix + "action"]))
audit.close("reported_direction_norm", summary["direction_norm"], norm(data["direction"]))
audit.close("reported_excluded_base", summary["excluded_base_norm"], norm(data["excluded_residual"]), norm(data["residual"]))
audit.close("linear:reported_true_norm", summary["linear_reported_true_norm"], norm(data["reduced_defect"]), norm(data["reduced_residual"]))
audit.check("linear:iteration_budget", 0 <= integer(summary["linear_iterations"]) <= integer(summary["linear_maximum_iterations"]))
trials = rows(trials_path)
audit.check("trial:complete_grid", len(trials) == len(ALPHAS))
trial_observations = []
for index, row in enumerate(trials):
alpha = finite(row["alpha"])
audit.check(f"trial:{index}:alpha", index < len(ALPHAS) and alpha == ALPHAS[index])
audit.check(f"trial:{index}:sample", integer(row["sample"]) == index)
prepared = integer(row["prepared"])
audit.check(f"trial:{index}:prepared_flag", prepared in (0, 1))
result = {"sample": index, "alpha": alpha, "prepared": bool(prepared), "reason": integer(row["reason"]), "stage": integer(row["stage"])}
candidate_path = folder / (P + f"candidate_a{index}.txt")
if prepared or candidate_path.exists():
candidate = get(f"candidate_a{index}")
close_array(audit, f"trial:{index}:candidate", candidate, data["base"] + alpha * data["direction"])
if prepared:
audit.check(f"trial:{index}:prepared_status", result["reason"] == result["stage"] == -1)
physical_candidate = get(f"physical_candidate_a{index}")
close_array(audit, f"trial:{index}:physical_candidate", physical_candidate, candidate / sx)
full, reduced = get(f"residual_a{index}"), get(f"reduced_residual_a{index}")
close_array(audit, f"trial:{index}:restriction", reduced, coordinates.restrict(full))
excluded = coordinates.excluded(full)
full_norm, reduced_norm, excluded_norm = norm(full), norm(reduced), norm(excluded)
remainder = full - data["residual"] - alpha * data["action"]
reduced_remainder = reduced - data["reduced_residual"] - alpha * data["reduced_action"]
for label, actual in (("full_norm", full_norm), ("reduced_norm", reduced_norm), ("excluded_shape_norm", excluded_norm),
("full_remainder_norm", norm(remainder)), ("reduced_remainder_norm", norm(reduced_remainder))):
audit.close(f"trial:{index}:" + label, finite(row[label]), actual, norm(data["residual"]))
audit.close(f"trial:{index}:pythagoras", full_norm ** 2, reduced_norm ** 2 + excluded_norm ** 2, full_norm ** 2)
for label, actual in (("full", full_norm), ("reduced", reduced_norm)):
accepted = actual <= (1 - 1e-4 * alpha) * gates[label]["residual_norm"]
audit.check(f"trial:{index}:" + label + "_accept", integer(row[label + "_merit_pass"]) in (0, 1) and bool(integer(row[label + "_merit_pass"])) == accepted)
result[label + "_merit_pass"] = accepted
result.update(full_norm=full_norm, reduced_norm=reduced_norm, excluded_shape_norm=excluded_norm,
full_remainder_norm=norm(remainder), reduced_remainder_norm=norm(reduced_remainder))
else:
audit.check(f"trial:{index}:failure_status", result["reason"] >= 0 and result["stage"] >= 0)
for name in (f"residual_a{index}", f"reduced_residual_a{index}"):
audit.check(f"trial:{index}:unavailable:" + name, not (folder / (P + name + ".txt")).exists())
for label in ("full_norm", "reduced_norm", "excluded_shape_norm", "full_remainder_norm", "reduced_remainder_norm"):
audit.check(f"trial:{index}:unavailable:" + label, math.isnan(float(row[label])))
audit.check(f"trial:{index}:failure_not_accepted", integer(row["full_merit_pass"]) == integer(row["reduced_merit_pass"]) == 0)
trial_observations.append(result)
package = basis_package(folder, coordinates, data["physical_base"], required, audit) if not coordinates.identity else {"status": "identity_control"}
if not coordinates.identity:
audit.check("basis:degree_matches_summary", package["metadata"]["maximum_degree"] == degree)
binding = provenance(folder, required, audit)
observations = {"summary": summary, "linear": gates, "merit_directional_derivatives": slopes,
"classification": "full_and_reduced_gates_pass" if gates["full"]["verified_gate"] and gates["reduced"]["verified_gate"] else
"reduced_gate_only_not_full_Newton" if gates["reduced"]["verified_gate"] else "finite_reduced_solve_failed_gate",
"base_excluded_shape_norm": norm(data["excluded_residual"]), "trials": trial_observations,
"basis": package, "provenance": binding}
except (ValueError, OSError, KeyError, TypeError, IndexError, StopIteration, np.linalg.LinAlgError) as error:
audit.check("complete_readable_consistent_artifacts:" + str(error), False)
return {"directory": str(folder), "artifact_pass": not audit.failures, "checks_count": audit.count,
"failures": audit.failures, "required_artifacts": sorted(required), "observations": observations if not audit.failures else {}}
def self_test():
count = 0
def checked(condition):
nonlocal count
assert condition
count += 1
# Deliberately different value/residual factors and shape offsets catch the
# tempting but invalid reuse of the state basis as a residual test basis.
b = np.array([[1., .4], [1., -.1], [1., -.3]])
sx = np.array([2., 3., 5., 7., 11., 13., 17.])
rf = np.array([.2, .3, .7, 1.1, 1.3, 1.7, 1.9])
summary = dict(full_size=7, shape_size=3, mode_count=2, shape_value_offset=1, shape_residual_offset=3, identity_control=0)
px, tx = np.linalg.qr(sx[1:4, None] * b)
qf, tf = np.linalg.qr(b / rf[3:6, None])
maps = dict(zip(MAPS, (b, px, qf, tx, tf)))
c = Coordinates(summary, maps)
a = Audit(); c.validate(sx, rf, a); checked(not a.failures)
z = np.arange(1., 7.)
f = np.arange(-3., 4.)
checked(vector_near(c.restrict(c.inject(z), False), z))
checked(vector_near(c.restrict(c.inject(z, True)), z))
checked(near(norm(f) ** 2, norm(c.restrict(f)) ** 2 + norm(c.excluded(f)) ** 2))
physical_dual = einsum("ij,i->j", b, f[3:6] / rf[3:6])
checked(vector_near(einsum("ji,j->i", tf, c.restrict(f)[3:5]), physical_dual))
bad = Coordinates(summary, {**maps, "residual_basis": px})
a = Audit(); bad.validate(sx, rf, a); checked("maps:dual_QR" in a.failures)
a = Audit(); c.validate(sx, rf[::-1], a); checked(bool(a.failures))
checked(norm(c.restrict(c.excluded(f))) < 1e-14)
# Full-rank bases may rotate the coordinates. Verify the recovered full
# direction, not equality of the rotated coefficient arrays.
bfull = np.array([[1., .4, .2], [1., -.1, .7], [1., -.3, -.6]])
px, tx = np.linalg.qr(sx[1:4, None] * bfull)
qf, tf = np.linalg.qr(bfull / rf[3:6, None])
full = Coordinates({**summary, "mode_count": 3}, dict(zip(MAPS, (bfull, px, qf, tx, tf))))
op = np.diag(np.arange(2., 9.)) + .03 * np.ones((7, 7))
columns = []
for i in range(7):
columns.append(full.restrict(einsum("ij,j->i", op, full.inject(np.eye(7)[:, i]))))
reduced_op = np.column_stack(columns)
result = full.inject(np.linalg.solve(reduced_op, -full.restrict(f)))
checked(vector_near(result, np.linalg.solve(op, -f)))
identity = Coordinates({**summary, "mode_count": 3, "identity_control": 1}, {})
checked(np.array_equal(identity.inject(f), f) and np.array_equal(identity.restrict(f), f))
checked(np.array_equal(identity.excluded(f), np.zeros(7)))
# A reduced zero defect can coexist with a substantial discarded full one.
discarded = c.excluded(f)
checked(norm(discarded) > .1 and norm(c.restrict(discarded)) < 1e-14)
import csv
import tempfile
def fixture(folder, identity=False):
folder.mkdir()
def save(name, array):
array = np.asarray(array)
with (folder / (P + name + ".txt")).open("w") as stream:
stream.write((f"{len(array)}" if array.ndim == 1 else f"{array.shape[0]} {array.shape[1]}") + "\n")
np.savetxt(stream, array.ravel(), fmt="%.17g")
def csv_save(name, columns, records):
with (folder / (P + name + ".csv")).open("w", newline="") as stream:
writer = csv.writer(stream); writer.writerow(columns); writer.writerows(records)
n, s, k, vo, ro = 18, 12, 9, 1, 4
points = []
for i in range(s):
z = 1 - 2 * (i + .5) / s
phi = i * math.pi * (3 - math.sqrt(5))
points.append((math.sqrt(1 - z * z) * math.cos(phi), math.sqrt(1 - z * z) * math.sin(phi), z))
points = np.asarray(points)
raw, modes = harmonics(points, 2)
weights = np.ones(s)
gram = einsum("ni,n,nj->ij", raw, weights, raw)
transform = np.linalg.inv(np.linalg.cholesky(gram).T)
b = einsum("ij,jk->ik", raw, transform)
sx, rf = np.linspace(1., 3., n), np.linspace(.4, 2., n)
px, tx = np.linalg.qr(sx[vo:vo + s, None] * b)
qf, tf = np.linalg.qr(b / rf[ro:ro + s, None])
maps = dict(zip(MAPS, (b, px, qf, tx, tf)))
summary = dict(schema_version=1, full_size=n, shape_size=s, mode_count=s if identity else k,
shape_value_offset=vo, shape_residual_offset=ro, identity_control=int(identity),
maximum_degree=0 if identity else 2, reduced_size=n if identity else n - s + k,
linear_relative_tolerance=.03, linear_absolute_tolerance=0., linear_maximum_iterations=200,
linear_restart=160, linear_status=0, linear_iterations=7, linear_seconds=.01,
algebra_self_check_passed=1, accepted_commits=0, accepted_buffers_bitwise_identical=1,
normalization_factors_bitwise_identical=1, direction_buffers_bitwise_identical=1,
restored_residual_error=0, restored_action_error=0, preparations=8, probe_exception=0)
c = Coordinates(summary, {} if identity else maps)
reduced_direction = np.sin(np.arange(summary["reduced_size"]) + 1.)
direction = c.inject(reduced_direction)
action = direction.copy()
residual = -action + c.excluded(np.cos(np.arange(n)))
base = np.linspace(.1, .3, n)
data = dict(base=base, physical_base=base / sx, residual=residual, direction=direction,
physical_direction=direction / sx, action=action, defect=residual + action,
state_factors=sx, residual_factors=rf, reduced_direction=reduced_direction,
restored_residual=residual, restored_action=action)
for name in ("residual", "action", "defect"):
data["reduced_" + name] = c.restrict(data[name])
for name in ("residual", "defect"):
data["excluded_" + name] = c.excluded(data[name])
for label, prefix in (("full", ""), ("reduced", "reduced_")):
fn, dn = norm(data[prefix + "residual"]), norm(data[prefix + "defect"])
summary[label + "_base_norm"] = fn
summary[label + "_relative_defect"] = dn / fn
summary[label + "_verified_gate"] = int(dn <= .03 * fn)
summary[label + "_merit_slope"] = float(einsum("i,i->", data[prefix + "residual"], data[prefix + "action"]))
summary["linear_reported_true_norm"] = norm(data["reduced_defect"])
summary["direction_norm"] = norm(direction)
summary["excluded_base_norm"] = norm(data["excluded_residual"])
for name, values in data.items():
save(name, values)
csv_save("summary", ["metric", "value"], summary.items())
csv_save("layout", ["kind", "block", "offset", "size"],
[("value", "density", 0, vo), ("value", "surface_deformation", vo, s), ("value", "tail", vo + s, n - vo - s),
("residual", "head", 0, ro), ("residual", "surface_shape_balance", ro, s), ("residual", "tail", ro + s, n - ro - s)])
trials = []
for index, alpha in enumerate(ALPHAS):
save(f"candidate_a{index}", base + alpha * direction)
if index == 0:
trials.append((index, alpha, 0, 0, 0, "nan", "nan", "nan", 0, 0, "nan", "nan"))
continue
f = residual + alpha * action + .025 * alpha ** 2 * residual
fr = c.restrict(f)
remainder = f - residual - alpha * action
save(f"physical_candidate_a{index}", (base + alpha * direction) / sx)
save(f"residual_a{index}", f); save(f"reduced_residual_a{index}", fr)
trials.append((index, alpha, 1, -1, -1, norm(f), norm(fr), norm(c.excluded(f)),
int(norm(f) <= (1 - 1e-4 * alpha) * norm(residual)),
int(norm(fr) <= (1 - 1e-4 * alpha) * norm(data["reduced_residual"])),
norm(remainder), norm(c.restrict(remainder))))
csv_save("trials", ["sample", "alpha", "prepared", "reason", "stage", "full_norm", "reduced_norm", "excluded_shape_norm",
"full_merit_pass", "reduced_merit_pass", "full_remainder_norm", "reduced_remainder_norm"], trials)
if not identity:
for name, values in maps.items():
save(name, values)
for name, values in {"basis_raw": raw, "gram_raw": gram, "coefficient_transform": transform,
"gram_orthonormal": einsum("ij,ik,kl->jl", transform, gram, transform),
"basis_samples_raw": raw, "basis_weights": weights}.items():
save(name, values)
csv_save("basis_nodes", ["parameter", "unit_radial_x", "unit_radial_y", "unit_radial_z", "reference_radius", "physical_radius", "base_parameter"],
[(i, *point, 1., 1 + data["physical_base"][vo + i], data["physical_base"][vo + i]) for i, point in enumerate(points)])
csv_save("basis_modes", ["column", "degree", "m", "pivot_norm", "relative_pivot"],
[(i, m["degree"], m["m"], 1 / transform[i, i], 1 / (transform[i, i] * math.sqrt(gram[i, i]))) for i, m in enumerate(modes)])
metadata = dict(maximum_degree=2, modes=k, surface_parameters=s, quadrature=14, surface_quadrature_points=s,
physical_surface_area=s, accepted_buffers_unchanged=1, prepared_state_unchanged=1, normalization_factors_unchanged=1,
vector_displacement_metric_claimed=0, base_projection_performed=0, trial_preparations=0,
radial_trace_validation_actions=1, metric_scope="scalar_radial_amplitude_FE_trace_mass_on_current_physical_surface",
maximum_gram_orthogonality_error=1e-15, maximum_sample_reconstruction_error=0.,
adjoint_relative_error=0., rank_relative_pivot_threshold=1e-12)
csv_save("basis_metadata", ["metric", "value"], metadata.items())
return save
with tempfile.TemporaryDirectory() as tmp:
folder = Path(tmp) / "reduced"
save = fixture(folder)
result = inspect(folder)
assert result["artifact_pass"], result["failures"]
checked(result["artifact_pass"])
checked(result["observations"]["classification"] == "reduced_gate_only_not_full_Newton")
for name in ("residual_basis", "candidate_a1", "excluded_residual", "gram_raw", "state_factors"):
path = folder / (P + name + ".txt")
original = path.read_bytes()
values = matrix(path) if name in ("residual_basis", "gram_raw") else vector(path)
values.flat[0] += .02
save(name, values)
checked(not inspect(folder)["artifact_pass"])
path.write_bytes(original)
summary_path = folder / (P + "summary.csv")
original = summary_path.read_text()
summary_path.write_text(original.replace("full_verified_gate,0", "full_verified_gate,1"))
checked(not inspect(folder)["artifact_pass"])
summary_path.write_text(original)
save("residual_a0", np.ones(18))
checked(not inspect(folder)["artifact_pass"])
(folder / (P + "residual_a0.txt")).unlink()
identity_folder = Path(tmp) / "identity"
fixture(identity_folder, True)
result = inspect(identity_folder)
checked(result["artifact_pass"] and result["observations"]["classification"] == "full_and_reduced_gates_pass")
print(f"{count} tiny algebra, end-to-end artifact and corruption checks passed")
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("directories", nargs="*")
parser.add_argument("--output", type=Path)
parser.add_argument("--self-test", action="store_true")
args = parser.parse_args()
if args.self_test:
self_test()
return 0
if not args.directories or args.output is None:
parser.error("Provide probe directories and a fresh output JSON")
output = args.output.resolve()
if output.exists() or any(output.is_relative_to(Path(d).resolve()) for d in args.directories):
parser.error("Use a fresh output outside immutable probe directories")
cases = [inspect(d) for d in args.directories]
result = {"schema_version": 1, "passed": all(c["artifact_pass"] for c in cases), "checker_sha256": digest(__file__),
"tolerances": {"relative": RTOL, "cancellation_epsilon_multiplier": 2048}, "cases": cases,
"scope": "Independent saved-vector and map algebra only. Reduced success does not certify the unrestricted equations, FEM evaluation, or physical validity."}
output.parent.mkdir(parents=True, exist_ok=True)
output.write_text(json.dumps(result, indent=2, allow_nan=False) + "\n")
print(f"{'PASS' if result['passed'] else 'FAIL'}: {len(cases)} cases; {output}")
return 0 if result["passed"] else 1
if __name__ == "__main__":
sys.exit(main())

View File

@@ -0,0 +1,377 @@
#!/usr/bin/env python3
"""Check up to three ordered frozen reduced-surface probes as an affine chain.
This checks saved handoffs and the common physical shape span. Individual FEM
artifact audits remain separate; --case-audit binds their completed JSON reviews
without rerunning their larger matrix checks. Passing this audit establishes
neither an unrestricted Newton solve nor a physically valid stellar endpoint.
"""
import argparse
import csv
import hashlib
import json
import math
import os
from pathlib import Path
import sys
for _name in ("OPENBLAS_NUM_THREADS", "OMP_NUM_THREADS", "MKL_NUM_THREADS", "VECLIB_MAXIMUM_THREADS"):
os.environ[_name] = "1"
import numpy as np
PREFIX = "reduced_surface_"
EPS = np.finfo(float).eps
def digest(path):
result = hashlib.sha256()
with Path(path).open("rb") as stream:
for chunk in iter(lambda: stream.read(1024 * 1024), b""):
result.update(chunk)
return result.hexdigest()
def rows(path):
with Path(path).open(newline="") as stream:
reader = csv.DictReader(stream)
if not reader.fieldnames or len(set(reader.fieldnames)) != len(reader.fieldnames):
raise ValueError(f"Missing or duplicate CSV columns: {path}")
result = list(reader)
if any(None in row or any(value is None for value in row.values()) for row in result):
raise ValueError(f"Malformed CSV data: {path}")
return result
def finite(value):
result = float(value)
if not math.isfinite(result):
raise ValueError(f"Nonfinite value: {value}")
return result
def integer(value):
result = finite(value)
if result != int(result):
raise ValueError(f"Nonintegral value: {value}")
return int(result)
def load(path, matrix=False):
with Path(path).open() as stream:
shape = tuple(int(value) for value in stream.readline().split())
values = np.loadtxt(stream, ndmin=1)
if len(shape) != (2 if matrix else 1) or min(shape) <= 0 or values.ndim != 1 or values.size != math.prod(shape):
raise ValueError(f"Invalid saved array dimensions: {path}")
if not np.isfinite(values).all():
raise ValueError(f"Nonfinite saved array: {path}")
return values.reshape(shape)
def norm(values):
# Stable scaling keeps an overflowing squared norm from becoming an
# apparently permissive infinite threshold in the handoff checks.
scale = float(np.max(np.abs(values), initial=0.))
result = 0. if scale == 0. else scale * math.sqrt(float(np.sum((values / scale) ** 2)))
return finite(result)
def compare(actual, expected, atol, rtol):
if actual.shape != expected.shape:
return {"passed": False, "reason": "shape_mismatch"}
difference = actual - expected
bound = atol + rtol * np.maximum(np.abs(actual), np.abs(expected))
maximum = float(np.max(np.abs(difference), initial=0.))
scale = max(norm(actual), norm(expected))
return {"passed": bool(np.all(np.abs(difference) <= bound)),
"bitwise_equal": actual.tobytes() == expected.tobytes(),
"maximum_absolute_difference": maximum, "difference_norm": norm(difference),
"relative_difference_norm": norm(difference) / scale if scale else 0.,
"absolute_tolerance": atol, "relative_tolerance": rtol}
def span_check(basis, increment, reference, atol, rtol):
coefficients, _, rank, singular = np.linalg.lstsq(basis, increment, rcond=None)
if not np.isfinite(coefficients).all() or not np.isfinite(singular).all():
raise ValueError("Nonfinite least-squares coefficients or singular values")
# This small validation contraction needs no BLAS dispatch. Explicit
# products also make a real overflow distinguishable from platform BLAS
# floating-status warnings observed despite finite saved input vectors.
with np.errstate(over="raise", invalid="raise", divide="raise"):
reconstructed = np.sum(basis * coefficients[None, :], axis=1)
if not np.isfinite(reconstructed).all():
raise ValueError("Nonfinite reconstructed shape increment")
residual = increment - reconstructed
error, size = norm(residual), norm(increment)
# Subtracting two full shape bases has a small absolute rounding floor;
# report it separately rather than inflating the relative span tolerance.
subtraction_floor = float(64 * EPS * max(norm(reference), norm(reference + increment), 1e-300))
threshold = float(atol * math.sqrt(increment.size) + subtraction_floor + rtol * size)
return {"passed": bool(int(rank) == basis.shape[1] and error <= threshold),
"rank": int(rank), "requested_rank": basis.shape[1], "increment_norm": size,
"projection_error_norm": error, "relative_projection_error": error / size if size else 0.,
"projection_error_threshold": threshold, "subtraction_roundoff_allowance": subtraction_floor,
"largest_singular_value": float(singular[0]), "smallest_singular_value": float(singular[-1]),
"coefficients": coefficients.tolist()}
def inspect(directories, atol=1e-14, rtol=5e-10, span_rtol=5e-10, reviews=()):
failures, checks, cases, links = [], 0, [], []
def check(label, condition):
nonlocal checks
checks += 1
if not condition:
failures.append(label)
individual = {}
review_hashes = {}
try:
folders = [Path(path).resolve() for path in directories]
if not 1 <= len(folders) <= 3 or len(set(folders)) != len(folders):
raise ValueError("Provide one to three distinct case directories in chain order")
for review_path in reviews:
review_path = Path(review_path).resolve()
review = json.loads(review_path.read_text())
review_hashes[str(review_path)] = digest(review_path)
for case in review.get("cases", [review]):
if "directory" not in case:
raise ValueError("Individual review lacks its case directory")
key = str(Path(case["directory"]).resolve())
if key in individual:
raise ValueError(f"Duplicate individual case review: {key}")
individual[key] = case
for index, folder in enumerate(folders):
used = {}
def file(name, extension=".txt"):
path = folder / (PREFIX + name + extension)
used[path.name] = digest(path)
return path
summary_rows = rows(file("summary", ".csv"))
summary = {row["metric"]: finite(row["value"]) for row in summary_rows}
if len(summary) != len(summary_rows):
raise ValueError("Duplicate summary metrics")
layout = rows(file("layout", ".csv"))
shape_rows = [row for row in layout if row["kind"] == "value" and row["block"] == "surface_deformation"]
if len(shape_rows) != 1:
raise ValueError("Missing or duplicate physical shape value block")
offset, size = (integer(shape_rows[0][key]) for key in ("offset", "size"))
data = {name: load(file(name)) for name in
("physical_base", "base", "residual", "state_factors", "residual_factors", "reduced_residual", "reduced_defect")}
basis = load(file("basis_raw"), matrix=True)
n = data["base"].size
check(f"case{index}:shape_layout", 0 <= offset <= n - size and size > 0 and basis.shape[0] == size)
check(f"case{index}:array_dimensions", all(data[key].shape == (n,) for key in
("physical_base", "residual", "state_factors", "residual_factors")))
check(f"case{index}:positive_factors", bool(np.all(data["state_factors"] > 0) and np.all(data["residual_factors"] > 0)))
roundtrip = compare(data["base"], data["state_factors"] * data["physical_base"], atol, rtol)
check(f"case{index}:physical_normalized_roundtrip", roundtrip["passed"])
check(f"case{index}:reduced_model", summary["identity_control"] == 0 and
summary["shape_value_offset"] == offset and summary["shape_size"] == size and
summary["mode_count"] == basis.shape[1])
reduced_norm, defect_norm = norm(data["reduced_residual"]), norm(data["reduced_defect"])
relative, absolute = summary["linear_relative_tolerance"], summary["linear_absolute_tolerance"]
check(f"case{index}:linear_tolerance", 0 < relative < 1 and absolute >= 0 and reduced_norm > 0)
threshold = max(relative * reduced_norm, absolute)
reduced_gate = defect_norm <= threshold
check(f"case{index}:reported_reduced_gate", summary["reduced_verified_gate"] in (0, 1) and
bool(summary["reduced_verified_gate"]) == reduced_gate)
trials = rows(file("trials", ".csv"))
unit_rows = [row for row in trials if integer(row["sample"]) == 0]
if len(unit_rows) != 1 or finite(unit_rows[0]["alpha"]) != 1.:
raise ValueError("Expected exactly one alpha=1 sample zero")
unit = unit_rows[0]
unit_prepared = integer(unit["prepared"])
check(f"case{index}:unit_prepared_boolean", unit_prepared in (0, 1))
candidate = None
merit = {"prepared": bool(unit_prepared)}
if unit_prepared:
candidate = {name: load(file(name + "_a0")) for name in
("physical_candidate", "candidate", "residual", "reduced_residual")}
full_pass = norm(candidate["residual"]) <= (1. - 1e-4) * norm(data["residual"])
reduced_pass = norm(candidate["reduced_residual"]) <= (1. - 1e-4) * reduced_norm
for label, passed in (("full", full_pass), ("reduced", reduced_pass)):
flag = integer(unit[label + "_merit_pass"])
check(f"case{index}:reported_{label}_unit_merit", flag in (0, 1) and bool(flag) == passed)
merit.update(full_merit_pass=full_pass, reduced_merit_pass=reduced_pass,
full_norm=norm(candidate["residual"]), reduced_norm=norm(candidate["reduced_residual"]))
else:
check(f"case{index}:unprepared_merit_flags", integer(unit["full_merit_pass"]) == integer(unit["reduced_merit_pass"]) == 0)
qualifies = bool(reduced_gate and unit_prepared and merit.get("full_merit_pass") and merit.get("reduced_merit_pass"))
# Only predecessor probes must offer a successful handoff. A final
# failed or rejected unit trial honestly terminates a valid prefix.
if index < len(folders) - 1:
check(f"case{index}:qualifies_for_next_base", qualifies)
run_path, provenance_path = folder.parent / (folder.name + "_run.json"), folder.parent / "provenance.json"
run = json.loads(run_path.read_text())
provenance = json.loads(provenance_path.read_text())
check(f"case{index}:completed_producer", bool(run.get("finished_utc")) and run.get("exit_code") == 0 and not run.get("timed_out", False))
for name, observed in used.items():
check(f"case{index}:producer_hash:{name}", run.get("output_hashes", {}).get(name) == observed)
binding = individual.get(str(folder))
bound = False
if reviews:
check(f"case{index}:individual_review_present", binding is not None)
if binding is not None:
source = binding.get("observations", {}).get("provenance", {})
bound = bool(binding.get("artifact_pass") and source.get("bound") and
source.get("run_sha256") == digest(run_path) and
source.get("provenance_sha256") == digest(provenance_path))
check(f"case{index}:individual_review_bound", bound)
record = {"directory": str(folder), "input_hashes": used, "run_sha256": digest(run_path),
"provenance_sha256": digest(provenance_path), "individual_audit_bound": bound,
"normalization_roundtrip": roundtrip, "reduced_verified_gate": reduced_gate,
"reduced_defect_norm": defect_norm, "reduced_gate_threshold": threshold,
"unit_trial": merit, "qualifies_for_continuation": qualifies,
"physical_shape_span": None}
if index == 0:
first_basis, first_shape = basis, data["physical_base"][offset:offset + size].copy()
shared_hashes = {name: used[PREFIX + name + extension] for name, extension in
(("layout", ".csv"), ("state_factors", ".txt"), ("residual_factors", ".txt"), ("basis_raw", ".txt"))}
first_provenance = provenance
else:
for name, expected in shared_hashes.items():
extension = ".csv" if name == "layout" else ".txt"
check(f"case{index}:identical_{name}", used[PREFIX + name + extension] == expected)
for key in ("binary_sha256", "mesh_sha256"):
check(f"case{index}:identical_{key}", bool(provenance.get(key)) and provenance.get(key) == first_provenance.get(key))
if previous_candidate is None:
raise ValueError("A chain predecessor has no prepared unit candidate")
comparisons = {label: compare(data[current], previous_candidate[prior], atol, rtol) for label, current, prior in
(("physical", "physical_base", "physical_candidate"), ("normalized", "base", "candidate"),
("residual", "residual", "residual"))}
for label, observation in comparisons.items():
check(f"handoff{index}:{label}", observation["passed"])
links.append({"from": str(folders[index - 1]), "to": str(folder), **comparisons})
observation = span_check(first_basis, data["physical_base"][offset:offset + size] - first_shape,
first_shape, atol, span_rtol)
check(f"case{index}:same_affine_shape_span", observation["passed"])
record["physical_shape_span"] = observation
cases.append(record)
previous_candidate = candidate
except (OSError, ValueError, KeyError, TypeError, IndexError, FloatingPointError, np.linalg.LinAlgError) as error:
check("complete_consistent_chain_inputs:" + str(error), False)
passed = not failures
all_bound = bool(cases) and len(cases) == len(directories) and all(case["individual_audit_bound"] for case in cases)
return {"schema_version": 1, "passed": passed, "checks_count": checks, "failures": failures,
"individual_audits_all_bound": all_bound, "complete_artifact_validation": passed and all_bound,
"case_audit_hashes": review_hashes, "cases": cases, "handoffs": links,
"tolerances": {"handoff_absolute": atol, "handoff_relative": rtol, "shape_span_relative": span_rtol},
"scope": "Frozen saved-vector affine chain only; individual artifact audits are separate. No new FEM evaluation, unrestricted convergence, admissibility certificate, or physical validation is claimed."}
def self_test():
# A good endpoint difference can be small in total norm yet outside the
# allowed shape span. The orthogonal perturbation must still be caught.
basis = np.array([[1., 0.], [0., 1.], [1., 1.]])
reference = np.array([.1, .2, .3])
increment = basis @ np.array([.03, -.01])
span = span_check(basis, increment, reference, 1e-14, 5e-10)
assert span["passed"]
assert json.loads(json.dumps(span, allow_nan=False))["passed"] is True
assert not span_check(basis, increment + 1e-5 * np.array([1., 1., -1.]), reference, 1e-14, 5e-10)["passed"]
assert not span_check(np.column_stack((basis[:, 0], basis[:, 0])), increment, reference, 1e-14, 5e-10)["passed"]
assert compare(reference, reference.copy(), 1e-14, 5e-10)["bitwise_equal"]
roundtrip = compare(reference + 2e-15, reference, 1e-14, 5e-10)
assert roundtrip["passed"] and not roundtrip["bitwise_equal"]
assert not compare(reference + 1e-5, reference, 1e-14, 5e-10)["passed"]
# Two tiny producer folders exercise the handoff logic itself, including
# the distinction between an honest stopped prefix and a falsely extended
# chain. These are not substitutes for independent per-case FEM audits.
import tempfile
with tempfile.TemporaryDirectory() as temporary:
root = Path(temporary)
(root / "provenance.json").write_text(json.dumps({"binary_sha256": "synthetic", "mesh_sha256": "synthetic"}))
def csv_save(folder, name, columns, values):
with (folder / (PREFIX + name + ".csv")).open("w", newline="") as stream:
writer = csv.writer(stream)
writer.writerow(columns)
writer.writerows(values)
def save(folder, name, array):
array = np.asarray(array)
with (folder / (PREFIX + name + ".txt")).open("w") as stream:
stream.write(" ".join(str(value) for value in array.shape) + "\n")
np.savetxt(stream, array.ravel(), fmt="%.17g")
def seal(folder):
record = {"finished_utc": "synthetic_complete", "exit_code": 0,
"output_hashes": {path.name: digest(path) for path in folder.iterdir()}}
(root / (folder.name + "_run.json")).write_text(json.dumps(record))
first, second = root / "first", root / "second"
for index, folder in enumerate((first, second)):
folder.mkdir()
base = np.array([1., .1 * index, .1 * index, 1.])
candidate = base + np.array([0., .1, .1, 0.])
residual = np.full(4, .5 ** index)
reduced = np.full(3, .5 ** index)
for name, array in {"physical_base": base, "base": base, "residual": residual,
"state_factors": np.ones(4), "residual_factors": np.ones(4),
"reduced_residual": reduced, "reduced_defect": .01 * reduced,
"basis_raw": np.ones((2, 1)), "physical_candidate_a0": candidate,
"candidate_a0": candidate, "residual_a0": .5 * residual,
"reduced_residual_a0": .5 * reduced}.items():
save(folder, name, array)
csv_save(folder, "summary", ("metric", "value"),
{"identity_control": 0, "shape_value_offset": 1, "shape_size": 2, "mode_count": 1,
"linear_relative_tolerance": .03, "linear_absolute_tolerance": 0., "reduced_verified_gate": 1}.items())
csv_save(folder, "layout", ("kind", "block", "offset", "size"),
(("value", "head", 0, 1), ("value", "surface_deformation", 1, 2), ("value", "tail", 3, 1)))
csv_save(folder, "trials", ("sample", "alpha", "prepared", "full_merit_pass", "reduced_merit_pass"),
((0, 1, 1, 1, 1),))
seal(folder)
result = inspect((first, second))
assert result["passed"], result["failures"]
assert json.loads(json.dumps(result, allow_nan=False))["passed"] is True
assert not result["complete_artifact_validation"]
original = (first / (PREFIX + "reduced_defect.txt")).read_bytes()
save(first, "reduced_defect", np.ones(3))
seal(first)
result = inspect((first, second))
assert not result["passed"] and "case0:qualifies_for_next_base" in result["failures"]
(first / (PREFIX + "reduced_defect.txt")).write_bytes(original)
seal(first)
save(second, "physical_base", np.array([1., .10001, .1, 1.]))
seal(second)
result = inspect((first, second))
assert not result["passed"] and "handoff1:physical" in result["failures"]
print("12 tiny affine-span, JSON, handoff, complete-prefix and corruption checks passed")
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("directories", nargs="*", type=Path)
parser.add_argument("--output", type=Path)
parser.add_argument("--case-audit", type=Path, action="append", default=[])
parser.add_argument("--absolute-tolerance", type=float, default=1e-14)
parser.add_argument("--relative-tolerance", type=float, default=5e-10)
parser.add_argument("--span-relative-tolerance", type=float, default=5e-10)
parser.add_argument("--self-test", action="store_true")
args = parser.parse_args()
if args.self_test:
self_test()
return 0
if not 1 <= len(args.directories) <= 3 or args.output is None:
parser.error("Provide one to three ordered case directories and --output")
tolerances = (args.absolute_tolerance, args.relative_tolerance, args.span_relative_tolerance)
if any(not math.isfinite(value) or value < 0 for value in tolerances):
parser.error("Tolerances must be finite and nonnegative")
output = args.output.resolve()
if output.exists() or any(output.is_relative_to(path.resolve()) for path in args.directories):
parser.error("Use a fresh output outside immutable case directories")
result = inspect(args.directories, *tolerances, reviews=args.case_audit)
result["checker_sha256"] = digest(__file__)
output.parent.mkdir(parents=True, exist_ok=True)
output.write_text(json.dumps(result, indent=2, allow_nan=False) + "\n")
print(f"{'PASS' if result['passed'] else 'FAIL'}: {result['checks_count']} chain checks; {output}")
return 0 if result["passed"] else 1
if __name__ == "__main__":
sys.exit(main())

View File

@@ -0,0 +1,799 @@
#!/usr/bin/env python3
"""Audit frozen shape/field artifacts without reevaluating FEM.
Use the NumPy-enabled Python environment. The SVD is taken directly on the tall
matrix of saved block actions: squaring its condition number through a Gram
matrix would obscure precisely the weak response this experiment investigates.
Physical observations use broken scalar gradients, not RT transport or DG jump
distributions. Neither these observations nor a small restricted singular value
identify a physical gauge or establish the rank of the complete Jacobian.
"""
import argparse
import csv
import hashlib
import json
import math
import os
from pathlib import Path
import sys
# Avoid competing with a later numerical campaign through a threaded BLAS pool.
for _name in ("OPENBLAS_NUM_THREADS", "OMP_NUM_THREADS", "MKL_NUM_THREADS", "VECLIB_MAXIMUM_THREADS"):
os.environ[_name] = "1"
import numpy as np
P = "weak_shape_"
PP = P + "physical_"
EPS = np.finfo(float).eps
RTOL = 5e-10
FIELDS = ("density", "specific_enthalpy", "gravity_potential")
INTEGRALS = ("base_integral", "pullback_integral", "transport_integral", "eulerian_integral",
"base_squared_integral", "pullback_squared_integral", "transport_squared_integral",
"eulerian_squared_integral", "pullback_transport_cross_integral")
SQUARES = INTEGRALS[4:8]
def digest(path):
h = hashlib.sha256()
with Path(path).open("rb") as stream:
for chunk in iter(lambda: stream.read(1024 * 1024), b""):
h.update(chunk)
return h.hexdigest()
def rows(path):
with Path(path).open(newline="") as stream:
reader = csv.DictReader(stream)
if not reader.fieldnames or len(set(reader.fieldnames)) != len(reader.fieldnames):
raise ValueError(f"Missing or duplicate CSV columns: {path}")
result = list(reader)
if any(None in row or any(v is None for v in row.values()) for row in result):
raise ValueError(f"Malformed CSV row: {path}")
return result
def finite(value):
number = float(value)
if not math.isfinite(number):
raise ValueError(f"Nonfinite available value: {value}")
return number
def integer(value):
number = finite(value)
if number != int(number):
raise ValueError(f"Nonintegral count/index: {value}")
return int(number)
def vector(path):
with Path(path).open() as stream:
size = int(stream.readline().strip())
data = np.loadtxt(stream, dtype=float, ndmin=1)
if size <= 0 or data.ndim != 1 or data.size != size or not np.isfinite(data).all():
raise ValueError(f"Invalid finite vector: {path}")
return data
def norm(value):
return float(np.linalg.norm(value))
def checked_einsum(subscripts, *operands):
# NumPy 2.2.6 / Accelerate can flag invalid/divide/overflow for a bounded
# 257x6 matrix product whose answer agrees with scalar fsum to 4e-15.
# Direct contractions avoid that BLAS path; finite and reconstruction
# checks remain mandatory, with no warning suppression or relaxed bounds.
if any(not np.isfinite(operand).all() for operand in operands):
raise ValueError("Nonfinite contraction input")
result = np.einsum(subscripts, *operands, optimize=False)
if not np.isfinite(result).all():
raise ValueError("Nonfinite contraction result")
return result
def near(a, b, scale=0.):
return math.isfinite(a) and math.isfinite(b) and abs(a - b) <= (
RTOL * max(abs(a), abs(b)) + 2048 * EPS * abs(scale) + 1e-28)
def vector_near(a, b, scale=0.):
return a.shape == b.shape and near(norm(a - b), 0., scale + norm(a) + norm(b))
def ratio(a, b):
return finite(a / b) if b > 0 else None
class Audit:
def __init__(self):
self.count = 0
self.failures = []
def check(self, name, condition):
self.count += 1
if not bool(condition):
self.failures.append(name)
def close(self, name, actual, expected, scale=0.):
self.check(name, near(actual, expected, scale))
def table(path, key):
result = {}
for row in rows(path):
index = key(row)
if index in result:
raise ValueError(f"Duplicate row {index}: {path}")
result[index] = row
return result
def layout(path, size):
result = {}
all_rows = rows(path)
if any(r["kind"] not in ("value", "residual") for r in all_rows):
raise ValueError("Unknown layout kind")
for kind in ("value", "residual"):
entries = [r for r in all_rows if r["kind"] == kind]
offset, names, blocks = 0, set(), []
for row in entries:
start, count = integer(row["offset"]), integer(row["size"])
if start != offset or count <= 0 or row["block"] in names:
raise ValueError(f"Invalid {kind} layout partition")
names.add(row["block"])
blocks.append((row["block"], start, count))
offset += count
if offset != size:
raise ValueError(f"Incomplete {kind} layout partition")
result[kind] = blocks
return result
def restricted_svd(direction, actions, blocks, audit):
norms = np.array([norm(direction[o:o+n]) for _, o, n in blocks])
active = [i for i, x in enumerate(norms) if x > 0.]
for i, x in enumerate(norms):
if x == 0.:
audit.check(f"zero_direction_block_action:{i}", norm(actions[i]) == 0.)
if not active:
raise ValueError("No nonzero block directions")
matrix = np.column_stack([actions[i] / norms[i] for i in active])
if not np.isfinite(matrix).all():
raise ValueError("Nonfinite scaled block action")
u, singular, vh = np.linalg.svd(matrix, full_matrices=False)
weights = vh[-1].copy()
# Fix sign for reproducible reporting; repeated singular values still permit
# different equally valid vectors, which the JSON explicitly acknowledges.
if weights[np.argmax(np.abs(weights))] < 0:
weights *= -1
combination = np.zeros_like(direction)
action = np.zeros_like(direction)
coefficients = {}
for weight, i in zip(weights, active):
name, start, count = blocks[i]
coefficient = float(weight / norms[i])
combination[start:start+count] = coefficient * direction[start:start+count]
action += coefficient * actions[i]
coefficients[name] = {"orthonormal_basis_weight": float(weight),
"saved_block_direction_multiplier": coefficient}
scale = float(singular[0])
audit.close("restricted_svd:unit_direction", norm(combination), 1.)
audit.close("restricted_svd:smallest_action_norm", norm(action), float(singular[-1]), scale)
audit.check("restricted_svd:action_reconstruction", vector_near(action, checked_einsum("ij,j->i",matrix,weights), scale))
audit.check("restricted_svd:factorization", vector_near(matrix, checked_einsum("ij,jk->ik",u*singular,vh), norm(matrix)))
audit.check("restricted_svd:finite", np.isfinite(singular).all() and np.isfinite(vh).all())
return {
"scope": "Jacobian restricted to nonzero normalized saved block directions; not full Jacobian rank or nullspace",
"basis": "disjoint block directions divided by their normalized coefficient two-norm",
"active_blocks": [blocks[i][0] for i in active], "singular_values": singular.tolist(),
"condition_ratio_in_restricted_span": ratio(float(singular[0]), float(singular[-1])),
"smallest_direction_norm": norm(combination), "smallest_action_norm": norm(action),
"coefficients": coefficients,
"reconstructed_direction_float64_sha256": hashlib.sha256(combination.astype("<f8").tobytes()).hexdigest(),
"reconstructed_action_float64_sha256": hashlib.sha256(action.astype("<f8").tobytes()).hexdigest(),
"smallest_singular_value_gap": float(singular[-2] - singular[-1]) if len(singular) > 1 else None,
"qualification": "basis metric is coefficient normalization; vector sign fixed, degenerate subspace basis not unique"
}, action
def surface_fit(surface, physical, physical_direction, blocks, audit):
shape = next(b for b in blocks if b[0] == "surface_deformation")
_, offset, size = shape
audit.check("surface:complete_parameter_indices", sorted(surface) == list(range(size)))
ordered = [surface[i] for i in range(size)]
audit.check("surface:unique_volume_dofs", len({integer(r["volume_scalar_true_dof"]) for r in ordered}) == size)
audit.check("surface:nonnegative_volume_dofs", all(integer(r["volume_scalar_true_dof"]) >= 0 for r in ordered))
xyz = np.array([[finite(r["unit_radial_" + axis]) for axis in "xyz"] for r in ordered])
data = np.array([finite(r["physical_direction_parameter"]) for r in ordered])
for i, row in enumerate(ordered):
r0, r = finite(row["reference_radius"]), finite(row["physical_radius"])
b = finite(row["base_parameter"])
audit.check(f"surface:radii:{i}", r0 > 0 and r > 0)
audit.close(f"surface:unit_radial:{i}", norm(xyz[i]), 1.)
audit.close(f"surface:radius_identity:{i}", r, r0 + b, abs(r0) + abs(b))
audit.close(f"surface:base:{i}", b, float(physical[offset+i]))
audit.close(f"surface:direction:{i}", data[i], float(physical_direction[offset+i]))
x, y, z = xyz.T
columns = [np.ones(size), x, y, z, x*y, x*z, y*z, x*x-y*y, 3*z*z-1]
fits = []
for degree, count in ((0, 1), (1, 4), (2, 9)):
matrix = np.column_stack(columns[:count])
coef, _, rank, singular = np.linalg.lstsq(matrix, data, rcond=None)
residual = data - checked_einsum("ij,j->i",matrix,coef)
audit.check(f"surface:fit_finite:{degree}", np.isfinite(coef).all() and np.isfinite(singular).all())
fits.append({"maximum_degree": degree, "rank": int(rank), "basis_coefficients": coef.tolist(),
"relative_nodal_l2_remainder": ratio(norm(residual), norm(data)),
"nodal_l2_remainder": norm(residual), "singular_values": singular.tolist()})
return {"scope": "unweighted nodal least squares in real l=0,1,2 polynomial spans; not area-weighted harmonic coefficients or gauge identification",
"basis": ["1", "nx", "ny", "nz", "nx*ny", "nx*nz", "ny*nz", "nx^2-ny^2", "3*nz^2-1"],
"direction_nodal_l2": norm(data), "direction_maximum_absolute": float(np.max(np.abs(data))), "fits": fits}
def physical_analysis(folder, physical, physical_direction, blocks, audit, required):
def read(suffix, key):
name = PP + suffix + ".csv"
required.add(name)
return table(folder / name, key)
metadata = read("metadata", lambda r: r["key"])
meta = {k: r["value"] for k, r in metadata.items()}
audit.check("physical:schema", meta["schema"] == "weak_shape_physical_v1")
audit.check("physical:declared_scalar_scope", "broken" in meta["dg_derivatives"] and "not evaluated" in meta["gravity_vector"])
elem = read("elements", lambda r: (integer(r["quadrature"]), integer(r["element"]), r["field"]))
geometry = read("geometry", lambda r: (integer(r["quadrature"]), integer(r["element"])))
affine = read("affine", lambda r: (integer(r["quadrature"]), integer(r["element"])))
surface = read("surface_nodes", lambda r: integer(r["parameter"]))
summary = read("summary", lambda r: (integer(r["quadrature"]), r["field"], r["metric"]))
observed = {key: finite(r["value"]) for key, r in summary.items()}
expected_summary = set()
def compare(q, field, metric, expected, scale=0.):
key = (q, field, metric)
expected_summary.add(key)
audit.close("physical:summary:" + str(key), observed[key], expected, scale)
audit.check("physical:quadrature_coverage", {q for q, _ in geometry} == {10, 14})
ids = {e for q, e in geometry if q == 10}
audit.check("physical:same_elements_at_both_rules", ids and ids == {e for q, e in geometry if q == 14})
audit.check("physical:affine_coverage", set(affine) == set(geometry))
audit.check("physical:field_coverage", set(elem) == {(q, e, f) for q, e in geometry for f in FIELDS})
outputs = []
for q in (10, 14):
geo = [geometry[(q, e)] for e in sorted(ids)]
aff = [affine[(q, e)] for e in sorted(ids)]
for e, g, a in zip(sorted(ids), geo, aff):
for key in g:
if key not in ("quadrature", "element"):
finite(g[key])
volume = finite(g["physical_volume"])
audit.check(f"physical:geometry_positive:{q}:{e}", volume > 0 and integer(g["points"]) > 0)
for prefix in ("reference", "physical"):
lo, hi = finite(g[prefix+"_radius_min"]), finite(g[prefix+"_radius_max"])
audit.check(f"physical:radius_range:{q}:{e}:{prefix}", 0 <= lo <= hi)
for key in ("base_displacement_squared_integral", "direction_displacement_squared_integral"):
audit.check(f"physical:geometry_square:{q}:{e}:{key}", finite(g[key]) >= 0)
for key, family in (("density_element_order", "density_family_order"),
("enthalpy_element_order", "enthalpy_family_order"),
("potential_element_order", "potential_family_order"),
("displacement_element_order", "displacement_family_order")):
audit.check(f"physical:order:{q}:{e}:{key}", integer(g[key]) == integer(meta[family]))
for key in ("reference_volume", "value_error_squared_integral", "reference_value_squared_integral",
"gradient_error_squared_integral", "reference_gradient_squared_integral"):
audit.check(f"physical:affine_nonnegative:{q}:{e}:{key}", finite(a[key]) >= 0)
audit.check(f"physical:affine_volume:{q}:{e}", finite(a["reference_volume"]) > 0)
audit.check(f"physical:affine_points:{q}:{e}", integer(a["points"]) == integer(g["points"]))
audit.close(f"physical:affine_identity:{q}:{e}", finite(a["reference_gradient_squared_integral"]), 3*finite(a["reference_volume"]))
totals_g = {k: math.fsum(finite(g[k]) for g in geo) for k in
("physical_volume", "base_displacement_squared_integral", "direction_displacement_squared_integral")}
for key, value in totals_g.items():
compare(q, "geometry", key, value)
compare(q, "geometry", "stellar_elements", len(ids))
totals_a = {k: math.fsum(finite(a[k]) for a in aff) for k in
("reference_volume", "value_error_squared_integral", "reference_value_squared_integral",
"gradient_error_squared_integral", "reference_gradient_squared_integral")}
for key, value in totals_a.items():
compare(q, "affine", key, value)
for label, num, den in (("relative_value_l2_error", "value_error_squared_integral", "reference_value_squared_integral"),
("relative_gradient_l2_error", "gradient_error_squared_integral", "reference_gradient_squared_integral")):
compare(q, "affine", label, math.sqrt(totals_a[num] / totals_a[den]))
field_outputs = {}
for field in FIELDS:
records = [elem[(q, e, field)] for e in sorted(ids)]
for e, row, g in zip(sorted(ids), records, geo):
values = {k: finite(row[k]) for k in INTEGRALS}
audit.check(f"physical:gradient_kind:{q}:{e}:{field}", row["gradient_kind"] == ("continuous_H1" if field == "specific_enthalpy" else "broken_DG"))
for key in ("attribute", "geometry", "points"):
audit.check(f"physical:element_binding:{q}:{e}:{field}:{key}", integer(row[key]) == integer(g[key]))
audit.close(f"physical:volume_binding:{q}:{e}:{field}", finite(row["physical_volume"]), finite(g["physical_volume"]))
audit.check(f"physical:squares:{q}:{e}:{field}", all(values[k] >= 0 for k in SQUARES))
for prefix in ("base","pullback","transport","eulerian"):
first,second=values[prefix+"_integral"],values[prefix+"_squared_integral"]
product=finite(row["physical_volume"])*second
audit.check(f"physical:moment_cauchy:{q}:{e}:{field}:{prefix}", first*first <= product+2048*EPS*(first*first+product)+1e-28)
# Signed element moments may themselves cancel. Cauchy bounds
# their absolute quadrature sums using the saved positive moments.
scale = math.sqrt(finite(row["physical_volume"])) * (math.sqrt(values["pullback_squared_integral"])+math.sqrt(values["transport_squared_integral"]))
audit.close(f"physical:signed_identity:{q}:{e}:{field}", values["eulerian_integral"], values["pullback_integral"]-values["transport_integral"], scale)
d2, t2, e2, cross = (values[k] for k in ("pullback_squared_integral", "transport_squared_integral", "eulerian_squared_integral", "pullback_transport_cross_integral"))
audit.close(f"physical:squared_identity:{q}:{e}:{field}", e2, d2+t2-2*cross, d2+t2+2*abs(cross))
audit.check(f"physical:cauchy:{q}:{e}:{field}", abs(cross) <= math.sqrt(d2)*math.sqrt(t2) + 2048*EPS*(d2+t2) + 1e-28)
totals = {k: math.fsum(finite(r[k]) for r in records) for k in INTEGRALS}
for key in (*SQUARES, "pullback_transport_cross_integral"):
compare(q, field, key, totals[key])
for prefix in ("pullback", "transport", "eulerian"):
compare(q, field, prefix+"_l2_norm", math.sqrt(totals[prefix+"_squared_integral"]))
d2, t2, e2, cross = (totals[k] for k in ("pullback_squared_integral", "transport_squared_integral", "eulerian_squared_integral", "pullback_transport_cross_integral"))
compare(q, field, "squared_norm_identity_error", e2-d2-t2+2*cross, d2+t2+2*abs(cross))
audit.close(f"physical:total_squared_identity:{q}:{field}", e2, d2+t2-2*cross, d2+t2+2*abs(cross))
# Each element spans a radius interval. Midpoint bins are explicitly
# element-group summaries, not integrals over exact spherical shells.
bins = []
outer = max(finite(g["physical_radius_max"]) for g in geo)
for low, high in ((0., .25), (.25, .5), (.5, .75), (.75, .9), (.9, 1.0000001)):
chosen = [i for i, g in enumerate(geo) if low <= .5*(finite(g["physical_radius_min"])+finite(g["physical_radius_max"]))/outer < high]
bins.append({"normalized_element_midradius_interval": [low, min(high, 1.)], "elements": len(chosen),
"eulerian_squared_integral": math.fsum(finite(records[i]["eulerian_squared_integral"]) for i in chosen),
"pullback_squared_integral": math.fsum(finite(records[i]["pullback_squared_integral"]) for i in chosen)})
audit.check(f"physical:radial_bin_coverage:{q}:{field}", sum(b["elements"] for b in bins) == len(ids))
top = sorted(zip(sorted(ids), records), key=lambda pair: finite(pair[1]["eulerian_squared_integral"]), reverse=True)[:10]
field_outputs[field] = {"integrals": totals, "eulerian_over_pullback_l2": ratio(math.sqrt(e2), math.sqrt(d2)),
"eulerian_over_pullback_plus_transport_l2": ratio(math.sqrt(e2), math.sqrt(d2)+math.sqrt(t2)),
"pullback_l2_per_unit_displacement_l2": ratio(math.sqrt(d2), math.sqrt(totals_g["direction_displacement_squared_integral"])),
"transport_l2_per_unit_displacement_l2": ratio(math.sqrt(t2), math.sqrt(totals_g["direction_displacement_squared_integral"])),
"eulerian_l2_per_unit_displacement_l2": ratio(math.sqrt(e2), math.sqrt(totals_g["direction_displacement_squared_integral"])),
"eulerian_rms": math.sqrt(e2/totals_g["physical_volume"]),
"pullback_transport_cosine": ratio(cross, math.sqrt(d2)*math.sqrt(t2)),
"radial_element_groups": bins,
"largest_eulerian_elements": [{"element": e, "squared_integral": finite(r["eulerian_squared_integral"]),
"fraction": ratio(finite(r["eulerian_squared_integral"]), e2)} for e, r in top]}
totals_g["direction_displacement_l2"] = math.sqrt(totals_g["direction_displacement_squared_integral"])
totals_g["direction_displacement_rms"] = math.sqrt(totals_g["direction_displacement_squared_integral"]/totals_g["physical_volume"])
outputs.append({"quadrature": q, "geometry": totals_g, "affine": totals_a, "fields": field_outputs})
for metric, expected in (("accepted_trial_prepared_normalization_unchanged", 1.), ("production_mapping_cache_unchanged", 1.),
("trial_preparations", 0.), ("volume_direction_actions", 1.)):
compare(0, "invariant", metric, expected)
for metric in ("maximum_scatter_roundtrip_error", "maximum_surface_trace_error"):
key = (0, "reconstruction", metric)
expected_summary.add(key)
audit.check("physical:"+metric, 0 <= observed[key] <= 512*EPS*max(1., float(np.max(np.abs(physical))), float(np.max(np.abs(physical_direction)))))
audit.check("physical:summary_coverage", set(observed) == expected_summary)
sensitivity = {}
for field in FIELDS:
sensitivity[field] = {}
for key in (*SQUARES, "pullback_transport_cross_integral"):
a, b = (out["fields"][field]["integrals"][key] for out in outputs)
sensitivity[field][key] = {"q10": a, "q14": b, "difference": b-a,
"relative_to_q14": ratio(abs(b-a), abs(b))}
return {"metadata": meta, "quadratures": outputs, "quadrature_sensitivity": sensitivity,
"surface": surface_fit(surface, physical, physical_direction, blocks, audit),
"scope": "recorded stellar broken-scalar integrals; no interface jumps, RT transport, exact shell integrals or continuum gauge test"}
def producer_binding(direction_path, folder, audit):
producer = direction_path.parent
mapping = {"nonlinear_step_physical_base.txt":"physical_base", "nonlinear_step_normalized_base.txt":"base",
"nonlinear_step_state_factors.txt":"state_factors", "nonlinear_step_residual_factors.txt":"residual_factors",
"nonlinear_step_residual.txt":"residual", "nonlinear_step_action_full.txt":"action"}
present = [name for name in mapping if (producer/name).exists()]
if not present:
return {"status":"producer_neighbors_unavailable", "bound":False}
if len(present) != len(mapping) or not (producer/"nonlinear_step_layout.csv").exists():
raise ValueError("Incomplete nonlinear-step direction producer artifacts")
saved_hashes, equal = {}, {}
for name, current in mapping.items():
path=producer/name
saved_hashes[name]=digest(path)
a,b=vector(path),vector(folder/(P+current+".txt"))
exact=np.array_equal(a,b)
equal[name]=exact
audit.check("producer:vector:"+name, exact if "factors" in name else vector_near(a,b))
path=producer/"nonlinear_step_layout.csv"
saved_hashes[path.name]=digest(path)
audit.check("producer:layout", rows(path)==rows(folder/(P+"layout.csv")))
run_path=producer.parent/(producer.name+"_run.json")
run_bound=False
if run_path.exists():
run=json.loads(run_path.read_text())
for name, actual in saved_hashes.items():
audit.check("producer:recorded_output_hash:"+name, run["output_hashes"].get(name)==actual)
audit.check("producer:direction_output_hash", run["output_hashes"].get(direction_path.name)==digest(direction_path))
saved_hashes[run_path.name]=digest(run_path)
run_bound=True
return {"status":"producer_neighbors_compared", "bound":run_bound, "producer":str(producer),
"hashes":saved_hashes,"vectors_bitwise_equal":equal,
"qualification":"neighbor hashes checked against producer run when present; no FEM rerun"}
def provenance(folder, required, audit):
root = folder.parent
source_file, run_file = root / "provenance.json", root / (folder.name + "_run.json")
if not source_file.exists() and not run_file.exists():
return {"status": "unavailable", "bound": False}
if not source_file.exists() or not run_file.exists():
raise ValueError("Partially present campaign provenance")
source, run = (json.loads(p.read_text()) for p in (source_file, run_file))
audit.check("provenance:case_id", run["id"] == folder.name)
command = run["command"]
final_mode = "--weak-shape-final" in command
audit.check("provenance:completed_probe_exit", run["exit_code"] == 0 or (final_mode and run["exit_code"] == 3))
audit.check("provenance:required_output_hashes", required <= set(run["output_hashes"]))
for name, expected in run["output_hashes"].items():
path = folder / name
audit.check("provenance:contained_output:"+name, path.resolve().is_relative_to(folder.resolve()))
audit.check("provenance:output_hash:"+name, digest(path) == expected)
for name, expected in run.get("input_state_hashes", {}).items():
audit.check("provenance:input_hash:"+name, digest(Path(name)) == expected)
case = next(c for c in source["cases"] if c["id"] == folder.name)
expected = [str(root / "plateau_diagnostic"), *case["arguments"], "--mesh", source["mesh"], "--output", str(folder)]
audit.check("provenance:command", command == expected)
audit.check("provenance:binary_hash", digest(Path(command[0])) == source["binary_sha256"])
audit.check("provenance:mesh_hash", digest(Path(source["mesh"])) == source["mesh_sha256"])
manifest = root / "cases.json"
if manifest.exists():
audit.check("provenance:case_manifest", json.loads(manifest.read_text()) == source["cases"])
meta_path=folder/"metadata.txt"
if meta_path.exists():
meta=dict(line.split("=",1) for line in meta_path.read_text().splitlines() if "=" in line)
audit.check("provenance:mode", ("--weak-shape-probe" in command) != final_mode)
audit.check("provenance:metadata_mode", meta["weak_shape_probe"]==str(int(not final_mode)) and meta["weak_shape_final"]==str(int(final_mode)))
audit.check("provenance:metadata_scope", meta["weak_shape_direction_space"]=="normalized_current_factors" and
meta["weak_shape_operator"]=="full_monolithic" and meta["weak_shape_trial_policy"]=="raw_prepare_only")
for option,key in (("--linear-tol","linear_tol"),("--restart","restart"),("--max-linear","max_linear"),
("--max-newton","max_newton"),("--index","n"),("--angular-momentum","J")):
if option in command:
audit.check("provenance:metadata_argument:"+option, finite(command[command.index(option)+1])==finite(meta[key]))
if final_mode:
audit.check("provenance:reported_convergence", integer(meta["converged"])==int(run["exit_code"]==0))
audit.check("provenance:final_accepted_state", np.array_equal(vector(folder/"accepted_state.txt"),vector(folder/(P+"physical_base.txt"))))
producer = None
for option, saved in (("--probe-state", "physical_base"), ("--probe-direction", "direction")):
if option in command:
input_path = Path(command[command.index(option)+1])
if not input_path.is_absolute():
input_path = Path(source["source"]) / input_path
input_path = input_path.resolve()
audit.check("provenance:input_bound:"+option, str(input_path) in run.get("input_state_hashes", {}))
audit.check("provenance:input_vector:"+option, np.array_equal(vector(input_path), vector(folder/(P+saved+".txt"))))
if option == "--probe-direction":
producer = producer_binding(input_path,folder,audit)
return {"status": "runner_hashes_checked", "bound": True, "source_commit": source["commit"],
"provenance_sha256": digest(source_file), "run_sha256": digest(run_file), "binary_sha256": source["binary_sha256"],
"direction_producer":producer}
def inspect(folder):
folder = Path(folder).resolve()
audit, required, observations = Audit(), set(), {}
try:
def get(name):
filename = P + name + ".txt"
required.add(filename)
return vector(folder / filename)
required.update(P+n+".csv" for n in ("summary", "layout", "blocks", "trials"))
summary = {k: finite(r["value"]) for k, r in table(folder/(P+"summary.csv"), lambda r:r["metric"]).items()}
for key, value in {"schema_version": 1, "accepted_commits": 0, "probe_exception": 0,
"accepted_buffers_bitwise_identical": 1, "normalization_factors_bitwise_identical": 1,
"direction_buffers_bitwise_identical": 1, "maximum_restore_error": 0,
"restored_action_error": 0}.items():
audit.check("summary:"+key, summary[key] == value)
x, xp, f, p, pp, jp, defect, factors, rf = [get(n) for n in
("base", "physical_base", "residual", "direction", "physical_direction", "action", "defect", "state_factors", "residual_factors")]
n = x.size
audit.check("vector_sizes", all(v.size == n for v in (xp,f,p,pp,jp,defect,factors,rf)))
audit.check("summary:state_size", summary["state_size"] == n)
audit.check("positive_factors", np.all(factors > 0) and np.all(rf > 0))
audit.check("denormalized_base", vector_near(xp, x/factors))
audit.check("denormalized_direction", vector_near(pp, p/factors))
audit.check("defect_identity", vector_near(defect, f+jp, norm(f)+norm(jp)))
audit.check("restored_residual_exact", np.array_equal(f, get("restored_residual")))
audit.check("restored_action_exact", np.array_equal(jp, get("restored_action")))
fn, pn, jn, dn = map(norm, (f,p,jp,defect))
if fn <= 0 or pn <= 0:
raise ValueError("Probe requires nonzero base residual and direction")
threshold = max(summary["outer_absolute_tolerance"], summary["outer_tolerance"]*fn)
audit.check("valid_linear_controls", 0 < summary["outer_tolerance"] < 1 and summary["outer_absolute_tolerance"] >= 0 and
integer(summary["maximum_iterations"]) > 0 and integer(summary["restart"]) > 0)
for key, value in {"base_norm":fn, "direction_norm":pn, "action_norm":jn, "verified_defect_norm":dn,
"verified_relative_defect":dn/fn, "verified_threshold":threshold}.items():
audit.close("summary:"+key, summary[key], value)
audit.check("verified_gate_truth", summary["verified_gate"] in (0,1) and bool(summary["verified_gate"]) == (dn <= threshold))
audit.check("supplied_direction_flag", summary["supplied_direction"] in (0,1))
if not summary["supplied_direction"]:
audit.close("linear_reported_true_norm", summary["linear_reported_true_norm"], dn, fn+jn)
audit.check("linear_iterations", 0 <= integer(summary["linear_iterations"]) <= integer(summary["maximum_iterations"]))
blocks = layout(folder/(P+"layout.csv"), n)
actions = [get("action_b"+str(i)) for i in range(len(blocks["value"]))]
audit.check("split_column_count", summary["split_columns"] == len(actions))
audit.check("direct_action_count", summary["direct_jacobian_applications"] == len(actions)+2)
audit.check("preparation_count", summary["preparations"] == 6 + int(not summary["supplied_direction"]))
audit.check("finite_nonnegative_probe_time", summary["total_probe_seconds"] >= 0)
total = np.sum(actions, axis=0)
action_scale = math.fsum(norm(a) for a in actions)
audit.check("split_action_sum", vector_near(total, jp, action_scale))
audit.close("reported_split_error", summary["split_action_sum_error"], norm(total-jp), action_scale)
reported = table(folder/(P+"blocks.csv"), lambda r:(integer(r["column"]),r["residual_block"]))
audit.check("block_table_coverage", set(reported) == {(i,r[0]) for i in range(len(actions)) for r in blocks["residual"]})
for i,(name,start,count) in enumerate(blocks["value"]):
for rname,offset,size in blocks["residual"]:
row = reported[(i,rname)]
audit.check(f"block_metadata:{i}:{rname}", row["value_block"]==name and integer(row["value_offset"])==start and
integer(row["value_size"])==count and integer(row["residual_offset"])==offset and integer(row["residual_size"])==size)
audit.close(f"block_direction_norm:{i}:{rname}", finite(row["direction_norm"]), norm(p[start:start+count]))
audit.close(f"block_action_norm:{i}:{rname}", finite(row["action_norm"]), norm(actions[i][offset:offset+size]))
svd, smallest_action = restricted_svd(p, actions, blocks["value"], audit)
svd["smallest_action_residual_blocks"] = {name:norm(smallest_action[o:o+s]) for name,o,s in blocks["residual"]}
trial_rows = table(folder/(P+"trials.csv"), lambda r:integer(r["trial"]))
audit.check("trial_coverage", set(trial_rows)=={0,1,2})
trials = []
for i,alpha in enumerate((1/128,1/512,1/2048)):
row = trial_rows[i]
audit.check(f"trial_alpha:{i}", finite(row["alpha"])==alpha)
audit.check(f"trial_prepared_flag:{i}", row["prepared"] in ("0","1"))
audit.check(f"trial_candidate:{i}", vector_near(get("candidate_a"+str(i)), x+alpha*p, norm(x)+alpha*pn))
prediction = f+alpha*jp
audit.close(f"trial_prediction_norm:{i}", finite(row["linear_prediction_norm"]), norm(prediction))
prepared = row["prepared"]=="1"
entry = {"trial":i, "alpha":alpha, "prepared":prepared, "reason":integer(row["reason"]), "stage":integer(row["stage"])}
if prepared:
audit.check(f"trial_prepared_reasons:{i}", entry["reason"] == entry["stage"] == -1)
ft = get("residual_a"+str(i)); remainder = ft-prediction
values = {"residual_norm":norm(ft), "remainder_norm":norm(remainder), "remainder_over_alpha":norm(remainder)/alpha}
for key,value in values.items():
audit.close(f"trial:{i}:{key}", finite(row[key]), value, (fn+alpha*jn+norm(ft)) / (alpha if key=="remainder_over_alpha" else 1))
entry.update(values)
entry.update(residual_over_base=norm(ft)/fn, remainder_over_alpha_squared=norm(remainder)/alpha**2,
linear_dot_remainder=float(checked_einsum("i,i->",prediction,remainder)))
else:
audit.check(f"trial_failed_reasons:{i}", entry["reason"]>=0 and entry["stage"]>=0)
audit.check(f"trial_failed_vector_absent:{i}", not (folder/(P+"residual_a"+str(i)+".txt")).exists())
audit.check(f"trial_failed_metrics:{i}", all(math.isnan(float(row[k])) for k in ("residual_norm","remainder_norm","remainder_over_alpha")))
trials.append(entry)
physical_data = physical_analysis(folder,xp,pp,blocks["value"],audit,required)
if (folder/"metadata.txt").exists():
required.add("metadata.txt")
meta=dict(line.split("=",1) for line in (folder/"metadata.txt").read_text().splitlines() if "=" in line)
for key,source in (("outer_tolerance","linear_tol"),("restart","restart"),("maximum_iterations","max_linear")):
audit.check("metadata:linear_control:"+key,summary[key]==finite(meta[source]))
if meta.get("weak_shape_final")=="1":
required.add("accepted_state.txt")
binding = provenance(folder,required,audit)
observations = {"summary":summary, "provenance":binding,
"linear_classification":"verified_newton_direction" if dn<=threshold else "finite_direction_failed_true_gate",
"verified_linear_gate":dn<=threshold, "restricted_block_span_svd":svd, "trials":trials,
"block_action_cancellation_factor":ratio(action_scale,jn), "physical":physical_data,
"input_vector_hashes":{name:digest(folder/(P+name+".txt")) for name in ("physical_base","base","direction","state_factors","residual_factors")},
"layout_sha256":digest(folder/(P+"layout.csv"))}
except (OSError, ValueError, KeyError, TypeError, IndexError, StopIteration, OverflowError, ZeroDivisionError, np.linalg.LinAlgError) as error:
audit.check("complete_consistent_artifacts: " + str(error),False)
passed = not audit.failures
return {"directory":str(folder), "artifact_pass":passed, "observations_valid":passed,
"checks_count":audit.count, "failures":audit.failures,
"required_artifacts":sorted(required), "observations":observations if passed else {}}
def comparisons(cases):
output=[]
for i,left in enumerate(cases):
for right in cases[i+1:]:
if not left["artifact_pass"] or not right["artifact_pass"]:
continue
a,b=left["observations"],right["observations"]
same_layout=a["layout_sha256"]==b["layout_sha256"]
same={k:a["input_vector_hashes"][k]==b["input_vector_hashes"][k] for k in a["input_vector_hashes"]}
output.append({"left":left["directory"],"right":right["directory"],"same_layout":same_layout,"same_saved_vectors":same,
"same_state_metric_comparison":same_layout and all(same[k] for k in ("physical_base","base","state_factors","residual_factors")),
"qualification":"different discretizations or factors require physical comparisons; raw coefficient norms are not comparable"})
return output
def tiny_fixture(folder, failed_gate=False):
"""Construct a complete eight-coordinate synthetic producer, with no FEM."""
folder.mkdir(parents=True,exist_ok=True)
def save(name,v):
(folder/(P+name+".txt")).write_text(str(len(v))+"\n"+"\n".join(format(float(x),".17g") for x in v)+"\n")
def write(name,records):
with (folder/name).open("w",newline="") as stream:
out=csv.DictWriter(stream,fieldnames=list(records[0]));out.writeheader();out.writerows(records)
sf=np.arange(1.,9.);xp=np.array([2.,0.,0.,0.,0.,0.,0.,1.]);x=xp*sf
p=np.arange(1.,9.)*1e-4;f=-p;jp=p*(.9 if failed_gate else 1.)
for name,v in {"base":x,"physical_base":xp,"residual":f,"direction":p,"physical_direction":p/sf,
"action":jp,"defect":f+jp,"state_factors":sf,"residual_factors":np.ones(8),
"restored_residual":f,"restored_action":jp}.items():save(name,v)
blocks=[("density",0,1),("surface_deformation",1,6),("constant",7,1)]
write(P+"layout.csv",[{"kind":kind,"block":name,"offset":o,"size":n} for kind in ("value","residual") for name,o,n in blocks])
br=[]
for i,(name,o,n) in enumerate(blocks):
a=np.zeros(8);a[o:o+n]=jp[o:o+n];save("action_b"+str(i),a)
for rn,ro,rs in blocks:
br.append(dict(column=i,value_block=name,value_offset=o,value_size=n,residual_block=rn,residual_offset=ro,
residual_size=rs,direction_norm=norm(p[o:o+n]),action_norm=norm(a[ro:ro+rs])))
write(P+"blocks.csv",br)
summary=dict(schema_version=1,state_size=8,supplied_direction=1,accepted_commits=0,outer_tolerance=.03,
outer_absolute_tolerance=0,maximum_iterations=200,restart=160,base_norm=norm(f),direction_norm=norm(p),
action_norm=norm(jp),verified_defect_norm=norm(f+jp),verified_relative_defect=norm(f+jp)/norm(f),
verified_threshold=.03*norm(f),verified_gate=int(not failed_gate),split_columns=3,split_action_sum_error=0,
restored_action_error=0,probe_exception=0,accepted_buffers_bitwise_identical=1,normalization_factors_bitwise_identical=1,
direction_buffers_bitwise_identical=1,maximum_restore_error=0,preparations=6,direct_jacobian_applications=5,total_probe_seconds=1.)
write(P+"summary.csv",[dict(metric=k,value=v) for k,v in summary.items()])
tr=[]
for i,a in enumerate((1/128,1/512,1/2048)):
save("candidate_a"+str(i),x+a*p);pred=f+a*jp;ft=pred+a*a*np.ones(8)*1e-5;save("residual_a"+str(i),ft)
tr.append(dict(trial=i,alpha=a,prepared=1,reason=-1,stage=-1,residual_norm=norm(ft),remainder_norm=norm(ft-pred),
remainder_over_alpha=norm(ft-pred)/a,linear_prediction_norm=norm(pred)))
write(P+"trials.csv",tr)
meta=dict(schema="weak_shape_physical_v1",dg_derivatives="broken DG derivatives",gravity_vector="not evaluated",
density_family_order="2",enthalpy_family_order="3",potential_family_order="2",displacement_family_order="3")
write(PP+"metadata.csv",[dict(key=k,value=v) for k,v in meta.items()])
elements=[];geometry=[];affine=[];ps=[]
for q in (10,14):
g=dict(quadrature=q,element=0,attribute=1,geometry=5,points=8,reference_mesh_geometry_order=4,density_element_order=2,
enthalpy_element_order=3,potential_element_order=2,displacement_element_order=3,reference_radius_min=.1,
reference_radius_max=.9,physical_radius_min=.1,physical_radius_max=.9,physical_volume=1.,
base_displacement_squared_integral=0.,direction_displacement_squared_integral=.2)
geometry.append(g)
ar=dict(quadrature=q,element=0,points=8,reference_volume=1.,value_error_squared_integral=.01,
reference_value_squared_integral=1.,gradient_error_squared_integral=.03,reference_gradient_squared_integral=3.)
affine.append(ar)
for field in FIELDS:
vals=dict(zip(INTEGRALS,(2.,3.,2.,1.,4.,9.,4.,1.,6.)))
elements.append(dict(quadrature=q,element=0,attribute=1,geometry=5,field=field,
gradient_kind="continuous_H1" if field=="specific_enthalpy" else "broken_DG",points=8,physical_volume=1.,**vals))
measured={k:vals[k] for k in (*SQUARES,"pullback_transport_cross_integral")}
measured.update(pullback_l2_norm=3.,transport_l2_norm=2.,eulerian_l2_norm=1.,squared_norm_identity_error=0.)
ps.extend(dict(quadrature=q,field=field,metric=k,value=v) for k,v in measured.items())
ps.extend(dict(quadrature=q,field="geometry",metric=k,value=v) for k,v in
dict(stellar_elements=1,physical_volume=1.,base_displacement_squared_integral=0.,direction_displacement_squared_integral=.2).items())
am={k:v for k,v in ar.items() if k not in ("quadrature","element","points")}
am.update(relative_value_l2_error=.1,relative_gradient_l2_error=.1)
ps.extend(dict(quadrature=q,field="affine",metric=k,value=v) for k,v in am.items())
ps.extend(dict(quadrature=0,field="invariant",metric=k,value=v) for k,v in
dict(accepted_trial_prepared_normalization_unchanged=1,production_mapping_cache_unchanged=1,trial_preparations=0,volume_direction_actions=1).items())
ps.extend(dict(quadrature=0,field="reconstruction",metric=k,value=0.) for k in
("maximum_scatter_roundtrip_error","maximum_surface_trace_error"))
for name,data in (("elements",elements),("geometry",geometry),("affine",affine),("summary",ps)):write(PP+name+".csv",data)
xyz=[[1.,0.,0.],[-1.,0.,0.],[0.,1.,0.],[0.,-1.,0.],[0.,0.,1.],[0.,0.,-1.]]
write(PP+"surface_nodes.csv",[dict(parameter=i,volume_scalar_true_dof=i,unit_radial_x=v[0],unit_radial_y=v[1],
unit_radial_z=v[2],reference_radius=1.,physical_radius=1.,base_parameter=0.,physical_direction_parameter=p[i+1]/sf[i+1]) for i,v in enumerate(xyz)])
def self_test():
"""Tiny algebraic controls only; never opens campaign artifacts."""
import tempfile
count=0
def require(condition):
nonlocal count
assert condition
count+=1
audit=Audit()
p=np.array([2.,3.,0.])
actions=[np.array([2.,0.,0.]),np.array([-3.,3e-8,0.]),np.zeros(3)]
out,action=restricted_svd(p,actions,[("a",0,1),("b",1,1),("zero",2,1)],audit)
require(not audit.failures)
require(near(out["singular_values"][-1],1e-8/math.sqrt(2),1e-8))
require(out["active_blocks"]==["a","b"])
require(norm(action)<1e-7)
bad=Audit();restricted_svd(p,actions[:2]+[np.ones(3)],[("a",0,1),("b",1,1),("zero",2,1)],bad)
require(bool(bad.failures))
require(not vector_near(np.array([1.,2.]),np.array([1.,2.001])))
require(near(1e-20,0.,1.))
# This size triggers spurious Accelerate matmul flags on the investigation
# host. Use independent scalar sums, not another BLAS product, as the oracle.
a=np.linspace(-1.,1.,257*6).reshape(257,6);v=np.arange(1.,7.)
expected=np.array([math.fsum(float(x*y) for x,y in zip(row,v)) for row in a])
with np.errstate(divide="raise",over="raise",invalid="raise"):
require(vector_near(checked_einsum("ij,j->i",a,v),expected,norm(expected)))
b=np.arange(18.).reshape(6,3)/18.
expected_matrix=np.array([[math.fsum(float(a[i,k]*b[k,j]) for k in range(6)) for j in range(3)] for i in range(257)])
require(vector_near(checked_einsum("ij,jk->ik",a,b),expected_matrix,norm(expected_matrix)))
try:checked_einsum("i,i->",np.array([math.inf]),np.ones(1));raise AssertionError("nonfinite contraction accepted")
except ValueError:require(True)
with tempfile.TemporaryDirectory() as directory:
d=Path(directory)
(d/"v").write_text("3\n1\n2\n3\n")
require(np.array_equal(vector(d/"v"),np.array([1.,2.,3.])))
for text in ("2\n1\n", "2\n1\nnan\n", "2\n1\ninf\n"):
(d/"v").write_text(text)
try:vector(d/"v");raise AssertionError("invalid vector accepted")
except ValueError:require(True)
(d/"layout").write_text("kind,block,offset,size\nvalue,a,0,2\nresidual,b,0,2\n")
require(layout(d/"layout",2)["value"]==[("a",0,2)])
(d/"layout").write_text("kind,block,offset,size\nvalue,a,1,2\nresidual,b,0,2\n")
try:layout(d/"layout",2);raise AssertionError("bad layout accepted")
except ValueError:require(True)
xyz=np.array([[1.,0.,0.],[-1.,0.,0.],[0.,1.,0.],[0.,-1.,0.],[0.,0.,1.],[0.,0.,-1.]])
values=2.+3.*xyz[:,0]
surf={i:{"volume_scalar_true_dof":str(i),"unit_radial_x":str(v[0]),"unit_radial_y":str(v[1]),"unit_radial_z":str(v[2]),
"reference_radius":"1","physical_radius":"1","base_parameter":"0","physical_direction_parameter":str(values[i])} for i,v in enumerate(xyz)}
audit=Audit();fits=surface_fit(surf,np.zeros(6),values,[("surface_deformation",0,6)],audit)
require(not audit.failures)
require(fits["fits"][1]["relative_nodal_l2_remainder"]<1e-14)
require(fits["fits"][0]["relative_nodal_l2_remainder"]>.1)
with tempfile.TemporaryDirectory() as directory:
d=Path(directory).resolve()/"case"
tiny_fixture(d)
result=inspect(d)
assert result["artifact_pass"],result["failures"]
require(result["observations"]["verified_linear_gate"])
require(result["observations"]["provenance"]["status"]=="unavailable")
require(result["observations"]["physical"]["quadratures"][0]["fields"]["density"]["eulerian_over_pullback_plus_transport_l2"]==.2)
tiny_fixture(d,failed_gate=True)
result=inspect(d)
require(result["artifact_pass"] and result["observations"]["linear_classification"]=="finite_direction_failed_true_gate")
for name in ("defect.txt","restored_action.txt","candidate_a1.txt","physical_base.txt","action_b1.txt"):
tiny_fixture(d)
path=d/(P+name);lines=path.read_text().splitlines();lines[1]=str(float(lines[1])+.001);path.write_text("\n".join(lines)+"\n")
require(not inspect(d)["artifact_pass"])
for filename,key in (("elements","pullback_transport_cross_integral"),("summary","value"),("geometry","physical_volume")):
tiny_fixture(d);path=d/(PP+filename+".csv");data=rows(path);data[0][key]=str(float(data[0][key])+.1)
with path.open("w",newline="") as stream:
writer=csv.DictWriter(stream,fieldnames=list(data[0]));writer.writeheader();writer.writerows(data)
require(not inspect(d)["artifact_pass"])
for missing in (False,True):
tiny_fixture(d);path=d/(PP+"summary.csv");data=rows(path)
if missing:data=[r for r in data if r["metric"]!="production_mapping_cache_unchanged"]
else:
next(r for r in data if r["metric"]=="production_mapping_cache_unchanged")["value"]="0"
with path.open("w",newline="") as stream:
writer=csv.DictWriter(stream,fieldnames=list(data[0]));writer.writeheader();writer.writerows(data)
require(not inspect(d)["artifact_pass"])
tiny_fixture(d)
path=d/(P+"trials.csv");data=rows(path);data[0].update(prepared="0",reason="2",stage="3",
residual_norm="nan",remainder_norm="nan",remainder_over_alpha="nan")
with path.open("w",newline="") as stream:
writer=csv.DictWriter(stream,fieldnames=list(data[0]));writer.writeheader();writer.writerows(data)
(d/(P+"residual_a0.txt")).unlink()
require(inspect(d)["artifact_pass"])
tiny_fixture(d)
root=d.parent
executable=root/"plateau_diagnostic";executable.write_text("synthetic binary fixture")
mesh=root/"mesh";mesh.write_text("synthetic mesh fixture")
case={"id":"case","arguments":["--weak-shape-probe"]}
prov={"commit":"0"*40,"source":str(root),"cases":[case],"mesh":str(mesh),"mesh_sha256":digest(mesh),"binary_sha256":digest(executable)}
(root/"provenance.json").write_text(json.dumps(prov))
run={"id":"case","exit_code":0,"input_state_hashes":{},"command":[str(executable),"--weak-shape-probe","--mesh",str(mesh),"--output",str(d)],
"output_hashes":{p.name:digest(p) for p in d.iterdir()}}
(root/"case_run.json").write_text(json.dumps(run))
result=inspect(d)
assert result["artifact_pass"],result["failures"]
require(result["observations"]["provenance"]["bound"])
run["output_hashes"][P+"action.txt"]="0"*64
(root/"case_run.json").write_text(json.dumps(run))
require(not inspect(d)["artifact_pass"])
producer=root/"producer";producer.mkdir()
for old,new in {"physical_base":"physical_base","normalized_base":"base","state_factors":"state_factors",
"residual_factors":"residual_factors","residual":"residual","action_full":"action","direction_full":"direction"}.items():
(producer/("nonlinear_step_"+old+".txt")).write_bytes((d/(P+new+".txt")).read_bytes())
(producer/"nonlinear_step_layout.csv").write_bytes((d/(P+"layout.csv")).read_bytes())
(root/"producer_run.json").write_text(json.dumps({"output_hashes":{p.name:digest(p) for p in producer.iterdir()}}))
audit=Audit();bound=producer_binding(producer/"nonlinear_step_direction_full.txt",d,audit)
require(bound["bound"] and not audit.failures)
(producer/"nonlinear_step_state_factors.txt").write_text("8\n"+"2\n"*8)
audit=Audit();producer_binding(producer/"nonlinear_step_direction_full.txt",d,audit)
require(bool(audit.failures))
print(f"{count} tiny synthetic checks passed")
def main():
parser=argparse.ArgumentParser(description=__doc__)
parser.add_argument("directories",nargs="*",type=Path)
parser.add_argument("--output",type=Path)
parser.add_argument("--self-test",action="store_true")
args=parser.parse_args()
if args.self_test:
self_test();return 0
if not args.directories or args.output is None:
parser.error("Provide one or more probe directories and --output")
destination=args.output.resolve()
if destination.exists() or any(destination.is_relative_to(d.resolve()) for d in args.directories):
parser.error("Use a fresh output JSON outside the immutable probe directories")
cases=[inspect(d) for d in args.directories]
result={"schema_version":1,"passed":all(c["artifact_pass"] for c in cases),"checker_sha256":digest(Path(__file__)),
"numpy_version":np.__version__,"tolerances":{"relative":RTOL,"cancellation_roundoff_multiplier":2048,"absolute_floor":1e-28},
"scope":"Independent recorded-vector algebra/hash and physical-integral identity audit; no FEM rerun, quadrature rerun, full-rank, gauge, convergence or physical-model certificate",
"cases":cases,"comparisons":comparisons(cases)}
destination.parent.mkdir(parents=True,exist_ok=True)
destination.write_text(json.dumps(result,indent=2,allow_nan=False)+"\n")
print(json.dumps({"passed":result["passed"],"cases":len(cases),"output":str(destination)}))
return 0 if result["passed"] else 1
if __name__=="__main__":
sys.exit(main())

View File

@@ -0,0 +1,397 @@
#!/usr/bin/env python3
"""Check saved native harmonic geometry/force algebra and campaign provenance.
No FEM residual or physical quadrature is recomputed. The force complement is
Euclidean in nodal coordinates, not the solver's dimensioned residual metric.
Artifact consistency, nonlinear convergence and physical accuracy are separate.
"""
import argparse
import csv
import hashlib
import json
import math
import os
from pathlib import Path
import tempfile
for _name in ("OPENBLAS_NUM_THREADS", "OMP_NUM_THREADS", "MKL_NUM_THREADS", "VECLIB_MAXIMUM_THREADS"):
os.environ[_name] = "1"
import numpy as np
EPS = np.finfo(float).eps
RTOL = 5e-10
STAGES = ("initial", "final")
REQUIRED = {"metadata.txt", "layout.csv", "accepted_state.txt", "surface_basis.csv", "newton.csv"} | {
f"{stage}_{suffix}.csv" for stage in STAGES
for suffix in ("physical", "surface_coefficients", "surface_nodal_force", "surface_audit")
}
def digest(path):
h = hashlib.sha256()
with Path(path).open("rb") as stream:
for chunk in iter(lambda: stream.read(1024 * 1024), b""):
h.update(chunk)
return h.hexdigest()
def rows(path):
with Path(path).open(newline="") as stream:
reader = csv.DictReader(stream)
if not reader.fieldnames or len(set(reader.fieldnames)) != len(reader.fieldnames):
raise ValueError(f"Missing/duplicate CSV columns: {path}")
data = list(reader)
if any(None in row or any(v is None for v in row.values()) for row in data):
raise ValueError(f"Malformed CSV row: {path}")
return data
def finite(value):
result = float(value)
if not math.isfinite(result):
raise ValueError(f"Nonfinite available algebraic value: {value}")
return result
def integer(value):
result = finite(value)
if result != int(result):
raise ValueError(f"Nonintegral index/count: {value}")
return int(result)
def keyed(data, key):
result = {key(row): row for row in data}
if len(result) != len(data):
raise ValueError("Duplicate observation key")
return result
def contract(subscripts, *arrays):
if any(not np.isfinite(a).all() for a in arrays):
raise ValueError("Nonfinite contraction input")
# Avoid the Accelerate matmul flag issue observed in the earlier auditors.
result = np.einsum(subscripts, *arrays, optimize=False)
if not np.isfinite(result).all():
raise ValueError("Nonfinite contraction result")
return result
def norm(a):
return math.sqrt(float(contract("i,i->", np.ravel(a), np.ravel(a))))
class Audit:
def __init__(self):
self.checks = []
def check(self, name, condition):
self.checks.append({"check": name, "passed": bool(condition)})
def close(self, name, actual, expected, scale=0.):
a, b = np.asarray(actual, dtype=float), np.asarray(expected, dtype=float)
valid = a.shape == b.shape and np.isfinite(a).all() and np.isfinite(b).all()
self.check(name, valid and norm(a-b) <= RTOL * max(norm(a), norm(b)) + 256 * EPS * abs(scale))
@property
def passed(self):
return all(c["passed"] for c in self.checks)
def modes(degree, maximum_order):
if degree < 0 or maximum_order < -1 or maximum_order > degree:
raise ValueError("Invalid harmonic degree/order")
cutoff = degree if maximum_order == -1 else maximum_order
return [(l, m) for l in range(degree+1) for m in range(-min(l, cutoff), min(l, cutoff)+1)]
def surface_stage(folder, stage, basis, catalog, audit):
label = stage + ":surface:"
coefficients = rows(folder / f"{stage}_surface_coefficients.csv")
forces = rows(folder / f"{stage}_surface_nodal_force.csv")
summary = {k: finite(r["value"]) for k, r in keyed(
rows(folder / f"{stage}_surface_audit.csv"), lambda r: r["metric"]).items()}
n, k = basis.shape
if len(coefficients) != k or len(forces) != n:
raise ValueError("Surface coefficient/force counts disagree with basis")
audit.check(label+"coefficient_indices", [integer(r["index"]) for r in coefficients] == list(range(k)))
audit.check(label+"mode_catalog", [(integer(r["degree"]), integer(r["order"])) for r in coefficients] == catalog)
audit.check(label+"node_indices", [integer(r["node"]) for r in forces] == list(range(n)))
audit.check(label+"reported_dimensions", summary["parameter_count"] == k and summary["nodal_count"] == n)
a = np.array([finite(r["radial_length_coefficient"]) for r in coefficients])
radial, force, excluded = (np.array([finite(r[field]) for r in forces])
for field in ("radial_displacement", "force", "excluded_force"))
audit.close(label+"radial_displacement", radial, contract("ij,j->i", basis, a), norm(basis)*norm(a))
q, r = np.linalg.qr(basis, mode="reduced")
if not np.isfinite(q).all() or not np.isfinite(r).all():
raise ValueError("Nonfinite QR factors")
relative_pivots = np.abs(np.diag(r)) / np.sqrt(contract("ij,ij->j", basis, basis))
audit.check(label+"resolved_mode_rank", np.isfinite(relative_pivots).all() and np.all(relative_pivots > 1e-12))
audit.close(label+"QR_reconstruction", contract("ij,jk->ik", q, r), basis)
audit.close(label+"QR_orthogonality", contract("ij,ik->jk", q, q), np.eye(k))
projection = contract("ij,j->i", q, contract("ij,i->j", q, force))
expected_excluded = force-projection
modal_force = contract("ij,i->j", basis, force)
audit.close(label+"excluded_projection", excluded, expected_excluded, norm(force))
audit.close(label+"excluded_annihilates_modes", contract("ij,i->j", basis, excluded), np.zeros(k),
norm(basis)*norm(force))
audit.close(label+"orthogonal_energy", norm(force)**2, norm(projection)**2 + norm(excluded)**2, norm(force)**2)
audit.close(label+"virtual_work", float(contract("i,i->", a, modal_force)),
float(contract("i,i->", radial, force)), norm(radial)*norm(force))
for metric, actual in (("full_nodal_force_euclidean_norm", norm(force)),
("excluded_nodal_force_euclidean_norm", norm(excluded)),
("modal_force_euclidean_norm", norm(modal_force))):
audit.close(label+metric, summary[metric], actual, norm(basis)*norm(force))
audit.check(label+"producer_equivalence_errors_nonnegative", summary["volume_equivalence_error"] >= 0 and
summary["force_pullback_equivalence_error"] >= 0)
audit.check(label+"producer_pullback_bound", summary["force_pullback_equivalence_error"] <=
1e-11 * (1 + norm(modal_force)))
return a, {"summary": summary, "radial_displacement_euclidean_norm": norm(radial),
"coefficient_euclidean_norm": norm(a), "minimum_relative_QR_pivot": float(min(relative_pivots)),
"excluded_force_fraction": norm(excluded)/norm(force) if norm(force) > 0 else None,
"basis_transpose_excluded_norm": norm(contract("ij,i->j", basis, excluded)),
"volume_and_native_pullback_equivalence": "producer observations; underlying vectors are not saved"}
def physical_stage(folder, stage, metadata, audit):
data = keyed(rows(folder / f"{stage}_physical.csv"), lambda r: (integer(r["quadrature"]), r["metric"]))
audit.check(stage+":physical:quadratures", {q for q, _ in data} == {14, 18})
result = {}
for q in (14, 18):
m = {name: float(row["value"]) for (order, name), row in data.items() if order == q}
label = f"{stage}:physical:q{q}:"
audit.check(label+"model", m["polytropic_index"] == finite(metadata["n"]) and
m["polytropic_constant"] == finite(metadata["K"]))
for key in ("complete_volume_measurement", "pressure_from_enthalpy_defined_everywhere",
"pressure_from_density_defined_everywhere"):
audit.check(label+key+":boolean", m[key] in (0., 1.))
complete = m["complete_volume_measurement"] == 1
if complete:
audit.close(label+"mass_error", m["mass_absolute_error"], abs(m["mass"]-finite(metadata["M"])), abs(m["mass"]))
audit.close(label+"J_error", m["angular_momentum_absolute_error"], abs(m["angular_momentum_z"]-finite(metadata["J"])), 1.)
milestones = {}
for prefix, pressure, valid in (("", "pressure_integral", "pressure_from_density_defined_everywhere"),
("enthalpy_", "enthalpy_pressure_integral", "pressure_from_enthalpy_defined_everywhere")):
defined = complete and m[valid] == 1 and math.isfinite(m["binding_energy"]) and abs(m["binding_energy"]) > 0
for force_prefix, binding in (("", "binding_energy"), ("force_", "force_binding_energy")):
key = prefix+force_prefix+"virial_"
signed, error = m[key+"signed"], m[key+"error"]
if defined:
terms = (2*m["kinetic_energy"], m[binding], 3*m[pressure])
scale = math.fsum(abs(v) for v in terms)/abs(m["binding_energy"])
audit.close(label+key+"identity", signed, math.fsum(terms)/abs(m["binding_energy"]), scale)
audit.close(label+key+"absolute", error, abs(signed), scale)
else:
audit.check(label+key+"undefined", math.isnan(signed) and math.isnan(error))
milestones[key+"within_1e5"] = bool(error <= 1e-5) if defined and math.isfinite(error) else None
audit.check(label+"finite_native_residual", math.isfinite(m["normalized_bordered_residual"]) and
m["normalized_bordered_residual"] >= 0)
result[str(q)] = {"metrics": m, "virial_milestones": milestones,
"undefined_metrics": [name for name, value in m.items() if not math.isfinite(value)]}
return result
def inspect_case(folder, record, metadata, audit):
if metadata["surface_prescription"] != "harmonics":
raise ValueError("The native harmonic auditor requires harmonic cases")
catalog = modes(integer(metadata["surface_degree"]), integer(metadata["surface_maximum_order"]))
with (folder / "surface_basis.csv").open(newline="") as stream:
basis = np.array([[finite(value) for value in row] for row in csv.reader(stream)])
if basis.ndim != 2 or basis.shape[1] != len(catalog) or basis.shape[0] < basis.shape[1]:
raise ValueError("Invalid tall harmonic basis dimensions")
audit.close("basis:monopole_normalization", basis[:, 0], np.full(basis.shape[0], 1/math.sqrt(4*math.pi)))
surface, coefficients = {}, {}
for stage in STAGES:
coefficients[stage], surface[stage] = surface_stage(folder, stage, basis, catalog, audit)
layout = keyed(rows(folder / "layout.csv"), lambda r: (r["kind"], r["block"]))
totals = {}
for kind in ("value", "residual"):
blocks = sorted((r for (k, _), r in layout.items() if k == kind), key=lambda r: integer(r["offset"]))
offset = 0
for row in blocks:
audit.check("layout:"+kind+":"+row["block"], integer(row["offset"]) == offset and integer(row["size"]) > 0 and finite(row["scale"]) > 0)
offset += integer(row["size"])
totals[kind] = offset
audit.check("layout:square", totals["value"] == totals["residual"] > 0)
shape = layout["value", "surface_deformation"]
audit.check("layout:shape_dimensions", integer(shape["size"]) == len(catalog) and
integer(layout["residual", "surface_shape_balance"]["size"]) == len(catalog))
with (folder / "accepted_state.txt").open() as stream:
size = integer(stream.readline())
state = np.loadtxt(stream, ndmin=1)
if state.ndim != 1 or len(state) != size or size != totals["value"] or not np.isfinite(state).all():
raise ValueError("Invalid accepted physical state")
start = integer(shape["offset"])
audit.close("final:coefficients_match_accepted_state", coefficients["final"], state[start:start+len(catalog)])
physics = {stage: physical_stage(folder, stage, metadata, audit) for stage in STAGES}
history = rows(folder / "newton.csv")
audit.check("newton:ordered_iterations", [integer(row["iteration"]) for row in history] == list(range(len(history))))
accepted = 0
before = physics["initial"]["18"]["metrics"]["normalized_bordered_residual"]
for row in history:
label = "newton:"+row["iteration"]+":"
flag, residual, alpha = integer(row["accepted"]), finite(row["F"]), finite(row["alpha"])
audit.check(label+"accepted_boolean", flag in (0, 1))
audit.check(label+"nonnegative_norm", residual >= 0)
for name in ("seconds", "linear_seconds", "prepare_seconds", "refresh_seconds"):
audit.check(label+name, finite(row[name]) >= 0)
if flag == 1:
accepted += 1
audit.check(label+"accepted_alpha", 0 < alpha <= 1)
audit.check(label+"recorded_true_linear_gate", 0 <= finite(row["linear_true"]) <= finite(metadata["linear_tol"])*(1+RTOL))
audit.check(label+"residual_decrease", residual <= before*(1+RTOL))
else:
audit.close(label+"rejected_state_preserved", residual, before)
before = residual
audit.check("newton:accepted_count", integer(metadata["accepted_steps"]) == accepted)
converged = integer(metadata["converged"])
audit.check("newton:converged_boolean", converged in (0, 1))
audit.check("newton:exit_matches_outcome", record["exit_code"] == (0 if converged else 3))
for q in ("14", "18"):
audit.close("newton:final_residual:q"+q, physics["final"][q]["metrics"]["normalized_bordered_residual"], before)
sensitivities = {stage: {name: physics[stage]["18"]["metrics"][name]-value
for name, value in physics[stage]["14"]["metrics"].items()
if math.isfinite(value) and math.isfinite(physics[stage]["18"]["metrics"].get(name, math.nan))}
for stage in STAGES}
return {"metadata": metadata, "modes": catalog, "basis_shape": list(basis.shape), "surface": surface,
"physical": physics, "q18_minus_q14": sensitivities, "newton": history,
"accepted_steps": accepted, "converged": bool(converged), "failure": metadata.get("failure"),
"initial_residual": physics["initial"]["18"]["metrics"]["normalized_bordered_residual"],
"final_residual": before, "summed_iteration_seconds": math.fsum(finite(r["seconds"]) for r in history),
"basis_values_independently_reconstructed": False,
"basis_limitation": "Reference node directions are not saved; mode labels and monopole are checked, not all Y_lm values."}
def audit_campaign(campaign):
campaign = campaign.resolve()
audit, results = Audit(), {}
provenance = json.loads((campaign / "provenance.json").read_text())
cases = provenance["cases"]
audit.check("campaign:manifest", cases == json.loads((campaign / "cases.json").read_text()) and
len(cases) > 0 and len({c["id"] for c in cases}) == len(cases))
audit.check("campaign:binary", digest(campaign / "plateau_diagnostic") == provenance["binary_sha256"])
audit.check("campaign:mesh", digest(provenance["mesh"]) == provenance["mesh_sha256"])
for case in cases:
name, arguments = case["id"], case["arguments"]
local = Audit()
try:
if not name or any(c not in "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-" for c in name):
raise ValueError("Invalid case directory name")
folder = campaign / name
record_path = campaign / (name+"_run.json")
record = json.loads(record_path.read_text())
local.check("provenance:completed", bool(record.get("finished_utc")) and not record.get("timed_out", False) and record.get("exit_code") in (0, 3))
local.check("provenance:command", record["id"] == name and record["command"] ==
[str(campaign / "plateau_diagnostic"), *arguments, "--mesh", provenance["mesh"], "--output", str(folder)])
hashes = record["output_hashes"]
local.check("provenance:required_hashes", REQUIRED <= set(hashes))
observed = {str(p.relative_to(folder)) for p in folder.rglob("*") if p.is_file() and p.suffix in (".txt", ".csv", ".json")}
local.check("provenance:complete_output_manifest", set(hashes) == observed)
for relative, expected in hashes.items():
path = folder / relative
if not path.resolve().is_relative_to(folder.resolve()):
raise ValueError("Output hash path escapes case directory")
local.check("provenance:output:"+relative, digest(path) == expected)
for path, expected in record.get("input_state_hashes", {}).items():
local.check("provenance:input:"+path, digest(path) == expected)
entries = [line.split("=", 1) for line in (folder / "metadata.txt").read_text().splitlines() if "=" in line]
metadata = dict(entries)
if len(metadata) != len(entries):
raise ValueError("Duplicate metadata key")
for option, key in (("--index", "n"), ("--angular-momentum", "J"), ("--surface-degree", "surface_degree"),
("--surface-maximum-order", "surface_maximum_order"), ("--max-newton", "max_newton"),
("--linear-tol", "linear_tol"), ("--max-linear", "max_linear"), ("--restart", "restart")):
if option in arguments:
local.check("requested:"+key, finite(metadata[key]) == finite(arguments[arguments.index(option)+1]))
for option, key in (("--surface-prescription", "surface_prescription"), ("--strategy", "strategy"),
("--preconditioner-variant", "preconditioner_variant")):
if option in arguments:
local.check("requested:"+key, metadata[key] == arguments[arguments.index(option)+1])
if "--no-central" in arguments:
local.check("requested:no_central", metadata["central_phase"] == "0")
result = inspect_case(folder, record, metadata, local)
result["run_sha256"] = digest(record_path)
result["timing"] = {key: record.get(key) for key in ("seconds", "utc_elapsed_seconds", "utc_minus_monotonic_seconds", "child_cpu_seconds")}
except (OSError, ValueError, KeyError, TypeError, IndexError, OverflowError, np.linalg.LinAlgError) as error:
local.check("readable_complete_artifacts:"+str(error), False)
result = {"error": str(error)}
result.update(artifact_passed=local.passed, checks=local.checks)
results[name] = result
audit.check("case:"+name, local.passed)
return {"schema_version": 1, "artifact_passed": audit.passed, "campaign": str(campaign),
"source_commit": provenance["commit"], "provenance_sha256": digest(campaign / "provenance.json"),
"auditor_sha256": digest(__file__), "tolerances": {"relative": RTOL, "arithmetic_allowance_eps": 256},
"scope": "Saved algebra, hashes and reported scalar identities; no fresh FEM, quadrature or model validity certificate.",
"checks": audit.checks, "cases": results}
def self_test():
"""Tiny real-mode fixture; deliberate corruptions must fail independently."""
constant, linear = 1/math.sqrt(4*math.pi), math.sqrt(3/(4*math.pi))
points = np.array([[1, 0, 0], [-1, 0, 0], [0, 1, 0], [0, -1, 0], [0, 0, 1], [0, 0, -1]])
basis = np.column_stack((np.full(6, constant), -linear*points[:, 1], linear*points[:, 2], -linear*points[:, 0]))
coefficients = np.array([.2, .01, .02, .03])
force = np.array([.3, -.4, .2, .7, -.3, .9])
modal = contract("ij,i->j", basis, force)
excluded = force-contract("ij,j->i", basis, modal/contract("ij,ij->j", basis, basis))
radial = contract("ij,j->i", basis, coefficients)
outcomes = []
for corruption in (None, "catalog", "radial", "excluded", "norm", "nonfinite", "coefficient_count"):
with tempfile.TemporaryDirectory() as directory:
folder = Path(directory)
mode_rows = [[i, l, m, coefficients[i]] for i, (l, m) in enumerate(modes(1, -1))]
force_rows = [[i, radial[i], force[i], excluded[i]] for i in range(6)]
summary = {"parameter_count": 4, "nodal_count": 6, "full_nodal_force_euclidean_norm": norm(force),
"excluded_nodal_force_euclidean_norm": norm(excluded), "modal_force_euclidean_norm": norm(modal),
"volume_equivalence_error": 0., "force_pullback_equivalence_error": 0.}
if corruption == "catalog": mode_rows[1][2] = 0
if corruption == "radial": force_rows[0][1] += .01
if corruption == "excluded": force_rows[1][3] += .01
if corruption == "norm": summary["modal_force_euclidean_norm"] += .01
if corruption == "nonfinite": force_rows[2][2] = math.nan
if corruption == "coefficient_count": mode_rows.pop()
for name, header, data in (("coefficients", ("index", "degree", "order", "radial_length_coefficient"), mode_rows),
("nodal_force", ("node", "radial_displacement", "force", "excluded_force"), force_rows),
("audit", ("metric", "value"), summary.items())):
with (folder / ("initial_surface_"+name+".csv")).open("w", newline="") as stream:
writer = csv.writer(stream); writer.writerow(header); writer.writerows(data)
check = Audit()
try:
surface_stage(folder, "initial", basis, modes(1, -1), check)
passed = check.passed
except (ValueError, KeyError):
passed = False
outcomes.append({"fixture": corruption or "valid", "passed": passed == (corruption is None)})
return {"self_test_passed": all(r["passed"] for r in outcomes), "fixtures": outcomes}
def safe(value):
if isinstance(value, float) and not math.isfinite(value): return None
if isinstance(value, dict): return {k: safe(v) for k, v in value.items()}
if isinstance(value, (list, tuple)): return [safe(v) for v in value]
return value
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("campaign", type=Path, nargs="?")
parser.add_argument("--output", type=Path)
parser.add_argument("--self-test", action="store_true")
args = parser.parse_args()
if args.self_test:
result = self_test()
print(json.dumps(result, indent=2))
return 0 if result["self_test_passed"] else 1
if args.campaign is None or args.output is None:
parser.error("A campaign and --output are required unless --self-test is selected")
try:
result = audit_campaign(args.campaign)
except (OSError, ValueError, KeyError, TypeError) as error:
result = {"artifact_passed": False, "error": str(error), "auditor_sha256": digest(__file__)}
args.output.write_text(json.dumps(safe(result), indent=2, allow_nan=False)+"\n")
print("PASS" if result["artifact_passed"] else "FAIL", args.output)
return 0 if result["artifact_passed"] else 1
if __name__ == "__main__":
raise SystemExit(main())

View File

@@ -0,0 +1,497 @@
#!/usr/bin/env python3
"""Audit coupled-trial saved vectors and transactions, not physical convergence.
A retained correction can still fail Armijo. Each alpha is an independent frozen
trial, not one step in a nonlinear trajectory. Saved J actions are checked by
vector algebra; this checker does not perform another FEM operator application.
"""
import argparse
import json
import math
from pathlib import Path
from check_nonlinear_step import EPS, close, digest, dot, layout_for, minus, norm, rows, sanitize, vector
P = 'coupled_trial_'
STATUS = ('not_attempted','original_accepted','budget_exhausted','kept','linear_failure',
'norm_limit','non_finite','inadmissible','not_improved')
GRAVITY_VALUES = {'gravity_gradient','gravity_potential'}
GRAVITY_ROWS = {'gravity_gradient_relation','poisson_balance'}
BASE = {'metadata.txt'} | {P+n+'.csv' for n in ('summary','layout','preparations','trials','blocks','physical')} | {
P+n+'.txt' for n in ('base_normalized','base_physical','base_residual','state_factors','residual_factors',
'direction','base_action','base_defect','restored_residual','restored_action')}
def near_vector(a,b,scale):
return len(a)==len(b) and norm(minus(a,b)) <= 1024*EPS*max(scale,1.e-28)
def finite_ratio(numerator,denominator):
if not math.isfinite(numerator) or not math.isfinite(denominator) or denominator==0:
return None
result=numerator/denominator
return result if math.isfinite(result) else None
def correction_mechanism(base,direction,alpha,prediction,before_residual,corrected_state,
corrected_residual,correction,rhs,action):
"""Describe a saved correction; large remainders are observations, not failed audits.
The candidate Jacobian action gives R_new = (J_candidate c - rhs) + E,
where E is the correction's own Taylor remainder. Improving merit does not
imply that either term or the affine-target remainder becomes smaller.
"""
cn,pn,rn=norm(correction),norm(direction),norm(rhs)
displacement=minus(corrected_state,base)
before=minus(before_residual,prediction)
after=minus(corrected_residual,prediction)
defect=minus(action,rhs)
own_taylor=minus(minus(corrected_residual,before_residual),action)
en,dn=norm(own_taylor),norm(defect)
reconstruction=[v+w for v,w in zip(defect,own_taylor)]
return sanitize({
'correction_direction_cosine':finite_ratio(dot(correction,direction),cn*pn),
'correction_over_rhs_norm':finite_ratio(cn,rn),
'correction_over_alpha_squared':finite_ratio(cn,alpha*alpha),
'corrected_displacement_norm':norm(displacement),
'corrected_displacement_over_outer_step_norm':finite_ratio(norm(displacement),alpha*pn),
'effective_direction_projection_t':finite_ratio(dot(displacement,direction),pn*pn),
'remainder_before_norm':norm(before),
'remainder_after_norm':norm(after),
'verified_linear_defect_norm':dn,
'own_taylor_remainder_norm':en,
'own_taylor_over_correction_squared':finite_ratio(en,cn*cn),
'own_taylor_over_verified_defect':finite_ratio(en,dn),
'linear_defect_dot_own_taylor':dot(defect,own_taylor),
'remainder_decomposition_error_norm':norm(minus(after,reconstruction)),
'scope':'Saved candidate-J vector algebra; normalized coefficient norms, with no new FEM action or asymptotic-order claim.'})
def inspect_case(folder):
try:
return inspect_case_artifacts(Path(folder))
except (OSError,ValueError,KeyError,TypeError,IndexError,OverflowError,ZeroDivisionError) as error:
return {'passed':False,'checks':[{'check':'complete_readable_artifacts','passed':False,'error':str(error)}],
'observations_valid':False,'required_artifacts':sorted(BASE),'trial_outcomes':[]}
def inspect_case_artifacts(folder):
checks=[]
def check(name,value): checks.append({'check':name,'passed':bool(value)})
def flag(row,key,label):
value=float(row[key]);check(label+key+':boolean',value in (0,1));return value==1
required=set(BASE)
def get(name,needed=True):
path=folder/(P+name+'.txt')
if needed:
required.add(path.name);return vector(path)
check(name+':unavailable_file_absent',not path.exists());return None
summary_rows=rows(folder/(P+'summary.csv'))
summary={r['metric']:float(r['value']) for r in summary_rows}
check('unique_summary',len(summary)==len(summary_rows))
meta=dict(line.split('=',1) for line in (folder/'metadata.txt').read_text().splitlines() if '=' in line)
for key,metadata_key in {'outer_linear_tolerance':'linear_tol','seed_control':'coupled_seed_control',
'coupled_maximum_correction_ratio':'coupled_maximum_ratio','coupled_relative_tolerance':'coupled_tolerance',
'coupled_maximum_iterations':'coupled_iterations','coupled_restart':'coupled_restart',
'gravity_relative_tolerance':'gravity_tolerance','gravity_maximum_iterations':'gravity_iterations',
'gravity_restart':'gravity_restart','coupled_attempt_budget_per_independent_alpha':'coupled_attempts_per_iteration'}.items():
check('summary_metadata:'+key,summary[key]==float(meta[metadata_key]))
check('strategy_scope',meta['strategy'] in ('coupled','curvature-coupled') and
summary['gravity_path']==int(meta['strategy']=='curvature-coupled'))
for key in ('outer_linear_tolerance','sufficient_decrease'):
check('valid_control:'+key,math.isfinite(summary[key]) and 0<summary[key]<1)
check('valid_coupled_relative_tolerance',math.isfinite(summary['coupled_relative_tolerance']) and summary['coupled_relative_tolerance']>0)
check('valid_gravity_relative_tolerance',math.isfinite(summary['gravity_relative_tolerance']) and summary['gravity_relative_tolerance']>=0)
for key in ('coupled_maximum_iterations','coupled_restart','gravity_maximum_iterations','gravity_restart'):
check('valid_control:'+key,math.isfinite(summary[key]) and summary[key]>0 and summary[key]==int(summary[key]))
check('valid_correction_cap',math.isfinite(summary['coupled_maximum_correction_ratio']) and summary['coupled_maximum_correction_ratio']>0)
check('fixed_driver_controls',summary['sufficient_decrease']==1.e-4 and
summary['coupled_absolute_tolerance']==1.e-14 and summary['gravity_absolute_tolerance']==1.e-14)
for name,value in {'schema_version':1,'independent_frozen_alphas':1,'accepted_commits':0,
'polynomial_direction_repairs':0,'sampled_enthalpy_policy':1,'coupled_attempt_budget_per_independent_alpha':1,
'probe_exception':0,'accepted_buffers_bitwise_identical':1,'normalization_factors_bitwise_identical':1,
'direction_buffers_bitwise_identical':1,'direction_buffers_unchanged_before_restoration':1,
'fresh_operator_and_inverse_current':1}.items():check(name,summary[name]==value)
for i,name in enumerate(STATUS):check('status_mapping:'+name,summary['soc_status_'+name]==i)
x,physical,f,p,j,sf,rf=[get(n) for n in ('base_normalized','base_physical','base_residual','direction','base_action','state_factors','residual_factors')]
size=len(x)
check('square_vector_dimensions',all(len(v)==size for v in (physical,f,p,j,sf,rf)))
check('positive_normalization',all(v>0 for v in sf+rf))
check('base_physical_normalization',near_vector(x,[v*a for v,a in zip(physical,sf)],norm(x)))
layout=rows(folder/(P+'layout.csv'));vl=layout_for(layout,'value',size);rl=layout_for(layout,'residual',size)
gi=[i for name,(start,n) in vl.items() if name in GRAVITY_VALUES for i in range(start,start+n)]
gravity_value_indices=set(gi)
gr=[i for name,(start,n) in rl.items() if name in GRAVITY_ROWS for i in range(start,start+n)]
f0,pn,jn=norm(f),norm(p),norm(j)
check('finite_positive_base_residual',math.isfinite(f0) and f0>0)
check('finite_direction_norm',math.isfinite(pn))
defect=[a+b for a,b in zip(f,j)];dn=norm(defect)
check('base_defect_vector',near_vector(get('base_defect'),defect,f0+jn))
outer_threshold=summary['outer_linear_tolerance']*f0;outer_gate=dn<=outer_threshold
for key,value in {'base_residual_norm':f0,'base_merit':.5*f0*f0,'direction_norm':pn,
'base_merit_slope':dot(f,j),'outer_verified_defect_norm':dn,'outer_verified_relative_defect':dn/f0,
'outer_verified_threshold':outer_threshold}.items():check(key,close(summary[key],value,f0+jn))
check('outer_gate',summary['outer_verified_gate']==int(outer_gate))
check('outer_failed_gate_skips_trials',summary['outer_gate_failure_skips_trials']==int(not outer_gate))
check('restored_residual_vector',near_vector(get('restored_residual'),f,f0))
check('restored_action_vector',near_vector(get('restored_action'),j,jn))
restored_f=norm(minus(get('restored_residual'),f));restored_j=norm(minus(get('restored_action'),j))
check('restoration_envelope',math.isfinite(summary['maximum_base_restoration_error']) and
restored_f<=summary['maximum_base_restoration_error']+1024*EPS*f0 and summary['maximum_base_restoration_error']<=1.e-10*f0)
check('restored_action_error',close(summary['restored_base_action_error'],restored_j,jn) and restored_j<=1.e-10*max(jn,1.e-28))
for name in ('gravity_path','seed_control'):flag(summary,name,'summary:')
expected_alphas=[1.] if summary['seed_control']==1 else [1/16,1/64,1/256,1/1024]
for i,a in enumerate(expected_alphas):check('alpha_'+str(i),summary['alpha_'+str(i)]==a)
trial_rows=rows(folder/(P+'trials.csv'));block_rows=rows(folder/(P+'blocks.csv'))
check('complete_trial_grid',[int(r['sample']) for r in trial_rows]==(list(range(len(expected_alphas))) if outer_gate else []))
block_map={(int(r['sample']),r['stage'],r['block']):r for r in block_rows}
check('unique_block_rows',len(block_map)==len(block_rows));seen_blocks=set()
partitions={'all':(0,size),**rl}
outcomes=[]
totals={'attempts':0,'kept':0,'fallbacks':0,'iterations':0,'preparations':0,'restorations':0,
'solve_seconds':0.,'verification_seconds':0.,'preparation_seconds':0.,'refresh_seconds':0.}
def block_check(sample,a,stage,residual):
for name,(start,n) in partitions.items():
key=(sample,stage,name);seen_blocks.add(key);r=block_map[key]
check(f'{sample}:{stage}:{name}:layout',int(r['offset'])==start and int(r['size'])==n and float(r['alpha'])==a)
check(f'{sample}:{stage}:{name}:norm',close(float(r['residual_norm']),norm(residual[start:start+n]),norm(residual)))
for row in trial_rows:
i=int(row['sample']);a=float(row['alpha']);label=str(i)+':'
check(label+'alpha',a==expected_alphas[i]);suffix='_a'+str(i)
flags={k:flag(row,k,label) for k in ('gravity_path','raw_prepared','gravity_attempted','gravity_reported_gate',
'gravity_prepared_gate','before_prepared','before_usable','before_accepted','soc_called','soc_attempted',
'aux_reported_gate','aux_verified_gate','aux_verification_applied','corrected_metric_observed',
'corrected_accepted','selected_prepared','selected_accepted','selected_is_original','rhs_saved',
'correction_saved','verified_vectors_saved')}
check(label+'gravity_policy',int(flags['gravity_path'])==summary['gravity_path'])
prediction=[v+a*w for v,w in zip(f,j)];raw_state=get('raw_state'+suffix)
check(label+'linear_prediction',near_vector(get('prediction'+suffix),prediction,f0+a*jn))
check(label+'raw_displacement',near_vector(raw_state,[v+a*w for v,w in zip(x,p)],norm(x)+a*pn))
vectors={}
for stage,available,normkey,meritkey in (
('raw',flags['raw_prepared'],'raw_norm','raw_merit'),
('before',flags['before_prepared'],'before_norm','before_merit'),
('corrected',flags['corrected_metric_observed'],'corrected_norm','corrected_merit'),
('selected',flags['selected_prepared'],'selected_norm','selected_merit')):
residual=get(stage+'_residual'+suffix,available)
state=raw_state if stage=='raw' else get(stage+'_state'+suffix,available)
if available:
check(label+stage+':dimensions',len(residual)==len(state)==size)
rn=norm(residual);check(label+stage+':norm',close(float(row[normkey]),rn,rn))
check(label+stage+':merit',close(float(row[meritkey]),.5*rn*rn,rn*rn))
vectors[stage]=(state,residual);block_check(i,a,stage,residual)
if stage in ('corrected','selected'):
pv=get(stage+'_physical'+suffix)
check(label+stage+':physical',near_vector(state,[v*b for v,b in zip(pv,sf)],norm(state)))
else:
check(label+stage+':unavailable_metrics',math.isnan(float(row[normkey])) and math.isnan(float(row[meritkey])))
if stage in ('corrected','selected'):get(stage+'_physical'+suffix,False)
check(label+'raw_rejection', (int(row['raw_rejection_reason'])==-1 and int(row['raw_rejection_stage'])==-1)
if flags['raw_prepared'] else (int(row['raw_rejection_reason'])>=0 and int(row['raw_rejection_stage'])>=0))
check(label+'gravity_attempt',flags['gravity_attempted']==(flags['gravity_path'] and flags['raw_prepared']))
if not flags['gravity_path']:
check(label+'vacuous_gravity_gates',flags['gravity_reported_gate'] and flags['gravity_prepared_gate'])
check(label+'raw_baseline_preparation',flags['before_prepared']==flags['raw_prepared'])
get('gravity_correction'+suffix,False)
if flags['before_prepared']:
check(label+'raw_baseline_state',vectors['before'][0]==raw_state)
check(label+'raw_baseline_residual',vectors['before'][1]==vectors['raw'][1])
else:
save_gravity=flags['gravity_attempted'] and flags['gravity_reported_gate']
gc=get('gravity_correction'+suffix,save_gravity)
if save_gravity:
check(label+'gravity_partition_present',bool(gi) and bool(gr))
check(label+'gravity_only_correction',len(gc)==size and all(v==0 for k,v in enumerate(gc) if k not in gravity_value_indices))
if flags['before_prepared']:
check(label+'gravity_displacement',near_vector(vectors['before'][0],[v+w for v,w in zip(raw_state,gc)],norm(raw_state)+norm(gc)))
target=norm([vectors['before'][1][k]-prediction[k] for k in gr])
check(label+'gravity_affine_target',close(float(row['gravity_target_defect']),target,f0+a*jn))
if flags['gravity_prepared_gate']:
threshold=float(row['gravity_target_threshold']);disagreement=float(row['gravity_affine_disagreement'])
check(label+'gravity_prepared_necessary_gate',math.isfinite(threshold) and threshold>=0 and target<=threshold+512*EPS*f0 and
math.isfinite(disagreement) and 0<=disagreement<=threshold)
usable=flags['before_prepared'] and flags['gravity_reported_gate'] and flags['gravity_prepared_gate']
check(label+'before_usable',flags['before_usable']==usable)
armijo=(1-summary['sufficient_decrease']*a)*.5*f0*f0
before_accept=usable and float(row['before_merit'])<=armijo
check(label+'before_armijo',flags['before_accepted']==before_accept)
check(label+'soc_called',flags['soc_called']==usable)
attempted=usable and not before_accept
check(label+'one_independent_attempt',flags['soc_attempted']==attempted)
status=int(row['soc_status']);check(label+'known_status',0<=status<len(STATUS))
name=STATUS[status]
rhs=get('soc_rhs'+suffix,flags['rhs_saved']);correction=get('soc_correction'+suffix,flags['correction_saved'])
action=get('soc_action'+suffix,flags['verified_vectors_saved']);saved_defect=get('soc_defect'+suffix,flags['verified_vectors_saved'])
check(label+'saved_data_requires_attempt',attempted or not any(flags[k] for k in ('rhs_saved','correction_saved','verified_vectors_saved')))
# Save flags cannot hide a finite verification that reported failure.
# Nonfinite actions may legitimately have no finite vector artifact.
finite_verification=flags['aux_verification_applied'] and math.isfinite(float(row['aux_verified_true_norm']))
check(label+'verification_save_contract',
(not flags['verified_vectors_saved'] or (flags['aux_verification_applied'] and flags['rhs_saved'] and flags['correction_saved'])) and
(not finite_verification or flags['verified_vectors_saved']))
if attempted:
totals['attempts']+=1;totals['kept']+=name=='kept';totals['fallbacks']+=name!='kept'
check(label+'aux_status_gate',flags['aux_reported_gate']==(int(row['aux_status'])==0))
check(label+'bounded_iterations',0<=int(row['aux_iterations'])<=summary['coupled_maximum_iterations'])
cap=summary['coupled_maximum_correction_ratio']*a*pn
check(label+'correction_cap',close(float(row['correction_cap']),cap,cap))
if rhs is not None:
wanted=[u-v for u,v in zip(prediction,vectors['before'][1])]
check(label+'aux_rhs',near_vector(rhs,wanted,norm(prediction)+norm(vectors['before'][1])))
rhs_norm=norm(rhs)
if math.isfinite(rhs_norm):
threshold=max(summary['coupled_absolute_tolerance'],summary['coupled_relative_tolerance']*rhs_norm)
check(label+'aux_rhs_norm',close(float(row['aux_rhs_norm']),rhs_norm,rhs_norm))
check(label+'aux_threshold',close(float(row['aux_threshold']),threshold,threshold))
if flags['verified_vectors_saved']:
delta=minus(action,rhs);error=norm(delta)
check(label+'verified_defect_vector',near_vector(saved_defect,delta,norm(action)+norm(rhs)))
check(label+'verified_defect_norm',close(float(row['aux_verified_true_norm']),error,norm(rhs)))
check(label+'saved_defect_norm',close(float(row['verified_action_defect_norm']),error,norm(rhs)))
check(label+'independent_aux_gate',flags['aux_verified_gate']==(error<=float(row['aux_threshold'])))
cn=norm(correction)
check(label+'correction_norm',close(float(row['correction_norm']),cn,cn))
check(label+'correction_ratio',close(float(row['correction_ratio']),cn/(a*pn),cn/(a*pn)))
expected_core=1 if not flags['aux_reported_gate'] or not flags['aux_verified_gate'] else (2 if cn>cap else 0)
check(label+'core_decision',int(row['aux_core_status'])==expected_core)
core=int(row['aux_core_status'])
if core in (0,1,2):
check(label+'finite_core_complete_evidence',flags['rhs_saved'] and flags['correction_saved'] and
flags['aux_verification_applied'] and flags['verified_vectors_saved'])
if core!=0:
check(label+'failed_core_falls_back',name=={1:'linear_failure',2:'norm_limit',3:'non_finite'}.get(core))
check(label+'failed_core_no_preparation',int(row['soc_preparations'])==0 and int(row['soc_restorations'])==0 and not flags['corrected_metric_observed'])
else:
check(label+'admissible_core_requires_gates',flags['aux_reported_gate'] and flags['aux_verified_gate'] and
flags['verified_vectors_saved'] and float(row['correction_norm'])<=cap)
if flags['corrected_metric_observed']:
check(label+'corrected_requires_admissible_core',core==0)
check(label+'corrected_displacement',near_vector(vectors['corrected'][0],
[v+w for v,w in zip(vectors['before'][0],correction)],norm(vectors['before'][0])+norm(correction)))
better=float(row['corrected_merit'])<float(row['before_merit'])
check(label+'full_merit_selection',name==('kept' if better else 'not_improved'))
if name=='kept':
check(label+'kept_observed',flags['corrected_metric_observed'])
check(label+'kept_preparations',int(row['soc_preparations'])==1 and int(row['soc_restorations'])==0)
elif core==0:
check(label+'mutated_fallback_restored',int(row['soc_restorations'])==1 and int(row['soc_preparations']) in (1,2))
else:
check(label+'no_attempt_status',name==('original_accepted' if before_accept else 'not_attempted'))
check(label+'no_aux_certificate',int(row['aux_status'])==-1 and int(row['aux_core_status'])==-1 and
not flags['aux_reported_gate'] and not flags['aux_verified_gate'] and not flags['aux_verification_applied'])
check(label+'no_aux_work',int(row['aux_iterations'])==0 and int(row['soc_preparations'])==0 and int(row['soc_restorations'])==0)
check(label+'no_corrected_candidate',not flags['corrected_metric_observed'])
check(label+'selected_prepared',flags['selected_prepared']==flags['before_prepared'])
if flags['selected_prepared']:
expected=vectors['corrected'] if name=='kept' else vectors['before']
check(label+'selected_state',vectors['selected'][0]==expected[0])
check(label+'selected_residual',near_vector(vectors['selected'][1],expected[1],norm(expected[1])))
same=vectors['selected'][0]==vectors['before'][0]
check(label+'selected_original_identity',flags['selected_is_original']==same)
if same:
difference=norm(minus(vectors['selected'][1],vectors['before'][1]))
check(label+'fallback_difference',close(float(row['fallback_residual_difference']),difference,norm(expected[1])))
check(label+'fallback_residual_preserved',difference<=1024*EPS*max(norm(expected[1]),1.e-28))
else:check(label+'no_original_identity',not flags['selected_is_original'])
check(label+'corrected_armijo',flags['corrected_accepted']==(flags['corrected_metric_observed'] and float(row['corrected_merit'])<=armijo))
check(label+'selected_armijo',flags['selected_accepted']==(usable and flags['selected_prepared'] and float(row['selected_merit'])<=armijo))
for key in ('raw_seconds','gravity_seconds','soc_seconds','soc_refresh_seconds','soc_solve_seconds','soc_verification_seconds',
'soc_preparation_seconds','capture_seconds','total_sample_seconds'):
check(label+key,math.isfinite(float(row[key])) and float(row[key])>=0)
parts=sum(float(row['soc_'+k]) for k in ('refresh_seconds','solve_seconds','verification_seconds','preparation_seconds'))
check(label+'soc_time_scope',float(row['soc_seconds'])+1.e-6>=parts)
check(label+'sample_time_scope',float(row['total_sample_seconds'])+1.e-6>=sum(float(row[k]) for k in ('raw_seconds','gravity_seconds','soc_seconds','capture_seconds')))
for key in ('preparations','restorations','solve_seconds','verification_seconds','preparation_seconds','refresh_seconds'):
totals[key]+=float(row['soc_'+key])
totals['iterations']+=int(row['aux_iterations'])
outcomes.append({'sample':i,'alpha':a,'transaction_status':name,'before_usable':usable,'before_armijo':before_accept,
'correction_attempted':attempted,'aux_verified_gate':flags['aux_verified_gate'],'corrected_metric_observed':flags['corrected_metric_observed'],
'selected_armijo':flags['selected_accepted'],'before_residual_norm':float(row['before_norm']),
'selected_residual_norm':float(row['selected_norm']),'full_merit_improved':name=='kept',
'correction_norm':float(row['correction_norm']),'correction_cap':float(row['correction_cap']),
'auxiliary_iterations':int(row['aux_iterations']),'auxiliary_verified_defect_norm':float(row['aux_verified_true_norm']),
'corrected_affine_target_defect_norm':norm(minus(vectors['corrected'][1],prediction)) if flags['corrected_metric_observed'] else None,
'correction_mechanism':correction_mechanism(x,p,a,prediction,vectors['before'][1],vectors['corrected'][0],
vectors['corrected'][1],correction,rhs,action) if attempted and flags['corrected_metric_observed'] and
correction is not None and rhs is not None and action is not None else None,
'auxiliary_seconds':{k:float(row['soc_'+k]) for k in ('refresh_seconds','solve_seconds','verification_seconds','preparation_seconds')},
'residual_norms_by_block':{stage:{block:norm(value[1][start:start+n]) for block,(start,n) in rl.items()}
for stage,value in vectors.items()}})
check('complete_block_coverage',seen_blocks==set(block_map))
if outer_gate:
for key,value in totals.items():check('soc_total:'+key,close(summary['soc_'+key],value,value))
preparations=rows(folder/(P+'preparations.csv'))
check('preparation_sequence',[int(r['sequence']) for r in preparations]==list(range(1,len(preparations)+1)))
check('explicit_preparation_count',summary['explicit_probe_preparations']==len(preparations))
for r in preparations:
check('preparation_time:'+r['sequence'],math.isfinite(float(r['seconds'])) and float(r['seconds'])>=0)
if r['kind']!='raw':check('base_restoration_prepares:'+r['sequence'],r['prepared']=='1' and close(float(r['residual_norm']),f0,f0))
raw_preparations=[r for r in preparations if r['kind']=='raw']
check('raw_preparation_coverage',[int(r['sample']) for r in raw_preparations]==[int(r['sample']) for r in trial_rows])
for prep,trial in zip(raw_preparations,trial_rows):
label=prep['sample']+':raw_preparation:'
for key in ('prepared','rejection_reason','rejection_stage'):
check(label+key,prep[key]==trial['raw_'+key])
check(label+'alpha',float(prep['alpha'])==float(trial['alpha']))
measured=float(prep['residual_norm']);reported=float(trial['raw_norm'])
check(label+'residual',close(measured,reported) if prep['prepared']=='1' else math.isnan(measured) and math.isnan(reported))
check(label+'time_scope',float(prep['seconds'])<=float(trial['raw_seconds'])+1.e-6)
check('preparation_time_total',close(summary['explicit_probe_preparation_seconds'],sum(float(r['seconds']) for r in preparations)))
check('final_restoration_present',bool(preparations) and preparations[-1]['kind']=='final_base_restore')
check('total_time',math.isfinite(summary['total_seconds']) and summary['total_seconds']>=0)
physical_observations=inspect_physical(folder,trial_rows,meta,check)
check('no_unexplained_vector_artifacts',{p.name for p in folder.glob(P+'*.txt')}==
{name for name in required if name.startswith(P) and name.endswith('.txt')})
passed=all(r['passed'] for r in checks)
return sanitize({'passed':passed,'checks':checks,'observations_valid':passed,'metadata':meta,'summary':summary,
'required_artifacts':sorted(required),'outer_linear_gate':outer_gate,'trial_outcomes':outcomes if passed else [],
'physical_observations':physical_observations if passed else [],
'scope':'Independent saved-vector arithmetic and transaction/provenance audit. Frozen alpha samples are not a nonlinear trajectory. Physical replay metrics are checked for internal consistency and reported separately; no independent FEM quadrature is performed.',
'gravity_scope':'Saved vectors independently check the affine gravity target defect. This schema does not independently reconstruct the gravity inner solve or its contribution-based arithmetic allowance.',
'operator_scope':'Saved SOC J actions verify the reported algebraic defect; this checker does not perform another FEM action.'})
def inspect_physical(folder,trials,metadata,check):
"""Check replay binding and scalar identities without certifying the star."""
records=rows(folder/(P+'physical.csv'))
measured={(int(r['sample']),r['source'],int(r['quadrature']),r['metric']):float(r['value']) for r in records}
check('physical:unique_measurements',len(measured)==len(records))
used=set()
def get(sample,source,q,key):
index=(sample,source,q,key);used.add(index);return measured[index]
for key in ('accepted_buffers_unchanged_before_restoration','accepted_buffers_unchanged_after_restoration',
'normalization_factors_unchanged','direction_buffers_unchanged','accepted_operator_and_inverse_current'):
check('physical:'+key,get(-1,'restoration',0,key)==1)
selected=[r for r in trials if r['selected_prepared']=='1']
check('physical:snapshot_count',get(-1,'replay',0,'selected_snapshots_measured')==len(selected))
check('physical:sample_coverage',{k[0] for k in measured if k[0]>=0}=={int(r['sample']) for r in selected})
observations=[]
for trial in selected:
sample=int(trial['sample']);source=P+'selected_physical_a'+str(sample)+'.txt'
saved=vector(folder/source);label='physical:'+str(sample)+':'
check(label+'fresh_preparation',get(sample,source,0,'fresh_preparation_passed')==1)
for q in (14,18):
prefix=label+str(q)+':'
m={key[3]:value for key,value in measured.items() if key[:3]==(sample,source,q)}
used.update(key for key in measured if key[:3]==(sample,source,q))
check(prefix+'quadrature',m['quadrature_order']==q)
check(prefix+'physics',m['polytropic_index']==float(metadata['n']) and
m['polytropic_constant']==float(metadata['K']) and m['target_mass']==float(metadata['M']))
for key in ('stellar_samples','valid_stellar_samples','invalid_stellar_samples','negative_density_samples',
'negative_enthalpy_samples','invalid_density_eos_samples','invalid_enthalpy_eos_samples'):
check(prefix+key,math.isfinite(m[key]) and m[key]>=0 and m[key]==int(m[key]))
check(prefix+'sample_accounting',m['valid_stellar_samples']+m['invalid_stellar_samples']==m['stellar_samples'])
complete=m['invalid_stellar_samples']==0 and m['valid_stellar_samples']>0 and math.isfinite(m['volume']) and m['volume']>0
check(prefix+'complete_measurement',m['complete_volume_measurement']==int(complete))
hp=complete and m['invalid_enthalpy_eos_samples']==0
rp=complete and m['negative_density_samples']==0 and m['invalid_density_eos_samples']==0
check(prefix+'enthalpy_pressure_definition',m['pressure_from_enthalpy_defined_everywhere']==int(hp))
check(prefix+'density_pressure_definition',m['pressure_from_density_defined_everywhere']==int(rp))
check(prefix+'snapshot_roundtrip',0<=m['saved_prepared_l2_difference']<=1024*EPS*(1+norm(saved)) and
0<=m['saved_prepared_maximum_difference']<=m['saved_prepared_l2_difference']+1024*EPS and
0<=m['saved_prepared_maximum_scaled_difference']<=1024*EPS)
selected_norm=float(trial['selected_norm'])
# Repreparing a denormalized snapshot introduces roundoff. This
# tolerance checks replay identity, not physical residual accuracy.
check(prefix+'selected_residual_binding',math.isfinite(m['normalized_bordered_residual']) and
abs(m['normalized_bordered_residual']-selected_norm)<=1024*EPS*(1+selected_norm))
check(prefix+'central_border_finite',math.isfinite(m['central_border']) and math.isfinite(m['normalized_border_action']))
if metadata['central_phase']=='0':
check(prefix+'unbordered_model',m['central_border']==0 and m['normalized_border_action']==0 and
close(m['normalized_unbordered_residual'],m['normalized_bordered_residual'],selected_norm))
if complete:
check(prefix+'mass_error',close(m['mass_absolute_error'],abs(m['mass']-m['target_mass']),abs(m['mass'])+m['target_mass']))
check(prefix+'sampled_signs',
(m['minimum_density']<0)==(m['negative_density_samples']>0) and
(m['minimum_enthalpy']<0)==(m['negative_enthalpy_samples']>0))
w=m['binding_energy'];wf=m['force_binding_energy'];t=m['kinetic_energy']
virials={}
for prefix_pressure,defined,pressure_key in (('',rp,'pressure_integral'),('enthalpy_',hp,'enthalpy_pressure_integral')):
pressure=m[pressure_key]
check(prefix+pressure_key+':definition',math.isfinite(pressure) if defined else math.isnan(pressure))
for force,binding in (('',w),('force_',wf)):
key=prefix_pressure+force+'virial_';signed=m[key+'signed'];error=m[key+'error']
valid=defined and math.isfinite(w) and w<0
if valid:
expected=(2*t+binding+3*pressure)/abs(w)
scale=(2*abs(t)+abs(binding)+3*abs(pressure))/abs(w)
check(prefix+key+'identity',close(signed,expected,scale) and close(error,abs(signed),scale))
else:check(prefix+key+'undefined',math.isnan(signed) and math.isnan(error))
virials[key+'within_1e5']=(error<=1.e-5) if valid and math.isfinite(error) else None
observations.append({'sample':sample,'quadrature':q,'selected_armijo':trial['selected_accepted']=='1',
'complete_volume_measurement':complete,'pressure_from_density_defined':rp,'pressure_from_enthalpy_defined':hp,
'negative_density_samples':m['negative_density_samples'],'minimum_density':m['minimum_density'],
'negative_enthalpy_samples':m['negative_enthalpy_samples'],'minimum_enthalpy':m['minimum_enthalpy'],
'global_enthalpy_certificate':'not_measured','virial_status':virials,'reported_metrics':m})
check('physical:source_and_quadrature_coverage',used==set(measured))
return observations
def suppress_observations(results):
for result in results.values():
result.update(passed=False,observations_valid=False,trial_outcomes=[],physical_observations=[])
def inspect_campaign(campaign):
campaign=Path(campaign).resolve();checks=[];results={}
def check(name,value):checks.append({'check':name,'passed':bool(value)})
try:
provenance=json.loads((campaign/'provenance.json').read_text());cases=provenance['cases']
check('executable_hash',digest(campaign/'plateau_diagnostic')==provenance['binary_sha256'])
check('mesh_hash',digest(Path(provenance['mesh']))==provenance['mesh_sha256'])
check('unique_cases',bool(cases) and len(cases)==len({c['id'] for c in cases}))
check('manifest_snapshot',json.loads((campaign/'cases.json').read_text())==cases)
for case in cases:
name=case['id'];folder=campaign/name;args=case['arguments'];record=json.loads((campaign/(name+'_run.json')).read_text())
check(name+':completed',bool(record.get('finished_utc')) and record.get('exit_code')==0 and not record.get('timed_out',False))
check(name+':command',record.get('id')==name and record.get('command')==[str(campaign/'plateau_diagnostic'),*args,'--mesh',provenance['mesh'],'--output',str(folder)])
expected={}
for option,saved in (('--probe-state','base_physical'),('--probe-direction','direction')):
if option not in args:raise ValueError('A frozen coupled trial must bind '+option)
path=Path(args[args.index(option)+1]);path=path if path.is_absolute() else Path(provenance['source'])/path
expected[str(path.resolve())]=saved
check(name+':required_input_hashes',expected.keys()<=record.get('input_state_hashes',{}).keys())
for path,value in record.get('input_state_hashes',{}).items():check(name+':input:'+path,digest(Path(path))==value)
for filename,value in record.get('output_hashes',{}).items():check(name+':output:'+filename,digest(folder/filename)==value)
for path,saved in expected.items():
source=vector(Path(path));target=vector(folder/(P+saved+'.txt'))
check(name+':input_binding:'+saved,source==target if saved=='direction' else near_vector(source,target,norm(source)))
result=inspect_case(folder);results[name]=result;meta=result.get('metadata',{})
check(name+':required_output_hashes',set(result['required_artifacts'])<=record.get('output_hashes',{}).keys())
check(name+':expert_probe','--coupled-trial-probe' in args and meta.get('coupled_trial_probe')=='1')
bindings={'--index':'n','--angular-momentum':'J','--linear-tol':'linear_tol','--coupled-tol':'coupled_tolerance',
'--coupled-iterations':'coupled_iterations','--coupled-restart':'coupled_restart','--coupled-max-ratio':'coupled_maximum_ratio',
'--coupled-attempts':'coupled_attempts_per_iteration','--gravity-tol':'gravity_tolerance',
'--gravity-iterations':'gravity_iterations','--gravity-restart':'gravity_restart'}
for option,key in bindings.items():
if option in args:check(name+':requested_'+key,key in meta and float(meta[key])==float(args[args.index(option)+1]))
if '--strategy' in args:check(name+':strategy',meta.get('strategy')==args[args.index('--strategy')+1])
if '--no-central' in args:check(name+':no_central',meta.get('central_phase')=='0')
check(name+':independent_alpha_metadata',meta.get('coupled_trial_alphas_are_independent')=='1')
check(name+':sampled_enthalpy_scope',meta.get('coupled_trial_admissibility')=='sampled_enthalpy_without_repair')
check(name+':seed_control',meta.get('coupled_seed_control')==str(int('--coupled-seed-control' in args)))
passed=all(c['passed'] for c in checks) and all(r['passed'] for r in results.values())
if not all(c['passed'] for c in checks):
suppress_observations(results)
return {'passed':passed,'source_commit':provenance['commit'],'checker_sha256':digest(Path(__file__)),
'checker_utility_sha256':digest(Path(__file__).with_name('check_nonlinear_step.py')),
'provenance_sha256':digest(campaign/'provenance.json'),'provenance_checks':checks,'cases':results,
'scope':'Artifact validity and numerical/physical success are separate conclusions.'}
except (OSError,ValueError,KeyError,TypeError,IndexError) as error:
suppress_observations(results)
return {'passed':False,'provenance_checks':checks+[{'check':'complete_readable_campaign','passed':False,'error':str(error)}],'cases':results}
def main():
parser=argparse.ArgumentParser(description=__doc__)
parser.add_argument('campaign',type=Path);parser.add_argument('--output',type=Path,required=True)
args=parser.parse_args()
if args.output.resolve()==args.campaign.resolve() or args.campaign.resolve() in args.output.resolve().parents:
parser.error('Write the review outside the immutable campaign.')
result=inspect_campaign(args.campaign);args.output.write_text(json.dumps(result,indent=2,allow_nan=False)+'\n')
print('PASS' if result['passed'] else 'FAIL',args.output)
for name,case in result['cases'].items():print(name,'artifacts=',case['passed'],'outer_linear=',case.get('outer_linear_gate'))
return 0 if result['passed'] else 1
if __name__=='__main__':raise SystemExit(main())

View File

@@ -0,0 +1,382 @@
#!/usr/bin/env python3
"""Audit the paired six-step live experiment without loading state vectors.
Hashes bind the producer's observations. Scalar identities check those recorded
observations; they do not supply a fresh FEM action, a pointwise certificate, or
an unavailable corrected displacement. Nonconvergence and physical defects are
reported separately from artifact/decision consistency.
"""
import argparse
import csv
import datetime
import hashlib
import json
import math
from pathlib import Path
import sys
EPS = sys.float_info.epsilon
ARMIJO = 1.e-4 # The live driver's default; this is not a configurable CLI flag.
COUNTERS = ('attempts', 'kept', 'fallbacks', 'iterations', 'preparations', 'restorations',
'solve_seconds', 'verification_seconds', 'preparation_seconds', 'refresh_seconds')
REQUIRED = {'metadata.txt', 'layout.csv', 'initial_physical.csv', 'final_physical.csv',
'newton.csv', 'blocks.csv', 'trials.csv', 'coupled_trials.csv', 'coupled_search.csv',
'coupled_candidates.csv', 'trial_state_consistency.csv', 'numerical_strategies.csv',
'accepted_state.txt'}
def digest(path):
result = hashlib.sha256()
with path.open('rb') as stream:
for chunk in iter(lambda: stream.read(1024 * 1024), b''):
result.update(chunk)
return result.hexdigest()
def rows(path):
with path.open() as stream:
result = list(csv.DictReader(stream))
if any(None in row or any(value is None for value in row.values()) for row in result):
raise ValueError(f'Incomplete CSV row: {path}')
return result
def close(a, b, scale=0.):
return math.isfinite(a) and math.isfinite(b) and abs(a-b) <= 1.e-10*max(abs(a), abs(b)) + 256*EPS*abs(scale)
def safe(value):
if isinstance(value, float) and not math.isfinite(value):
return None
if isinstance(value, dict):
return {key: safe(item) for key, item in value.items()}
if isinstance(value, (list, tuple)):
return [safe(item) for item in value]
return value
def key(row):
return int(row['iteration']), int(row['trial'])
def indexed(records):
result = {key(row): row for row in records}
if len(result) != len(records):
raise ValueError('Duplicate iteration/trial observations')
return result
def physical(path, metadata, check):
data = rows(path)
values = {(int(row['quadrature']), row['metric']): float(row['value']) for row in data}
check(path.name+':unique_metrics', len(values) == len(data))
check(path.name+':quadratures', {q for q, _ in values} == {14, 18})
result = {}
for q in (14, 18):
m = {metric: value for (order, metric), value in values.items() if order == q}
label = f'{path.name}:{q}:'
check(label+'model', m['polytropic_index'] == float(metadata['n']) and m['polytropic_constant'] == float(metadata['K']))
complete = m['complete_volume_measurement'] == 1
if complete:
check(label+'mass_error', close(m['mass_absolute_error'], abs(m['mass']-float(metadata['M'])), abs(m['mass'])))
check(label+'angular_momentum_error', close(m['angular_momentum_absolute_error'], abs(m['angular_momentum_z']-float(metadata['J'])), 1.))
virials = {}
for pressure_prefix, defined_key, pressure_key in (
('', 'pressure_from_density_defined_everywhere', 'pressure_integral'),
('enthalpy_', 'pressure_from_enthalpy_defined_everywhere', 'enthalpy_pressure_integral')):
defined = m[defined_key] == 1 and complete and math.isfinite(m['binding_energy']) and m['binding_energy'] < 0
for force, binding_key in (('', 'binding_energy'), ('force_', 'force_binding_energy')):
name = pressure_prefix+force+'virial_'
signed, error = m[name+'signed'], m[name+'error']
if defined:
numerator = 2*m['kinetic_energy']+m[binding_key]+3*m[pressure_key]
scale = (2*abs(m['kinetic_energy'])+abs(m[binding_key])+3*abs(m[pressure_key]))/abs(m['binding_energy'])
check(label+name+'identity', close(signed, numerator/abs(m['binding_energy']), scale) and close(error, abs(signed), scale))
else:
check(label+name+'undefined', math.isnan(signed) and math.isnan(error))
virials[name+'within_1e5'] = error <= 1.e-5 if defined and math.isfinite(error) else None
result[str(q)] = {'metrics': m, 'virial_milestones': virials,
'pressure_from_density_defined': m['pressure_from_density_defined_everywhere'] == 1,
'sampled_negative_density': m['negative_density_samples'] > 0,
'sampled_negative_enthalpy': m['negative_enthalpy_samples'] > 0,
'global_enthalpy_certificate': 'not_measured'}
return result
def inspect_case(folder, record, check):
metadata = dict(line.split('=', 1) for line in (folder/'metadata.txt').read_text().splitlines() if '=' in line)
history, trials = rows(folder/'newton.csv'), rows(folder/'trials.csv')
coupled, searches = indexed(rows(folder/'coupled_trials.csv')), indexed(rows(folder/'coupled_search.csv'))
consistency = indexed(rows(folder/'trial_state_consistency.csv'))
trial_map = indexed(trials)
check('trial_joins', set(trial_map) == set(coupled) == set(searches) == set(consistency))
candidates = {}
for row in rows(folder/'coupled_candidates.csv'):
candidates.setdefault(key(row), []).append(row)
check('candidate_trial_coverage', set(candidates) <= set(trial_map))
strategy_rows = rows(folder/'numerical_strategies.csv')
strategy = {row['metric']: float(row['value']) for row in strategy_rows}
check('unique_strategy_summary', len(strategy) == len(strategy_rows))
initial = physical(folder/'initial_physical.csv', metadata, check)
endpoint = physical(folder/'final_physical.csv', metadata, check)
before = initial['18']['metrics']['normalized_bordered_residual']
initial_residual = before
check('six_step_control', metadata['max_newton'] == '6' and float(metadata['linear_tol']) == .03)
check('single_auxiliary_budget', metadata['coupled_attempts_per_iteration'] == '1')
check('outer_iteration_sequence', [int(row['iteration']) for row in history] == list(range(len(history))) and len(history) <= 6)
block_data = rows(folder/'blocks.csv')
residual_blocks = {row['block'] for row in rows(folder/'layout.csv') if row['kind'] == 'residual'}
blocks = {(int(row['iteration']), row['stage'], row['block']): float(row['normalized_norm']) for row in block_data}
check('unique_block_observations', len(blocks) == len(block_data))
expected_blocks = {(int(row['iteration']), stage, block) for row in history for stage in ('before', 'after') for block in residual_blocks}
check('block_coverage', set(blocks) == expected_blocks)
previous = dict.fromkeys(COUNTERS, 0.)
previous_deferred = 0.
accepted_count = 0
cumulative_seconds = 0.
cumulative_linear_iterations = 0
step_results = []
used_trials = set()
for row in history:
iteration = int(row['iteration'])
iteration_trials = [trial for trial in trials if int(trial['iteration']) == iteration]
check(f'{iteration}:trial_sequence', [int(trial['trial']) for trial in iteration_trials] == list(range(len(iteration_trials))))
check(f'{iteration}:trial_count', int(row['trials']) == len(iteration_trials))
for stage, value in (('before', before), ('after', float(row['F']))):
block_norm = math.hypot(*(blocks[(iteration, stage, block)] for block in residual_blocks))
check(f'{iteration}:{stage}:block_norm', close(block_norm, value))
check(f'{iteration}:linear_rhs_matches_base', close(float(row['linear_rhs_norm']), before))
outer_gate = math.isfinite(float(row['linear_true'])) and float(row['linear_true']) <= .03
step_accepted = row['accepted'] == '1'
check(f'{iteration}:accepted_boolean', row['accepted'] in ('0', '1'))
accepted_trials = [trial for trial in iteration_trials if trial['disposition'] == '0']
check(f'{iteration}:accepted_trial_count', len(accepted_trials) == int(step_accepted))
if step_accepted:
accepted_count += 1
check(f'{iteration}:accepted_linear_gate', row['linear_status'] == '0' and outer_gate)
check(f'{iteration}:strict_residual_decrease', 0 <= float(row['F']) < before)
check(f'{iteration}:accepted_trial_binding', accepted_trials[0] == iteration_trials[-1] and
close(float(accepted_trials[0]['F']), float(row['F'])) and accepted_trials[0]['alpha'] == row['alpha'])
else:
check(f'{iteration}:failed_state_unchanged', close(float(row['F']), before))
increments = dict.fromkeys(COUNTERS, 0.)
deferred_increment = 0.
observations = []
for trial in iteration_trials:
address = key(trial)
used_trials.add(address)
label = f'{iteration}:{address[1]}:'
c, search, roundtrip = coupled[address], searches[address], consistency[address]
alpha = float(trial['alpha'])
check(label+'alpha_binding', 0 < alpha <= 1 and float(c['alpha']) == alpha and float(search['alpha']) == alpha)
check(label+'diagnostics_available', c['diagnostics_available'] == '1' and c['status'] == search['status'])
check(label+'observer_roundtrip', math.isfinite(float(roundtrip['relative_error'])) and
0 <= float(roundtrip['relative_error']) <= 64*EPS and math.isfinite(float(roundtrip['normalized_physical_roundtrip_error'])) and
float(roundtrip['normalized_physical_roundtrip_error']) >= 0)
change = {}
for counter in COUNTERS:
current = float(c[counter+'_total'])
check(label+counter+':monotone', math.isfinite(current) and current >= previous[counter])
change[counter] = current-previous[counter]
increments[counter] += change[counter]
previous[counter] = current
deferred = float(search['deferred_total'])
check(label+'deferred_monotone', math.isfinite(deferred) and deferred >= previous_deferred)
deferred_change = deferred-previous_deferred
deferred_increment += deferred_change
previous_deferred = deferred
has_solve = c['has_solve'] == '1'
status = int(c['status'])
check(label+'known_status', 0 <= status <= 9 and c['has_solve'] in ('0', '1'))
check(label+'attempt_accounting', change['attempts'] == int(has_solve) and change['iterations'] == int(c['linear_iterations']))
check(label+'selection_accounting', change['kept'] == int(status == 3) and
change['fallbacks'] == int(has_solve and status != 3) and deferred_change == int(status == 9))
proposals = candidates.get(address, [])
check(label+'candidate_count', len(proposals) == int(search['candidate_count']) and len(proposals) <= int(metadata['coupled_beta_steps']))
check(label+'candidate_sequence', [int(item['candidate']) for item in proposals] == list(range(len(proposals))))
merit_limit = (1-ARMIJO*alpha)*.5*before*before
if trial['disposition'] == '0':
check(label+'ordinary_merit_acceptance', math.isfinite(float(trial['F'])) and .5*float(trial['F'])**2 <= merit_limit)
for index, proposal in enumerate(proposals):
beta, merit = float(proposal['beta']), float(proposal['merit'])
check(label+f'beta{index}:grid', close(beta, float(metadata['coupled_beta_reduction'])**index))
check(label+f'beta{index}:status', proposal['status'] in ('0', '1', '2') and proposal['accepted'] in ('0', '1'))
valid = proposal['status'] == '0'
check(label+f'beta{index}:metric', math.isfinite(merit) and merit >= 0 if valid else math.isnan(merit))
accepted = valid and merit < float(c['original_merit']) and merit <= merit_limit
check(label+f'beta{index}:ordinary_acceptance', (proposal['accepted'] == '1') == accepted)
if accepted:
check(label+'first_accepted_beta_stops_search', index == len(proposals)-1)
check(label+f'beta{index}:time', math.isfinite(float(proposal['preparation_seconds'])) and float(proposal['preparation_seconds']) >= 0)
if has_solve:
rhs, threshold, verified = float(c['rhs_norm']), float(c['threshold']), float(c['verified_true_norm'])
check(label+'auxiliary_work_bound', 0 <= int(c['linear_iterations']) <= int(metadata['coupled_iterations']))
if math.isfinite(rhs) and math.isfinite(threshold):
check(label+'auxiliary_threshold', close(threshold, max(1.e-14, float(metadata['coupled_tolerance'])*rhs)))
if math.isfinite(verified) and math.isfinite(threshold):
check(label+'auxiliary_true_gate', (c['verified_gate'] == '1') == (verified <= threshold))
if status == 3:
selected_beta = float(search['selected_beta'])
chosen = [item for item in proposals if float(item['beta']) == selected_beta]
check(label+'retained_auxiliary_certificate', has_solve and c['linear_status'] == '0' and c['verified_gate'] == '1' and
math.isfinite(float(c['verified_true_norm'])) and float(c['verified_true_norm']) <= float(c['threshold']) and
0 <= float(c['correction_norm']) <= float(c['maximum_correction_norm']))
check(label+'retained_beta_observed', len(chosen) == 1 and chosen[0]['status'] == '0')
if len(chosen) == 1:
check(label+'retained_metric_replay', close(float(chosen[0]['merit']), float(c['corrected_merit'])))
check(label+'retained_merit_improves', 0 <= float(c['corrected_merit']) < float(c['original_merit']))
check(label+'retained_residual_binding', close(.5*float(trial['F'])**2, float(c['corrected_merit'])))
else:
check(label+'no_stale_selection', math.isnan(float(search['selected_beta'])))
if not has_solve:
check(label+'no_stale_auxiliary_report', c['linear_status'] == '-1' and c['verified_gate'] == '0' and not proposals)
if status == 9 or has_solve:
if metadata['strategy'] == 'curvature-backtracked-coupled':
base_merit, predicted = float(search['base_merit']), float(search['predicted_merit'])
drop = float(search['predicted_decrease'])
check(label+'prediction_base_binding', close(base_merit, .5*before*before))
check(label+'predicted_decrease_identity', close(drop, base_merit-predicted, base_merit))
if drop > 0:
ratio = (float(c['original_merit'])-base_merit)/drop
check(label+'excess_ratio_identity', close(float(search['excess_ratio']), ratio, 1.))
check(label+'near_gate_decision', (ratio <= float(metadata['coupled_excess_ratio'])) == has_solve)
else:
check(label+'nonpositive_prediction_defers', status == 9 and not has_solve)
observations.append({'trial': address[1], 'alpha': alpha, 'disposition': int(trial['disposition']),
'rejection_source': trial['source'], 'F': float(trial['F']), 'coupled_status': status,
'selected_beta': float(search['selected_beta']), 'auxiliary_changes': change,
'deferrals': deferred_change, 'candidates': proposals})
check(f'{iteration}:auxiliary_attempt_budget', increments['attempts'] <= 1)
for field in ('seconds', 'linear_seconds', 'prepare_seconds', 'refresh_seconds'):
check(f'{iteration}:{field}', math.isfinite(float(row[field])) and float(row[field]) >= 0)
cumulative_seconds += float(row['seconds'])
cumulative_linear_iterations += int(row['linear_iterations'])
step_results.append({'iteration': iteration, 'accepted': step_accepted, 'F_before': before, 'F': float(row['F']),
'alpha': float(row['alpha']), 'outer_true_relative': float(row['linear_true']), 'outer_true_gate': outer_gate,
'outer_linear_iterations': int(row['linear_iterations']), 'iteration_seconds': float(row['seconds']),
'cumulative_iteration_seconds': cumulative_seconds, 'cumulative_outer_linear_iterations': cumulative_linear_iterations,
'linear_seconds': float(row['linear_seconds']), 'reported_trial_preparation_seconds': float(row['prepare_seconds']),
'outer_refresh_seconds': float(row['refresh_seconds']), 'auxiliary_changes': increments,
'auxiliary_deferrals': deferred_increment, 'trials': observations})
before = float(row['F'])
check('all_trials_accounted', used_trials == set(trial_map))
check('accepted_steps_metadata', accepted_count == int(metadata['accepted_steps']))
converged = metadata['converged'] == '1'
check('termination_record', metadata['converged'] in ('0', '1') and record['exit_code'] == (0 if converged else 3) and
(converged or bool(metadata.get('failure'))))
check('bounded_outcome', accepted_count == 6 or converged or bool(metadata.get('failure')))
for counter, total in previous.items():
check('final_auxiliary_'+counter, close(strategy['coupled_'+counter], total))
check('final_deferred_count', strategy['coupled_deferred_attempts'] == previous_deferred)
for q in ('14', '18'):
check('endpoint_residual_'+q, close(endpoint[q]['metrics']['normalized_bordered_residual'], before))
return {'metadata': metadata, 'converged': converged, 'failure': metadata.get('failure'), 'accepted_steps': accepted_count,
'initial_residual': initial_residual, 'final_residual': before, 'steps': step_results,
'summed_iteration_seconds': math.fsum(float(row['seconds']) for row in history),
'summed_outer_linear_iterations': sum(int(row['linear_iterations']) for row in history),
'auxiliary_totals': previous, 'auxiliary_deferrals_total': previous_deferred,
'initial_physical': initial, 'endpoint_physical': endpoint,
'actual_corrected_displacement': 'not_logged; alpha and beta do not determine its norm',
'first_accepted_record': next((row for row in history if row['accepted'] == '1'), None),
'first_after_blocks': [row for row in block_data if row['iteration'] == '0' and row['stage'] == 'after']}
def audit(campaign):
campaign = campaign.resolve()
checks, cases = [], {}
def check(name, value):
checks.append({'check': name, 'passed': bool(value)})
try:
provenance = json.loads((campaign/'provenance.json').read_text())
specifications = provenance['cases']
check('paired_manifest', len(specifications) == 2 and len({case['id'] for case in specifications}) == 2 and
specifications == json.loads((campaign/'cases.json').read_text()))
check('immutable_executable', digest(campaign/'plateau_diagnostic') == provenance['binary_sha256'])
check('mesh_identity', digest(Path(provenance['mesh'])) == provenance['mesh_sha256'])
for specification in specifications:
name, arguments = specification['id'], specification['arguments']
folder = campaign/name
record_path = campaign/(name+'_run.json')
record = json.loads(record_path.read_text())
case_check = lambda label, value: check(name+':'+label, value)
case_check('completed_observation', bool(record.get('finished_utc')) and not record.get('timed_out', False) and record.get('exit_code') in (0, 3))
case_check('command_identity', record['id'] == name and record['command'] ==
[str(campaign/'plateau_diagnostic'), *arguments, '--mesh', provenance['mesh'], '--output', str(folder)])
for path, expected in record['input_state_hashes'].items():
case_check('input_hash:'+path, digest(Path(path)) == expected)
outputs = record['output_hashes']
case_check('required_hashes', REQUIRED <= outputs.keys())
observed_files = {str(path.relative_to(folder)) for path in folder.rglob('*') if path.is_file() and path.suffix in ('.txt', '.csv', '.json')}
case_check('complete_hash_manifest', observed_files == set(outputs))
for path, expected in outputs.items():
case_check('output_hash:'+path, digest(folder/path) == expected)
result = inspect_case(folder, record, case_check)
metadata = result['metadata']
for option, field in {'--index': 'n', '--angular-momentum': 'J', '--max-newton': 'max_newton', '--restart': 'restart',
'--max-linear': 'max_linear', '--linear-tol': 'linear_tol', '--rtol': 'rtol', '--atol': 'atol',
'--schur-sweeps': 'schur_correction_sweeps', '--schur-relaxation': 'schur_relaxation'}.items():
if option in arguments:
case_check('requested_'+field, float(metadata[field]) == float(arguments[arguments.index(option)+1]))
for option, field in (('--strategy', 'strategy'), ('--preconditioner-variant', 'preconditioner_variant')):
case_check('requested_'+field, metadata[field] == arguments[arguments.index(option)+1])
case_check('no_central', '--no-central' in arguments and metadata['central_phase'] == '0')
elapsed = (datetime.datetime.fromisoformat(record['finished_utc'])-datetime.datetime.fromisoformat(record['started_utc'])).total_seconds()
case_check('utc_elapsed_identity', close(record['utc_elapsed_seconds'], elapsed))
case_check('clock_difference_identity', close(record['utc_minus_monotonic_seconds'], elapsed-record['seconds'], elapsed))
case_check('child_cpu_identity', close(record['child_cpu_seconds'], record['child_user_cpu_seconds']+record['child_system_cpu_seconds']))
for field in ('seconds', 'utc_elapsed_seconds', 'child_user_cpu_seconds', 'child_system_cpu_seconds', 'child_cpu_seconds'):
case_check('timing_'+field, math.isfinite(record[field]) and record[field] >= 0)
result['timing'] = {field: record[field] for field in ('started_utc', 'finished_utc', 'seconds', 'utc_elapsed_seconds',
'utc_minus_monotonic_seconds', 'child_user_cpu_seconds', 'child_system_cpu_seconds', 'child_cpu_seconds')}
result['timing']['clock_disagreement_observed'] = abs(record['utc_minus_monotonic_seconds']) > max(.5, .01*record['seconds'])
result['run_record_sha256'] = digest(record_path)
result['output_hashes'] = outputs
cases[name] = result
first, second = specifications
def without_strategy(arguments):
values = list(arguments)
position = values.index('--strategy')
del values[position:position+2]
return values
check('pair:only_strategy_differs', without_strategy(first['arguments']) == without_strategy(second['arguments']))
a, b = cases[first['id']], cases[second['id']]
check('pair:strategies', {a['metadata']['strategy'], b['metadata']['strategy']} == {'curvature', 'curvature-backtracked-coupled'})
excluded = {'strategy', 'converged', 'accepted_steps', 'failure'}
check('pair:matching_metadata', {k: v for k, v in a['metadata'].items() if k not in excluded} ==
{k: v for k, v in b['metadata'].items() if k not in excluded})
for path in ('initial_physical.csv', 'layout.csv'):
check('pair:exact_'+path, a['output_hashes'][path] == b['output_hashes'][path])
both_first = a['first_accepted_record'] is not None and b['first_accepted_record'] is not None
if both_first:
fields = ('iteration', 'F', 'alpha', 'trials', 'linear_status', 'linear_iterations', 'linear_true',
'central_border', 'unbordered_F', 'linear_initial_residual', 'linear_rhs_norm', 'linear_initial_over_rhs')
check('pair:first_accepted_record_exact', all(a['first_accepted_record'][k] == b['first_accepted_record'][k] for k in fields))
check('pair:first_accepted_blocks_exact', a['first_after_blocks'] == b['first_after_blocks'])
passed = all(item['passed'] for item in checks)
return safe({'passed': passed, 'observations_bound_to_valid_artifacts': passed, 'checks': checks, 'cases': cases,
'source_commit': provenance['commit'], 'provenance_sha256': digest(campaign/'provenance.json'),
'analysis_script_sha256': digest(Path(__file__)), 'both_first_accepted_steps_observed': both_first,
'scope': 'Recorded decision/scalar-identity audit, with streaming artifact hashes. Outer and auxiliary true defects are producer observations, not recomputed FEM actions. Matching first-step diagnostics are not bitwise state equality. Numerical and physical outcomes are separate; no speedup-to-convergence claim. Auxiliary phase counters are differenced, not summed repeatedly; nested phase timings must not be added to total iteration time.'})
except (OSError, ValueError, KeyError, TypeError, IndexError, OverflowError) as error:
check('complete_readable_campaign', False)
return safe({'passed': False, 'checks': checks, 'error': str(error), 'cases': cases,
'interpretation_valid': False})
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('campaign', type=Path)
parser.add_argument('--output', type=Path, required=True)
args = parser.parse_args()
if args.output.resolve() == args.campaign.resolve() or args.campaign.resolve() in args.output.resolve().parents:
parser.error('Write analysis outside the immutable campaign.')
result = audit(args.campaign)
args.output.write_text(json.dumps(result, indent=2, allow_nan=False)+'\n')
print('PASS' if result['passed'] else 'FAIL', args.output)
for name, case in result['cases'].items():
print(name, 'accepted=', case['accepted_steps'], 'converged=', case['converged'], 'final F=', case['final_residual'])
return 0 if result['passed'] else 1
if __name__ == '__main__':
raise SystemExit(main())

View File

@@ -0,0 +1,407 @@
#!/usr/bin/env python3
"""Audit a sequential frozen line search, separately from numerical success.
Only saved-vector arithmetic is independent here: no FEM action or physical
quadrature is repeated. A shared attempt budget and first-accept stopping rule
are checked explicitly; these frozen searches are not Newton trajectories.
"""
import argparse
import json
import math
from pathlib import Path
from check_nonlinear_step import EPS, close, digest, dot, layout_for, minus, norm, rows, sanitize, vector
from check_coupled_trial import inspect_physical, near_vector
P = 'damped_coupled_'
STATUS = ('not_attempted', 'original_accepted', 'budget_exhausted', 'kept', 'linear_failure',
'norm_limit', 'non_finite', 'inadmissible', 'not_improved', 'prediction_deferred')
BASE = {'metadata.txt', 'coupled_trial_physical.csv'} | {
P + name + '.csv' for name in ('summary', 'trials', 'candidates', 'evaluations', 'layout')} | {
P + name + '.txt' for name in ('base', 'base_physical', 'base_residual', 'direction', 'base_action',
'state_factors', 'residual_factors', 'restored_residual', 'restored_action')}
def same_number(a, b, scale=0.):
return (math.isnan(a) and math.isnan(b)) or (not math.isfinite(a) and a == b) or close(a, b, scale)
def merit(values):
return .5 * math.fsum(value * value for value in values)
def eligibility(base_merit, prediction_merit, original_merit, maximum_excess):
decrease = base_merit - prediction_merit
ratio = (original_merit - base_merit) / decrease if math.isfinite(decrease) and decrease > 0. else math.nan
return math.isfinite(ratio) and ratio <= maximum_excess, decrease, ratio
def correction_mechanism(prediction, before, corrected, action, rhs, beta):
remainder = minus(before, prediction)
defect = minus(action, rhs)
own = [z - y - beta * a for z, y, a in zip(corrected, before, action)]
after = minus(corrected, prediction)
reconstructed = [(1. - beta) * r + beta * d + e for r, d, e in zip(remainder, defect, own)]
return {'remainder_before_norm': norm(remainder), 'remainder_after_norm': norm(after),
'scaled_linear_defect_norm': abs(beta) * norm(defect), 'own_taylor_remainder_norm': norm(own),
'decomposition_error_norm': norm(minus(after, reconstructed))}
def inspect_case(folder):
try:
return inspect_case_artifacts(Path(folder))
except (OSError, ValueError, KeyError, TypeError, IndexError, OverflowError, ZeroDivisionError) as error:
return {'passed': False, 'observations_valid': False, 'required_artifacts': sorted(BASE),
'checks': [{'check': 'complete_readable_artifacts', 'passed': False, 'error': str(error)}],
'trials': [], 'physical_observations': []}
def inspect_case_artifacts(folder):
checks, required = [], set(BASE)
def check(name, condition):
checks.append({'check': name, 'passed': bool(condition)})
def flag(row, key, label):
value = float(row[key]); check(label + key + ':boolean', value in (0., 1.)); return value == 1.
def get(name, available=True, prefix=P):
path = folder / (prefix + name + '.txt')
if available:
required.add(path.name); return vector(path)
check(name + ':unavailable_file_absent', not path.exists()); return None
summary_rows = rows(folder / (P + 'summary.csv'))
summary = {row['metric']: row['value'] if row['metric'] == 'mode' else float(row['value']) for row in summary_rows}
check('unique_summary', len(summary) == len(summary_rows))
metadata = dict(line.split('=', 1) for line in (folder / 'metadata.txt').read_text().splitlines() if '=' in line)
mode = summary['mode']; check('mode', mode in ('none', 'full', 'damped', 'near'))
check('metadata_scope', metadata['damped_coupled_probe'] == '1' and metadata['coupled_trial_alphas_are_independent'] == '0' and
metadata['coupled_trial_admissibility'] == 'sampled_enthalpy_without_repair' and metadata['coupled_search'] == mode)
for key, source in {'outer_linear_tolerance': 'linear_tol', 'relative_tolerance': 'coupled_tolerance',
'maximum_iterations': 'coupled_iterations', 'restart': 'coupled_restart',
'maximum_correction_ratio': 'coupled_maximum_ratio', 'attempt_budget': 'coupled_attempts_per_iteration',
'beta_reduction': 'coupled_beta_reduction', 'maximum_excess_ratio': 'coupled_excess_ratio'}.items():
check('metadata:' + key, summary[key] == float(metadata[source]))
for key, expected in {'schema_version': 1, 'attempt_budget': 1, 'shared_iteration_budget': 1,
'accepted_commits': 0, 'probe_exception': 0, 'accepted_buffers_bitwise_identical': 1,
'direction_buffers_bitwise_identical': 1, 'normalization_factors_bitwise_identical': 1,
'fresh_operator_and_inverse_current': 1}.items():
check(key, summary[key] == expected)
for name in ('original_accepted', 'budget_exhausted', 'kept', 'prediction_deferred'):
check('status_mapping:' + name, summary['status_' + name] == STATUS.index(name))
for value, name in enumerate(('evaluated', 'inadmissible', 'non_finite')):
check('candidate_status:' + name, summary['candidate_status_' + name] == value)
gravity_path = flag(summary, 'gravity_path', 'summary:')
check('gravity_policy', gravity_path == metadata['strategy'].startswith('curvature-'))
maximum_trials = int(summary['maximum_trials'])
maximum_steps = int(summary['maximum_beta_steps'])
reduction = summary['beta_reduction']
check('outer_grid_control', 1 <= maximum_trials <= 30 and maximum_trials == summary['maximum_trials'])
check('beta_grid_control', maximum_steps >= 1 and maximum_steps == summary['maximum_beta_steps'] and 0 < reduction < 1)
check('full_step_policy', mode not in ('none', 'full') or maximum_steps == 1)
check('beta_steps_metadata', mode in ('none', 'full') or maximum_steps == int(metadata['coupled_beta_steps']))
check('finite_controls', all(math.isfinite(summary[key]) and summary[key] > 0. for key in
('relative_tolerance', 'maximum_correction_ratio', 'maximum_excess_ratio', 'outer_linear_tolerance')))
check('nonnegative_absolute_tolerance', math.isfinite(summary['absolute_tolerance']) and summary['absolute_tolerance'] >= 0.)
check('sufficient_decrease', 0 < summary['sufficient_decrease'] < 1)
x, physical, f, p, j, sf, rf = [get(name) for name in
('base', 'base_physical', 'base_residual', 'direction', 'base_action', 'state_factors', 'residual_factors')]
size = len(x)
check('dimensions', all(len(value) == size for value in (physical, f, p, j, sf, rf)))
check('positive_normalization', all(value > 0. for value in sf + rf))
check('base_normalization', near_vector(x, [value * factor for value, factor in zip(physical, sf)], norm(x)))
layout = rows(folder / (P + 'layout.csv'))
value_layout = layout_for(layout, 'value', size); residual_layout = layout_for(layout, 'residual', size)
gravity_values = {i for name, (offset, count) in value_layout.items() if name in ('gravity_gradient', 'gravity_potential')
for i in range(offset, offset + count)}
gravity_rows = [i for name, (offset, count) in residual_layout.items() if name in ('gravity_gradient_relation', 'poisson_balance')
for i in range(offset, offset + count)]
fn, pn, jn, m0 = norm(f), norm(p), norm(j), merit(f)
check('finite_nonzero_base', math.isfinite(fn) and fn > 0. and math.isfinite(pn) and pn > 0.)
defect = [a + b for a, b in zip(f, j)]
check('outer_true_gate', norm(defect) <= summary['outer_linear_tolerance'] * fn and summary['outer_verified_gate'] == 1)
for key, value in {'base_norm': fn, 'base_merit': m0, 'outer_relative_defect': norm(defect) / fn}.items():
check(key, close(summary[key], value, value))
for name, expected in (('residual', f), ('action', j)):
restored = get('restored_' + name)
error = norm(minus(restored, expected))
check('restored_' + name, near_vector(restored, expected, norm(expected)) and
close(summary['restored_' + name + '_error'], error, norm(expected)))
trial_rows = rows(folder / (P + 'trials.csv'))
candidate_rows = rows(folder / (P + 'candidates.csv'))
evaluation_rows = rows(folder / (P + 'evaluations.csv'))
check('sequential_trials', [int(row['trial']) for row in trial_rows] == list(range(len(trial_rows))) and
1 <= len(trial_rows) <= maximum_trials)
candidate_map = {(int(row['trial']), int(row['candidate'])): row for row in candidate_rows}
evaluation_map = {(int(row['trial']), int(row['evaluation'])): row for row in evaluation_rows}
check('unique_candidates', len(candidate_map) == len(candidate_rows))
check('unique_evaluations', len(evaluation_map) == len(evaluation_rows))
seen_candidates, seen_evaluations, outcomes = set(), set(), []
attempts, deferred, iterations, operation_seconds = 0, 0, 0, 0.
accepted_trial, physical_trials = -1, []
for row in trial_rows:
i, alpha = int(row['trial']), float(row['alpha'])
label, suffix = str(i) + ':', '_a' + str(i)
check(label + 'alpha', alpha == math.ldexp(1., -i))
flags = {key: flag(row, key, label) for key in ('raw_prepared', 'gravity_gate', 'usable', 'before_accepted',
'attempted', 'aux_gate', 'aux_reported_gate', 'aux_verification_applied', 'rhs_saved', 'correction_saved',
'verified_vectors_saved', 'selected_prepared', 'selected_accepted', 'selected_original')}
status = int(row['status']); check(label + 'status', 0 <= status < len(STATUS))
name = STATUS[status]
raw = get('raw' + suffix); prediction = get('prediction' + suffix)
raw_f = get('raw_residual' + suffix, flags['raw_prepared'])
check(label + 'raw_state', near_vector(raw, [a + alpha * b for a, b in zip(x, p)], norm(x) + alpha * pn))
check(label + 'prediction', near_vector(prediction, [a + alpha * b for a, b in zip(f, j)], fn + alpha * jn))
check(label + 'preparation_status', (int(row['raw_reason']) == -1 and int(row['raw_stage']) == -1)
if flags['raw_prepared'] else (int(row['raw_reason']) >= 0 and int(row['raw_stage']) >= 0))
check(label + 'usable_requires_preparation', not flags['usable'] or (flags['raw_prepared'] and flags['gravity_gate']))
if not gravity_path:
check(label + 'raw_path', flags['gravity_gate'] and flags['usable'] == flags['raw_prepared'])
before = get('before' + suffix, flags['usable'])
before_f = get('before_residual' + suffix, flags['usable'])
gravity_correction = get('gravity_correction' + suffix, gravity_path and flags['gravity_gate'])
if flags['usable'] and not gravity_path:
check(label + 'raw_baseline', before == raw and before_f == raw_f)
if gravity_correction is not None:
check(label + 'gravity_support', len(gravity_correction) == size and bool(gravity_values) and bool(gravity_rows) and
all(value == 0. for index, value in enumerate(gravity_correction) if index not in gravity_values))
check(label + 'gravity_displacement', near_vector(before, [a + b for a, b in zip(raw, gravity_correction)], norm(raw) + norm(gravity_correction)))
target = norm([before_f[index] - prediction[index] for index in gravity_rows])
threshold = float(row['gravity_target_threshold']); disagreement = float(row['gravity_affine_disagreement'])
check(label + 'gravity_target', close(float(row['gravity_target_defect']), target, fn + alpha * jn))
check(label + 'gravity_gate', math.isfinite(threshold) and threshold >= 0. and target <= threshold + 512 * EPS * fn and
math.isfinite(disagreement) and 0. <= disagreement <= threshold)
selected = get('selected' + suffix, flags['selected_prepared'])
selected_f = get('selected_residual' + suffix, flags['selected_prepared'])
check(label + 'selected_prepared', flags['selected_prepared'] == flags['usable'])
cutoff = (1. - summary['sufficient_decrease'] * alpha) * m0
for stage, value in (('before', before_f), ('selected', selected_f)):
if value is not None:
check(label + stage + '_norm', close(float(row[stage + '_norm']), norm(value), norm(value)))
check(label + stage + '_merit', close(float(row[stage + '_merit']), merit(value), merit(value)))
else:
check(label + stage + '_unavailable', math.isnan(float(row[stage + '_norm'])) and math.isnan(float(row[stage + '_merit'])))
before_accepted = flags['usable'] and merit(before_f) <= cutoff
check(label + 'before_armijo', flags['before_accepted'] == before_accepted)
eligible, predicted_decrease, excess = eligibility(m0, merit(prediction), merit(before_f), summary['maximum_excess_ratio']) \
if flags['usable'] else (False, math.nan, math.nan)
for key, expected in (('predicted_decrease', predicted_decrease), ('excess_ratio', excess)):
if math.isfinite(float(row[key])):
check(label + key, close(float(row[key]), expected, abs(expected)))
should_attempt = flags['usable'] and mode != 'none' and not before_accepted and attempts < summary['attempt_budget'] and \
(mode != 'near' or eligible)
check(label + 'attempt_decision', flags['attempted'] == should_attempt)
if mode == 'near' and flags['usable'] and not before_accepted and attempts < summary['attempt_budget']:
check(label + 'gate_recorded', same_number(float(row['predicted_decrease']), predicted_decrease, m0) and
same_number(float(row['excess_ratio']), excess, abs(excess)))
if not should_attempt:
expected = 'not_attempted' if not flags['usable'] or mode == 'none' else (
'original_accepted' if before_accepted else ('budget_exhausted' if attempts >= summary['attempt_budget'] else 'prediction_deferred'))
check(label + 'skip_status', name == expected)
deferred += expected == 'prediction_deferred'
if expected == 'prediction_deferred':
check(label + 'deferred_gate_recorded', same_number(float(row['predicted_decrease']), predicted_decrease, m0) and
same_number(float(row['excess_ratio']), excess, abs(excess)))
attempts += should_attempt
check(label + 'shared_budget', int(row['attempts_total']) == attempts <= summary['attempt_budget'])
rhs = get('rhs' + suffix, flags['rhs_saved']); correction = get('correction' + suffix, flags['correction_saved'])
action = get('action' + suffix, flags['verified_vectors_saved']); saved_defect = get('defect' + suffix, flags['verified_vectors_saved'])
check(label + 'save_flags', should_attempt or not any(flags[key] for key in ('rhs_saved', 'correction_saved', 'verified_vectors_saved')))
check(label + 'finite_verification_saved', not (flags['aux_verification_applied'] and math.isfinite(float(row['aux_defect']))) or flags['verified_vectors_saved'])
core = int(row['aux_core_status'])
if should_attempt:
iterations += int(row['aux_iterations'])
check(label + 'iteration_limit', 0 <= int(row['aux_iterations']) <= summary['maximum_iterations'])
check(label + 'reported_status', flags['aux_reported_gate'] == (int(row['aux_status']) == 0))
cap = summary['maximum_correction_ratio'] * alpha * pn
check(label + 'unscaled_cap', same_number(float(row['correction_cap']), cap, cap))
if rhs is not None:
check(label + 'rhs', near_vector(rhs, minus(prediction, before_f), norm(prediction) + norm(before_f)))
if math.isfinite(float(row['aux_threshold'])):
check(label + 'rhs_norm', close(float(row['aux_rhs_norm']), norm(rhs), norm(rhs)))
check(label + 'threshold', close(float(row['aux_threshold']), max(summary['absolute_tolerance'],
summary['relative_tolerance'] * norm(rhs)), float(row['aux_threshold'])))
if flags['verified_vectors_saved']:
check(label + 'verified_availability', flags['aux_verification_applied'] and rhs is not None and correction is not None)
delta = minus(action, rhs); dn, cn = norm(delta), norm(correction)
check(label + 'saved_defect', near_vector(saved_defect, delta, norm(action) + norm(rhs)))
check(label + 'true_defect', same_number(float(row['aux_defect']), dn, norm(rhs)))
check(label + 'true_gate', flags['aux_gate'] == (math.isfinite(dn) and dn <= float(row['aux_threshold'])))
check(label + 'correction_norm', same_number(float(row['correction_norm']), cn, cn))
expected_core = 3 if not math.isfinite(cn) else (1 if not flags['aux_reported_gate'] or not flags['aux_gate'] else (2 if cn > cap else 0))
check(label + 'core_decision', core == expected_core)
if core == 0:
check(label + 'admissible_requires_gates', flags['aux_reported_gate'] and flags['aux_gate'] and
flags['verified_vectors_saved'] and float(row['correction_norm']) <= cap)
else:
check(label + 'failed_core_status', name == {1: 'linear_failure', 2: 'norm_limit', 3: 'non_finite'}.get(core))
check(label + 'failed_core_no_preparation', int(row['preparations']) == 0 and int(row['restorations']) == 0)
else:
check(label + 'no_aux_certificate', core == -1 and int(row['aux_status']) == -1 and not flags['aux_gate'] and
not flags['aux_reported_gate'] and not flags['aux_verification_applied'] and int(row['aux_iterations']) == 0)
check(label + 'no_aux_preparations', int(row['preparations']) == 0 and int(row['restorations']) == 0)
count = int(row['candidate_count'])
check(label + 'candidate_budget', 0 <= count <= maximum_steps and (should_attempt and core == 0 or count == 0))
crows = [candidate_map[(i, k)] for k in range(count)]
seen_candidates.update((i, k) for k in range(count))
erows = [value for key, value in evaluation_map.items() if key[0] == i]
check(label + 'evaluation_order', [int(value['evaluation']) for value in erows] == list(range(len(erows))))
observed, mechanisms = [], []
for erow in erows:
e = int(erow['evaluation']); seen_evaluations.add((i, e)); tag = suffix + '_e' + str(e)
ex, ef = get('evaluated_state' + tag), get('evaluated_residual' + tag)
beta = float(erow['beta'])
check(label + f'e{e}:requires_correction', should_attempt and core == 0 and correction is not None)
scale = norm(before) + norm(correction)
check(label + f'e{e}:displacement', near_vector(ex, [b + beta * c for b, c in zip(before, correction)], scale))
allowed_beta = [0.] + [reduction ** k for k in range(count)]
check(label + f'e{e}:known_beta_or_restore', any(near_vector(ex,
[b + value * c for b, c in zip(before, correction)], scale) for value in allowed_beta))
check(label + f'e{e}:norm', same_number(float(erow['residual_norm']), norm(ef), norm(ef)))
check(label + f'e{e}:merit', same_number(float(erow['merit']), merit(ef), merit(ef)))
check(label + f'e{e}:armijo', flag(erow, 'accepted', label) == (merit(ef) <= cutoff))
observed.append((beta, ex, ef))
mechanisms.append({'evaluation': e, 'beta': beta, **correction_mechanism(prediction, before_f, ef, action, rhs, beta)})
evaluated = []
first_accepted = None
for k, crow in enumerate(crows):
beta = reduction ** k
check(label + f'c{k}:beta', float(crow['beta']) == beta)
cstatus = int(crow['status']); check(label + f'c{k}:status', cstatus in (0, 1, 2))
if cstatus == 0:
matches = [(ex, ef) for observed_beta, ex, ef in observed if near_vector(ex,
[b + beta * c for b, c in zip(before, correction)], norm(before) + norm(correction))]
check(label + f'c{k}:fresh_evaluation', bool(matches))
ex, ef = matches[0]
cm = merit(ef); evaluated.append((beta, ex, ef, cm))
check(label + f'c{k}:merit', close(float(crow['merit']), cm, cm))
accepted = cm <= cutoff
check(label + f'c{k}:armijo', flag(crow, 'accepted', label) == accepted)
if accepted and first_accepted is None: first_accepted = k
else:
check(label + f'c{k}:rejected', not flag(crow, 'accepted', label))
check(label + f'c{k}:time', math.isfinite(float(crow['preparation_seconds'])) and float(crow['preparation_seconds']) >= 0.)
if should_attempt and core == 0:
check(label + 'beta_stop_rule', count == (first_accepted + 1 if first_accepted is not None else maximum_steps))
selected_beta = float(row['selected_beta'])
if flags['usable']:
better_candidates = [item for item in evaluated if item[3] < merit(before_f)]
best = min(better_candidates, key=lambda item: item[3]) if better_candidates else None
if name == 'kept':
fresh = [ef for beta, ex, ef in observed if ex == selected]
check(label + 'kept_best', best is not None and selected_beta == best[0] and selected == best[1])
check(label + 'selected_fresh_residual', bool(fresh) and near_vector(selected_f, fresh[-1], norm(fresh[-1])) and merit(selected_f) < merit(before_f))
else:
check(label + 'fallback_original', math.isnan(selected_beta) and selected == before and near_vector(selected_f, before_f, norm(before_f)))
check(label + 'discarded_best_requires_failed_replay', best is None or
(name in ('inadmissible', 'non_finite', 'not_improved') and int(row['restorations']) > 0))
check(label + 'selected_original', flags['selected_original'] == (selected == before))
else:
check(label + 'unavailable_selection', math.isnan(selected_beta) and not flags['selected_original'])
accepted_now = flags['usable'] and merit(selected_f) <= cutoff
check(label + 'selected_armijo', flags['selected_accepted'] == accepted_now)
if accepted_now:
check(label + 'first_accept_stops', i == len(trial_rows) - 1 and accepted_trial == -1)
accepted_trial = i
pv = get('selected_physical' + suffix, prefix='coupled_trial_')
check(label + 'physical_normalization', near_vector(selected, [v * a for v, a in zip(pv, sf)], norm(selected)))
physical_trials.append({'sample': str(i), 'selected_prepared': '1', 'selected_accepted': '1', 'selected_norm': row['selected_norm']})
for key in ('raw_seconds', 'gravity_seconds', 'correction_seconds', 'solve_seconds', 'refresh_seconds', 'verification_seconds', 'preparation_seconds'):
check(label + key, math.isfinite(float(row[key])) and float(row[key]) >= 0.)
operation_seconds += sum(float(row[key]) for key in ('raw_seconds', 'gravity_seconds', 'correction_seconds'))
check(label + 'correction_time_scope', float(row['correction_seconds']) + 1.e-6 >=
sum(float(row[key]) for key in ('solve_seconds', 'refresh_seconds', 'verification_seconds', 'preparation_seconds')))
outcomes.append({'trial': i, 'alpha': alpha, 'status': name, 'attempted': should_attempt, 'attempts_total': attempts,
'before_accepted': before_accepted, 'selected_accepted': accepted_now, 'selected_beta': selected_beta,
'before_norm': float(row['before_norm']), 'selected_norm': float(row['selected_norm']),
'predicted_decrease': predicted_decrease, 'excess_ratio': excess, 'candidate_mechanisms': mechanisms})
check('candidate_coverage', seen_candidates == set(candidate_map))
check('evaluation_coverage', seen_evaluations == set(evaluation_map))
check('accepted_trial', summary['accepted_trial'] == accepted_trial)
if accepted_trial < 0:
check('exhausted_trial_grid', len(trial_rows) == maximum_trials)
else:
last = trial_rows[-1]
for key, value in {'accepted_alpha': float(last['alpha']), 'accepted_norm': float(last['selected_norm']),
'accepted_beta': float(last['selected_beta'])}.items(): check(key, same_number(summary[key], value, value))
for key, value in {'attempts': attempts, 'aux_iterations': iterations, 'deferred_attempts': deferred}.items():
check(key, summary[key] == value)
check('operation_time_total', close(summary['search_operation_seconds'], operation_seconds, operation_seconds))
check('wall_time_scope', math.isfinite(summary['search_wall_seconds']) and summary['search_wall_seconds'] + 1.e-6 >= operation_seconds)
physical_observations = inspect_physical(folder, physical_trials, metadata, check)
check('no_unexplained_vectors', {path.name for pattern in (P + '*.txt', 'coupled_trial_*.txt') for path in folder.glob(pattern)} ==
{name for name in required if name.endswith('.txt') and name != 'metadata.txt'})
passed = all(item['passed'] for item in checks)
return sanitize({'passed': passed, 'observations_valid': passed, 'required_artifacts': sorted(required), 'checks': checks,
'summary': summary, 'metadata': metadata, 'trials': outcomes if passed else [],
'physical_observations': physical_observations if passed else [],
'scope': 'Sequential frozen search with one shared auxiliary-solve budget. Saved-vector arithmetic, not independent FEM or Newton convergence.'})
def inspect_campaign(campaign):
campaign = Path(campaign).resolve(); checks, results = [], {}
def check(name, value): checks.append({'check': name, 'passed': bool(value)})
try:
provenance = json.loads((campaign / 'provenance.json').read_text())
cases = provenance['cases']
check('executable_hash', digest(campaign / 'plateau_diagnostic') == provenance['binary_sha256'])
check('mesh_hash', digest(Path(provenance['mesh'])) == provenance['mesh_sha256'])
check('case_manifest', json.loads((campaign / 'cases.json').read_text()) == cases)
check('unique_cases', bool(cases) and len(cases) == len({case['id'] for case in cases}))
for case in cases:
name, arguments = case['id'], case['arguments']; folder = campaign / name
record = json.loads((campaign / (name + '_run.json')).read_text())
check(name + ':completed', record.get('exit_code') == 0 and bool(record.get('finished_utc')) and not record.get('timed_out', False))
check(name + ':command', record.get('id') == name and record.get('command') ==
[str(campaign / 'plateau_diagnostic'), *arguments, '--mesh', provenance['mesh'], '--output', str(folder)])
expected_inputs = {}
for option, saved in (('--probe-state', 'base_physical'), ('--probe-direction', 'direction')):
path = Path(arguments[arguments.index(option) + 1])
path = path if path.is_absolute() else Path(provenance['source']) / path
expected_inputs[str(path.resolve())] = saved
check(name + ':required_input_hashes', expected_inputs.keys() <= record.get('input_state_hashes', {}).keys())
for path, value in record.get('input_state_hashes', {}).items(): check(name + ':input:' + path, digest(Path(path)) == value)
for filename, value in record.get('output_hashes', {}).items(): check(name + ':output:' + filename, digest(folder / filename) == value)
for path, saved in expected_inputs.items():
source, target = vector(Path(path)), vector(folder / (P + saved + '.txt'))
check(name + ':input_binding:' + saved, source == target if saved == 'direction' else near_vector(source, target, norm(source)))
result = inspect_case(folder); results[name] = result
check(name + ':required_output_hashes', set(result['required_artifacts']) <= record.get('output_hashes', {}).keys())
check(name + ':probe_scope', '--damped-coupled-probe' in arguments)
metadata = result.get('metadata', {})
for option, key in {'--index': 'n', '--angular-momentum': 'J', '--linear-tol': 'linear_tol',
'--coupled-tol': 'coupled_tolerance', '--coupled-iterations': 'coupled_iterations',
'--coupled-restart': 'coupled_restart', '--coupled-max-ratio': 'coupled_maximum_ratio',
'--coupled-beta-steps': 'coupled_beta_steps', '--coupled-beta-reduction': 'coupled_beta_reduction',
'--coupled-excess-ratio': 'coupled_excess_ratio', '--coupled-attempts': 'coupled_attempts_per_iteration',
'--gravity-tol': 'gravity_tolerance', '--gravity-iterations': 'gravity_iterations', '--gravity-restart': 'gravity_restart'}.items():
if option in arguments:
check(name + ':requested:' + key, key in metadata and float(metadata[key]) == float(arguments[arguments.index(option) + 1]))
for option, key in (('--coupled-search', 'coupled_search'), ('--strategy', 'strategy')):
if option in arguments: check(name + ':requested:' + key, metadata.get(key) == arguments[arguments.index(option) + 1])
if '--no-central' in arguments: check(name + ':central_constraint', metadata.get('central_phase') == '0')
passed = all(item['passed'] for item in checks) and all(result['passed'] for result in results.values())
if not all(item['passed'] for item in checks):
for result in results.values(): result.update(passed=False, observations_valid=False, trials=[], physical_observations=[])
return {'passed': passed, 'source_commit': provenance['commit'], 'checker_sha256': digest(Path(__file__)),
'checker_helpers_sha256': {name: digest(Path(__file__).with_name(name)) for name in
('check_coupled_trial.py', 'check_nonlinear_step.py')},
'provenance_sha256': digest(campaign / 'provenance.json'), 'provenance_checks': checks, 'cases': results}
except (OSError, ValueError, KeyError, TypeError, IndexError) as error:
for result in results.values(): result.update(passed=False, observations_valid=False, trials=[], physical_observations=[])
return {'passed': False, 'provenance_checks': checks + [{'check': 'complete_readable_campaign', 'passed': False, 'error': str(error)}], 'cases': results}
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('campaign', type=Path); parser.add_argument('--output', required=True, type=Path)
args = parser.parse_args()
if args.output.resolve() == args.campaign.resolve() or args.campaign.resolve() in args.output.resolve().parents:
parser.error('Write the audit outside the immutable campaign.')
result = inspect_campaign(args.campaign)
args.output.write_text(json.dumps(result, indent=2, allow_nan=False) + '\n')
print('PASS' if result['passed'] else 'FAIL', args.output)
return 0 if result['passed'] else 1
if __name__ == '__main__':
raise SystemExit(main())

View File

@@ -0,0 +1,85 @@
#!/usr/bin/env python3
"""Independent n=3 Lane–Emden integration; no FEM or production code changes."""
from fractions import Fraction
from pathlib import Path
import json
import math
import sys
import scipy
from scipy.integrate import solve_ivp
def central_series(x, terms=10):
# Recurrence from theta'' + 2 theta'/x + theta^3 = 0 avoids
# a singular initial-value evaluation and a hand-transcribed series.
coeff = [Fraction(1)]
for k in range(terms - 1):
cube = sum(
coeff[i] * coeff[j] * coeff[k-i-j]
for i in range(k+1) for j in range(k-i+1)
)
coeff.append(-cube / ((2*k+2)*(2*k+3)))
theta = math.fsum(float(a)*x**(2*k) for k, a in enumerate(coeff))
mu = -math.fsum(2*k*float(a)*x**(2*k+1) for k, a in enumerate(coeff) if k)
return theta, mu
def solve(rtol, atol, maximum_step, start):
def rhs(x, y):
theta, mu = y
return -mu / x**2, x**2 * theta**3
def zero(x, y):
return y[0]
zero.terminal = True
zero.direction = -1
result = solve_ivp(rhs, (start, 10.0), central_series(start),
events=zero, method="DOP853", rtol=rtol, atol=atol,
max_step=maximum_step)
if not result.success or len(result.t_events[0]) != 1:
raise RuntimeError(result.message)
xi = float(result.t_events[0][0])
mu = float(result.y_events[0][0, 1])
kcrit = math.pi / (4.0*math.pi*mu)**(2.0/3.0)
rho_for_unit_radius = xi**3/(4.0*math.pi*mu)
mass = 4.0*math.pi*(driver_k/math.pi)**1.5*mu
radius = xi*math.sqrt(driver_k/math.pi)*driver_rho**(-1.0/3.0)
return dict(rtol=rtol, atol=atol, maximum_step=maximum_step, start=start,
steps=len(result.t)-1, function_evaluations=result.nfev,
xi1=xi, mu1=mu, K_for_mass_one=kcrit,
rho_c_for_mass_and_radius_one=rho_for_unit_radius,
M_LE_at_driver_K=mass, M_target_minus_M_LE=1.0-mass,
R_LE_at_driver_K_and_rho_c=radius,
K_driver_relative_to_critical_minus_one=driver_k/kcrit-1.0,
virial_bound_T_over_absW_max=0.5*(1.0-mass**(2.0/3.0)))
metadata = Path(sys.argv[1]).resolve()
values = dict(line.split("=", 1) for line in metadata.read_text().splitlines() if "=" in line)
if float(values["n"]) != 3.0 or float(values["M"]) != 1.0:
raise ValueError("This diagnostic uses the campaign's n=3, M=1, G=1 convention")
driver_k = float(values["K"])
driver_rho = float(values["rho_c"])
checks = [solve(3e-12, 1e-14, 0.2, 1e-3),
solve(3e-13, 1e-15, 0.1, 1e-3),
solve(3e-14, 1e-16, 0.05, 1e-3),
solve(3e-14, 1e-16, 0.025, 1e-2),
solve(3e-14, 1e-16, 0.025, 1e-4)]
mu = checks[-1]["mu1"]
def mass_for_k(k):
return 4.0*math.pi*(k/math.pi)**1.5*mu
out = dict(metadata=str(metadata), python=sys.version, scipy=scipy.__version__,
convention="G=1; theta'= -mu/xi^2; mu'=xi^2 theta^3; first theta zero",
driver={name: values[name] for name in ("n", "K", "rho_c", "M", "J", "xi1", "mu1")},
checks=checks,
mass_check_spread=max(x["M_LE_at_driver_K"] for x in checks)-min(x["M_LE_at_driver_K"] for x in checks),
full_metadata_K_binary64_ulp=math.ulp(driver_k),
M_LE_for_K_adjacent_binary64=[mass_for_k(math.nextafter(driver_k, -math.inf)),
mass_for_k(math.nextafter(driver_k, math.inf))],
K_quoted_12_decimal_rounding_interval=[0.3639390599515, 0.3639390599525],
M_LE_for_K_quoted_rounding_interval=[mass_for_k(0.3639390599515), mass_for_k(0.3639390599525)],
limitation="Tolerance/step/start sensitivity check, not an interval-arithmetic error certificate.")
print(json.dumps(out, indent=2))

View File

@@ -0,0 +1,499 @@
#!/usr/bin/env python3
"""Audit frozen nonlinear paths using saved vectors, not scalar curvature fits.
Artifact validity, independently verified linear accuracy, observed nonlinear
improvement, and physical validity are different conclusions. Remainder floors
are heuristic estimates, never certified FEM assembly bounds.
"""
import argparse
import csv
import hashlib
import json
import math
from pathlib import Path
import sys
P = 'nonlinear_step_'
DIRECTIONS = ('full', 'shape', 'fields')
PATHS = ('raw', 'curvature')
EPS = sys.float_info.epsilon
GR = {'gravity_gradient_relation', 'poisson_balance'}
GV = {'gravity_gradient', 'gravity_potential'}
BASE_FILES = {'metadata.txt', P + 'layout.csv'} | {P + n + '.csv' for n in ('summary', 'linear', 'paths', 'blocks', 'mixed', 'preparations', 'inner', 'restorations')} | {
P + n + '.txt' for n in ('physical_base', 'normalized_base', 'residual', 'rhs', 'state_factors', 'residual_factors', 'restored_residual')
} | {P + k + '_' + d + '.txt' for k in ('direction', 'action', 'restored_action') for d in DIRECTIONS}
def digest(path):
return hashlib.sha256(path.read_bytes()).hexdigest()
def rows(path):
with path.open() as stream:
return list(csv.DictReader(stream))
def vector(path):
tokens = path.read_text().split()
count = int(tokens[0])
values = [float(t) for t in tokens[1:]]
if count <= 0 or count != len(values) or not all(math.isfinite(v) for v in values):
raise ValueError(f'Invalid finite vector: {path}')
return values
def norm(v):
return math.sqrt(math.fsum(x * x for x in v))
def dot(a, b):
if len(a) != len(b): raise ValueError('Incompatible vectors')
return math.fsum(x * y for x, y in zip(a, b))
def minus(a, b):
if len(a) != len(b): raise ValueError('Incompatible vectors')
return [x - y for x, y in zip(a, b)]
def close(a, b, scale=0.0):
return math.isfinite(a) and math.isfinite(b) and abs(a - b) <= 5e-10 * max(abs(a), abs(b)) + 512 * EPS * abs(scale) + 1e-28
def nonnegative(x):
return math.isfinite(x) and x >= 0
def sanitize(value):
if isinstance(value, float) and not math.isfinite(value): return None
if isinstance(value, dict): return {k: sanitize(v) for k, v in value.items()}
if isinstance(value, (list, tuple)): return [sanitize(v) for v in value]
return value
def flag(row, key, check, prefix):
check(prefix + key + ':boolean', row[key] in ('0', '1'))
return row[key] == '1'
def layout_for(layout, kind, count):
result, covered = {}, []
entries = [r for r in layout if r['kind'] == kind]
for row in entries:
start, size = int(row['offset']), int(row['size'])
if start < 0 or size < 0: raise ValueError('Invalid layout')
result[row['block']] = (start, size)
covered.extend(range(start, start + size))
if len(result) != len(entries) or covered != list(range(count)):
raise ValueError(f'{kind} blocks do not partition the vector')
return result
def indices(layout, names):
return sorted(i for name in names for i in range(layout[name][0], sum(layout[name])))
def measurements(base, action, trial, alpha):
prediction = [f + alpha * j for f, j in zip(base, action)]
remainder = minus(trial, prediction)
fn, jn, ln, tn, rn = map(norm, (base, action, prediction, trial, remainder))
projection = dot(prediction, remainder)
identity = abs(tn * tn - ln * ln - 2 * projection - rn * rn)
return {'base_norm': fn, 'action_norm': jn, 'linear_prediction_norm': ln, 'residual_norm': tn,
'remainder_norm': rn, 'remainder_over_alpha': rn / alpha, 'remainder_over_alpha_squared': rn / alpha ** 2,
'linear_dot_remainder': projection, 'norm_identity_error': identity}, prediction, remainder
def check_measurements(row, values, check, prefix):
a = float(row['alpha'])
scale = values['base_norm'] + a * values['action_norm'] + values['residual_norm']
for name, value in values.items():
reported = float(row[name])
if name == 'norm_identity_error':
check(prefix + name, math.isfinite(reported) and max(abs(reported), value) <= 2048 * EPS * scale ** 2 + 1e-28)
else:
rounding_scale = scale / a if name == 'remainder_over_alpha' else scale / a ** 2 if name == 'remainder_over_alpha_squared' else scale ** 2 if name == 'linear_dot_remainder' else scale
check(prefix + name, close(value, reported, rounding_scale))
def vector_orders(observations, linear_passed):
groups = {}
for row in observations: groups.setdefault((row['path'], row['direction'], row['block']), []).append(row)
output = []
for key, entries in groups.items():
entries.sort(key=lambda r: r['alpha'], reverse=True)
intervals = []
for first, second in zip(entries, entries[1:]):
resolved = all(r['usable'] and r['increment_resolved'] and r['remainder_norm'] > 10 * r['floor'] for r in (first, second))
if resolved:
intervals.append({'alpha_large': first['alpha'], 'alpha_small': second['alpha'],
'vector_remainder_order': math.log(first['remainder_norm'] / second['remainder_norm']) / math.log(first['alpha'] / second['alpha']),
'derivative_error_ratio': second['remainder_over_alpha'] / first['remainder_over_alpha']})
output.append(dict(zip(('path', 'direction', 'block'), key)) | {'resolved_intervals': intervals,
'status': 'resolved_vector_observations' if intervals else 'unresolved',
'eligible_for_newton_forcing_comparison': linear_passed})
return output
def inspect_case(folder):
try: return inspect_case_artifacts(Path(folder))
except (OSError, ValueError, KeyError, TypeError, IndexError, OverflowError, ZeroDivisionError) as error:
return {'passed': False, 'checks': [{'check': 'complete_readable_artifacts', 'passed': False, 'error': str(error)}],
'observations_valid': False, 'vector_order_observations': [], 'required_artifacts': sorted(BASE_FILES)}
def inspect_case_artifacts(folder):
checks = []
def check(name, passed): checks.append({'check': name, 'passed': bool(passed)})
summary_rows = rows(folder / (P + 'summary.csv'))
summary = {r['metric']: float(r['value']) for r in summary_rows}
check('unique_summary', len(summary) == len(summary_rows))
meta = dict(line.split('=', 1) for line in (folder / 'metadata.txt').read_text().splitlines() if '=' in line)
saved = {name: vector(folder / (P + name + '.txt')) for name in ('physical_base', 'normalized_base', 'residual', 'rhs', 'state_factors', 'residual_factors')}
x, physical, f = saved['normalized_base'], saved['physical_base'], saved['residual']
sf, rf = saved['state_factors'], saved['residual_factors']
check('state_dimensions', len(x) == len(physical) == len(sf))
check('residual_dimensions', len(f) == len(saved['rhs']) == len(rf))
check('positive_factors', all(v > 0 for v in sf + rf))
check('normalized_physical_consistency', all(close(a, b * c, abs(a)) for a, b, c in zip(x, physical, sf)))
check('rhs_is_minus_F', saved['rhs'] == [-v for v in f])
layout = rows(folder / (P + 'layout.csv'))
vl, rl = layout_for(layout, 'value', len(x)), layout_for(layout, 'residual', len(f))
gi, gr, si = indices(vl, GV), indices(rl, GR), set(indices(vl, {'surface_deformation'}))
retained = sorted(set(range(len(x))) - set(gi))
dirs = {d: vector(folder / (P + 'direction_' + d + '.txt')) for d in DIRECTIONS}
acts = {d: vector(folder / (P + 'action_' + d + '.txt')) for d in DIRECTIONS}
for d in DIRECTIONS: check(d + ':dimensions', len(dirs[d]) == len(x) and len(acts[d]) == len(f))
check('shape_split_exact', dirs['shape'] == [v if i in si else 0.0 for i, v in enumerate(dirs['full'])])
check('fields_split_exact', dirs['fields'] == [0.0 if i in si else v for i, v in enumerate(dirs['full'])])
split_error = norm([a - b - c for a, b, c in zip(acts['full'], acts['shape'], acts['fields'])])
check('action_split', split_error <= 512 * EPS * sum(norm(v) for v in acts.values()) + 1e-28)
lr = rows(folder / (P + 'linear.csv'))
check('one_linear_report', len(lr) == 1)
linear = lr[0]
rhs_norm, defect = norm(saved['rhs']), norm([a + b for a, b in zip(f, acts['full'])])
target = max(summary['linear_absolute_tolerance'], float(meta['linear_tol']) * rhs_norm)
check('linear_control_matches_metadata', summary['linear_relative_tolerance'] == float(meta['linear_tol']) and summary['linear_maximum_iterations'] == int(meta['max_linear']) and summary['linear_restart_length'] == int(meta['restart']))
gate = defect <= target
for key, value in [('rhs_norm', rhs_norm), ('verified_true_norm', defect), ('verified_relative_true', defect / rhs_norm), ('threshold', target)]:
check('linear:' + key, close(value, float(linear[key]), 1.0 if key == 'verified_relative_true' else rhs_norm))
check('summary_linear_gate', summary['linear_verified_gate'] == int(gate))
check('honest_linear_gate', flag(linear, 'verified_gate', check, 'linear:') == gate)
converged = flag(linear, 'converged', check, 'linear:')
check('linear_status', converged == (linear['status'] == '0'))
check('linear_finite_reported_defect', nonnegative(float(linear['reported_true_norm'])))
check('linear_budget', 0 <= int(linear['iterations']) <= int(meta['max_linear']))
check('linear_time', nonnegative(float(linear['seconds'])))
path_rows, block_rows, mixed_rows = (rows(folder / (P + n + '.csv')) for n in ('paths', 'blocks', 'mixed'))
pm = {(int(r['sample']), r['direction'], r['path']): r for r in path_rows}
bm = {(int(r['sample']), r['direction'], r['path'], r['block']): r for r in block_rows}
mm = {(int(r['sample']), r['path'], r['block']): r for r in mixed_rows}
check('unique_paths', len(pm) == len(path_rows)); check('unique_blocks', len(bm) == len(block_rows)); check('unique_mixed', len(mm) == len(mixed_rows))
samples = sorted({key[0] for key in pm})
check('eight_samples', samples == list(range(8)))
check('complete_path_grid', set(pm) == {(i, d, p) for i in samples for d in DIRECTIONS for p in PATHS})
layouts = {'all': (0, len(f)), **rl}
check('complete_block_grid', set(bm) == {(i,d,p,b) for i in samples for d in DIRECTIONS for p in PATHS for b in layouts})
check('complete_mixed_grid', set(mm) == {(i,p,b) for i in samples for p in PATHS for b in layouts})
restoration_error = validate_restoration(folder, summary, f, acts, layouts, check)
inner_rows = rows(folder / (P + 'inner.csv'))
inner_map = {(int(r['sample']), r['direction']): r for r in inner_rows}
check('unique_inner_reports', len(inner_map) == len(inner_rows))
check('inner_coverage', set(inner_map) == {(i,d) for i in samples for d in DIRECTIONS if pm[(i,d,'raw')]['prepared'] == '1'})
validate_work(folder, summary, linear, inner_rows, path_rows, check)
cancellation = []
for block, (start, size) in layouts.items():
an = {d:norm(acts[d][start:start+size]) for d in DIRECTIONS}
denominator = an['shape'] * an['fields']
cancellation.append({'block':block, 'action_norms':an,
'shape_fields_cosine':dot(acts['shape'][start:start+size],acts['fields'][start:start+size])/denominator if denominator else None,
'full_over_sum_split_norms':an['full']/(an['shape']+an['fields']) if an['shape']+an['fields'] else None})
required, observations, outcomes = set(BASE_FILES), [], []
for sample in samples:
alphas = {float(pm[(sample, d, p)]['alpha']) for d in DIRECTIONS for p in PATHS}
check(f'{sample}:common_positive_alpha', len(alphas) == 1 and all(math.isfinite(a) and a > 0 for a in alphas))
a, data = next(iter(alphas)), {}
check(f'{sample}:recorded_alpha', a == summary['alpha_' + str(sample)])
for d in DIRECTIONS:
pred_name = P + 'prediction_' + d + '_a' + str(sample) + '.txt'
required.add(pred_name)
saved_prediction = vector(folder / pred_name)
check(f'{sample}:{d}:prediction_vector', len(saved_prediction) == len(f) and all(close(v,f0+a*j,abs(f0)+a*abs(j)) for v,f0,j in zip(saved_prediction,f,acts[d])))
for path in PATHS:
row, label = pm[(sample, d, path)], f'{sample}:{d}:{path}:'
flags = {k: flag(row, k, check, label) for k in ('prepared', 'inner_converged', 'prepared_gate', 'usable', 'increment_resolved')}
check(label + 'usable_definition', flags['usable'] == (flags['prepared'] and flags['inner_converged'] and flags['prepared_gate']))
check(label + 'seconds', nonnegative(float(row['seconds'])))
correction = [0.0] * len(x)
if path == 'curvature' and flags['inner_converged']:
correction_name = P + 'correction_curvature_' + d + '_a' + str(sample) + '.txt'
required.add(correction_name); correction = vector(folder / correction_name)
check(label + 'correction_only_gravity', len(correction) == len(x) and all(correction[i] == 0 for i in retained))
if path == 'curvature' and (sample,d) in inner_map:
ir = inner_map[(sample,d)]
inner_converged = ir['converged'] == '1'
check(label + 'inner_matches', flags['inner_converged'] == inner_converged and inner_converged == (ir['status'] == '0') and float(ir['alpha']) == a)
inner_target = max(summary['gravity_absolute_tolerance'],summary['gravity_relative_tolerance']*float(ir['rhs_norm']))
check(label + 'inner_target', close(float(ir['threshold']),inner_target,inner_target))
if inner_converged: check(label + 'inner_gate', nonnegative(float(ir['true_norm'])) and float(ir['true_norm']) <= inner_target)
if path == 'raw': check(label + 'vacuous_flags', flags['inner_converged'] and flags['prepared_gate'])
if not flags['prepared']:
check(label + 'not_usable', not flags['usable'])
check(label + 'unprepared_metrics_unavailable', all(math.isnan(float(row[k])) for k in ('residual_norm','merit','remainder_norm','linear_dot_remainder','norm_identity_error','heuristic_roundoff_scale')))
for block in layouts:
br = bm[(sample,d,path,block)]
check(label + block + ':unprepared_unavailable', all(math.isnan(float(br[k])) for k in ('residual_norm','remainder_norm','linear_dot_remainder','norm_identity_error')))
outcomes.append({'sample':sample,'alpha':a,'direction':d,'path':path,**flags,
'status':'raw_preparation_failed' if path=='raw' else 'raw_preparation_blocked' if pm[(sample,d,'raw')]['prepared']=='0' else 'inner_solve_failed' if not flags['inner_converged'] else 'corrected_preparation_failed'})
data[(d, path)] = None; continue
files = {k: P + k + '_' + path + '_' + d + '_a' + str(sample) + '.txt' for k in ('state', 'residual')}
required.update(files.values())
state, trial = vector(folder / files['state']), vector(folder / files['residual'])
check(label + 'dimensions', len(state) == len(x) and len(trial) == len(f))
values, prediction, remainder = measurements(f, acts[d], trial, a)
check_measurements(row, values, check, label)
check(label + 'merit', close(.5 * values['residual_norm'] ** 2, float(row['merit']), values['residual_norm'] ** 2))
check(label + 'slope', close(dot(f, acts[d]), float(row['slope']), norm(f) * norm(acts[d])))
increment = minus(state, x)
intended = [a * v + delta for v,delta in zip(dirs[d],correction)]
addition_error = norm(minus(increment,intended))
expected_norm = norm(intended)
check(label + 'expected_step_norm', close(expected_norm,float(row['expected_step_norm']),expected_norm))
check(label + 'addition_error_norm', close(addition_error,float(row['addition_error_norm']),norm(x)))
resolved = expected_norm > 64*EPS*(1+norm(x)) and norm(increment)>0 and addition_error <= .01*expected_norm
check(label + 'honest_increment_resolution', flags['increment_resolved'] == resolved)
derivative = values['remainder_over_alpha']/values['action_norm'] if values['action_norm']>0 else math.nan
check(label + 'relative_derivative_error', close(derivative,float(row['relative_derivative_error']),derivative) if math.isfinite(derivative) else math.isnan(float(row['relative_derivative_error'])))
check(label + 'actual_step_norm', close(norm(increment), float(row['actual_step_norm']), norm(x)))
if path == 'raw':
intended = [a * v for v in dirs[d]]
error = norm(minus(increment, intended))
check(label + 'raw_state_path', error <= 512 * EPS * (norm(x) + norm(intended)) + 1e-28)
check(label + 'vacuous_gravity_flags', flags['inner_converged'] and flags['prepared_gate'])
else:
raw = data[(d, 'raw')]
check(label + 'prepared_raw_required', raw is not None)
delta = minus(state, raw['state'])
check(label + 'saved_correction_matches_state', norm(minus(delta,correction)) <= 512*EPS*(norm(state)+norm(correction))+1e-28)
check(label + 'retained_coordinates_unchanged', all(delta[i] == 0 for i in retained))
check(label + 'gravity_correction_norm', close(norm(delta), float(row['gravity_correction_norm']), norm(state)))
target_defect = norm(remainder[i] for i in gr)
check(label + 'gravity_affine_target_defect', close(target_defect, float(row['gravity_target_defect']), values['base_norm'] + a * values['action_norm']))
allowance, threshold = float(row['gravity_arithmetic_allowance']), float(row['gravity_target_threshold'])
check(label + 'threshold_is_inner_defect_plus_allowance', close(threshold,float(inner_map[(sample,d)]['true_norm'])+allowance,threshold))
check(label + 'gravity_thresholds', nonnegative(allowance) and nonnegative(threshold) and threshold >= allowance)
if flags['prepared_gate']:
check(label + 'gravity_target_gate', target_defect <= threshold + 512 * EPS * values['base_norm'])
check(label + 'gravity_affine_gate', nonnegative(float(row['gravity_affine_disagreement'])) and float(row['gravity_affine_disagreement']) <= allowance)
data[(d, path)] = {'state': state, 'trial': trial, 'prediction': prediction, 'remainder': remainder, 'flags': flags}
outcomes.append({'sample': sample, 'alpha': a, 'direction': d, 'path': path, **flags, 'status':'usable' if flags['usable'] else 'prepared_gravity_gate_failed',
'actual_gravity_residual_norm':norm(trial[i] for i in gr),
'gravity_affine_target_defect':float(row['gravity_target_defect']) if path=='curvature' else None,
'actual_norm': values['residual_norm'], 'predicted_norm': values['linear_prediction_norm'],
'actual_merit_decrease': .5 * (values['base_norm'] ** 2 - values['residual_norm'] ** 2),
'predicted_merit_decrease': .5 * (values['base_norm'] ** 2 - values['linear_prediction_norm'] ** 2)})
for block, (start, size) in layouts.items():
br = bm[(sample, d, path, block)]
check(label + block + ':layout', int(br['offset']) == start and int(br['size']) == size and float(br['alpha']) == a)
part, _, _ = measurements(f[start:start + size], acts[d][start:start + size], trial[start:start + size], a)
check_measurements(br, part, check, label + block + ':')
roundoff = 128 * EPS * (1+part['base_norm'] + a * part['action_norm'] + part['residual_norm'])
floor = max(8*restoration_error,roundoff)
reported_floor = float(br['heuristic_roundoff_scale'])
check(label + block + ':heuristic_floor', math.isfinite(reported_floor) and roundoff*(1-1e-12) <= reported_floor <= floor*(1+1e-12))
if block == 'all': check(label+'path_floor_matches',close(float(row['heuristic_roundoff_scale']),reported_floor,reported_floor))
observations.append({'sample': sample, 'alpha': a, 'path': path, 'direction': d, 'block': block,
'usable': flags['usable'], 'increment_resolved': flags['increment_resolved'], **part, 'floor': floor})
for path in PATHS:
usable = all(data[(d, path)] is not None and data[(d, path)]['flags']['usable'] for d in DIRECTIONS)
for block, (start, size) in layouts.items():
row, label = mm[(sample, path, block)], f'{sample}:{path}:mixed:{block}:'
check(label + 'layout', int(row['offset']) == start and int(row['size']) == size and float(row['alpha']) == a)
check(label + 'honest_usable', flag(row, 'usable', check, label) == usable)
all_prepared = all(data[(d,path)] is not None for d in DIRECTIONS)
if not all_prepared:
check(label+'unavailable_metrics',all(math.isnan(float(row[k])) for k in ('full_remainder_norm','mixed_remainder_norm','linear_dot_mixed','norm_identity_error')))
continue
remainders = {d: data[(d, path)]['remainder'][start:start + size] for d in DIRECTIONS}
remainders['mixed'] = [u - v - w for u, v, w in zip(remainders['full'], remainders['shape'], remainders['fields'])]
prediction = data[('full', path)]['prediction'][start:start + size]
scale = norm(prediction) + sum(norm(v) for v in remainders.values())
projections = {d: dot(prediction, v) for d, v in remainders.items()}
for d, vals in remainders.items():
check(label + d + ':norm', close(norm(vals), float(row[d + '_remainder_norm']), scale))
check(label + d + ':projection', close(projections[d], float(row['linear_dot_' + d]), scale ** 2))
error = abs(projections['full'] - projections['shape'] - projections['fields'] - projections['mixed'])
check(label + 'projection_identity', error <= 2048 * EPS * scale ** 2 + 1e-28 and math.isfinite(float(row['projection_identity_error'])) and abs(float(row['projection_identity_error'])) <= 2048*EPS*scale**2+1e-28)
identity = norm(data[('full',path)]['trial'][start:start+size])**2 - norm(prediction)**2 - 2*(projections['shape']+projections['fields']+projections['mixed']) - norm(remainders['full'])**2
check(label+'full_merit_identity',abs(identity)<=2048*EPS*scale**2+1e-28 and math.isfinite(float(row['norm_identity_error'])) and abs(float(row['norm_identity_error']))<=2048*EPS*scale**2+1e-28)
validate_summary(summary, check)
for obs in observations:
if obs['path'] == 'curvature': obs['floor'] += float(pm[(obs['sample'], obs['direction'], obs['path'])]['gravity_arithmetic_allowance'])
passed = all(r['passed'] for r in checks)
return sanitize({'passed': passed, 'checks': checks, 'observations_valid': passed, 'required_artifacts': sorted(required),
'metadata': meta, 'summary': summary, 'direction_quality': {'raw_linear_gate': gate, 'backend_converged': converged,
'verified_relative_defect': defect / rhs_norm, 'passed': gate and converged}, 'paths': outcomes, 'shape_fields_action_cancellation': cancellation,
'preparation_failures':[r for r in rows(folder/(P+'preparations.csv')) if r['prepared']=='0'],
'gravity_assessment_scope':'Saved trial vectors independently verify the affine-target defect, not the underlying gravity action used by the reported affine-disagreement allowance. Actual gravity residual norms are reported separately.',
'vector_order_observations': vector_orders(observations, gate and converged) if passed else [],
'scope': 'Artifact validity is separate from linear convergence, nonlinear improvement, admissibility and physical validation.',
'order_scope': 'Orders require usable paths, finite verified J actions, resolved increments and vector remainders exceeding10 times the heuristic floor. Floor=max(8 times maximum restoration drift,128eps times(1+residual/action scales))+gravity arithmetic allowance for corrected paths. Normalized block norms use the configured diagonal Riesz factors, not exact physical L2. Noninteger superlinear order can be consistent with the EOS; derivative-error decline is reported without an order-two pass requirement. Failed outer forcing gates do not invalidate directional Taylor measurements; they preclude Newton-forcing comparisons and eta-based descent guarantees. This is not a certified assembly bound or universal order claim.'})
def validate_summary(summary, check):
ones = {'accepted_buffers_bitwise_identical','normalization_factors_bitwise_identical',
'roundoff_scale_is_subtraction_heuristic','path_seconds_include_shared_raw_preparation'}
zeroes = {'accepted_state_change','accepted_residual_change','accepted_physical_change',
'accepted_commits','polynomial_direction_repairs','linear_gate_failure_skips_trials'}
check('required_summary_invariants', ones | zeroes | {'maximum_original_restoration_error','maximum_restored_action_difference'} <= summary.keys())
for key in ones: check(key,summary.get(key)==1)
for key in zeroes: check(key,summary.get(key)==0)
check('supported_schema',summary.get('schema_version')==1 and summary.get('machine_epsilon')==EPS)
def validate_restoration(folder, summary, f, actions, layouts, check):
restored = vector(folder/(P+'restored_residual.txt'))
difference = norm(minus(restored,f))
records = rows(folder/(P+'restorations.csv'))
grouped = {}
for row in records: grouped.setdefault((row['sequence'],row['kind']),[]).append(row)
maximum = 0.0
for key,group in grouped.items():
by_block = {r['block']:r for r in group}
check('restoration:'+str(key)+':complete_blocks',len(by_block)==len(group) and set(by_block)==set(layouts))
for block,(start,size) in layouts.items():
row=by_block[block]
check('restoration:'+str(key)+':'+block, int(row['offset'])==start and int(row['size'])==size and close(float(row['base_norm']),norm(f[start:start+size])) and nonnegative(float(row['difference_norm'])))
block_norm = norm(float(by_block[b]['difference_norm']) for b in layouts if b!='all')
check('restoration:'+str(key)+':norm_partition',close(block_norm,float(by_block['all']['difference_norm']),norm(f)))
maximum=max(maximum,float(by_block['all']['difference_norm']))
check('restoration_records_present',bool(grouped))
check('maximum_restoration_recorded',close(maximum,summary['maximum_original_restoration_error'],norm(f)))
check('final_residual_restored',difference<=maximum+512*EPS*norm(f)+1e-28)
changes=[]
for d in DIRECTIONS:
final=vector(folder/(P+'restored_action_'+d+'.txt'))
changes.append(norm(minus(final,actions[d])))
check('maximum_action_change_recorded',close(max(changes),summary['maximum_restored_action_difference'],max(map(norm,actions.values()))))
# Restoration may be nonzero roundoff, but cannot be arbitrarily large and
# still certify that these finite differences use one frozen operator.
check('base_restoration_small',maximum<=2048*EPS*(1+norm(f)))
check('action_restoration_small',max(changes)<=2048*EPS*(1+max(map(norm,actions.values()))))
return maximum
def validate_work(folder, summary, linear, inner, paths, check):
preparations=rows(folder/(P+'preparations.csv'))
check('preparation_count',len(preparations)==summary['preparations'])
check('preparation_sequence', [int(r['sequence']) for r in preparations]==list(range(1,len(preparations)+1)))
check('preparation_times',all(nonnegative(float(r['seconds'])) for r in preparations))
check('preparation_total_time',close(math.fsum(float(r['seconds']) for r in preparations),summary['preparation_seconds']))
check('prepared_path_count',sum(r['prepared']=='1' for r in paths)==summary['prepared_paths'])
for direction in DIRECTIONS:
for path in PATHS:
calls=[r for r in preparations if r['kind']==path and r['direction']==direction]
wanted=[r for r in paths if r['path']==path and r['direction']==direction and (path=='raw' or r['inner_converged']=='1')]
check(direction+':'+path+':preparation_coverage',len(calls)==len(wanted) and {(float(r['alpha']),r['prepared']) for r in calls}=={(float(r['alpha']),r['prepared']) for r in wanted})
check('gravity_solve_count',len(inner)==summary['gravity_solves'])
check('gravity_iteration_total',sum(int(r['iterations']) for r in inner)==summary['gravity_iterations'])
check('gravity_failure_count',sum(r['converged']!='1' for r in inner)==summary['gravity_failures'])
check('gravity_solve_time',close(math.fsum(float(r['seconds']) for r in inner),summary['gravity_solve_seconds']))
check('linear_time_matches',close(float(linear['seconds']),summary['linear_solve_seconds']))
# Raw and corrected path timers overlap; do not add them to form a cost.
check('total_time_scope',nonnegative(summary['total_seconds']) and summary['total_seconds']+1e-6>=summary['preparation_seconds']+summary['linear_solve_seconds']+summary['gravity_solve_seconds'])
def inspect_campaign(campaign):
campaign, checks, results = Path(campaign).resolve(), [], {}
def check(name, passed): checks.append({'check': name, 'passed': bool(passed)})
try:
provenance = json.loads((campaign / 'provenance.json').read_text())
check('immutable_executable', digest(campaign / 'plateau_diagnostic') == provenance['binary_sha256'])
check('mesh_hash', digest(Path(provenance['mesh'])) == provenance['mesh_sha256'])
cases = provenance['cases']
check('unique_nonempty_cases', bool(cases) and len(cases) == len({c['id'] for c in cases}))
check('manifest_snapshot', json.loads((campaign / 'cases.json').read_text()) == cases)
for case in cases:
name = case['id']; folder = campaign / name
record = json.loads((campaign / (name + '_run.json')).read_text())
check(name + ':completed', bool(record.get('finished_utc')) and record.get('exit_code') == 0 and not record.get('timed_out', False))
args = case['arguments']
command = [str(campaign / 'plateau_diagnostic'), *args, '--mesh', provenance['mesh'], '--output', str(folder)]
check(name + ':command', record.get('command') == command and record.get('id') == name)
expected = set()
for i, arg in enumerate(args):
if arg == '--probe-state':
p = Path(args[i + 1]); p = p if p.is_absolute() else Path(provenance['source']) / p
expected.add(str(p.resolve()))
check(name + ':required_input_hashes', expected <= record.get('input_state_hashes', {}).keys())
for p, value in record.get('input_state_hashes', {}).items(): check(name + ':input:' + p, digest(Path(p)) == value)
for p, value in record.get('output_hashes', {}).items(): check(name + ':output:' + p, digest(folder / p) == value)
result = inspect_case(folder)
check(name + ':required_output_hashes', set(result['required_artifacts']) <= record.get('output_hashes', {}).keys())
bindings={'--linear-tol':'linear_tol','--max-linear':'max_linear','--restart':'restart',
'--index':'n','--angular-momentum':'J','--gravity-tol':'gravity_tolerance',
'--gravity-iterations':'gravity_iterations','--gravity-restart':'gravity_restart',
'--schur-sweeps':'context_gravity_schur_sweeps','--schur-relaxation':'context_gravity_schur_relaxation'}
metadata=result.get('metadata',{})
check(name+':expert_probe_selected','--nonlinear-step-probe' in args and metadata.get('nonlinear_step_probe')=='1')
for option,key in bindings.items():
if option in args:check(name+':requested_'+key,key in metadata and float(metadata[key])==float(args[args.index(option)+1]))
if '--preconditioner-variant' in args:check(name+':requested_inverse',metadata.get('context_preconditioner_variant')==args[args.index('--preconditioner-variant')+1])
if '--no-central' in args:check(name+':no_central_constraint',metadata.get('central_phase')=='0')
results[name] = result
passed = all(c['passed'] for c in checks) and all(r['passed'] for r in results.values())
if not all(c['passed'] for c in checks):
for r in results.values(): r.update(passed=False, observations_valid=False, vector_order_observations=[])
return {'passed': passed, 'source_commit': provenance['commit'], 'provenance_sha256': digest(campaign / 'provenance.json'),
'checker_sha256': digest(Path(__file__)), 'provenance_checks': checks, 'cases': results,
'scope': 'Independent vector/provenance audit. A failed numerical gate is a valid observation, not a successful model.'}
except (OSError, ValueError, KeyError, TypeError, IndexError) as error:
for r in results.values(): r.update(passed=False, observations_valid=False, vector_order_observations=[])
return {'passed': False, 'provenance_checks': checks + [{'check': 'complete_readable_campaign', 'passed': False, 'error': str(error)}], 'cases': results}
def compare_same_state(left_folder, left_review, right_folder, right_review):
"""Compare sampled directions only after caller-provided artifact audits.
A small action of their difference is evidence about this one sampled
response. It is neither a nullspace construction nor a condition estimate.
"""
left_folder,right_folder=Path(left_folder),Path(right_folder)
names=('physical_base','normalized_base','residual','rhs','state_factors','residual_factors')
identity={name:digest(left_folder/(P+name+'.txt'))==digest(right_folder/(P+name+'.txt')) for name in names}
identity['layout']=digest(left_folder/(P+'layout.csv'))==digest(right_folder/(P+'layout.csv'))
available=left_review['passed'] and right_review['passed'] and all(identity.values())
result={'available':available,'same_input_hashes':identity,
'eligible_for_newton_forcing_comparison':available and left_review.get('direction_quality',{}).get('passed',False) and right_review.get('direction_quality',{}).get('passed',False),
'scope':'w=p_right-p_left and Jw=action_right-action_left use identical saved state/RHS/factors/layout. One sampled weak response is not proof of a nullspace, gauge or condition number. Norms use diagonal normalization, not exact physical L2.'}
if not available:return result
pa,pb=(vector(folder/(P+'direction_full.txt')) for folder in (left_folder,right_folder))
ja,jb=(vector(folder/(P+'action_full.txt')) for folder in (left_folder,right_folder))
w,jw=minus(pb,pa),minus(jb,ja)
result['direction_difference_norm']=norm(w);result['action_difference_norm']=norm(jw)
result['sampled_action_over_direction_difference']=norm(jw)/norm(w) if norm(w)>0 else None
result['direction_cosine']=dot(pa,pb)/(norm(pa)*norm(pb)) if norm(pa)*norm(pb)>0 else None
result['differences_by_block']={}
layout=rows(left_folder/(P+'layout.csv'))
for kind,values in [('value',w),('residual',jw)]:
partition=layout_for(layout,kind,len(values))
result['differences_by_block'][kind]={block:norm(values[start:start+size]) for block,(start,size) in partition.items()}
return result
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('campaign', type=Path)
parser.add_argument('--output', type=Path, required=True)
args = parser.parse_args()
if args.campaign.resolve() in args.output.resolve().parents:
parser.error('Write the review outside the immutable campaign.')
result = inspect_campaign(args.campaign)
args.output.write_text(json.dumps(result, indent=2, allow_nan=False) + '\n')
print('PASS' if result['passed'] else 'FAIL', args.output)
for name, case in result['cases'].items(): print(name, 'artifacts=', case['passed'], 'raw_linear=', case.get('direction_quality', {}).get('raw_linear_gate'))
return 0 if result['passed'] else 1
if __name__ == '__main__':
raise SystemExit(main())

View File

@@ -0,0 +1,375 @@
#!/usr/bin/env python3
"""Check frozen numerical-strategy probes, without certifying a stellar model.
Exit 0: requested evidence passes. Exit 3: an invariant or expectation fails.
Exit 2: evidence is incomplete (including a correctly reported failed solve).
Use check_plateau_physics.py separately for an end-to-end equilibrium endpoint.
"""
import argparse
import csv
import json
import math
from pathlib import Path
import sys
EPSILON = sys.float_info.epsilon
APPLICATION_AGREEMENT_TOLERANCE = 2.0e-12
SIGN_STATUSES = {"certified_nonnegative", "unresolved", "negative", "non_finite"}
def read_rows(path, required):
with path.open(newline="") as stream:
reader = csv.DictReader(stream)
if reader.fieldnames is None or len(set(reader.fieldnames)) != len(reader.fieldnames):
raise ValueError(f"Missing or duplicate columns in {path.name}")
if not set(required).issubset(reader.fieldnames):
raise ValueError(f"Missing required columns in {path.name}: {sorted(set(required) - set(reader.fieldnames))}")
result = []
for row in reader:
if None in row or any(value is None for value in row.values()):
raise ValueError(f"Malformed CSV row in {path.name}")
result.append(row)
return result
def metrics(path):
result = {}
for row in read_rows(path, ("metric", "value")):
if not row["metric"] or row["metric"] in result:
raise ValueError(f"Empty or duplicate metric in {path.name}")
result[row["metric"]] = float(row["value"])
return result
def number(row, key):
return float(row[key])
def flag(row, key):
if row[key] not in ("0", "1"):
raise ValueError(f"Invalid boolean {key}: {row[key]!r}")
return row[key] == "1"
def nonnegative(value):
return math.isfinite(value) and value >= 0.0
def roundoff(*values):
return 512.0 * EPSILON * (1.0 + sum(abs(value) for value in values if math.isfinite(value)))
def clean_json(value):
if isinstance(value, float) and not math.isfinite(value):
return None
if isinstance(value, dict):
return {key: clean_json(item) for key, item in value.items()}
if isinstance(value, list):
return [clean_json(item) for item in value]
return value
class Assessment:
def __init__(self, folder, restoration_tolerance):
self.folder = folder
self.restoration_tolerance = restoration_tolerance
self.checks = []
self.outcomes = {}
def check(self, name, condition, **details):
self.checks.append({"name": name, "status": "pass" if condition else "fail", **details})
def incomplete(self, name, **details):
self.checks.append({"name": name, "status": "incomplete", **details})
def restore(self, values, accepted, restored):
for key in accepted:
self.check(key, values[key] == 0.0, value=values[key], required=0.0)
for key in restored:
self.check(key, nonnegative(values[key]) and values[key] <= self.restoration_tolerance,
value=values[key], tolerance=self.restoration_tolerance)
def polynomial(self, expect_negative):
certificates = read_rows(self.folder / "polynomial_certificates.csv", ("state", "status", "witness_element", "x", "y", "z"))
by_state = {row["state"]: row for row in certificates}
if len(by_state) != len(certificates):
raise ValueError("Duplicate polynomial certificate state")
for name in ("frozen_base", "context_seed_anchor", "original_full_candidate"):
if name not in by_state:
raise ValueError(f"Missing polynomial certificate: {name}")
if any(row["status"] not in SIGN_STATUSES for row in certificates):
raise ValueError("Unknown polynomial certificate status")
repairs = read_rows(self.folder / "polynomial_repair.csv", ("status", "minimum_safe_fraction", "base_status"))
if len(repairs) != 1:
raise ValueError("Polynomial repair summary must contain one row")
repair = repairs[0]
trials = read_rows(self.folder / "polynomial_repair_trials.csv", ("fraction", "alpha", "certificate", "prepared", "merit_slope"))
base_status = by_state["frozen_base"]["status"]
self.outcomes["polynomial"] = {"base": base_status, "anchor": by_state["context_seed_anchor"]["status"],
"repair": repair["status"], "trials": len(trials)}
self.check("repair_base_matches_certificate", repair["base_status"] == base_status)
if expect_negative:
self.check("expected_negative_base_detected", base_status == "negative", observed=base_status)
self.check("negative_base_repair_rejected", repair["status"] == "invalid_base", observed=repair["status"])
if base_status != "certified_nonnegative":
self.check("uncertified_base_is_rejected", repair["status"] == "invalid_base")
self.check("uncertified_base_has_no_repaired_trials", all(number(row, "fraction") == 0.0 for row in trials))
if base_status == "unresolved":
self.incomplete("polynomial_base_classification", reason="Subdivision budget did not resolve the base sign")
if base_status == "negative":
witness = by_state["frozen_base"]
self.check("negative_base_has_local_witness", int(witness["witness_element"]) >= 0 and
all(0.0 <= number(witness, axis) <= 1.0 for axis in ("x", "y", "z")))
if repair["status"] == "feasible":
fraction = number(repair, "minimum_safe_fraction")
self.check("repair_fraction_in_unit_interval", math.isfinite(fraction) and 0.0 <= fraction <= 1.0,
fraction=fraction)
repaired = [row for row in trials if number(row, "fraction") > 0.0]
if fraction > 0.0 and not repaired:
self.incomplete("certified_repair_trials", reason="No repaired candidates were evaluated")
for index, row in enumerate(repaired):
self.check(f"repaired_polynomial_{index}_certified", row["certificate"] == "certified_nonnegative")
self.outcomes["polynomial"]["prepared_repaired_trials"] = sum(flag(row, "prepared") for row in repaired)
self.outcomes["polynomial"]["descent_repaired_trials"] = sum(number(row, "merit_slope") < 0.0 for row in repaired)
elif repair["status"] != "invalid_base":
self.incomplete("polynomial_repair_available", outcome=repair["status"])
restoration = metrics(self.folder / "polynomial_restoration.csv")
self.restore(restoration,
("accepted_physical_difference", "accepted_normalized_difference", "accepted_residual_difference", "restored_correction_difference"),
("restored_residual_difference",))
def applications(self):
fields = ("direction", "compact_operator", "compact_inverse",
"operator_norm", "operator_error", "operator_relative_error",
"compact_operator_seconds", "root_operator_seconds",
"inverse_norm", "inverse_error", "inverse_relative_error",
"compact_inverse_seconds", "root_inverse_seconds")
rows = read_rows(self.folder / "gravity_applications.csv", fields)
outcome = {"recorded_directions": len(rows), "measurements": [],
"relative_tolerance": APPLICATION_AGREEMENT_TOLERANCE,
"absolute_floor": APPLICATION_AGREEMENT_TOLERANCE,
"inverse_equivalence_assumption": "Default independent material/gravity recipe; not a universal requirement for custom compact inverses"}
self.outcomes["gravity_applications"] = outcome
if not rows:
self.incomplete("gravity_applications_available", reason="No application directions recorded")
return
directions = set()
paths = set()
for row in rows:
direction = int(row["direction"])
if direction < 0 or direction in directions:
raise ValueError("Gravity application direction indices must be unique and nonnegative")
directions.add(direction)
compact_operator = flag(row, "compact_operator")
compact_inverse = flag(row, "compact_inverse")
paths.add((compact_operator, compact_inverse))
measurement = {"direction": direction,
"operator_path": "compact" if compact_operator else "root_restriction",
"inverse_path": "compact" if compact_inverse else "root_restriction"}
for kind in ("operator", "inverse"):
prefix = f"application_{direction}_{kind}"
scale, error, relative = (number(row, f"{kind}_{suffix}") for suffix in ("norm", "error", "relative_error"))
actual_seconds, reference_seconds = (number(row, f"{path}_{kind}_seconds") for path in ("compact", "root"))
self.check(f"{prefix}_finite_nonnegative", all(nonnegative(value) for value in
(scale, error, relative, actual_seconds, reference_seconds)))
# Match the real-FEM fixture's error/max(1, reference norm)
# comparison. Near a null action this is an absolute floor;
# a large reported relative error must not replace this gate.
tolerance = APPLICATION_AGREEMENT_TOLERANCE * max(1.0, scale)
self.check(f"{prefix}_same_action", nonnegative(scale) and nonnegative(error) and error <= tolerance,
error=error, reference_norm=scale, allowed=tolerance)
expected_relative = error / scale if scale > 0.0 else (0.0 if error == 0.0 else math.inf)
self.check(f"{prefix}_relative_error_arithmetic", nonnegative(relative) and
math.isclose(relative, expected_relative, rel_tol=1e-12, abs_tol=1e-30))
measurement[kind] = {"reference_norm": scale, "error": error, "relative_error": relative,
"allowed": tolerance, "selected_seconds": actual_seconds,
"root_seconds": reference_seconds}
outcome["measurements"].append(measurement)
self.check("gravity_application_paths_consistent", len(paths) == 1)
outcome["compact_operator_directions"] = sum(flag(row, "compact_operator") for row in rows)
outcome["compact_inverse_directions"] = sum(flag(row, "compact_inverse") for row in rows)
def gravity(self):
summary = metrics(self.folder / "numerical_strategy_summary.csv")
self.restore(summary, ("accepted_state_change", "accepted_residual_change", "accepted_physical_change"),
("maximum_original_restoration_error",))
inner = read_rows(self.folder / "numerical_strategy_inner.csv", ("kind", "alpha", "index", "status", "converged", "right_hand_side_norm", "true_residual_norm", "relative_true_residual_norm", "threshold"))
lookup = {}
for index, row in enumerate(inner):
key = (row["kind"], number(row, "alpha"), int(row["index"]))
if key in lookup:
raise ValueError(f"Duplicate inner solve record: {key}")
lookup[key] = row
converged = flag(row, "converged")
self.check(f"inner_{index}_status_consistent", (int(row["status"]) == 0) == converged)
if converged:
rhs, residual, threshold = (number(row, key) for key in ("right_hand_side_norm", "true_residual_norm", "threshold"))
self.check(f"inner_{index}_true_defect_gate", all(nonnegative(x) for x in (rhs, residual, threshold)) and residual <= math.nextafter(threshold, math.inf),
true_residual=residual, threshold=threshold)
expected_relative = residual / rhs if rhs > 0 else (0.0 if residual == 0 else math.inf)
self.check(f"inner_{index}_relative_defect", math.isclose(number(row, "relative_true_residual_norm"), expected_relative, rel_tol=1e-12, abs_tol=1e-30))
else:
self.incomplete(f"inner_{index}_solve_available", kind=row["kind"], alpha=number(row, "alpha"),
outcome="numerical_solve_failure", solve_status=int(row["status"]))
self.outcomes["gravity_inner"] = {"recorded_calls": len(inner), "failed_calls": sum(not flag(row, "converged") for row in inner)}
self.curvature(summary, lookup)
self.reduced(summary, lookup)
def curvature(self, summary, lookup):
rows = read_rows(self.folder / "numerical_strategy_curvature.csv", ("alpha", "prepared", "inner_converged", "corrected_prepared", "raw_gravity_remainder", "corrected_gravity_remainder", "gravity_correction_norm", "correction_over_alpha_squared", "retained_state_change"))
if len(rows) != 4 or sorted(number(row, "alpha") for row in rows) != [.001, .01, .1, 1.]:
self.incomplete("curvature_probe_coverage", expected_alphas=[1, .1, .01, .001], recorded_rows=len(rows))
reliable = []
evaluated = 0
for row in rows:
alpha = number(row, "alpha")
if not math.isfinite(alpha) or alpha <= 0:
raise ValueError("A curvature step must be finite and positive")
prepared, solved, corrected = (flag(row, key) for key in ("prepared", "inner_converged", "corrected_prepared"))
self.check(f"curvature_{alpha:g}_stages_consistent", (not solved or prepared) and (not corrected or solved))
if not (prepared and solved and corrected):
self.incomplete(f"curvature_{alpha:g}_corrected_trial_available", raw_prepared=prepared,
inner_converged=solved, corrected_prepared=corrected)
continue
evaluated += 1
solve = lookup[("curvature", alpha, 0)]
self.check(f"curvature_{alpha:g}_inner_record_consistent", flag(solve, "converged"))
raw, actual, correction, coefficient = (number(row, key) for key in ("raw_gravity_remainder", "corrected_gravity_remainder", "gravity_correction_norm", "correction_over_alpha_squared"))
floor = roundoff(*(number(row, key) for key in ("base_residual_norm", "raw_residual_norm", "corrected_residual_norm", "linear_prediction_norm")))
self.check(f"curvature_{alpha:g}_finite_nonnegative", all(nonnegative(x) for x in (raw, actual, correction, coefficient)))
self.check(f"curvature_{alpha:g}_retained_unchanged", number(row, "retained_state_change") == 0.0)
self.check(f"curvature_{alpha:g}_coefficient_arithmetic", math.isclose(coefficient, correction / alpha**2, rel_tol=1e-12, abs_tol=1e-30))
tolerance = number(solve, "threshold") + floor
self.check(f"curvature_{alpha:g}_remainder_cancelled", nonnegative(actual) and actual <= tolerance,
corrected_remainder=actual, allowed=tolerance, raw_remainder=raw)
if alpha <= .1 and raw > 100.0 * floor and correction > 100.0 * floor and number(solve, "threshold") < .01 * raw:
reliable.append((alpha, correction, coefficient))
self.outcomes["curvature"] = {"fully_evaluated_steps": evaluated, "unavailable_steps": len(rows) - evaluated,
"resolved_small_steps": reliable}
if evaluated == 0:
self.incomplete("curvature_cancellation_available", reason="No prepared, solved, corrected trial")
reliable.sort(reverse=True)
if len(reliable) >= 2:
coarse, fine = reliable[-2:]
order = math.log(fine[1] / coarse[1]) / math.log(fine[0] / coarse[0])
self.check("curvature_at_least_second_order_trend", order >= 1.7, observed_order=order,
minimum_test_order=1.7, alphas=[coarse[0], fine[0]],
interpretation="A finite-range trend check, not an asymptotic proof")
else:
self.incomplete("curvature_second_order_trend", reason="Fewer than two small steps above the heuristic arithmetic/solve floor")
def reduced(self, summary, lookup):
tolerance = summary["gravity_completion_tolerance"]
self.check("gravity_completion_tolerance_valid", math.isfinite(tolerance) and tolerance > 0.0)
completions = read_rows(self.folder / "numerical_strategy_completions.csv", ("kind", "alpha", "completed", "final_gravity_norm", "retained_state_change"))
for index, row in enumerate(completions):
self.check(f"completion_{index}_retained_unchanged", number(row, "retained_state_change") == 0.0)
if flag(row, "completed"):
residual = number(row, "final_gravity_norm")
self.check(f"completion_{index}_prepared_gravity_gate", nonnegative(residual) and residual <= tolerance,
final_gravity_norm=residual, tolerance=tolerance)
self.outcomes["gravity_completion"] = {"attempts": len(completions), "completed": sum(flag(row, "completed") for row in completions)}
if summary.get("reduced_base_completed") != 1.0:
self.incomplete("reduced_base_available", reason="Base gravity completion did not reach its prepared-residual tolerance")
return
for kind in ("reduced_action", "reduced_lift"):
if (kind, 0.0, 0) not in lookup or not flag(lookup[kind, 0.0, 0], "converged"):
self.incomplete("reduced_action_available", reason=f"{kind} did not converge")
return
action = summary["reduced_action_norm"]
lifted_g = summary["lifted_gravity_action_norm"]
agreement = summary["lifted_retained_action_difference"]
lift = lookup["reduced_lift", 0.0, 0]
floor = roundoff(action, number(lift, "right_hand_side_norm"))
self.check("lifted_tangent_gravity_gate", nonnegative(lifted_g) and lifted_g <= number(lift, "threshold") + floor,
lifted_gravity_action=lifted_g, allowed=number(lift, "threshold") + floor)
allowed_agreement = 1e-8 * abs(action) + floor
self.check("schur_matches_lifted_full_action", nonnegative(agreement) and agreement <= allowed_agreement,
difference=agreement, allowed=allowed_agreement)
differences = read_rows(self.folder / "numerical_strategy_reduced_derivative.csv", ("alpha", "plus_completed", "minus_completed", "relative_error", "difference_quotient_error", "plus_gravity_norm", "minus_gravity_norm", "residual_subtraction_roundoff_scale"))
reliable = []
valid = []
for row in differences:
if not (flag(row, "plus_completed") and flag(row, "minus_completed")):
self.incomplete(f"reduced_fd_{row['alpha']}_completed_pair_available",
plus_completed=flag(row, "plus_completed"), minus_completed=flag(row, "minus_completed"))
continue
alpha, error, relative, floor = (number(row, key) for key in ("alpha", "difference_quotient_error", "relative_error", "residual_subtraction_roundoff_scale"))
valid.append((alpha, error, relative, floor))
self.check(f"reduced_fd_{alpha:g}_finite", all(nonnegative(x) for x in (error, floor)) and
(nonnegative(relative) or abs(action) <= roundoff(action)))
self.check(f"reduced_fd_{alpha:g}_completed_sides", all(nonnegative(number(row, key)) and number(row, key) <= tolerance for key in ("plus_gravity_norm", "minus_gravity_norm")))
if error > 20.0 * floor:
reliable.append((alpha, error))
self.outcomes["reduced_central_difference"] = {"completed_pairs": len(valid), "measurements": valid}
if not valid:
self.incomplete("reduced_central_difference_available", reason="No pair completed on both sides")
return
self.check("reduced_central_difference_accuracy", any(
(nonnegative(item[2]) and item[2] <= 1e-5) or item[1] <= 20.0 * item[3] for item in valid),
minimum_relative_error=min(item[2] for item in valid), tolerance=1e-5)
reliable.sort(reverse=True)
orders = [math.log(b[1] / a[1]) / math.log(b[0] / a[0]) for a, b in zip(reliable, reliable[1:]) if a[0] != b[0]]
if any(order >= 1.5 for order in orders):
self.check("reduced_central_difference_second_order_trend", True, observed_orders=orders)
elif all(item[1] <= 20.0 * item[3] for item in valid):
self.check("reduced_central_difference_floor_consistent", True,
interpretation="Errors are at the recorded residual-subtraction scale; order is unresolved")
else:
self.incomplete("reduced_central_difference_trend", observed_orders=orders,
reason="No resolved second-order interval; inner completion error has no measured retained-residual amplification bound")
def assess(folder, required=(), expect_negative=False, restoration_tolerance=0.0):
assessment = Assessment(folder, restoration_tolerance)
sections = set(required)
if (folder / "polynomial_certificates.csv").exists() or expect_negative:
sections.add("polynomial")
if (folder / "numerical_strategy_summary.csv").exists():
sections.add("gravity")
if (folder / "gravity_applications.csv").exists():
sections.add("applications")
if not sections:
assessment.incomplete("probe_artifacts_available", reason="No recognized frozen strategy outputs")
for section in sorted(sections):
try:
if section == "polynomial":
assessment.polynomial(expect_negative)
elif section == "gravity":
assessment.gravity()
elif section == "applications":
assessment.applications()
else:
raise ValueError(f"Unknown required probe: {section}")
except FileNotFoundError as error:
assessment.incomplete(f"{section}_artifacts_complete", error=str(error))
except KeyError as error:
assessment.incomplete(f"{section}_records_complete", missing=str(error))
except (ValueError, OSError, csv.Error, ZeroDivisionError) as error:
assessment.check(f"{section}_artifacts_valid", False, error=str(error))
statuses = {item["status"] for item in assessment.checks}
status = "fail" if "fail" in statuses else "incomplete" if "incomplete" in statuses else "pass"
report = {"schema_version": 1, "result_folder": str(folder.resolve()), "status": status,
"checks": assessment.checks, "outcomes": assessment.outcomes,
"scope": "Frozen algebra, admissibility, and restoration checks; use check_plateau_physics.py for equilibrium/virial acceptance"}
return clean_json(report), {"pass": 0, "incomplete": 2, "fail": 3}[status]
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("result_folder", type=Path)
parser.add_argument("--require", choices=("polynomial", "gravity", "applications"), action="append", default=[])
parser.add_argument("--expect-negative-base", action="store_true")
parser.add_argument("--restoration-tolerance", type=float, default=0.0)
args = parser.parse_args()
if not nonnegative(args.restoration_tolerance):
parser.error("--restoration-tolerance must be finite and nonnegative")
report, code = assess(args.result_folder, args.require, args.expect_negative_base, args.restoration_tolerance)
print(json.dumps(report, indent=2, allow_nan=False))
return code
if __name__ == "__main__":
sys.exit(main())

View File

@@ -0,0 +1,101 @@
# Checking numerical-strategy experiments
Run the checker on each completed frozen-probe directory:
```sh
python3 experiments/check_numerical_strategies.py RESULT_FOLDER --require gravity
python3 experiments/check_numerical_strategies.py RESULT_FOLDER --require applications
python3 experiments/check_numerical_strategies.py RESULT_FOLDER --require polynomial
python3 experiments/check_numerical_strategies.py LATE_ROTATING_FOLDER --require polynomial --expect-negative-base
python3 experiments/test_check_numerical_strategies.py
```
Polynomial, gravity-strategy, and gravity-application sections are discovered
automatically when their CSV files exist. Repeating `--require` demands each
named section. Older campaigns without `gravity_applications.csv` remain valid
unless `--require applications` is supplied. Exit 0 means the requested checks passed;
3 means an invariant or numerical expectation failed; 2 means evidence is
incomplete. An honestly reported failed inner solve, unavailable trial, or
unresolved certificate must not turn into a passing verification. Expected
negative-base detection and rejection are successful guard tests, not successful
equilibrium solves.
Accepted state, residual, physical state, saved correction, and retained-coordinate
changes must be exactly zero. Restored residual drift defaults to exactly zero;
`--restoration-tolerance` relaxes only that comparison when explicitly justified.
The JSON output records the chosen tolerance.
For successful curvature probes, the checker compares the fresh gravity remainder
with the selected inner threshold plus a documented arithmetic scale, verifies
that only gravity changed, and checks correction/alpha² arithmetic. It requires
two small steps resolved above that scale to assess a second-order trend. An
observed order of at least 1.7 passes the finite-range trend check; this does not
prove an asymptotic rate. Higher order is allowed because a quadratic coefficient
can vanish.
Reduced probes must satisfy the freshly prepared gravity completion tolerance,
the lifted gravity tangent gate, and agreement of the Schur action with the
retained part of the full lifted action. Central differences must reach relative
error at most 1e-5 or an absolute error within the recorded residual-subtraction
scale. They must also show a resolved interval with order at least 1.5, or reach
that scale. Relative error is not meaningful for a null action. A plateau above that scale is incomplete
evidence rather than an automatic claim of a bad Jacobian: the retained-residual
amplification of the remaining gravity error has not been bounded. The recorded
roundoff scales are heuristics, not rigorous forward-error bounds.
When `gravity_applications.csv` is present, every recorded direction must satisfy
compact-versus-root normalized operator agreement and the default fixture's
inverse agreement. The gate matches the real-FEM test:
`error <= 2e-12 * max(1, reference_norm)`, a relative tolerance with an absolute
floor for small actions. Norms, absolute/relative errors, and both application
times must be finite and nonnegative; relative-error columns must also agree
with the absolute measurements. The reported compact/fallback flags must be
valid and consistent across this one prepared subsystem's directions. Fallback
is a valid reported outcome, including for custom recipes. An empty set of
directions or a missing explicitly required file is incomplete evidence.
Inverse equality is an expectation for the default independent material/gravity
recipe used by these fixtures, not a mathematical requirement on every possible
custom compact preconditioner. A custom inverse deliberately different from the
root restriction needs its own comparison expectation; this checker must not
be cited as accepting that difference. Operator equality always remains required
because both paths must apply the same equations and normalization. The JSON
retains the selected paths and separate application times without imposing a
speedup threshold.
This script deliberately does not duplicate physical acceptance. For each
end-to-end model, run `check_plateau_physics.py` on its endpoint. That separate
gate requires recorded strict nonlinear convergence and all eight defined virial
measurements at or below 1e-5. Its local EOS, hydrostatic, and sign measurements
remain part of the physical assessment.
## Bounded validation matrix
These are proposed operational limits, not measured performance predictions.
Use one numerical process at a time and preserve all capped failures as results.
| Layer | Cases | Bound / acceptance |
|---|---|---|
| Algebra and lifecycle | Gravity subsystem, Schur reduction, polynomial certificate tests; one and two MPI ranks | 2 minutes per test group; true-defect, stale-state, empty-local, rollback, type-contract coverage |
| Python checker | Synthetic passing, false-convergence, mutation, missing-data, negative-base, compact/fallback agreement, and NaN records | 30 seconds; standard-library unit tests |
| Positivity frozen states | n=1 J=0.1 captured iteration 2 and iteration 11; a certified seed/control | 10 minutes per probe; iteration 11 must be negative and reject repair with `invalid_base`; no claim that the earlier base is positive before checking it |
| Gravity curvature | n=1.5 J=0 captured iteration 1 | 15 minutes; alpha = 1, 0.1, 0.01, 0.001; gate fresh remainder cancellation and small-step order |
| Reduced gravity | Same n=1.5 state, plus constrained n=3 saved seed direction | 15 minutes per probe; completion and four central-difference pairs; n=3 direction remains an approximate diagnostic correction |
| Regression equilibrium | n=1 J=0 and low-rotation J=0.05 baseline; opt-in strategies individually | Preserve existing nonlinear/linear caps, add a 20-minute wall limit per model; strict solver and all virial gates remain mandatory |
| Failure-prone equilibrium | n=1 J=0.1 and n=1.5 J=0, strategies separately before combinations | 8 Newton steps / 20 minutes; report residual progress, auxiliary work, rejection causes, and physical endpoint without equating the cap with convergence |
At the supplied frozen-gravity defaults, there are at most 24 explicitly requested
inner solves, each capped at 160 iterations, and at most 42 preparations in the
normal completed path. The maximum covers four curvature corrections, nine
gravity completions with up to two corrections each, and two reduced actions.
Rejected preparations can reduce those counts. Root integration controls and
end-to-end outer solves are separately bounded; their nested work is not covered
by this frozen-probe count.
The completed n=1.5 frozen campaign passed all 124 algebraic and invariant
checks, including the four-pair resolved central-difference trend and compact
application comparisons. The checker regression suite passed 18 Python tests.
These results do not replace physical acceptance of an end-to-end model.
Treat outer reduced-solve time as inclusive of nested gravity solves. Report the
inner counters separately, but do not add the two times as if they were disjoint.

View File

@@ -0,0 +1,203 @@
#!/usr/bin/env python3
"""Report a plateau endpoint and gate strict solver convergence plus eight virials.
Usage: check_plateau_physics.py RESULT_FOLDER
Exit 0: solver_and_virial_milestone passes. Exit 3: it does not pass.
Exit 2: required endpoint data is missing or malformed. Standard-library only.
Local errors remain measurements; passing this gate is not full physical validation.
"""
import argparse
import csv
import json
import math
from pathlib import Path
import sys
THRESHOLD = 1.0e-5
QUADRATURES = (14, 18)
VIRIALS = {
"pressure_from_enthalpy_energy": "enthalpy_virial_error",
"pressure_from_enthalpy_force": "enthalpy_force_virial_error",
"pressure_from_density_energy": "virial_error",
"pressure_from_density_force": "force_virial_error",
}
SIGN_METRICS = (
"minimum_density", "maximum_density", "negative_density_samples",
"negative_density_mass_fraction", "negative_density_volume_fraction",
"minimum_enthalpy", "maximum_enthalpy", "negative_enthalpy_samples",
"negative_enthalpy_volume_fraction",
)
CONSERVATION_METRICS = (
"mass", "mass_absolute_error", "angular_momentum_z", "angular_momentum_absolute_error",
)
LOCAL_METRICS = (
"eos_density_mismatch_maximum", "eos_density_mismatch_maximum_scaled",
"eos_density_mismatch_rms", "eos_density_mismatch_rms_scaled",
"bernoulli_raw_rms", "bernoulli_raw_rms_scaled",
"bernoulli_mean_subtracted_rms", "bernoulli_mean_subtracted_rms_scaled",
"bernoulli_sampled_range", "hydrostatic_gradient_rms",
)
PRESSURE_METRICS = (
"pressure_from_density_defined_everywhere", "pressure_integral",
"pressure_from_enthalpy_defined_everywhere", "enthalpy_pressure_integral",
)
REQUIRED_METRICS = (
*VIRIALS.values(), *SIGN_METRICS, *CONSERVATION_METRICS,
*LOCAL_METRICS, *PRESSURE_METRICS, "complete_volume_measurement",
)
def measurement(value):
"""Keep JSON standard-compliant without losing the reason for a null value."""
result = {"value": value if math.isfinite(value) else None, "finite": math.isfinite(value)}
if not result["finite"]:
result["nonfinite_value"] = "nan" if math.isnan(value) else ("+inf" if value > 0 else "-inf")
return result
def read_metadata(path):
result = {}
for line in path.read_text().splitlines():
if not line.strip():
continue
if "=" not in line:
raise ValueError(f"Malformed metadata line in {path}: {line!r}")
key, value = line.split("=", 1)
if not key or key in result:
raise ValueError(f"Empty or duplicate metadata key in {path}: {key!r}")
result[key] = value
if result.get("converged") not in ("0", "1"):
raise ValueError("metadata.txt must contain a completed converged=0 or converged=1 result")
if "accepted_steps" not in result or int(result["accepted_steps"]) < 0:
raise ValueError("metadata.txt must contain a nonnegative accepted_steps count")
return result
def read_physical(path):
result = {q: {} for q in QUADRATURES}
with path.open(newline="") as stream:
reader = csv.DictReader(stream)
if reader.fieldnames != ["quadrature", "metric", "value"]:
raise ValueError("final_physical.csv requires the header quadrature,metric,value")
for row in reader:
if None in row or any(value is None for value in row.values()):
raise ValueError("Malformed row in final_physical.csv")
q = int(row["quadrature"])
if q not in result:
continue
key = row["metric"]
if not key or key in result[q]:
raise ValueError(f"Empty or duplicate physical metric at quadrature {q}: {key!r}")
result[q][key] = float(row["value"])
for q, values in result.items():
missing = [key for key in REQUIRED_METRICS if key not in values]
if missing:
raise ValueError(f"Missing quadrature {q} endpoint metrics: {', '.join(missing)}")
for key in ("complete_volume_measurement", "pressure_from_density_defined_everywhere",
"pressure_from_enthalpy_defined_everywhere"):
if values[key] not in (0.0, 1.0):
raise ValueError(f"Invalid boolean metric at quadrature {q}: {key}")
for key in VIRIALS.values():
if math.isfinite(values[key]) and values[key] < 0:
raise ValueError(f"A virial error must be nonnegative: quadrature {q}, {key}")
return result
def pressure_report(values, kind):
flag = values[f"pressure_from_{kind}_defined_everywhere"] == 1.0
integral = values["pressure_integral" if kind == "density" else "enthalpy_pressure_integral"]
return {
"defined_at_all_samples": flag,
"integral": measurement(integral),
"valid": flag and math.isfinite(integral),
}
def negative_samples_detected(values, kind):
minimum = values[f"minimum_{kind}"]
count = values[f"negative_{kind}_samples"]
if not math.isfinite(minimum) or not math.isfinite(count):
return None
return minimum < 0.0 or count > 0.0
def assess(folder):
meta = read_metadata(folder / "metadata.txt")
physical = read_physical(folder / "final_physical.csv")
per_quadrature = {}
all_virials_pass = True
for q, values in physical.items():
complete = values["complete_volume_measurement"] == 1.0
pressure = {kind: pressure_report(values, kind) for kind in ("enthalpy", "density")}
virials = {}
for name, key in VIRIALS.items():
value = values[key]
kind = "density" if "density" in name else "enthalpy"
check = measurement(value)
if not complete or not pressure[kind]["valid"] or not math.isfinite(value):
check["status"] = "undefined"
check["reason"] = (
"incomplete_volume_measurement" if not complete else
"pressure_not_defined_or_finite" if not pressure[kind]["valid"] else
"nonfinite_virial"
)
else:
check["status"] = "pass" if value <= THRESHOLD else "fail"
all_virials_pass = all_virials_pass and check["status"] == "pass"
virials[name] = check
per_quadrature[str(q)] = {
"complete_volume_measurement": complete,
"virials": virials,
"pressure": pressure,
"sampled_signs": {
"negative_density_detected": negative_samples_detected(values, "density"),
"negative_enthalpy_detected": negative_samples_detected(values, "enthalpy"),
**{key: measurement(values[key]) for key in SIGN_METRICS},
},
"conservation": {key: measurement(values[key]) for key in CONSERVATION_METRICS},
"local_measurements_without_acceptance_tolerances": {
key: measurement(values[key]) for key in LOCAL_METRICS
},
}
strict_converged = meta["converged"] == "1"
passed = strict_converged and all_virials_pass
report = {
"schema_version": 1,
"result_folder": str(folder.resolve()),
"solver_and_virial_milestone": "pass" if passed else "fail",
"strict_solver": {
"converged": strict_converged,
"accepted_steps": int(meta["accepted_steps"]),
"failure": meta.get("failure"),
"absolute_tolerance": meta.get("atol"),
"relative_tolerance": meta.get("rtol"),
},
"virial_threshold": THRESHOLD,
"all_eight_virial_checks_pass": all_virials_pass,
"quadratures": per_quadrature,
"interpretation": [
"The milestone requires strict recorded solver convergence and all four defined, finite virial errors <= 1e-5 at both quadratures.",
"The milestone is not full physical validation. Mass/J errors and local EOS/Bernoulli measurements have no acceptance tolerances here.",
"Density and enthalpy signs are quadrature samples; sampled extrema and local errors are not certified pointwise bounds.",
"An undefined pressure-from-density virial is kept separate from a finite virial that exceeds the threshold.",
],
}
return report, 0 if passed else 3
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("result_folder", type=Path)
args = parser.parse_args()
try:
report, code = assess(args.result_folder)
except (OSError, ValueError, csv.Error) as error:
report, code = {"schema_version": 1, "input_error": str(error)}, 2
print(json.dumps(report, indent=2, allow_nan=False))
return code
if __name__ == "__main__":
sys.exit(main())

View File

@@ -0,0 +1,36 @@
# Plateau endpoint milestone checker
Run the standalone standard-library script with one completed result folder:
```sh
python3 experiments/check_plateau_physics.py /absolute/path/to/plateau-result
```
It reads `metadata.txt` and `final_physical.csv` and prints standard JSON. Exit codes:
- **0:** `solver_and_virial_milestone=pass`: recorded strict solver convergence and all eight defined, finite virial errors at or below 1e-5.
- **3:** those milestone checks do not all pass, including an undefined pressure integral.
- **2:** missing or malformed required endpoint data, including an incomplete quadrature table or missing convergence outcome.
The eight checks comprise energy and force virials with both P(h) and P(rho), each at quadrature orders 14 and 18. An undefined check is distinguished from a finite check exceeding the threshold. Pressure validity, density/enthalpy signs, negative-density budgets, mass/J errors, and local EOS/Bernoulli measurements are reported separately. Nonfinite numbers become JSON null with a retained finite flag and NaN/infinity classification.
This joint solver-and-eight-virial screen is deliberately stricter than the primary
physical milestone of virial balance within 1e-5. The n=1.5 endpoints meet that
milestone using P(h); an undefined P(rho) caused by small signed DG undershoot
does not by itself demonstrate a physical virial failure. The JSON keeps those
individual outcomes separate from its conservative aggregate result.
Passing this gate is **not full physical validation**. No new tolerance is assigned to mass/J or local errors. Sampled signs and extrema are not certified pointwise bounds. The script trusts the diagnostic's recorded convergence flag and physical measurements; it does not reconstruct a model, validate provenance, or independently recompute integrals. It does not inspect or modify production code.
Verification on the September 16 campaign:
| Completed case | Expected and observed exit | Distinction checked |
| --- | ---: | --- |
| n=1, J=0.05, no central constraint, restart 160 | 0 | Strict convergence and all virials pass |
| Same model, restart 40 | 3 | Virials pass, strict convergence fails |
| n=1.5, J=0, no central constraint, restart 160 | 3 | P(h) virials pass; P(rho) is undefined |
| n=3 initial seed | 3 | P(h) virials exceed the threshold |
Threshold equality, one virial just above threshold, and missing required data
were also checked. Detailed verification JSON and reports remain with the raw
campaign artifacts in the audit workspace.

View File

@@ -0,0 +1,371 @@
#!/usr/bin/env python3
"""Audit frozen preconditioner artifacts and compare equal-accuracy solve costs.
A completed experiment is valid even when neither inverse reaches the requested
linear tolerance. Those observations must survive the audit, without acquiring
an invented time-to-convergence speedup.
"""
import argparse
import csv
import hashlib
import json
import math
from pathlib import Path
REQUIRED_ARTIFACTS = {
'metadata.txt', 'layout.csv', 'preconditioner_summary.csv', 'preconditioner_actions.csv',
'preconditioner_blocks.csv', 'preconditioner_correction_blocks.csv', 'preconditioner_history.csv',
'preconditioner_invariants.csv', 'preconditioner_reference.csv', 'preconditioner_scope.txt',
'benchmark_physical_base.txt', 'benchmark_normalized_base.txt', 'benchmark_normalized_rhs.txt',
'benchmark_state_factors.txt', 'benchmark_residual_factors.txt',
'benchmark_invariant_direction.txt', 'benchmark_invariant_action.txt',
'context_reference_normalized_correction.txt',
} | {role + suffix for role in ('baseline', 'candidate') for suffix in (
'_normalized_correction.txt', '_physical_correction.txt',
'_normalized_linear_defect.txt', '_physical_linear_defect.txt')}
COARSE_VARIANTS = {'coupled-shape-coarse', 'gravity-schur-coarse'}
def digest(path):
return hashlib.sha256(path.read_bytes()).hexdigest()
def hash_matches(path, expected):
return path.is_file() and digest(path) == expected
def rows(path):
with path.open() as stream:
return list(csv.DictReader(stream))
def vector(path):
values = path.read_text().split()
if not values:
raise ValueError(f'Empty vector: {path}')
count = int(values[0])
result = [float(v) for v in values[1:]]
if count <= 0 or count != len(result) or not all(math.isfinite(v) for v in result):
raise ValueError(f'Invalid finite vector: {path}')
return result
def norm(values):
return math.sqrt(math.fsum(v * v for v in values))
def close(left, right):
return math.isfinite(left) and math.isfinite(right) and math.isclose(left, right, rel_tol=2e-12, abs_tol=1e-28)
def ratio(numerator, denominator):
# Exact residual zero is a valid outcome. Do not invent a finite ratio or
# serialize infinity when the comparison denominator is exactly zero.
return numerator / denominator if denominator > 0 else None
def invalidate_comparison(result):
comparison = result['comparison']
comparison['comparison_valid'] = False
comparison['outcome'] = 'invalid_artifacts'
for key in ('candidate_over_baseline_defect', 'candidate_over_baseline_measured_cost',
'equal_gate_speedup', 'effective_base_equal_gate_speedup'):
comparison[key] = None
def invalid_case(error):
result = {'passed': False, 'checks': [{'check': 'readable_complete_artifacts', 'passed': False,
'error': str(error)}], 'comparison': {}}
invalidate_comparison(result)
return result
def inspect_case(folder):
try:
return inspect_case_artifacts(folder)
except (OSError, ValueError, KeyError, TypeError, OverflowError, ZeroDivisionError) as error:
return invalid_case(error)
def inspect_coarse(folder, by_role, check):
coarse_roles = {role for role, row in by_role.items() if row['variant'] in COARSE_VARIANTS}
if not coarse_roles:
return {}
records = rows(folder / 'preconditioner_coarse.csv')
check('coarse_only_requested_roles', {r['role'] for r in records} == coarse_roles)
report = {}
stage_names = ('constructed', 'before_krylov', 'after_krylov')
stable_names = {
'input_modes', 'independent_modes', 'active_modes', 'fallback',
'minimum_overlap_lower_bound', 'reciprocal_overlap_condition',
'setup_jacobian_applications', 'setup_inverse_applications', 'setup_seconds',
'persistent_vector_bytes',
}
counter_names = {'applications', 'inverse_applications', 'failed_applications'}
construction_names = {'physical_inverse_construction_seconds', 'basis_construction_seconds',
'complete_coarse_construction_seconds'}
fallback_names = {0: 'none', 1: 'no_independent_modes', 2: 'insufficient_subspace_overlap'}
for role in coarse_roles:
row = by_role[role]
prefix = role + '_coarse_'
selected = [r for r in records if r['role'] == role]
check(prefix + 'variant_matches', all(r['variant'] == row['variant'] for r in selected))
check(prefix + 'unique_metrics', len(selected) == len({(r['stage'], r['metric']) for r in selected}))
stages = {name: {r['metric']: r['value'] for r in selected if r['stage'] == name}
for name in (*stage_names, 'validation')}
check(prefix + 'known_stages', {r['stage'] for r in selected} == set(stages))
for stage in stage_names:
check(prefix + stage + '_complete', stable_names | counter_names <= stages[stage].keys())
constructed = stages['constructed']
check(prefix + 'construction_components_recorded', construction_names <= constructed.keys())
counts = {name: int(constructed[name]) for name in (
'input_modes', 'independent_modes', 'active_modes', 'fallback',
'setup_jacobian_applications', 'setup_inverse_applications', 'persistent_vector_bytes')}
input_modes, independent, active, fallback = (counts[name] for name in
('input_modes', 'independent_modes', 'active_modes', 'fallback'))
check(prefix + 'consistent_mode_counts', 0 <= active <= independent <= input_modes)
check(prefix + 'consistent_fallback',
(fallback == 0 and active == independent and active > 0) or
(fallback == 1 and independent == active == 0) or
(fallback == 2 and independent > 0 and active == 0))
setup_inverse, setup_jacobian = (counts[name] for name in
('setup_inverse_applications', 'setup_jacobian_applications'))
check(prefix + 'consistent_setup_work', independent <= setup_inverse <= input_modes and
2 * setup_inverse <= setup_jacobian <= input_modes + setup_inverse and
counts['persistent_vector_bytes'] > 0)
for stage in stage_names:
# NaN overlap estimates are expected when rank rejection prevents
# forming a coarse system. Preserve their strings in the report.
check(prefix + stage + '_unchanged_preparation', all(
float(stages[stage][name]) == float(constructed[name]) or
(math.isnan(float(stages[stage][name])) and math.isnan(float(constructed[name])))
for name in stable_names))
calls = int(stages[stage]['applications'])
inverse_calls = int(stages[stage]['inverse_applications'])
check(prefix + stage + '_successful_applications', calls >= 0 and inverse_calls == calls and
int(stages[stage]['failed_applications']) == 0)
check(prefix + 'constructed_without_applications', int(constructed['applications']) == 0)
check(prefix + 'all_active_modes_checked', int(stages['before_krylov']['applications']) == active + 1)
check(prefix + 'solve_work_matches', int(stages['after_krylov']['applications']) -
int(stages['before_krylov']['applications']) == int(row['preconditioner_applications']))
if fallback == 0:
check(prefix + 'usable_overlap', all(math.isfinite(float(constructed[name])) and
float(constructed[name]) > 0 for name in
('minimum_overlap_lower_bound', 'reciprocal_overlap_condition')) and
float(constructed['minimum_overlap_lower_bound']) >= 1e-8)
elif fallback == 2:
overlap = float(constructed['minimum_overlap_lower_bound'])
check(prefix + 'overlap_fallback_reason', not math.isfinite(overlap) or overlap < 1e-8)
times = {name: float(constructed[name]) for name in construction_names | {'setup_seconds'}}
check(prefix + 'finite_nonnegative_construction_times', all(math.isfinite(v) and v >= 0 for v in times.values()))
check(prefix + 'complete_coarse_construction_cost', times['complete_coarse_construction_seconds'] + 1e-8 >=
times['basis_construction_seconds'] + times['setup_seconds'])
check(prefix + 'physical_and_coarse_cost_included', close(float(row['construction_seconds']),
times['physical_inverse_construction_seconds'] + times['complete_coarse_construction_seconds']))
error = float(stages['validation']['maximum_exact_coarse_relative_error'])
check(prefix + 'exact_subspace_error_within_tolerance', math.isfinite(error) and 0 <= error <= 1e-8)
check(prefix + 'empty_validation_is_vacuous', active > 0 or error == 0)
# An empty validation loop reports zero by construction. It proves no
# coarse identity and cannot substantiate a coarse-method speedup.
refined_base = row['variant'] == 'gravity-schur-coarse' and int(row['schur_correction_sweeps']) > 0
effective_base = 'gravity-schur' if refined_base else 'independent'
report[role] = {
'active': active > 0, 'input_modes': input_modes, 'independent_modes': independent,
'active_modes': active, 'fallback_code': fallback,
'fallback': fallback_names.get(fallback, 'invalid'),
'exact_subspace_validation': ('verified' if math.isfinite(error) and 0 <= error <= 1e-8
else 'failed') if active > 0 else 'not_applicable_empty_subspace',
'maximum_exact_coarse_relative_error': stages['validation']['maximum_exact_coarse_relative_error'],
'effective_base_variant': effective_base,
'effective_method': row['variant'] if active > 0 else effective_base,
'method_status': 'active_coarse' if active > 0 else
'baseline_fallback' if effective_base == 'independent' else 'gravity_schur_fallback',
'recorded_stages': stages,
'timing_scope': 'Construction includes physical inverse, basis, and coarse setup. '
'Extra exact-subspace checks are diagnostics outside solve totals.',
}
return report
def inspect_case_artifacts(folder):
checks = []
def check(name, result):
checks.append({'check': name, 'passed': bool(result)})
summary = rows(folder / 'preconditioner_summary.csv')
check('exactly_one_baseline_and_candidate', len(summary) == 2 and {r['role'] for r in summary} == {'baseline', 'candidate'})
by_role = {r['role']: r for r in summary}
rhs = vector(folder / 'benchmark_normalized_rhs.txt')
rhs_norm = norm(rhs)
check('finite_nonzero_rhs', math.isfinite(rhs_norm) and rhs_norm > 0)
layout = rows(folder / 'layout.csv')
residual_blocks = [r for r in layout if r['kind'] == 'residual']
covered = []
for row in residual_blocks:
covered.extend(range(int(row['offset']), int(row['offset']) + int(row['size'])))
check('residual_layout_covers_vector_once', covered == list(range(len(rhs))))
invariants = rows(folder / 'preconditioner_invariants.csv')
required = {'accepted_physical_bitwise_identical', 'accepted_normalized_bitwise_identical',
'accepted_residual_bitwise_identical', 'correction_bitwise_identical',
'trial_state_bitwise_identical', 'trial_residual_bitwise_identical',
'candidate_physical_bitwise_identical', 'state_factors_bitwise_identical',
'residual_factors_bitwise_identical', 'preparation_generation_unchanged',
'normalized_operator_current', 'jacobian_action_bitwise_identical'}
for role in ('context_reference', 'baseline', 'candidate'):
role_rows = [r for r in invariants if r['role'] == role]
metrics = {r['metric']: float(r['value']) for r in role_rows}
check(role + '_unique_invariants', len(role_rows) == len(metrics))
check(role + '_all_invariants_recorded', required <= metrics.keys())
check(role + '_all_invariants_pass', all(metrics.get(name) == 1.0 for name in required))
check(role + '_exact_jacobian_unchanged', metrics.get('jacobian_action_difference_norm') == 0.0)
action_rows = rows(folder / 'preconditioner_actions.csv')
check('action_checks_present', len(action_rows) == 2 and
{row['role'] for row in action_rows} == {'baseline', 'candidate'})
for row in action_rows:
measured = by_role[row['role']]
expected = measured['variant'] == 'independent' or (
measured['variant'] == 'gravity-schur' and int(measured['schur_correction_sweeps']) == 0)
check(row['role'] + '_action_variant_matches', row['variant'] == by_role[row['role']]['variant'])
check(row['role'] + '_equivalence_requirement_recorded',
row['context_equivalence_required'] == ('1' if expected else '0'))
if expected:
difference = float(row['context_action_relative_difference'])
check(row['role'] + '_fresh_inverse_matches_default',
math.isfinite(difference) and 0 <= difference <= 256 * 2.220446049250313e-16)
check('baseline_is_independent', by_role['baseline']['variant'] == 'independent')
block_rows = rows(folder / 'preconditioner_blocks.csv')
for role, row in by_role.items():
defect = vector(folder / (role + '_normalized_linear_defect.txt'))
solution = vector(folder / (role + '_normalized_correction.txt'))
true_norm = norm(defect)
check(role + '_compatible_vector_sizes', len(defect) == len(rhs) == len(solution))
check(role + '_rhs_norm', close(float(row['rhs_norm']), rhs_norm))
check(role + '_defect_norm', close(float(row['true_residual_norm']), true_norm))
check(role + '_relative_defect', close(float(row['true_relative']), true_norm / rhs_norm))
check(role + '_solution_norm', close(float(row['normalized_correction_norm']), norm(solution)))
target = float(row['relative_tolerance']) * rhs_norm
check(role + '_valid_positive_tolerance', math.isfinite(target) and target > 0)
check(role + '_unchanged_target', close(float(row['absolute_target']), target))
check(role + '_valid_gate_flag', row['true_gate_pass'] in ('0', '1'))
check(role + '_honest_gate', (row['true_gate_pass'] == '1') == (true_norm <= target))
check(role + '_cold_start', close(float(row['reported_initial_norm']), rhs_norm))
check(role + '_iteration_count', int(row['iterations']) == int(row['preconditioner_applications'])
and 0 < int(row['iterations']) <= int(row['maximum_iterations']))
timing_names = ['construction_seconds', 'normalization_binding_seconds', 'krylov_setup_seconds', 'krylov_seconds']
check(role + '_valid_timing', all(math.isfinite(float(row[k])) and float(row[k]) >= 0 for k in timing_names))
check(role + '_complete_setup_solve_cost', close(float(row['setup_plus_solve_seconds']), sum(float(row[k]) for k in timing_names)))
extra_timings = ['true_check_seconds', 'jacobian_seconds', 'preconditioner_seconds']
check(role + '_valid_verification_application_timing',
all(math.isfinite(float(row[k])) and float(row[k]) >= 0 for k in extra_timings))
full_cost = float(row['setup_solve_and_true_check_seconds'])
check(role + '_complete_verified_solve_cost', full_cost > 0 and
close(full_cost, float(row['setup_plus_solve_seconds']) + float(row['true_check_seconds'])))
check(role + '_one_independent_true_check', int(row['true_check_jacobian_applications']) == 1)
check(role + '_nonoverlapping_application_timers',
float(row['jacobian_seconds']) + float(row['preconditioner_seconds']) <= float(row['krylov_seconds']) + 1e-8)
role_blocks = [r for r in block_rows if r['role'] == role]
recorded = {r['block']: r for r in role_blocks}
check(role + '_unique_residual_blocks', len(role_blocks) == len(recorded))
check(role + '_all_residual_blocks_present', set(recorded) == {b['block'] for b in residual_blocks})
for block in residual_blocks:
start, count = int(block['offset']), int(block['size'])
measured = recorded[block['block']]
check(role + '_' + block['block'] + '_defect_norm',
close(float(measured['normalized_defect_norm']), norm(defect[start:start + count])))
check(role + '_' + block['block'] + '_rhs_norm',
close(float(measured['normalized_rhs_norm']), norm(rhs[start:start + count])))
baseline, candidate = by_role['baseline'], by_role['candidate']
coarse = inspect_coarse(folder, by_role, check)
for key in ('restart', 'maximum_iterations', 'relative_tolerance', 'rhs_norm', 'absolute_target'):
check('matched_' + key, baseline[key] == candidate[key])
both_pass = baseline['true_gate_pass'] == candidate['true_gate_pass'] == '1'
outcome = 'both_pass' if both_pass else ('candidate_only_pass' if candidate['true_gate_pass'] == '1'
else 'baseline_only_pass' if baseline['true_gate_pass'] == '1' else 'neither_passes')
comparison = {'outcome': outcome, 'recorded_gate_outcome': outcome, 'comparison_valid': True,
'candidate_over_baseline_defect': ratio(float(candidate['true_relative']), float(baseline['true_relative'])),
'candidate_over_baseline_measured_cost': ratio(float(candidate['setup_solve_and_true_check_seconds']), float(baseline['setup_solve_and_true_check_seconds'])),
'equal_gate_speedup': float(baseline['setup_solve_and_true_check_seconds']) / float(candidate['setup_solve_and_true_check_seconds']) if both_pass else None,
'effective_base_equal_gate_speedup': None,
'baseline': baseline, 'candidate': candidate, 'coarse': coarse}
if 'candidate' in coarse and not coarse['candidate']['active']:
if coarse['candidate']['effective_base_variant'] == 'gravity-schur':
comparison['effective_base_equal_gate_speedup'] = comparison['equal_gate_speedup']
comparison['equal_gate_speedup'] = None
result = {'passed': all(c['passed'] for c in checks), 'checks': checks, 'comparison': comparison}
if not result['passed']:
invalidate_comparison(result)
return result
def inspect_campaign(campaign):
provenance = json.loads((campaign / 'provenance.json').read_text())
checks = [{'check': 'immutable_executable_hash', 'passed': hash_matches(campaign / 'plateau_diagnostic', provenance['binary_sha256'])},
{'check': 'mesh_hash', 'passed': hash_matches(Path(provenance['mesh']), provenance['mesh_sha256'])},
{'check': 'nonempty_unique_cases', 'passed': bool(provenance['cases']) and
len(provenance['cases']) == len({case['id'] for case in provenance['cases']})}]
results = {}
for case in provenance['cases']:
name = case['id']
record = json.loads((campaign / (name + '_run.json')).read_text())
checks.append({'check': name + '_completed', 'passed': bool(record.get('finished_utc')) and
record.get('exit_code') == 0 and not record.get('timed_out', False)})
checks.append({'check': name + '_required_outputs_hashed',
'passed': REQUIRED_ARTIFACTS <= record.get('output_hashes', {}).keys()})
arguments = case.get('arguments', [])
expected_inputs = set()
for index, argument in enumerate(arguments):
if argument in ('--probe-state', '--probe-direction', '--replay-candidate'):
path = Path(arguments[index + 1])
if not path.is_absolute(): path = Path(provenance['source']) / path
expected_inputs.add(str(path.resolve()))
checks.append({'check': name + '_required_inputs_hashed',
'passed': expected_inputs <= record.get('input_state_hashes', {}).keys()})
for path, expected in record.get('input_state_hashes', {}).items():
checks.append({'check': name + '_input_hash_' + path, 'passed': hash_matches(Path(path), expected)})
for path, expected in record.get('output_hashes', {}).items():
checks.append({'check': name + '_output_hash_' + path, 'passed': hash_matches(campaign / name / path, expected)})
results[name] = inspect_case(campaign / name)
candidate = results[name]['comparison'].get('candidate', {})
requested_variant = (arguments[arguments.index('--preconditioner-variant') + 1]
if '--preconditioner-variant' in arguments else 'independent')
if requested_variant in COARSE_VARIANTS or candidate.get('variant') in COARSE_VARIANTS:
checks.append({'check': name + '_coarse_report_hashed',
'passed': 'preconditioner_coarse.csv' in record.get('output_hashes', {})})
if '--preconditioner-variant' in arguments:
expected_variant = arguments[arguments.index('--preconditioner-variant') + 1]
checks.append({'check': name + '_requested_variant', 'passed': candidate.get('variant') == expected_variant})
passed = all(c['passed'] for c in checks) and all(r['passed'] for r in results.values())
if not all(c['passed'] for c in checks):
# A valid-looking CSV cannot substantiate a speedup when its producing
# executable or input/output provenance failed verification.
for result in results.values():
result['passed'] = False
invalidate_comparison(result)
assessment = {'passed': passed, 'source_commit': provenance['commit'], 'provenance_checks': checks, 'cases': results,
'scope': 'Frozen linear-solve comparison only. A failed baseline has no finite equal-gate speedup.'}
return assessment
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('campaign', type=Path)
parser.add_argument('--output', type=Path)
args = parser.parse_args()
campaign = args.campaign.resolve()
assessment = inspect_campaign(campaign)
path = args.output or campaign / 'preconditioner_assessment.json'
path.write_text(json.dumps(assessment, indent=2, allow_nan=False) + '\n')
for name, result in assessment['cases'].items():
c = result['comparison']
print(name, 'PASS' if result['passed'] else 'FAIL', c['outcome'],
'defect_ratio=', c['candidate_over_baseline_defect'], 'equal_gate_speedup=', c['equal_gate_speedup'])
coarse = c.get('coarse', {}).get('candidate')
if coarse:
print(' coarse_status=', coarse['method_status'], 'effective_method=', coarse['effective_method'],
'identity=', coarse['exact_subspace_validation'],
'effective_base_equal_gate_speedup=', c['effective_base_equal_gate_speedup'])
return 0 if assessment['passed'] else 1
if __name__ == '__main__':
raise SystemExit(main())

View File

@@ -0,0 +1,162 @@
#!/usr/bin/env python3
"""Compare two visualization resolutions of the same physical FEM state."""
from __future__ import annotations
import argparse
import hashlib
import json
from pathlib import Path
import numpy as np
from plot_model_slices import Slice, color_scale, load_slice, plt, render
def slice_metrics(data: Slice) -> dict:
"""Integrate the displayed triangles, not the underlying curved FE slice."""
u, v = int(data.metadata["horizontal_axis"]), int(data.metadata["vertical_axis"])
points = data.vertices[data.triangles]
x, y = points[:, :, 2 + u], points[:, :, 2 + v]
area = .5 * np.abs((x[:, 1] - x[:, 0]) * (y[:, 2] - y[:, 0]) -
(x[:, 2] - x[:, 0]) * (y[:, 1] - y[:, 0]))
metrics = {
"triangle_count": len(data.triangles),
"triangle_area_sum": float(np.sum(area)),
"piecewise_linear_density_integral": float(np.sum(area * points[:, :, 5].mean(axis=1))),
"piecewise_linear_enthalpy_integral": float(np.sum(area * points[:, :, 6].mean(axis=1))),
}
metrics["exported_geometric_diagnostics"] = {
key: float(data.metadata[key]) if key in data.metadata else None
for key in ("maximum_plane_error", "maximum_sampled_chord_error", "surface_maximum_plane_error",
"reference_surface_maximum_plane_error", "surface_maximum_sampled_chord_error",
"reference_surface_maximum_sampled_chord_error")
}
for name, segments in (("surface", data.surface), ("reference_surface", data.reference_surface)):
if len(segments):
a, b = segments[:, [u, v]], segments[:, [3 + u, 3 + v]]
endpoints = np.concatenate((a, b))
values = {"segment_count": len(segments),
"segment_length_sum": float(np.linalg.norm(b - a, axis=1).sum()),
"u_min": float(endpoints[:, 0].min()), "u_max": float(endpoints[:, 0].max()),
"v_min": float(endpoints[:, 1].min()), "v_max": float(endpoints[:, 1].max())}
else:
values = {"segment_count": 0, "segment_length_sum": 0., "u_min": None, "u_max": None, "v_min": None, "v_max": None}
metrics[name] = values
return metrics
def differences(coarse: dict, fine: dict) -> dict:
result = {}
for key in coarse:
a, b = coarse[key], fine[key]
if isinstance(a, dict):
result[key] = differences(a, b)
elif a is None or b is None:
result[key] = {"coarse": a, "fine": b, "signed_change": None, "absolute_change": None,
"relative_change": None, "relative_absolute_change": None}
else:
delta = b - a
relative = delta / abs(a) if a != 0 else (0. if delta == 0 else None)
result[key] = {"coarse": a, "fine": b, "signed_change": delta, "absolute_change": abs(delta),
"relative_change": relative,
"relative_absolute_change": abs(relative) if relative is not None else None}
return result
def validate_pair(coarse: Slice, fine: Slice) -> None:
if coarse.directory.resolve() == fine.directory.resolve():
raise ValueError("Coarse and fine exports must be distinct directories")
for key in ("plane", "horizontal_axis", "vertical_axis", "normal_axis"):
if coarse.metadata[key] != fine.metadata[key]:
raise ValueError("The paired exports have different physical planes")
if float(coarse.metadata["offset"]) != float(fine.metadata["offset"]):
raise ValueError("The paired exports have different physical plane offsets")
if int(coarse.metadata["subdivisions"]) >= int(fine.metadata["subdivisions"]):
raise ValueError("Fine subdivisions must exceed coarse subdivisions")
def comparison(coarse: Slice, fine: Slice, source_state: Path) -> dict:
validate_pair(coarse, fine)
if not source_state.is_file():
raise ValueError("--source-state must identify the caller-verified common saved state file")
digest = hashlib.sha256()
with source_state.open("rb") as stream:
for chunk in iter(lambda: stream.read(1024 * 1024), b""):
digest.update(chunk)
return {
"coarse_directory": str(coarse.directory.resolve()), "fine_directory": str(fine.directory.resolve()),
"plane": coarse.metadata["plane"], "offset": float(coarse.metadata["offset"]),
"coarse_subdivisions": int(coarse.metadata["subdivisions"]), "fine_subdivisions": int(fine.metadata["subdivisions"]),
"state_provenance": {
"caller_asserted_common_source": str(source_state.resolve()), "source_sha256": digest.hexdigest(),
"export_binding_verified": False,
"limitation": "Caller must verify that both exports used this same state, mesh, field orders and physical specifications. The CSVs do not bind themselves cryptographically to the source state.",
},
"changes": differences(slice_metrics(coarse), slice_metrics(fine)),
"scope": [
"Triangle area and field integrals sum supplied triangles, including any overlaps; they are not union-area measures.",
"Field integrals are signed integrals of piecewise-linear vertex data in 2D; they are not 3D mass, pressure, virial or exact curved-FEM integrals.",
"Surface segment-length sums approximate perimeter and include any duplicated/overlapping segments.",
"Relative change is (fine-coarse)/abs(coarse); it is null for a zero coarse value and a nonzero fine value.",
"Near-zero coarse signed integrals can have large relative changes; inspect absolute changes as well.",
"Shared physical axes and separate shared density/enthalpy color normalizations preserve actual deformation and signed field values.",
"Agreement under one refinement does not certify global geometric conformity, positivity or equilibrium.",
],
}
def render_comparison(coarse: Slice, fine: Slice, *, reference_outline=False, title=None, pixels=512):
validate_pair(coarse, fine)
bounds = (min(float(d.metadata["u_min"]) for d in (coarse, fine)),
max(float(d.metadata["u_max"]) for d in (coarse, fine)),
min(float(d.metadata["v_min"]) for d in (coarse, fine)),
max(float(d.metadata["v_max"]) for d in (coarse, fine)))
normalizations = [color_scale(np.concatenate((coarse.vertices[:, column], fine.vertices[:, column])))
for column in (5, 6)] if len(coarse.vertices) + len(fine.vertices) else None
figure, axes = plt.subplots(2, 2, figsize=(13.4, 10.6), layout="constrained")
for column, (label, data) in enumerate((("Coarse", coarse), ("Fine", fine))):
render(data, reference_outline=reference_outline,
title=f"{label}: {data.metadata['subdivisions']} subdivisions",
normalizations=normalizations, physical_bounds=bounds,
figure=figure, axes=axes[:, column], heading=False, pixels=pixels)
figure.suptitle(f"{title or 'Same-state slice refinement'} — physical {coarse.metadata['plane']} plane, offset {float(coarse.metadata['offset']):.6g}\n"
f"Common axes/color scales; {pixels}×{pixels} scalar pixels; actual deformation; equilibrium not assessed", fontsize=11)
return figure
def main() -> None:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("coarse", type=Path, help="Coarse plane directory, e.g. first/final_slices/xz")
parser.add_argument("fine", type=Path, help="Fine plane directory for the same saved state")
parser.add_argument("--source-state", required=True, type=Path,
help="Common saved state file; caller asserts both exports used this state and matching discretization")
parser.add_argument("--output", required=True, type=Path, help="New JSON/PNG/PDF prefix outside the source checkout")
parser.add_argument("--reference-outline", action="store_true")
parser.add_argument("--pixels", type=int, default=512, help="Common scalar sample grid per axis, 32–2048")
parser.add_argument("--title")
args = parser.parse_args()
source_checkout = Path(__file__).resolve().parents[1]
if args.output.resolve().is_relative_to(source_checkout):
raise ValueError("Comparison artifacts must be written outside the source checkout")
paths = [args.output.with_suffix(suffix) for suffix in (".json", ".png", ".pdf")]
if any(path.exists() for path in paths):
raise FileExistsError("Refusing to overwrite an existing comparison artifact")
coarse, fine = load_slice(args.coarse), load_slice(args.fine)
report = comparison(coarse, fine, args.source_state)
figure = render_comparison(coarse, fine, reference_outline=args.reference_outline, title=args.title, pixels=args.pixels)
report["rasterization"] = {"pixels_per_axis": args.pixels, "sample_location": "pixel centers",
"scalar_interpolation": "barycentric within each supplied triangle before color mapping",
"overlap_owner": "first supplied triangle; no trace averaging", "vacuum": "masked",
"limitation": "Subpixel features may be missed; this raster is not an exact curved-FEM evaluation."}
report["figures"] = [str(path.resolve()) for path in paths[1:]]
args.output.parent.mkdir(parents=True, exist_ok=True)
paths[0].write_text(json.dumps(report, indent=2, allow_nan=False) + "\n")
for path in paths[1:]:
figure.savefig(path, dpi=200, bbox_inches="tight", pad_inches=.15)
plt.close(figure)
for path in paths:
print(path)
if __name__ == "__main__":
main()

View File

@@ -0,0 +1,312 @@
#!/usr/bin/env python3
"""Summarize completed Q3/Q4 six-iteration-budget controls; standard library only.
Usage: compare_shape_order_runs.py Q3_ENDPOINT Q4_ENDPOINT --output FRESH.json
Each endpoint must have its sibling ENDPOINT_run.json completion/hash record.
The parent campaign provenance.json supplies the recorded mesh/source identities.
Exit 0 means comparable complete artifacts, including bounded solver failures;
exit 2 means missing, inconsistent or unsuitable inputs. No physical pass is implied.
"""
import argparse
import csv
import hashlib
import io
import json
import math
from pathlib import Path
import statistics
import sys
PHYSICAL = (
"mass", "mass_absolute_error", "volume", "minimum_mapping_determinant",
"enthalpy_pressure_integral", "enthalpy_virial_error", "enthalpy_virial_signed",
"enthalpy_force_virial_error", "enthalpy_force_virial_signed",
"eos_density_mismatch_rms", "eos_density_mismatch_rms_scaled",
"eos_density_mismatch_maximum", "eos_density_mismatch_maximum_scaled",
"minimum_density", "maximum_density", "negative_density_samples",
"negative_density_volume_fraction", "negative_density_mass_fraction",
"negative_density_mass_magnitude", "minimum_enthalpy", "negative_enthalpy_samples",
"bernoulli_raw_rms", "bernoulli_raw_rms_scaled", "hydrostatic_gradient_rms",
"gravity_gradient_vs_broken_potential_gradient_rms",
"pressure_from_density_defined_everywhere", "pressure_from_enthalpy_defined_everywhere",
"virial_error", "force_virial_error", "complete_volume_measurement",
"stellar_samples", "valid_stellar_samples", "invalid_stellar_samples",
"invalid_density_eos_samples", "invalid_enthalpy_eos_samples",
"normalized_unbordered_residual", "central_border", "polytropic_index", "polytropic_constant",
)
CONTROLS = (
"n", "K", "rho_c", "J", "M", "R_reference", "central_phase", "max_newton",
"restart", "max_linear", "linear_tol", "atol", "rtol", "strategy",
"gravity_tolerance", "gravity_iterations", "gravity_restart", "weak_shape_final",
"context_preconditioner_variant", "context_gravity_schur_sweeps",
"context_gravity_schur_relaxation",
)
WARNINGS = [
"Across-order normalized residual norms and coefficient spectra are not physical accuracy measures. "
"Only within-variant residual reductions are compared.",
"Q3 and Q4 have different surface sample/parameter spaces; raw nodal norms and unweighted harmonic "
"fits are not directly comparable surface integrals. Surface-mode audits are not consumed here.",
"q18 denotes the physical diagnostic integration-rule order, not a field order or converged quadrature limit. "
"P(h) energy/force virials are reported separately from density-based virials, which may be undefined.",
"q14 direction norms describe each endpoint's independently computed Newton direction, not the same "
"vector across orders. Density/potential gradients are broken element-local derivatives; jumps are excluded.",
"A failed endpoint verified_gate remains a failed linear observation; its direction norms do not describe "
"a direction satisfying the requested Newton forcing tolerance.",
"The affine representation check projects reference physical coordinates into the displacement space; "
"it does not certify that the production r^2 radial lift is affine.",
"Six configured iterations are a bounded comparison, not a convergence certificate. "
"Use check_plateau_physics.py for the existing solver/virial milestone gate.",
]
def require(condition, message):
if not condition:
raise ValueError(message)
def number(value, name, finite=True):
result = float(value)
require(not finite or math.isfinite(result), f"Nonfinite {name}")
return result
def integer(value, name):
result = number(value, name)
require(result.is_integer(), f"Noninteger {name}")
return int(result)
def close(a, b, name):
require(math.isclose(a, b, rel_tol=1e-10, abs_tol=1e-18), f"Inconsistent {name}: {a} vs {b}")
def pairs(rows, key="metric"):
result = {}
for row in rows:
name = row[key]
require(name and name not in result, f"Empty or duplicate key: {name!r}")
result[name] = row["value"]
return result
class Inputs:
def __init__(self, directory):
self.directory = directory.resolve()
self.hashes = {}
def text(self, path):
path = path.resolve()
data = path.read_bytes()
self.hashes[str(path)] = {"sha256": hashlib.sha256(data).hexdigest(), "bytes": len(data)}
return data.decode("utf-8")
def csv(self, name, columns):
reader = csv.DictReader(io.StringIO(self.text(self.directory / name)))
require(reader.fieldnames is not None and set(columns).issubset(reader.fieldnames),
f"Missing columns in {name}: {columns}")
require(len(reader.fieldnames) == len(set(reader.fieldnames)), f"Duplicate columns in {name}")
rows = list(reader)
require(all(None not in row and all(v is not None for v in row.values()) for row in rows),
f"Truncated or malformed row in {name}")
return rows
def physical(source, name, metadata):
rows = source.csv(name, ("quadrature", "metric", "value"))
selected = pairs([r for r in rows if integer(r["quadrature"], name) == 18])
missing = set(PHYSICAL) - selected.keys()
require(not missing, f"Missing q18 metrics in {name}: {sorted(missing)}")
values = {k: number(selected[k], k, finite=False) for k in PHYSICAL}
close(values["polytropic_index"], 1.5, name + " polytropic index")
close(values["polytropic_constant"], number(metadata["K"], "K"), name + " polytropic constant")
require(values["central_border"] == 0, f"Unexpected central border in {name}")
require(math.isfinite(values["normalized_unbordered_residual"]) and
values["normalized_unbordered_residual"] >= 0, f"Invalid residual in {name}")
# Undefined density-based quantities are observations, not silently zeroed errors.
unavailable = {k: str(v) for k, v in values.items() if not math.isfinite(v)}
return {"quadrature_order": 18, "metrics": {k: v if math.isfinite(v) else None for k, v in values.items()},
"unavailable_metrics": unavailable}
def summarize(directory, displacement_order):
source = Inputs(directory)
metadata = pairs([dict(zip(("metric", "value"), line.split("=", 1)))
for line in source.text(directory / "metadata.txt").splitlines() if line.strip()])
require(set(CONTROLS).issubset(metadata), "Missing run configuration metadata")
require(number(metadata["n"], "n") == 1.5 and number(metadata["J"], "J") == 0,
"Expected n=1.5, J=0")
require(integer(metadata["central_phase"], "central_phase") == 0, "Central phase must be off")
require(integer(metadata["max_newton"], "max_newton") == 6, "Expected a six-iteration budget")
require(metadata.get("converged") in ("0", "1"), "Missing completed solver outcome")
accepted = integer(metadata["accepted_steps"], "accepted_steps")
require(0 <= accepted <= 6, "Accepted-step count outside configured budget")
require(metadata["converged"] == "1" or metadata.get("failure"), "Missing solver-failure explanation")
runner_path = directory.parent / (directory.name + "_run.json")
runner = json.loads(source.text(runner_path))
require(runner.get("finished_utc") and runner.get("exit_code") in (0, 3),
"Runner incomplete, interrupted, or exited without a normal solver outcome")
require((runner["exit_code"] == 0) == (metadata["converged"] == "1"), "Runner/solver outcome mismatch")
provenance = json.loads(source.text(directory.parent / "provenance.json"))
provenance = {k: provenance[k] for k in ("commit", "branch", "source", "mesh", "mesh_sha256",
"binary_sha256", "runtime_environment")}
require(all(isinstance(provenance[k], str) and len(provenance[k]) == 64
for k in ("mesh_sha256", "binary_sha256")), "Missing recorded mesh/binary hashes")
fe = pairs(source.csv("weak_shape_physical_metadata.csv", ("key", "value")), key="key")
expected = {"density": 2, "enthalpy": 3, "potential": 2, "gravity_flux": 2,
"displacement": displacement_order}
for field, order in expected.items():
require(integer(fe[field + "_family_order"], field) == order, f"Unexpected {field} order")
for key, collection in {"reference_mesh_geometry_collection": "H1_3D_P4",
"displacement_collection": f"H1_3D_P{displacement_order}",
"surface_deformation_collection": f"H1_3D_P{displacement_order}"}.items():
require(fe[key] == collection, f"Unexpected {key}: {fe[key]}")
weak = {k: number(v, k, finite=False) for k, v in
pairs(source.csv("weak_shape_summary.csv", ("metric", "value"))).items()}
for key in ("accepted_buffers_bitwise_identical", "normalization_factors_bitwise_identical",
"direction_buffers_bitwise_identical"):
require(weak[key] == 1, f"Endpoint probe changed {key}")
require(weak["probe_exception"] == 0 and weak["accepted_commits"] == 0, "Incomplete or mutating endpoint probe")
layout = {kind: {} for kind in ("value", "residual")}
for row in source.csv("weak_shape_layout.csv", ("kind", "block", "offset", "size")):
kind, block = row["kind"], row["block"]
require(kind in layout and block not in layout[kind], "Invalid/duplicate layout block")
size = integer(row["size"], "block size")
require(size >= 0 and integer(row["offset"], "block offset") == sum(layout[kind].values()),
"Noncontiguous or negative block layout")
layout[kind][block] = size
require(all(sum(blocks.values()) == weak["state_size"] for blocks in layout.values()), "Layout size mismatch")
require(layout["value"]["surface_deformation"] == layout["residual"]["surface_shape_balance"],
"Surface parameter/equation count mismatch")
initial = physical(source, "initial_physical.csv", metadata)
final = physical(source, "final_physical.csv", metadata)
initial_f = initial["metrics"]["normalized_unbordered_residual"]
final_f = final["metrics"]["normalized_unbordered_residual"]
require(initial_f > 0, "Initial residual must be positive for this comparison")
close(final_f, weak["base_norm"], "final physical/probe residual")
history = source.csv("newton.csv", ("iteration", "accepted", "F", "alpha", "trials", "linear_status",
"linear_iterations", "linear_true", "seconds", "linear_seconds",
"prepare_seconds", "refresh_seconds", "linear_rhs_norm"))
steps = []
for i, row in enumerate(history):
require(integer(row["iteration"], "iteration") == i and i < 6, "Invalid iteration sequence")
step = {k: integer(row[k], k) for k in ("iteration", "accepted", "trials", "linear_status", "linear_iterations")}
require(step["accepted"] in (0, 1) and step["trials"] >= 0 and step["linear_iterations"] >= 0,
"Invalid iteration count/flag")
step.update({k: number(row[k], k) for k in ("F", "alpha", "seconds", "linear_seconds",
"prepare_seconds", "refresh_seconds")})
require(all(step[k] >= 0 for k in ("F", "seconds", "linear_seconds", "prepare_seconds", "refresh_seconds")),
"Negative residual/timing")
relative = number(row["linear_true"], "linear_true", finite=False)
step["linear_relative_true_defect"] = relative if math.isfinite(relative) else None
step["linear_relative_true_defect_unavailable"] = None if math.isfinite(relative) else str(relative)
if step["accepted"]:
require(0 < step["alpha"] <= 1 and step["linear_status"] == 0 and math.isfinite(relative),
"Accepted step lacks a successful finite linear report")
require(relative <= number(metadata["linear_tol"], "linear_tol") * (1 + 1e-10) + 1e-15,
"Accepted step exceeds the recorded linear tolerance")
else:
require(i == len(history) - 1, "Nonfinal rejected iteration")
steps.append(step)
require(sum(s["accepted"] for s in steps) == accepted, "History/metadata accepted count mismatch")
if steps:
close(steps[-1]["F"], final_f, "last recorded/final residual")
rhs = number(history[0]["linear_rhs_norm"], "first linear RHS", finite=False)
if math.isfinite(rhs):
close(rhs, initial_f, "initial residual/first linear RHS")
else:
close(initial_f, final_f, "zero-iteration endpoint residual")
direction = {}
physical_rows = source.csv("weak_shape_physical_summary.csv", ("quadrature", "field", "metric", "value"))
for row in physical_rows:
if integer(row["quadrature"], "direction quadrature") == 14:
field = direction.setdefault(row["field"], {})
require(row["metric"] not in field, "Duplicate q14 direction metric")
field[row["metric"]] = number(row["value"], "q14 direction metric")
for field in ("density", "specific_enthalpy", "gravity_potential"):
require(all(k in direction.get(field, {}) for k in
("pullback_l2_norm", "transport_l2_norm", "eulerian_l2_norm")), f"Missing q14 {field} norms")
require(all(k in direction.get("affine", {}) for k in ("relative_value_l2_error", "relative_gradient_l2_error")),
"Missing q14 affine errors")
squared = direction["geometry"]["direction_displacement_squared_integral"]
require(squared >= 0, "Negative displacement squared integral")
direction["geometry"]["direction_displacement_l2_norm"] = math.sqrt(squared)
for path, digest in source.hashes.items():
if Path(path).parent == source.directory:
require(runner["output_hashes"].get(Path(path).name) == digest["sha256"],
f"Runner hash missing/mismatched: {path}")
times = [s["seconds"] for s in steps]
endpoint = {k: weak[k] for k in ("state_size", "linear_status", "linear_iterations", "linear_seconds",
"verified_gate", "verified_relative_defect", "total_probe_seconds")}
endpoint_unavailable = {k: str(v) for k, v in endpoint.items() if not math.isfinite(v)}
return {"directory": str(source.directory), "input_files": source.hashes,
"recorded_campaign_provenance": provenance,
"controls": {k: metadata[k] for k in CONTROLS}, "orders": expected,
"finite_element_metadata": fe, "block_sizes": layout,
"outcome": {"runner_completed": True, "runner_exit_code": runner["exit_code"],
"converged": metadata["converged"] == "1", "failure": metadata.get("failure"),
"accepted_updates": accepted, "completed_six_updates": accepted == 6},
"newton": {"recorded_iterations": len(steps), "steps": steps,
"accepted_alphas": [s["alpha"] for s in steps if s["accepted"]],
"krylov_iterations_total": sum(s["linear_iterations"] for s in steps),
"iteration_seconds_total": sum(times),
"iteration_seconds_mean": statistics.mean(times) if times else None,
"iteration_seconds_median": statistics.median(times) if times else None,
"linear_seconds_total": sum(s["linear_seconds"] for s in steps),
"preparation_seconds_total": sum(s["prepare_seconds"] for s in steps),
"refresh_seconds_total": sum(s["refresh_seconds"] for s in steps),
"timing_scope": "AfterIteration records only; excludes initialization, final physical measurement "
"and endpoint weak-shape probe. Components are not asserted to partition wall time.",
"initial_normalized_residual": initial_f, "final_normalized_residual": final_f,
"final_over_initial_normalized_residual": final_f / initial_f},
"initial_physical_q18": initial, "final_physical_q18": final,
"endpoint_probe": {k: v if math.isfinite(v) else None for k, v in endpoint.items()},
"endpoint_probe_unavailable_metrics": endpoint_unavailable,
"endpoint_direction_q14": direction}
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("q3", type=Path)
parser.add_argument("q4", type=Path)
parser.add_argument("--output", required=True, type=Path)
args = parser.parse_args()
try:
require(args.q3.resolve() != args.q4.resolve(), "Q3 and Q4 must be distinct endpoint directories")
require(not args.output.exists(), "Output must be fresh")
require(not any(args.output.resolve().is_relative_to(p.resolve()) for p in (args.q3, args.q4)),
"Write the comparison outside the immutable endpoint directories")
q3, q4 = summarize(args.q3.resolve(), 3), summarize(args.q4.resolve(), 4)
require(q3["controls"] == q4["controls"], "Physics/solver controls differ beyond displacement order")
require(q3["recorded_campaign_provenance"]["mesh_sha256"] ==
q4["recorded_campaign_provenance"]["mesh_sha256"], "Recorded reference meshes differ")
require(q3["recorded_campaign_provenance"]["runtime_environment"] ==
q4["recorded_campaign_provenance"]["runtime_environment"], "Recorded runtime environments differ")
result = {"schema_version": 1, "artifact_comparison_complete": True,
"scope": "Recorded endpoint comparison; no FEM rerun or physical acceptance certificate",
"comparison": {"matched_maximum_newton_iterations": 6,
"equal_accepted_counts": q3["outcome"]["accepted_updates"] ==
q4["outcome"]["accepted_updates"],
"both_completed_six_updates": q3["outcome"]["completed_six_updates"] and
q4["outcome"]["completed_six_updates"]},
"warnings": WARNINGS, "q3": q3, "q4": q4}
# Deliberately omit an across-order normalized-residual ratio.
text = json.dumps(result, indent=2, allow_nan=False) + "\n"
with args.output.open("x") as stream:
stream.write(text)
print(f"Wrote {args.output}; accepted updates: Q3={q3['outcome']['accepted_updates']}, "
f"Q4={q4['outcome']['accepted_updates']}. Not a physical-validation certificate.")
return 0
except (OSError, ValueError, KeyError, TypeError) as error:
print(f"Comparison incomplete or unsuitable: {error}", file=sys.stderr)
return 2
if __name__ == "__main__":
sys.exit(main())

View File

@@ -0,0 +1,259 @@
#pragma once
// Include after import mean_field. These helpers transfer an initial guess;
// they do not certify that it solves the destination model. The caller binds
// model, mesh, field orders and surface-basis provenance before installation.
#include <algorithm>
#include <charconv>
#include <cmath>
#include <cstring>
#include <exception>
#include <filesystem>
#include <fstream>
#include <limits>
#include <map>
#include <set>
#include <span>
#include <stdexcept>
#include <string>
#include <string_view>
#include <utility>
#include <vector>
namespace experiment::continuation {
using SnapshotMetadata = std::map<std::string, std::string>;
struct SnapshotBlock final {
std::string name;
int offset;
int size;
};
namespace detail {
inline constexpr std::string_view centralBorder = "fixed_central_density.border";
inline bool Finite(const mfem::Vector &vector) {
for (int i = 0; i < vector.Size(); ++i)
if (!std::isfinite(vector(i))) return false;
return true;
}
inline bool Identical(const mfem::Vector &left, const mfem::Vector &right) {
return left.Size() == right.Size() &&
(left.Size() == 0 || std::memcmp(left.GetData(), right.GetData(),
sizeof(mfem::real_t) * static_cast<std::size_t>(left.Size())) == 0);
}
inline void RequireSerial(MPI_Comm communicator) {
int ranks = 0;
if (communicator == MPI_COMM_NULL || MPI_Comm_size(communicator, &ranks) != MPI_SUCCESS || ranks != 1)
throw std::invalid_argument("Continuation snapshots currently require one MPI rank.");
}
inline int NonnegativeInteger(std::string_view text) {
int value = -1;
const auto result = std::from_chars(text.data(), text.data() + text.size(), value);
if (text.empty() || result.ec != std::errc{} || result.ptr != text.data() + text.size() || value < 0)
throw std::invalid_argument("A snapshot layout offset or size is not a nonnegative integer.");
return value;
}
inline std::vector<std::string> Fields(std::string line) {
if (!line.empty() && line.back() == '\r') line.pop_back();
if (line.find('"') != std::string::npos)
throw std::invalid_argument("Snapshot layout requires the producer's unquoted CSV format.");
std::vector<std::string> result;
std::size_t first = 0;
while (true) {
const auto comma = line.find(',', first);
result.push_back(line.substr(first, comma == std::string::npos ? comma : comma - first));
if (comma == std::string::npos) return result;
first = comma + 1;
}
}
// Contiguity establishes an exact coordinate partition independently of file
// order. Equal total sizes alone cannot detect permuted or missing physics.
inline int ValidatePartition(std::span<const SnapshotBlock> blocks) {
if (blocks.empty()) throw std::invalid_argument("Snapshot layout has no physical value blocks.");
std::vector<SnapshotBlock> ordered(blocks.begin(), blocks.end());
std::set<std::string> names;
for (const auto &block : ordered) {
if (block.name.empty() || !names.insert(block.name).second || block.offset < 0 || block.size < 0 ||
block.offset > std::numeric_limits<int>::max() - block.size)
throw std::invalid_argument("Snapshot layout has invalid or repeated block coordinates.");
if (block.name == centralBorder && block.size != 1)
throw std::invalid_argument("A central-density border must contain exactly one scalar.");
}
std::sort(ordered.begin(), ordered.end(), [](const auto &a, const auto &b) {
return a.offset < b.offset || (a.offset == b.offset && a.size < b.size);
});
int size = 0;
for (const auto &block : ordered) {
if (block.offset != size)
throw std::invalid_argument("Snapshot layout contains a gap or overlapping coordinates.");
size += block.size;
}
if (size == 0) throw std::invalid_argument("Snapshot state is empty.");
return size;
}
inline std::vector<SnapshotBlock> ReadValueBlocks(const std::filesystem::path &path) {
std::ifstream input(path);
std::string line;
if (!input || !std::getline(input, line))
throw std::invalid_argument("Cannot read snapshot layout: " + path.string());
const auto header = Fields(line);
std::map<std::string, std::size_t> columns;
for (std::size_t i = 0; i < header.size(); ++i)
if (header[i].empty() || !columns.emplace(header[i], i).second)
throw std::invalid_argument("Snapshot layout has an invalid CSV header.");
for (const auto *name : {"kind", "block", "offset", "size"})
if (!columns.contains(name)) throw std::invalid_argument("Snapshot layout lacks a required column.");
std::vector<SnapshotBlock> values, residuals;
while (std::getline(input, line)) {
const auto fields = Fields(line);
if (fields.size() != header.size())
throw std::invalid_argument("Snapshot layout has an incomplete CSV row.");
const auto &kind = fields[columns.at("kind")];
SnapshotBlock block{fields[columns.at("block")], NonnegativeInteger(fields[columns.at("offset")]),
NonnegativeInteger(fields[columns.at("size")])};
if (kind == "value") values.push_back(std::move(block));
else if (kind == "residual") residuals.push_back(std::move(block));
else throw std::invalid_argument("Snapshot layout has an unknown coordinate kind.");
}
if (input.bad()) throw std::runtime_error("Snapshot layout read failed.");
ValidatePartition(values);
if (!residuals.empty()) ValidatePartition(residuals);
return values;
}
inline mfem::Vector ReadVector(const std::filesystem::path &path, int expectedSize) {
std::ifstream input(path);
long long count = -1;
if (!(input >> count) || count != expectedSize)
throw std::invalid_argument("Snapshot vector length disagrees with its named layout: " + path.string());
mfem::Vector values(expectedSize);
for (int i = 0; i < expectedSize; ++i)
if (!(input >> values(i)) || !std::isfinite(values(i)))
throw std::invalid_argument("Snapshot vector is incomplete or nonfinite: " + path.string());
std::string trailing;
if (input >> trailing || input.bad())
throw std::invalid_argument("Snapshot vector has trailing data or a read error: " + path.string());
return values;
}
} // namespace detail
inline SnapshotMetadata ParseSnapshotMetadata(const std::filesystem::path &directory) {
const auto path = directory / "metadata.txt";
std::ifstream input(path);
if (!input) throw std::invalid_argument("Continuation requires snapshot metadata: " + path.string());
SnapshotMetadata metadata;
std::string line;
while (std::getline(input, line)) {
if (!line.empty() && line.back() == '\r') line.pop_back();
if (line.empty()) continue;
const auto separator = line.find('=');
if (separator == std::string::npos || separator == 0 ||
!metadata.emplace(line.substr(0, separator), line.substr(separator + 1)).second)
throw std::invalid_argument("Snapshot metadata has a malformed or repeated key.");
}
if (input.bad() || metadata.empty()) throw std::invalid_argument("Snapshot metadata is empty or unreadable.");
return metadata;
}
inline mfem::Vector MapNamedPhysicalBlocks(
const mfem::Vector &source, std::span<const SnapshotBlock> sourceBlocks,
std::span<const SnapshotBlock> targetBlocks, bool allowCentralBorderChange = false
) {
if (source.Size() != detail::ValidatePartition(sourceBlocks) || !detail::Finite(source))
throw std::invalid_argument("Snapshot source does not match its finite physical coordinate layout.");
mfem::Vector target(detail::ValidatePartition(targetBlocks));
target = 0.0;
std::map<std::string, const SnapshotBlock *> sourceByName, targetByName;
for (const auto &block : sourceBlocks) sourceByName.emplace(block.name, &block);
for (const auto &block : targetBlocks) targetByName.emplace(block.name, &block);
for (const auto &block : sourceBlocks)
if (!targetByName.contains(block.name) && !(allowCentralBorderChange && block.name == detail::centralBorder))
throw std::invalid_argument("Snapshot contains an unknown destination block: " + block.name);
for (const auto &block : targetBlocks) {
const auto found = sourceByName.find(block.name);
if (found == sourceByName.end()) {
if (allowCentralBorderChange && block.name == detail::centralBorder) continue;
throw std::invalid_argument("Snapshot is missing a required destination block: " + block.name);
}
const auto &from = *found->second;
if (from.size != block.size)
throw std::invalid_argument("Snapshot block has a different coordinate count: " + block.name);
for (int i = 0; i < block.size; ++i) target(block.offset + i) = source(from.offset + i);
}
return target;
}
template <class Problem>
mfem::Vector LoadMappedSnapshot(const Problem &problem, const std::filesystem::path &path,
bool allowCentralBorderChange = false, bool allowUnconvergedRestart = false) {
detail::RequireSerial(problem.GetCommunicator());
const auto statePath = std::filesystem::is_directory(path) ? path / "accepted_state.txt" : path;
const auto directory = std::filesystem::exists(statePath.parent_path() / "metadata.txt") ?
statePath.parent_path() : statePath.parent_path().parent_path();
const bool isAcceptedEndpoint = statePath.filename() == "accepted_state.txt" && statePath.parent_path() == directory;
if (!isAcceptedEndpoint && !allowUnconvergedRestart)
throw std::invalid_argument("Captured iterates require the explicit unconverged-restart override.");
const auto metadata = ParseSnapshotMetadata(directory);
const auto converged = metadata.find("converged");
if (converged != metadata.end() && converged->second != "0" && converged->second != "1")
throw std::invalid_argument("Snapshot metadata has an invalid convergence flag.");
if (!allowUnconvergedRestart && (converged == metadata.end() || converged->second != "1"))
throw std::invalid_argument("Continuation refuses an unverified or unconverged predecessor; an explicit restart override is required.");
const auto sourceBlocks = detail::ReadValueBlocks(directory / "layout.csv");
const auto source = detail::ReadVector(statePath, detail::ValidatePartition(sourceBlocks));
std::vector<SnapshotBlock> targetBlocks;
for (const auto &block : problem.GetManifest().valueBlocks())
targetBlocks.push_back({std::string(block.stableId), block.offset, block.size});
auto mapped = MapNamedPhysicalBlocks(source, sourceBlocks, targetBlocks, allowCentralBorderChange);
if (mapped.Size() != problem.StateSize())
throw std::logic_error("Destination manifest does not cover its physical state.");
return mapped;
}
// No mesh or FEM preparation is needed: these cases catch the silent block
// reorder/border mistakes that a length-only snapshot reader would permit.
inline int RunSnapshotCoordinateSelfChecks() {
int checks = 0;
const auto require = [&](bool condition) {
if (!condition) throw std::logic_error("Continuation coordinate self-check failed.");
++checks;
};
const auto rejects = [&](auto action) {
bool rejected = false;
try { action(); } catch (const std::invalid_argument &) { rejected = true; }
require(rejected);
};
const std::vector<SnapshotBlock> source{{"density", 0, 2}, {"enthalpy", 2, 1}};
const std::vector<SnapshotBlock> reordered{{"enthalpy", 0, 1}, {"density", 1, 2}};
const std::vector<SnapshotBlock> bordered{{"enthalpy", 0, 1}, {std::string(detail::centralBorder), 1, 1}, {"density", 2, 2}};
mfem::Vector values(3);
values(0) = 2.; values(1) = 3.; values(2) = 7.;
const auto mapped = MapNamedPhysicalBlocks(values, source, reordered);
require(mapped(0) == 7. && mapped(1) == 2. && mapped(2) == 3.);
const auto added = MapNamedPhysicalBlocks(values, source, bordered, true);
require(added.Size() == 4 && added(0) == 7. && added(1) == 0. && added(2) == 2. && added(3) == 3.);
require(detail::Identical(MapNamedPhysicalBlocks(added, bordered, source, true), values));
rejects([&] { MapNamedPhysicalBlocks(values, source, bordered); });
rejects([&] { MapNamedPhysicalBlocks(added, bordered, source); });
auto bad = source; bad[1].name = "unknown";
rejects([&] { MapNamedPhysicalBlocks(values, bad, source); });
bad = source; bad[1].offset = 1;
rejects([&] { MapNamedPhysicalBlocks(values, bad, source); });
bad = source; bad[1].offset = 3;
rejects([&] { MapNamedPhysicalBlocks(values, bad, source); });
bad = source; bad[1].name = "density";
rejects([&] { MapNamedPhysicalBlocks(values, bad, source); });
bad = source; bad[0].size = 1; bad[1].offset = 1; bad[1].size = 2;
rejects([&] { MapNamedPhysicalBlocks(values, source, bad); });
values(0) = std::numeric_limits<double>::quiet_NaN();
rejects([&] { MapNamedPhysicalBlocks(values, source, reordered); });
return checks;
}
} // namespace experiment::continuation

View File

@@ -0,0 +1,70 @@
[
{
"id": "n2_restart_raw",
"arguments": [
"--index",
"2",
"--angular-momentum",
"0",
"--surface-prescription",
"harmonics",
"--surface-degree",
"4",
"--restart",
"160",
"--max-linear",
"300",
"--rtol",
"0",
"--atol",
"1e-12",
"--no-central",
"--max-newton",
"6",
"--linear-tol",
".03",
"--strategy",
"baseline",
"--restart-snapshot",
"../../diagnostics/coupled_convergence_2026-09-19/screen_v1/n2_J0/capture_3/physical_base.txt",
"--allow-unconverged-restart",
"--model-slices",
"--slice-subdivisions",
"4"
]
},
{
"id": "n2_restart_gravity_path",
"arguments": [
"--index",
"2",
"--angular-momentum",
"0",
"--surface-prescription",
"harmonics",
"--surface-degree",
"4",
"--restart",
"160",
"--max-linear",
"300",
"--rtol",
"0",
"--atol",
"1e-12",
"--no-central",
"--max-newton",
"6",
"--linear-tol",
".03",
"--strategy",
"curvature",
"--restart-snapshot",
"../../diagnostics/coupled_convergence_2026-09-19/screen_v1/n2_J0/capture_3/physical_base.txt",
"--allow-unconverged-restart",
"--model-slices",
"--slice-subdivisions",
"4"
]
}
]

View File

@@ -0,0 +1,295 @@
[
{
"id": "n2_late_gravity",
"arguments": [
"--index",
"2",
"--angular-momentum",
"0",
"--surface-prescription",
"harmonics",
"--surface-degree",
"4",
"--restart",
"160",
"--max-linear",
"300",
"--rtol",
"0",
"--atol",
"1e-12",
"--max-newton",
"0",
"--linear-tol",
".003",
"--preconditioner-probe",
"--preconditioner-variant",
"gravity-schur",
"--restart-snapshot",
"../../diagnostics/coupled_convergence_2026-09-19/screen_v1/n2_J0/capture_3/physical_base.txt",
"--allow-unconverged-restart",
"--no-central",
"--benchmark-trials"
]
},
{
"id": "n2_late_surface",
"arguments": [
"--index",
"2",
"--angular-momentum",
"0",
"--surface-prescription",
"harmonics",
"--surface-degree",
"4",
"--restart",
"160",
"--max-linear",
"300",
"--rtol",
"0",
"--atol",
"1e-12",
"--max-newton",
"0",
"--linear-tol",
".003",
"--preconditioner-probe",
"--preconditioner-variant",
"surface-border-schur",
"--restart-snapshot",
"../../diagnostics/coupled_convergence_2026-09-19/screen_v1/n2_J0/capture_3/physical_base.txt",
"--allow-unconverged-restart",
"--no-central"
]
},
{
"id": "n2_late_combined",
"arguments": [
"--index",
"2",
"--angular-momentum",
"0",
"--surface-prescription",
"harmonics",
"--surface-degree",
"4",
"--restart",
"160",
"--max-linear",
"300",
"--rtol",
"0",
"--atol",
"1e-12",
"--max-newton",
"0",
"--linear-tol",
".003",
"--preconditioner-probe",
"--preconditioner-variant",
"gravity-schur-surface-border-schur",
"--restart-snapshot",
"../../diagnostics/coupled_convergence_2026-09-19/screen_v1/n2_J0/capture_3/physical_base.txt",
"--allow-unconverged-restart",
"--no-central",
"--benchmark-trials"
]
},
{
"id": "n2_late_tight_combined",
"arguments": [
"--index",
"2",
"--angular-momentum",
"0",
"--surface-prescription",
"harmonics",
"--surface-degree",
"4",
"--restart",
"160",
"--max-linear",
"300",
"--rtol",
"0",
"--atol",
"1e-12",
"--max-newton",
"0",
"--linear-tol",
"1e-7",
"--preconditioner-probe",
"--preconditioner-variant",
"gravity-schur-surface-border-schur",
"--restart-snapshot",
"../../diagnostics/coupled_convergence_2026-09-19/screen_v1/n2_J0/capture_3/physical_base.txt",
"--allow-unconverged-restart",
"--no-central",
"--benchmark-trials"
]
},
{
"id": "n3_late_combined",
"arguments": [
"--index",
"3",
"--angular-momentum",
"0",
"--surface-prescription",
"harmonics",
"--surface-degree",
"4",
"--restart",
"160",
"--max-linear",
"300",
"--rtol",
"0",
"--atol",
"1e-12",
"--max-newton",
"0",
"--linear-tol",
".003",
"--preconditioner-probe",
"--preconditioner-variant",
"gravity-schur-surface-border-schur",
"--restart-snapshot",
"../../diagnostics/coupled_convergence_2026-09-19/screen_v1/n3_J0_control/capture_7/physical_base.txt",
"--allow-unconverged-restart",
"--benchmark-trials"
]
},
{
"id": "n1_rotating_late_combined",
"arguments": [
"--index",
"1",
"--angular-momentum",
"0.1",
"--surface-prescription",
"harmonics",
"--surface-degree",
"4",
"--restart",
"160",
"--max-linear",
"300",
"--rtol",
"0",
"--atol",
"1e-12",
"--max-newton",
"0",
"--linear-tol",
".003",
"--preconditioner-probe",
"--preconditioner-variant",
"gravity-schur-surface-border-schur",
"--restart-snapshot",
"../../diagnostics/coupled_convergence_2026-09-19/screen_v1/n1_J0p1/capture_7/physical_base.txt",
"--allow-unconverged-restart",
"--no-central",
"--benchmark-trials"
]
},
{
"id": "n1p5_rotating_late_combined",
"arguments": [
"--index",
"1.5",
"--angular-momentum",
"0.1",
"--surface-prescription",
"harmonics",
"--surface-degree",
"4",
"--restart",
"160",
"--max-linear",
"300",
"--rtol",
"0",
"--atol",
"1e-12",
"--max-newton",
"0",
"--linear-tol",
".003",
"--preconditioner-probe",
"--preconditioner-variant",
"gravity-schur-surface-border-schur",
"--restart-snapshot",
"../../diagnostics/coupled_convergence_2026-09-19/screen_v1/n1p5_J0p1/accepted_state.txt",
"--allow-unconverged-restart",
"--no-central",
"--benchmark-trials"
]
},
{
"id": "n2_late_ldu_gravity",
"arguments": [
"--index",
"2",
"--angular-momentum",
"0",
"--surface-prescription",
"harmonics",
"--surface-degree",
"4",
"--restart",
"160",
"--max-linear",
"300",
"--rtol",
"0",
"--atol",
"1e-12",
"--max-newton",
"0",
"--linear-tol",
".003",
"--preconditioner-probe",
"--preconditioner-variant",
"stellar-ldu-gravity-schur",
"--restart-snapshot",
"../../diagnostics/coupled_convergence_2026-09-19/screen_v1/n2_J0/capture_3/physical_base.txt",
"--allow-unconverged-restart",
"--no-central"
]
},
{
"id": "n3_late_ldu_gravity",
"arguments": [
"--index",
"3",
"--angular-momentum",
"0",
"--surface-prescription",
"harmonics",
"--surface-degree",
"4",
"--restart",
"160",
"--max-linear",
"300",
"--rtol",
"0",
"--atol",
"1e-12",
"--max-newton",
"0",
"--linear-tol",
".003",
"--preconditioner-probe",
"--preconditioner-variant",
"stellar-ldu-gravity-schur",
"--restart-snapshot",
"../../diagnostics/coupled_convergence_2026-09-19/screen_v1/n3_J0_control/capture_7/physical_base.txt",
"--allow-unconverged-restart",
"--benchmark-trials"
]
}
]

View File

@@ -0,0 +1,65 @@
[
{
"id": "n3_late_gravity",
"arguments": [
"--index",
"3",
"--angular-momentum",
"0",
"--surface-prescription",
"harmonics",
"--surface-degree",
"4",
"--restart",
"160",
"--max-linear",
"300",
"--rtol",
"0",
"--atol",
"1e-12",
"--max-newton",
"0",
"--linear-tol",
".003",
"--preconditioner-probe",
"--preconditioner-variant",
"gravity-schur",
"--restart-snapshot",
"../../diagnostics/coupled_convergence_2026-09-19/screen_v1/n3_J0_control/capture_7/physical_base.txt",
"--allow-unconverged-restart"
]
},
{
"id": "n1p5_rotating_late_gravity",
"arguments": [
"--index",
"1.5",
"--angular-momentum",
"0.1",
"--surface-prescription",
"harmonics",
"--surface-degree",
"4",
"--restart",
"160",
"--max-linear",
"300",
"--rtol",
"0",
"--atol",
"1e-12",
"--max-newton",
"0",
"--linear-tol",
".003",
"--preconditioner-probe",
"--preconditioner-variant",
"gravity-schur",
"--restart-snapshot",
"../../diagnostics/coupled_convergence_2026-09-19/screen_v1/n1p5_J0p1/accepted_state.txt",
"--allow-unconverged-restart",
"--no-central"
]
}
]

View File

@@ -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"
]
}
]

View File

@@ -0,0 +1,86 @@
[
{
"id": "n2_spherical_s4",
"arguments": [
"--index",
"2",
"--angular-momentum",
"0",
"--no-central",
"--surface-prescription",
"harmonics",
"--surface-degree",
"4",
"--max-newton",
"0",
"--density-snapshot",
"../../diagnostics/coupled_convergence_2026-09-19/screen_v1/n2_J0",
"--model-slices-only",
"--slice-subdivisions",
"4"
]
},
{
"id": "n2_spherical_s8",
"arguments": [
"--index",
"2",
"--angular-momentum",
"0",
"--no-central",
"--surface-prescription",
"harmonics",
"--surface-degree",
"4",
"--max-newton",
"0",
"--density-snapshot",
"../../diagnostics/coupled_convergence_2026-09-19/screen_v1/n2_J0",
"--model-slices-only",
"--slice-subdivisions",
"8"
]
},
{
"id": "n1p5_rotating_s4",
"arguments": [
"--index",
"1.5",
"--angular-momentum",
"0.1",
"--no-central",
"--surface-prescription",
"harmonics",
"--surface-degree",
"4",
"--max-newton",
"0",
"--density-snapshot",
"../../diagnostics/coupled_convergence_2026-09-19/screen_v1/n1p5_J0p1",
"--model-slices-only",
"--slice-subdivisions",
"4"
]
},
{
"id": "n1p5_rotating_s8",
"arguments": [
"--index",
"1.5",
"--angular-momentum",
"0.1",
"--no-central",
"--surface-prescription",
"harmonics",
"--surface-degree",
"4",
"--max-newton",
"0",
"--density-snapshot",
"../../diagnostics/coupled_convergence_2026-09-19/screen_v1/n1p5_J0p1",
"--model-slices-only",
"--slice-subdivisions",
"8"
]
}
]

View File

@@ -0,0 +1,47 @@
[
{
"id": "late_raw_coupled",
"arguments": [
"--index",
"1.5",
"--angular-momentum",
"0",
"--no-central",
"--max-newton",
"0",
"--coupled-trial-probe",
"--strategy",
"coupled",
"--probe-state",
"/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/nonlinear_step_2026-09-18/late_v1/n1p5_late_eta003/nonlinear_step_physical_base.txt",
"--probe-direction",
"/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/nonlinear_step_2026-09-18/late_v1/n1p5_late_eta003/nonlinear_step_direction_full.txt",
"--linear-tol",
"0.03",
"--restart",
"160",
"--preconditioner-variant",
"gravity-schur",
"--schur-sweeps",
"1",
"--schur-relaxation",
"0.5",
"--gravity-tol",
"1e-10",
"--gravity-iterations",
"300",
"--gravity-restart",
"80",
"--coupled-tol",
"0.03",
"--coupled-iterations",
"160",
"--coupled-restart",
"160",
"--coupled-max-ratio",
"1",
"--coupled-attempts",
"1"
]
}
]

View File

@@ -0,0 +1,138 @@
[
{
"id": "late_curvature_coupled",
"arguments": [
"--index",
"1.5",
"--angular-momentum",
"0",
"--no-central",
"--max-newton",
"0",
"--coupled-trial-probe",
"--strategy",
"curvature-coupled",
"--probe-state",
"/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/nonlinear_step_2026-09-18/late_v1/n1p5_late_eta003/nonlinear_step_physical_base.txt",
"--probe-direction",
"/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/nonlinear_step_2026-09-18/late_v1/n1p5_late_eta003/nonlinear_step_direction_full.txt",
"--linear-tol",
"0.03",
"--restart",
"160",
"--preconditioner-variant",
"gravity-schur",
"--schur-sweeps",
"1",
"--schur-relaxation",
"0.5",
"--gravity-tol",
"1e-10",
"--gravity-iterations",
"300",
"--gravity-restart",
"80",
"--coupled-tol",
"0.03",
"--coupled-iterations",
"160",
"--coupled-restart",
"160",
"--coupled-max-ratio",
"1",
"--coupled-attempts",
"1"
]
},
{
"id": "late_raw_coupled",
"arguments": [
"--index",
"1.5",
"--angular-momentum",
"0",
"--no-central",
"--max-newton",
"0",
"--coupled-trial-probe",
"--strategy",
"coupled",
"--probe-state",
"/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/nonlinear_step_2026-09-18/late_v1/n1p5_late_eta003/nonlinear_step_physical_base.txt",
"--probe-direction",
"/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/nonlinear_step_2026-09-18/late_v1/n1p5_late_eta003/nonlinear_step_direction_full.txt",
"--linear-tol",
"0.03",
"--restart",
"160",
"--preconditioner-variant",
"gravity-schur",
"--schur-sweeps",
"1",
"--schur-relaxation",
"0.5",
"--gravity-tol",
"1e-10",
"--gravity-iterations",
"300",
"--gravity-restart",
"80",
"--coupled-tol",
"0.03",
"--coupled-iterations",
"160",
"--coupled-restart",
"160",
"--coupled-max-ratio",
"1",
"--coupled-attempts",
"1"
]
},
{
"id": "seed_curvature_coupled",
"arguments": [
"--index",
"1.5",
"--angular-momentum",
"0",
"--no-central",
"--max-newton",
"0",
"--coupled-trial-probe",
"--strategy",
"curvature-coupled",
"--probe-state",
"/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/nonlinear_step_2026-09-18/controls_v1/n1p5_seed_eta003/nonlinear_step_physical_base.txt",
"--probe-direction",
"/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/nonlinear_step_2026-09-18/controls_v1/n1p5_seed_eta003/nonlinear_step_direction_full.txt",
"--linear-tol",
"0.03",
"--restart",
"160",
"--preconditioner-variant",
"gravity-schur",
"--schur-sweeps",
"1",
"--schur-relaxation",
"0.5",
"--gravity-tol",
"1e-10",
"--gravity-iterations",
"300",
"--gravity-restart",
"80",
"--coupled-tol",
"0.03",
"--coupled-iterations",
"160",
"--coupled-restart",
"160",
"--coupled-max-ratio",
"1",
"--coupled-attempts",
"1",
"--coupled-seed-control"
]
}
]

View File

@@ -0,0 +1,62 @@
[
{
"id": "n1p5_J0_control",
"arguments": [
"--index",
"1.5",
"--angular-momentum",
"0",
"--strategy",
"curvature",
"--no-central",
"--max-newton",
"6",
"--restart",
"160",
"--max-linear",
"200",
"--linear-tol",
"0.03",
"--rtol",
"1e-8",
"--atol",
"0",
"--preconditioner-variant",
"gravity-schur",
"--schur-sweeps",
"1",
"--schur-relaxation",
"0.5"
]
},
{
"id": "n1p5_J0_near",
"arguments": [
"--index",
"1.5",
"--angular-momentum",
"0",
"--strategy",
"curvature-backtracked-coupled",
"--no-central",
"--max-newton",
"6",
"--restart",
"160",
"--max-linear",
"200",
"--linear-tol",
"0.03",
"--rtol",
"1e-8",
"--atol",
"0",
"--preconditioner-variant",
"gravity-schur",
"--schur-sweeps",
"1",
"--schur-relaxation",
"0.5"
]
}
]

View File

@@ -0,0 +1,143 @@
[
{
"id": "late_curvature_full",
"arguments": [
"--index",
"1.5",
"--angular-momentum",
"0",
"--no-central",
"--max-newton",
"0",
"--damped-coupled-probe",
"--strategy",
"curvature-coupled",
"--probe-state",
"/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/nonlinear_step_2026-09-18/late_v1/n1p5_late_eta003/nonlinear_step_physical_base.txt",
"--probe-direction",
"/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/nonlinear_step_2026-09-18/late_v1/n1p5_late_eta003/nonlinear_step_direction_full.txt",
"--linear-tol",
"0.03",
"--restart",
"160",
"--preconditioner-variant",
"gravity-schur",
"--schur-sweeps",
"1",
"--schur-relaxation",
"0.5",
"--gravity-tol",
"1e-10",
"--gravity-iterations",
"300",
"--gravity-restart",
"80",
"--coupled-tol",
"0.03",
"--coupled-iterations",
"160",
"--coupled-restart",
"160",
"--coupled-max-ratio",
"1",
"--coupled-attempts",
"1",
"--coupled-search",
"full"
]
},
{
"id": "late_raw_none",
"arguments": [
"--index",
"1.5",
"--angular-momentum",
"0",
"--no-central",
"--max-newton",
"0",
"--damped-coupled-probe",
"--strategy",
"coupled",
"--probe-state",
"/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/nonlinear_step_2026-09-18/late_v1/n1p5_late_eta003/nonlinear_step_physical_base.txt",
"--probe-direction",
"/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/nonlinear_step_2026-09-18/late_v1/n1p5_late_eta003/nonlinear_step_direction_full.txt",
"--linear-tol",
"0.03",
"--restart",
"160",
"--preconditioner-variant",
"gravity-schur",
"--schur-sweeps",
"1",
"--schur-relaxation",
"0.5",
"--gravity-tol",
"1e-10",
"--gravity-iterations",
"300",
"--gravity-restart",
"80",
"--coupled-tol",
"0.03",
"--coupled-iterations",
"160",
"--coupled-restart",
"160",
"--coupled-max-ratio",
"1",
"--coupled-attempts",
"1",
"--coupled-search",
"none"
]
},
{
"id": "late_raw_near",
"arguments": [
"--index",
"1.5",
"--angular-momentum",
"0",
"--no-central",
"--max-newton",
"0",
"--damped-coupled-probe",
"--strategy",
"coupled",
"--probe-state",
"/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/nonlinear_step_2026-09-18/late_v1/n1p5_late_eta003/nonlinear_step_physical_base.txt",
"--probe-direction",
"/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/nonlinear_step_2026-09-18/late_v1/n1p5_late_eta003/nonlinear_step_direction_full.txt",
"--linear-tol",
"0.03",
"--restart",
"160",
"--preconditioner-variant",
"gravity-schur",
"--schur-sweeps",
"1",
"--schur-relaxation",
"0.5",
"--gravity-tol",
"1e-10",
"--gravity-iterations",
"300",
"--gravity-restart",
"80",
"--coupled-tol",
"0.03",
"--coupled-iterations",
"160",
"--coupled-restart",
"160",
"--coupled-max-ratio",
"1",
"--coupled-attempts",
"1",
"--coupled-search",
"near"
]
}
]

View File

@@ -0,0 +1,425 @@
[
{
"id": "late_raw_none",
"arguments": [
"--index",
"1.5",
"--angular-momentum",
"0",
"--no-central",
"--max-newton",
"0",
"--damped-coupled-probe",
"--strategy",
"coupled",
"--probe-state",
"/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/nonlinear_step_2026-09-18/late_v1/n1p5_late_eta003/nonlinear_step_physical_base.txt",
"--probe-direction",
"/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/nonlinear_step_2026-09-18/late_v1/n1p5_late_eta003/nonlinear_step_direction_full.txt",
"--linear-tol",
"0.03",
"--restart",
"160",
"--preconditioner-variant",
"gravity-schur",
"--schur-sweeps",
"1",
"--schur-relaxation",
"0.5",
"--gravity-tol",
"1e-10",
"--gravity-iterations",
"300",
"--gravity-restart",
"80",
"--coupled-tol",
"0.03",
"--coupled-iterations",
"160",
"--coupled-restart",
"160",
"--coupled-max-ratio",
"1",
"--coupled-attempts",
"1",
"--coupled-search",
"none"
]
},
{
"id": "late_raw_full",
"arguments": [
"--index",
"1.5",
"--angular-momentum",
"0",
"--no-central",
"--max-newton",
"0",
"--damped-coupled-probe",
"--strategy",
"coupled",
"--probe-state",
"/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/nonlinear_step_2026-09-18/late_v1/n1p5_late_eta003/nonlinear_step_physical_base.txt",
"--probe-direction",
"/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/nonlinear_step_2026-09-18/late_v1/n1p5_late_eta003/nonlinear_step_direction_full.txt",
"--linear-tol",
"0.03",
"--restart",
"160",
"--preconditioner-variant",
"gravity-schur",
"--schur-sweeps",
"1",
"--schur-relaxation",
"0.5",
"--gravity-tol",
"1e-10",
"--gravity-iterations",
"300",
"--gravity-restart",
"80",
"--coupled-tol",
"0.03",
"--coupled-iterations",
"160",
"--coupled-restart",
"160",
"--coupled-max-ratio",
"1",
"--coupled-attempts",
"1",
"--coupled-search",
"full"
]
},
{
"id": "late_raw_damped",
"arguments": [
"--index",
"1.5",
"--angular-momentum",
"0",
"--no-central",
"--max-newton",
"0",
"--damped-coupled-probe",
"--strategy",
"coupled",
"--probe-state",
"/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/nonlinear_step_2026-09-18/late_v1/n1p5_late_eta003/nonlinear_step_physical_base.txt",
"--probe-direction",
"/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/nonlinear_step_2026-09-18/late_v1/n1p5_late_eta003/nonlinear_step_direction_full.txt",
"--linear-tol",
"0.03",
"--restart",
"160",
"--preconditioner-variant",
"gravity-schur",
"--schur-sweeps",
"1",
"--schur-relaxation",
"0.5",
"--gravity-tol",
"1e-10",
"--gravity-iterations",
"300",
"--gravity-restart",
"80",
"--coupled-tol",
"0.03",
"--coupled-iterations",
"160",
"--coupled-restart",
"160",
"--coupled-max-ratio",
"1",
"--coupled-attempts",
"1",
"--coupled-search",
"damped"
]
},
{
"id": "late_raw_near",
"arguments": [
"--index",
"1.5",
"--angular-momentum",
"0",
"--no-central",
"--max-newton",
"0",
"--damped-coupled-probe",
"--strategy",
"coupled",
"--probe-state",
"/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/nonlinear_step_2026-09-18/late_v1/n1p5_late_eta003/nonlinear_step_physical_base.txt",
"--probe-direction",
"/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/nonlinear_step_2026-09-18/late_v1/n1p5_late_eta003/nonlinear_step_direction_full.txt",
"--linear-tol",
"0.03",
"--restart",
"160",
"--preconditioner-variant",
"gravity-schur",
"--schur-sweeps",
"1",
"--schur-relaxation",
"0.5",
"--gravity-tol",
"1e-10",
"--gravity-iterations",
"300",
"--gravity-restart",
"80",
"--coupled-tol",
"0.03",
"--coupled-iterations",
"160",
"--coupled-restart",
"160",
"--coupled-max-ratio",
"1",
"--coupled-attempts",
"1",
"--coupled-search",
"near"
]
},
{
"id": "late_curvature_none",
"arguments": [
"--index",
"1.5",
"--angular-momentum",
"0",
"--no-central",
"--max-newton",
"0",
"--damped-coupled-probe",
"--strategy",
"curvature-coupled",
"--probe-state",
"/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/nonlinear_step_2026-09-18/late_v1/n1p5_late_eta003/nonlinear_step_physical_base.txt",
"--probe-direction",
"/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/nonlinear_step_2026-09-18/late_v1/n1p5_late_eta003/nonlinear_step_direction_full.txt",
"--linear-tol",
"0.03",
"--restart",
"160",
"--preconditioner-variant",
"gravity-schur",
"--schur-sweeps",
"1",
"--schur-relaxation",
"0.5",
"--gravity-tol",
"1e-10",
"--gravity-iterations",
"300",
"--gravity-restart",
"80",
"--coupled-tol",
"0.03",
"--coupled-iterations",
"160",
"--coupled-restart",
"160",
"--coupled-max-ratio",
"1",
"--coupled-attempts",
"1",
"--coupled-search",
"none"
]
},
{
"id": "late_curvature_full",
"arguments": [
"--index",
"1.5",
"--angular-momentum",
"0",
"--no-central",
"--max-newton",
"0",
"--damped-coupled-probe",
"--strategy",
"curvature-coupled",
"--probe-state",
"/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/nonlinear_step_2026-09-18/late_v1/n1p5_late_eta003/nonlinear_step_physical_base.txt",
"--probe-direction",
"/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/nonlinear_step_2026-09-18/late_v1/n1p5_late_eta003/nonlinear_step_direction_full.txt",
"--linear-tol",
"0.03",
"--restart",
"160",
"--preconditioner-variant",
"gravity-schur",
"--schur-sweeps",
"1",
"--schur-relaxation",
"0.5",
"--gravity-tol",
"1e-10",
"--gravity-iterations",
"300",
"--gravity-restart",
"80",
"--coupled-tol",
"0.03",
"--coupled-iterations",
"160",
"--coupled-restart",
"160",
"--coupled-max-ratio",
"1",
"--coupled-attempts",
"1",
"--coupled-search",
"full"
]
},
{
"id": "late_curvature_damped",
"arguments": [
"--index",
"1.5",
"--angular-momentum",
"0",
"--no-central",
"--max-newton",
"0",
"--damped-coupled-probe",
"--strategy",
"curvature-coupled",
"--probe-state",
"/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/nonlinear_step_2026-09-18/late_v1/n1p5_late_eta003/nonlinear_step_physical_base.txt",
"--probe-direction",
"/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/nonlinear_step_2026-09-18/late_v1/n1p5_late_eta003/nonlinear_step_direction_full.txt",
"--linear-tol",
"0.03",
"--restart",
"160",
"--preconditioner-variant",
"gravity-schur",
"--schur-sweeps",
"1",
"--schur-relaxation",
"0.5",
"--gravity-tol",
"1e-10",
"--gravity-iterations",
"300",
"--gravity-restart",
"80",
"--coupled-tol",
"0.03",
"--coupled-iterations",
"160",
"--coupled-restart",
"160",
"--coupled-max-ratio",
"1",
"--coupled-attempts",
"1",
"--coupled-search",
"damped"
]
},
{
"id": "late_curvature_near",
"arguments": [
"--index",
"1.5",
"--angular-momentum",
"0",
"--no-central",
"--max-newton",
"0",
"--damped-coupled-probe",
"--strategy",
"curvature-coupled",
"--probe-state",
"/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/nonlinear_step_2026-09-18/late_v1/n1p5_late_eta003/nonlinear_step_physical_base.txt",
"--probe-direction",
"/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/nonlinear_step_2026-09-18/late_v1/n1p5_late_eta003/nonlinear_step_direction_full.txt",
"--linear-tol",
"0.03",
"--restart",
"160",
"--preconditioner-variant",
"gravity-schur",
"--schur-sweeps",
"1",
"--schur-relaxation",
"0.5",
"--gravity-tol",
"1e-10",
"--gravity-iterations",
"300",
"--gravity-restart",
"80",
"--coupled-tol",
"0.03",
"--coupled-iterations",
"160",
"--coupled-restart",
"160",
"--coupled-max-ratio",
"1",
"--coupled-attempts",
"1",
"--coupled-search",
"near"
]
},
{
"id": "seed_curvature_near",
"arguments": [
"--index",
"1.5",
"--angular-momentum",
"0",
"--no-central",
"--max-newton",
"0",
"--damped-coupled-probe",
"--strategy",
"curvature-coupled",
"--probe-state",
"/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/nonlinear_step_2026-09-18/controls_v1/n1p5_seed_eta003/nonlinear_step_physical_base.txt",
"--probe-direction",
"/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/nonlinear_step_2026-09-18/controls_v1/n1p5_seed_eta003/nonlinear_step_direction_full.txt",
"--linear-tol",
"0.03",
"--restart",
"160",
"--preconditioner-variant",
"gravity-schur",
"--schur-sweeps",
"1",
"--schur-relaxation",
"0.5",
"--gravity-tol",
"1e-10",
"--gravity-iterations",
"300",
"--gravity-restart",
"80",
"--coupled-tol",
"0.03",
"--coupled-iterations",
"160",
"--coupled-restart",
"160",
"--coupled-max-ratio",
"1",
"--coupled-attempts",
"1",
"--coupled-search",
"near"
]
}
]

View File

@@ -0,0 +1,117 @@
[
{
"id": "n1_J0",
"arguments": [
"--index",
"1",
"--angular-momentum",
"0",
"--surface-prescription",
"harmonics",
"--surface-degree",
"4",
"--max-newton",
"8",
"--restart",
"160",
"--max-linear",
"200",
"--linear-tol",
"0.03",
"--rtol",
"1e-8",
"--atol",
"0",
"--strategy",
"baseline",
"--density-order-final",
"--no-central"
]
},
{
"id": "n1p5_J0",
"arguments": [
"--index",
"1.5",
"--angular-momentum",
"0",
"--surface-prescription",
"harmonics",
"--surface-degree",
"4",
"--max-newton",
"8",
"--restart",
"160",
"--max-linear",
"200",
"--linear-tol",
"0.03",
"--rtol",
"1e-8",
"--atol",
"0",
"--strategy",
"baseline",
"--density-order-final",
"--no-central"
]
},
{
"id": "n3_J0",
"arguments": [
"--index",
"3",
"--angular-momentum",
"0",
"--surface-prescription",
"harmonics",
"--surface-degree",
"4",
"--max-newton",
"8",
"--restart",
"160",
"--max-linear",
"200",
"--linear-tol",
"0.03",
"--rtol",
"1e-8",
"--atol",
"0",
"--strategy",
"baseline",
"--density-order-final"
]
},
{
"id": "n1_J0p01",
"arguments": [
"--index",
"1",
"--angular-momentum",
"0.01",
"--surface-prescription",
"harmonics",
"--surface-degree",
"4",
"--max-newton",
"8",
"--restart",
"160",
"--max-linear",
"200",
"--linear-tol",
"0.03",
"--rtol",
"1e-8",
"--atol",
"0",
"--strategy",
"baseline",
"--density-order-final",
"--no-central"
]
}
]

View File

@@ -0,0 +1,56 @@
[
{
"id": "n1_equilibrium",
"arguments": [
"--index",
"1",
"--angular-momentum",
"0",
"--surface-prescription",
"harmonics",
"--surface-degree",
"4",
"--no-central",
"--max-newton",
"0",
"--density-order-projection",
"--density-snapshot",
"../../diagnostics/spherical_harmonic_surface_2026-09-19/campaign/n1_J0_L4"
]
},
{
"id": "n1p5_equilibrium",
"arguments": [
"--index",
"1.5",
"--angular-momentum",
"0",
"--surface-prescription",
"harmonics",
"--surface-degree",
"4",
"--no-central",
"--max-newton",
"0",
"--density-order-projection",
"--density-snapshot",
"../../diagnostics/spherical_harmonic_surface_2026-09-19/campaign/n1p5_J0_L4"
]
},
{
"id": "n3_seed",
"arguments": [
"--index",
"3",
"--angular-momentum",
"0",
"--surface-prescription",
"harmonics",
"--surface-degree",
"4",
"--max-newton",
"0",
"--density-order-projection"
]
}
]

View File

@@ -0,0 +1,384 @@
#pragma once
// Frozen-field order controls, not solver recipes. All target spaces borrow the
// same mesh and retain the source enthalpy and deformation without modification.
#include "negative_density_projection.hpp"
#include "density_polynomial_regions.hpp"
#include <iostream>
#include <chrono>
#include <map>
#include <span>
namespace experiment::plateau_diagnostics {
namespace density_order_detail {
namespace projection = negative_density_projection_detail;
using ObserverClock = std::chrono::steady_clock;
inline double Seconds(ObserverClock::time_point start, ObserverClock::time_point finish) {
return std::chrono::duration<double>(finish - start).count();
}
inline void WriteTimings(const std::filesystem::path& path, ObserverClock::time_point start,
ObserverClock::time_point prepared, ObserverClock::time_point errors,
ObserverClock::time_point finished) {
auto out = region::Open(path);
out << "phase,seconds\nsetup_and_projection," << Seconds(start, prepared)
<< "\nindependent_error_quadrature," << Seconds(prepared, errors)
<< "\nregion_observation_and_output," << Seconds(errors, finished)
<< "\nobserver_total," << Seconds(start, finished) << '\n';
}
inline int ValidateState(polytrope_validation::PhysicalState& state, double n, double K) {
const auto& fem = state.finiteElements;
if (!std::isfinite(n) || n < 1 || !std::isfinite(K) || K <= 0 || !fem.mesh || !fem.densityFes ||
!fem.enthalpyFes || !fem.compactificationCoordinate || fem.mesh->Dimension() != 3 || !fem.mesh->Conforming() ||
fem.densityFes->GetVDim() != 1 || dynamic_cast<const mfem::L2_FECollection*>(fem.densityFes->FEColl()) == nullptr ||
state.density.ParFESpace() != fem.densityFes.get() || state.enthalpy.ParFESpace() != fem.enthalpyFes.get())
throw std::invalid_argument("Density order observations require the current conforming 3D scalar L2 state and finite n>=1,K>0.");
int ranks = 0;
MPI_Comm_size(fem.mesh->GetComm(), &ranks);
if (ranks != 1) throw std::invalid_argument("Density order observations require one MPI rank.");
int degree = -1;
for (int element = 0; element < fem.mesh->GetNE(); ++element) if (state.isStellar(element)) {
const auto* fe = fem.densityFes->GetFE(element);
if (!fe || fe->GetOrder() < 2 || fe->GetOrder() > 4 || fe->GetMapType() != mfem::FiniteElement::VALUE ||
fe->GetGeomType() != mfem::Geometry::CUBE || fe->GetDof() != (fe->GetOrder() + 1) * (fe->GetOrder() + 1) * (fe->GetOrder() + 1))
throw std::invalid_argument("Density order observations require scalar VALUE tensor Q2/Q3/Q4 elements.");
if (degree >= 0 && degree != fe->GetOrder()) throw std::invalid_argument("Variable density order is outside this frozen study.");
degree = fe->GetOrder();
}
if (degree < 0) throw std::invalid_argument("Density order observation found no stellar elements.");
return degree;
}
struct SourceCheckpoint final {
mfem::Vector density, enthalpy, potential, gravity, displacement;
explicit SourceCheckpoint(const polytrope_validation::PhysicalState& state)
: density(state.density), enthalpy(state.enthalpy), potential(state.potential),
gravity(state.gravityGradientReference), displacement(state.displacement) {}
void Verify(const polytrope_validation::PhysicalState& state) const {
if (!region::Identical(density, state.density) || !region::Identical(enthalpy, state.enthalpy) ||
!region::Identical(potential, state.potential) || !region::Identical(gravity, state.gravityGradientReference) ||
!region::Identical(displacement, state.displacement))
throw std::logic_error("Density order diagnostic changed a source field.");
}
};
inline void WriteScope(const std::filesystem::path& path, bool projections, int sourceDegree, double n, double K) {
auto out = region::Open(path);
out << "source_fields_bitwise_identical=1\ntrial_preparations=0\nmpi_ranks=1\nsource_density_degree=" << sourceDegree
<< "\nn=" << n << "\nK=" << K << "\nprojection_controls=" << projections << '\n'
<< "All measures use unchanged source enthalpy and physical geometry.\n"
<< "eos_nodal_interpolation is interpolation of rho_EOS(h_h), NOT original Lane-Emden initialization.\n"
<< "eos_l2_q26 uses one fixed order26 rule for both mass and target source at each density order.\n"
<< "Surface records are one-sided samples, not area fractions.\n"
<< "Density coefficients are in different FE spaces; their array differences across orders are not physical norms.\n"
<< "EOS errors and moments are weighted physical integrals; full and negative measures share root-sliced quadrature.\n"
<< "density_order_error_quadrature.csv independently compares unsliced order26/30 EOS error; it should be used for error-norm sensitivity.\n"
<< "Complete EOS integrals are undefined if negative h is sampled; density mass and negative-region measures remain reported.\n"
<< "Projection/interpolation construction rejects negative sampled enthalpy; it does not repair the source.\n"
<< "Root-sliced measures are numerical estimates, not global positivity certificates.\n"
<< "negative_mass_uncertainty_scale is the integral of a coefficient-scaled reconstruction tolerance, not a rigorous bound.\n"
<< "Resolved-negative intervals have a direct FE witness below their reconstruction tolerance; their full volume is still an estimate.\n"
<< "Uncertain shallow intervals and surface values are retained and separately labeled; no density field is clipped.\n"
<< "Near repeated roots and narrow unsampled tangential pockets remain unresolved limitations.\n";
}
struct DegreeFields final {
int degree;
std::unique_ptr<mfem::L2_FECollection> collection;
std::unique_ptr<mfem::ParFiniteElementSpace> space;
std::unique_ptr<mfem::ParGridFunction> interpolation, projection, constant;
mfem::DenseMatrix shapes;
DegreeFields(mfem::ParMesh& mesh, int order, const mfem::IntegrationRule& rule)
: degree(order), collection(std::make_unique<mfem::L2_FECollection>(order, 3, mfem::BasisType::GaussLegendre, mfem::FiniteElement::VALUE)),
space(std::make_unique<mfem::ParFiniteElementSpace>(&mesh, collection.get())),
interpolation(std::make_unique<mfem::ParGridFunction>(space.get())),
projection(std::make_unique<mfem::ParGridFunction>(space.get())),
constant(std::make_unique<mfem::ParGridFunction>(space.get())) {
*interpolation = 0.; *projection = 0.;
mfem::ConstantCoefficient one(1.);
constant->ProjectCoefficient(one);
const auto* fe = collection->FiniteElementForGeometry(mfem::Geometry::CUBE);
shapes.SetSize(fe->GetDof(), rule.GetNPoints());
mfem::Vector shape(fe->GetDof());
for (int q = 0; q < rule.GetNPoints(); ++q) {
fe->CalcShape(rule.IntPoint(q), shape);
for (int i = 0; i < shape.Size(); ++i) shapes(i, q) = shape(i);
}
}
};
struct ErrorField final {
std::string_view label;
int degree;
const mfem::ParGridFunction* density;
};
struct ErrorMeasure final {
Real volume{0}, mass{0}, targetMass{0}, eosSquared{0}, signedEos{0};
Real minimumRho{std::numeric_limits<Real>::infinity()};
double minimumH{std::numeric_limits<double>::infinity()};
std::size_t negativeH{0};
};
inline void ErrorHeader(std::ostream& out) {
out << "control,degree,element,attribute,quadrature_request,quadrature_achieved,quadrature_points,volume,mass,target_mass,"
"eos_squared_integral,signed_eos_integral,minimum_density,minimum_enthalpy,negative_enthalpy_samples,eos_defined_everywhere_sampled\n";
}
inline void WriteError(std::ostream& out, std::string_view label, int degree, int element, int attribute,
int order, const mfem::IntegrationRule& rule, const ErrorMeasure& measure) {
const Real nan = std::numeric_limits<Real>::quiet_NaN();
if (!(measure.volume > 0) || !std::isfinite(measure.volume) || !std::isfinite(measure.mass) ||
!std::isfinite(measure.minimumRho) || !std::isfinite(measure.minimumH) ||
(measure.negativeH == 0 && (!std::isfinite(measure.targetMass) || !std::isfinite(measure.eosSquared) || !std::isfinite(measure.signedEos))))
throw std::runtime_error("Nonfinite independent density error measure.");
out << label << ',' << degree << ',' << element << ',' << attribute << ',' << order << ',' << rule.GetOrder() << ','
<< rule.GetNPoints() << ',' << measure.volume << ',' << measure.mass << ','
<< (measure.negativeH == 0 ? measure.targetMass : nan) << ',' << (measure.negativeH == 0 ? measure.eosSquared : nan) << ','
<< (measure.negativeH == 0 ? measure.signedEos : nan) << ',' << measure.minimumRho << ',' << measure.minimumH << ','
<< measure.negativeH << ',' << (measure.negativeH == 0) << '\n';
}
// A squared EOS error needs more quadrature than either projection moment.
// This pass reuses each mapped sample and reference basis across all supplied
// fields; it does not assemble another matrix or solve another projection.
inline void ObserveErrorRule(polytrope_validation::PhysicalState& state, std::span<const ErrorField> fields,
int order, double n, double K, std::ostream& out) {
const auto& fem = state.finiteElements;
const auto& rule = mfem::IntRules.Get(mfem::Geometry::CUBE, order);
std::map<const mfem::FiniteElement*, std::unique_ptr<mfem::DenseMatrix>> shapeCache;
std::vector<const mfem::DenseMatrix*> shapes(fields.size());
std::vector<mfem::Vector> coefficients(fields.size());
mean_field::mapping::GridFunctionMappingEvaluator mapper(state.domainMapper, state.displacement, *fem.compactificationCoordinate);
mean_field::mapping::MappingPointContext mapped;
for (int element = 0; element < fem.mesh->GetNE(); ++element) {
if (!state.isStellar(element)) continue;
auto* transformation = fem.mesh->GetElementTransformation(element);
for (std::size_t field = 0; field < fields.size(); ++field) {
const auto& density = *fields[field].density;
const auto* fe = density.ParFESpace()->GetFE(element);
if (fe->GetOrder() != fields[field].degree || fe->GetMapType() != mfem::FiniteElement::VALUE || fe->GetGeomType() != mfem::Geometry::CUBE)
throw std::logic_error("Independent density error quadrature received an incompatible scalar field.");
auto& cached = shapeCache[fe];
if (!cached) {
cached = std::make_unique<mfem::DenseMatrix>(fe->GetDof(), rule.GetNPoints());
mfem::Vector shape(fe->GetDof());
for (int q = 0; q < rule.GetNPoints(); ++q) {
fe->CalcShape(rule.IntPoint(q), shape);
for (int i = 0; i < shape.Size(); ++i) (*cached)(i, q) = shape(i);
}
}
shapes[field] = cached.get();
mfem::Array<int> dofs;
auto* dofTransform = density.ParFESpace()->GetElementDofs(element, dofs);
density.GetSubVector(dofs, coefficients[field]);
if (dofTransform) dofTransform->InvTransformPrimal(coefficients[field]);
}
std::vector<ErrorMeasure> measures(fields.size());
for (int q = 0; q < rule.GetNPoints(); ++q) {
const auto& point = rule.IntPoint(q);
if (mapper.EvaluatePoint(*transformation, point, mapped) != mean_field::mapping::MappingStatus::valid || mapped.compactified)
throw std::domain_error("Invalid independent density error mapping.");
const double h = state.enthalpy.GetValue(element, point);
const Real target = EosTarget(h, n, K);
transformation->SetIntPoint(&point);
const double reference = transformation->Jacobian().Det();
const Real weight = static_cast<Real>(point.weight) * reference * mapped.mapping_determinant;
if (!(reference > 0) || !std::isfinite(reference) || !(mapped.mapping_determinant > 0) ||
!std::isfinite(mapped.mapping_determinant) || !(weight > 0) || !std::isfinite(weight))
throw std::domain_error("Invalid independent density error weight.");
for (std::size_t field = 0; field < fields.size(); ++field) {
auto& measure = measures[field];
Real rho = 0;
const auto* shape = shapes[field]->GetColumn(q);
for (int i = 0; i < coefficients[field].Size(); ++i) rho += static_cast<Real>(shape[i]) * coefficients[field](i);
if (!std::isfinite(rho)) throw std::domain_error("Nonfinite independently observed density.");
measure.volume += weight; measure.mass += weight * rho; measure.targetMass += weight * target;
measure.eosSquared += weight * (rho - target) * (rho - target); measure.signedEos += weight * (rho - target);
measure.minimumRho = std::min(measure.minimumRho, rho); measure.minimumH = std::min(measure.minimumH, h);
measure.negativeH += h < 0;
}
}
for (std::size_t field = 0; field < fields.size(); ++field)
WriteError(out, fields[field].label, fields[field].degree, element, fem.mesh->GetAttribute(element), order, rule, measures[field]);
}
out.flush();
}
} // namespace density_order_detail
inline void RecordDensityOrderProjection(polytrope_validation::PhysicalState& state, double n, double K,
const std::filesystem::path& output) {
namespace d = density_order_detail;
const auto observerStart = d::ObserverClock::now();
const int sourceDegree = d::ValidateState(state, n, K);
std::filesystem::create_directories(output);
d::RootSelfChecks(output / "density_order_root_selfchecks.csv");
d::SourceCheckpoint checkpoint(state);
const auto& fem = state.finiteElements;
const auto& rule = mfem::IntRules.Get(mfem::Geometry::CUBE, 26);
std::vector<std::unique_ptr<d::DegreeFields>> controls;
for (int degree : {2, 3, 4}) controls.push_back(std::make_unique<d::DegreeFields>(*fem.mesh, degree, rule));
auto elements = d::region::Open(output / "density_order_projection_elements.csv");
elements << "degree,element,attribute,quadrature_request,quadrature_achieved,quadrature_points,dofs,basis_family,volume,target_mass,"
"interpolation_mass,projection_mass,interpolation_eos_squared,projection_eos_squared,rhs_norm,normal_defect_norm,"
"normal_relative_defect,constant_coefficient_error,constant_sample_error,interpolation_coefficient_minimum,"
"projection_coefficient_minimum,projection_coefficient_maximum\n";
auto nodes = d::region::Open(output / "density_order_nodes.csv");
nodes << "degree,element,local_dof,global_dof,xi,eta,zeta,h,target_rho,interpolation_coefficient,projection_coefficient\n";
auto errorQuadrature = d::region::Open(output / "density_order_error_quadrature.csv");
d::ErrorHeader(errorQuadrature);
mean_field::mapping::GridFunctionMappingEvaluator mapper(state.domainMapper, state.displacement, *fem.compactificationCoordinate);
mean_field::mapping::MappingPointContext mapped;
mfem::Vector weights(rule.GetNPoints()), targets(rule.GetNPoints());
for (int element = 0; element < fem.mesh->GetNE(); ++element) {
if (!state.isStellar(element)) continue;
auto* transformation = fem.mesh->GetElementTransformation(element);
// Geometry and EOS evaluation dominate observer cost; share these
// samples across target orders without sharing their independent M,b.
long double volume = 0, targetMass = 0;
double minimumH = std::numeric_limits<double>::infinity();
for (int q = 0; q < rule.GetNPoints(); ++q) {
const auto& point = rule.IntPoint(q);
if (mapper.EvaluatePoint(*transformation, point, mapped) != mean_field::mapping::MappingStatus::valid || mapped.compactified)
throw std::domain_error("Invalid density order projection mapping.");
const double h = state.enthalpy.GetValue(element, point);
if (!std::isfinite(h) || h < 0) throw std::domain_error("Density order projection encountered inadmissible sampled enthalpy.");
targets(q) = d::EosTarget(h, n, K);
minimumH = std::min(minimumH, h);
transformation->SetIntPoint(&point);
const double reference = transformation->Jacobian().Det();
weights(q) = point.weight * reference * mapped.mapping_determinant;
if (!(reference > 0) || !std::isfinite(reference) || !(mapped.mapping_determinant > 0) ||
!std::isfinite(mapped.mapping_determinant) || !(weights(q) > 0) || !std::isfinite(weights(q)))
throw std::domain_error("Invalid density order projection weight.");
volume += weights(q); targetMass += static_cast<long double>(weights(q)) * targets(q);
}
for (auto& control : controls) {
const auto* fe = control->space->GetFE(element);
const int size = fe->GetDof();
mfem::Array<int> dofs;
if (control->space->GetElementDofs(element, dofs) != nullptr || dofs.Size() != size)
throw std::invalid_argument("Density order projection requires untransformed scalar DG element DOFs.");
for (int i = 0; i < size; ++i) if (dofs[i] < 0) throw std::logic_error("Unexpected signed DG density DOF.");
mfem::Vector interpolated(size), nodalH(size), rhs(size), constantRhs(size), constantExpected;
const auto& nodalRule = fe->GetNodes();
if (nodalRule.GetNPoints() != size) throw std::logic_error("Density target collection is not nodal.");
for (int i = 0; i < size; ++i) {
nodalH(i) = state.enthalpy.GetValue(element, nodalRule.IntPoint(i));
if (!std::isfinite(nodalH(i)) || nodalH(i) < 0)
throw std::domain_error("Density order nodal interpolation encountered inadmissible enthalpy.");
interpolated(i) = d::EosTarget(nodalH(i), n, K);
}
mfem::DenseMatrix mass(size);
mass = 0.; rhs = 0.; constantRhs = 0.;
for (int q = 0; q < rule.GetNPoints(); ++q) {
const auto* shape = control->shapes.GetColumn(q);
for (int j = 0; j < size; ++j) {
const double weighted = weights(q) * shape[j];
rhs(j) += weighted * targets(q); constantRhs(j) += weighted;
auto* column = mass.GetColumn(j);
for (int i = 0; i <= j; ++i) column[i] += weighted * shape[i];
}
}
for (int j = 0; j < size; ++j) for (int i = 0; i < j; ++i) mass(j, i) = mass(i, j);
const auto lower = d::projection::Factor(mass);
const auto projected = d::projection::Solve(lower, rhs), constant = d::projection::Solve(lower, constantRhs);
const auto defect = d::projection::Defect(mass, projected, rhs);
d::projection::VerifySolve(mass, projected, rhs, defect);
d::projection::VerifySolve(mass, constant, constantRhs, d::projection::Defect(mass, constant, constantRhs));
control->constant->GetSubVector(dofs, constantExpected);
double constantError = 0, constantSampleError = 0;
for (int i = 0; i < size; ++i) constantError = std::max(constantError, std::abs(constant(i) - constantExpected(i)));
long double interpolationMass = 0, projectionMass = 0, interpolationError = 0, projectionError = 0;
d::ErrorMeasure interpolationMeasure, projectionMeasure;
interpolationMeasure.volume = projectionMeasure.volume = volume;
interpolationMeasure.targetMass = projectionMeasure.targetMass = targetMass;
interpolationMeasure.minimumH = projectionMeasure.minimumH = minimumH;
for (int q = 0; q < rule.GetNPoints(); ++q) {
long double interpolatedValue = 0, projectedValue = 0, constantValue = 0;
for (int i = 0; i < size; ++i) {
const double shape = control->shapes(i, q);
interpolatedValue += static_cast<long double>(shape) * interpolated(i);
projectedValue += static_cast<long double>(shape) * projected(i);
constantValue += static_cast<long double>(shape) * constant(i);
}
interpolationMass += weights(q) * interpolatedValue; projectionMass += weights(q) * projectedValue;
interpolationError += weights(q) * (interpolatedValue - targets(q)) * (interpolatedValue - targets(q));
projectionError += weights(q) * (projectedValue - targets(q)) * (projectedValue - targets(q));
interpolationMeasure.signedEos += weights(q) * (interpolatedValue - targets(q));
projectionMeasure.signedEos += weights(q) * (projectedValue - targets(q));
interpolationMeasure.minimumRho = std::min(interpolationMeasure.minimumRho, interpolatedValue);
projectionMeasure.minimumRho = std::min(projectionMeasure.minimumRho, projectedValue);
constantSampleError = std::max(constantSampleError, static_cast<double>(std::abs(constantValue - 1)));
}
if (!std::isfinite(constantError) || !std::isfinite(constantSampleError) || constantError > 1e-10 || constantSampleError > 1e-10)
throw std::runtime_error("Density order projection failed independent constant reconstruction.");
control->interpolation->SetSubVector(dofs, interpolated); control->projection->SetSubVector(dofs, projected);
interpolationMeasure.mass = interpolationMass; interpolationMeasure.eosSquared = interpolationError;
projectionMeasure.mass = projectionMass; projectionMeasure.eosSquared = projectionError;
d::WriteError(errorQuadrature, "eos_nodal_interpolation", control->degree, element, fem.mesh->GetAttribute(element), 26, rule, interpolationMeasure);
d::WriteError(errorQuadrature, "eos_l2_q26", control->degree, element, fem.mesh->GetAttribute(element), 26, rule, projectionMeasure);
const double rhsNorm = d::projection::Norm(rhs), defectNorm = d::projection::Norm(defect);
elements << control->degree << ',' << element << ',' << fem.mesh->GetAttribute(element) << ",26," << rule.GetOrder() << ','
<< rule.GetNPoints() << ',' << size << ',' << std::quoted(control->collection->Name()) << ',' << volume << ',' << targetMass << ','
<< interpolationMass << ',' << projectionMass << ',' << interpolationError << ',' << projectionError << ','
<< rhsNorm << ',' << defectNorm << ',' << d::projection::Relative(defectNorm, rhsNorm) << ',' << constantError << ','
<< constantSampleError << ',' << interpolated.Min() << ',' << projected.Min() << ',' << projected.Max() << '\n';
for (int i = 0; i < size; ++i) {
const auto& point = nodalRule.IntPoint(i);
nodes << control->degree << ',' << element << ',' << i << ',' << dofs[i] << ',' << point.x << ',' << point.y << ',' << point.z
<< ',' << nodalH(i) << ',' << interpolated(i) << ',' << interpolated(i) << ',' << projected(i) << '\n';
}
}
}
elements.flush(); nodes.flush(); errorQuadrature.flush();
std::vector<d::ErrorField> errorFields;
for (const auto& control : controls) {
errorFields.push_back({"eos_nodal_interpolation", control->degree, control->interpolation.get()});
errorFields.push_back({"eos_l2_q26", control->degree, control->projection.get()});
}
const auto projectionsFinished = d::ObserverClock::now();
d::ObserveErrorRule(state, errorFields, 30, n, K, errorQuadrature);
const auto errorObservationFinished = d::ObserverClock::now();
d::Outputs observations(output);
for (const auto& control : controls) {
std::cout << "Frozen density order Q" << control->degree << " interpolation/projection observations" << std::endl;
const auto degree = std::to_string(control->degree);
d::projection::WriteVector(output / ("density_order_Q" + degree + "_eos_nodal_interpolation_coefficients.txt"), *control->interpolation);
d::projection::WriteVector(output / ("density_order_Q" + degree + "_eos_l2_q26_coefficients.txt"), *control->projection);
d::Observe(state, *control->interpolation, control->degree, "eos_nodal_interpolation", n, K, observations);
d::Observe(state, *control->projection, control->degree, "eos_l2_q26", n, K, observations);
}
checkpoint.Verify(state);
d::WriteScope(output / "density_order_scope.txt", true, sourceDegree, n, K);
d::WriteTimings(output / "density_order_timings.csv", observerStart, projectionsFinished,
errorObservationFinished, d::ObserverClock::now());
}
inline void RecordDensityOrderState(polytrope_validation::PhysicalState& state, double n, double K,
const std::filesystem::path& output) {
namespace d = density_order_detail;
const auto observerStart = d::ObserverClock::now();
const int degree = d::ValidateState(state, n, K);
std::filesystem::create_directories(output);
d::RootSelfChecks(output / "density_order_root_selfchecks.csv");
d::SourceCheckpoint checkpoint(state);
auto errorQuadrature = d::region::Open(output / "density_order_error_quadrature.csv");
d::ErrorHeader(errorQuadrature);
const std::array<d::ErrorField, 1> errorFields{{{"stored_density", degree, &state.density}}};
const auto setupFinished = d::ObserverClock::now();
for (int order : {26, 30}) d::ObserveErrorRule(state, errorFields, order, n, K, errorQuadrature);
const auto errorObservationFinished = d::ObserverClock::now();
d::Outputs observations(output);
d::Observe(state, state.density, degree, "stored_density", n, K, observations);
d::projection::WriteVector(output / "density_order_stored_density_coefficients.txt", state.density);
checkpoint.Verify(state);
d::WriteScope(output / "density_order_scope.txt", false, degree, n, K);
d::WriteTimings(output / "density_order_timings.csv", observerStart, setupFinished,
errorObservationFinished, d::ObserverClock::now());
}
} // namespace experiment::plateau_diagnostics

View File

@@ -0,0 +1,383 @@
#pragma once
// Diagnostic-only extension of the Q2 slice observer. A monotonic partition
// from derivative roots handles degrees three and four without sampling a sign
// indicator or relying on a particular closed-form cubic/quartic formula.
#include "negative_density_regions.hpp"
#include <string_view>
namespace experiment::plateau_diagnostics::density_order_detail {
namespace region = negative_density_regions_detail;
using Real = region::Real;
struct Polynomial final {
std::array<Real, 5> coefficients{};
int degree{0};
[[nodiscard]] Real Value(Real x) const {
Real value = coefficients[degree], correction = 0;
for (int j = degree - 1; j >= 0; --j) {
const Real product = value * x;
const Real productError = std::fma(value, x, -product);
const Real sum = product + coefficients[j];
const Real sumError = std::abs(product) >= std::abs(coefficients[j])
? (product - sum) + coefficients[j] : (coefficients[j] - sum) + product;
correction = std::fma(correction, x, productError + sumError);
value = sum;
}
// Compensated Horner retains the sign of shallow pockets without
// assuming long double has a wider mantissa on Apple arm64.
return value + correction;
}
[[nodiscard]] Real Scale() const {
Real result = 0;
for (int j = 0; j <= degree; ++j) result += std::abs(coefficients[j]);
return result;
}
[[nodiscard]] Polynomial Derivative() const {
Polynomial result;
result.degree = std::max(0, degree - 1);
for (int j = 1; j <= degree; ++j) result.coefficients[j - 1] = j * coefficients[j];
return result;
}
[[nodiscard]] Real Integral(Real left, Real right) const {
constexpr int binomial[5][5]{{1}, {1, 1}, {1, 2, 1}, {1, 3, 3, 1}, {1, 4, 6, 4, 1}};
const Real width = right - left, middle = left + width / 2;
Real mean = Value(middle);
for (int k = 2; k <= degree; k += 2) {
Real translated = 0;
for (int j = degree; j >= k; --j)
translated = std::fma(translated, middle, binomial[j][k] * coefficients[j]);
mean += translated * std::pow(width / 2, k) / (k + 1);
}
return width * mean;
}
};
inline Polynomial Interpolate(const std::array<double, 5>& values, int degree) {
if (degree < 2 || degree > 4) throw std::invalid_argument("Density slice degree must be two, three, or four.");
std::array<Real, 5> nodes{}, divided{}, basis{};
for (int i = 0; i <= degree; ++i) {
nodes[i] = static_cast<double>(i) / degree;
divided[i] = values[i];
if (!std::isfinite(values[i])) throw std::domain_error("Nonfinite density interpolation value.");
}
for (int width = 1; width <= degree; ++width)
for (int i = degree; i >= width; --i)
divided[i] = (divided[i] - divided[i - 1]) / (nodes[i] - nodes[i - width]);
Polynomial result;
result.degree = degree;
basis[0] = 1;
for (int k = 0; k <= degree; ++k) {
for (int j = 0; j <= k; ++j) result.coefficients[j] += divided[k] * basis[j];
if (k == degree) break;
for (int j = k + 1; j > 0; --j) basis[j] = basis[j - 1] - nodes[k] * basis[j];
basis[0] *= -nodes[k];
}
return result;
}
inline std::vector<Real> Roots(Polynomial polynomial) {
while (polynomial.degree > 0 && polynomial.coefficients[polynomial.degree] == 0) --polynomial.degree;
const Real scale = polynomial.Scale();
if (!std::isfinite(scale)) throw std::domain_error("Nonfinite density polynomial coefficients.");
if (polynomial.degree == 0 || scale == 0) return {};
int exponent = 0;
(void)std::frexp(scale, &exponent);
// A power-of-two rescaling preserves the represented polynomial. Dividing
// by an arbitrary norm can create a pocket at an exact repeated root.
for (int j = 0; j <= polynomial.degree; ++j)
polynomial.coefficients[j] = std::scalbn(polynomial.coefficients[j], -exponent);
if (polynomial.degree == 1) {
const Real root = -polynomial.coefficients[0] / polynomial.coefficients[1];
return std::isfinite(root) && root >= 0 && root <= 1 ? std::vector<Real>{root} : std::vector<Real>{};
}
std::vector<Real> partition{0, 1};
for (Real point : Roots(polynomial.Derivative())) if (point > 0 && point < 1) partition.push_back(point);
std::sort(partition.begin(), partition.end());
partition.erase(std::unique(partition.begin(), partition.end()), partition.end());
std::vector<Real> result;
for (Real point : partition) if (polynomial.Value(point) == 0) result.push_back(point);
for (std::size_t i = 1; i < partition.size(); ++i) {
Real left = partition[i - 1], right = partition[i];
Real fleft = polynomial.Value(left), fright = polynomial.Value(right);
if (fleft == 0 || fright == 0 || (fleft < 0) == (fright < 0)) continue;
// No value tolerance declares a critical point to be zero. Doing so
// could erase both roots of a shallow pocket next to that critical point.
for (int iteration = 0; iteration < 128; ++iteration) {
const Real middle = left + (right - left) / 2;
if (middle == left || middle == right) break;
const Real value = polynomial.Value(middle);
if (value == 0) { left = right = middle; break; }
if ((value < 0) == (fleft < 0)) { left = middle; fleft = value; }
else { right = middle; fright = value; }
}
result.push_back(std::abs(polynomial.Value(left)) <= std::abs(polynomial.Value(right)) ? left : right);
}
std::sort(result.begin(), result.end());
result.erase(std::unique(result.begin(), result.end()), result.end());
return result;
}
inline std::vector<region::Interval> Partition(const Polynomial& polynomial) {
std::vector<Real> points{0, 1};
for (Real root : Roots(polynomial)) if (root > 0 && root < 1) points.push_back(root);
std::sort(points.begin(), points.end());
points.erase(std::unique(points.begin(), points.end()), points.end());
std::vector<region::Interval> result;
for (std::size_t j = 1; j < points.size(); ++j) {
const Real left = points[j - 1], right = points[j];
const bool negative = polynomial.Value(left + (right - left) / 2) < 0;
for (Real fraction : {Real{0.25}, Real{0.75}}) {
const Real value = polynomial.Value(left + fraction * (right - left));
if ((negative && value > 0) || (!negative && value < 0))
throw std::runtime_error("Density polynomial root partition has inconsistent signs.");
}
result.push_back({left, right, negative});
}
return result;
}
inline void RootSelfChecks(const std::filesystem::path& path) {
auto out = region::Open(path);
out << "case,degree,negative_length,expected_negative_length,negative_mass,expected_negative_mass,passed\n";
const auto check = [&](const char* name, Polynomial polynomial, Real expectedLength, Real expectedMass) {
Real length = 0, mass = 0;
for (const auto& interval : Partition(polynomial)) if (interval.negative) {
length += interval.right - interval.left;
mass -= polynomial.Integral(interval.left, interval.right);
}
const bool passed = std::abs(length - expectedLength) < 2e-11L * std::max(Real{1e-8}, expectedLength) &&
std::abs(mass - expectedMass) < 2e-10L * std::max(Real{1e-8}, expectedMass);
out << name << ',' << polynomial.degree << ',' << length << ',' << expectedLength << ',' << mass << ',' << expectedMass << ',' << passed << '\n';
if (!passed) throw std::runtime_error(std::string("General density root self-check failed: ") + name);
};
check("positive_constant", {{{1}}, 0}, 0, 0);
check("negative_constant", {{{-2}}, 0}, 1, 2);
check("linear_crossing", {{{-0.25L, 1}}, 1}, 0.25L, 0.03125L);
check("quadratic_interior_pocket", {{{0.05L, -0.6L, 1.5L}}, 2}, std::sqrt(Real{6}) / 15, std::sqrt(Real{6}) / 2250);
check("cubic_interior_pocket", {{{0, 3.0L / 16, -1, 1}}, 3}, 0.5L, 1.0L / 96);
check("quartic_two_pockets", {{{105.0L / 4096, -11.0L / 32, 43.0L / 32, -2, 1}}, 4}, 0.5L, 19.0L / 15360);
check("quartic_double_roots_nonnegative", {{{9.0L / 256, -3.0L / 8, 11.0L / 8, -2, 1}}, 4}, 0, 0);
// Independently check the power-basis reconstruction, including its highest
// degree, rather than testing only roots of hand-entered coefficient arrays.
for (int degree : {2, 3, 4}) {
std::array<double, 5> values{};
for (int i = 0; i <= degree; ++i) values[i] = std::pow(static_cast<double>(i) / degree, degree);
const auto p = Interpolate(values, degree);
for (Real t : {Real{0.13}, Real{0.37}, Real{0.81}})
if (std::abs(p.Value(t) - std::pow(t, degree)) > 2e-14L)
throw std::runtime_error("Density polynomial interpolation self-check failed.");
out << "reconstruct_t_power_" << degree << ',' << degree << ",0,0,0,0,1\n";
}
}
struct Outputs final {
std::ofstream elements, summary, intervals, surface;
explicit Outputs(const std::filesystem::path& output)
: elements(region::Open(output / "density_order_elements.csv")),
summary(region::Open(output / "density_order_summary.csv")),
intervals(region::Open(output / "density_order_intervals.csv")),
surface(region::Open(output / "density_order_surface.csv")) {
constexpr auto extra = "target_mass,eos_squared_integral,signed_eos_integral,negative_mass_uncertainty_scale,"
"first_moment_x,first_moment_y,first_moment_z,inertia_z,minimum_enthalpy,negative_enthalpy_samples,"
"eos_defined_everywhere_sampled,resolved_negative_intervals,uncertain_negative_intervals,"
"resolved_witness_negative_volume,resolved_witness_negative_mass,uncertain_negative_volume,uncertain_negative_mass,";
elements << "control,degree,tangential_order,interval_order,element,attribute,axis,orientation,surface_face," << extra;
region::Header(elements);
summary << "control,degree,tangential_order,interval_order," << extra;
region::Header(summary);
intervals << "control,degree,element,axis,orientation,u,v,t_left,t_right,c0,c1,c2,c3,c4,negative_volume,negative_mass,"
"minimum_density,witness_h,reconstruction_tolerance,resolved_negative_witness\n";
surface << "control,degree,face,element,u,v,rho,h,rho_eos,error,eos_defined,reconstruction_tolerance,resolved_negative\n";
}
};
struct Extra final {
Real targetMass{0}, eosSquared{0}, signedEos{0}, uncertainty{0};
std::array<Real, 3> firstMoment{};
Real inertiaZ{0};
double minimumH{std::numeric_limits<double>::infinity()};
std::size_t negativeH{0};
std::size_t resolvedNegativeIntervals{0}, uncertainNegativeIntervals{0};
Real resolvedVolume{0}, resolvedMass{0}, uncertainVolume{0}, uncertainMass{0};
void Add(const Extra& other) {
targetMass += other.targetMass; eosSquared += other.eosSquared; signedEos += other.signedEos; uncertainty += other.uncertainty;
inertiaZ += other.inertiaZ; minimumH = std::min(minimumH, other.minimumH); negativeH += other.negativeH;
resolvedNegativeIntervals += other.resolvedNegativeIntervals; uncertainNegativeIntervals += other.uncertainNegativeIntervals;
resolvedVolume += other.resolvedVolume; resolvedMass += other.resolvedMass;
uncertainVolume += other.uncertainVolume; uncertainMass += other.uncertainMass;
for (int d = 0; d < 3; ++d) firstMoment[d] += other.firstMoment[d];
}
void Write(std::ostream& out) const {
const Real nan = std::numeric_limits<Real>::quiet_NaN();
out << (negativeH == 0 ? targetMass : nan) << ',' << (negativeH == 0 ? eosSquared : nan) << ','
<< (negativeH == 0 ? signedEos : nan) << ',' << uncertainty << ',';
for (Real value : firstMoment) out << value << ',';
out << inertiaZ << ',' << minimumH << ',' << negativeH << ',' << (negativeH == 0) << ','
<< resolvedNegativeIntervals << ',' << uncertainNegativeIntervals << ',' << resolvedVolume << ',' << resolvedMass << ','
<< uncertainVolume << ',' << uncertainMass << ',';
}
};
inline double EosTarget(double h, double n, double K) {
if (!std::isfinite(h)) throw std::domain_error("Nonfinite enthalpy in density order observer.");
const double rho = h > 0 ? std::pow(h / ((n + 1) * K), n) : 0;
if (!std::isfinite(rho)) throw std::domain_error("Nonfinite EOS target in density order observer.");
return rho;
}
inline void Observe(polytrope_validation::PhysicalState& state, const mfem::ParGridFunction& density,
int degree, std::string_view label, double n, double K, Outputs& output) {
const auto& fem = state.finiteElements;
const auto axes = region::ChooseAxes(state);
mean_field::mapping::GridFunctionMappingEvaluator mapper(state.domainMapper, state.displacement, *fem.compactificationCoordinate);
mean_field::mapping::MappingPointContext mapped;
const auto& intervalRule = mfem::IntRules.Get(mfem::Geometry::SEGMENT, 14);
for (int order : {14, 22, 30}) {
const auto& tangentRule = mfem::IntRules.Get(mfem::Geometry::SEGMENT, order);
region::Measure global;
Extra globalExtra;
for (int element = 0; element < fem.mesh->GetNE(); ++element) {
if (!state.isStellar(element)) continue;
const auto& axis = axes[static_cast<std::size_t>(element)];
auto* transformation = fem.mesh->GetElementTransformation(element);
region::Measure local;
Extra localExtra;
for (int iu = 0; iu < tangentRule.GetNPoints(); ++iu) for (int iv = 0; iv < tangentRule.GetNPoints(); ++iv) {
const auto& up = tangentRule.IntPoint(iu);
const auto& vp = tangentRule.IntPoint(iv);
const double u = up.x, v = vp.x;
std::array<double, 5> values{};
for (int i = 0; i <= degree; ++i) values[i] = density.GetValue(element, region::Point(axis, u, v, static_cast<double>(i) / degree));
const auto polynomial = Interpolate(values, degree);
const Real tolerance = 2048 * std::numeric_limits<double>::epsilon() * polynomial.Scale();
const auto verify = [&](Real t, double rho) {
const Real error = std::abs(polynomial.Value(t) - rho);
local.maximumReconstructionError = std::max(local.maximumReconstructionError, static_cast<double>(error));
local.maximumReconstructionTolerance = std::max(local.maximumReconstructionTolerance, static_cast<double>(tolerance));
if (!std::isfinite(rho) || error > tolerance) throw std::runtime_error("Density order slice reconstruction failed.");
};
for (Real t : {Real{0.07}, Real{0.19}, Real{0.41}, Real{0.63}, Real{0.87}, Real{0.97}})
verify(t, density.GetValue(element, region::Point(axis, u, v, t)));
++local.lines;
const auto critical = Roots(polynomial.Derivative());
const auto evaluate = [&](Real t, region::Measure& piece, bool negative) {
const auto point = region::Point(axis, u, v, t);
if (mapper.EvaluatePoint(*transformation, point, mapped) != mean_field::mapping::MappingStatus::valid || mapped.compactified)
throw std::domain_error("Invalid density order mapping.");
const double rho = density.GetValue(element, point), h = state.enthalpy.GetValue(element, point);
verify(t, rho);
if (!std::isfinite(h)) throw std::domain_error("Nonfinite density order enthalpy.");
if (rho < piece.minimumRho) {
piece.minimumRho = rho; piece.witnessH = h; piece.witnessElement = element;
piece.witnessT = static_cast<double>(t); piece.witnessU = u; piece.witnessV = v;
for (int d = 0; d < 3; ++d) piece.witnessPosition[d] = mapped.physical_position(d);
}
if (negative) {
const double radius = mapped.physical_position.Norml2();
piece.negativeRadiusMin = std::min(piece.negativeRadiusMin, radius);
piece.negativeRadiusMax = std::max(piece.negativeRadiusMax, radius);
}
transformation->SetIntPoint(&point);
const double reference = transformation->Jacobian().Det();
const Real determinant = static_cast<Real>(reference) * mapped.mapping_determinant;
if (!(reference > 0) || !std::isfinite(reference) || !(mapped.mapping_determinant > 0) ||
!std::isfinite(mapped.mapping_determinant) || !std::isfinite(determinant))
throw std::domain_error("Invalid density order physical measure.");
return std::pair{determinant, h};
};
for (const auto& part : Partition(polynomial)) {
region::Measure piece;
(void)evaluate(part.left, piece, part.negative);
(void)evaluate(part.right, piece, part.negative);
for (Real point : critical) if (point > part.left && point < part.right) (void)evaluate(point, piece, part.negative);
for (int iq = 0; iq < intervalRule.GetNPoints(); ++iq) {
const auto& qp = intervalRule.IntPoint(iq);
const Real t = part.left + (part.right - part.left) * qp.x;
const auto [determinant, h] = evaluate(t, piece, part.negative);
const Real weight = static_cast<Real>(up.weight) * vp.weight * qp.weight * (part.right - part.left) * determinant;
const Real rho = polynomial.Value(t), target = EosTarget(h, n, K);
if (!(weight > 0) || !std::isfinite(weight) || !std::isfinite(rho) ||
(part.negative && rho > 0) || (!part.negative && rho < 0))
throw std::runtime_error("Density order interval quadrature has an inconsistent sign.");
piece.volume += weight; piece.mass += weight * rho; ++piece.points;
localExtra.targetMass += weight * target;
localExtra.eosSquared += weight * (rho - target) * (rho - target);
localExtra.signedEos += weight * (rho - target);
localExtra.uncertainty += weight * tolerance;
localExtra.minimumH = std::min(localExtra.minimumH, h);
localExtra.negativeH += h < 0;
for (int d = 0; d < 3; ++d) localExtra.firstMoment[d] += weight * rho * mapped.physical_position(d);
localExtra.inertiaZ += weight * rho * (static_cast<Real>(mapped.physical_position(0)) * mapped.physical_position(0) +
static_cast<Real>(mapped.physical_position(1)) * mapped.physical_position(1));
}
if (part.negative) {
piece.negativeIntervals = 1; piece.negativeVolume = piece.volume; piece.negativeMass = -piece.mass;
piece.negativeTMin = part.left; piece.negativeTMax = part.right;
const bool resolved = piece.minimumRho < -tolerance;
if (resolved) {
++localExtra.resolvedNegativeIntervals;
localExtra.resolvedVolume += piece.negativeVolume; localExtra.resolvedMass += piece.negativeMass;
} else {
++localExtra.uncertainNegativeIntervals;
localExtra.uncertainVolume += piece.negativeVolume; localExtra.uncertainMass += piece.negativeMass;
}
if (order == 30) {
output.intervals << label << ',' << degree << ',' << element << ',' << axis.coordinate << ',' << axis.orientation
<< ',' << u << ',' << v << ',' << part.left << ',' << part.right;
for (Real coefficient : polynomial.coefficients) output.intervals << ',' << coefficient;
output.intervals << ',' << piece.negativeVolume << ',' << piece.negativeMass << ',' << piece.minimumRho << ','
<< piece.witnessH << ',' << tolerance << ',' << resolved << '\n';
}
}
local.Add(piece);
}
}
if (!(local.volume > 0) || !std::isfinite(local.mass) || !std::isfinite(local.negativeMass))
throw std::runtime_error("Nonfinite density order region integral.");
output.elements << label << ',' << degree << ',' << order << ",14," << element << ',' << fem.mesh->GetAttribute(element) << ','
<< axis.coordinate << ',' << axis.orientation << ',' << axis.face << ',';
localExtra.Write(output.elements); region::Write(output.elements, local);
global.Add(local); globalExtra.Add(localExtra);
}
if (!(global.volume > 0)) throw std::runtime_error("Density order observer found no stellar volume.");
output.summary << label << ',' << degree << ',' << order << ",14,";
globalExtra.Write(output.summary); region::Write(output.summary, global);
output.summary.flush(); output.elements.flush(); output.intervals.flush();
}
// These are one-sided field traces on every stellar/nonstellar face, not
// surface-area samples. They expose extrapolation defects missed by nodes.
for (int face = 0; face < fem.mesh->GetNumFaces(); ++face) {
int left = -1, right = -1;
fem.mesh->GetFaceElements(face, &left, &right);
const bool leftStar = left >= 0 && state.isStellar(left), rightStar = right >= 0 && state.isStellar(right);
if (leftStar == rightStar) continue;
const int element = leftStar ? left : right;
auto* transformation = fem.mesh->GetFaceElementTransformations(face);
mfem::Array<int> dofs;
auto* dofTransform = density.ParFESpace()->GetElementDofs(element, dofs);
mfem::Vector coefficients, shape(dofs.Size());
density.GetSubVector(dofs, coefficients);
if (dofTransform) dofTransform->InvTransformPrimal(coefficients);
const auto* fe = density.ParFESpace()->GetFE(element);
for (double u : {0., .25, .5, .75, 1.}) for (double v : {0., .25, .5, .75, 1.}) {
mfem::IntegrationPoint facePoint, point;
facePoint.Set2(u, v);
if (leftStar) transformation->Loc1.Transform(facePoint, point); else transformation->Loc2.Transform(facePoint, point);
const double rho = density.GetValue(element, point), h = state.enthalpy.GetValue(element, point);
if (!std::isfinite(h)) throw std::domain_error("Nonfinite density order surface enthalpy.");
const double target = h >= 0 ? EosTarget(h, n, K) : std::numeric_limits<double>::quiet_NaN();
if (!std::isfinite(rho)) throw std::domain_error("Nonfinite density order surface trace.");
fe->CalcShape(point, shape);
Real magnitude = 0;
for (int i = 0; i < shape.Size(); ++i) magnitude += std::abs(static_cast<Real>(shape(i)) * coefficients(i));
const Real tolerance = 2048 * std::numeric_limits<double>::epsilon() * magnitude;
output.surface << label << ',' << degree << ',' << face << ',' << element << ',' << u << ',' << v << ','
<< rho << ',' << h << ',' << target << ',' << rho - target << ',' << (h >= 0) << ',' << tolerance << ',' << (rho < -tolerance) << '\n';
}
}
output.surface.flush();
}
} // namespace experiment::plateau_diagnostics::density_order_detail

View File

@@ -0,0 +1,78 @@
#pragma once
// Include after the benchmark and physical-snapshot helpers. Each observation
// starts from the same prepared physical state; nothing is accepted or clipped.
namespace experiment::plateau_diagnostics {
template <class State>
void RecordHarmonicLinearTrials(State &state, const mean_field::fem::FEM &fem,
const std::filesystem::path &output, double index) {
namespace d = preconditioner_benchmark_detail;
const mfem::Vector base(state.trialNormalizedState), residual(state.trialNormalizedResidual),
savedCorrection(state.normalizedCorrection), accepted(state.AcceptedPhysicalState());
mfem::Vector physicalBase;
state.normalizedOperator->DenormalizeState(base, physicalBase);
const auto restore = [&] {
state.trialNormalizedState = base;
if (!state.PrepareTrial()) throw std::runtime_error("Linear trial base cannot be restored");
};
auto trials = d::Open(output / "linear_direction_trials.csv");
trials << "role,alpha,prepared,reason,stage,base_norm,trial_norm,relative_norm,linear_defect_relative,"
"direction_norm,action_norm,merit_slope,remainder_norm,remainder_over_alpha,"
"predicted_norm,signed_remainder_projection,merit_identity_error,decrease_screen\n";
auto blocks = d::Open(output / "linear_direction_trial_blocks.csv");
blocks << "role,alpha,block,base_norm,action_norm,trial_norm,remainder_norm\n";
auto bounds = d::Open(output / "linear_direction_enthalpy_bounds.csv");
bounds << "role,metric,value\n";
for (const std::string role : {"baseline", "candidate"}) {
restore();
const auto correction = coupled_physical_detail::Load(output / (role + "_normalized_correction.txt"), base.Size());
mfem::Vector action(base.Size()), defect(base.Size());
state.normalizedOperator->Mult(correction, action);
defect = action; defect += residual;
const double relative = defect.Norml2() / residual.Norml2();
const double slope = residual * action;
state.normalizedCorrection = correction;
for (const auto &[key, value] : MeasureEnthalpyStep(state, fem, index, &physicalBase))
bounds << role << ',' << key << ',' << value << '\n';
d::Save(output / (role + "_trial_jacobian_action.txt"), action);
for (const double alpha : {1., .25, .0625, .015625, .00390625, .0009765625, .000244140625}) {
restore();
state.trialNormalizedState = base;
state.trialNormalizedState.Add(alpha, correction);
const auto prepared = state.PrepareTrial();
trials << role << ',' << alpha << ',' << prepared.has_value() << ','
<< (prepared ? -1 : int(prepared.error().reason)) << ','
<< (prepared ? -1 : int(prepared.error().stage)) << ',' << residual.Norml2() << ',';
if (!prepared) {
trials << "nan,nan," << relative << ',' << correction.Norml2() << ',' << action.Norml2()
<< ',' << slope << ",nan,nan,nan,nan,nan,0\n";
continue;
}
const mfem::Vector trial(state.trialNormalizedResidual);
mfem::Vector prediction(residual), remainder(trial);
prediction.Add(alpha, action);
remainder -= prediction;
const double projection = prediction * remainder;
const double identity = trial * trial - prediction * prediction - 2. * projection - remainder * remainder;
trials << trial.Norml2() << ',' << trial.Norml2() / residual.Norml2() << ',' << relative << ','
<< correction.Norml2() << ',' << action.Norml2() << ',' << slope << ',' << remainder.Norml2()
<< ',' << remainder.Norml2() / alpha << ',' << prediction.Norml2() << ',' << projection << ','
<< identity << ',' << (trial * trial <= (1. - 1e-4 * alpha) * (residual * residual)) << '\n';
for (const auto &block : state.Problem().GetManifest().residualBlocks())
blocks << role << ',' << alpha << ',' << block.stableId << ','
<< d::BlockNorm(residual, block.offset, block.size) << ','
<< d::BlockNorm(action, block.offset, block.size) << ','
<< d::BlockNorm(trial, block.offset, block.size) << ','
<< d::BlockNorm(remainder, block.offset, block.size) << '\n';
}
trials.flush(); blocks.flush(); bounds.flush();
}
restore();
state.normalizedCorrection = savedCorrection;
if (!d::Identical(accepted, state.AcceptedPhysicalState()) ||
!d::Identical(residual, state.trialNormalizedResidual))
throw std::runtime_error("Linear trial observations altered their base or accepted state");
auto invariants = d::Open(output / "linear_direction_trial_invariants.csv");
invariants << "metric,value\naccepted_unchanged,1\nbase_residual_restored,1\n";
}
} // namespace experiment::plateau_diagnostics

View File

@@ -0,0 +1,282 @@
#!/usr/bin/env python3
"""Small independent log-density controls for rho(t)=t**n on [0,1].
No stellar solve or FEM library is used. A three-coordinate exponential moment
fit illustrates a changed density approximation, not a production proposal.
Polynomial extrema are analytic; integrals use independently generated Gauss
rules, with 64/128-point comparison. Only stdlib is required.
"""
import argparse
import csv
from fractions import Fraction
import hashlib
import json
import math
from pathlib import Path
import unittest
def dot(a, b):
return math.fsum(x * y for x, y in zip(a, b))
def norm(a):
return math.sqrt(dot(a, a))
def gauss(count):
rule = []
for j in range(1, count + 1):
z = math.cos(math.pi * (j - .25) / (count + .5))
for _ in range(40):
p0, p1 = 1., z
for degree in range(2, count + 1):
p0, p1 = p1, ((2 * degree - 1) * z * p1 - (degree - 1) * p0) / degree
derivative = count * (z * p1 - p0) / (z * z - 1)
change = p1 / derivative
z -= change
if abs(change) < 2e-16:
break
rule.append(((1 + z) / 2, 1 / ((1 - z * z) * derivative * derivative)))
return sorted(rule)
def polynomial(c, t):
return c[0] + t * (c[1] + t * c[2])
def interpolate(values):
separation = math.sqrt(.6)
slope = (values[2] - values[0]) / separation
curvature = (10 / 3) * (values[2] + values[0] - 2 * values[1])
return [values[1] - slope / 2 + curvature / 4, slope - curvature, curvature]
def project(n):
n = Fraction(str(n))
moments = [1 / (n + j + 1) for j in range(3)]
return [float(sum(a * b for a, b in zip(row, moments)))
for row in ((9, -36, 30), (-36, 192, -180), (30, -180, 180))]
def extrema(c):
points = [0., 1.]
if c[2] and 0 < -c[1] / (2 * c[2]) < 1:
points.append(-c[1] / (2 * c[2]))
return min(polynomial(c, t) for t in points), max(polynomial(c, t) for t in points)
def basis(t):
return [1., math.sqrt(3) * (2 * t - 1), math.sqrt(5) * (6 * t * t - 6 * t + 1)]
def orthogonal_coefficients(c):
return [c[0] + c[1] / 2 + c[2] / 3, (c[1] + c[2]) / (2 * math.sqrt(3)), c[2] / (6 * math.sqrt(5))]
def power_coefficients(a):
return [a[0] - math.sqrt(3) * a[1] + math.sqrt(5) * a[2],
2 * math.sqrt(3) * a[1] - 6 * math.sqrt(5) * a[2], 6 * math.sqrt(5) * a[2]]
def target_moments(n):
return [1 / (n + 1), math.sqrt(3) * (2 / (n + 2) - 1 / (n + 1)),
math.sqrt(5) * (6 / (n + 3) - 6 / (n + 2) + 1 / (n + 1))]
def moments_and_jacobian(density, rule):
samples = [(weight * density(t), basis(t)) for t, weight in rule]
moments = [math.fsum(weight * phi[i] for weight, phi in samples) for i in range(3)]
jacobian = [[math.fsum(weight * phi[i] * phi[j] for weight, phi in samples) for j in range(3)] for i in range(3)]
return moments, jacobian
def solve(matrix, rhs):
a = [row[:] + [value] for row, value in zip(matrix, rhs)]
for column in range(3):
pivot = max(range(column, 3), key=lambda i: abs(a[i][column]))
a[column], a[pivot] = a[pivot], a[column]
if not abs(a[column][column]) > 1e-16:
raise ArithmeticError("Unresolved tiny moment Jacobian")
for row in range(column + 1, 3):
factor = a[row][column] / a[column][column]
for j in range(column, 4):
a[row][j] -= factor * a[column][j]
result = [0.] * 3
for row in (2, 1, 0):
result[row] = (a[row][3] - dot(a[row][row + 1:3], result[row + 1:])) / a[row][row]
if norm([dot(row, result) - value for row, value in zip(matrix, rhs)]) > 1e-12 * norm(rhs):
raise ArithmeticError("Tiny solve failed independent defect check")
return result
def determinant(a):
return (a[0][0] * (a[1][1] * a[2][2] - a[1][2] * a[2][1])
- a[0][1] * (a[1][0] * a[2][2] - a[1][2] * a[2][0])
+ a[0][2] * (a[1][0] * a[2][1] - a[1][1] * a[2][0]))
def eigenvalues(a):
# Eigenvalues of the three-by-three symmetric weighted mass matrix itself;
# no Gram-squared surrogate or full stellar conditioning claim is involved.
mean = sum(a[i][i] for i in range(3)) / 3
centered = [[a[i][j] - (mean if i == j else 0) for j in range(3)] for i in range(3)]
scale = math.sqrt(sum(value * value for row in centered for value in row) / 6)
if scale == 0:
return [mean] * 3
angle = math.acos(max(-1., min(1., determinant([[x / scale for x in row] for row in centered]) / 2))) / 3
values = sorted(mean + 2 * scale * math.cos(angle + j * 2 * math.pi / 3) for j in range(3))
if abs(sum(values) - 3 * mean) > 1e-12 or abs(math.prod(values) - determinant(a)) > 1e-12:
raise ArithmeticError("Tiny spectral invariants failed")
return values
def fit_log_moments(n, initial, rule):
target = target_moments(n)
a = orthogonal_coefficients(initial)
for iteration in range(40):
moments, jacobian = moments_and_jacobian(lambda t: math.exp(dot(a, basis(t))), rule)
residual = [value - wanted for value, wanted in zip(moments, target)]
if norm(residual) < 2e-13 * norm(target):
return power_coefficients(a), iteration, norm(residual) / norm(target)
direction = solve(jacobian, [-value for value in residual])
old_norm = norm(residual)
for backtrack in range(20):
step = 2. ** -backtrack
trial = [value + step * change for value, change in zip(a, direction)]
try:
trial_moments, _ = moments_and_jacobian(lambda t: math.exp(dot(trial, basis(t))), rule)
new_norm = norm([value - wanted for value, wanted in zip(trial_moments, target)])
except OverflowError:
continue
if new_norm < (1 - 1e-4 * step) * old_norm:
a = trial
break
else:
raise ArithmeticError("Tiny moment fit failed line search")
raise ArithmeticError("Tiny moment fit did not converge")
def controls(n):
nodes = [t for t, _ in gauss(3)]
direct = interpolate([t ** n for t in nodes])
logs = interpolate([n * math.log(t) for t in nodes])
log_mass = moments_and_jacobian(lambda t: math.exp(polynomial(logs, t)), gauss(64))[0][0]
shifted = logs[:]
shifted[0] += math.log((1 / (n + 1)) / log_mass)
fitted, iterations, relative = fit_log_moments(n, logs, gauss(64))
return [("density_q2_interpolation_or_exp_coefficients", "polynomial", direct, None),
("density_q2_l2_projection", "polynomial", project(n), None),
("pointwise_exp_q2_log_interpolation", "exp", logs, None),
("pointwise_exp_q2_log_mass_shift", "exp", shifted, None),
("pointwise_exp_q2_log_moment_fit", "exp", fitted,
{"iterations": iterations, "relative_moment_defect_64": relative}),
("matched_factor_t_power_n_exp_zero", "factor", [0., 0., 0.], None)]
def evaluate_case(n, name, kind, coefficients, fit):
if kind == "polynomial":
density = lambda t: polynomial(coefficients, t)
minimum, maximum = extrema(coefficients)
elif kind == "exp":
density = lambda t: math.exp(polynomial(coefficients, t))
lo, hi = extrema(coefficients)
minimum, maximum = math.exp(lo), math.exp(hi)
else:
density = lambda t: t ** n
minimum, maximum = 0., 1.
moments, jacobian = moments_and_jacobian(density, gauss(128))
coarse_moments, _ = moments_and_jacobian(density, gauss(64))
residual = [a - b for a, b in zip(moments, target_moments(n))]
error = math.sqrt(math.fsum(w * (density(t) - t ** n) ** 2 for t, w in gauss(128)))
eig = eigenvalues(jacobian) if kind in ("exp", "factor") else None
return dict(n=n, name=name, kind=kind, coefficients=coefficients,
boundary_density=density(0.), minimum_density=minimum, maximum_density=maximum,
cell_mass=moments[0], relative_mass_error=moments[0] * (n + 1) - 1,
relative_l2_error=error * math.sqrt(2 * n + 1),
moment_defect=residual, relative_moment_defect=norm(residual) / norm(target_moments(n)),
moment_quadrature_64_vs_128_maximum=max(abs(a - b) for a, b in zip(moments, coarse_moments)),
log_coordinate_jacobian_eigenvalues=eig,
log_coordinate_jacobian_condition=eig[-1] / eig[0] if eig else None,
fit=fit)
class Tests(unittest.TestCase):
def test_gauss(self):
for degree in range(12):
self.assertAlmostEqual(math.fsum(w * t ** degree for t, w in gauss(8)), 1 / (degree + 1), places=14)
def test_log_coefficients_do_not_fix_polynomial(self):
for n in (1.5, 3.):
nodes = [t for t, _ in gauss(3)]
a = interpolate([math.exp(n * math.log(t)) for t in nodes])
b = interpolate([t ** n for t in nodes])
self.assertLess(max(abs(x - y) for x, y in zip(a, b)), 2e-15)
self.assertLess(extrema(a)[0], 0)
def test_fit_and_vacuum(self):
for n in (1., 1.5, 3.):
results = [evaluate_case(n, *case) for case in controls(n)]
fitted = next(row for row in results if row["name"].endswith("moment_fit"))
self.assertLess(fitted["relative_moment_defect"], 3e-13)
self.assertGreater(fitted["boundary_density"], 0)
self.assertGreater(fitted["relative_l2_error"], 1e-3)
exact = results[-1]
self.assertEqual(exact["boundary_density"], 0)
self.assertEqual(exact["relative_l2_error"], 0)
def test_jacobian(self):
a, direction, step = [-1., .2, -.1], [.3, -.1, .2], 1e-5
rule = gauss(64)
_, jacobian = moments_and_jacobian(lambda t: math.exp(dot(a, basis(t))), rule)
plus, _ = moments_and_jacobian(lambda t: math.exp(dot([x + step * y for x, y in zip(a, direction)], basis(t))), rule)
minus, _ = moments_and_jacobian(lambda t: math.exp(dot([x - step * y for x, y in zip(a, direction)], basis(t))), rule)
error = [(x - y) / (2 * step) - dot(row, direction) for x, y, row in zip(plus, minus, jacobian)]
self.assertLess(norm(error), 2e-10)
self.assertEqual(eigenvalues([[1., 0., 0.], [0., 1., 0.], [0., 0., 1.]]), [1., 1., 1.])
self.assertLess(max(abs(x - y) for x, y in zip(eigenvalues([[2., 1., 0.], [1., 2., 0.], [0., 0., 4.]]), [1., 3., 4.])), 2e-14)
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--output", type=Path)
parser.add_argument("--self-test", action="store_true")
args = parser.parse_args()
if args.self_test:
result = unittest.TextTestRunner(verbosity=2).run(unittest.defaultTestLoader.loadTestsFromTestCase(Tests))
if not result.wasSuccessful():
raise SystemExit(1)
if args.output is None:
return
cases = [evaluate_case(n, *case) for n in (1., 1.5, 3.) for case in controls(n)]
data = dict(schema="log_density_reference_v1", producer_sha256=hashlib.sha256(Path(__file__).read_bytes()).hexdigest(),
scope="Uniform 1D frozen t^n profile; no FEM, coupled star solve, virial test, or general-EOS validation.",
eigenvalue_scope="Three-dimensional log-coordinate weighted mass matrix in L2-orthonormal polynomial basis on [0,1].",
scaling="For rho=A*Delta^n*t^n, local reference-basis Jacobian=A*Delta^(n+1)*H_n; relative to ordinary mass the scale is A*Delta^n.",
cases=cases)
if args.output is None:
print(json.dumps(data, indent=2, allow_nan=False))
return
args.output.mkdir(parents=True, exist_ok=False)
with (args.output / "summary.csv").open("w", newline="") as stream:
writer = csv.DictWriter(stream, fieldnames=list(cases[0]))
writer.writeheader()
for row in cases:
writer.writerow({key: json.dumps(value) if isinstance(value, (list, dict)) else value for key, value in row.items()})
with (args.output / "profiles.csv").open("w", newline="") as stream:
writer = csv.writer(stream)
writer.writerow(["n", "method", "t", "target", "density"])
for row in cases:
for j in range(401):
t = j / 400
value = (t ** row["n"] if row["kind"] == "factor" else
math.exp(polynomial(row["coefficients"], t)) if row["kind"] == "exp" else
polynomial(row["coefficients"], t))
writer.writerow([row["n"], row["name"], t, t ** row["n"], value])
data["artifacts_sha256"] = {path.name: hashlib.sha256(path.read_bytes()).hexdigest() for path in sorted(args.output.iterdir())}
(args.output / "summary.json").write_text(json.dumps(data, indent=2, allow_nan=False) + "\n")
print("Wrote", args.output)
if __name__ == "__main__":
main()

View File

@@ -0,0 +1,126 @@
#!/usr/bin/env python3
"""Generate projected scalar controls from completed frozen coupled-trial cases.
This performs saved-vector algebra only. Replaying x+t*p through the existing
full operator distinguishes scalar step selection from transverse SOC benefit.
"""
import argparse
import csv
import datetime
import hashlib
import json
import math
from pathlib import Path
import sys
PREFIX = 'coupled_trial_'
SHARED = ('base_normalized.txt', 'base_physical.txt', 'base_residual.txt', 'direction.txt',
'state_factors.txt', 'residual_factors.txt', 'layout.csv')
def digest(path):
return hashlib.sha256(path.read_bytes()).hexdigest()
def vector(path):
words = path.read_text().split()
values = [float(word) for word in words[1:]]
if not words or int(words[0]) != len(values) or not values or not all(map(math.isfinite, values)):
raise ValueError(f'Invalid finite vector: {path}')
return values
def rows(path):
with path.open() as stream:
return list(csv.DictReader(stream))
def norm(values):
return math.sqrt(math.fsum(value * value for value in values))
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('screen', type=Path)
parser.add_argument('output', type=Path)
args = parser.parse_args()
screen, output = args.screen.resolve(), args.output.resolve()
if output.exists() or screen in output.parents:
parser.error('Use a fresh output directory outside the immutable source screen.')
source_provenance = screen / 'provenance.json'
campaign = json.loads(source_provenance.read_text())
input_hashes = {str(source_provenance): digest(source_provenance)}
expected_shared = None
generated, cases, observations = [], [], []
for source_case, label in (('late_raw_coupled', 'raw'), ('late_curvature_coupled', 'gravity')):
folder, record_path = screen / source_case, screen / (source_case + '_run.json')
record = json.loads(record_path.read_text())
if record.get('exit_code') != 0 or not record.get('finished_utc') or record.get('timed_out', False):
raise ValueError(f'Source case has not completed successfully: {source_case}')
input_hashes[str(record_path)] = digest(record_path)
names = [PREFIX + name for name in SHARED] + ['metadata.txt'] + [
PREFIX + name for name in ('summary.csv', 'trials.csv', 'selected_state_a2.txt')]
for name in names:
path = folder / name
value = digest(path)
if record.get('output_hashes', {}).get(name) != value:
raise ValueError(f'Source artifact does not match its completed-run hash: {path}')
input_hashes[str(path)] = value
shared = {name: input_hashes[str(folder / (PREFIX + name))] for name in SHARED}
if expected_shared is not None and shared != expected_shared:
raise ValueError('Source cases do not share exactly the same base, direction, normalization and layout.')
expected_shared = shared
meta = dict(line.split('=', 1) for line in (folder / 'metadata.txt').read_text().splitlines() if '=' in line)
if float(meta['n']) != 1.5 or float(meta['J']) != 0. or meta['central_phase'] != '0':
raise ValueError('These controls require the saved n=1.5, J=0 model without a central-density constraint.')
summary = {row['metric']: float(row['value']) for row in rows(folder / (PREFIX + 'summary.csv'))}
if summary['probe_exception'] != 0 or summary['outer_verified_gate'] != 1:
raise ValueError('Source probe did not complete with a verified outer Newton direction.')
matches = [row for row in rows(folder / (PREFIX + 'trials.csv')) if row['sample'] == '2']
if len(matches) != 1 or float(matches[0]['alpha']) != 1 / 256 or matches[0]['selected_accepted'] != '1' or \
int(matches[0]['soc_status']) != int(summary['soc_status_kept']):
raise ValueError('Expected a kept, Armijo-accepted coupled correction at sample 2, alpha=1/256.')
x, p, selected = [vector(folder / (PREFIX + name)) for name in
('base_normalized.txt', 'direction.txt', 'selected_state_a2.txt')]
if not len(x) == len(p) == len(selected):
raise ValueError('Source vectors have incompatible dimensions.')
displacement = [y - b for y, b in zip(selected, x)]
pp = math.fsum(value * value for value in p)
if not math.isfinite(pp) or pp <= 0.:
raise ValueError('Projection requires a finite nonzero direction norm.')
t = math.fsum(step * direction for step, direction in zip(displacement, p)) / pp
candidate = [math.fsum((b, t * direction)) for b, direction in zip(x, p)]
perpendicular = [math.fsum((step, -t * direction)) for step, direction in zip(displacement, p)]
if not math.isfinite(t) or t <= 0. or not all(map(math.isfinite, candidate)):
raise ValueError('Projected control is nonfinite or does not advance along the supplied direction.')
candidate_path = output / (label + '_projected_normalized.txt')
generated.append((candidate_path, candidate))
cases.append({'id': 'scalar_match_' + label + '_soc', 'arguments': [
'--index', '1.5', '--angular-momentum', '0', '--no-central', '--max-newton', '0',
'--strategy', 'baseline', '--preconditioner-variant', 'independent',
'--probe-state', str(folder / (PREFIX + 'base_physical.txt')),
'--replay-candidate', str(candidate_path)]})
observations.append({'source_case': source_case, 'sample': 2, 'nominal_alpha': 1 / 256, 't': t,
'selected_displacement_norm': norm(displacement), 'scalar_displacement_norm': t * math.sqrt(pp),
'perpendicular_norm': norm(perpendicular), 'perpendicular_dot_direction':
math.fsum(value * direction for value, direction in zip(perpendicular, p)),
'source_selected_residual_norm': float(matches[0]['selected_norm']), 'candidate': str(candidate_path)})
# Validate everything before creating output; never replace campaign inputs.
output.mkdir(parents=True)
for path, values in generated:
path.write_text(str(len(values)) + '\n' + ''.join(format(value, '.17g') + '\n' for value in values))
(output / 'cases.json').write_text(json.dumps(cases, indent=2, allow_nan=False) + '\n')
generator = Path(__file__).resolve()
(output / 'generator.py').write_bytes(generator.read_bytes())
provenance = {'created_utc': datetime.datetime.now(datetime.timezone.utc).isoformat(),
'generator': str(generator), 'generator_sha256': digest(generator), 'python': sys.version,
'source_screen': str(screen), 'source_commit': campaign['commit'], 'input_hashes': input_hashes,
'output_hashes': {path.name: digest(path) for path in output.iterdir()}, 'controls': observations,
'scope': 'Projection controls only; no FEM evaluations, acceptance conclusions, or linear solves performed.'}
(output / 'generator_provenance.json').write_text(json.dumps(provenance, indent=2, allow_nan=False) + '\n')
print(output / 'cases.json')
if __name__ == '__main__':
main()

View File

@@ -0,0 +1,258 @@
#pragma once
#include "model_slice_geometry.hpp"
#include "polytrope_physical_state.hpp"
#include <chrono>
#include <cstring>
#include <iomanip>
#include <iostream>
#include <map>
namespace experiment::model_slices {
struct Options final {
std::string plane{"both"};
double offset{0.};
int subdivisions{6};
void Validate() const {
if (subdivisions < 2 || subdivisions > 32)
throw std::invalid_argument("Slice subdivisions must be between 2 and 32.");
(void)Plane::Parse(plane == "both" ? "xz" : plane, offset);
}
};
namespace detail {
inline std::ofstream Open(const std::filesystem::path& path) {
if (std::filesystem::exists(path)) throw std::invalid_argument("Refusing to overwrite slice output: " + path.string());
std::ofstream stream(path);
stream.exceptions(std::ios::failbit | std::ios::badbit);
stream << std::setprecision(17);
return stream;
}
inline bool Identical(const mfem::Vector& a, const mfem::Vector& b) {
return a.Size() == b.Size() && (a.Size() == 0 ||
std::memcmp(a.GetData(), b.GetData(), std::size_t(a.Size()) * sizeof(double)) == 0);
}
inline mfem::IntegrationPoint IntegrationPoint(const Vector& reference) {
mfem::IntegrationPoint point;
point.Set3(reference[0], reference[1], reference[2]);
return point;
}
class ElementMap final {
public:
ElementMap(polytrope_validation::PhysicalState& state, int element, bool deformed = true)
: state(state), deformed(deformed), transformation(*state.finiteElements.mesh->GetElementTransformation(element)) {}
Point operator()(const Vector& reference) {
const auto point = IntegrationPoint(reference);
Vector physical{};
if (deformed) {
if (state.mapping.EvaluatePoint(transformation, point, mapped) != mean_field::mapping::MappingStatus::valid || mapped.compactified)
throw std::domain_error("Model slices require valid, noncompactified stellar geometry.");
for (int d = 0; d < 3; ++d) physical[d] = mapped.physical_position(d);
} else {
transformation.Transform(point, referencePosition);
for (int d = 0; d < 3; ++d) physical[d] = referencePosition(d);
}
for (double value : physical) if (!std::isfinite(value)) throw std::domain_error("Nonfinite slice geometry.");
return {reference, physical};
}
private:
polytrope_validation::PhysicalState& state;
bool deformed;
mfem::ElementTransformation& transformation;
mean_field::mapping::MappingPointContext mapped;
mfem::Vector referencePosition = mfem::Vector(3);
};
class Intersections final {
public:
Intersections(ElementMap& map, Plane plane, double tolerance) : map(map), plane(std::move(plane)), tolerance(tolerance) {}
Point operator()(const Point& a, const Point& b) {
const Vector& first = a.reference < b.reference ? a.reference : b.reference;
const Vector& last = a.reference < b.reference ? b.reference : a.reference;
const std::array<double, 6> key{first[0], first[1], first[2], last[0], last[1], last[2]};
if (const auto found = cache.find(key); found != cache.end()) return found->second;
const Point root = Intersect(a, b, plane, tolerance, map);
cache.emplace(key, root);
return root;
}
private:
ElementMap& map;
Plane plane;
double tolerance;
std::map<std::array<double, 6>, Point> cache;
};
struct Bounds final {
Vector lower{INFINITY, INFINITY, INFINITY}, upper{-INFINITY, -INFINITY, -INFINITY};
void Add(const Vector& value) {
for (int d = 0; d < 3; ++d) { lower[d] = std::min(lower[d], value[d]); upper[d] = std::max(upper[d], value[d]); }
}
};
inline void ExportPlane(polytrope_validation::PhysicalState& state, const Options& options, const Plane& plane,
const std::filesystem::path& directory) {
const auto start = std::chrono::steady_clock::now();
if (!std::filesystem::create_directory(directory)) throw std::invalid_argument("Slice directory already exists.");
auto vertices = Open(directory / "vertices.csv"), triangles = Open(directory / "triangles.csv");
vertices << "vertex,element,attribute,xi,eta,zeta,x,y,z,rho,h,plane_error\n";
triangles << "triangle,element,v0,v1,v2\n";
auto& mesh = *state.finiteElements.mesh;
const int n = options.subdivisions, width = n + 1;
const auto index = [width](int i, int j, int k) { return i + width * (j + width * k); };
Bounds bounds;
std::size_t vertexCount = 0, triangleCount = 0;
double maximumPlaneError = 0., maximumChordError = 0., minimumDensity = INFINITY, minimumEnthalpy = INFINITY;
// Coordinate-scaled tolerance is independent of density units and order.
double scale = 0.;
for (int element = 0; element < mesh.GetNE(); ++element) if (state.isStellar(element)) {
ElementMap map(state, element);
for (int corner = 0; corner < 8; ++corner) {
const auto point = map({double(corner & 1), double((corner >> 1) & 1), double((corner >> 2) & 1)});
scale = std::max(scale, std::hypot(point.physical[0], point.physical[1], point.physical[2]));
}
}
if (!(scale > 0) || !std::isfinite(scale)) throw std::domain_error("Invalid stellar slice scale.");
const double tolerance = 2e-12 * std::max(scale, std::abs(plane.offset));
for (int element = 0; element < mesh.GetNE(); ++element) if (state.isStellar(element)) {
if (mesh.GetElementBaseGeometry(element) != mfem::Geometry::CUBE)
throw std::invalid_argument("Model slices currently require hexahedral stellar elements.");
ElementMap map(state, element);
Intersections intersections(map, plane, tolerance);
std::vector<Point> lattice(static_cast<std::size_t>(width * width * width));
for (int k = 0; k <= n; ++k) for (int j = 0; j <= n; ++j) for (int i = 0; i <= n; ++i) {
auto& point = lattice[index(i, j, k)];
point = map({double(i) / n, double(j) / n, double(k) / n});
bounds.Add(point.physical);
}
for (int k = 0; k < n; ++k) for (int j = 0; j < n; ++j) for (int i = 0; i < n; ++i) {
std::array<Point, 8> cube;
for (int c = 0; c < 8; ++c) cube[c] = lattice[index(i + (c & 1), j + ((c >> 1) & 1), k + ((c >> 2) & 1))];
for (const auto& indices : cubeTetrahedra) {
std::array<Point, 4> tetrahedron;
for (int c = 0; c < 4; ++c) tetrahedron[c] = cube[indices[c]];
for (const auto& triangle : CutTetrahedron(tetrahedron, plane, tolerance, intersections)) {
triangles << triangleCount++ << ',' << element << ',' << vertexCount << ',' << vertexCount + 1 << ',' << vertexCount + 2 << '\n';
Vector referenceCenter{}, physicalCenter{};
for (const auto& point : triangle) {
const auto ip = IntegrationPoint(point.reference);
const double rho = state.density.GetValue(element, ip), h = state.enthalpy.GetValue(element, ip);
if (!std::isfinite(rho) || !std::isfinite(h)) throw std::domain_error("Nonfinite slice field value.");
const double error = std::abs(plane.Distance(point));
if (error > tolerance) throw std::logic_error("A slice vertex is off its physical plane.");
maximumPlaneError = std::max(maximumPlaneError, error);
minimumDensity = std::min(minimumDensity, rho); minimumEnthalpy = std::min(minimumEnthalpy, h);
vertices << vertexCount++ << ',' << element << ',' << mesh.GetAttribute(element);
for (double value : point.reference) vertices << ',' << value;
for (double value : point.physical) vertices << ',' << value;
vertices << ',' << rho << ',' << h << ',' << error << '\n';
for (int d = 0; d < 3; ++d) {
referenceCenter[d] += point.reference[d] / 3.; physicalCenter[d] += point.physical[d] / 3.;
}
bounds.Add(point.physical);
}
maximumChordError = std::max(maximumChordError, Distance(map(referenceCenter).physical, physicalCenter));
}
}
}
}
vertices.flush(); triangles.flush();
std::array<std::size_t, 2> segmentCounts{};
std::array<int, 2> coplanar{};
std::array<double, 2> surfaceError{}, surfaceChordError{};
for (int reference = 0; reference < 2; ++reference) {
auto surface = Open(directory / (reference ? "reference_surface.csv" : "surface.csv"));
surface << "segment,face,element,x0,y0,z0,x1,y1,z1,maximum_plane_error\n";
for (int face = 0; face < mesh.GetNumFaces(); ++face) {
int left = -1, right = -1;
mesh.GetFaceElements(face, &left, &right);
const bool leftStar = left >= 0 && state.isStellar(left), rightStar = right >= 0 && state.isStellar(right);
if (leftStar == rightStar) continue;
const int element = leftStar ? left : right;
auto* faceMap = mesh.GetFaceElementTransformations(face);
if (faceMap->GetGeometryType() != mfem::Geometry::SQUARE)
throw std::invalid_argument("Model slices currently require quadrilateral material faces.");
ElementMap map(state, element, !reference);
Intersections intersections(map, plane, tolerance);
std::vector<Point> lattice(static_cast<std::size_t>(width * width));
for (int j = 0; j <= n; ++j) for (int i = 0; i <= n; ++i) {
mfem::IntegrationPoint facePoint, elementPoint;
facePoint.Set2(double(i) / n, double(j) / n);
if (leftStar) faceMap->Loc1.Transform(facePoint, elementPoint); else faceMap->Loc2.Transform(facePoint, elementPoint);
lattice[i + width * j] = map({elementPoint.x, elementPoint.y, elementPoint.z});
}
for (int j = 0; j < n; ++j) for (int i = 0; i < n; ++i) {
const std::array<Point, 4> square{lattice[i + width * j], lattice[i + 1 + width * j],
lattice[i + width * (j + 1)], lattice[i + 1 + width * (j + 1)]};
for (const auto& indices : {std::array<int, 3>{0, 1, 3}, std::array<int, 3>{0, 3, 2}}) {
const Triangle triangle{square[indices[0]], square[indices[1]], square[indices[2]]};
for (const auto& segment : CutSurfaceTriangle(triangle, plane, tolerance, intersections, coplanar[reference])) {
const double error = std::max(std::abs(plane.Distance(segment[0])), std::abs(plane.Distance(segment[1])));
if (error > tolerance) throw std::logic_error("A surface intersection is off its physical plane.");
surfaceError[reference] = std::max(surfaceError[reference], error);
surfaceChordError[reference] = std::max(surfaceChordError[reference],
Distance(map(Blend(segment[0].reference, segment[1].reference, .5)).physical,
Blend(segment[0].physical, segment[1].physical, .5)));
surface << segmentCounts[reference]++ << ',' << face << ',' << element;
for (const auto& point : segment) { for (double value : point.physical) surface << ',' << value; bounds.Add(point.physical); }
surface << ',' << error << '\n';
}
}
}
}
}
auto metadata = Open(directory / "metadata.csv");
metadata << "metric,value\nplane," << plane.name << "\nnormal_axis," << plane.normal
<< "\nhorizontal_axis," << plane.horizontal << "\nvertical_axis," << plane.vertical
<< "\noffset," << plane.offset << "\nsubdivisions," << n << "\nroot_tolerance," << tolerance
<< "\ndeformation_scale,1\ntriangle_count," << triangleCount << "\nvertex_count," << vertexCount
<< "\nmaximum_plane_error," << maximumPlaneError << "\nmaximum_sampled_chord_error," << maximumChordError
<< "\nminimum_sampled_density," << minimumDensity << "\nminimum_sampled_enthalpy," << minimumEnthalpy
<< "\nsurface_segments," << segmentCounts[0] << "\nreference_surface_segments," << segmentCounts[1]
<< "\nsurface_coplanar_triangles," << coplanar[0] << "\nreference_surface_coplanar_triangles," << coplanar[1]
<< "\nsurface_maximum_plane_error," << surfaceError[0] << "\nreference_surface_maximum_plane_error," << surfaceError[1]
<< "\nsurface_maximum_sampled_chord_error," << surfaceChordError[0]
<< "\nreference_surface_maximum_sampled_chord_error," << surfaceChordError[1]
<< "\nu_min," << bounds.lower[plane.horizontal] << "\nu_max," << bounds.upper[plane.horizontal]
<< "\nv_min," << bounds.lower[plane.vertical] << "\nv_max," << bounds.upper[plane.vertical]
<< "\nseconds," << std::chrono::duration<double>(std::chrono::steady_clock::now() - start).count() << '\n';
if (triangleCount && !segmentCounts[0]) throw std::runtime_error("Material slice has no resolved outer boundary; refine or move the plane.");
if (coplanar[0] || coplanar[1]) throw std::runtime_error("Slice is coplanar with a surface patch; choose a different plane offset.");
}
} // namespace detail
inline void Record(polytrope_validation::PhysicalState& state, const Options& options,
const std::filesystem::path& output, const std::string& label) {
options.Validate();
int ranks = 0;
MPI_Comm_size(state.finiteElements.mesh->GetComm(), &ranks);
if (ranks != 1 || state.finiteElements.mesh->Dimension() != 3 || !state.finiteElements.mesh->Conforming())
throw std::invalid_argument("Model slices require a conforming 3D mesh on one MPI rank.");
const mfem::Vector density(state.density), enthalpy(state.enthalpy), displacement(state.displacement);
const auto directory = output / (label + "_slices");
if (!std::filesystem::create_directory(directory)) throw std::invalid_argument("Slice output directory already exists.");
auto checks = detail::Open(directory / "geometry_self_checks.csv");
checks << "case,observed,expected,tolerance,passed\n";
for (const auto& check : GeometrySelfChecks())
checks << check.name << ',' << check.observed << ',' << check.expected << ',' << check.tolerance << ",1\n";
const std::vector<std::string> planes = options.plane == "both" ? std::vector<std::string>{"xz", "xy"} : std::vector<std::string>{options.plane};
for (const auto& name : planes) {
std::cout << label << " physical " << name << " slice, subdivisions=" << options.subdivisions << std::endl;
detail::ExportPlane(state, options, Plane::Parse(name, options.offset), directory / name);
}
if (!detail::Identical(density, state.density) || !detail::Identical(enthalpy, state.enthalpy) || !detail::Identical(displacement, state.displacement))
throw std::logic_error("Model slice export changed a source field.");
auto scope = detail::Open(directory / "scope.txt");
scope << "source_fields_bitwise_identical=1\ndeformation_scale=1\n"
<< "Vertices evaluate the independent FEM density and enthalpy on the actual deformed physical plane.\n"
<< "Triangles remain local to their material element; exterior fields are never sampled.\n"
<< "A coincident internal face uses the positive-normal-side DG trace.\n"
<< "Surface and undeformed reference outlines are separately intersected with the same physical plane.\n"
<< "Interior colors and boundary chords approximate curved cuts at the recorded subdivision count.\n"
<< "Sampled chord errors and bounds are diagnostics, not rigorous geometric enclosures.\n"
<< "Refine subdivisions to assess image stability; subcell tangencies or multiple edge crossings can be missed.\n"
<< "The slice does not certify positivity, equilibrium, virial balance or the absence of unsampled features.\n";
}
} // namespace experiment::model_slices

View File

@@ -0,0 +1,194 @@
#pragma once
// Pure geometry keeps the physical-plane construction independently testable.
// The caller supplies the actual curved element map, never a displaced image
// of an already selected reference-plane slice.
#include <algorithm>
#include <array>
#include <cmath>
#include <limits>
#include <stdexcept>
#include <string>
#include <utility>
#include <vector>
namespace experiment::model_slices {
using Vector = std::array<double, 3>;
struct Point final { Vector reference{}, physical{}; };
struct Plane final {
int horizontal{0}, vertical{2}, normal{1};
double offset{0.};
std::string name{"xz"};
static Plane Parse(const std::string& name, double offset = 0.) {
if (!std::isfinite(offset)) throw std::invalid_argument("Slice offset must be finite.");
if (name == "xz") return {0, 2, 1, offset, name};
if (name == "xy") return {0, 1, 2, offset, name};
if (name == "yz") return {1, 2, 0, offset, name};
throw std::invalid_argument("Slice plane must be xz, xy or yz.");
}
double Distance(const Point& point) const { return point.physical[normal] - offset; }
};
using Triangle = std::array<Point, 3>;
using Segment = std::array<Point, 2>;
inline double Distance(const Vector& a, const Vector& b) {
return std::hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
}
inline Vector Blend(const Vector& a, const Vector& b, double fraction) {
Vector out{};
for (int i = 0; i < 3; ++i) out[i] = (1. - fraction) * a[i] + fraction * b[i];
return out;
}
inline double TwiceArea(const Triangle& t, const Plane& plane) {
const int u = plane.horizontal, v = plane.vertical;
return (t[1].physical[u] - t[0].physical[u]) * (t[2].physical[v] - t[0].physical[v]) -
(t[1].physical[v] - t[0].physical[v]) * (t[2].physical[u] - t[0].physical[u]);
}
template <class Evaluate>
Point Intersect(Point left, Point right, const Plane& plane, double tolerance, Evaluate&& evaluate) {
double fl = plane.Distance(left), fr = plane.Distance(right);
if (std::abs(fl) <= tolerance) return left;
if (std::abs(fr) <= tolerance) return right;
if ((fl < 0) == (fr < 0)) throw std::logic_error("Slice root is not bracketed.");
for (int iteration = 0; iteration < 80; ++iteration) {
// Smooth maps usually need only a few secant evaluations. Periodic
// bisection guarantees shrinking brackets even near a grazing cut.
const double fraction = iteration % 4 == 3 ? .5 : std::clamp(fl / (fl - fr), .02, .98);
const Point candidate = evaluate(Blend(left.reference, right.reference, fraction));
const double fc = plane.Distance(candidate);
if (!std::isfinite(fc)) throw std::domain_error("Nonfinite physical-plane root.");
if (std::abs(fc) <= tolerance) return candidate;
if ((fc < 0) == (fl < 0)) { left = candidate; fl = fc; }
else { right = candidate; fr = fc; }
}
throw std::runtime_error("Curved physical-plane intersection did not meet its tolerance.");
}
inline void AppendUnique(std::vector<Point>& points, const Point& point, double tolerance) {
for (const auto& old : points) if (Distance(old.physical, point.physical) <= 4 * tolerance) return;
points.push_back(point);
}
template <std::size_t Size, class Intersection>
std::vector<Point> EdgeIntersections(const std::array<Point, Size>& points, const Plane& plane,
double tolerance, Intersection&& intersect) {
std::vector<Point> cut;
for (std::size_t i = 0; i < Size; ++i) {
const double a = plane.Distance(points[i]);
if (std::abs(a) <= tolerance) AppendUnique(cut, points[i], tolerance);
for (std::size_t j = i + 1; j < Size; ++j) {
const double b = plane.Distance(points[j]);
if ((a < -tolerance && b > tolerance) || (a > tolerance && b < -tolerance))
AppendUnique(cut, intersect(points[i], points[j]), tolerance);
}
}
return cut;
}
template <class Intersection>
std::vector<Triangle> CutTetrahedron(const std::array<Point, 4>& points, const Plane& plane,
double tolerance, Intersection&& intersect) {
bool positive = false, nonpositive = false;
for (const auto& point : points) {
positive |= plane.Distance(point) > tolerance;
nonpositive |= plane.Distance(point) <= tolerance;
}
// A plane coincident with an internal face takes the trace from its
// positive-normal side. Rendering both sides would arbitrarily hide one
// of the two independent DG traces and double the slice area.
if (!positive || !nonpositive) return {};
auto cut = EdgeIntersections(points, plane, tolerance, intersect);
if (cut.size() < 3) return {};
Vector center{};
for (const auto& point : cut) for (int d = 0; d < 3; ++d) center[d] += point.physical[d] / cut.size();
std::sort(cut.begin(), cut.end(), [&](const Point& a, const Point& b) {
return std::atan2(a.physical[plane.vertical] - center[plane.vertical], a.physical[plane.horizontal] - center[plane.horizontal]) <
std::atan2(b.physical[plane.vertical] - center[plane.vertical], b.physical[plane.horizontal] - center[plane.horizontal]);
});
std::vector<Triangle> triangles;
for (std::size_t i = 1; i + 1 < cut.size(); ++i) {
Triangle triangle{cut[0], cut[i], cut[i + 1]};
if (std::abs(TwiceArea(triangle, plane)) > tolerance * tolerance) triangles.push_back(triangle);
}
return triangles;
}
template <class Intersection>
std::vector<Segment> CutSurfaceTriangle(const Triangle& points, const Plane& plane,
double tolerance, Intersection&& intersect, int& coplanar) {
int on = 0;
bool positive = false;
for (const auto& point : points) {
on += std::abs(plane.Distance(point)) <= tolerance;
positive |= plane.Distance(point) > tolerance;
}
if (on == 3) { ++coplanar; return {}; }
if (on == 2 && !positive) return {};
auto cut = EdgeIntersections(points, plane, tolerance, intersect);
if (cut.size() == 2 && Distance(cut[0].physical, cut[1].physical) > 4 * tolerance) return {{cut[0], cut[1]}};
return {};
}
// The common body diagonal makes face triangulations agree between adjacent
// reference subcubes. Field connectivity remains local to the owning element.
inline constexpr std::array<std::array<int, 4>, 6> cubeTetrahedra{{
{0, 1, 3, 7}, {0, 3, 2, 7}, {0, 2, 6, 7},
{0, 6, 4, 7}, {0, 4, 5, 7}, {0, 5, 1, 7}
}};
struct Check final { std::string name; double observed, expected, tolerance; };
inline std::vector<Check> GeometrySelfChecks() {
std::vector<Check> checks;
const auto record = [&](std::string name, double observed, double expected, double tolerance) {
if (!std::isfinite(observed) || std::abs(observed - expected) > tolerance)
throw std::runtime_error("Model slice geometry self-check failed: " + name);
checks.push_back({std::move(name), observed, expected, tolerance});
};
const auto identity = [](Vector reference) { return Point{reference, reference}; };
const Plane plane = Plane::Parse("xy", .5);
auto intersection = [&](Point a, Point b) { return Intersect(a, b, plane, 1e-13, identity); };
std::array<Point, 8> cube;
for (int i = 0; i < 8; ++i) cube[i] = identity({double(i & 1), double((i >> 1) & 1), double((i >> 2) & 1)});
double area = 0., affineIntegral = 0., planeError = 0.;
for (const auto& indices : cubeTetrahedra) {
std::array<Point, 4> tet;
for (int i = 0; i < 4; ++i) tet[i] = cube[indices[i]];
for (const auto& triangle : CutTetrahedron(tet, plane, 1e-13, intersection)) {
const double a = .5 * std::abs(TwiceArea(triangle, plane));
area += a;
for (const auto& point : triangle) {
affineIntegral += a / 3. * (point.physical[0] + 2 * point.physical[1] - point.physical[2]);
planeError = std::max(planeError, std::abs(plane.Distance(point)));
}
}
}
record("unit_cube_slice_area", area, 1., 1e-12);
record("affine_signed_field_integral", affineIntegral, 1., 1e-12);
record("physical_plane_residual", planeError, 0., 1e-12);
// This shear bends the preimage of z=0.5. Cutting z_ref=0.5 and
// displacing afterward gives the wrong result, even though it looks smooth.
const auto curved = [](Vector reference) {
Vector physical = reference;
physical[2] += .3 * reference[0] * reference[0];
return Point{reference, physical};
};
const Point root = Intersect(curved({0, 0, 0}), curved({1, 0, 1}), plane, 1e-13, curved);
const double expected = (-1. + std::sqrt(1.6)) / .6;
record("curved_edge_reference_root", root.reference[0], expected, 1e-12);
record("curved_edge_physical_plane", root.physical[2], .5, 1e-12);
int coplanar = 0;
const Triangle surface{identity({0, 0, 0}), identity({1, 0, 0}), identity({0, 0, 1})};
const auto segments = CutSurfaceTriangle(surface, plane, 1e-13, intersection, coplanar);
record("surface_intersection_segment_count", double(segments.size()), 1., 0.);
record("surface_intersection_length", Distance(segments[0][0].physical, segments[0][1].physical), .5, 1e-12);
const Plane facePlane = Plane::Parse("xy", 0.);
auto faceIntersection = [&](Point a, Point b) { return Intersect(a, b, facePlane, 1e-13, identity); };
const std::array<Point, 4> above{identity({0, 0, 0}), identity({1, 0, 0}), identity({0, 1, 0}), identity({0, 0, 1})};
auto below = above; below[3] = identity({0, 0, -1});
record("coincident_face_positive_side", double(CutTetrahedron(above, facePlane, 1e-13, faceIntersection).size()), 1., 0.);
record("coincident_face_negative_side", double(CutTetrahedron(below, facePlane, 1e-13, faceIntersection).size()), 0., 0.);
return checks;
}
} // namespace experiment::model_slices

View File

@@ -0,0 +1,13 @@
// Standalone, no MFEM or MPI setup: c++ -std=c++20 -O0 this_file.cpp -o /tmp/slice_checks
#include "model_slice_geometry.hpp"
#include <iostream>
int main() {
try {
for (const auto& check : experiment::model_slices::GeometrySelfChecks())
std::cout << check.name << ": " << check.observed << '\n';
} catch (const std::exception& error) {
std::cerr << error.what() << '\n';
return 1;
}
}

View File

@@ -0,0 +1,76 @@
[
{
"id": "n3_J0p035_K0p99",
"arguments": [
"--index",
"3",
"--angular-momentum",
".035",
"--n3-K-factor",
".99",
"--no-central",
"--surface-prescription",
"harmonics",
"--surface-degree",
"4",
"--max-newton",
"10",
"--restart",
"160",
"--max-linear",
"300",
"--linear-tol",
".03",
"--rtol",
"0",
"--atol",
"1e-12",
"--model-slices",
"--slice-subdivisions",
"4",
"--capture-iterations",
"0,3,7",
"--strategy",
"curvature",
"--preconditioner-variant",
"gravity-schur"
]
},
{
"id": "n3_J0p035_K0p99_ldu",
"arguments": [
"--index",
"3",
"--angular-momentum",
".035",
"--n3-K-factor",
".99",
"--no-central",
"--surface-prescription",
"harmonics",
"--surface-degree",
"4",
"--max-newton",
"10",
"--restart",
"160",
"--max-linear",
"300",
"--linear-tol",
".03",
"--rtol",
"0",
"--atol",
"1e-12",
"--model-slices",
"--slice-subdivisions",
"4",
"--capture-iterations",
"0,3,7",
"--strategy",
"curvature",
"--preconditioner-variant",
"stellar-ldu-gravity-schur"
]
}
]

View File

@@ -0,0 +1,18 @@
[
{
"id": "n1_equilibrium",
"arguments": ["--index", "1", "--angular-momentum", "0", "--surface-prescription", "harmonics", "--surface-degree", "4", "--no-central", "--max-newton", "0", "--density-diagnostic", "--density-snapshot", "../../diagnostics/spherical_harmonic_surface_2026-09-19/campaign/n1_J0_L4"]
},
{
"id": "n1p5_seed",
"arguments": ["--index", "1.5", "--angular-momentum", "0", "--surface-prescription", "harmonics", "--surface-degree", "4", "--no-central", "--max-newton", "0", "--density-diagnostic"]
},
{
"id": "n1p5_equilibrium",
"arguments": ["--index", "1.5", "--angular-momentum", "0", "--surface-prescription", "harmonics", "--surface-degree", "4", "--no-central", "--max-newton", "0", "--density-diagnostic", "--density-snapshot", "../../diagnostics/spherical_harmonic_surface_2026-09-19/campaign/n1p5_J0_L4"]
},
{
"id": "n3_seed",
"arguments": ["--index", "3", "--angular-momentum", "0", "--surface-prescription", "harmonics", "--surface-degree", "4", "--max-newton", "0", "--density-diagnostic"]
}
]

View File

@@ -0,0 +1,362 @@
#pragma once
// Experiment-only observations of a frozen physical state. No sampled field,
// projection, or positivity condition is installed in the equilibrium problem.
#include "negative_density_projection.hpp"
#include <array>
#include <cmath>
#include <filesystem>
#include <fstream>
#include <iomanip>
#include <iostream>
#include <limits>
#include <map>
#include <queue>
#include <stdexcept>
#include <string>
#include <vector>
namespace experiment::plateau_diagnostics {
namespace negative_density_detail {
inline std::ofstream Open(const std::filesystem::path &path) {
if (std::filesystem::exists(path))
throw std::runtime_error("Diagnostic output already exists: " + path.string());
std::ofstream out(path);
out.exceptions(std::ios::badbit | std::ios::failbit);
out << std::setprecision(17);
return out;
}
struct SurfaceFace {
int face, element, axis;
double coordinate;
};
struct Topology {
std::vector<SurfaceFace> surface;
std::vector<int> layer;
std::vector<std::vector<int>> faces;
};
inline Topology BuildTopology(polytrope_validation::PhysicalState &state) {
auto &mesh = *state.finiteElements.mesh;
Topology result;
result.layer.assign(mesh.GetNE(), -1);
result.faces.resize(mesh.GetNE());
std::vector<std::vector<int>> neighbors(mesh.GetNE());
std::queue<int> queue;
for (int face = 0; face < mesh.GetNumFaces(); ++face) {
int left = -1, right = -1;
mesh.GetFaceElements(face, &left, &right);
const bool leftStar = left >= 0 && state.isStellar(left);
const bool rightStar = right >= 0 && state.isStellar(right);
if (leftStar && rightStar) {
neighbors[left].push_back(right);
neighbors[right].push_back(left);
}
if (leftStar == rightStar)
continue;
const int element = leftStar ? left : right;
auto *transformation = mesh.GetFaceElementTransformations(face);
if (transformation == nullptr)
throw std::runtime_error("Missing stellar interface transformation.");
mfem::IntegrationPoint facePoint, point;
facePoint.Set2(0.5, 0.5);
if (leftStar)
transformation->Loc1.Transform(facePoint, point);
else
transformation->Loc2.Transform(facePoint, point);
const std::array<double, 3> coordinate{point.x, point.y, point.z};
int axis = -1;
double value = 0.;
for (int d = 0; d < 3; ++d) {
if (std::abs(coordinate[d]) < 1e-12 || std::abs(coordinate[d] - 1.) < 1e-12) {
if (axis >= 0)
throw std::runtime_error("Ambiguous reference surface face.");
axis = d;
value = std::round(coordinate[d]);
}
}
if (axis < 0)
throw std::runtime_error("Density localization currently requires tensor-product cells.");
result.faces[element].push_back(static_cast<int>(result.surface.size()));
result.surface.push_back({face, element, axis, value});
if (result.layer[element] < 0) {
result.layer[element] = 0;
queue.push(element);
}
}
while (!queue.empty()) {
const int element = queue.front();
queue.pop();
for (const int neighbor : neighbors[element])
if (result.layer[neighbor] < 0) {
result.layer[neighbor] = result.layer[element] + 1;
queue.push(neighbor);
}
}
for (int element = 0; element < mesh.GetNE(); ++element)
if (state.isStellar(element) && result.layer[element] < 0)
throw std::runtime_error("Stellar component is disconnected from its surface.");
return result;
}
struct Aggregate {
std::size_t samples = 0, negative = 0, negativeH = 0, jointNegative = 0;
long double volume = 0., mass = 0., negativeMass = 0., negativeVolume = 0., negativeHVolume = 0.,
closure2 = 0.;
double minimum = INFINITY, maximum = -INFINITY, minimumH = INFINITY;
double negativeHMinimum = INFINITY, negativeHMaximum = -INFINITY;
double negativeRadiusMinimum = INFINITY, negativeRadiusMaximum = -INFINITY;
double negativeReferenceDepthMinimum = INFINITY, negativeReferenceDepthMaximum = -INFINITY;
void
Add(double rho,
double h,
double rhoH,
double radius,
double depth,
double weight) {
++samples;
volume += weight;
mass += weight * rho;
closure2 += weight * (rho - rhoH) * (rho - rhoH);
minimum = std::min(minimum, rho);
maximum = std::max(maximum, rho);
minimumH = std::min(minimumH, h);
if (h < 0.) {
++negativeH;
negativeHVolume += weight;
}
if (rho >= 0.)
return;
++negative;
if (h < 0.)
++jointNegative;
negativeMass -= weight * rho;
negativeVolume += weight;
negativeHMinimum = std::min(negativeHMinimum, h);
negativeHMaximum = std::max(negativeHMaximum, h);
negativeRadiusMinimum = std::min(negativeRadiusMinimum, radius);
negativeRadiusMaximum = std::max(negativeRadiusMaximum, radius);
if (std::isfinite(depth)) {
negativeReferenceDepthMinimum = std::min(negativeReferenceDepthMinimum, depth);
negativeReferenceDepthMaximum = std::max(negativeReferenceDepthMaximum, depth);
}
}
};
inline double Observed(double v) {
return std::isfinite(v) ? v : std::numeric_limits<double>::quiet_NaN();
}
inline void Header(std::ostream &out) {
out << "samples,negative_samples,negative_h_samples,joint_negative_samples,volume,mass,negative_mass,"
"negative_volume,negative_h_volume,closure_squared_integral,minimum_density,maximum_density,minimum_"
"h,minimum_h_at_negative_rho,maximum_h_at_negative_rho,negative_radius_minimum,negative_radius_"
"maximum,negative_reference_depth_minimum,negative_reference_depth_maximum\n";
}
inline void Write(
std::ostream &out,
const Aggregate &a
) {
out << a.samples << ',' << a.negative << ',' << a.negativeH << ',' << a.jointNegative << ',' << a.volume
<< ',' << a.mass << ',' << a.negativeMass << ',' << a.negativeVolume << ',' << a.negativeHVolume << ','
<< a.closure2 << ',' << Observed(a.minimum) << ',' << Observed(a.maximum) << ',' << Observed(a.minimumH)
<< ',' << Observed(a.negativeHMinimum) << ',' << Observed(a.negativeHMaximum) << ','
<< Observed(a.negativeRadiusMinimum) << ',' << Observed(a.negativeRadiusMaximum) << ','
<< Observed(a.negativeReferenceDepthMinimum) << ',' << Observed(a.negativeReferenceDepthMaximum)
<< '\n';
}
inline double ReferenceDepth(
const Topology &topology,
int element,
const mfem::IntegrationPoint &point
) {
const std::array<double, 3> coordinates{point.x, point.y, point.z};
double depth = INFINITY;
for (const int index : topology.faces[element]) {
const auto &face = topology.surface[index];
depth = std::min(depth, std::abs(coordinates[face.axis] - face.coordinate));
}
return Observed(depth);
}
} // namespace negative_density_detail
inline void RecordNegativeDensity(
polytrope_validation::PhysicalState &state,
double n,
double K,
const std::filesystem::path &output
) {
namespace d = negative_density_detail;
const auto topology = d::BuildTopology(state);
const auto projections = MeasureNegativeDensityProjection(state, n, K, output);
auto &mesh = *state.finiteElements.mesh;
auto topologyFile = d::Open(output / "density_element_topology.csv");
topologyFile << "element,attribute,surface_layer,surface_face_count,density_order,enthalpy_order,density_dof_"
"minimum,density_dof_maximum\n";
mfem::Array<int> dofs;
mfem::Vector coefficients;
for (int element = 0; element < mesh.GetNE(); ++element)
if (state.isStellar(element)) {
auto *transform = state.finiteElements.densityFes->GetElementVDofs(element, dofs);
state.density.GetSubVector(dofs, coefficients);
if (transform)
transform->InvTransformPrimal(coefficients);
topologyFile << element << ',' << mesh.GetAttribute(element) << ',' << topology.layer[element] << ','
<< topology.faces[element].size() << ','
<< state.finiteElements.densityFes->GetFE(element)->GetOrder() << ','
<< state.finiteElements.enthalpyFes->GetFE(element)->GetOrder() << ','
<< coefficients.Min() << ',' << coefficients.Max() << '\n';
}
auto globalFile = d::Open(output / "density_summary.csv");
globalFile << "quadrature,field,";
d::Header(globalFile);
auto elementFile = d::Open(output / "density_elements.csv");
elementFile << "quadrature,field,element,attribute,surface_layer,";
d::Header(elementFile);
auto radialFile = d::Open(output / "density_radial_bins.csv");
radialFile << "quadrature,field,radial_bin_left,radial_bin_right,";
d::Header(radialFile);
auto negativeFile = d::Open(output / "negative_density_samples.csv");
negativeFile << "quadrature,element,attribute,surface_layer,xi,eta,zeta,x,y,z,radius,reference_inward_depth,"
"weight,rho,h,rho_from_h";
for (const auto &control : projections.controls)
negativeFile << ",rho_projected_" << control.label;
negativeFile << '\n';
std::vector<std::string> labels{"state", "eos_pointwise"};
for (const auto &control : projections.controls)
labels.push_back(control.label);
const double factor = (n + 1.) * K;
mean_field::mapping::MappingPointContext mapped;
for (const int order : {18, 26}) {
std::cout << "Density localization quadrature " << order << std::endl;
std::vector<d::Aggregate> global(labels.size());
std::vector<std::map<int, d::Aggregate>> radial(labels.size());
for (int element = 0; element < mesh.GetNE(); ++element) {
if (!state.isStellar(element))
continue;
auto *transformation = mesh.GetElementTransformation(element);
if (transformation->GetGeometryType() != mfem::Geometry::CUBE)
throw std::runtime_error("Density localization requires hexahedral elements.");
const auto &rule = mfem::IntRules.Get(transformation->GetGeometryType(), order);
std::vector<d::Aggregate> local(labels.size());
for (int q = 0; q < rule.GetNPoints(); ++q) {
const auto &point = rule.IntPoint(q);
if (state.mapping.EvaluatePoint(*transformation, point, mapped) !=
mean_field::mapping::MappingStatus::valid)
throw std::runtime_error("Invalid mapping during density localization.");
transformation->SetIntPoint(&point);
const double weight = point.weight * transformation->Jacobian().Det() * mapped.mapping_determinant;
if (!std::isfinite(weight) || weight <= 0.)
throw std::runtime_error("Invalid density observation weight.");
const double rho = state.density.GetValue(element, point);
const double h = state.enthalpy.GetValue(element, point);
if (!std::isfinite(rho) || !std::isfinite(h))
throw std::runtime_error("Nonfinite observed density or enthalpy.");
const double rhoH = h > 0. ? std::pow(h / factor, n) : 0.;
const double radius = mapped.physical_position.Norml2();
const double depth = d::ReferenceDepth(topology, element, point);
std::vector<double> densities{rho, rhoH};
for (const auto &control : projections.controls)
densities.push_back(control.density->GetValue(element, point));
const int bin = static_cast<int>(std::floor(radius * 200.));
for (std::size_t field = 0; field < labels.size(); ++field) {
if (!std::isfinite(densities[field]))
throw std::runtime_error("Nonfinite projected density.");
local[field].Add(densities[field], h, rhoH, radius, depth, weight);
global[field].Add(densities[field], h, rhoH, radius, depth, weight);
radial[field][bin].Add(densities[field], h, rhoH, radius, depth, weight);
}
// Retain every negative-state point at the finer rule. Volume
// statistics above include all points, so this sparse export
// cannot silently redefine the denominator of a fraction.
if (rho < 0. && order == 26) {
negativeFile << order << ',' << element << ',' << mesh.GetAttribute(element) << ','
<< topology.layer[element] << ',' << point.x << ',' << point.y << ',' << point.z;
for (int axis = 0; axis < 3; ++axis)
negativeFile << ',' << mapped.physical_position(axis);
negativeFile << ',' << radius << ',' << depth << ',' << weight << ',' << rho << ',' << h << ','
<< rhoH;
for (std::size_t field = 2; field < densities.size(); ++field)
negativeFile << ',' << densities[field];
negativeFile << '\n';
}
}
for (std::size_t field = 0; field < labels.size(); ++field) {
elementFile << order << ',' << labels[field] << ',' << element << ',' << mesh.GetAttribute(element)
<< ',' << topology.layer[element] << ',';
d::Write(elementFile, local[field]);
}
}
for (std::size_t field = 0; field < labels.size(); ++field) {
globalFile << order << ',' << labels[field] << ',';
d::Write(globalFile, global[field]);
for (const auto &[bin, value] : radial[field]) {
radialFile << order << ',' << labels[field] << ',' << bin / 200. << ',' << (bin + 1) / 200. << ',';
d::Write(radialFile, value);
}
}
globalFile.flush();
elementFile.flush();
radialFile.flush();
negativeFile.flush();
}
// Surface-inward traces include the face itself, which volume Gauss rules
// never sample. The direction is a reference-cell coordinate line, not a
// physical normal or an assumed spherical radial line.
auto traces = d::Open(output / "density_surface_traces.csv");
traces << "face,element,tangent_u,tangent_v,inward_coordinate,x,y,z,radius,distance_from_face,rho,h,rho_from_h";
for (const auto &control : projections.controls)
traces << ",rho_projected_" << control.label;
traces << '\n';
constexpr std::array<double, 5> tangents{0., .25, .5, .75, 1.};
constexpr std::array<double, 17> depths{0., .001, .003, .007, .01, .02, .03, .04, .06,
.08, .1, .15, .2, .3, .5, .75, 1.};
for (const auto &face : topology.surface) {
auto *transformation = mesh.GetElementTransformation(face.element);
const int axis1 = (face.axis + 1) % 3, axis2 = (face.axis + 2) % 3;
for (const double u : tangents)
for (const double v : tangents) {
mfem::Vector boundaryPosition(3);
for (const double depth : depths) {
std::array<double, 3> coordinate{};
coordinate[face.axis] = face.coordinate == 0. ? depth : 1. - depth;
coordinate[axis1] = u;
coordinate[axis2] = v;
mfem::IntegrationPoint point;
point.Set3(coordinate[0], coordinate[1], coordinate[2]);
if (state.mapping.EvaluatePoint(*transformation, point, mapped) !=
mean_field::mapping::MappingStatus::valid)
throw std::runtime_error("Invalid surface-inward trace mapping.");
if (depth == 0.)
boundaryPosition = mapped.physical_position;
mfem::Vector distance(mapped.physical_position);
distance -= boundaryPosition;
const double rho = state.density.GetValue(face.element, point),
h = state.enthalpy.GetValue(face.element, point);
traces << face.face << ',' << face.element << ',' << u << ',' << v << ',' << depth;
for (int axis = 0; axis < 3; ++axis)
traces << ',' << mapped.physical_position(axis);
traces << ',' << mapped.physical_position.Norml2() << ',' << distance.Norml2() << ',' << rho
<< ',' << h << ',' << (h > 0. ? std::pow(h / factor, n) : 0.);
for (const auto &control : projections.controls)
traces << ',' << control.density->GetValue(face.element, point);
traces << '\n';
}
}
}
auto scope = d::Open(output / "density_scope.txt");
scope << "Frozen observations only; no equilibrium state, operator or field space is modified.\n"
<< "density_basis=" << state.finiteElements.densityFes->FEColl()->Name() << '\n'
<< "enthalpy_basis=" << state.finiteElements.enthalpyFes->FEColl()->Name() << '\n'
<< "surface_faces=" << topology.surface.size() << '\n'
<< "Surface layer is graph distance through stellar face neighbors to a stellar/nonstellar interface.\n"
<< "Reference inward depth is available only in cells touching that interface.\n"
<< "Radial bins are in current physical coordinates with the diagnostic's zero center and unit reference "
"radius.\n"
<< "Quadrature extrema and trace extrema are observations, not polynomial sign certificates.\n";
}
} // namespace experiment::plateau_diagnostics

View File

@@ -0,0 +1,403 @@
#pragma once
// Include after import mean_field. These element-local projections diagnose the
// weak closure at a frozen geometry and enthalpy; they are never state updates.
#include <algorithm>
#include <array>
#include <cmath>
#include <cstring>
#include <filesystem>
#include <fstream>
#include <iomanip>
#include <limits>
#include <memory>
#include <stdexcept>
#include <string>
#include <utility>
#include <vector>
#include "polytrope_physical_state.hpp"
namespace experiment::plateau_diagnostics {
struct DensityProjectionControl final {
std::string label;
// -1 denotes the production query, whose resolved order is recorded for
// each element. Explicit controls use ordinary MFEM rules of this order.
int quadratureOrder;
bool productionQuadrature;
std::unique_ptr<mfem::ParGridFunction> density;
};
struct NegativeDensityProjectionReport final {
// The spaces remain borrowed from PhysicalState::finiteElements. Values on
// vacuum elements are zero storage, not a physical extension of the star.
std::vector<DensityProjectionControl> controls;
};
namespace negative_density_projection_detail {
inline double Norm(const mfem::Vector& vector) {
long double squared = 0.0L;
for (int i = 0; i < vector.Size(); ++i) {
if (!std::isfinite(vector(i))) throw std::domain_error("Nonfinite projection vector.");
squared += static_cast<long double>(vector(i)) * vector(i);
}
const double norm = static_cast<double>(std::sqrt(squared));
if (!std::isfinite(norm)) throw std::domain_error("Projection norm overflow.");
return norm;
}
inline double Relative(const double numerator, const double denominator) {
return denominator > 0.0 ? numerator / denominator
: (numerator == 0.0 ? 0.0 : std::numeric_limits<double>::infinity());
}
inline void WriteVector(const std::filesystem::path& path, const mfem::Vector& vector) {
std::ofstream stream(path);
stream.exceptions(std::ios::failbit | std::ios::badbit);
stream << std::setprecision(17) << vector.Size() << '\n';
for (int i = 0; i < vector.Size(); ++i) stream << vector(i) << '\n';
}
// The independent, small Cholesky solve keeps this diagnostic separate from
// the production density inverse. A bad mass matrix must not be regularized:
// that would change the equation whose negative solution we are investigating.
inline mfem::DenseMatrix Factor(const mfem::DenseMatrix& mass) {
const int size = mass.Height();
mfem::DenseMatrix lower(size);
lower = 0.0;
double scale = 0.0;
for (int i = 0; i < size; ++i) scale = std::max(scale, mass(i, i));
if (!(scale > 0.0) || !std::isfinite(scale))
throw std::domain_error("Invalid density projection mass diagonal.");
for (int i = 0; i < size; ++i) {
for (int j = 0; j <= i; ++j) {
long double value = mass(i, j);
for (int k = 0; k < j; ++k) value -= static_cast<long double>(lower(i, k)) * lower(j, k);
if (i == j) {
if (!std::isfinite(value) || value <= 64.0L * std::numeric_limits<double>::epsilon() * scale)
throw std::domain_error("Density projection mass is singular or numerically unresolved.");
lower(i, j) = static_cast<double>(std::sqrt(value));
} else {
lower(i, j) = static_cast<double>(value / lower(j, j));
if (!std::isfinite(lower(i, j))) throw std::domain_error("Nonfinite mass factor.");
}
}
}
return lower;
}
inline mfem::Vector Solve(const mfem::DenseMatrix& lower, const mfem::Vector& rhs) {
mfem::Vector result(rhs);
for (int i = 0; i < result.Size(); ++i) {
long double value = result(i);
for (int j = 0; j < i; ++j) value -= static_cast<long double>(lower(i, j)) * result(j);
result(i) = static_cast<double>(value / lower(i, i));
}
for (int i = result.Size() - 1; i >= 0; --i) {
long double value = result(i);
for (int j = i + 1; j < result.Size(); ++j) value -= static_cast<long double>(lower(j, i)) * result(j);
result(i) = static_cast<double>(value / lower(i, i));
}
(void)Norm(result);
return result;
}
inline mfem::Vector Defect(const mfem::DenseMatrix& mass, const mfem::Vector& coefficients,
const mfem::Vector& rhs) {
mfem::Vector result(rhs.Size());
for (int i = 0; i < rhs.Size(); ++i) {
long double value = -static_cast<long double>(rhs(i));
for (int j = 0; j < coefficients.Size(); ++j)
value += static_cast<long double>(mass(i, j)) * coefficients(j);
result(i) = static_cast<double>(value);
}
return result;
}
inline void VerifySolve(const mfem::DenseMatrix& mass, const mfem::Vector& coefficients,
const mfem::Vector& rhs, const mfem::Vector& defect) {
long double massSquared = 0.0L;
for (int i = 0; i < mass.Height(); ++i)
for (int j = 0; j < mass.Width(); ++j)
massSquared += static_cast<long double>(mass(i, j)) * mass(i, j);
const long double scale = Norm(rhs) + std::sqrt(massSquared) * Norm(coefficients);
if (!std::isfinite(scale) || Norm(defect) > 1.0e-11L * scale)
throw std::runtime_error("Local density projection failed its independent normal-equation check.");
}
inline bool Identical(const mfem::Vector& first, const mfem::Vector& second) {
return first.Size() == second.Size() &&
(first.Size() == 0 || std::memcmp(first.GetData(), second.GetData(),
sizeof(double) * static_cast<std::size_t>(first.Size())) == 0);
}
struct Totals final {
int elements{0};
long double volume{0.0L}, projectedSavedSquared{0.0L}, projectedTargetSquared{0.0L}, savedTargetSquared{0.0L};
long double projectedDefectSquared{0.0L}, savedDefectSquared{0.0L};
double minimumSavedCoefficient{std::numeric_limits<double>::infinity()};
double minimumProjectedCoefficient{std::numeric_limits<double>::infinity()};
double maximumCoefficientDifference{0.0}, maximumConstantCoefficientError{0.0}, maximumConstantSampleError{0.0};
};
} // namespace negative_density_projection_detail
inline NegativeDensityProjectionReport MeasureNegativeDensityProjection(
experiment::polytrope_validation::PhysicalState& state, const double n, const double K,
const std::filesystem::path& output) {
namespace detail = negative_density_projection_detail;
using namespace mean_field;
const eos::Polytrope equationOfState(n, K);
const auto& fem = state.finiteElements;
if (!fem.mesh || !fem.densityFes || !fem.enthalpyFes || !fem.compactificationCoordinate ||
!fem.quadratureFactory || fem.mesh->Dimension() != 3 || !fem.mesh->Conforming() ||
fem.densityFes->GetVDim() != 1 ||
dynamic_cast<const mfem::L2_FECollection*>(fem.densityFes->FEColl()) == nullptr ||
state.density.ParFESpace() != fem.densityFes.get() || state.enthalpy.ParFESpace() != fem.enthalpyFes.get())
throw std::invalid_argument("Density projection diagnostics require the current scalar conforming L2 density space.");
int ranks = 0;
MPI_Comm_size(fem.mesh->GetComm(), &ranks);
if (ranks != 1) throw std::invalid_argument("Density projection diagnostics require one MPI rank.");
const double extra = (n - 1.0) * static_cast<double>(field::Enthalpy::Scalar::familyOrder);
if (!std::isfinite(extra) || extra < 0.0 || extra > std::numeric_limits<int>::max())
throw std::invalid_argument("Invalid production EOS quadrature order.");
const int extraOrder = static_cast<int>(std::ceil(extra));
std::filesystem::create_directories(output);
const auto elementsPath = output / "negative_density_projection_elements.csv";
const auto summaryPath = output / "negative_density_projection_summary.csv";
const auto productionResidualPath = output / "projection_production_closure_residual_full.txt";
if (std::filesystem::exists(elementsPath) || std::filesystem::exists(summaryPath) ||
std::filesystem::exists(productionResidualPath))
throw std::invalid_argument("Density projection diagnostics require fresh output files.");
NegativeDensityProjectionReport report;
for (const auto& [label, order] : std::array<std::pair<const char*, int>, 3>{
std::pair{"production", -1}, std::pair{"q18", 18}, std::pair{"q26", 26}}) {
const auto vectorPath = output / (std::string("negative_density_projection_") + label + "_coefficients.txt");
if (std::filesystem::exists(vectorPath))
throw std::invalid_argument("Density projection diagnostics would overwrite saved coefficients.");
auto projected = std::make_unique<mfem::ParGridFunction>(fem.densityFes.get());
*projected = 0.0;
report.controls.push_back({label, order, order < 0, std::move(projected)});
}
const mfem::Vector savedDensity(state.density), savedEnthalpy(state.enthalpy), savedPotential(state.potential),
savedGravity(state.gravityGradientReference), savedDisplacement(state.displacement);
// Even the observer's mapping cache is private here. No trial preparation,
// normalization, accepted buffer, or prepared operator is involved.
mapping::GridFunctionMappingEvaluator mapper(state.domainMapper, state.displacement, *fem.compactificationCoordinate);
mfem::ParGridFunction constant(fem.densityFes.get());
mfem::ConstantCoefficient one(1.0);
constant.ProjectCoefficient(one);
mfem::Vector fullClosureResidual(fem.densityFes->GetVSize());
fullClosureResidual = 0.0;
std::array<detail::Totals, 3> totals;
std::vector<bool> visited(static_cast<std::size_t>(fem.densityFes->GetVSize()), false);
std::ofstream elements(elementsPath), summary(summaryPath);
elements.exceptions(std::ios::failbit | std::ios::badbit);
summary.exceptions(std::ios::failbit | std::ios::badbit);
elements << std::setprecision(17);
summary << std::setprecision(17) << "control,metric,value\n";
elements << "control,requested_order,quadrature_order,quadrature_points,element,attribute,density_order,enthalpy_order,"
"basis_family,dofs,volume,minimum_h,minimum_target_density,saved_coefficient_minimum,saved_coefficient_maximum,"
"projected_coefficient_minimum,projected_coefficient_maximum,coefficient_difference_norm,coefficient_relative_difference,"
"coefficient_maximum_difference,rhs_norm,projected_normal_defect_norm,projected_normal_relative_defect,"
"saved_normal_defect_norm,saved_normal_relative_defect,projection_vs_saved_l2,projection_vs_target_l2,saved_vs_target_l2,"
"minimum_projected_sampled_density,minimum_saved_sampled_density,constant_normal_defect_norm,"
"constant_coefficient_error_maximum,constant_sample_error_maximum\n";
for (int element = 0; element < fem.mesh->GetNE(); ++element) {
if (!state.isStellar(element)) continue;
const auto* densityElement = fem.densityFes->GetFE(element);
const auto* enthalpyElement = fem.enthalpyFes->GetFE(element);
if (!densityElement || !enthalpyElement || densityElement->GetMapType() != mfem::FiniteElement::VALUE ||
densityElement->GetOrder() != field::Density::Scalar::familyOrder ||
enthalpyElement->GetOrder() != field::Enthalpy::Scalar::familyOrder)
throw std::invalid_argument("Density projection FE elements do not match the production scalar fields.");
mfem::Array<int> dofs;
if (fem.densityFes->GetElementDofs(element, dofs) != nullptr)
throw std::invalid_argument("Density projection does not support transformed element DOFs.");
if (dofs.Size() != densityElement->GetDof()) throw std::logic_error("Density element layout mismatch.");
for (int i = 0; i < dofs.Size(); ++i) {
if (dofs[i] < 0 || dofs[i] >= fullClosureResidual.Size() || visited[static_cast<std::size_t>(dofs[i])])
throw std::invalid_argument("Density projection requires independent, unsigned element-local DOFs.");
visited[static_cast<std::size_t>(dofs[i])] = true;
}
mfem::Vector saved, constantExpected;
state.density.GetSubVector(dofs, saved);
constant.GetSubVector(dofs, constantExpected);
(void)detail::Norm(saved);
auto* transformation = fem.mesh->GetElementTransformation(element);
for (std::size_t controlIndex = 0; controlIndex < report.controls.size(); ++controlIndex) {
auto& control = report.controls[controlIndex];
auto& total = totals[controlIndex];
const mfem::IntegrationRule* rule = nullptr;
int resolvedOrder = control.quadratureOrder;
if (control.productionQuadrature) {
// Reproduce the shared production rule, including the density
// mass degree when it exceeds the nonlinear source degree.
const auto query = field::Field<field::Enthalpy>::make_query<field::Enthalpy::Form::EosClosureSource>(
quadrature::QuadratureRole::discretization, transformation->OrderW(), std::array<int, 1>{extraOrder},
utils::DOMAINS::STELLAR, quadrature::MappingKind::general);
const auto sourceResolution = fem.quadratureFactory->get(query, transformation->GetGeometryType());
const auto massQuery = field::Field<field::Density>::make_query<field::Density::Form::EosClosureMass>(
quadrature::QuadratureRole::discretization, transformation->OrderW(), {},
utils::DOMAINS::STELLAR, quadrature::MappingKind::general);
const auto massResolution = fem.quadratureFactory->get(massQuery, transformation->GetGeometryType());
const auto &resolution = sourceResolution.resolution.order >= massResolution.resolution.order
? sourceResolution
: massResolution;
rule = resolution.integration_rule;
resolvedOrder = resolution.resolution.order;
} else {
rule = &mfem::IntRules.Get(transformation->GetGeometryType(), resolvedOrder);
}
if (!rule || rule->GetNPoints() == 0) throw std::runtime_error("Missing density projection quadrature.");
const int size = dofs.Size(), points = rule->GetNPoints();
mfem::DenseMatrix mass(size), samples(points, size);
mfem::Vector rhs(size), constantRhs(size), shape(size), weights(points), targets(points);
mass = 0.0;
rhs = 0.0;
constantRhs = 0.0;
double minimumH = std::numeric_limits<double>::infinity();
double minimumTarget = minimumH;
long double volume = 0.0L;
for (int q = 0; q < points; ++q) {
const auto& ip = rule->IntPoint(q);
mapping::MappingPointContext mapped;
if (mapper.EvaluatePoint(*transformation, ip, mapped) != mapping::MappingStatus::valid || mapped.compactified)
throw std::domain_error("Invalid stellar mapping during density projection.");
const double h = state.enthalpy.GetValue(element, ip);
if (!std::isfinite(h) || h < 0.0)
throw std::domain_error("Density projection encountered negative or nonfinite enthalpy; EOS was not clipped.");
const double target = eos::evaluate<eos::quantity::Density>(
equationOfState, dimensions::SpecificEnthalpyValue{h}).value();
transformation->SetIntPoint(&ip);
const double referenceDeterminant = transformation->Jacobian().Det();
const double weight = ip.weight * referenceDeterminant * mapped.mapping_determinant;
if (!(referenceDeterminant > 0.0) || !std::isfinite(referenceDeterminant) ||
!(mapped.mapping_determinant > 0.0) || !std::isfinite(mapped.mapping_determinant) ||
!(weight > 0.0) || !std::isfinite(weight) || target < 0.0 || !std::isfinite(target))
throw std::domain_error("Invalid density projection weight or EOS value.");
densityElement->CalcShape(ip, shape);
(void)detail::Norm(shape);
weights(q) = weight;
targets(q) = target;
volume += weight;
minimumH = std::min(minimumH, h);
minimumTarget = std::min(minimumTarget, target);
for (int i = 0; i < size; ++i) {
samples(q, i) = shape(i);
rhs(i) += weight * shape(i) * target;
constantRhs(i) += weight * shape(i);
for (int j = 0; j < size; ++j) mass(i, j) += weight * shape(i) * shape(j);
}
}
const auto lower = detail::Factor(mass);
const auto coefficients = detail::Solve(lower, rhs);
const auto constantCoefficients = detail::Solve(lower, constantRhs);
const auto projectedDefect = detail::Defect(mass, coefficients, rhs);
const auto savedDefect = detail::Defect(mass, saved, rhs);
const auto constantDefect = detail::Defect(mass, constantCoefficients, constantRhs);
detail::VerifySolve(mass, coefficients, rhs, projectedDefect);
detail::VerifySolve(mass, constantCoefficients, constantRhs, constantDefect);
control.density->SetSubVector(dofs, coefficients);
if (control.productionQuadrature) fullClosureResidual.SetSubVector(dofs, savedDefect);
mfem::Vector difference(coefficients);
difference -= saved;
double minimumSaved = std::numeric_limits<double>::infinity(), maximumSaved = -minimumSaved;
double minimumProjected = minimumSaved, maximumProjected = -minimumSaved;
double maximumDifference = 0.0, constantCoefficientError = 0.0, constantSampleError = 0.0;
for (int i = 0; i < size; ++i) {
minimumSaved = std::min(minimumSaved, saved(i));
maximumSaved = std::max(maximumSaved, saved(i));
minimumProjected = std::min(minimumProjected, coefficients(i));
maximumProjected = std::max(maximumProjected, coefficients(i));
maximumDifference = std::max(maximumDifference, std::abs(difference(i)));
constantCoefficientError = std::max(constantCoefficientError, std::abs(constantCoefficients(i) - constantExpected(i)));
}
long double projectedSavedSquared = 0.0L, projectedTargetSquared = 0.0L, savedTargetSquared = 0.0L;
double minimumProjectedSample = std::numeric_limits<double>::infinity(), minimumSavedSample = minimumProjectedSample;
for (int q = 0; q < points; ++q) {
long double projectedValue = 0.0L, savedValue = 0.0L, constantValue = 0.0L;
for (int i = 0; i < size; ++i) {
projectedValue += static_cast<long double>(samples(q, i)) * coefficients(i);
savedValue += static_cast<long double>(samples(q, i)) * saved(i);
constantValue += static_cast<long double>(samples(q, i)) * constantCoefficients(i);
}
const long double differenceValue = projectedValue - savedValue;
const long double projectedError = projectedValue - targets(q), savedError = savedValue - targets(q);
projectedSavedSquared += weights(q) * differenceValue * differenceValue;
projectedTargetSquared += weights(q) * projectedError * projectedError;
savedTargetSquared += weights(q) * savedError * savedError;
minimumProjectedSample = std::min(minimumProjectedSample, static_cast<double>(projectedValue));
minimumSavedSample = std::min(minimumSavedSample, static_cast<double>(savedValue));
constantSampleError = std::max(constantSampleError, static_cast<double>(std::abs(constantValue - 1.0L)));
}
if (!std::isfinite(constantCoefficientError) || !std::isfinite(constantSampleError) ||
constantCoefficientError > 1.0e-10 || constantSampleError > 1.0e-10)
throw std::runtime_error("Density projection failed independent constant reconstruction.");
const double rhsNorm = detail::Norm(rhs), projectedDefectNorm = detail::Norm(projectedDefect);
const double savedDefectNorm = detail::Norm(savedDefect);
elements << control.label << ',' << control.quadratureOrder << ',' << resolvedOrder << ',' << points << ','
<< element << ',' << fem.mesh->GetAttribute(element) << ',' << densityElement->GetOrder() << ','
<< enthalpyElement->GetOrder() << ',' << std::quoted(fem.densityFes->FEColl()->Name()) << ',' << size << ','
<< volume << ',' << minimumH << ',' << minimumTarget << ',' << minimumSaved << ',' << maximumSaved << ','
<< minimumProjected << ',' << maximumProjected << ',' << detail::Norm(difference) << ','
<< detail::Relative(detail::Norm(difference), detail::Norm(saved)) << ',' << maximumDifference << ','
<< rhsNorm << ',' << projectedDefectNorm << ',' << detail::Relative(projectedDefectNorm, rhsNorm) << ','
<< savedDefectNorm << ',' << detail::Relative(savedDefectNorm, rhsNorm) << ','
<< std::sqrt(projectedSavedSquared) << ',' << std::sqrt(projectedTargetSquared) << ','
<< std::sqrt(savedTargetSquared) << ',' << minimumProjectedSample << ',' << minimumSavedSample << ','
<< detail::Norm(constantDefect) << ',' << constantCoefficientError << ',' << constantSampleError << '\n';
++total.elements;
total.volume += volume;
total.projectedSavedSquared += projectedSavedSquared;
total.projectedTargetSquared += projectedTargetSquared;
total.savedTargetSquared += savedTargetSquared;
total.projectedDefectSquared += static_cast<long double>(projectedDefectNorm) * projectedDefectNorm;
total.savedDefectSquared += static_cast<long double>(savedDefectNorm) * savedDefectNorm;
total.minimumSavedCoefficient = std::min(total.minimumSavedCoefficient, minimumSaved);
total.minimumProjectedCoefficient = std::min(total.minimumProjectedCoefficient, minimumProjected);
total.maximumCoefficientDifference = std::max(total.maximumCoefficientDifference, maximumDifference);
total.maximumConstantCoefficientError = std::max(total.maximumConstantCoefficientError, constantCoefficientError);
total.maximumConstantSampleError = std::max(total.maximumConstantSampleError, constantSampleError);
}
}
const bool fieldsIdentical = detail::Identical(savedDensity, state.density) && detail::Identical(savedEnthalpy, state.enthalpy) &&
detail::Identical(savedPotential, state.potential) && detail::Identical(savedGravity, state.gravityGradientReference) &&
detail::Identical(savedDisplacement, state.displacement);
if (!fieldsIdentical) throw std::logic_error("Density projection diagnostic changed a source field.");
summary << "all,source_fields_bitwise_identical,1\nall,trial_preparations,0\nall,mpi_ranks,1\n"
"all,unsupported_elements_are_zero_storage,1\nall,negative_enthalpy_is_rejected,1\n"
"all,sampled_extrema_are_not_polynomial_certificates,1\n";
for (std::size_t index = 0; index < report.controls.size(); ++index) {
const auto& control = report.controls[index];
const auto& total = totals[index];
if (total.elements == 0) throw std::invalid_argument("Density projection found no stellar elements.");
const auto metric = [&](const char* name, const auto value) { summary << control.label << ',' << name << ',' << value << '\n'; };
metric("elements", total.elements);
metric("local_mass_solves", 2 * total.elements);
metric("volume", total.volume);
metric("projection_vs_saved_l2", std::sqrt(total.projectedSavedSquared));
metric("projection_vs_target_l2", std::sqrt(total.projectedTargetSquared));
metric("saved_vs_target_l2", std::sqrt(total.savedTargetSquared));
metric("projected_normal_defect_norm", std::sqrt(total.projectedDefectSquared));
metric("saved_normal_defect_norm", std::sqrt(total.savedDefectSquared));
metric("saved_coefficient_minimum", total.minimumSavedCoefficient);
metric("projected_coefficient_minimum", total.minimumProjectedCoefficient);
metric("coefficient_maximum_difference", total.maximumCoefficientDifference);
metric("constant_coefficient_error_maximum", total.maximumConstantCoefficientError);
metric("constant_sample_error_maximum", total.maximumConstantSampleError);
detail::WriteVector(output / ("negative_density_projection_" + control.label + "_coefficients.txt"), *control.density);
}
detail::WriteVector(productionResidualPath, fullClosureResidual);
return report;
}
} // namespace experiment::plateau_diagnostics

View File

@@ -0,0 +1,347 @@
#!/usr/bin/env python3
"""Independent surface-cell controls; no FEM state, solver, or limiter is changed.
For inward distance s in [0, width], assume h=kappa*s and rho=A*s**n.
Compare exact, uniformly weighted Q2 L2 projection with interpolation at MFEM's
default L2 Q2 Gauss-Legendre nodes. In one dimension Q2 means degree <= 2.
Extrema, zeros, and negative integrals use quadratic algebra, not plot sampling.
The normalized model is t**n, t=s/width. Physical density is
A*width**n*p(t). Curved metrics, tangential variation, higher terms in h,
and changes in kappa under refinement are deliberately outside this control.
Example:
python negative_density_reference_model.py --self-test
python negative_density_reference_model.py --output /tmp/surface-control --png
Only the optional PNG writer requires matplotlib; all arithmetic is stdlib.
"""
from __future__ import annotations
import argparse
import csv
import hashlib
import json
import math
from decimal import Decimal, localcontext
from fractions import Fraction
from pathlib import Path
import unittest
INDICES = (Fraction(1), Fraction(3, 2), Fraction(3))
INVERSE_MOMENTS = ((9, -36, 30), (-36, 192, -180), (30, -180, 180))
METHODS = ("exact_l2_projection", "gauss_legendre_interpolation")
def decimal(value):
if isinstance(value, Fraction):
return Decimal(value.numerator) / Decimal(value.denominator)
return Decimal(str(value))
def nodes():
r = (Decimal(3) / 5).sqrt()
return ((1 - r) / 2, Decimal("0.5"), (1 + r) / 2)
def exact_value(t, n):
return t * t.sqrt() if n == Fraction(3, 2) else t ** int(n)
def projection(n):
"""Invert the degree-two Hilbert moment matrix with rational arithmetic."""
moments = [1 / (n + j + 1) for j in range(3)]
return tuple(sum(a * b for a, b in zip(row, moments))
for row in INVERSE_MOMENTS)
def interpolation(n):
x = nodes()
values = [exact_value(t, n) for t in x]
slope = (values[2] - values[0]) / (x[2] - x[0])
curvature = (values[2] + values[0] - 2 * values[1]) * 10 / 3
return (values[1] - slope / 2 + curvature / 4,
slope - curvature, curvature)
def coefficients(n, method):
if method == METHODS[0] or n in (1, 3):
# For n=3 the cubic nodal polynomial is the shifted Legendre P3;
# hence its remainder is also the exact L2 projection. Using that
# identity avoids classifying a rounded zero curvature as an n=1 root.
return tuple(decimal(c) for c in projection(n))
return interpolation(n)
def value(c, t):
return c[0] + t * (c[1] + t * c[2])
def integral(c, left=Decimal(0), right=Decimal(1)):
return sum(a * (right ** (j + 1) - left ** (j + 1)) / (j + 1)
for j, a in enumerate(c))
def analyze(c):
a, b, q = c
if q == 0:
roots = [] if b == 0 else [-a / b]
else:
discriminant = b * b - 4 * a * q
roots = ([] if discriminant < 0 else
sorted({(-b - discriminant.sqrt()) / (2 * q),
(-b + discriminant.sqrt()) / (2 * q)}))
unit_roots = [t for t in roots if 0 <= t <= 1]
extrema = [Decimal(0), Decimal(1)]
if q != 0 and 0 < -b / (2 * q) < 1:
extrema.append(-b / (2 * q))
minimum_at = min(extrema, key=lambda t: value(c, t))
bounds = sorted({Decimal(0), Decimal(1), *unit_roots})
negative = [(left, right) for left, right in zip(bounds, bounds[1:])
if value(c, (left + right) / 2) < 0]
return {
"roots_in_cell": unit_roots,
"minimum_at": minimum_at,
"minimum": value(c, minimum_at),
"negative_intervals": negative,
"negative_width_fraction": sum((b - a for a, b in negative), Decimal(0)),
"negative_mass": -sum((integral(c, a, b) for a, b in negative), Decimal(0)),
"cell_mean": integral(c),
"boundary_value": a,
"interior_endpoint_value": value(c, Decimal(1)),
"nonnegative_on_closed_cell": value(c, minimum_at) >= 0,
}
def as_numbers(item):
if isinstance(item, (Decimal, Fraction)):
result = float(item)
if not math.isfinite(result):
raise ValueError("Nonfinite derived output")
return result
if isinstance(item, dict):
return {k: as_numbers(v) for k, v in item.items()}
if isinstance(item, (tuple, list)):
return [as_numbers(v) for v in item]
return item
def case(n, method):
c = coefficients(n, method)
result = analyze(c)
exact_mean = 1 / (decimal(n) + 1)
if n == 1:
exact_roots, exact_minimum = "0", "0"
elif n == 3:
exact_roots, exact_minimum = "1/5-sqrt(6)/30, 1/5+sqrt(6)/30", "-1/100"
elif method == METHODS[0]:
exact_roots, exact_minimum = "(sqrt(174)-12)/30", "-2/105"
else:
exact_roots = "(-c1+sqrt(c1^2-4*c0*c2))/(2*c2); c_j from the algebraic interpolation formula"
exact_minimum = "c0 from the algebraic interpolation formula"
result.update({
"n": n, "method": method, "coefficients_c0_c1_c2": c,
"coefficients_decimal": [str(v) for v in c],
"exact_projection_coefficients": [str(v) for v in projection(n)],
"roots_in_cell_exact": exact_roots, "minimum_exact": exact_minimum,
"exact_cell_mean": exact_mean,
"mean_error": result["cell_mean"] - exact_mean,
"negative_mass_over_exact_cell_mass": result["negative_mass"] / exact_mean,
"values_at_gl_nodes": [value(c, t) for t in nodes()],
"exact_values_at_gl_nodes": [exact_value(t, n) for t in nodes()],
})
return result
def refinement_row(result, width, amplitude):
n = result["n"]
scale = amplitude * exact_value(width, n)
return {
"n": n, "method": result["method"], "width": width,
"amplitude_A": amplitude, "minimum_density": scale * result["minimum"],
"minimum_distance": width * result["minimum_at"],
"negative_width": width * result["negative_width_fraction"],
"negative_mass_per_unit_area": scale * width * result["negative_mass"],
"exact_mass_per_unit_area": scale * width * result["exact_cell_mean"],
"negative_mass_over_exact_cell_mass": result["negative_mass_over_exact_cell_mass"],
}
class ReferenceChecks(unittest.TestCase):
def test_exact_moments(self):
for n in INDICES:
c = projection(n)
for j in range(3):
self.assertEqual(sum(a / (i + j + 1) for i, a in enumerate(c)),
1 / (n + j + 1))
def test_known_coefficients(self):
self.assertEqual(projection(Fraction(1)), (0, 1, 0))
self.assertEqual(projection(Fraction(3, 2)),
(Fraction(-2, 105), Fraction(16, 35), Fraction(4, 7)))
self.assertEqual(projection(Fraction(3)),
(Fraction(1, 20), Fraction(-3, 5), Fraction(3, 2)))
def test_interpolation_and_integer_identity(self):
for n in INDICES:
c = interpolation(n)
for t in nodes():
self.assertLess(abs(value(c, t) - exact_value(t, n)), Decimal("1e-55"))
if n in (1, 3):
for actual, expected in zip(c, coefficients(n, METHODS[1])):
self.assertLess(abs(actual - expected), Decimal("1e-55"))
def test_positive_dofs_do_not_certify_polynomial(self):
for n in (Fraction(3, 2), Fraction(3)):
result = case(n, METHODS[1])
self.assertTrue(all(v > 0 for v in result["values_at_gl_nodes"]))
self.assertLess(result["minimum"], 0)
def test_roots_and_extrema(self):
for method in METHODS:
self.assertTrue(case(Fraction(1), method)["nonnegative_on_closed_cell"])
for n in (Fraction(3, 2), Fraction(3)):
result = case(n, method)
c = coefficients(n, method)
for t in result["roots_in_cell"]:
self.assertLess(abs(value(c, t)), Decimal("1e-55"))
for left, right in result["negative_intervals"]:
self.assertLess(value(c, (left + right) / 2), 0)
self.assertGreater(result["negative_mass"], 0)
cubic = case(Fraction(3), METHODS[0])
self.assertEqual(cubic["minimum_at"], Decimal("0.2"))
self.assertEqual(cubic["minimum"], Decimal("-0.01"))
self.assertGreater(cubic["boundary_value"], 0)
self.assertEqual(cubic["roots_in_cell"],
[Decimal(".2") - Decimal(6).sqrt() / 30,
Decimal(".2") + Decimal(6).sqrt() / 30])
def test_gauss_mean_and_nonconservation_of_interpolation(self):
weights = (Decimal(5) / 18, Decimal(4) / 9, Decimal(5) / 18)
for n in INDICES:
mean = sum(w * exact_value(t, n) for w, t in zip(weights, nodes()))
self.assertLess(abs(mean - integral(interpolation(n))), Decimal("1e-55"))
self.assertLess(case(Fraction(3, 2), METHODS[1])["mean_error"], Decimal("-1e-4"))
def test_refinement_scales(self):
for n in (Fraction(3, 2), Fraction(3)):
for method in METHODS:
result = case(n, method)
coarse = refinement_row(result, Decimal(1), Decimal(7))
fine = refinement_row(result, Decimal(".5"), Decimal(7))
factor = exact_value(Decimal(".5"), n)
for key, expected in (("minimum_density", factor),
("negative_width", Decimal(".5")),
("negative_mass_per_unit_area", factor / 2)):
self.assertLess(abs(fine[key] / coarse[key] - expected), Decimal("1e-55"))
def write_csv(path, rows):
rows = [as_numbers(row) for row in rows]
with path.open("w", newline="") as stream:
writer = csv.DictWriter(stream, fieldnames=list(rows[0]))
writer.writeheader()
for row in rows:
writer.writerow({k: json.dumps(v) if isinstance(v, (list, dict)) else v
for k, v in row.items()})
def plot(output, results, samples):
import matplotlib
matplotlib.use("Agg")
import matplotlib.pyplot as plt
fig, axes = plt.subplots(2, 3, figsize=(12, 6), constrained_layout=True)
ts = [i / (samples - 1) for i in range(samples)]
for column, n in enumerate(INDICES):
for row in range(2):
ax = axes[row, column]
ax.plot(ts, [t ** float(n) for t in ts], "k", label="Exact density")
for result in results:
if result["n"] != n:
continue
c = [float(v) for v in result["coefficients_c0_c1_c2"]]
ax.plot(ts, [value(c, t) for t in ts],
"--" if result["method"] == METHODS[1] else "-",
label="GL interpolation" if result["method"] == METHODS[1] else "L2 projection")
ax.axhline(0, color="0.7", linewidth=0.8)
ax.scatter([float(t) for t in nodes()],
[float(exact_value(t, n)) for t in nodes()], s=18, color="k")
ax.set_title(f"n = {float(n):g}" + ("; near-surface detail" if row else ""))
ax.set_xlabel("Inward distance / cell width")
if row:
ax.set_xlim(0, 0.35)
ax.set_ylim(-0.027, 0.075 if n == 3 else 0.23)
if column == 0:
ax.set_ylabel("Density / (A width^n)")
axes[0, 0].legend(fontsize=8)
fig.suptitle("Uniform 1D surface-cell model: positive nodal data can yield a negative polynomial")
fig.savefig(output / "profiles.png", dpi=170)
plt.close(fig)
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--output", type=Path, help="Fresh directory for JSON and CSV artifacts")
parser.add_argument("--self-test", action="store_true")
parser.add_argument("--png", action="store_true", help="Also plot profiles (requires matplotlib)")
parser.add_argument("--widths", nargs="+", default=["1", ".5", ".25", ".125"])
parser.add_argument("--amplitude", default="1", help="A in rho=A*s^n")
parser.add_argument("--samples", type=int, default=501, help="Plot/CSV samples, not extrema checks")
args = parser.parse_args()
widths, amplitude = [Decimal(x) for x in args.widths], Decimal(args.amplitude)
if any(not x.is_finite() or x <= 0 for x in (*widths, amplitude)):
parser.error("Widths and amplitude must be finite and positive")
if args.samples < 2 or (args.png and args.output is None):
parser.error("At least two samples are required; --png requires --output")
with localcontext() as context:
context.prec = 70
if args.self_test:
test_result = unittest.TextTestRunner(verbosity=2).run(
unittest.defaultTestLoader.loadTestsFromTestCase(ReferenceChecks))
if not test_result.wasSuccessful():
raise SystemExit(1)
if args.output is None:
return
results = [case(n, method) for n in INDICES for method in METHODS]
report = {
"schema": "negative_density_reference_model_v1",
"producer_sha256": hashlib.sha256(Path(__file__).read_bytes()).hexdigest(),
"model": "h=kappa*s; rho=A*s^n; t=s/width in [0,1]; uniform physical weight",
"scope": "Analytic mechanism control, not a fit or accuracy certificate for the 3D star",
"arithmetic": "Exact rational projection; 70-digit decimal algebraic interpolation/roots",
"gl_nodes": nodes(), "gl_nodes_exact": "(1-sqrt(3/5))/2, 1/2, (1+sqrt(3/5))/2",
"node_source": "MFEM L2_FECollection defaults to BasisType::GaussLegendre; Q2 tensor element",
"projection_derivation": "c=H^-1 b; H_ij=1/(i+j+1); b_i=1/(n+i+1), i,j=0,1,2",
"interpolation_derivation": "v_j=t_j^n; b=(v_+-v_-)/sqrt(3/5); c=(10/3)*(v_++v_--2v_0); p=v_0+b*(t-.5)+c*(t-.5)^2",
"negative_interval_convention": "Interior points are strictly negative; endpoints are roots except a negative physical-cell endpoint",
"refinement": "rho=A*width^n*p(t); negative mass/area scales width^(n+1); relative first-cell negativity need not disappear",
"cases": results,
}
if args.output is None:
print(json.dumps(as_numbers(report), indent=2, allow_nan=False))
return
args.output.mkdir(parents=True, exist_ok=False)
write_csv(args.output / "summary.csv", results)
write_csv(args.output / "refinement.csv",
[refinement_row(result, width, amplitude) for result in results for width in widths])
profiles = []
for result in results:
for i in range(args.samples):
t = Decimal(i) / (args.samples - 1)
profiles.append({"n": result["n"], "method": result["method"], "t": t,
"exact": exact_value(t, result["n"]),
"approximation": value(result["coefficients_c0_c1_c2"], t)})
write_csv(args.output / "profiles.csv", profiles)
if args.png:
plot(args.output, results, args.samples)
report["artifacts_sha256"] = {p.name: hashlib.sha256(p.read_bytes()).hexdigest()
for p in sorted(args.output.iterdir())}
(args.output / "summary.json").write_text(json.dumps(as_numbers(report), indent=2, allow_nan=False) + "\n")
print(f"Wrote six analytic controls to {args.output}")
if __name__ == "__main__":
main()

View File

@@ -0,0 +1,73 @@
[
{
"id": "n1_equilibrium",
"arguments": [
"--index",
"1",
"--angular-momentum",
"0",
"--surface-prescription",
"harmonics",
"--surface-degree",
"4",
"--no-central",
"--max-newton",
"0",
"--density-regions",
"--density-snapshot",
"../../diagnostics/spherical_harmonic_surface_2026-09-19/campaign/n1_J0_L4"
]
},
{
"id": "n1p5_seed",
"arguments": [
"--index",
"1.5",
"--angular-momentum",
"0",
"--surface-prescription",
"harmonics",
"--surface-degree",
"4",
"--no-central",
"--max-newton",
"0",
"--density-regions"
]
},
{
"id": "n1p5_equilibrium",
"arguments": [
"--index",
"1.5",
"--angular-momentum",
"0",
"--surface-prescription",
"harmonics",
"--surface-degree",
"4",
"--no-central",
"--max-newton",
"0",
"--density-regions",
"--density-snapshot",
"../../diagnostics/spherical_harmonic_surface_2026-09-19/campaign/n1p5_J0_L4"
]
},
{
"id": "n3_seed",
"arguments": [
"--index",
"3",
"--angular-momentum",
"0",
"--surface-prescription",
"harmonics",
"--surface-degree",
"4",
"--max-newton",
"0",
"--density-regions"
]
}
]

View File

@@ -0,0 +1,420 @@
#pragma once
// Include after import mean_field. Root splitting removes the discontinuous
// sign indicator from the integration coordinate; tangential and mapped-volume
// integration still require the quadrature convergence study recorded here.
#include "polytrope_physical_state.hpp"
#include <algorithm>
#include <array>
#include <cmath>
#include <cstring>
#include <filesystem>
#include <fstream>
#include <iomanip>
#include <limits>
#include <string>
#include <vector>
namespace experiment::plateau_diagnostics {
namespace negative_density_regions_detail {
using Real = long double;
struct Polynomial final {
Real c, b, a;
[[nodiscard]] Real Value(Real t) const { return std::fma(std::fma(a, t, b), t, c); }
[[nodiscard]] Real Integral(Real left, Real right) const {
const Real width = right - left;
// Subtracting antiderivatives loses a thin pocket's entire mass when
// both antiderivatives are large. This centered quadratic identity does
// not subtract nearly equal endpoint values.
return width * (Value(left + width / 2) + a * width * width / 12);
}
[[nodiscard]] Real Scale() const { return std::max({std::abs(a), std::abs(b), std::abs(c)}); }
};
struct Interval final { Real left, right; bool negative; };
inline Polynomial Interpolate(Real left, Real middle, Real right) {
return {left, 4 * middle - 3 * left - right, 2 * (left + right - 2 * middle)};
}
inline std::vector<Interval> Partition(const Polynomial& p) {
if (!std::isfinite(p.a) || !std::isfinite(p.b) || !std::isfinite(p.c))
throw std::domain_error("Nonfinite density slice polynomial.");
std::vector<Real> points{0, 1};
const auto add = [&](Real root) {
if (std::isfinite(root) && root > 0 && root < 1) points.push_back(root);
};
const Real scale = p.Scale();
if (scale > 0) {
const Real a = p.a / scale, b = p.b / scale, c = p.c / scale;
// No relative cutoff turns a small quadratic into a line: a thin
// negative interval can be the very effect this diagnostic must retain.
if (a == 0) {
if (b != 0) add(-c / b);
} else {
const Real discriminant = std::fma(-4 * a, c, b * b);
if (discriminant == 0) {
add(-b / (2 * a));
} else if (discriminant > 0) {
const Real q = -Real{0.5} * (b + std::copysign(std::sqrt(discriminant), b));
// The product-of-roots form avoids cancellation at a root near
// the face. q cannot vanish for a positive discriminant.
add(q / a);
add(c / q);
}
}
}
std::sort(points.begin(), points.end());
points.erase(std::unique(points.begin(), points.end()), points.end());
std::vector<Interval> result;
for (std::size_t i = 1; i < points.size(); ++i) {
const Real left = points[i - 1], right = points[i];
if (!(right > left)) throw std::logic_error("Invalid density root partition.");
const Real value = p.Value(left + (right - left) / 2);
const bool negative = value < 0;
// Two extra interior signs catch missed roots without assigning a
// finite-width pocket to an exactly tangent double root.
for (const Real fraction : {Real{0.25}, Real{0.75}}) {
const Real check = p.Value(left + fraction * (right - left));
if ((negative && check > 0) || (!negative && check < 0))
throw std::runtime_error("Density slice root partition has inconsistent interval signs.");
}
result.push_back({left, right, negative});
}
return result;
}
inline std::ofstream Open(const std::filesystem::path& path) {
if (std::filesystem::exists(path)) throw std::invalid_argument("Density region output already exists: " + path.string());
std::ofstream out(path);
out.exceptions(std::ios::failbit | std::ios::badbit);
out << std::setprecision(20);
return out;
}
// These are analytic, uniform-measure one-dimensional controls, independent of
// FEM and geometry. The fractional/cubic data are interpolated at three Gauss
// nodes, reproducing the underresolved positive-profile mechanism of interest.
inline void SelfChecks(const std::filesystem::path& path) {
auto out = Open(path);
out << "case,negative_length,expected_negative_length,negative_mass,expected_negative_mass,passed\n";
const auto check = [&](const char* name, const Polynomial& p, Real expectedLength, Real expectedMass) {
Real length = 0, mass = 0;
for (const auto& interval : Partition(p)) if (interval.negative) {
length += interval.right - interval.left;
mass -= p.Integral(interval.left, interval.right);
}
const bool passed = std::abs(length - expectedLength) <= 2e-14L * std::max(Real{1e-12}, expectedLength) &&
std::abs(mass - expectedMass) <= 2e-13L * std::max(Real{1e-12}, expectedMass);
out << name << ',' << length << ',' << expectedLength << ',' << mass << ',' << expectedMass << ',' << passed << '\n';
if (!passed) throw std::runtime_error(std::string("Density region analytic self-check failed: ") + name);
};
check("positive_quadratic", {1, 0, 1}, 0, 0);
check("negative_constant", {-2, 0, 0}, 1, 2);
check("linear_crossing", {-0.25L, 1, 0}, 0.25L, 0.03125L);
check("double_root_nonnegative", {0.25L, -1, 1}, 0, 0);
check("near_linear_positive", {1, 1, 1e-28L}, 0, 0);
// Exact binary coefficients isolate the root algorithm from the separate
// conditioning of subtracting a tiny decimal offset from a large value.
check("near_double_negative", {0.25L - std::ldexp(Real{1}, -40), -1, 1},
std::ldexp(Real{1}, -19), 4 * std::ldexp(Real{1}, -60) / 3);
const Real d = std::sqrt(Real{15}) / 10;
const auto fractional = [](Real t) { return t * std::sqrt(t); };
const Real y0 = fractional(Real{0.5} - d), y1 = fractional(Real{0.5}), y2 = fractional(Real{0.5} + d);
const Real a = (y0 + y2 - 2 * y1) / (2 * d * d);
const Real b = (y2 - y0) / (2 * d) - a;
const Polynomial fractionalInterpolant{y1 - b / 2 - a / 4, b, a};
check("gauss_q2_t_power_1p5", fractionalInterpolant,
0.04548403175047501373888L, 0.0005262295634284655L);
check("gauss_q2_t_power_3", {0.05L, -0.6L, 1.5L}, std::sqrt(Real{6}) / 15, std::sqrt(Real{6}) / 2250);
}
struct Axis final {
int coordinate{0};
int orientation{1};
int face{-1};
int faceCount{0};
};
inline std::vector<Axis> ChooseAxes(polytrope_validation::PhysicalState& state) {
auto& mesh = *state.finiteElements.mesh;
std::vector<Axis> axes(static_cast<std::size_t>(mesh.GetNE()));
for (int face = 0; face < mesh.GetNumFaces(); ++face) {
int left = -1, right = -1;
mesh.GetFaceElements(face, &left, &right);
const bool leftStar = left >= 0 && state.isStellar(left);
const bool rightStar = right >= 0 && state.isStellar(right);
if (leftStar == rightStar) continue;
const int element = leftStar ? left : right;
auto& axis = axes[static_cast<std::size_t>(element)];
++axis.faceCount;
if (axis.face >= 0) continue;
auto* transformation = mesh.GetFaceElementTransformations(face);
if (!transformation) throw std::runtime_error("Missing density region face transformation.");
mfem::IntegrationPoint facePoint, point;
facePoint.Set2(0.5, 0.5);
if (leftStar) transformation->Loc1.Transform(facePoint, point);
else transformation->Loc2.Transform(facePoint, point);
const std::array<double, 3> coordinates{point.x, point.y, point.z};
int selected = -1;
for (int d = 0; d < 3; ++d) {
if (std::abs(coordinates[d]) < 1e-12 || std::abs(coordinates[d] - 1) < 1e-12) {
if (selected >= 0) throw std::runtime_error("Ambiguous density region reference face.");
selected = d;
}
}
if (selected < 0) throw std::runtime_error("Density region face is not a tensor-product cell face.");
axis.coordinate = selected;
axis.orientation = coordinates[selected] < 0.5 ? 1 : -1;
axis.face = face;
}
return axes;
}
inline mfem::IntegrationPoint Point(const Axis& axis, double u, double v, Real t) {
std::array<double, 3> coordinate{};
coordinate[axis.coordinate] = static_cast<double>(axis.orientation > 0 ? t : 1 - t);
coordinate[(axis.coordinate + 1) % 3] = u;
coordinate[(axis.coordinate + 2) % 3] = v;
mfem::IntegrationPoint result;
result.Set3(coordinate[0], coordinate[1], coordinate[2]);
return result;
}
struct Measure final {
Real volume{0}, mass{0}, negativeVolume{0}, negativeMass{0};
std::size_t lines{0}, negativeIntervals{0}, points{0};
double minimumRho{std::numeric_limits<double>::infinity()};
double witnessH{std::numeric_limits<double>::quiet_NaN()};
double witnessT{std::numeric_limits<double>::quiet_NaN()}, witnessU{witnessT}, witnessV{witnessT};
std::array<double, 3> witnessPosition{};
int witnessElement{-1};
double negativeRadiusMin{std::numeric_limits<double>::infinity()}, negativeRadiusMax{-negativeRadiusMin};
Real negativeTMin{std::numeric_limits<Real>::infinity()}, negativeTMax{-negativeTMin};
double maximumReconstructionError{0}, maximumReconstructionTolerance{0};
void Add(const Measure& other) {
volume += other.volume; mass += other.mass;
negativeVolume += other.negativeVolume; negativeMass += other.negativeMass;
lines += other.lines; negativeIntervals += other.negativeIntervals; points += other.points;
if (other.minimumRho < minimumRho) {
minimumRho = other.minimumRho; witnessH = other.witnessH;
witnessT = other.witnessT; witnessU = other.witnessU; witnessV = other.witnessV;
witnessPosition = other.witnessPosition; witnessElement = other.witnessElement;
}
negativeRadiusMin = std::min(negativeRadiusMin, other.negativeRadiusMin);
negativeRadiusMax = std::max(negativeRadiusMax, other.negativeRadiusMax);
negativeTMin = std::min(negativeTMin, other.negativeTMin);
negativeTMax = std::max(negativeTMax, other.negativeTMax);
maximumReconstructionError = std::max(maximumReconstructionError, other.maximumReconstructionError);
maximumReconstructionTolerance = std::max(maximumReconstructionTolerance, other.maximumReconstructionTolerance);
}
};
inline Real Observed(Real value) { return std::isfinite(value) ? value : std::numeric_limits<Real>::quiet_NaN(); }
inline void Header(std::ostream& out) {
out << "tangent_lines,negative_intervals,integration_points,volume,mass,negative_volume,negative_mass,"
"negative_volume_fraction,negative_mass_fraction,minimum_density,witness_h,witness_element,witness_t,witness_u,witness_v,"
"witness_x,witness_y,witness_z,negative_radius_minimum,negative_radius_maximum,negative_interval_t_minimum,"
"negative_interval_t_maximum,maximum_reconstruction_error,maximum_reconstruction_tolerance\n";
}
inline void Write(std::ostream& out, const Measure& m) {
out << m.lines << ',' << m.negativeIntervals << ',' << m.points << ',' << m.volume << ',' << m.mass << ','
<< m.negativeVolume << ',' << m.negativeMass << ',' << m.negativeVolume / m.volume << ','
<< (m.mass != 0 ? m.negativeMass / std::abs(m.mass) : std::numeric_limits<Real>::quiet_NaN()) << ','
<< m.minimumRho << ',' << m.witnessH << ',' << m.witnessElement << ',' << m.witnessT << ',' << m.witnessU << ',' << m.witnessV;
for (double x : m.witnessPosition) out << ',' << x;
out << ',' << Observed(m.negativeRadiusMin) << ',' << Observed(m.negativeRadiusMax) << ','
<< Observed(m.negativeTMin) << ',' << Observed(m.negativeTMax) << ','
<< m.maximumReconstructionError << ',' << m.maximumReconstructionTolerance << '\n';
}
inline bool Identical(const mfem::Vector& a, const mfem::Vector& b) {
return a.Size() == b.Size() && (a.Size() == 0 || std::memcmp(a.GetData(), b.GetData(), sizeof(mfem::real_t) * a.Size()) == 0);
}
} // namespace negative_density_regions_detail
inline void RecordDensityNegativeRegions(polytrope_validation::PhysicalState& state, double n, double K,
const std::filesystem::path& output) {
namespace d = negative_density_regions_detail;
using d::Real;
if (!std::isfinite(n) || n < 1 || !std::isfinite(K) || K <= 0)
throw std::invalid_argument("Density regions require finite n>=1 and K>0.");
std::filesystem::create_directories(output);
// Fail the one-dimensional arithmetic controls before any FEM evaluation.
d::SelfChecks(output / "density_negative_regions_selfchecks.csv");
const auto& fem = state.finiteElements;
if (!fem.mesh || !fem.densityFes || !fem.enthalpyFes || !fem.compactificationCoordinate ||
fem.mesh->Dimension() != 3 || !fem.mesh->Conforming() || fem.densityFes->GetVDim() != 1 ||
dynamic_cast<const mfem::L2_FECollection*>(fem.densityFes->FEColl()) == nullptr ||
state.density.ParFESpace() != fem.densityFes.get() || state.enthalpy.ParFESpace() != fem.enthalpyFes.get())
throw std::invalid_argument("Density regions require the current scalar L2 density space on a conforming 3D mesh.");
int ranks = 0;
MPI_Comm_size(fem.mesh->GetComm(), &ranks);
if (ranks != 1) throw std::invalid_argument("Density regions currently require one MPI rank.");
for (int element = 0; element < fem.mesh->GetNE(); ++element) if (state.isStellar(element)) {
const auto* fe = fem.densityFes->GetFE(element);
if (!fe || fe->GetOrder() != 2 || fe->GetMapType() != mfem::FiniteElement::VALUE ||
fe->GetGeomType() != mfem::Geometry::CUBE || fe->GetDof() != 27)
throw std::invalid_argument("Density root splitting requires scalar VALUE Q2 hexahedral density elements.");
}
const auto axes = d::ChooseAxes(state);
const mfem::Vector savedDensity(state.density), savedEnthalpy(state.enthalpy), savedPotential(state.potential),
savedGravity(state.gravityGradientReference), savedDisplacement(state.displacement);
mean_field::mapping::GridFunctionMappingEvaluator mapper(state.domainMapper, state.displacement, *fem.compactificationCoordinate);
mean_field::mapping::MappingPointContext mapped;
auto elements = d::Open(output / "density_negative_regions_elements.csv");
elements << "tangential_order,interval_order,element,attribute,axis,orientation,surface_face,surface_face_count,";
d::Header(elements);
auto summary = d::Open(output / "density_negative_regions_summary.csv");
summary << "tangential_order,interval_order,";
d::Header(summary);
auto intervals = d::Open(output / "density_negative_regions_intervals.csv");
intervals << "tangential_order,element,attribute,axis,orientation,surface_face,u,v,tangential_weight,t_left,t_right,"
"coefficient_c,coefficient_b,coefficient_a,negative_volume,negative_mass,minimum_density,witness_h,"
"radius_minimum,radius_maximum,left_x,left_y,left_z,right_x,right_y,right_z\n";
constexpr int intervalOrder = 14;
const auto& intervalRule = mfem::IntRules.Get(mfem::Geometry::SEGMENT, intervalOrder);
if (intervalRule.GetNPoints() != 8) throw std::logic_error("Unexpected density interval Gauss rule.");
for (int tangentialOrder : {14, 22, 30}) {
const auto& tangentRule = mfem::IntRules.Get(mfem::Geometry::SEGMENT, tangentialOrder);
if (tangentRule.GetNPoints() != tangentialOrder / 2 + 1)
throw std::logic_error("Unexpected density tangential Gauss rule.");
d::Measure global;
for (int element = 0; element < fem.mesh->GetNE(); ++element) {
if (!state.isStellar(element)) continue;
const auto& axis = axes[static_cast<std::size_t>(element)];
auto* transformation = fem.mesh->GetElementTransformation(element);
d::Measure local;
for (int iu = 0; iu < tangentRule.GetNPoints(); ++iu) for (int iv = 0; iv < tangentRule.GetNPoints(); ++iv) {
const auto& up = tangentRule.IntPoint(iu);
const auto& vp = tangentRule.IntPoint(iv);
const double u = up.x, v = vp.x;
const Real tangentWeight = static_cast<Real>(up.weight) * vp.weight;
const auto value = [&](Real t) {
const auto point = d::Point(axis, u, v, t);
const double rho = state.density.GetValue(element, point);
if (!std::isfinite(rho)) throw std::domain_error("Nonfinite density slice value.");
return rho;
};
const auto polynomial = d::Interpolate(value(0), value(Real{0.5}), value(1));
const Real tolerance = 512 * std::numeric_limits<double>::epsilon() * polynomial.Scale();
const auto verify = [&](Real t, double actual) {
const Real error = std::abs(polynomial.Value(t) - actual);
local.maximumReconstructionError = std::max(local.maximumReconstructionError, static_cast<double>(error));
local.maximumReconstructionTolerance = std::max(local.maximumReconstructionTolerance, static_cast<double>(tolerance));
if (!std::isfinite(error) || error > tolerance)
throw std::runtime_error("Frozen density slice fails independent Q2 reconstruction.");
};
for (Real t : {Real{0.125}, Real{0.25}, Real{0.375}, Real{0.625}, Real{0.75}, Real{0.875}})
verify(t, value(t));
const auto parts = d::Partition(polynomial);
++local.lines;
const auto evaluate = [&](Real t, d::Measure& measure, bool negativeRegion) {
const auto point = d::Point(axis, u, v, t);
if (mapper.EvaluatePoint(*transformation, point, mapped) != mean_field::mapping::MappingStatus::valid || mapped.compactified)
throw std::domain_error("Invalid stellar density-region mapping.");
const double rho = state.density.GetValue(element, point), h = state.enthalpy.GetValue(element, point);
if (!std::isfinite(rho) || !std::isfinite(h)) throw std::domain_error("Nonfinite density-region witness.");
verify(t, rho);
if (rho < measure.minimumRho) {
measure.minimumRho = rho; measure.witnessH = h; measure.witnessElement = element;
measure.witnessT = static_cast<double>(t); measure.witnessU = u; measure.witnessV = v;
for (int component = 0; component < 3; ++component) measure.witnessPosition[component] = mapped.physical_position(component);
}
if (negativeRegion) {
const double radius = mapped.physical_position.Norml2();
if (!std::isfinite(radius)) throw std::domain_error("Nonfinite density-region radius.");
measure.negativeRadiusMin = std::min(measure.negativeRadiusMin, radius);
measure.negativeRadiusMax = std::max(measure.negativeRadiusMax, radius);
}
transformation->SetIntPoint(&point);
const double referenceDeterminant = transformation->Jacobian().Det();
const Real determinant = static_cast<Real>(referenceDeterminant) * mapped.mapping_determinant;
if (!(referenceDeterminant > 0) || !std::isfinite(referenceDeterminant) ||
!(mapped.mapping_determinant > 0) || !std::isfinite(mapped.mapping_determinant) ||
!(determinant > 0) || !std::isfinite(determinant))
throw std::domain_error("Nonpositive or nonfinite density-region physical measure.");
return determinant;
};
for (const auto& part : parts) {
d::Measure piece;
std::array<double, 3> leftPosition{}, rightPosition{};
(void)evaluate(part.left, piece, part.negative);
for (int component = 0; component < 3; ++component) leftPosition[component] = mapped.physical_position(component);
(void)evaluate(part.right, piece, part.negative);
for (int component = 0; component < 3; ++component) rightPosition[component] = mapped.physical_position(component);
if (polynomial.a != 0) {
const Real stationary = -polynomial.b / (2 * polynomial.a);
if (stationary > part.left && stationary < part.right) (void)evaluate(stationary, piece, part.negative);
}
for (int it = 0; it < intervalRule.GetNPoints(); ++it) {
const auto& qp = intervalRule.IntPoint(it);
const Real t = part.left + (part.right - part.left) * qp.x;
const Real determinant = evaluate(t, piece, part.negative);
const Real weight = tangentWeight * (part.right - part.left) * qp.weight * determinant;
const Real rho = polynomial.Value(t);
if (!(weight > 0) || !std::isfinite(weight) || !std::isfinite(rho) ||
(part.negative && rho > 0) || (!part.negative && rho < 0))
throw std::runtime_error("Density region quadrature disagrees with its root partition.");
piece.volume += weight;
piece.mass += weight * rho;
++piece.points;
}
if (part.negative) {
piece.negativeIntervals = 1;
piece.negativeVolume = piece.volume;
piece.negativeMass = -piece.mass;
piece.negativeTMin = part.left;
piece.negativeTMax = part.right;
if (tangentialOrder == 30) {
intervals << tangentialOrder << ',' << element << ',' << fem.mesh->GetAttribute(element) << ','
<< axis.coordinate << ',' << axis.orientation << ',' << axis.face << ',' << u << ',' << v << ','
<< tangentWeight << ',' << part.left << ',' << part.right << ',' << polynomial.c << ',' << polynomial.b << ','
<< polynomial.a << ',' << piece.negativeVolume << ',' << piece.negativeMass << ',' << piece.minimumRho << ','
<< piece.witnessH << ',' << piece.negativeRadiusMin << ',' << piece.negativeRadiusMax;
for (double x : leftPosition) intervals << ',' << x;
for (double x : rightPosition) intervals << ',' << x;
intervals << '\n';
}
}
local.Add(piece);
}
}
if (!(local.volume > 0) || !std::isfinite(local.volume) || !std::isfinite(local.mass) ||
!std::isfinite(local.negativeVolume) || !std::isfinite(local.negativeMass) || local.negativeMass < 0)
throw std::runtime_error("Invalid integrated density-region measure.");
elements << tangentialOrder << ',' << intervalOrder << ',' << element << ',' << fem.mesh->GetAttribute(element) << ','
<< axis.coordinate << ',' << axis.orientation << ',' << axis.face << ',' << axis.faceCount << ',';
d::Write(elements, local);
global.Add(local);
}
if (!(global.volume > 0)) throw std::invalid_argument("Density region diagnostic found no stellar volume.");
summary << tangentialOrder << ',' << intervalOrder << ',';
d::Write(summary, global);
summary.flush(); elements.flush(); intervals.flush();
}
const bool unchanged = d::Identical(savedDensity, state.density) && d::Identical(savedEnthalpy, state.enthalpy) &&
d::Identical(savedPotential, state.potential) && d::Identical(savedGravity, state.gravityGradientReference) &&
d::Identical(savedDisplacement, state.displacement);
if (!unchanged) throw std::logic_error("Density region observation changed a source field.");
auto scope = d::Open(output / "density_negative_regions_scope.txt");
scope << "source_fields_bitwise_identical=1\ntrial_preparations=0\nmpi_ranks=1\n"
<< "n=" << n << "\nK=" << K << "\ndensity_basis=" << fem.densityFes->FEColl()->Name() << '\n'
<< "Mass uses the reconstructed Q2 polynomial, verified against direct FE values; no density or EOS clipping.\n"
<< "Volume weights contain one reference determinant and one deformation determinant.\n"
<< "All stellar cells are included; surface axes point inward from the lowest-index stellar/nonstellar face.\n"
<< "Other cells use reference axis0. Tangential orders14/22/30 use8/12/16 points per axis; interval order14 uses8.\n"
<< "Whole-cell denominators integrate every root-partition interval with the same sliced quadrature.\n"
<< "Negative intervals are exact for each reconstructed Q2 line up to floating arithmetic; tangential integration is sampled.\n"
<< "Witnesses and radial bounds are samples, not global extrema or polynomial sign certificates.\n"
<< "Near-double-root regions below reconstruction uncertainty are not certified; compare quadrature levels and errors.\n";
}
} // namespace experiment::plateau_diagnostics

View File

@@ -0,0 +1,41 @@
[
{
"id": "n1p5_late_eta0003",
"arguments": [
"--index", "1.5",
"--angular-momentum", "0",
"--no-central",
"--max-newton", "0",
"--nonlinear-step-probe",
"--probe-state", "/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/preconditioner_improvement_2026-09-18/newton_v1/n1p5_J0_curvature_gravity_schur/accepted_state.txt",
"--restart", "160",
"--max-linear", "600",
"--linear-tol", "0.003",
"--preconditioner-variant", "gravity-schur",
"--schur-sweeps", "1",
"--schur-relaxation", "0.5",
"--gravity-tol", "1e-10",
"--gravity-iterations", "300",
"--gravity-restart", "80"
]
},
{
"id": "n1p5_seed_eta003",
"arguments": [
"--index", "1.5",
"--angular-momentum", "0",
"--no-central",
"--max-newton", "0",
"--nonlinear-step-probe",
"--restart", "160",
"--max-linear", "600",
"--linear-tol", "0.03",
"--preconditioner-variant", "gravity-schur",
"--schur-sweeps", "1",
"--schur-relaxation", "0.5",
"--gravity-tol", "1e-10",
"--gravity-iterations", "300",
"--gravity-restart", "80"
]
}
]

View File

@@ -0,0 +1,22 @@
[
{
"id": "n1p5_late_eta003",
"arguments": [
"--index", "1.5",
"--angular-momentum", "0",
"--no-central",
"--max-newton", "0",
"--nonlinear-step-probe",
"--probe-state", "/Users/tboudreaux/.codex/.chatgpt-projects/g-p-6a6b3f2194ec8191bebcd59075897f1d/diagnostics/preconditioner_improvement_2026-09-18/newton_v1/n1p5_J0_curvature_gravity_schur/accepted_state.txt",
"--restart", "160",
"--max-linear", "600",
"--linear-tol", "0.03",
"--preconditioner-variant", "gravity-schur",
"--schur-sweeps", "1",
"--schur-relaxation", "0.5",
"--gravity-tol", "1e-10",
"--gravity-iterations", "300",
"--gravity-restart", "80"
]
}
]

View File

@@ -0,0 +1,142 @@
[
{
"id": "n1_J0_curvature",
"arguments": [
"--index",
"1",
"--angular-momentum",
"0",
"--strategy",
"curvature",
"--max-newton",
"10",
"--no-central",
"--restart",
"160",
"--max-linear",
"200",
"--capture-iterations",
"0,1,2,3,4,5,6,7,8,9"
]
},
{
"id": "n1_J0_reduced",
"arguments": [
"--index",
"1",
"--angular-momentum",
"0",
"--strategy",
"reduced",
"--max-newton",
"10",
"--no-central",
"--restart",
"160",
"--max-linear",
"200",
"--capture-iterations",
"0,1,2,3,4,5,6,7,8,9"
]
},
{
"id": "n1p5_J0_curvature",
"arguments": [
"--index",
"1.5",
"--angular-momentum",
"0",
"--strategy",
"curvature",
"--max-newton",
"12",
"--no-central",
"--restart",
"160",
"--max-linear",
"200",
"--capture-iterations",
"0,1,2,3,4,5,6,7,8,9,10,11"
]
},
{
"id": "n1p5_J0_reduced",
"arguments": [
"--index",
"1.5",
"--angular-momentum",
"0",
"--strategy",
"reduced",
"--max-newton",
"10",
"--no-central",
"--restart",
"160",
"--max-linear",
"200",
"--capture-iterations",
"0,1,2,3,4,5,6,7,8,9"
]
},
{
"id": "n1_J0p10_positivity",
"arguments": [
"--index",
"1",
"--angular-momentum",
"0.1",
"--strategy",
"positivity",
"--max-newton",
"8",
"--no-central",
"--restart",
"160",
"--max-linear",
"200",
"--capture-iterations",
"0,1,2,3,4,5,6,7"
]
},
{
"id": "n1_J0p10_positivity_curvature",
"arguments": [
"--index",
"1",
"--angular-momentum",
"0.1",
"--strategy",
"positivity-curvature",
"--max-newton",
"8",
"--no-central",
"--restart",
"160",
"--max-linear",
"200",
"--capture-iterations",
"0,1,2,3,4,5,6,7"
]
},
{
"id": "n1_J0p10_positivity_reduced",
"arguments": [
"--index",
"1",
"--angular-momentum",
"0.1",
"--strategy",
"positivity-reduced",
"--max-newton",
"4",
"--no-central",
"--restart",
"160",
"--max-linear",
"200",
"--capture-iterations",
"0,1,2,3"
]
}
]

View File

@@ -0,0 +1,475 @@
#!/usr/bin/env python3
"""Read completed/partial pressure diagnostics; never launch a solver or modify inputs."""
import argparse
import csv
import json
import math
from pathlib import Path
ROOT = Path(__file__).resolve().parent
ITERATIONS = (2, 3, 4, 7, 11)
def rows(path):
if not path.exists():
return []
with path.open() as stream:
return [r for r in csv.DictReader(stream) if None not in r and all(v is not None for v in r.values())]
def metrics(path):
return {r['metric']: float(r['value']) for r in rows(path)}
def metadata(path):
if not path.exists():
return {}
return dict(line.split('=', 1) for line in path.read_text().splitlines() if '=' in line)
def numeric(row):
result = {}
for key, value in row.items():
try:
result[key] = float(value)
except ValueError:
result[key] = value
return result
def negative_h_rejection(row):
# Enums at source9e1b65d: thermodynamic_domain=2, pressure_force=6,
# outside_domain=5. The prepared pressure operator emits this for h<0.
return all(float(row.get(k, -999)) == v for k, v in
[('admissible', 0), ('reason', 2), ('stage', 6), ('eos_code', 5)])
def sanitize(value):
if isinstance(value, float) and not math.isfinite(value):
return None
if isinstance(value, dict):
return {k: sanitize(v) for k, v in value.items()}
if isinstance(value, list):
return [sanitize(v) for v in value]
return value
def case(iteration):
folder = ROOT / 'focused' / f'n1_J0p10_iteration_{iteration}'
capture = metadata(ROOT / 'captures/n1_J0p10_capture' / f'capture_{iteration}/capture.txt')
bound = metrics(folder / 'frozen_enthalpy_bound.csv')
inputs = metrics(folder / 'frozen_input_checks.csv')
replay = rows(folder / 'replayed_candidate.csv')
trial_rows = rows(folder / 'pressure_obstruction_trials.csv')
limits = [numeric(r) for r in rows(folder / 'pressure_obstruction_limits.csv')]
summary = metrics(folder / 'pressure_obstruction_summary.csv')
live = next((r for r in rows(ROOT / 'captures/n1_J0p10_capture/newton.csv')
if int(r['iteration']) == iteration), None)
result = {'iteration': iteration, 'folder': str(folder), 'capture': capture,
'bounds': bound, 'input_checks': inputs, 'limits': limits,
'exact_candidate': numeric(replay[0]) if replay else None,
'exact_candidate_confirms_pressure_negative_h': negative_h_rejection(replay[0]) if replay else None,
'restoration_completed': 'final_restoration_residual_difference' in inputs,
'pressure_trials_completed': len(trial_rows),
'pressure_trials_expected': summary.get('candidate_trial_count'),
'trial_checks': [], 'live_newton_step': numeric(live) if live else None}
result['pressure_grid_complete'] = (summary.get('candidate_trial_count') is not None and
len(trial_rows) == summary['candidate_trial_count'])
if capture:
result['direction_roundoff_relative_estimate'] = (
float(capture['direction_roundoff_scale_estimate']) / float(capture['direction_norm']))
if bound:
result['closure_to_pressure_bound_ratio'] = bound['closure_alpha_h'] / bound['pressure_alpha_h']
result['exact_first_trial_over_pressure_bound'] = float(capture['first_trial_alpha']) / bound['pressure_alpha_h']
if live:
result['accepted_alpha_over_union_bound'] = float(live['alpha']) / bound['alpha_thermodynamic']
result['tightest_sampled_family'] = ('closure' if bound['closure_alpha_h'] < bound['pressure_alpha_h'] else
'pressure' if bound['pressure_alpha_h'] < bound['closure_alpha_h'] else 'tie')
midpoint = .5 * (bound['closure_alpha_h'] + bound['pressure_alpha_h'])
result['between_bounds_midpoint'] = {
'alpha': midpoint,
'closure_limiting_h_prediction': bound['limiting_h'] + midpoint * bound['limiting_dh'],
'pressure_limiting_h_prediction': bound['pressure_limiting_h'] + midpoint * bound['pressure_limiting_dh'],
}
for row in trial_rows:
r = numeric(row)
errors = [abs(r[f'{family}_limiting_h_evaluated'] - r[f'{family}_limiting_h_prediction'])
for family in ('pressure', 'closure')]
sign_checks = [((r[f'{family}_limiting_h_evaluated'] < 0) ==
(r[f'{family}_limiting_h_prediction'] < 0)) for family in ('pressure', 'closure')]
ratio = r['alpha_over_union_bound']
r['maximum_limiting_h_evaluation_prediction_absolute_difference'] = max(errors)
r['both_limiting_point_signs_match_prediction'] = all(sign_checks)
r['confirms_pressure_negative_h'] = negative_h_rejection(row)
# Descriptive expectation check for these fixed cases, not a general
# assertion that h>=0 guarantees preparation or merit acceptance.
expected = (r['direction'] == 'shape_only' or ratio < 1)
r['admissibility_matches_enthalpy_only_prediction'] = bool(r['admissible']) == expected
result['trial_checks'].append(r)
if trial_rows:
result['all_limiting_sign_predictions_match'] = all(r['both_limiting_point_signs_match_prediction']
for r in result['trial_checks'])
result['all_admissibility_matches_enthalpy_only_prediction'] = all(
r['admissibility_matches_enthalpy_only_prediction'] for r in result['trial_checks'])
result['mapping_rejections'] = sum(r['admissible'] == 0 and r['reason'] in (0, 1)
for r in result['trial_checks'])
result['maximum_limiting_h_absolute_disagreement'] = max(
r['maximum_limiting_h_evaluation_prediction_absolute_difference'] for r in result['trial_checks'])
shape_rows = [r for r in result['trial_checks'] if r['direction'] == 'shape_only']
h_crossing_rows = [r for r in result['trial_checks']
if r['direction'] == 'enthalpy_only' and r['alpha_over_union_bound'] > 1]
result['shape_only_all_prepared'] = all(r['admissible'] == 1 for r in shape_rows) if len(shape_rows) == 4 else None
result['enthalpy_only_crossing_failures_all_pressure_negative_h'] = (
all(r['confirms_pressure_negative_h'] for r in h_crossing_rows) if len(h_crossing_rows) == 2 else None)
return result
def fmt(value):
return 'pending' if value is None else f'{value:.9g}'
def vector_entries(path, indices):
"""Read only selected zero-based entries; reject an incompatible saved vector."""
if not path.exists():
return None
selected = set(indices)
found = {}
with path.open() as stream:
size = int(next(stream).strip())
if not selected or min(selected) < 0 or max(selected) >= size:
raise ValueError(f'Carrier indices incompatible with {path}')
count = 0
for index, line in enumerate(stream):
value = float(line)
count += 1
if index in selected:
found[index] = value
if count != size or len(found) != len(selected):
raise ValueError(f'Incomplete vector {path}')
return [found[index] for index in indices]
def extrema(values):
return {'count': len(values), 'minimum': min(values), 'maximum': max(values),
'maximum_absolute': max(abs(x) for x in values),
'l2_norm': math.sqrt(math.fsum(x*x for x in values)),
'negative_count': sum(x < 0 for x in values),
'nonzero_count': sum(x != 0 for x in values)}
def supplemental(cases):
"""Find the two supplemental case IDs without imposing an output-parent name."""
result = {'cases': [], 'offline_surface_checks': []}
case_ids = [('n1_J0p10_onset_between_bounds', 2), ('n1_J0p10_late_surface_trace', 11)]
reference_rows = None
for name, iteration in case_ids:
candidates = [path.parent for path in ROOT.glob(f'**/{name}/surface_trace_summary.csv')]
if len(candidates) > 1:
raise ValueError(f'Ambiguous duplicate supplemental case: {name}')
if not candidates:
result['cases'].append({'id': name, 'iteration': iteration, 'available': False})
continue
folder = candidates[0]
carrier_rows = [numeric(r) for r in rows(folder / 'surface_trace_rows.csv')]
summary = metrics(folder / 'surface_trace_summary.csv')
if 'pressure_alpha_h' not in summary:
result['cases'].append({'id': name, 'iteration': iteration, 'available': False})
continue
contribution_rows = [numeric(r) for r in rows(folder / 'surface_trace_limits.csv')]
node_rows = [numeric(r) for r in rows(folder / 'surface_trace_nodes.csv')]
replay_rows = rows(folder / 'replayed_candidate.csv')
source_case = next(c for c in cases if c['iteration'] == iteration)
details = {'id': name, 'iteration': iteration, 'available': True, 'folder': str(folder),
'summary': summary, 'contributions': contribution_rows,
'replayed_candidate': numeric(replay_rows[0]) if replay_rows else None,
'carrier_rows_complete': len(carrier_rows) == summary.get('surface_row_count'),
'nodal_checks': [],
'restoration': metrics(folder / 'frozen_input_checks.csv')}
provenance = folder.parent / 'provenance.json'
if provenance.exists():
p = json.loads(provenance.read_text())
details['provenance'] = {key: p.get(key) for key in ('commit', 'branch', 'mesh_sha256')}
if carrier_rows and details['carrier_rows_complete']:
indices = [int(r['root_index']) for r in carrier_rows]
if len(set(indices)) != len(indices):
raise ValueError(f'Duplicate surface indices in {folder}')
if reference_rows is not None and indices != reference_rows:
raise ValueError('Supplemental surface carrier maps differ')
reference_rows = indices
for family in ('closure', 'pressure'):
nodal = [r for r in node_rows if r['family'] == family]
if not nodal:
continue
if len(nodal) != nodal[0]['node_count']:
continue # A live CSV may not yet have all nodal rows.
union = nodal[0]['alpha_union']
factors = [('base', 0), ('near_below_union', .99*union),
('near_above_union', 1.01*union), ('unit_step', 1)]
if source_case['capture']:
factors.append(('captured_first_alpha', float(source_case['capture']['first_trial_alpha'])))
if source_case['live_newton_step']:
factors.append(('accepted_alpha', source_case['live_newton_step']['alpha']))
scale = max(abs(r[k]) for r in nodal for k in ('h', 'dh'))
tolerance = 64 * math.ulp(1.0) * scale
limit = next((r for r in contribution_rows if r['family'] == family), None)
if limit is None:
continue
for label, alpha in factors:
values = [r['h'] + alpha*r['dh'] for r in nodal]
stats = extrema(values)
stats.update({'family': family, 'element': nodal[0]['element'], 'fe_order': nodal[0]['fe_order'],
'label': label, 'alpha': alpha, 'roundoff_scale_estimate': tolerance,
'negative_beyond_roundoff_count': sum(v < -tolerance for v in values),
'limiting_point_h': limit['full_h'] + alpha*limit['full_dh']})
details['nodal_checks'].append(stats)
if name.endswith('between_bounds') and details['replayed_candidate']:
r = details['replayed_candidate']
details['replay_confirms_closure_outside_domain'] = all(r.get(k) == v for k, v in
[('admissible', 0), ('reason', 2), ('stage', 3), ('eos_code', 5)])
details['candidate_derivation'] = json.loads((ROOT / 'supplemental_inputs/between_bounds_derivation.json').read_text())
result['cases'].append(details)
if reference_rows is not None:
result['surface_root_indices'] = reference_rows
for c in cases:
folder = ROOT / 'captures/n1_J0p10_capture' / f"capture_{c['iteration']}"
base = vector_entries(folder / 'physical_base.txt', reference_rows)
candidate = vector_entries(folder / 'physical_candidate.txt', reference_rows)
if base is None or candidate is None:
continue
alpha = float(c['capture']['first_trial_alpha'])
dh = [(v-b)/alpha for b, v in zip(base, candidate)]
result['offline_surface_checks'].append({'iteration': c['iteration'], 'first_trial_alpha': alpha,
'base_h': extrema(base), 'exact_candidate_h': extrema(candidate),
'reconstructed_direction_dh': extrema(dh),
'base_and_exact_candidate_entire_surface_identically_zero': all(v == 0 for v in base + candidate)})
return result
def main():
global ROOT
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('campaign_root', nargs='?', type=Path, default=ROOT,
help='Campaign artifact directory (default: directory containing this script).')
ROOT = parser.parse_args().campaign_root.expanduser().resolve()
if not ROOT.is_dir():
parser.error(f'Campaign directory does not exist: {ROOT}')
cases = [case(i) for i in ITERATIONS]
transitions = []
for first, second in zip(cases, cases[1:]):
if second['iteration'] != first['iteration'] + 1 or not first['bounds'] or not second['bounds']:
continue
alpha = first['live_newton_step']['alpha']
for family, prefix in [('closure', ''), ('pressure', 'pressure_')]:
b, c = first['bounds'], second['bounds']
same = all(b[prefix + key] == c[prefix + key] for key in ['limiting_element', 'limiting_point'])
predicted = b[prefix + 'limiting_h'] + alpha * b[prefix + 'limiting_dh']
observed = c[prefix + 'limiting_h']
transitions.append({'from_iteration': first['iteration'], 'to_iteration': second['iteration'],
'family': family, 'same_limiting_point': same, 'accepted_alpha': alpha,
'predicted_next_h': predicted, 'observed_next_h': observed,
'absolute_disagreement': abs(predicted - observed) if same else None})
supplements = supplemental(cases)
provenance_file = ROOT / 'focused/provenance.json'
source_revision = json.loads(provenance_file.read_text()).get('commit', '9e1b65d') if provenance_file.exists() else '9e1b65d'
report = {'schema_version': 2, 'source_revision': source_revision,
'interpretation': 'Exact candidate replay is authoritative; direction probes include reconstruction roundoff.',
'cases': cases, 'consecutive_captured_step_checks': transitions, 'supplemental': supplements}
polynomial_path = ROOT / 'pressure_polynomial_checks.json'
polynomial = json.loads(polynomial_path.read_text()) if polynomial_path.exists() else None
if polynomial:
report['offline_polynomial_artifacts'] = ['pressure_polynomial_checks.json', 'pressure_polynomial_analysis.md']
(ROOT / 'pressure_checks.json').write_text(json.dumps(sanitize(report), indent=2, allow_nan=False) + '\n')
lines = ['# Pressure obstruction analysis', '',
'Read-only analysis of the frozen n=1, J=.1 direction captures. This script launches no solver and does not modify case data. '
f'The original focused source is {source_revision}; iteration numbers are zero-based. '
'Supplemental source revisions are recorded per case in pressure_checks.json. Partial cases are explicitly pending.', '',
'| Iteration | Exact first alpha | Pressure bound | Closure bound | Limiting pressure h | dh | Element / point | Exact replay |',
'|---:|---:|---:|---:|---:|---:|---|---|']
for c in cases:
b = c['bounds']
loc = f"{int(b['pressure_limiting_element'])} / {int(b['pressure_limiting_point'])}" if b else 'pending'
replay = ('pressure negative h' if c['exact_candidate_confirms_pressure_negative_h'] else
('other; inspect JSON' if c['exact_candidate'] else 'pending'))
alpha = float(c['capture']['first_trial_alpha']) if c['capture'] else None
lines.append(f"| {c['iteration']} | {fmt(alpha)} | {fmt(b.get('pressure_alpha_h'))} | "
f"{fmt(b.get('closure_alpha_h'))} | {fmt(b.get('pressure_limiting_h'))} | "
f"{fmt(b.get('pressure_limiting_dh'))} | {loc} | {replay} |")
if all(c['exact_candidate_confirms_pressure_negative_h'] for c in cases):
lines += ['', '**All five exact saved first candidates reproduce finite negative enthalpy in pressure preparation.** '
'These failures are thermodynamic-domain rejections, not geometry rejections. The saved candidates are '
'replayed directly, so this conclusion does not depend on reconstructing the Newton direction.']
populated = [c for c in cases if c['bounds']]
if populated:
lines += ['', 'The family attaining the smaller sampled bound is ' + ', '.join(
f"iteration {c['iteration']}: {c['tightest_sampled_family']}" for c in populated) + '.', '',
'| Iteration | Live accepted alpha | Accepted alpha / union bound |', '|---:|---:|---:|']
for c in populated:
lines.append(f"| {c['iteration']} | {fmt(c['live_newton_step']['alpha'])} | {fmt(c['accepted_alpha_over_union_bound'])} |")
if cases[-1]['bounds'] and cases[0]['bounds']:
first, last = cases[0]['bounds'], cases[-1]['bounds']
lines += ['', f"From iteration 2 to 11 the pressure bound shrinks by "
f"{first['pressure_alpha_h']/last['pressure_alpha_h']:.6g} times. The limiting pressure sample remains "
f"element {int(last['pressure_limiting_element'])}, point {int(last['pressure_limiting_point'])}; "
'its h approaches zero while dh remains negative. '
f"At iteration 11 the closure bound is {last['closure_alpha_h']/last['pressure_alpha_h']:.6g} times larger. "
'The mechanism of the step-length collapse is established along these directions; why the Newton '
'directions continue to decrease this h remains unresolved.']
if transitions:
maximum = max(r['absolute_disagreement'] for r in transitions if r['absolute_disagreement'] is not None)
lines += ['', f"For consecutive captured states at the same limiting point, h_next = h + alpha_accepted*dh "
f"agrees with the independently scanned next base to at most {maximum:.3g} absolute. "
'The pointwise approach to the enthalpy boundary is therefore directly tied to the accepted steps.']
lines += ['', '## Crossing controls', '',
'| Iteration | Candidate rows / expected | Shape-only all prepared | h-only crossing rejects negative h | Geometry rejections | Max h prediction/evaluation difference | Restored |',
'|---:|---:|---|---|---:|---:|---|']
for c in cases:
if c['iteration'] not in (2, 11):
continue
lines.append(f"| {c['iteration']} | {c['pressure_trials_completed']} / {fmt(c['pressure_trials_expected'])} | "
f"{c.get('shape_only_all_prepared') if c.get('shape_only_all_prepared') is not None else 'pending'} | "
f"{c.get('enthalpy_only_crossing_failures_all_pressure_negative_h') if c.get('enthalpy_only_crossing_failures_all_pressure_negative_h') is not None else 'pending'} | "
f"{c.get('mapping_rejections', 'pending')} | {fmt(c.get('maximum_limiting_h_absolute_disagreement'))} | "
f"{c['restoration_completed']} |")
onset = cases[0]
if onset['bounds']:
b = onset['bounds']
midpoint = onset['between_bounds_midpoint']
midpoint_case = next(c for c in supplements['cases'] if c['iteration'] == 2)
measured_midpoint = midpoint_case.get('replay_confirms_closure_outside_domain')
midpoint_outcome = ('The supplemental candidate reproduces thermodynamic-domain rejection at the closure stage '
'(reason=2, stage=3, EOS code=5), confirming pressure preparation passes at this alpha before closure fails.'
if measured_midpoint is True else
'The supplemental replay has a different outcome; inspect pressure_checks.json.'
if measured_midpoint is False else
'Its production outcome is pending; the supplemental replay can separate closure from pressure.')
lines += ['', '## Onset interpretation', '',
f"The onset has a tighter **{onset['tightest_sampled_family']}** bound: closure {b['closure_alpha_h']:.12g}, "
f"pressure {b['pressure_alpha_h']:.12g}. The original alpha=1 trial crosses both. "
'Pressure is prepared before closure, so the recorded pressure-stage rejection identifies the first failing stage at that alpha; '
'it does not establish the pressure quadrature as the tightest restriction.', '',
f"A midpoint alpha={midpoint['alpha']:.12g} predicts closure h="
f"{midpoint['closure_limiting_h_prediction']:.9g} and pressure h="
f"{midpoint['pressure_limiting_h_prediction']:.9g} at the respective limiting points. "
'This midpoint is outside the original probe grid. ' + midpoint_outcome, '']
populated_limits = [c for c in cases if c['limits']]
if populated_limits:
lines += ['', '## Limiting-point locations', '',
'| Iteration | Family | Surface-adjacent element | Reference radius | Physical base (x, y, z) |',
'|---:|---|---|---:|---|']
for c in populated_limits:
for r in c['limits']:
xyz = ', '.join(fmt(r[f'physical_{d}']) for d in 'xyz')
lines.append(f"| {c['iteration']} | {r['family']} | {int(r['element'])}; "
f"{bool(r['element_touches_stellar_surface'])} | {fmt(r['reference_radius'])} | ({xyz}) |")
lines += ['', '## Surface trace is an enforced equation', '',
'The runtime isobaric condition is not absent merely because the field registry has no essential constraint. '
'The root constructs an enthalpy boundary map on StellarSurface (prepared_stellar_equilibrium.cpp:407), '
'replaces surface hydrostatic residual rows (lines 809–810), and replaces their Jacobian rows (904–908). '
'The compiled constraint is h−h(P_surface), with identity h Jacobian for fixed pressure '
'(surface/compiled.cppm:47–59). At P_surface=0 the polytropic EOS gives h=0. '
'The radial seed explicitly sets these boundary coefficients to zero '
'(seed/stellar_equilibrium_projection.cppm:203–208).', '',
'This is algebraic enforcement, not a per-trial coefficient projection. Source inspection alone does not '
'establish exact zero in every captured iterate under an inexact linear solve. Even a zero polynomial '
'boundary trace does not guarantee nonnegative enthalpy within the adjacent high-order element. '
'The observed near-surface wall therefore does not establish a missing boundary condition or interpolation '
'as the cause of the Newton direction.']
trace_cases = [c for c in supplements['cases'] if c['available']]
if trace_cases:
lines += ['', '## Supplemental surface carrier and nodal checks', '',
'The actual surface carrier indices come from GetPressureSurfaceRows(), then select entries in each '
'saved physical state. Boundary-only fields retain those coefficients and zero every other enthalpy '
'coefficient; evaluating this field at a limiting interior point gives the boundary contribution to '
'that polynomial value, not a separate trace sample on the stellar surface.', '',
'| Iteration | Carrier rows | Base max abs h | Direction max abs dh | Unit-step max abs h |',
'|---:|---:|---:|---:|---:|']
for c in trace_cases:
m = c['summary']
lines.append(f"| {c['iteration']} | {fmt(m.get('surface_row_count'))} | {fmt(m.get('base_h_maximum_absolute'))} | "
f"{fmt(m.get('direction_dh_maximum_absolute'))} | {fmt(m.get('h_plus_dh_maximum_absolute'))} |")
offline = supplements['offline_surface_checks']
if len(offline) == len(ITERATIONS) and all(c['base_and_exact_candidate_entire_surface_identically_zero'] for c in offline):
lines += ['', '**All actual surface enthalpy coefficients are exactly zero in all five saved bases and all '
'five exact first candidates.** Their reconstructed boundary directions are therefore also zero. '
'Boundary-row leakage is ruled out for these captured directions, independently of the inexact '
'linear-solve possibility from source inspection.']
else:
lines += ['', 'Offline surface checks (including nonzero and negative counts) are recorded per capture in '
'pressure_checks.json; inspect them before inferring exact trace enforcement in captured states.']
lines += ['', '| Iteration | Family | Full h | Boundary contribution h | Full dh | Boundary contribution dh |',
'|---:|---|---:|---:|---:|---:|']
for c in trace_cases:
for r in c['contributions']:
lines.append(f"| {c['iteration']} | {r['family']} | {fmt(r['full_h'])} | {fmt(r['boundary_h'])} | "
f"{fmt(r['full_dh'])} | {fmt(r['boundary_dh'])} |")
lines += ['', 'Full physical fields are scattered through the production field adapter, then evaluated at FE '
'GetNodes() coordinates. These values do not assume that raw signed local DOF indices are nodal values. '
'The same element is intentionally exported separately for each limiting rule family.', '',
'| Iteration | Family | Step | Nodal minimum h | Negative nodes | Limiting interior-point h |',
'|---:|---|---|---:|---:|---:|']
for c in trace_cases:
for r in c['nodal_checks']:
if r['label'] in ('base', 'near_above_union', 'unit_step'):
lines.append(f"| {c['iteration']} | {r['family']} | {r['label']} | {fmt(r['minimum'])} | "
f"{r['negative_count']} | {fmt(r['limiting_point_h'])} |")
undershoots = [(c['iteration'], r['family']) for c in trace_cases for r in c['nodal_checks']
if r['label'] == 'near_above_union' and r['minimum'] >= 0 and r['limiting_point_h'] < 0]
if undershoots:
lines += ['', 'At 1.01 times the union bound, nonnegative values at every FE node coexist with negative '
'enthalpy at the limiting interior point in ' + ', '.join(f'iteration {i} {family}' for i, family in undershoots) +
'. This demonstrates an interior polynomial undershoot in these trial directions. It does not '
'establish an interpolation implementation error or explain why Newton selects this direction.']
lines += ['', 'Nodal nonnegativity is not a certificate of positivity between nodes. The JSON includes strict '
'negative counts and a separate 64-epsilon times nodal-value-scale estimate, which is descriptive '
'rather than a certified rounding bound. Equality exactly at the union bound is deliberately not '
'used to decide a crossing. The production quadrature union bound also does not certify positivity '
'at unsampled points; these results do not establish the minimum enthalpy over an entire element.']
if polynomial:
lines += ['', '## Offline interior polynomial check', '',
'A separate independently validated tensor-Q3 reconstruction samples 495,264 strictly interior '
'reference points in each exported limiting element, including logarithmic distances to its zero '
'face. It reconstructs all 64 nodes exactly and both production limit points to roundoff.']
for c in polynomial['cases']:
minimum = c['sampled_extrema']['base']['minimum']
if minimum < -c['roundoff_scale_estimate']:
point = ', '.join(fmt(x) for x in c['sampled_extrema']['base']['minimum_reference_point'])
lines += ['', f"**The saved iteration {c['iteration']} base already has negative enthalpy between "
f"production quadrature points:** sampled h={minimum:.9g} at reference ({point}). "
'This base-state finding is independent of Newton-direction reconstruction. The surface '
'coefficients and all 64 FE node values remain nonnegative; production quadrature positivity '
'therefore misses a real polynomial undershoot in this accepted state.']
else:
lines += ['', f"Iteration {c['iteration']} has no negative base samples on this grid; its sampled "
f"directional bound {c['directional_bound']['sampled_admissible_step_bound']:.12g} is tighter "
f"than the production bound {c['union_production_bound']:.12g}. Absence of negative samples "
'does not certify positivity everywhere.']
lines += ['', 'See pressure_polynomial_analysis.md and pressure_polynomial_checks.json for interpolation '
'validation, minima, locations and limitations. No solver or preparation rule was changed.']
lines += ['', '## Scope and interpretation', '',
'A replay with reason=2, stage=6, EOS code=5 is the production pressure operator’s finite h<0 branch. '
'It resolves the old CSV ambiguity with inverted geometry. Missing determinant/F data on rejection are not measured nonfinite residuals.', '',
'The bound scans the exact production pressure/closure quadrature points using pointwise polynomial contractions. '
'The independently re-evaluated h values in the crossing table concern the two frozen limiting points, not a full search for each trial’s most negative point. '
'Optimized tensor contractions can differ at roundoff; .99/1.01 factors deliberately avoid equality at the crossing.', '',
'Element-to-surface adjacency, when available in pressure_obstruction_limits.csv, is an exact topology flag. '
'It is not distance to the surface. Physical/reference Cartesian coordinates and element-local integration coordinates are distinct.', '',
'At iteration 11 the supplied direction is reconstructed from a first-trial difference at alpha=1.9073486328125e-6; '
'its relative subtraction-roundoff scale estimate is approximately 4.88e-7, not a certified error bound. '
'The exact saved candidate is replayed without that reconstruction and is authoritative for the observed rejection.', '',
'Preparation success in a frozen probe does not establish line-search merit acceptance, physical equilibrium, or eventual Newton convergence. '
'No requested stopping test, enthalpy admissibility rule, or solver was changed. '
'The evolving bound is directional: a falling h/dh bound does not by itself identify why the nonlinear correction keeps pointing outward from the admissible set.', '',
'Machine-readable evidence and all individual trial checks: pressure_checks.json. '
'Reproduce this analysis with `python3 analyze_pressure.py /path/to/campaign_artifacts`; '
'the optional campaign path defaults to the script directory.']
(ROOT / 'pressure_analysis.md').write_text('\n'.join(lines) + '\n')
print(json.dumps({'cases_with_exact_replay': sum(c['exact_candidate'] is not None for c in cases),
'cases_fully_restored': sum(c['restoration_completed'] for c in cases),
'supplemental_available': sum(c['available'] for c in supplements['cases']),
'supplemental_fully_restored': sum('final_restoration_residual_difference' in c.get('restoration', {})
for c in supplements['cases']),
'candidate_rows': {c['iteration']: c['pressure_trials_completed'] for c in cases}}, sort_keys=True))
if __name__ == '__main__':
main()

View File

@@ -0,0 +1,234 @@
#!/usr/bin/env python3
"""Read-only shape CSV audit. No solver/library dependency; outputs live elsewhere than raw case files."""
from __future__ import annotations
import argparse, csv, hashlib, json, math
from pathlib import Path
from collections import defaultdict
CASES = ('n1_J0p10_iteration_2', 'n1p5_J0_iteration_1', 'n3_J0_seed_R160_curvature')
def rows(path):
with path.open(newline='') as stream:
reader = csv.DictReader(stream)
result = list(reader)
for r in result:
if None in r or any(v is None for v in r.values()):
raise ValueError(f'Malformed/incomplete CSV row in {path}: {r}')
return result
def num(r, key): return float(r[key])
def flag(r, key): return r[key] == '1'
def norm(values): return math.sqrt(math.fsum(v*v for v in values))
def ratio(a,b): return a/b if math.isfinite(a) and math.isfinite(b) and b > 0 else math.nan
def clean(obj):
if isinstance(obj, float) and not math.isfinite(obj): return None
if isinstance(obj, dict): return {str(k):clean(v) for k,v in obj.items()}
if isinstance(obj, (tuple,list)): return [clean(v) for v in obj]
return obj
def signed_aggregate(rs):
out = {}
for kind in ('full','shape','fields','mixed'):
out[kind+'_remainder_norm'] = norm(num(r,kind+'_remainder_norm') for r in rs)
out['linear_dot_'+kind] = math.fsum(num(r,'linear_dot_'+kind) for r in rs)
for name in ('linear_prediction_norm','full_trial_norm','heuristic_roundoff_scale'):
out[name] = norm(num(r,name) for r in rs)
for name in ('merit_identity_error','projection_decomposition_error'):
out[name] = math.fsum(num(r,name) for r in rs)
for a,b in (('full','shape'),('full','fields'),('full','mixed'),('shape','fields'),('shape','mixed'),('fields','mixed')):
dot = 0.
for r in rs:
na,nb = num(r,a+'_remainder_norm'),num(r,b+'_remainder_norm')
if na == 0 or nb == 0: continue
dot += na*nb*num(r,a+'_'+b+'_cosine')
out[a+'_'+b+'_cosine'] = ratio(dot, out[a+'_remainder_norm']*out[b+'_remainder_norm'])
out['linear_curvature_cross_term'] = 2*out['linear_dot_full']
out['curvature_squared_term'] = out['full_remainder_norm']**2
out['merit_curvature_total'] = out['linear_curvature_cross_term']+out['curvature_squared_term']
return out
def analyze_case(case):
summary_path = case/'shape_curvature_summary.csv'
if not summary_path.exists(): return {'status':'pending'}
summary = {r['metric']:num(r,'value') for r in rows(summary_path)}
required = ('preparations','accepted_normalized_state_change','accepted_residual_change','accepted_physical_state_change')
if not all(k in summary for k in required): return {'status':'incomplete', 'summary':summary}
names = ('preparations','restorations','directions','actions','bounds','remainders','mixed')
data = {name:rows(case/f'shape_curvature_{name}.csv') for name in names}
result = {'status':'complete','summary':summary,'sha256':{p.name:hashlib.sha256(p.read_bytes()).hexdigest() for p in case.glob('shape_curvature_*.csv')}}
input_checks=case/'frozen_input_checks.csv'
if input_checks.exists(): result['input_checks']={r['metric']:num(r,'value') for r in rows(input_checks)}
replay=case/'replayed_candidate.csv'
if replay.exists(): result['replayed_candidate']=rows(replay)
checks = result['checks'] = {}
checks['accepted_vectors_unchanged'] = all(summary[k] == 0 for k in required[1:])
checks['direction_split_exact'] = summary['direction_split_error_norm'] == 0
checks['action_split_within_recorded_heuristic'] = summary['action_linearity_within_heuristic'] == 1
checks['preparation_count_matches_events'] = summary['preparations'] == len(data['preparations'])
checks['all_preparations_admissible'] = all(flag(r,'admissible') for r in data['preparations'])
result['rejections'] = [r for r in data['preparations'] if not flag(r,'admissible')]
checks['all_state_increments_resolved'] = all(flag(r,'state_increment_resolved') for r in data['remainders'])
checks['all_alpha_squared_valid'] = all(flag(r,'alpha_squared_valid') for r in data['remainders'])
result['max_restoration_difference'] = max((num(r,'restoration_difference_norm') for r in data['restorations']),default=0)
result['actions'] = data['actions']
result['directions'] = data['directions']
drift = defaultdict(float)
for r in data['restorations']: drift[r['block']] = max(drift[r['block']],num(r,'restoration_difference_norm'))
for r in data['remainders']:
r['effective_floor'] = max(num(r,'heuristic_roundoff_scale'),8*drift[r['block']])
r['effective_floor_ratio'] = ratio(num(r,'remainder_norm'),r['effective_floor'])
r['robustly_above_floor'] = flag(r,'admissible') and flag(r,'state_increment_resolved') and flag(r,'alpha_squared_valid') and r['effective_floor_ratio'] >= 10
gravity = lambda r: r['block'] in ('gravity_gradient_relation', 'poisson_balance')
affine = [r for r in data['remainders'] if r['direction']=='fields' and gravity(r)]
result['fixed_shape_gravity'] = {
'blocks':sorted({r['block'] for r in affine}),
'max_remainder':max((num(r,'remainder_norm') for r in affine),default=math.nan),
'max_effective_floor_ratio':max((r['effective_floor_ratio'] for r in affine),default=math.nan),
'all_below_recorded_or_restoration_floor': bool(affine) and all(r['effective_floor_ratio'] <= 1 for r in affine),
'rows':affine,
}
by_direction_block = defaultdict(list)
for r in data['remainders']: by_direction_block[r['direction'],r['block']].append(r)
slopes = []
for (direction,block),rs in by_direction_block.items():
rs.sort(key=lambda r:num(r,'alpha'),reverse=True)
for high,low in zip(rs,rs[1:]):
if not high['robustly_above_floor'] or not low['robustly_above_floor']: continue
slope = math.log(num(high,'remainder_norm')/num(low,'remainder_norm'))/math.log(num(high,'alpha')/num(low,'alpha'))
slopes.append({'direction':direction,'block':block,'alpha_high':num(high,'alpha'),'alpha_low':num(low,'alpha'),'slope':slope,'high_floor_ratio':high['effective_floor_ratio'],'low_floor_ratio':low['effective_floor_ratio']})
result['resolved_slopes'] = slopes
by_alpha = defaultdict(list)
mixed_by_block = defaultdict(list)
block_identity_ratios, block_projection_ratios = [], []
for r in data['mixed']:
by_alpha[num(r,'alpha')].append(r)
mixed_by_block[r['block']].append(r)
if not flag(r,'all_trials_admissible'): continue
den = num(r,'full_trial_norm')**2 + num(r,'linear_prediction_norm')**2 + 2*abs(num(r,'linear_dot_full')) + num(r,'full_remainder_norm')**2
block_identity_ratios.append(ratio(abs(num(r,'merit_identity_error')),den))
pden = math.fsum(abs(num(r,'linear_dot_'+k)) for k in ('full','shape','fields','mixed'))
if pden > 0: block_projection_ratios.append(ratio(abs(num(r,'projection_decomposition_error')),pden))
for block,rs in mixed_by_block.items():
rs.sort(key=lambda r:num(r,'alpha'),reverse=True)
for high,low in zip(rs,rs[1:]):
floor_high=max(num(high,'heuristic_roundoff_scale'),24*drift[block])
floor_low=max(num(low,'heuristic_roundoff_scale'),24*drift[block])
def robust(r,floor):
return all(flag(r,key) for key in ('all_trials_admissible','all_state_increments_resolved','alpha_squared_valid')) and num(r,'mixed_remainder_norm') >= 10*floor
if not robust(high,floor_high) or not robust(low,floor_low): continue
slopes.append({'direction':'mixed','block':block,'alpha_high':num(high,'alpha'),'alpha_low':num(low,'alpha'),'slope':math.log(num(high,'mixed_remainder_norm')/num(low,'mixed_remainder_norm'))/math.log(num(high,'alpha')/num(low,'alpha')),'high_floor_ratio':ratio(num(high,'mixed_remainder_norm'),floor_high),'low_floor_ratio':ratio(num(low,'mixed_remainder_norm'),floor_low)})
aggregates = []
identity_ratios,projection_ratios = [],[]
for alpha,rs in sorted(by_alpha.items(),reverse=True):
item = {'alpha':alpha,'all_admissible':all(flag(r,'all_trials_admissible') for r in rs),'all_resolved':all(flag(r,'all_state_increments_resolved') for r in rs)}
if item['all_admissible']:
item.update(signed_aggregate(rs))
item['base_residual_norm'] = summary['base_residual_norm']
item['trial_over_base'] = ratio(item['full_trial_norm'],summary['base_residual_norm'])
item['linear_over_base'] = ratio(item['linear_prediction_norm'],summary['base_residual_norm'])
item['full_remainder_over_alpha_squared'] = ratio(item['full_remainder_norm'],alpha**2)
full_rows = [r for r in data['remainders'] if r['direction']=='full' and num(r,'alpha') == alpha]
item['full_effective_floor_norm'] = norm(r['effective_floor'] for r in full_rows)
item['full_effective_floor_ratio'] = ratio(item['full_remainder_norm'],item['full_effective_floor_norm'])
item['gravity'] = signed_aggregate([r for r in rs if gravity(r)])
item['gravity_full_remainder_squared_fraction'] = ratio(item['gravity']['full_remainder_norm']**2,item['full_remainder_norm']**2)
item['blocks'] = rs
den = item['full_trial_norm']**2+item['linear_prediction_norm']**2+2*abs(item['linear_dot_full'])+item['full_remainder_norm']**2
item['merit_identity_relative_error'] = ratio(abs(item['merit_identity_error']),den)
pden = math.fsum(abs(item['linear_dot_'+k]) for k in ('full','shape','fields','mixed'))
item['projection_decomposition_relative_error'] = ratio(abs(item['projection_decomposition_error']),pden)
identity_ratios.append(item['merit_identity_relative_error'])
projection_ratios.append(item['projection_decomposition_relative_error'])
aggregates.append(item)
result['alphas'] = aggregates
result['max_merit_identity_relative_error'] = max(identity_ratios,default=math.nan)
result['max_projection_decomposition_relative_error'] = max(projection_ratios,default=math.nan)
result['max_block_merit_identity_relative_error'] = max(block_identity_ratios,default=math.nan)
result['max_block_projection_decomposition_relative_error'] = max(block_projection_ratios,default=math.nan)
result['remainder_rows'] = data['remainders']
return result
def make_markdown(results,provenance):
lines = ['# Shape-curvature analysis','',f"Focused executable source `{provenance.get('commit','unknown')}`; binary SHA-256 `{provenance.get('binary_sha256','unknown')}`.",'',
'This analysis reads the saved full, shape-only, and fields-only residual probes. Norms and projections use the existing normalization. The mixed remainder is a vector subtraction before its norm. No solver was run by this analysis.','',
'Source expectation: gravity has the form Fg=M(q)g+BᵀPhi and Fp=B g−S(q)rho. With q fixed, it is affine in all remaining fields; shape dependence and products of shape changes with field changes can supply second-order remainders. See [residual assembly](/Users/tboudreaux/Programming/4DSTAR/MeanField/libmeanfield/impl/operators/gravity_field.cpp:415) and [Jacobian shape/source actions](/Users/tboudreaux/Programming/4DSTAR/MeanField/libmeanfield/impl/operators/gravity_field_jacobian.cpp:242).','',
'Arithmetic checks use the reported preparation history and the final restoration drift. Slopes are reported only when both adjacent residual remainders exceed the larger of the recorded floor and eight times final restoration drift by at least 10×, and both increments are resolved. These floors are heuristic, not certified assembly-error bounds.','']
lines += ['## Common-cap comparison','',
'The signed columns below divide squared-merit contributions by each case’s own ‖F0‖². Their sum equals (‖Ftrial‖²−‖L‖²)/‖F0‖². They are evaluated at each direction’s common admissible cap; these are generally different alpha values.','',
'| case | alpha | ‖Ftrial‖/‖F0‖ | 2<L,Rs>/F0² | 2<L,Rf>/F0² | 2<L,Rm>/F0² | ‖Rfull‖²/F0² | total curvature/F0² |',
'|---|---:|---:|---:|---:|---:|---:|---:|']
for name,result in results.items():
if result['status'] != 'complete':
lines += [f"| {name} | {result['status']} | | | | | | |"]
continue
if not result['alphas'] or not result['alphas'][0]['all_admissible']:
lines += [f"| {name} | no complete common-cap triple | | | | | | |"]
continue
a=result['alphas'][0]; den=result['summary']['base_residual_norm']**2
lines += [f"| {name} | {a['alpha']:.7g} | {a['trial_over_base']:.8g} | {2*a['linear_dot_shape']/den:.7g} | {2*a['linear_dot_fields']/den:.7g} | {2*a['linear_dot_mixed']/den:.7g} | {a['curvature_squared_term']/den:.7g} | {a['merit_curvature_total']/den:.7g} |"]
lines += ['']
if all(r['status']=='complete' for r in results.values()):
lines += ['Across these three saved directions, every one of the shape helper’s 66 preparations is admissible and every accepted-vector change and restoration drift is exactly zero. The coupled gravity Taylor remainders have resolved slopes near two, while fields-only gravity remainders stay at approximately 2.5e-14–4.0e-14. This supports geometry–field curvature along the tested directions; no first-derivative inconsistency is visible in the resolved regime. The numerical floor is heuristic: the n1.5 and n3 fields-only maxima exceed it by factors 1.04 and 1.39, which is recorded explicitly.','',
'The practical mechanisms differ. The rotating n1 direction is blocked at its original full step by pressure admissibility; its sampled safe interval decreases the residual. The n1.5 full step is admissible and is strongly rejected by curvature in the residual metric. The n3 saved direction encounters both an enthalpy restriction and a curvature penalty at the largest tested safe step, but smaller sampled steps improve the residual. Its originating linear solve also missed the 3% gate.','']
lines += ['## First-order gravity cancellation','',
'These are cancellations between the two parts of each selected correction. They are not condition-number or symmetry measurements.','',
'| case | block | norm(Jshape) | norm(Jfields) | norm(Jfull) | shape/fields cosine |',
'|---|---|---:|---:|---:|---:|']
for name,result in results.items():
if result['status'] != 'complete': continue
for r in result['actions']:
if r['block'] not in ('gravity_gradient_relation','poisson_balance'): continue
lines += [f"| {name} | {r['block']} | {num(r,'shape_action_norm'):.8g} | {num(r,'fields_action_norm'):.8g} | {num(r,'full_action_norm'):.8g} | {num(r,'shape_fields_cosine'):.12g} |"]
lines += ['']
for name,result in results.items():
lines += ['## '+name,'']
if result['status'] != 'complete':
lines += ['Status: '+result['status']+'.','']; continue
s=result['summary']; checks=result['checks']; aff=result['fixed_shape_gravity']
if name=='n1_J0p10_iteration_2':
lines += ['**Interpretation:** the sampled admissible interval improves the residual, although mixed curvature makes it worse than the linear prediction. The original full-step pressure rejection is a separate admissibility event. The largest-step mixed signed projection is adverse, while the shape-only signed projection is favorable. The last alpha is limited by residual arithmetic and does not diagnose loss of second-order consistency.','']
elif name=='n1p5_J0_iteration_1':
lines += ['**Interpretation:** this is an admissible, curvature-driven merit rejection. At alpha=1 the linear prediction almost removes the residual, while the actual residual grows by over 12×. Alpha=.1 remains merit-worse; alpha=.01 improves it. Gravity shape and mixed remainders dominate despite partial cancellation. Their squared remainder term dominates the full-step merit cost; at alpha=.1 both shape and mixed signed projections are adverse. The fields-only gravity maximum exceeds the chosen heuristic floor by only 4.2%, remaining at approximately 3e-14 absolute; that minor heuristic exceedance is not evidence of nonlinear fixed-shape gravity.','']
elif name=='n3_J0_seed_R160_curvature':
lines += ['**Interpretation:** the largest common safe step is admissible but merit-worse; the next decade improves the residual. The mixed remainder is the largest component and is strongly aligned with the full remainder. Its signed projection onto the linear prediction is nevertheless favorable at the largest alpha, as is the fields-only projection: the adverse total curvature cost comes from the squared remainder norm overwhelming those favorable cross terms. At smaller resolved alphas the net curvature slightly improves the linear prediction. The saved R160 direction retains true linear defect 0.0402590213 and had failed the 0.03 gate; this probe is not a live Newton convergence result. Fields-only gravity stays below 4e-14 absolute, up to 1.393× the heuristic floor.','']
lines += [f"Frozen ‖F‖={s['base_residual_norm']:.9g}; ‖p‖={s['full_direction_norm']:.9g}; common alpha cap={s['common_alpha_cap']:.9g}. {int(s['preparations'])} preparations. Accepted-vector changes are all zero: **{checks['accepted_vectors_unchanged']}**. Direction split exact: **{checks['direction_split_exact']}**. Jacobian split error {s['action_split_error_norm']:.3e}, recorded scale {s['action_linearity_heuristic_scale']:.3e}; maximum per-block restoration drift {result['max_restoration_difference']:.3e}.",'',
f"All preparations admissible: **{checks['all_preparations_admissible']}**; all increments resolved: **{checks['all_state_increments_resolved']}**. Fields-only gravity maximum remainder {aff['max_remainder']:.3e}, maximum ratio to the effective heuristic floor {aff['max_effective_floor_ratio']:.3e}. Every sampled fields-only gravity remainder lies below that floor: **{aff['all_below_recorded_or_restoration_floor']}**.",'',
f"Maximum aggregate merit-identity relative error {result['max_merit_identity_relative_error']:.3e}; projection-decomposition relative error {result['max_projection_decomposition_relative_error']:.3e}.",'',
'| alpha | ‖Ftrial‖/‖F0‖ | ‖L‖/‖F0‖ | ‖Rfull‖/alpha² | full R / floor | ‖Rs‖ | ‖Rf‖ | ‖Rm‖ | gravity share of ‖Rfull‖² |','|---:|---:|---:|---:|---:|---:|---:|---:|---:|']
for a in result['alphas']:
if not a['all_admissible']: lines += [f"| {a['alpha']:.6g} | inadmissible | | | | | | | |"]
else: lines += [f"| {a['alpha']:.6g} | {a['trial_over_base']:.8g} | {a['linear_over_base']:.8g} | {a['full_remainder_over_alpha_squared']:.8g} | {a['full_effective_floor_ratio']:.3g} | {a['shape_remainder_norm']:.4e} | {a['fields_remainder_norm']:.4e} | {a['mixed_remainder_norm']:.4e} | {a['gravity_full_remainder_squared_fraction']:.6%} |"]
lines += ['', '| alpha | 2<L,Rs> | 2<L,Rf> | 2<L,Rm> | ‖Rfull‖² | curvature contribution to squared merit |','|---:|---:|---:|---:|---:|---:|']
for a in result['alphas']:
if a['all_admissible']: lines += [f"| {a['alpha']:.6g} | {2*a['linear_dot_shape']:.7e} | {2*a['linear_dot_fields']:.7e} | {2*a['linear_dot_mixed']:.7e} | {a['curvature_squared_term']:.7e} | {a['merit_curvature_total']:.7e} |"]
lines += ['', 'Positive signed terms increase the squared residual relative to the linear prediction; negative terms decrease it. The quadratic remainder-norm term contains component cross terms, so the signed projections alone are not a unique additive attribution of the entire curvature cost.','',
'| direction | residual block | resolved intervals | slope range | smallest resolved alpha |','|---|---|---:|---:|---:|']
grouped_slopes=defaultdict(list)
for p in result['resolved_slopes']: grouped_slopes[p['direction'],p['block']].append(p)
for (direction,block),ps in grouped_slopes.items():
lines += [f"| {direction} | {block} | {len(ps)} | {min(p['slope'] for p in ps):.6f}–{max(p['slope'] for p in ps):.6f} | {min(p['alpha_low'] for p in ps):.3g} |"]
lines += ['']
lines += ['## Discriminating next experiment','',
'Where the full Jacobian action is small because shape and field actions cancel, suppressing the shape component alone would destroy that first-order balance. A targeted hypothesis is that the current straight Newton trial loses the geometry–gravity balance at second order. Test it by holding each saved trial’s shape, density, and other material/scalar coordinates fixed, solving only its linear gravity subsystem to a documented true defect, and comparing the completed trial against the original one. Record all residual blocks, the new hydrostatic/force response, interior diagnostics and virial; lowering the gravity residual alone is insufficient. This is a proposed diagnostic, not a demonstrated solver improvement or a recommendation to promote a new policy.','',
'The completed comparison should preserve the original direction and trial as a control, disclose solve cost, and separate the pressure-admissibility obstruction from residual-metric rejection. A linear one-way preconditioner’s previous failure does not test this nonlinear conditional completion. These probes do not justify clipping enthalpy or deleting shape coordinates.','',
'Before promoting such a change, localize the important remainder and signed-merit contributions by material and exterior element assembly, preserving their shared-DOF cross terms. The existing aggregate gravity norms cannot tell whether an apparently large improvement benefits the interior or mainly removes exterior error. Interior consistency and virial ≤1e-5 remain the promotion criteria.','',
'## Interpretation limits','',
'A resolved second-order remainder, first-order decay of its difference-quotient error, and arithmetic-level fields-only gravity remainder support geometric/field curvature along these particular directions. They do not prove every Jacobian column correct. Jacobian additivity tests linearity and restoration, not agreement with the nonlinear derivative by itself.','',
'These residual-block aggregates do not separate interior from exterior elements. They neither locate a physical error nor identify a symmetry or near-null mode. A large correction or curvature may coexist with a weak normalized direction, but this split is not a condition-number measurement. No new model was accepted and these probes do not establish a virial milestone.','']
return '\n'.join(lines)
def main():
ap=argparse.ArgumentParser(description=__doc__)
ap.add_argument('--campaign',type=Path,default=Path(__file__).resolve().parent,
help='Campaign root containing focused/; writes shape_checks.json and shape_analysis.md here. Defaults to the script directory.')
args=ap.parse_args()
campaign=args.campaign; focused=campaign/'focused'
provenance=json.loads((focused/'provenance.json').read_text())
results={case:analyze_case(focused/case) for case in CASES}
out={'schema_version':1,'source_commit':provenance.get('commit'),'binary_sha256':provenance.get('binary_sha256'),'cases':results}
(campaign/'shape_checks.json').write_text(json.dumps(clean(out),indent=2,allow_nan=False)+'\n')
(campaign/'shape_analysis.md').write_text(make_markdown(results,provenance))
for name,r in results.items(): print(name,r['status'])
if __name__=='__main__':main()

View File

@@ -0,0 +1,143 @@
"""Audit the pressure/shape campaign's completed outputs without running solvers.
The sole argument is the campaign directory containing captures/ and focused/.
The script reads existing results and writes focused_audit_checks.json there.
Unfinished cases are reported as pending; this is an observation audit, not a
stellar convergence or physical acceptance gate.
"""
import argparse
import csv
import hashlib
import json
import math
from pathlib import Path
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("campaign_root", type=Path)
ROOT = parser.parse_args().campaign_root.resolve()
FOCUSED = ROOT / "focused"
def rows(path):
with path.open() as source:
result = list(csv.DictReader(source))
if any(None in r or any(v is None for v in r.values()) for r in result):
raise ValueError(f"Malformed CSV row: {path}")
return result
def metrics(path):
data = rows(path)
if len({r["metric"] for r in data}) != len(data):
raise ValueError(f"Duplicate metric: {path}")
return {r["metric"]: float(r["value"]) for r in data}
def sha(path):
return hashlib.sha256(path.read_bytes()).hexdigest()
def clean(value):
if isinstance(value, dict):
return {k: clean(v) for k, v in value.items()}
if isinstance(value, list):
return [clean(v) for v in value]
if isinstance(value, float) and not math.isfinite(value):
return None
return value
provenance = json.loads((FOCUSED / "provenance.json").read_text())
result = {
"source_commit": provenance["commit"],
"binary_hash_matches": sha(FOCUSED / "plateau_diagnostic") == provenance["binary_sha256"],
"completed": [],
"pending": [],
}
for case in json.loads((FOCUSED / "cases.json").read_text()):
case_id = case["id"]
manifest = FOCUSED / f"{case_id}_run.json"
if not manifest.exists():
result["pending"].append(case_id)
continue
run = json.loads(manifest.read_text())
if "exit_code" not in run:
result["pending"].append(case_id)
continue
folder = FOCUSED / case_id
data = {
"id": case_id,
"exit_code": run["exit_code"],
"seconds": run["seconds"],
"input_hash_count": len(run["input_state_hashes"]),
"input_hash_mismatches": [str(p) for p, h in run["input_state_hashes"].items() if sha(Path(p)) != h],
"output_hash_count": len(run["output_hashes"]),
"output_hash_mismatches": [p for p, h in run["output_hashes"].items() if sha(folder / p) != h],
"unhashed_data_files": sorted(str(p.relative_to(folder)) for p in folder.rglob("*") if p.is_file() and p.suffix in (".txt", ".csv", ".json") and str(p.relative_to(folder)) not in run["output_hashes"]),
"csv_rows": {p.name: len(rows(p)) for p in sorted(folder.glob("*.csv"))},
"frozen": metrics(folder / "frozen_input_checks.csv"),
}
args = case["arguments"]
direction = Path(args[args.index("--probe-direction") + 1])
physical = Path(args[args.index("--probe-state") + 1])
data["direction_copy_byte_identical"] = direction.read_bytes() == (folder / "probe_normalized_correction.txt").read_bytes()
data["physical_base_copy_byte_identical"] = physical.read_bytes() == (folder / "frozen_physical_base.txt").read_bytes()
if "iteration_" in case_id:
iteration = int(case_id.rsplit("_", 1)[1])
capture_root = ROOT / "captures" / ("n1p5_J0_capture" if case_id.startswith("n1p5") else "n1_J0p10_capture")
capture_manifest = json.loads((capture_root.parent / f"{capture_root.name}_run.json").read_text())
data["auxiliary_capture_input_hashes_match"] = all(sha(physical.parent / name) == capture_manifest["output_hashes"][str((physical.parent / name).relative_to(capture_root))] for name in ("normalized_base.txt", "normalized_residual.txt"))
old = next(r for r in rows(capture_root / "newton.csv") if int(r["iteration"]) == iteration)
data["historical_linear_defect_relative"] = float(old["linear_true"])
trial = next(r for r in rows(capture_root / "trials.csv") if int(r["iteration"]) == iteration and r["trial"] == "0")
data["original_first_trial"] = trial
replay = rows(folder / "replayed_candidate.csv")[0]
data["candidate_replay"] = replay
if trial["disposition"] == "4":
data["replayed_candidate_residual_exact"] = replay["admissible"] == "1" and replay["residual_norm"] == trial["F"]
data["replayed_candidate_residual_difference"] = float(replay["residual_norm"]) - float(trial["F"])
data["replayed_candidate_minimum_jacobian_exact"] = replay["minimum_jacobian"] == trial["min_jacobian"]
else:
previous = physical.parent
data["historical_linear_defect_relative"] = float(next(r for r in rows(previous / "frozen_linear.csv") if r["restart"] == "160")["true_relative"])
data["linear_defect_relative_difference"] = data["frozen"]["linear_defect_relative"] - data["historical_linear_defect_relative"]
layout = rows(folder / "layout.csv")
residual_blocks = {r["block"] for r in layout if r["kind"] == "residual"}
value_blocks = {r["block"] for r in layout if r["kind"] == "value"}
nr = sum(r["kind"] == "residual" for r in layout)
nv = sum(r["kind"] == "value" for r in layout)
if "--shape-curvature" in args:
data["shape_summary"] = metrics(folder / "shape_curvature_summary.csv")
expected = {"shape_curvature_directions.csv": 3 * nv, "shape_curvature_actions.csv": nr, "shape_curvature_preparations.csv": 22, "shape_curvature_restorations.csv": 4 * nr, "shape_curvature_remainders.csv": 18 * nr, "shape_curvature_mixed.csv": 6 * nr}
data["shape_row_count_mismatches"] = {f: [data["csv_rows"][f], count] for f, count in expected.items() if data["csv_rows"][f] != count}
restorations = rows(folder / "shape_curvature_restorations.csv")
data["shape_max_restoration_difference"] = max(float(r["restoration_difference_norm"]) for r in restorations)
mixed = rows(folder / "shape_curvature_mixed.csv")
alphas = {r["alpha"] for r in mixed}
remainders = rows(folder / "shape_curvature_remainders.csv")
data["shape_six_alphas"] = len(alphas) == 6
data["shape_mixed_keys_complete"] = {(r["alpha"], r["block"]) for r in mixed} == {(a, b) for a in alphas for b in residual_blocks}
data["shape_remainder_keys_complete"] = {(r["alpha"], r["direction"], r["block"]) for r in remainders} == {(a, d, b) for a in alphas for d in ("full", "shape", "fields") for b in residual_blocks}
data["shape_direction_keys_complete"] = {(r["direction"], r["value_block"]) for r in rows(folder / "shape_curvature_directions.csv")} == {(d, b) for d in ("full", "shape", "fields") for b in value_blocks}
data["shape_max_absolute_merit_identity_error"] = max(abs(float(r["merit_identity_error"])) for r in mixed)
data["shape_max_absolute_projection_decomposition_error"] = max(abs(float(r["projection_decomposition_error"])) for r in mixed)
data["shape_all_trials_admissible"] = all(r["all_trials_admissible"] == "1" for r in mixed)
data["shape_all_increments_resolved"] = all(r["all_state_increments_resolved"] == "1" for r in mixed)
data["shape_all_alpha_squared_valid"] = all(r["alpha_squared_valid"] == "1" for r in mixed)
if "--pressure-probe" in args:
data["pressure_summary"] = metrics(folder / "pressure_obstruction_summary.csv")
pressure = rows(folder / "pressure_obstruction_trials.csv")
blocks = rows(folder / "pressure_obstruction_blocks.csv")
data["pressure_admissible_trials"] = sum(r["admissible"] == "1" for r in pressure)
data["pressure_expected_block_rows"] = nr * data["pressure_admissible_trials"]
data["pressure_block_rows_complete"] = len(blocks) == data["pressure_expected_block_rows"]
data["pressure_trial_keys_unique"] = len({(r["direction"], r["alpha"]) for r in pressure}) == len(pressure)
data["pressure_block_keys_complete"] = {(r["direction"], r["alpha"], r["block"]) for r in blocks} == {(r["direction"], r["alpha"], b) for r in pressure if r["admissible"] == "1" for b in residual_blocks}
data["pressure_limiting_h_prediction_max_absolute_error"] = {
family: max(abs(float(r[f"{family}_limiting_h_prediction"]) - float(r[f"{family}_limiting_h_evaluated"])) for r in pressure)
for family in ("closure", "pressure")
}
result["completed"].append(data)
(ROOT / "focused_audit_checks.json").write_text(json.dumps(clean(result), indent=2) + "\n")
print(json.dumps({"completed": [r["id"] for r in result["completed"]], "pending": result["pending"]}, indent=2))

View File

@@ -0,0 +1,167 @@
"""Audit completed supplemental surface observations without running solvers.
Pass the campaign directory containing captures/, focused/, supplemental/ and
supplemental_inputs/. Writes surface_audit_checks.json in that directory.
This records method invariants and sampled values, not physical acceptance.
"""
import argparse
import csv
import hashlib
import json
import math
from pathlib import Path
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("campaign_root", type=Path)
ROOT = parser.parse_args().campaign_root.resolve()
SUPPLEMENTAL = ROOT / "supplemental"
def sha(path):
return hashlib.sha256(path.read_bytes()).hexdigest()
def rows(path):
with path.open() as source:
data = list(csv.DictReader(source))
if any(None in r or any(v is None for v in r.values()) for r in data):
raise ValueError(f"Malformed CSV row: {path}")
return data
def metrics(path):
data = rows(path)
if len({r["metric"] for r in data}) != len(data):
raise ValueError(f"Duplicate metric: {path}")
return {r["metric"]: float(r["value"]) for r in data}
def vector(path):
tokens = path.read_text().split()
data = list(map(float, tokens[1:]))
if len(data) != int(tokens[0]) or not all(map(math.isfinite, data)):
raise ValueError(f"Malformed/nonfinite vector: {path}")
return data
def clean(value):
if isinstance(value, dict):
return {k: clean(v) for k, v in value.items()}
if isinstance(value, list):
return [clean(v) for v in value]
if isinstance(value, float) and not math.isfinite(value):
return None
return value
provenance = json.loads((SUPPLEMENTAL / "provenance.json").read_text())
derivation = json.loads((ROOT / "supplemental_inputs/between_bounds_derivation.json").read_text())
base = vector(Path(derivation["normalized_base"]))
direction = vector(Path(derivation["direction"]))
candidate = vector(Path(derivation["candidate"]))
if not len(base) == len(direction) == len(candidate):
raise ValueError("Midpoint candidate vector dimensions differ")
alpha = derivation["alpha"]
bounds = metrics(ROOT / "focused/n1_J0p10_iteration_2/frozen_enthalpy_bound.csv")
result = {
"source_commit": provenance["commit"],
"binary_hash_matches": sha(SUPPLEMENTAL / "plateau_diagnostic") == provenance["binary_sha256"],
"midpoint": {
"alpha": alpha,
"vector_size": len(candidate),
"maximum_reconstruction_error": max(abs(b + alpha * d - c) for b, d, c in zip(base, direction, candidate)),
"candidate_hash_matches": sha(Path(derivation["candidate"])) == derivation["candidate_sha256"],
"bounds_match_original_scan": bounds["closure_alpha_h"] == derivation["closure_bound"] and bounds["pressure_alpha_h"] == derivation["pressure_bound"],
"strictly_between_bounds": derivation["closure_bound"] < alpha < derivation["pressure_bound"],
"exact_arithmetic_midpoint": alpha == 0.5 * (derivation["closure_bound"] + derivation["pressure_bound"]),
},
"completed": [],
"pending": [],
}
for case in json.loads((SUPPLEMENTAL / "cases.json").read_text()):
case_id = case["id"]
manifest = SUPPLEMENTAL / f"{case_id}_run.json"
if not manifest.exists():
result["pending"].append(case_id)
continue
run = json.loads(manifest.read_text())
if "exit_code" not in run:
result["pending"].append(case_id)
continue
folder = SUPPLEMENTAL / case_id
args = case["arguments"]
physical_path = Path(args[args.index("--probe-state") + 1])
direction_path = Path(args[args.index("--probe-direction") + 1])
capture_index = int(physical_path.parent.name.split("_")[-1])
original_focused = ROOT / "focused" / f"n1_J0p10_iteration_{capture_index}"
capture_root = physical_path.parent.parent
capture_manifest = json.loads((capture_root.parent / f"{capture_root.name}_run.json").read_text())
summary = metrics(folder / "surface_trace_summary.csv")
carrier = rows(folder / "surface_trace_rows.csv")
limits = rows(folder / "surface_trace_limits.csv")
nodes = rows(folder / "surface_trace_nodes.csv")
physical_base = vector(physical_path)
normalized_direction = vector(direction_path)
capture_metadata = dict(line.split("=", 1) for line in (physical_path.parent / "capture.txt").read_text().splitlines())
replay_alpha = alpha if "between_bounds" in case_id else float(capture_metadata["first_trial_alpha"])
data = {
"id": case_id,
"exit_code": run["exit_code"],
"seconds": run["seconds"],
"input_hash_count": len(run["input_state_hashes"]),
"input_hash_mismatches": [p for p, h in run["input_state_hashes"].items() if sha(Path(p)) != h],
"output_hash_count": len(run["output_hashes"]),
"output_hash_mismatches": [p for p, h in run["output_hashes"].items() if sha(folder / p) != h],
"unhashed_data_files": sorted(str(p.relative_to(folder)) for p in folder.rglob("*") if p.is_file() and p.suffix in (".txt", ".csv", ".json") and str(p.relative_to(folder)) not in run["output_hashes"]),
"auxiliary_capture_input_hashes_match": all(sha(physical_path.parent / name) == capture_manifest["output_hashes"][str((physical_path.parent / name).relative_to(capture_root))] for name in ("normalized_base.txt", "normalized_residual.txt")),
"frozen": metrics(folder / "frozen_input_checks.csv"),
"frozen_residual_byte_identical_to_original_focus": (folder / "frozen_normalized_residual.txt").read_bytes() == (original_focused / "frozen_normalized_residual.txt").read_bytes(),
"enthalpy_bound_byte_identical_to_original_focus": (folder / "frozen_enthalpy_bound.csv").read_bytes() == (original_focused / "frozen_enthalpy_bound.csv").read_bytes(),
"direction_copy_byte_identical": direction_path.read_bytes() == (folder / "probe_normalized_correction.txt").read_bytes(),
"physical_base_copy_byte_identical": physical_path.read_bytes() == (folder / "frozen_physical_base.txt").read_bytes(),
"candidate_replay": rows(folder / "replayed_candidate.csv")[0],
"surface_summary": summary,
"csv_rows": {p.name: len(rows(p)) for p in sorted(folder.glob("*.csv"))},
"carrier_rows_complete": len(carrier) == int(summary["surface_row_count"]) and {int(r["surface_index"]) for r in carrier} == set(range(len(carrier))),
"carrier_reduced_indices_unique": len({r["reduced_h_index"] for r in carrier}) == len(carrier),
"carrier_root_offsets_correct": all(int(r["root_index"]) == int(summary["h_root_offset"]) + int(r["reduced_h_index"]) for r in carrier),
"carrier_base_matches_physical_input": all(float(r["base_h"]) == physical_base[int(r["root_index"])] for r in carrier),
"all_input_carrier_normalized_direction_coefficients_zero": all(normalized_direction[int(r["root_index"])] == 0 for r in carrier),
"carrier_unit_step_arithmetic_error": max(abs(float(r["base_h"]) + float(r["direction_dh"]) - float(r["h_plus_dh"])) for r in carrier),
"carrier_recomputed": {},
"carrier_summary_differences": {},
"limit_families_complete": {r["family"] for r in limits} == {"closure", "pressure"} and len(limits) == 2,
"limit_partition_max_errors": {},
"nodes_by_family": {},
}
for name in ("base_h", "direction_dh", "h_plus_dh"):
values = [float(r[name]) for r in carrier]
data["carrier_recomputed"][name] = {
"minimum": min(values), "maximum": max(values), "maximum_absolute": max(map(abs, values)),
"norm": math.sqrt(math.fsum(v * v for v in values)),
"negative_count": sum(v < 0 for v in values), "nonzero_count": sum(v != 0 for v in values),
}
data["carrier_summary_differences"][name] = {stat: value - summary[f"{name}_{stat}"] for stat, value in data["carrier_recomputed"][name].items()}
for suffix in ("h", "dh", "h_plus_dh"):
data["limit_partition_max_errors"][suffix] = max(abs(float(r[f"full_{suffix}"]) - float(r[f"boundary_{suffix}"]) - float(r[f"interior_{suffix}"])) for r in limits)
for limit in limits:
family = limit["family"]
subset = [r for r in nodes if r["family"] == family]
data["nodes_by_family"][family] = {
"rows": len(subset),
"element_matches_limit": all(r["element"] == limit["element"] for r in subset),
"node_indices_complete": len(subset) > 0 and len(subset) == int(subset[0]["node_count"]) and {int(r["local_node"]) for r in subset} == set(range(len(subset))),
"fe_orders": sorted({int(r["fe_order"]) for r in subset}),
"geometry_types": sorted({int(r["geometry_type"]) for r in subset}),
"base_minimum": min(float(r["h"]) for r in subset),
"union_prediction_minimum": min(float(r["h_plus_alpha_union_dh"]) for r in subset),
"unit_step_minimum": min(float(r["h_plus_dh"]) for r in subset),
"replay_alpha": replay_alpha,
"replay_candidate_nodal_prediction_minimum": min(float(r["h"]) + replay_alpha * float(r["dh"]) for r in subset),
"union_prediction_max_arithmetic_error": max(abs(float(r["h"]) + float(r["alpha_union"]) * float(r["dh"]) - float(r["h_plus_alpha_union_dh"])) for r in subset),
"unit_step_max_arithmetic_error": max(abs(float(r["h"]) + float(r["dh"]) - float(r["h_plus_dh"])) for r in subset),
}
result["completed"].append(data)
(ROOT / "surface_audit_checks.json").write_text(json.dumps(clean(result), indent=2) + "\n")
print(json.dumps({"completed": [r["id"] for r in result["completed"]], "pending": result["pending"]}, indent=2))

View File

@@ -0,0 +1,218 @@
#!/usr/bin/env python3
"""Offline Q3 interpolation and bounded interior sampling; no solver or input mutation."""
import argparse
import csv
import itertools
import json
import math
from pathlib import Path
def read_rows(path):
with path.open() as stream:
return list(csv.DictReader(stream))
def weights(nodes, x):
return [math.prod((x-other)/(node-other) for other in nodes if other != node) for node in nodes]
def evaluate(axes, coefficients, point):
w = [weights(axis, x) for axis, x in zip(axes, point)]
return math.fsum(coefficients[i][j][k]*w[0][i]*w[1][j]*w[2][k]
for i, j, k in itertools.product(range(4), repeat=3))
def extrema_record():
return {'minimum': math.inf, 'minimum_reference_point': None,
'negative_samples': 0, 'negative_beyond_roundoff_samples': 0}
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('campaign_root', nargs='?', type=Path, default=Path(__file__).resolve().parent)
args = parser.parse_args()
root = args.campaign_root.expanduser().resolve()
trajectory = {int(r['iteration']): r for r in read_rows(root/'captures/n1_J0p10_capture/newton.csv')}
case_ids = [('n1_J0p10_onset_between_bounds', 2), ('n1_J0p10_late_surface_trace', 11)]
results = []
for name, iteration in case_ids:
candidates = list(root.glob(f'**/{name}/surface_trace_nodes.csv'))
if len(candidates) != 1:
raise ValueError(f'Expected one nodal export for {name}')
folder = candidates[0].parent
raw = read_rows(candidates[0])
nodal = [r for r in raw if r['family'] == 'pressure']
closure = [r for r in raw if r['family'] == 'closure']
limits = read_rows(folder/'surface_trace_limits.csv')
if len(nodal) != 64 or any(int(r['fe_order']) != 3 or int(r['node_count']) != 64 for r in nodal):
raise ValueError(f'{name} is not the expected 64-node cubic element')
if len({r['element'] for r in nodal + closure}) != 1:
raise ValueError('This bounded follow-up expects one shared limiting element per captured state')
for field in ('local_node', 'ip_x', 'ip_y', 'ip_z', 'h', 'dh'):
if [r[field] for r in nodal] != [r[field] for r in closure]:
raise ValueError(f'Family exports disagree: {name} {field}')
axes = [sorted({float(r['ip_'+axis]) for r in nodal}) for axis in 'xyz']
if any(len(axis) != 4 or axis[0] != 0 or axis[-1] != 1 for axis in axes):
raise ValueError('Expected four distinct interpolation coordinates per unit-cube axis')
coordinates = [tuple(float(r['ip_'+axis]) for axis in 'xyz') for r in nodal]
if set(coordinates) != set(itertools.product(*axes)) or len(set(coordinates)) != 64:
raise ValueError('Export is not a complete unique tensor-product grid')
fields = []
for field in ('h', 'dh'):
values = [[[0.0 for _ in range(4)] for _ in range(4)] for _ in range(4)]
for r, point in zip(nodal, coordinates):
i, j, k = [axis.index(x) for axis, x in zip(axes, point)]
values[i][j][k] = float(r[field])
fields.append(values)
scale = max(abs(float(r[field])) for r in nodal for field in ('h', 'dh'))
tolerance = 128*math.ulp(1.0)*scale
checks = []
node_error = max(abs(evaluate(axes, coefficients, point)-float(r[field]))
for field, coefficients in zip(('h', 'dh'), fields)
for r, point in zip(nodal, coordinates))
if node_error > tolerance:
raise ValueError(f'Node interpolation validation failed: {node_error}')
for limit in limits:
point = tuple(float(limit['ip_'+axis]) for axis in 'xyz')
check = {'family': limit['family'], 'reference_point': point}
for field, coefficients in zip(('h', 'dh'), fields):
value = evaluate(axes, coefficients, point)
expected = float(limit['full_'+field])
check[field] = value
check[field+'_production'] = expected
check[field+'_absolute_disagreement'] = abs(value-expected)
if abs(value-expected) > tolerance:
raise ValueError(f'Production-point interpolation validation failed: {check}')
checks.append(check)
pressure_limit = next(r for r in limits if r['family'] == 'pressure')
pressure_x, pressure_y = [float(pressure_limit['ip_'+axis]) for axis in 'xy']
surface_line = []
for z in (1e-6, .001, .005, float(pressure_limit['ip_z'])):
point = (pressure_x, pressure_y, z)
h, dh = [evaluate(axes, values, point) for values in fields]
surface_line.append({'reference_point': point, 'h': h, 'dh': dh})
zero_faces = []
for dim, axis in enumerate('xyz'):
for side in (0.0, 1.0):
face = [r for r in nodal if float(r['ip_'+axis]) == side]
if len(face) == 16 and all(float(r['h']) == 0 and float(r['dh']) == 0 for r in face):
zero_faces.append((dim, side))
if zero_faces != [(2, 0.0)]:
raise ValueError(f'Expected the exported exact-zero face z=0; found {zero_faces}')
grids = []
for dim, axis in enumerate('xyz'):
values = {i/64 for i in range(1, 64)} | set(axes[dim][1:-1])
values.update(float(r['ip_'+axis]) for r in limits)
if dim == 2:
values.update(10**(-12+i/4) for i in range(45)) # 1e-12 through 1e-1.
grids.append(sorted(values))
union = float(nodal[0]['alpha_union'])
alphas = [('base', 0.0), ('accepted_alpha', float(trajectory[iteration]['alpha'])),
('near_below_union', .99*union), ('near_above_union', 1.01*union)]
if iteration == 11:
alphas.append(('unit_step', 1.0))
extrema = {label: extrema_record() for label, _ in alphas}
directional_bound = {'minimum_nonnegative_base_ratio': math.inf, 'reference_point': None,
'h': None, 'dh': None, 'base_negative_and_direction_decreasing_samples': 0}
wz = [weights(axes[2], z) for z in grids[2]]
# Tensor contractions avoid a 64-term sum at every point. This is an
# independent offline interpolation, validated above before use.
for x in grids[0]:
wx = weights(axes[0], x)
yz = [[[math.fsum(values[i][j][k]*wx[i] for i in range(4)) for k in range(4)]
for j in range(4)] for values in fields]
for y in grids[1]:
wy = weights(axes[1], y)
z_values = [[math.fsum(values[j][k]*wy[j] for j in range(4)) for k in range(4)] for values in yz]
for z, weights_z in zip(grids[2], wz):
h, dh = [math.fsum(values[k]*weights_z[k] for k in range(4)) for values in z_values]
point = (x, y, z)
for label, alpha in alphas:
value = h+alpha*dh
record = extrema[label]
if value < record['minimum']:
record['minimum'] = value
record['minimum_reference_point'] = point
record['negative_samples'] += value < 0
record['negative_beyond_roundoff_samples'] += value < -tolerance
if h < 0 and dh < 0:
directional_bound['base_negative_and_direction_decreasing_samples'] += 1
if h >= 0 and dh < 0 and -h/dh < directional_bound['minimum_nonnegative_base_ratio']:
directional_bound.update(minimum_nonnegative_base_ratio=-h/dh, reference_point=point, h=h, dh=dh)
base_admissible = extrema['base']['negative_samples'] == 0
for label, alpha in alphas:
record = extrema[label]
h, dh = [evaluate(axes, values, record['minimum_reference_point']) for values in fields]
error = abs(h+alpha*dh-record['minimum'])
record['minimum_direct_sum_verification_error'] = error
if error > tolerance:
raise ValueError(f'Tensor contraction/direct-sum disagreement at minimum: {error}')
directional_bound['sampled_base_admissible'] = base_admissible
directional_bound['sampled_admissible_step_bound'] = directional_bound['minimum_nonnegative_base_ratio'] if base_admissible else None
result = {'case': name, 'iteration': iteration, 'element': int(nodal[0]['element']), 'fe_order': 3,
'geometry_type': int(nodal[0]['geometry_type']), 'node_count': 64, 'axes': axes,
'zero_faces': [{'axis': 'z', 'side': 0}], 'node_interpolation_max_error': node_error,
'production_point_checks': checks, 'roundoff_scale_estimate': tolerance,
'pressure_xy_surface_line': surface_line,
'grid': {'axes': grids, 'shape': [len(g) for g in grids], 'sample_count': math.prod(map(len, grids)),
'strictly_interior': True, 'log_surface_distances': [1e-12, 1e-1]},
'union_production_bound': union, 'alphas': dict(alphas), 'sampled_extrema': extrema,
'directional_bound': directional_bound}
results.append(result)
report = {'schema_version': 1, 'method': 'Independent tensor Q3 nodal interpolation and finite interior sampling',
'limitations': ['No global positivity certificate or rigorous polynomial minimum.',
'Reported minima are over the specified finite reference-coordinate grids.',
'Direction coefficients include saved-direction reconstruction roundoff; base h does not.',
'The roundoff scale is descriptive, not a certified interpolation error bound.'], 'cases': results}
(root/'pressure_polynomial_checks.json').write_text(json.dumps(report, indent=2, allow_nan=False)+'\n')
lines = ['# Offline enthalpy polynomial sampling', '',
'Both captured limiting elements have 64 distinct tensor-product nodes and cubic enthalpy order. '
'The interpolation uses only exported physical nodal h and dh; it launches no solver and changes no inputs. '
'The complete z=0 nodal face has exactly zero h and dh in both cases.', '',
'| Iteration | Node reconstruction error | Max production-point discrepancy | Grid points |',
'|---:|---:|---:|---:|']
for c in results:
error = max(r[key] for r in c['production_point_checks'] for key in ('h_absolute_disagreement', 'dh_absolute_disagreement'))
lines.append(f"| {c['iteration']} | {c['node_interpolation_max_error']:.9g} | {error:.9g} | {c['grid']['sample_count']} |")
lines += ['', 'Each grid is strictly inside the reference cube: uniform spacing 1/64, exported interior node '
'coordinates and production-limit coordinates, plus z distances 1e-12 through 1e-1 in quarter decades '
'from the exactly zero face. Minima below are sampled minima, not global polynomial minima.', '',
'| Iteration | State | Alpha | Sampled minimum h | Reference (x,y,z) | Negative samples |',
'|---:|---|---:|---:|---|---:|']
for c in results:
for label, record in c['sampled_extrema'].items():
point = ', '.join(f'{x:.9g}' for x in record['minimum_reference_point'])
lines.append(f"| {c['iteration']} | {label} | {c['alphas'][label]:.9g} | {record['minimum']:.9g} | ({point}) | {record['negative_samples']} |")
for c in results:
bound = c['directional_bound']
if not bound['sampled_base_admissible']:
lines += ['', f"Iteration {c['iteration']} already has negative enthalpy in the saved **base** on this grid. "
'A positivity-preserving step bound from that base is therefore undefined; the JSON separately '
'reports the smallest nonnegative-base ratio only as a diagnostic. This base conclusion does '
'not depend on reconstructing the Newton direction.']
else:
lines += ['', f"Iteration {c['iteration']} has no negative base samples on this grid. The sampled directional "
f"bound is {bound['sampled_admissible_step_bound']:.12g}, versus production-rule bound {c['union_production_bound']:.12g}. "
'This remains a sampled condition, not a guarantee of positivity everywhere.']
lines += ['', 'An independent direct 64-term sum also reproduces every contracted-grid minimum to roundoff. '
'Along the pressure-limit x,y line, the offline base-field values are:', '',
'| Iteration | z reference coordinate | Base h |', '|---:|---:|---:|']
for c in results:
for row in c['pressure_xy_surface_line']:
lines.append(f"| {c['iteration']} | {row['reference_point'][2]:.12g} | {row['h']:.12g} |")
lines += ['', 'The production-point validation establishes consistency with the exported full-field values at '
'both pressure and closure limit points to roundoff. Dense sampling can prove the existence of negative '
'values when their size clearly exceeds numerical disagreement; absence of negative samples cannot '
'prove positivity throughout the element. These data diagnose pointwise enthalpy, not virial balance '
'or the origin of the selected Newton direction.', '',
'Reproduce with `python3 sample_pressure_polynomial.py /path/to/campaign_artifacts`. '
'Machine-readable grids, locations, validation errors and sample counts are in pressure_polynomial_checks.json.']
(root/'pressure_polynomial_analysis.md').write_text('\n'.join(lines)+'\n')
print(json.dumps([{'iteration': c['iteration'], 'base_minimum': c['sampled_extrema']['base']['minimum'],
'sample_count': c['grid']['sample_count'], 'base_admissible': c['directional_bound']['sampled_base_admissible']}
for c in results]))
if __name__ == '__main__':
main()

View File

@@ -0,0 +1,36 @@
[
{
"id": "n1_J0p10_capture",
"arguments": [
"--index",
"1",
"--angular-momentum",
"0.1",
"--no-central",
"--restart",
"160",
"--max-newton",
"12",
"--capture-iterations",
"2,3,4,7,11"
],
"notes": "Repeat prior live trajectory; capture pressure onset and shrinking-step states from observer spans without changing solver policy."
},
{
"id": "n1p5_J0_capture",
"arguments": [
"--index",
"1.5",
"--angular-momentum",
"0",
"--no-central",
"--restart",
"160",
"--max-newton",
"3",
"--capture-iterations",
"1,2"
],
"notes": "Repeat first three guarded Newton attempts; capture first severely damped cold direction and subsequent guarded direction."
}
]

View File

@@ -0,0 +1,32 @@
[
{
"id": "n1_J0_no_central_R160",
"arguments": [
"--index",
"1",
"--angular-momentum",
"0",
"--no-central",
"--restart",
"160",
"--max-newton",
"8"
],
"notes": "Nonrotating physical counterpart of the combined sandbox example; strict Newton tolerance and q14/q18 physical validation."
},
{
"id": "n1_J0p10_no_central_R160",
"arguments": [
"--index",
"1",
"--angular-momentum",
"0.1",
"--no-central",
"--restart",
"160",
"--max-newton",
"12"
],
"notes": "Transfer check at twice the previously validated angular momentum, with unchanged numerical settings; no critical-rotation fraction is assumed."
}
]

View File

@@ -0,0 +1,47 @@
[
{
"id": "n1_J0p05_no_central_R40",
"arguments": [
"--index",
"1",
"--angular-momentum",
".05",
"--no-central",
"--restart",
"40",
"--max-newton",
"8"
],
"notes": "Matched central-phase removal control; baseline solver policy."
},
{
"id": "n1_J0p05_no_central_R160",
"arguments": [
"--index",
"1",
"--angular-momentum",
".05",
"--no-central",
"--restart",
"160",
"--max-newton",
"8"
],
"notes": "Only Krylov restart differs from preceding model."
},
{
"id": "n1p5_J0_no_central_R160",
"arguments": [
"--index",
"1.5",
"--angular-momentum",
"0",
"--no-central",
"--restart",
"160",
"--max-newton",
"8"
],
"notes": "Higher-index live control before initial-guess safeguard."
}
]

View File

@@ -0,0 +1,764 @@
#pragma once
// Include after importing mean_field. This is an experiment-local inverse;
// it does not replace or prepare the authoritative normalized Jacobian.
#include <algorithm>
#include <array>
#include <cmath>
#include <concepts>
#include <cstddef>
#include <cstdint>
#include <limits>
#include <memory>
#include <span>
#include <stdexcept>
#include <type_traits>
#include <utility>
#include <vector>
#include <mfem.hpp>
#include <mpi.h>
namespace experiment::plateau_diagnostics {
struct CoupledShapeCoarseOptions final {
double relativeRankTolerance{1.e-10};
double minimumSubspaceOverlap{1.e-8};
};
enum class CoupledShapeCoarseFallback { none, no_independent_modes, insufficient_subspace_overlap };
enum class CoupledShapeCoarseModeStatus { retained, dependent_source, dependent_filtered_image };
struct CoupledShapeCoarseModeReport final {
// QR admission is retained even if the complete space later falls back.
CoupledShapeCoarseModeStatus status{CoupledShapeCoarseModeStatus::dependent_source};
double normalizedInputNorm{0.0};
double sourceImageNorm{0.0};
double sourceIndependentFraction{0.0};
double filteredImageNorm{0.0};
double filteredIndependentFraction{0.0};
};
struct CoupledShapeCoarseStatistics final {
int inputModes{0};
int independentModes{0};
int activeModes{0};
int sourceDependentModes{0};
int imageDependentModes{0};
CoupledShapeCoarseFallback fallback{CoupledShapeCoarseFallback::no_independent_modes};
double reciprocalOverlapCondition{std::numeric_limits<double>::quiet_NaN()};
double minimumOverlapLowerBound{std::numeric_limits<double>::quiet_NaN()};
std::uint64_t setups{0};
std::uint64_t setupOperatorApplications{0};
std::uint64_t setupInverseApplications{0};
double lastSetupSeconds{0.0};
double lastSetupOperatorSeconds{0.0};
double lastSetupInverseSeconds{0.0};
double totalSetupSeconds{0.0};
// Application clocks are rank-local; aggregate them outside the timed
// solve. The only application reductions validate and project vectors.
std::uint64_t applications{0};
std::uint64_t inverseApplications{0};
std::uint64_t failedApplications{0};
double applicationSecondsLocal{0.0};
double inverseSecondsLocal{0.0};
std::size_t persistentVectorBytes{0};
};
template <class Candidate>
concept CoupledCoarseNormalizedOperator =
std::derived_from<Candidate, mfem::Operator> &&
requires(const Candidate &operation, const mfem::Vector &physical, mfem::Vector &normalized) {
{ operation.IsPrepared() } -> std::same_as<bool>;
{ operation.GetProblem().GetPreparationGeneration() } -> std::convertible_to<std::uint64_t>;
{ operation.NormalizeState(physical, normalized) } -> std::same_as<void>;
};
template <class Candidate>
concept CoupledCoarseStationaryInverse =
std::derived_from<Candidate, mfem::Solver> &&
mean_field::solver::LinearPreconditionerApplicationContractAvailable<Candidate> &&
(mean_field::solver::linearPreconditionerApplicationContract<Candidate> ==
mean_field::preconditioning::ApplicationContract::stationary_linear) &&
requires(const Candidate &inverse) {
{ inverse.IsCurrent() } -> std::same_as<bool>;
};
namespace coupled_shape_detail {
template <class Inverse>
using RootBlock = std::remove_cvref_t<decltype(std::declval<const Inverse &>().GetBlock())>;
template <class Inverse>
using MaterialBlock = typename RootBlock<Inverse>::StructureComponent::MaterialSurfaceComponent;
template <mean_field::equilibrium::DiscretizedStellarEquilibriumProblem Problem>
[[nodiscard]] mean_field::deformation::PreparedNodalRadialSurface
MakeDefaultRadialSurface(const Problem &problem) {
using namespace mean_field;
const auto &physical = problem.GetPhysicalOperator();
const auto &domain = physical.GetDomainDeformation();
const auto &fem = physical.GetHydrostaticOperator().GetFEM();
const auto dependencies = domain.discretizationDependencies();
const auto communicator = problem.GetCommunicator();
const auto all = [communicator](bool condition) {
int local = condition, global = 0;
if (MPI_Allreduce(&local, &global, 1, MPI_INT, MPI_MIN, communicator) != MPI_SUCCESS)
throw std::runtime_error("Could not validate the radial shape basis geometry.");
return global != 0;
};
if (!all(
physical.IsPrepared() && fem.mesh && fem.surfaceDeformationFes && fem.displacementFes &&
dependencies.isCurrent() && dependencies.physicalMeshIdentity == fem.mesh.get() &&
dependencies.surfaceScalarSpaceIdentity == fem.surfaceDeformationFes.get() &&
dependencies.volumeDisplacementSpaceIdentity == fem.displacementFes.get()
))
throw std::logic_error("Radial shape modes require the current physical deformation spaces.");
const auto &scalar = *fem.surfaceDeformationFes;
const auto &vector = *fem.displacementFes;
mfem::Vector center(3);
center = 0.0;
const deformation::NodalRadialSurface prescription(std::move(center));
if (!all(
fem.mesh->SpaceDimension() == 3 && scalar.GetVDim() == 1 && vector.GetVDim() == 3 &&
vector.GetOrdering() == mfem::Ordering::byNODES &&
vector.GetTrueVSize() == 3 * scalar.GetTrueVSize() && vector.FEColl() == scalar.FEColl() &&
domain.descriptor().surfaceDeformation == prescription.descriptor()
))
throw std::invalid_argument(
"The shape benchmark requires the default radial surface and its scalar companion."
);
// StellarEquilibriumProblem currently compiles this zero-center
// prescription, then erases its type. Reuse the same compiler and
// exact FEM boundary map instead of reproducing its geometry math.
auto radial = deformation::compileSurfaceDeformationPrescription(
prescription,
deformation::SurfaceDeformationCompilationContext{
*fem.surfaceDeformationFes, field::make_stellar_surface_scalar_dof_map(*fem.surfaceDeformationFes)
}
);
if (!all(radial.parameterCount() == domain.parameterCount()))
throw std::invalid_argument("The reconstructed radial map does not match the physical parameters.");
// The runtime descriptor does not retain the center. Verify actual
// surface motion against the reconstructed directions; metadata
// alone must not admit a future shifted-center prescription.
mfem::Vector unit(domain.parameterCount()), action(domain.volumeDisplacementSize());
unit = 1.0;
domain.applyJacobian(physical.GetSurfaceDeformationParameters(), unit, action);
bool matches = true;
const int scalarSize = scalar.GetTrueVSize();
for (int i = 0; i < radial.parameterCount(); ++i)
for (int component = 0; component < 3; ++component) {
// MFEM byNODES stores component-sized blocks, as required
// by the existing radial extension's true-DOF mapping.
const int dof = radial.surfaceDofMap().volume_true_dof(i) + component * scalarSize;
const double observed = action(dof), expected = radial.radialDirection(i, component);
matches = matches && std::isfinite(observed) && std::isfinite(expected) &&
std::abs(observed - expected) <= 512.0 * std::numeric_limits<double>::epsilon();
}
if (!all(matches && dependencies.isCurrent()))
throw std::invalid_argument("The actual surface motion disagrees with the zero-center radial basis.");
return radial;
}
template <class Problem, class Inverse>
concept SupportsShapeModes =
mean_field::equilibrium::DiscretizedStellarEquilibriumProblem<Problem> &&
requires(const Problem &problem, const Inverse &inverse) {
typename MaterialBlock<Inverse>::Factorization;
requires std::same_as<
typename MaterialBlock<Inverse>::Factorization,
mean_field::preconditioning::SurfaceThenMaterialTriangular>;
{ inverse.GetProblem() } -> std::same_as<const Problem &>;
{ inverse.IsCurrent() } -> std::same_as<bool>;
inverse.GetCoordinateMap().GetCorrectionRanges();
inverse.GetGroupedPreconditioner().GetStructurePreconditioner().GetCrossCouplings();
inverse.GetGroupedPreconditioner()
.GetStructurePreconditioner()
.GetMaterialSurfacePreconditioner()
.GetCoupledOperator();
inverse.GetGroupedPreconditioner().GetStructurePreconditioner().GetGravityPreconditioner();
{ problem.GetPreparationGeneration() } -> std::convertible_to<std::uint64_t>;
{
MakeDefaultRadialSurface(problem)
} -> std::same_as<mean_field::deformation::PreparedNodalRadialSurface>;
};
} // namespace coupled_shape_detail
// These are geometry modes, not Newton-RHS samples. Complete their material
// and gravity response with existing fixed inverses; neither completion is
// an exact elimination. Scalar unknowns stay zero, while the later full-J
// images retain every scalar equation, including an optional central border.
// Construction performs nine explicit surface-to-material actions, material
// inverse applications, material-to-gravity actions, and gravity applications.
// The material inverse also performs its usual internal coupling actions.
// One extra domain Jacobian action verifies the reconstructed radial basis.
template <
class Problem,
class PhysicalInverse>
requires coupled_shape_detail::SupportsShapeModes<
Problem,
PhysicalInverse>
[[nodiscard]] std::vector<mfem::Vector> MakeCoupledShapeModes(
const Problem &problem,
const PhysicalInverse &inverse
) {
using namespace mean_field;
using namespace utils::blocks;
using Material = coupled_shape_detail::MaterialBlock<PhysicalInverse>;
using Root = coupled_shape_detail::RootBlock<PhysicalInverse>;
using Corrections = typename Material::CorrectionBlocks;
using Residuals = typename Material::ResidualBlocks;
using Gravity = typename Root::StructureComponent::GravityComponent;
// The borrowed coupling operator exposes this exact three-field packing.
// Constraining the descriptor prevents a superficially compatible custom
// material recipe from silently assigning a physical mode to wrong rows.
static_assert(
std::same_as<
Corrections,
type_list<density::mass::value, surface_deformation::parameters::value, enthalpy::specific::value>>
);
static_assert(std::same_as<
Residuals, type_list<
density::mass::residual, surface_deformation::shape_equilibrium::residual,
enthalpy::specific::residual>>);
static_assert(
std::same_as<
typename Gravity::CorrectionBlocks, type_list<gravity::gradient::value, gravity::poisson::value>>
);
static_assert(
std::same_as<
typename Gravity::ResidualBlocks, type_list<gravity::gradient::residual, gravity::poisson::residual>>
);
constexpr auto densityRow = type_index_v<density::mass::residual, Residuals>;
constexpr auto enthalpyRow = type_index_v<enthalpy::specific::residual, Residuals>;
constexpr auto shapeColumn = type_index_v<surface_deformation::parameters::value, Corrections>;
constexpr auto materialFirst = type_index_v<density::mass::value, typename Root::CorrectionBlocks>;
constexpr auto gravityFirst = type_index_v<gravity::gradient::value, typename Root::CorrectionBlocks>;
const auto communicator = problem.GetCommunicator();
if (communicator == MPI_COMM_NULL)
throw std::invalid_argument("Physical shape modes require a valid communicator.");
const auto all = [communicator](bool condition) {
int local = condition, global = 0;
if (MPI_Allreduce(&local, &global, 1, MPI_INT, MPI_MIN, communicator) != MPI_SUCCESS)
throw std::runtime_error("Could not validate collective physical shape modes.");
return global != 0;
};
if (!all(
&inverse.GetProblem() == &problem && inverse.IsCurrent() &&
problem.GetPhysicalOperator().IsPrepared() && !inverse.iterative_mode
))
throw std::logic_error("Physical shape modes require the current inverse of this problem.");
const auto generation = problem.GetPreparationGeneration();
const auto &structure = inverse.GetGroupedPreconditioner().GetStructurePreconditioner();
const auto &material = structure.GetMaterialSurfacePreconditioner();
const auto &gravityInverse = structure.GetGravityPreconditioner();
const auto &couplings = material.GetCoupledOperator();
const auto &cross = structure.GetCrossCouplings();
const auto &offsets = couplings.GetOffsets();
const auto &coordinates = inverse.GetCoordinateMap();
const auto &ranges = coordinates.GetCorrectionRanges();
const auto radial = coupled_shape_detail::MakeDefaultRadialSurface(problem);
const auto materialOffset = ranges[materialFirst].preconditionerOffset;
const auto gravityOffset = ranges[gravityFirst].preconditionerOffset;
const auto shapeSize = offsets[shapeColumn + 1] - offsets[shapeColumn];
if (!all(
radial.spatialDimension() == 3 && radial.parameterCount() == shapeSize &&
material.Height() == material.Width() && gravityInverse.Height() == gravityInverse.Width() &&
material.Height() == cross.MaterialSize() && gravityInverse.Height() == cross.GravitySize() &&
materialOffset == 0 && gravityOffset == material.Height() &&
gravityOffset + gravityInverse.Height() <= coordinates.PreconditionerCorrectionSize() &&
!material.iterative_mode && !gravityInverse.iterative_mode
))
throw std::invalid_argument("Physical shape modes require compatible radial three-dimensional blocks.");
mfem::Vector materialRhs(material.Width()), materialAction(material.Height());
mfem::Vector gravityRhs(gravityInverse.Width()), gravityAction(gravityInverse.Height());
mfem::Vector grouped(coordinates.PreconditionerCorrectionSize());
mfem::Vector shape(shapeSize);
mfem::Vector densityRhs(materialRhs, offsets[densityRow], offsets[densityRow + 1] - offsets[densityRow]);
mfem::Vector enthalpyRhs(materialRhs, offsets[enthalpyRow], offsets[enthalpyRow + 1] - offsets[enthalpyRow]);
mfem::Vector shapeAction(materialAction, offsets[shapeColumn], shapeSize);
mfem::Vector groupedMaterial(grouped, materialOffset, materialAction.Size());
mfem::Vector groupedGravity(grouped, gravityOffset, gravityAction.Size());
std::vector<mfem::Vector> result;
result.reserve(9);
for (int mode = 0; mode < 9; ++mode) {
bool finite = true;
for (int i = 0; i < shapeSize; ++i) {
const double x = radial.radialDirection(i, 0), y = radial.radialDirection(i, 1),
z = radial.radialDirection(i, 2), radius = radial.referenceRadius(i);
// All real harmonics through l=2, up to irrelevant constants.
// Their span is rotation invariant; individual columns are not
// asserted to be exact translation or homology null directions.
const std::array<double, 9> angular{1.0, x, y, z, x * y, x * z, y * z, x * x - y * y, 3 * z * z - 1};
shape(i) = radius * angular[mode];
finite = finite && std::isfinite(shape(i)) && radius > 0.0;
}
if (!all(finite))
throw std::runtime_error("A physical radial shape mode is nonfinite or has invalid radius.");
materialRhs = 0.0;
couplings.ApplySurfaceToMaterial(shape, densityRhs, enthalpyRhs);
densityRhs *= -1.0;
enthalpyRhs *= -1.0;
densityRhs.SyncAliasMemory(materialRhs);
enthalpyRhs.SyncAliasMemory(materialRhs);
// Zero shape RHS in this policy holds its returned shape at zero.
// We then restore the prescribed shape rather than solving A_qq.
material.Mult(materialRhs, materialAction);
shapeAction = shape;
shapeAction.SyncAliasMemory(materialAction);
cross.ApplyMaterialToGravity(materialAction, gravityRhs);
gravityRhs *= -1.0;
gravityInverse.Mult(gravityRhs, gravityAction);
grouped = 0.0;
groupedMaterial = materialAction;
groupedGravity = gravityAction;
groupedMaterial.SyncAliasMemory(grouped);
groupedGravity.SyncAliasMemory(grouped);
result.emplace_back(problem.StateSize());
coordinates.UnpackCorrection(grouped, result.back());
finite = true;
for (int i = 0; i < result.back().Size(); ++i)
finite = finite && std::isfinite(result.back()(i));
if (!all(finite && inverse.IsCurrent() && generation == problem.GetPreparationGeneration()))
throw std::runtime_error("Physical shape completion failed or its preparation changed.");
}
return result;
}
/*
* The caller supplies deterministic, physically completed shape directions
* before exposing a Newton RHS. With A the full normalized Jacobian, form
* V = orth(A T), U = P0 V, and A U = Q R. Then apply
*
* P r = P0 [r + (V R^-1 - Q) Q^T r].
*
* This equals U R^-1 Q^T r + P0 (I-Q Q^T)r and is exact on range(A U)
* in exact arithmetic. The P0 A filtering can change the supplied physical
* correction space; this is not an exact completed-shape Schur inverse.
*
* For stationary P0, the extra right factor is nonsingular iff Q^T V is,
* provided R is nonsingular. Orthonormal V and Q let the small overlap
* matrix expose near-orthogonal subspaces. A failed overlap check selects
* P0 explicitly; it never regularizes A or adds a physical constraint.
* Invertibility/quality of P0 itself and full-system true-defect acceptance
* remain the caller's responsibility. No solver improvement is assumed.
*/
template <CoupledCoarseNormalizedOperator Operation, CoupledCoarseStationaryInverse Inverse>
class PreparedCoupledShapeCoarse final : public mfem::Solver {
public:
static constexpr auto applicationContract = mean_field::preconditioning::ApplicationContract::stationary_linear;
static constexpr int maximumModes = 16;
PreparedCoupledShapeCoarse(
const Operation &operation,
const Inverse &inverse,
std::span<const mfem::Vector> physicalModes,
MPI_Comm communicator,
CoupledShapeCoarseOptions options = {}
)
: mfem::Solver(
operation.Width(),
operation.Height()
),
m_operation(&operation),
m_inverse(&inverse),
m_communicator(communicator),
m_options(options),
m_residualWork(operation.Height()),
m_actionWork(operation.Width()) {
Refresh(physicalModes);
}
PreparedCoupledShapeCoarse(const PreparedCoupledShapeCoarse &) = delete;
PreparedCoupledShapeCoarse &operator=(const PreparedCoupledShapeCoarse &) = delete;
PreparedCoupledShapeCoarse(PreparedCoupledShapeCoarse &&) = delete;
PreparedCoupledShapeCoarse &operator=(PreparedCoupledShapeCoarse &&) = delete;
void SetOperator(const mfem::Operator &operation) override {
if (&operation != m_operation)
throw std::invalid_argument("A coupled coarse inverse cannot bind a different Jacobian.");
RequireCurrent();
}
[[nodiscard]] bool IsCurrent() const {
return m_ready && m_operation->IsPrepared() && m_inverse->IsCurrent() && !m_inverse->iterative_mode &&
m_generation == m_operation->GetProblem().GetPreparationGeneration();
}
[[nodiscard]] bool UsesCoarseCorrection() const noexcept {
return !m_sources.empty();
}
[[nodiscard]] MPI_Comm GetCommunicator() const noexcept {
return m_communicator;
}
[[nodiscard]] const CoupledShapeCoarseStatistics &GetStatistics() const noexcept {
return m_statistics;
}
[[nodiscard]] std::span<const CoupledShapeCoarseModeReport> GetModeReports() const noexcept {
return m_reports;
}
// These normalized residual-space columns permit independent checks:
// for each v, compare P(A(P0 v)) with P0 v using the authoritative A.
[[nodiscard]] std::span<const mfem::Vector> GetSourceBasis() const noexcept {
return m_sources;
}
void Refresh(std::span<const mfem::Vector> physicalModes) {
m_ready = false;
const double start = MPI_Wtime();
ValidatePreparation(physicalModes);
m_generation = m_operation->GetProblem().GetPreparationGeneration();
m_sources.clear();
m_images.clear();
m_reports.clear();
m_sources.reserve(physicalModes.size());
m_images.reserve(physicalModes.size());
m_reports.reserve(physicalModes.size());
m_upper.fill(0.0);
m_statistics.inputModes = static_cast<int>(physicalModes.size());
m_statistics.independentModes = m_statistics.activeModes = 0;
m_statistics.sourceDependentModes = m_statistics.imageDependentModes = 0;
m_statistics.fallback = CoupledShapeCoarseFallback::none;
m_statistics.reciprocalOverlapCondition = std::numeric_limits<double>::quiet_NaN();
m_statistics.minimumOverlapLowerBound = std::numeric_limits<double>::quiet_NaN();
double operatorSeconds = 0.0, inverseSeconds = 0.0;
mfem::Vector value(Height()), source(Width()), image(Width());
for (const auto &physical : physicalModes) {
CoupledShapeCoarseModeReport report;
m_operation->NormalizeState(physical, value);
RequireFinite(value);
report.normalizedInputNorm = Norm(value);
if (report.normalizedInputNorm == 0.0) {
++m_statistics.sourceDependentModes;
m_reports.push_back(report);
continue;
}
value /= report.normalizedInputNorm;
double actionStart = MPI_Wtime();
m_operation->Mult(value, source);
operatorSeconds += MPI_Wtime() - actionStart;
++m_statistics.setupOperatorApplications;
RequireFinite(source);
report.sourceImageNorm = Norm(source);
std::array<double, maximumModes> ignored{};
Reorthogonalize(source, m_sources, ignored);
const double sourceNorm = Norm(source);
report.sourceIndependentFraction = Fraction(sourceNorm, report.sourceImageNorm);
if (sourceNorm == 0.0 || report.sourceIndependentFraction <= m_options.relativeRankTolerance) {
++m_statistics.sourceDependentModes;
m_reports.push_back(report);
continue;
}
source /= sourceNorm;
actionStart = MPI_Wtime();
m_inverse->Mult(source, value);
inverseSeconds += MPI_Wtime() - actionStart;
++m_statistics.setupInverseApplications;
RequireFinite(value);
actionStart = MPI_Wtime();
m_operation->Mult(value, image);
operatorSeconds += MPI_Wtime() - actionStart;
++m_statistics.setupOperatorApplications;
RequireFinite(image);
report.filteredImageNorm = Norm(image);
std::array<double, maximumModes> upperColumn{};
Reorthogonalize(image, m_images, upperColumn);
const double imageNorm = Norm(image);
report.filteredIndependentFraction = Fraction(imageNorm, report.filteredImageNorm);
if (imageNorm == 0.0 || report.filteredIndependentFraction <= m_options.relativeRankTolerance) {
report.status = CoupledShapeCoarseModeStatus::dependent_filtered_image;
++m_statistics.imageDependentModes;
m_reports.push_back(report);
continue;
}
const int column = static_cast<int>(m_sources.size());
for (int row = 0; row < column; ++row)
m_upper[row * maximumModes + column] = upperColumn[row];
m_upper[column * maximumModes + column] = imageNorm;
image /= imageNorm;
m_sources.emplace_back(source);
m_images.emplace_back(image);
report.status = CoupledShapeCoarseModeStatus::retained;
m_reports.push_back(report);
}
m_statistics.independentModes = static_cast<int>(m_sources.size());
if (m_sources.empty()) {
m_statistics.fallback = CoupledShapeCoarseFallback::no_independent_modes;
} else {
const auto [condition, overlap] = CheckOverlap();
m_statistics.reciprocalOverlapCondition = condition;
m_statistics.minimumOverlapLowerBound = overlap;
if (!std::isfinite(overlap) || overlap < m_options.minimumSubspaceOverlap) {
m_statistics.fallback = CoupledShapeCoarseFallback::insufficient_subspace_overlap;
m_sources.clear();
m_images.clear();
}
}
m_statistics.activeModes = static_cast<int>(m_sources.size());
// Payload bytes exclude allocator metadata and borrowed objects.
m_statistics.persistentVectorBytes =
sizeof(mfem::real_t) * (static_cast<std::size_t>(m_residualWork.Size()) + m_actionWork.Size() +
2 * m_sources.size() * static_cast<std::size_t>(Width()));
if (!All(
m_operation->IsPrepared() && m_inverse->IsCurrent() &&
m_generation == m_operation->GetProblem().GetPreparationGeneration()
))
throw std::logic_error("The coupled coarse preparation changed during setup.");
m_statistics.lastSetupOperatorSeconds = Maximum(operatorSeconds);
m_statistics.lastSetupInverseSeconds = Maximum(inverseSeconds);
m_statistics.lastSetupSeconds = Maximum(MPI_Wtime() - start);
m_statistics.totalSetupSeconds += m_statistics.lastSetupSeconds;
++m_statistics.setups;
m_ready = true;
}
void Mult(
const mfem::Vector &rightHandSide,
mfem::Vector &action
) const override {
const double start = MPI_Wtime();
++m_statistics.applications;
try {
RequireCurrent();
if (!All(rightHandSide.Size() == Width() && action.Size() == Height()))
throw std::invalid_argument("A coupled coarse application requires preallocated root vectors.");
RequireFinite(rightHandSide);
m_residualWork = rightHandSide;
const int count = static_cast<int>(m_sources.size());
if (count != 0) {
std::array<double, maximumModes> projection{}, coefficients{};
Project(rightHandSide, m_images, projection);
coefficients = projection;
for (int row = count - 1; row >= 0; --row) {
for (int column = row + 1; column < count; ++column)
coefficients[row] -= m_upper[row * maximumModes + column] * coefficients[column];
coefficients[row] /= m_upper[row * maximumModes + row];
}
for (int column = 0; column < count; ++column) {
m_residualWork.Add(coefficients[column], m_sources[column]);
m_residualWork.Add(-projection[column], m_images[column]);
}
RequireFinite(m_residualWork);
}
const double inverseStart = MPI_Wtime();
++m_statistics.inverseApplications;
m_inverse->Mult(m_residualWork, m_actionWork);
m_statistics.inverseSecondsLocal += MPI_Wtime() - inverseStart;
RequireFinite(m_actionWork);
RequireCurrent();
action = m_actionWork;
m_statistics.applicationSecondsLocal += MPI_Wtime() - start;
} catch (...) {
++m_statistics.failedApplications;
m_statistics.applicationSecondsLocal += MPI_Wtime() - start;
throw;
}
}
private:
[[nodiscard]] static double Fraction(
double independent,
double original
) {
return original == 0.0 ? 0.0 : independent / original;
}
[[nodiscard]] bool All(bool value) const {
int local = value, global = 0;
if (MPI_Allreduce(&local, &global, 1, MPI_INT, MPI_MIN, m_communicator) != MPI_SUCCESS)
throw std::runtime_error("Could not validate a collective coupled coarse operation.");
return global != 0;
}
[[nodiscard]] double Maximum(double value) const {
double result = 0.0;
if (MPI_Allreduce(&value, &result, 1, MPI_DOUBLE, MPI_MAX, m_communicator) != MPI_SUCCESS)
throw std::runtime_error("Could not measure coupled coarse setup time.");
return result;
}
void RequireCurrent() const {
if (!All(IsCurrent()))
throw std::logic_error("The coupled coarse inverse is stale; refresh its dependencies and basis.");
}
void RequireFinite(const mfem::Vector &vector) const {
bool finite = true;
for (int i = 0; i < vector.Size(); ++i)
finite = finite && std::isfinite(vector(i));
if (!All(finite))
throw std::runtime_error("A coupled coarse vector is nonfinite.");
}
[[nodiscard]] double Norm(const mfem::Vector &vector) const {
const double local = vector * vector;
double global = 0.0;
if (MPI_Allreduce(&local, &global, 1, MPI_DOUBLE, MPI_SUM, m_communicator) != MPI_SUCCESS)
throw std::runtime_error("Could not compute a coupled coarse norm.");
if (!std::isfinite(global) || global < 0.0)
throw std::runtime_error("A coupled coarse norm is nonfinite.");
return std::sqrt(global);
}
void Project(
const mfem::Vector &vector,
const std::vector<mfem::Vector> &basis,
std::array<
double,
maximumModes> &coefficients
) const {
std::array<double, maximumModes> local{};
for (std::size_t i = 0; i < basis.size(); ++i)
local[i] = basis[i] * vector;
if (MPI_Allreduce(
local.data(), coefficients.data(), static_cast<int>(basis.size()), MPI_DOUBLE, MPI_SUM,
m_communicator
) != MPI_SUCCESS)
throw std::runtime_error("Could not project a coupled coarse vector.");
for (std::size_t i = 0; i < basis.size(); ++i)
if (!std::isfinite(coefficients[i]))
throw std::runtime_error("A coupled coarse projection is nonfinite.");
}
void Reorthogonalize(
mfem::Vector &vector,
const std::vector<mfem::Vector> &basis,
std::array<
double,
maximumModes> &coefficients
) const {
for (int pass = 0; pass < 2; ++pass) {
std::array<double, maximumModes> projection{};
Project(vector, basis, projection);
for (std::size_t i = 0; i < basis.size(); ++i) {
coefficients[i] += projection[i];
vector.Add(-projection[i], basis[i]);
}
}
}
void ValidatePreparation(std::span<const mfem::Vector> modes) const {
if (m_communicator == MPI_COMM_NULL)
throw std::invalid_argument("A coupled coarse inverse requires a valid communicator.");
const int count = modes.size() <= maximumModes ? static_cast<int>(modes.size()) : maximumModes + 1;
int minimumCount = 0, maximumCount = 0;
if (MPI_Allreduce(&count, &minimumCount, 1, MPI_INT, MPI_MIN, m_communicator) != MPI_SUCCESS ||
MPI_Allreduce(&count, &maximumCount, 1, MPI_INT, MPI_MAX, m_communicator) != MPI_SUCCESS)
throw std::runtime_error("Could not compare coupled coarse mode counts.");
const std::array<double, 2> options{m_options.relativeRankTolerance, m_options.minimumSubspaceOverlap};
std::array<double, 2> minimumOptions{}, maximumOptions{};
if (MPI_Allreduce(options.data(), minimumOptions.data(), 2, MPI_DOUBLE, MPI_MIN, m_communicator) !=
MPI_SUCCESS ||
MPI_Allreduce(options.data(), maximumOptions.data(), 2, MPI_DOUBLE, MPI_MAX, m_communicator) !=
MPI_SUCCESS)
throw std::runtime_error("Could not compare coupled coarse preparation options.");
bool valid = count > 0 && count <= maximumModes && minimumCount == maximumCount &&
minimumOptions == maximumOptions && std::isfinite(options[0]) && options[0] > 0.0 &&
options[0] < 1.0 && std::isfinite(options[1]) && options[1] > 0.0 && options[1] < 1.0 &&
m_operation->IsPrepared() && m_inverse->IsCurrent() && !m_inverse->iterative_mode &&
m_operation->Height() == m_operation->Width() && m_inverse->Height() == Height() &&
m_inverse->Width() == Width();
if constexpr (requires { m_inverse->GetNormalizedJacobian(); })
valid = valid && &m_inverse->GetNormalizedJacobian() == m_operation;
if (!All(valid))
throw std::invalid_argument(
"Coupled coarse setup needs current compatible objects and common valid options."
);
const long long localSize = Width();
long long globalSize = 0;
if (MPI_Allreduce(&localSize, &globalSize, 1, MPI_LONG_LONG, MPI_SUM, m_communicator) != MPI_SUCCESS ||
globalSize <= 0)
throw std::invalid_argument("A coupled coarse system must be globally nonempty.");
for (const auto &mode : modes) {
if (!All(mode.Size() == Height()))
throw std::invalid_argument("Coupled coarse modes must use complete physical root coordinates.");
RequireFinite(mode);
}
}
[[nodiscard]] std::pair<
double,
double>
CheckOverlap() const {
const int count = static_cast<int>(m_sources.size());
std::array<double, maximumModes * maximumModes> local{}, matrix{}, inverse{};
for (int row = 0; row < count; ++row)
for (int column = 0; column < count; ++column)
local[row * count + column] = m_images[row] * m_sources[column];
if (MPI_Allreduce(local.data(), matrix.data(), count * count, MPI_DOUBLE, MPI_SUM, m_communicator) !=
MPI_SUCCESS)
throw std::runtime_error("Could not assemble the coupled coarse overlap matrix.");
for (int index = 0; index < count * count; ++index)
if (!std::isfinite(matrix[index]))
return {0.0, 0.0};
double norm = 0.0;
for (int row = 0; row < count; ++row) {
inverse[row * count + row] = 1.0;
double sum = 0.0;
for (int column = 0; column < count; ++column)
sum += std::abs(matrix[row * count + column]);
norm = std::max(norm, sum);
}
if (!std::isfinite(norm) || norm == 0.0)
return {0.0, 0.0};
for (int column = 0; column < count; ++column) {
int pivot = column;
for (int row = column + 1; row < count; ++row)
if (std::abs(matrix[row * count + column]) > std::abs(matrix[pivot * count + column]))
pivot = row;
if (!std::isfinite(matrix[pivot * count + column]) ||
std::abs(matrix[pivot * count + column]) <= std::numeric_limits<double>::epsilon() * count * norm)
return {0.0, 0.0};
for (int j = 0; j < count; ++j) {
std::swap(matrix[column * count + j], matrix[pivot * count + j]);
std::swap(inverse[column * count + j], inverse[pivot * count + j]);
}
const double diagonal = matrix[column * count + column];
for (int j = 0; j < count; ++j) {
matrix[column * count + j] /= diagonal;
inverse[column * count + j] /= diagonal;
}
for (int row = 0; row < count; ++row)
if (row != column) {
const double factor = matrix[row * count + column];
for (int j = 0; j < count; ++j) {
matrix[row * count + j] -= factor * matrix[column * count + j];
inverse[row * count + j] -= factor * inverse[column * count + j];
}
}
}
double inverseOne = 0.0, inverseInfinity = 0.0;
for (int index = 0; index < count * count; ++index)
if (!std::isfinite(inverse[index]))
return {0.0, 0.0};
for (int i = 0; i < count; ++i) {
double rowSum = 0.0, columnSum = 0.0;
for (int j = 0; j < count; ++j) {
rowSum += std::abs(inverse[i * count + j]);
columnSum += std::abs(inverse[j * count + i]);
}
inverseInfinity = std::max(inverseInfinity, rowSum);
inverseOne = std::max(inverseOne, columnSum);
}
if (!std::isfinite(inverseOne) || !std::isfinite(inverseInfinity))
return {0.0, 0.0};
// Condition number alone misses epsilon*I. Since ||S^-1||_2 is
// bounded by sqrt(||S^-1||_1 ||S^-1||_inf), this also checks the
// absolute overlap of the two orthonormal subspaces. The computed
// inverse supplies a floating-point estimate, not an interval proof.
return {1.0 / (norm * inverseInfinity), (1.0 / std::sqrt(inverseOne)) / std::sqrt(inverseInfinity)};
}
const Operation *m_operation;
const Inverse *m_inverse;
MPI_Comm m_communicator;
CoupledShapeCoarseOptions m_options;
std::uint64_t m_generation{0};
bool m_ready{false};
std::vector<mfem::Vector> m_sources, m_images;
std::vector<CoupledShapeCoarseModeReport> m_reports;
std::array<double, maximumModes * maximumModes> m_upper{};
mutable mfem::Vector m_residualWork, m_actionWork;
mutable CoupledShapeCoarseStatistics m_statistics;
};
} // namespace experiment::plateau_diagnostics

Some files were not shown because too many files have changed in this diff Show More