Yin-Yang Schwarz coupling

The 3-D shell is covered by two identical patches, Yin and Yang, each a latitude-longitude block of the sphere (see Yin-Yang grid for the geometry and the coordinate transforms). Each patch has its own Stokes matrix. MILEVA does not assemble one global matrix for the shell; it solves the two patches separately and couples them through their walls by an overlapping Schwarz iteration, the coupling used for Yin-Yang mantle convection by Kageyama and Sato (2004) and Tackley (2008).

One Schwarz round

multigrid_stokes(::MutableGrid3D, ETA, buoy, cfg; n_schwarz, buoy_yang) keeps a current solution $(V_r,V_{\theta },V_{\phi },P)$ for each patch and runs n_schwarz rounds (default 5; the time loop uses the default). Each round:

1. Yang to Yin. yy_compute_th_bcs samples Yang's current velocity at the positions Yin's $\theta$-walls need and rotates the tangential components into Yin's local basis. The result is Dirichlet values for $V_{\theta }$ on Yin's wall faces and ghost values for $V_r$ and $V_{\phi }$ next to them.

2. Solve Yin. Only the right-hand side depends on those values, so it is rebuilt with assemble_stokes_3d(...; rhs_only = true) and Yin is solved with FGMRES and the multigrid preconditioner of Geometric multigrid. The matrix, its Galerkin hierarchy and the coarse factor are built once per call and reused by every round.

3. Yin to Yang. The same is done for Yang, from the new Yin solution.

4. Measure. The Schwarz residual is the largest change of any Yin velocity component over the round, divided by the largest velocity, and is appended to info.schwarz_residuals.

The Yin solution is returned as the primary field and Yang's in info.yang. Interpolation between patches is bilinear in $(\theta ,\phi )$ at each radius (_bilinear_sample_3d).

Schwarz residual per round for one Yin-Yang shell at $N_r=N_{\theta }=12$, $N_{\phi }=36$, two multigrid levels, FGMRES tolerance ${10}^{-6}$, for an isoviscous shell and a mid-depth viscosity step of ${10}^6$. Script: docs/scripts/solvers_3d.jl.

On this grid the residual falls by nearly three orders of magnitude in the first three or four rounds, to $5\times {10}^{-4}$ for the isoviscous shell and $2\times {10}^{-4}$ with the ${10}^6$ step. Further rounds do not improve it: the change between rounds grows again and levels off near 0.8 after about ten rounds. Tightening the FGMRES tolerance to ${10}^{-10}$ gives the same history, so the growth comes from the exchange between the patches, not from the inner solves. The default of five rounds stops close to the minimum.

Which walls are coupled

On the multigrid path only the $\theta$-walls are Schwarz-coupled. On the equator, Yin's $\phi$-wall maps onto Yang's $\theta$-wall rather than into Yang's interior, so a $\phi$-wall exchange (yy_compute_ph_bcs) would feed one wall from the other; it exists and is used by the single-level direct path.

Halo shift. Sampling the peer exactly at the ghost position does not contract: near the corners of the overlap that position lies on or next to the peer's own wall. yy_compute_th_bcs therefore samples the peer a fixed 30° of arc past the destination wall, $max(2,(\pi /6)/\mathrm{\Delta }\theta )$ cells (4 cells at $N_{\theta }$ = 12, 8 at 24), which lands the sample in the peer's interior and keeps the residual decreasing as the grid is refined. The Yin-Yang grid page discusses the consequences for the seam.

(A) The walls of both patches in global coordinates, from MILEVA's yy_yang_to_yin. Yin is the band of latitudes ±45° over longitudes ±135°; the Yang walls lie inside it, and the patches overlap between the two outlines. On the equator (circles) Yin's $\phi$-wall touches Yang's $\theta$-wall, so the two walls meet without overlap there. (B) Where Yin's lower $\theta$-wall takes its values from, in Yang's own $({\theta }^{\prime },{\phi }^{\prime })$, for $N_{\theta }=12$ (yy_yin_to_yang): the geometric ghost positions (grey) lie on the edge of Yang's patch, while the positions shifted by $max(2,(\pi /6)/\mathrm{\Delta }\theta )=4$ cells, as in yy_compute_th_bcs, lie well inside it (blue). Script: docs/scripts/solvers_yinyang_schwarz_sections.jl.

Fixed round count

The Schwarz loop runs a fixed number of rounds with no tolerance test, and more rounds are not always better (figure above). The residuals are written to the log at the log cadence ([stokes 3-D] lines); check that they still fall at the last round before changing n_schwarz or the resolution.

Temperature

The energy equation is coupled the same way with fewer steps. In the time loop yy_compute_T_wall_bcs samples the peer temperature at each patch's $\theta$-wall faces, both patches are re-diffused with those Dirichlet values cfg.nTSchwarz times per step (default 3), and yy_sync_T_walls! then overwrites each patch's wall-cell row with the peer value at that cell centre. See Energy equation.

Temperature at mid-depth along longitude 50°, where the patches overlap from 33° to 45° N (shaded where both have cell centres), after 60 explicit conduction steps (2.7 Gyr) on a shell with $N_r=N_{\theta }=12$, $N_{\phi }=36$. Both patches start from the same field with a 300 K anomaly at 40° N in the overlap. (A) Diffused alone with insulated $\theta$-walls, heat piles up against Yin's wall and the two patches differ by 37 K in the overlap. (B) With the exchange of the time loop (yy_compute_T_wall_bcs, cfg.nTSchwarz = 3, yy_sync_T_walls!) the difference falls to 6 K on this coarse grid. Script: docs/scripts/solvers_yinyang_schwarz_sections.jl.

Where in the code

Topic	File	Function
Schwarz loop	solvers/multigrid_stokes.jl	multigrid_stokes(::MutableGrid3D, ...)
Wall values from the peer	utils/yy_interp.jl	yy_compute_th_bcs, yy_compute_ph_bcs, _bilinear_sample_3d
Vector rotation	utils/yy_interp.jl	yy_rotation_yin_to_yang, yy_rotation_yang_to_yin
Temperature coupling	utils/yy_interp.jl	yy_compute_T_wall_bcs, yy_sync_T_walls!
Two-rank version	solvers/multigrid_stokes_mpi.jl	multigrid_stokes_mpi! (see Parallel solvers)
Tests	tests/	test_yy_rotation_vs_ks2004.jl, test_yinyang_phi_coupling_ab.jl, smoke_stokes_3d_mg.jl

References

• Kageyama, A. and Sato, T. (2004), "Yin-Yang grid": an overset grid in spherical geometry, Geochem. Geophys. Geosyst. 5, Q09005.

• Tackley, P. J. (2008), Modelling compressible mantle convection with large viscosity contrasts in a three-dimensional spherical shell using the yin-yang grid, Phys. Earth Planet. Inter. 171, 7-18.