From d8ef54eaaf5b49fc06dfbeea6799a0c206f77841 Mon Sep 17 00:00:00 2001 From: Anthony Craig Date: Thu, 20 Aug 2020 08:42:16 -0700 Subject: [PATCH] add initial Mapping and Merger Primer and Area Corrections sections --- doc/source/CMEPS-grid1.png | Bin 0 -> 11651 bytes doc/source/CMEPS-grid2.png | Bin 0 -> 6924 bytes doc/source/CMEPS-grid3.png | Bin 0 -> 73445 bytes doc/source/introduction.rst | 338 ++++++++++++++++++++++++++++++++++++ 4 files changed, 338 insertions(+) create mode 100644 doc/source/CMEPS-grid1.png create mode 100644 doc/source/CMEPS-grid2.png create mode 100644 doc/source/CMEPS-grid3.png diff --git a/doc/source/CMEPS-grid1.png b/doc/source/CMEPS-grid1.png new file mode 100644 index 0000000000000000000000000000000000000000..fab0ab0a83787bb825dbc21ce14cc7b35421771f GIT binary patch literal 11651 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 pejQu5tn}-wEKfocd%`<&FRY?df=6W2)BN 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

fT#-6@G52Nrn6zPb*A0~=rAMyd6Ai4=#$b2 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%0DWA=lsHF*BrjZkm<0IMwG&YYG)!YrV`$c%3a6 zti9P%^k|~*L&;M1bE)qMqoyzKlyhF(J+dr-{4n8uOskACX5*kjkSY2ytV~Dt&jfWR_WIK(|1pH&-0sYuT2_U zTFscHOUYpB7bLP$WBQ9{B&6QI=b9WMy-8pI36{rMlJLje#o_p{#b`YrsY%O|%`^G9 z<4o)D)l5oJ{L`NcJm3UP&l4GzX;YAVL5xZPy|X2G#EdYv{@$6lrgS^bewsl6IOxbI z^mk#KCSKp^MTTPshSCxATuRXb&mYII>d~AH+`Rpa3=>S$4sL+fdDBt@n9dd))KGLp zD&)1@ip~!FoPPBJSDuzg02>A&n`$_w&6sH5xq*i7Cb5GA1EC}p35vAnPQvkSjQ(_3 zdQNB5e`fI8H3FFp2^MyvEkw*sNrbK11_e$@(QsWoE$(W(854=b+(wBjfX~PFG2Go9 zZQ)oHmj_v!Z=Z0_dCaqF7Ph%2CZogWQEI#5;DM`F6~!JzO(ZyT2C=Myw}3PWSS!Sl zvm2Fw1o15G#c4YGm}Sm_uyFX%(14yin-fxPKy9(7aX;hX5O{oKyt-;UC7l8)7&wqu zeUTVYkgzn=FX%jAoP=5;@%mH)SlGHbF|r0I>^5+P8*beI%hVM~)PUY81Wyncqk_UC z5HE;o`2Z0@xTZy8Xtdt4kb;kLErBbz_ls2j3zc=&gMdwbK@lkGl|3*BfQ<-i2bA>C za*t#X`i;&XA47FXm6sJ@ovUc?RI^+uq8IH{8je(C;SD)-S`-J>4ncV?5_mq@#bnEc zor1tdV8TXn<9`iZkog0#+z}~puX5CSMTJyfD&rg))265cG_Fvf+M39rtCXPwc@~&} zu^wYRHtS(&Vgd)G2_|sTF#8x16Wm> zqB7w|Hys78>xDeAkUhGt$D14KjGp_NudEaG3=O6l=Yb(Vki9$h!TbVm&3-H6?;f(f z+H4@M{+FSZ!=_DepW5h!?P8I&ZPam~(RsQ3qRDg-`jwVx zLD(RitWm4V6%Wi>~HwAYdvo$Th7U&>xo0A#GVzd;Q(Yc_5Ic-&VgB&h?{5P*z7QdXz~ zRU}EYt}7=^9jI0VQ>*QD(Xm|aB4GYH1gIuOzLH~o1$FA1S`Sof?Kok|F_6uU8UU)B zm^k%D)&f-;%VbgRXID@U0<<0!MNm-#P(INR9bx?5n6Y}V5GMF?6k{WQ=tQXQp;LH@ zdSwrcU|>St1AaTacX`!&hM)QukySur literal 0 HcmV?d00001 diff --git a/doc/source/introduction.rst b/doc/source/introduction.rst index 2032d865f..80c160cac 100644 --- a/doc/source/introduction.rst +++ b/doc/source/introduction.rst @@ -73,3 +73,341 @@ med_utils_mod.F90 =========================== ============================ =========================== .. note:: Some modules, such as med_phases_prep_ocn.F90 and med_frac_mod.F90 also contain application specific-code blocks. + +Mapping and Merging Primer +####################################### + +This section provides a primer on mapping (interpolation) and merging of gridded +coupled fields. Masks, support for partial fractions on grids, weights generation, +and fraction +weighted mapping and merging all play roles in the conservation and quality of the +coupled fields. + +A pair of atmosphere and ocean/ice grids can be used to highlight the analysis. + +.. image:: CMEPS-grid1.png + :width: 400 + :alt: Sample CMEPS grids + +The most general CMEPS mediator assumes the ocean and sea ice surface grids are +identical while the atmosphere and land grids are also identical. The ocean/ice +grid defines the mask which means each ocean/ice gridcell is either a fully +active ocean/ice gridcell or not (i.e. land). Other configurations have been +and can be implemented and analyzed as well. + +The ocean/ice mask interpolated to the atmosphere/land grid +determines the complementary ocean/ice and land masks on the atmosphere grid. +The land model supports partially active gridcells such that each atmosphere +gridcell may contain a fraction of land, ocean, and sea ice. + +Focusing on a single atmosphere grid cell. + +.. image:: CMEPS-grid2.png + :width: 400 + :alt: Sample CMEPS gridcell overlap + +The gridcells can be labeled as follows. + +.. image:: CMEPS-grid3.png + :width: 300 + :alt: Sample CMEPS gridcell naming convention + +The atmosphere gridcell is labeled "a". On the atmosphere gridcell (the red box), +in general, +there is a land fraction (fal), an ocean fraction (fao), and a sea ice fraction +(fai). The sum of the surface fractions should always be 1.0 in these +conventions. There is also a gridbox average field on the atmosphere grid (Fa). +This could be a flux or a state that is +derived from the equivalent land (Fal), ocean (Fao), and sea ice (Fai) fields. +The gridbox average field is computed by merging the various surfaces:: + + Fa = fal*Fal + fao*Fao + fai*Fai + +This is a standard merge where:: + + fal + fao + fai = 1.0 + +and each surface field, Fal, Fao, and Fai are the values of the surface fields +on the atmosphere grid. + +The ocean gridcells (blue boxes) are labeled 1, 2, 3, and 4 in this example. +In general, +each ocean/ice gridcell partially overlaps multiple atmosphere gridcells. +Each ocean/ice gridcell has an overlapping Area (A) and a Mask (M) associated with it. +In this example, land is colored green, ocean blue, and sea ice white so just for +the figure depicted:: + + M1 = 0 + M2 = M3 = M4 = 1 + +Again, the ocean/ice areas (A) are overlapping areas so the sum of the overlapping +areas is equal to the atmophere area:: + + Aa = A1 + A2 + A3 + A4 + +The mapping weight (w) defined in this example allows a field on the ocean/ice +grid to be interpolated to the atmosphere/land grid. The mapping weights can +be constructed to be conservative, bilinear, bicubic, or with many other +approaches. The main point is that the weights represent a linear sparse matrix +such that in general:: + + Xa = [W] * Xo + +where Xa and Xo represent the vector of atmophere and ocean gridcells respectively, +and W is the sparse matrix weights linking each ocean gridcell to a set of atmosphere +gridcells. Nonlinear interpolation is not yet supported in most coupled systems. + +Mapping weights can be defined in a number of ways even beyond conservative +or bilinear. They can be masked or normalized using multiple approaches. The +weights generation is intricately tied to other aspects of the coupling method. +In CMEPS, area-overlap conservative weights are defined as follows:: + + w1 = A1/Aa + w2 = A2/Aa + w3 = A3/Aa + w4 = A4/Aa + +This simple approach which does not include any masking or normalization provides a +number of useful attributes. The weights always add up to 1.0:: + + w1 + w2 + w3 + w4 = 1.0 + +and a general area weighted average of fields on the ocean/ice grid mapped to +the atmosphere grid would be:: + + Fa = w1*F1 + w2*F2 + w3*F3 + w4*F4 + +These weights conserve area:: + + w1*Aa + w2*Aa + w3*Aa + w4*Aa = Aa + +and can be used to interpolate the ocean/ice mask to the atmosphere grid to compute +the land fraction:: + + f_ocean = w1*M1 + w2*M2 + w3*M3 + w4*M4 + f_land = (1-f_ocean) + +These weights also can be used to interpolate surface fractions:: + + fal = w1*fl1 + w2*fl2 + w3*fl3 + w4*fl4 + fao = w1*fo1 + w2*fo2 + w3*fo3 + w4*fo4 + fai = w1*fi1 + w2*fi2 + w3*fi3 + w4*fi4 + +Checking sums:: + + fal + fao + fai = w1*(fl1+fo1+fi1) + w2*(fl2+fo2+fi2) + w3*(fl3+fo3+fi3) + w4*(fl4+fo4+fi4) + fal + fao + fai = w1 + w2 + w3 + w4 = 1.0 + +And the equation for f_land and fal above are consistent if fl_n is defined as 1-M_n:: + + f_land = 1 - f_ocean + f_land = 1 - (w1*M1 + w2*M2 + w3*M3 + w4*M4) + + fal = w1*(1-M1) + w2*(1-M2) + w3*(1-M3) + w4*(1-M4) + fal = w1 + w2 + w3 + w4 - (w1*M1 + w2*M2 + w3*M3 + w4*M4) + fal = 1 - (w1*M1 + w2*M2 + w3*M3 + w4*M4) + +Clearly defined and consistent weights, areas, fractions, and masks is critical +to generating conservation in the system. + +When mapping masked or fraction weighted fields, these weights require that the +mapped field be normalized by the mapped fraction. Consider a case where sea +surface temperature (SST) is to be mapped to the atmosphere grid with:: + + M1 = 0; M2 = M3 = M4 = 1 + w1, w2, w3, w4 are defined as above A_n/Aa + +There are a number of ways to compute the mapped field. The direct weighted +average equation, Fa = w1*Fo1 + w2*Fo2 + w3*Fo3 + w4*Fo4, is ill-defined +because w1 is non-zero and Fo1 is underfined since it's a land gridcell +on the ocean grid. A masked weighted average, +Fa = M1*w1*Fo1 + M2*w2*Fo2 + M3*w3*Fo3 + M4*w4*Fo4 is also problematic. +Because M1 is zero, the contribution of the first term is zero. But the sum +of the remaining weights (M2*w2 + M3*w3 + M4*w4) is now not identically 1 +which means the weighted average is incorrect. (To test this, assume all the +weights are each 0.25 and all the Fo values are 10 degC, Fa would then be 7.5 degC). +Next consider a masked weighted normalized average, +f_ocean = (w1*M1 + w2*M2 + w3*M3 + w4*M4) and +Fa = (M1*w1*Fo1 + M2*w2*Fo2 + M3*w3*Fo3 + M4*w4*Fo4) / (f_ocean). +This produces a reasonable result because the weighted average of the ocean +SST is normalized by the weighted mask. But in practice, this only works +in cases where there is no sea ice because sea ice impacts the surface fractions. +Finally, consider +a fraction weighted normalized average using the dynamically varying +ocean fraction that is exposed to the atmosphere:: + + fo_n = 1 - fi_n + fao = w1*fo1 + w2*fo2 + w3*fo3 + w4*fo4 + Fao = (fo1*w1*Fo1 + fo2*w2*Fo2 + fo3*w3*Fo3 + fo4*w4*Fo4) / (fao) + +where fo1, fo2, fo3, and fo4 are the ocean fractions on the ocean gridcells +and depend on the sea ice fraction, +fao is the mapped ocean fraction on the atmosphere gridcell, and Fa +is the mapped SST. The ocean fractions are only defined where the ocean +mask is 1, otherwise the ocean and sea ice fractions are zero. +Now, the SST in each ocean gridcell is weighted by the fraction of the ocean +box exposed to the atmosphere and that weighted average is normalized by +the mapped dynamically varying fraction. This produces a reasonable result +as well as a conservative result. + +The conservation check involves thinking of Fo and Fa as a flux. On the +ocean grid, the quantity associated with the flux is:: + + Qo = (Fo1*fo1*A1 + Fo2*fo2*A2 + Fo3*fo3*A3 + Fo4*fo4*A4) * dt + +on the atmosphere grid, that quantity is the ocean fraction times the mapped +flux times the area times the timestep:: + + Qa = foa * Fao * Aa * dt + +Via some simple math, it can be shown that Qo = Qa if:: + + fao = w1*fo1 + w2*fo2 + w3*fo3 + w4*fo4 + Fao = (fo1*w1*Fo1 + fo2*w2*Fo2 + fo3*w3*Fo3 + fo4*w4*Fo4) / (fao) + +In practice, the fraction weighted normlized mapping field is computed +by mapping the ocean fraction and the fraction +weighted field from the ocean to the atmosphere grid separately and then +using the mapped fraction to normalize the field as a four step process:: + + Fo' = fo*Fo (a) + fao = w1*fo1 + w2*fo2 + w3*fo3 + w4*fo4 (b) + Fao' = w1*Fo1' + w2*Fo2' + w3*Fo3' + w4*Fo4' (c) + Fao = Fao'/fao (d) + +Steps (b) and (c) above are the sparse matrix multiply by the standard +conservative weights. +Step (a) fraction weighs the field and step (d) normalizes the mapped field. + +Another way to think of this is that the mapped flux (Fao') is normalized by the +same fraction (fao) that is used in the merge, so they actually cancel. +Both the normalization at the end of the mapping and the fraction weighting +in the merge can be skipped and the results should be identical. But then the mediator +will carry around Fao' instead of Fao and that field is far less intuitive +as it no longer represents the gridcell average value, but some subarea average +value. +In addition, that approach is only valid when carrying out full surface merges. If, +for instance, the SST is to be interpolated and not merged with anything, the field +must be normalized after mapping to be useful. + +The same mapping and merging process is valid for the sea ice:: + + fai = w1*fi1 + w2*fi2 + w3*fi3 + w4*fi4 + Fai = (fi1*w1*Fi1 + fi2*w2*Fi2 + fi3*w3*Fi3 + fi4*w4*Fi4) / (fai) + +Putting this together with the original merge equation:: + + Fa = fal*Fal + fao*Fao + fai*Fai + +where now:: + + fal = 1 - (fao+fai) + fao = w1*fo1 + w2*fo2 + w3*fo3 + w4*fo4 + fai = w1*fi1 + w2*fi2 + w3*fi3 + w4*fi4 + Fal = Fl1 = Fl2 = Fl3 = Fl4 as defined by the land model on the atm grid + Fao = (fo1*w1*Fo1 + fo2*w2*Fo2 + fo3*w3*Fo3 + fo4*w4*Fo4) / (fao) + Fai = (fi1*w1*Fi1 + fi2*w2*Fi2 + fi3*w3*Fi3 + fi4*w4*Fi4) / (fai) + +will simplify to an equation that contains twelve distinct terms for each of the +four ocean gridboxes and the three different surfaces:: + + Fa = (w1*fl1*Fl1 + w2*fl2*Fl2 + w3*fl3*Fl3 + w4*fl4*Fl4) + + (w1*fo1*Fo1 + w2*fo2*Fo2 + w3*fo3*Fo3 + w4*fo4*Fo4) + + (w1*fi1*Fi1 + w2*fi2*Fi2 + w3*fi3*Fi3 + w4*fi4*Fi4) + +and this further simplifies to something that looks like a mapping +of the field merged on the ocean grid:: + + Fa = w1*(fl1*Fl1+fo1*Fo1+fi1*Fi1) + + w2*(fl2*Fl2+fo2*Fo2+fi2*Fi2) + + w3*(fl3*Fl3+fo3*Fo3+fi3*Fi3) + + w4*(fl4*Fl4+fo4*Fo4+fi4*Fi4) + +Like the exercise with Fao above, these equations can be shown to be +fully conservative. + +To summarize, multiple features such as area calculations, +weights, masking, normalization, fraction weighting, and merging approaches +have to be considered together to ensure conservation. The CMEPS mediator +uses unmasked and unnormalized weights and then generally +maps using the fraction weighted normalized approach. Merges are carried +out with fraction weights. +This is applied to both state and flux fields, with conservative, bilinear, +and other mapping approaches, and for both merged and unmerged fields. +This ensures that the fields are always useful gridcell average values +when being coupled or analyzed throughout the coupling implementation. + + +Area Corrections +####################################### + +Area corrections are generally necessary when coupling fluxes between different +component models if conservation is important. The area corrections adjust +the fluxes such that the quantity is conserved between different models. The +area corrections are necessary because different model usually compute gridcell +areas using different approaches. These approaches are inherently part of the +model discretization, they are NOT ad-hoc. + +If the previous section, areas and weights were introduced. Those areas +were assumed to consist of the area overlaps between gridcells and were computed +using a consistent approach such that the areas conserve. ESMF is able to compute +these area overlaps and the corresponding mapping weights such that fluxes can +be mapped and quantities are conserved. + +However, the ESMF areas don't necessarily agree with the model areas that are inherently +computed in the individual component models. As a result, the fluxes need to +be corrected by the ratio of the model areas and the ESMF areas. Consider a +simple configuration where two grids are identical, the areas computed by +ESMF are identical, and all the weights are 1.0. So:: + + A1 = A2 (from ESMF) + w1 = 1.0 (from ESMF) + F2 = w1*F1 (mapping) + F2*A2 = F1*A1 (conservation) + +Now lets assume that the two models have fundamentally different discretizations, +different area algorithms (i.e. great circle vs simpler lon/lat approximations), +or even different +assumptions about the size and shape of the earth. The grids can be identical in +terms of the longitude and latitude of the +gridcell corners and centers, but the areas can also +be different because of the underlying model implementation. When a flux is passed +to or from each component, the quantity associated with that flux is proportional to +the model area, so:: + + A1 = A2 (ESMF areas) + w1 = 1.0 + F2 = w1*F1 (mapping) + F2 = F1 + A1m != A2m (model areas) + F1*A1m != F2*A2m (loss of conservation) + +This can be corrected by multiplying the fluxes +by an area correction. For each model, outgoing fluxes should be multiplied +by the model area divided by the ESMF area. Incoming fluxes should be multiplied +by the ESMF area divided by the model area. So:: + + F1' = A1m/A1*F1 + F2' = w1*F1' + F2 = F2'*A2/A2m + + Q2 = F2*A2m + = (F2'*A2/A2m)*A2m + = F2'*A2 + = (w1*F1')*A2 + = w1*(A1m/A1*F1)*A2 + = A1m*F1 + = Q1 + +and now the mapped flux conserves in the component models. The area corrections +should only be applied to fluxes. These area corrections +can actually be applied a number of ways. + +* The model areas can be passed into ESMF as extra arguments and then the weights will be adjusted. In this case, weights will no longer sum to 1 and different weights will need to be generated for mapping fluxes and states. +* Can pass quantities instead of fluxes, multiplying the flux in the component by the model area. But this has a significant impact on the overall coupling strategy. +* Can pass the areas to the mediator and the mediator can multiple fluxes by the source model area before mapping and divide by the destination model area area after mapping. +* Can pass the areas to the mediator and implement an area correction term on the incoming and outgoing fluxes that is the ratio of the model and ESMF areas. This is the approach shown above and is how CMEPS traditionally implements this feature. + +Model areas should be passed to the mediator at initialization so the area corrections +can be computed and applied. These area corrections do not vary in time. +