Skip to content

Add Zhong 2008 propagator-matrix analytic response - #594

Open
gthyagi wants to merge 5 commits into
underworldcode:developmentfrom
gthyagi:feature/zhong2008-analytic
Open

Add Zhong 2008 propagator-matrix analytic response#594
gthyagi wants to merge 5 commits into
underworldcode:developmentfrom
gthyagi:feature/zhong2008-analytic

Conversation

@gthyagi

Copy link
Copy Markdown
Contributor

Dependency

This is a stacked PR on top of #591, which adds the generic
uw.postprocessing.geoid coefficient API. The Zhong oracle calls those pure
functions rather than carrying a second geoid/self-gravity implementation.

Until #591 merges, this comparison also shows its three commits. After #591
merges into development, the remaining diff is the two commits
95b34701 and fb9ce95b.

What this adds

uw.analytic.Zhong2008 is a mesh-independent semi-analytical reference for the
spherical-shell delta-load Stokes benchmarks in Zhong et al. (2008).

For one harmonic degree l, it:

  • propagates the four-component Hager--O'Connell poloidal state in
    v = log(r) with an exact matrix exponential in each constant-viscosity
    layer;
  • accepts arbitrary piecewise-constant radial viscosity profiles;
  • applies the radial delta load as the traction-state jump
    (0, 0, -rint * load, 0);
  • solves the two remaining CMB state coefficients from impermeable free slip
    (radial velocity = tangential traction = 0) at both shell boundaries;
  • returns no-self-gravity topography/geoid, signed characteristic horizontal
    velocity, and horizontal velocity divergence at the surface and CMB;
  • returns self-gravity-corrected topography/geoid through the generic API from
    Add generic spherical-shell geoid and self-gravity postprocessing #591.

This is intentionally a numeric response oracle rather than an
AnalyticSolution(mesh): the paper publishes boundary response coefficients,
not pointwise symbolic velocity/pressure fields. It is exported from
uw.analytic but is not registered by available(), whose contract requires a
mesh-constructible symbolic solution.

Radial system

With L = l(l + 1) and state

u = (y1, y2, r sigma_rr / eta0, r sigma_r_perp / eta0)^T,

the constant-layer system is

du/dv = A u
[ -2 L 0 0 ]
[ -1 1 0 1/eta ]
A = [ 12 eta -6 L eta 1 L ]
[ -6 eta 2(2L-1) eta -1 -2 ]

and u(rb) = exp(A log(rb / ra)) u(ra).

API example

reference=uw.analytic.Zhong2008(
harmonic_degree=2,
radius_inner=0.55,
radius_outer=1.0,
internal_load_radius=0.775,
).response()
reference.surface_characteristic_velocityreference.self_gravity.surface_topography

The layered Table 3 case is selected with:

viscosity_interfaces=(0.971875,)
viscosities=(1.0, 1.0e4)

Published-reference validation

The focused test checks every parenthesized propagator entry in Zhong et al.
(2008) Tables 2 and 3:

CasesDepthsDegreesQuantities per casePublished values
Isoviscous0.25d, 0.5d, 0.75d2, 5, 8, 15896
10^4 viscosity lid0.25d, 0.5d, 0.75d2, 5, 8, 15896

All 192 values agree within the precision printed in the paper. Additional
tests cover both free-slip boundary states, response linearity in load
amplitude, no-self-gravity recovery, input validation, and public API behavior.

Representative degree-2, mid-mantle responses:

Casesbh_th_bU_tU_b
Isoviscous oracle0.4998490.9312600.04486290.0546149-0.01006410.0118606
Paper0.49980.93130.044860.05461-0.010060.01186
Layered oracle0.6103740.4353760.05789260.00675446-1.25811e-050.00555605
Paper0.61040.43540.057890.006754-1.258e-050.005556

Checks

  • python -m pytest tests/test_1029_analytic_zhong2008.py -v:
    34 passed
  • analytic contract/optional/oracle group: 66 passed, 15 skipped
  • ./uw test Level 1: 1476 passed, 49 skipped, 2 xfailed
  • documentation audit still exits on the repository-wide baseline of 138
    undocumented API items; it reports no new missing Zhong API item.

Review focus

Please check:

  1. the four-state matrix and traction scaling against the intended
    Hager--O'Connell convention;
  2. the sign and rint factor in the delta-load jump;
  3. whether a mesh-independent response oracle should remain directly exported
    but outside the symbolic available() registry;
  4. the constructor representation of radial viscosity interfaces.

References

  • Hager & O'Connell (1981), JGR 86, 4843--4878,
    doi:10.1029/JB086iB06p04843.
  • Zhong et al. (2008), G3 9, Q10017, doi:10.1029/2008GC002048.

Add pure Appendix A no-self-gravity and self-gravity response operators with explicit internal-load scaling, density-contrast naming, dimensional constant documentation, and harmonic-degree validation.
Provide a rotated-Stokes adapter that delegates normal-traction recovery to the existing Stokes.boundary_normal_traction API, projects only the requested P_l^0 response, and avoids duplicate CBF, constrained, or dynamic-topography implementations.
Keep the feature in uw.postprocessing rather than adding a Zhong-specific facade to the generic Stokes solver. Add focused formula, serial end-to-end, and two/four-rank MPI validation.
Move the public API under uw.postprocessing.geoid and remove Zhong-specific names from the reusable response data types and coefficient functions.
Support two-boundary shells with an optional internal load, require model-specific density and gravity inputs explicitly, and retain a focused rotated-free-slip adapter for recovering axisymmetric topography coefficients.
Rename the MPI regression, add no-load and parameter-validation coverage, and update developer documentation to distinguish generic postprocessing from a future semi-analytical propagator solver in uw.analytic.
Allow the generic spherical-shell coefficient functions to evaluate the degree-zero radial potential while keeping the rotated-Stokes adapter at degree one or greater because boundary normal traction recovery removes its mean.
Add focused degree-zero formula and adapter validation tests and document the distinction.
Implement a mesh-independent uw.analytic.Zhong2008 oracle for the spherical-shell delta-load Stokes benchmark. The solver propagates the Hager-O'Connell four-state poloidal system through arbitrary piecewise-constant radial viscosity layers, enforces impermeable free slip at the CMB and surface, and applies the internal load as a radial-traction jump.
Recover no-self-gravity topography, characteristic velocity, and boundary velocity divergence directly from the solved states. Delegate geoid and self-gravity feedback to the generic spherical-shell postprocessing API, using the physical constants published by Zhong et al. as configurable defaults.
Add Level 2 regression coverage for all 96 parenthesized analytic quantities in Zhong et al. Tables 2 and 3, plus boundary-condition, load-linearity, validation, and public-API tests. Focused analytic tests pass: 66 passed and 15 optional-assess tests skipped.
Describe the four-state Hager-O'Connell radial system, matrix exponential transfer, viscosity-interface continuity, delta-load stress jump, and free-slip boundary solve used by uw.analytic.Zhong2008.
Document the distinction between no-self-gravity outputs and the nested Zhong Table 2/3 self-gravity response, show isoviscous and layered usage, and record the complete 192-value published-table regression coverage. Add the oracle to the public analytic API documentation and developer changelog.
@gthyagi
gthyagi marked this pull request as ready for review August 16, 2026 17:44
@gthyagi
gthyagi requested a review from lmoresi as a code ownerAugust 16, 2026 17:44
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

@gthyagi