Warning, /doc/algorithm/horiz-grid.rst is written in an unsupported language. File is not indexed.
view on githubraw file Latest commit ee406b47 on 2021-12-07 22:38:03 UTC
bf89a37abc Phob*0001 .. _spatial_discrete_horizontal_grid:
4f2617d475 Jeff*0002
0003 Horizontal grid
0004 ---------------
0005
0006 The model domain is decomposed into tiles and within each tile a
0007 quasi-regular grid is used. A tile is the basic unit of domain
0008 decomposition for parallelization but may be used whether parallelized
0009 or not; see section [sec:domain\_decomposition] for more details.
0010 Although the tiles may be patched together in an unstructured manner
0011 (i.e. irregular or non-tessilating pattern), the interior of tiles is a
0012 structured grid of quadrilateral cells. The horizontal coordinate system
0013 is orthogonal curvilinear meaning we can not necessarily treat the two
0014 horizontal directions as separable. Instead, each cell in the horizontal
0015 grid is described by the length of it’s sides and it’s area.
0016
0017 The grid information is quite general and describes any of the available
0018 coordinates systems, cartesian, spherical-polar or curvilinear. All that
0019 is necessary to distinguish between the coordinate systems is to
0020 initialize the grid data (descriptors) appropriately.
0021
0022 In the following, we refer to the orientation of quantities on the
0023 computational grid using geographic terminology such as points of the
0024 compass. This is purely for convenience but should not be confused with
0025 the actual geographic orientation of model quantities.
0026
0027 .. figure:: figs/hgrid-abcd.*
0028 :width: 80%
0029 :align: center
0030 :alt: hgrid-abcd
0031 :name: hgrid-abcd
ee406b477f Mart*0032
0033 Staggering of horizontal grid descriptors (lengths and areas). The grid
0034 lines indicate the tracer cell boundaries and are the reference grid for
0035 all panels. a) The area of a tracer cell, :math:`A_c`, is bordered by the
0036 lengths :math:`\Delta x_g` and :math:`\Delta y_g`. b) The area of a
0037 vorticity cell, :math:`A_\zeta`, is bordered by the lengths :math:`\Delta
0038 x_c` and :math:`\Delta y_c`. c) The area of a u cell, :math:`A_w`, is
0039 bordered by the lengths :math:`\Delta x_v` and :math:`\Delta y_f`. d) The
0040 area of a v cell, :math:`A_s`, is bordered by the lengths :math:`\Delta
0041 x_f` and :math:`\Delta y_u`.
4f2617d475 Jeff*0042
0043 :numref:`hgrid-abcd` (a) shows the tracer cell (synonymous with the continuity
ee406b477f Mart*0044 cell). The length of the southern edge, :math:`\Delta x_g`, western edge,
0045 :math:`\Delta y_g` and surface area, :math:`A_c`, presented in the vertical are
0046 stored in arrays :varlink:`dxG`, :varlink:`dyG` and :varlink:`rA`. The “g”
0047 suffix indicates that the lengths are along the defining grid boundaries. The
0048 “c” suffix associates the quantity with the cell centers. The quantities are
0049 staggered in space and the indexing is such that **dxG(i,j)** is positioned to
0050 the south of **rA(i,j)** and **dyG(i,j)** positioned to the west.
0051
0052 :numref:`hgrid-abcd` (b) shows the vorticity cell. The length of the northern
0053 edge, :math:`\Delta x_c`, eastern edge, :math:`\Delta y_c` and surface area,
0054 :math:`A_\zeta`, presented in the vertical are stored in arrays :varlink:`dxC`,
0055 :varlink:`dyC` and :varlink:`rAz`. The “c” suffix indicates that the lengths
0056 are measured between the cell centers and the “:math:`\zeta`” suffix associates
0057 points with the vorticity points. The quantities are staggered in space and the
0058 indexing is such that **dxC(i,j)** is positioned to the north of **rAz(i,j)**
0059 and **dyC(i,j)** positioned to the east.
4f2617d475 Jeff*0060
0061 :numref:`hgrid-abcd` (c) shows the “u” or western (w) cell. The length of the
ee406b477f Mart*0062 southern edge, :math:`\Delta x_v`, eastern edge, :math:`\Delta y_f` and surface
0063 area, :math:`A_w`, presented in the vertical are stored in arrays
0064 :varlink:`dxV`, :varlink:`dyF` and :varlink:`rAw`. The “v” suffix indicates
0065 that the length is measured between the v-points, the “f” suffix indicates that
0066 the length is measured between the (tracer) cell faces and the “w” suffix
0067 associates points with the u-points (w stands for west). The quantities are
0068 staggered in space and the indexing is such that **dxV(i,j)** is positioned to
0069 the south of **rAw(i,j)** and **dyF(i,j)** positioned to the east.
4f2617d475 Jeff*0070
0071 :numref:`hgrid-abcd` (d) shows the “v” or southern (s) cell. The length of the
ee406b477f Mart*0072 northern edge, :math:`\Delta x_f`, western edge, :math:`\Delta y_u` and surface
0073 area, :math:`A_s`, presented in the vertical are stored in arrays
0074 :varlink:`dxF`, :varlink:`dyU` and :varlink:`rAs`. The “u” suffix indicates
0075 that the length is measured between the u-points, the “f” suffix indicates that
0076 the length is measured between the (tracer) cell faces and the “s” suffix
0077 associates points with the v-points (s stands for south). The quantities are
0078 staggered in space and the indexing is such that **dxF(i,j)** is positioned to
0079 the north of **rAs(i,j)** and **dyU(i,j)** positioned to the west.
0080
0081 .. admonition:: S/R :filelink:`INI_CARTESIAN_GRID
0082 <model/src/ini_cartesian_grid.F>` ,
0083 :filelink:`INI_SPHERICAL_POLAR_GRID
0084 <model/src/ini_spherical_polar_grid.F>` ,
0085 :filelink:`INI_CURVILINEAR_GRID
0086 <model/src/ini_curvilinear_grid.F>`
4f2617d475 Jeff*0087 :class: note
0088
0089 | :math:`A_c , A_\zeta , A_w , A_s` : :varlink:`rA`, :varlink:`rAz`, :varlink:`rAw`, :varlink:`rAs` ( :filelink:`GRID.h <model/inc/GRID.h>` )
0090 | :math:`\Delta x_g , \Delta y_g` : :varlink:`dxG`, :varlink:`dyG` ( :filelink:`GRID.h <model/inc/GRID.h>` )
0091 | :math:`\Delta x_c , \Delta y_c` : :varlink:`dxC`, :varlink:`dyC` ( :filelink:`GRID.h <model/inc/GRID.h>` )
0092 | :math:`\Delta x_f , \Delta y_f` : :varlink:`dxF`, :varlink:`dyF` ( :filelink:`GRID.h <model/inc/GRID.h>` )
0093 | :math:`\Delta x_v , \Delta y_u` : :varlink:`dxV`, :varlink:`dyU` ( :filelink:`GRID.h <model/inc/GRID.h>` )
0094
0095
0096 Reciprocals of horizontal grid descriptors
0097 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0098
0099 Lengths and areas appear in the denominator of expressions as much as in
0100 the numerator. For efficiency and portability, we pre-calculate the
0101 reciprocal of the horizontal grid quantities so that in-line divisions
0102 can be avoided.
0103
ee406b477f Mart*0104 For each grid descriptor (array) there is a reciprocal named using the prefix
0105 ``recip_``. This doubles the amount of storage in :filelink:`GRID.h
0106 <model/inc/GRID.h>` but they are all only 2-D descriptors.
4f2617d475 Jeff*0107
0108 .. admonition:: S/R :filelink:`INI_MASKS_ETC <model/src/ini_masks_etc.F>`
0109 :class: note
0110
0111 | :math:`A_c^{-1} , A_\zeta^{-1} , A_w^{-1} , A_s^{-1}` : :varlink:`recip_rA`, :varlink:`recip_rAz`, :varlink:`recip_rAw`, :varlink:`recip_rAs` ( :filelink:`GRID.h <model/inc/GRID.h>` )
0112 | :math:`\Delta x_g^{-1} , \Delta y_g^{-1}` : :varlink:`recip_dxG`, :varlink:`recip_dyG` ( :filelink:`GRID.h <model/inc/GRID.h>` )
0113 | :math:`\Delta x_c^{-1} , \Delta y_c^{-1}` : :varlink:`recip_dxC`, :varlink:`recip_dyC` ( :filelink:`GRID.h <model/inc/GRID.h>` )
0114 | :math:`\Delta x_f^{-1} , \Delta y_f^{-1}` : :varlink:`recip_dxF`, :varlink:`recip_dyF` ( :filelink:`GRID.h <model/inc/GRID.h>` )
0115 | :math:`\Delta x_v^{-1} , \Delta y_u^{-1}` : :varlink:`recip_dxV`, :varlink:`recip_dyU` ( :filelink:`GRID.h <model/inc/GRID.h>` )
0116
0117 Cartesian coordinates
0118 ~~~~~~~~~~~~~~~~~~~~~
0119
0120 Cartesian coordinates are selected when the logical flag
0121 :varlink:`usingCartesianGrid` in namelist ``PARM04`` is set to true. The grid
0122 spacing can be set to uniform via scalars :varlink:`dXspacing` and
0123 :varlink:`dYspacing` in namelist ``PARM04`` or to variable resolution by the
0124 vectors :varlink:`DELX` and :varlink:`DELY`. Units are normally meters.
0125 Non-dimensional coordinates can be used by interpreting the
0126 gravitational constant as the Rayleigh number.
0127
0128 Spherical-polar coordinates
0129 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
0130
0131 Spherical coordinates are selected when the logical flag
0132 :varlink:`usingSphericalPolarGrid` in namelist ``PARM04`` is set to true. The
0133 grid spacing can be set to uniform via scalars :varlink:`dXspacing` and
0134 :varlink:`dYspacing` in namelist ``PARM04`` or to variable resolution by the
ee406b477f Mart*0135 vectors :varlink:`DELX` and :varlink:`DELY`. Units of these namelist variables
0136 are alway degrees. The horizontal grid descriptors are calculated from these
4f2617d475 Jeff*0137 namelist variables have units of meters.
0138
0139 Curvilinear coordinates
0140 ~~~~~~~~~~~~~~~~~~~~~~~
0141
0142 Curvilinear coordinates are selected when the logical flag
0143 :varlink:`usingCurvilinearGrid` in namelist ``PARM04`` is set to true. The grid
0144 spacing can not be set via the namelist. Instead, the grid descriptors
0145 are read from data files, one for each descriptor. As for other grids,
0146 the horizontal grid descriptors have units of meters.
