--- manual/s_phys_pkgs/text/gridalt.tex	2005/08/02 21:35:40	1.6
+++ manual/s_phys_pkgs/text/gridalt.tex	2005/08/03 16:57:31	1.7
@@ -116,19 +116,128 @@
 In order to minimize the correction terms for the state variables on the alternative,
 higher resolution grid, the vertical interpolation scheme must be constructed so that
 a dynamics-to-physics interpolation can be exactly reversed with a physics-to-dynamics mapping.
-The simple scheme employed to achieve this is:
+The simple scheme employed to achieve this is:\\
 
 Coarse to fine:\
 For all physics layers l in dynamics layer L, $ T_{phys}(l) = \{T_{dyn}(L)\} = T_{dyn}(L) $.
 
 Fine to coarse:\
-For all physics layers l in dynamics layer L, $T_{dyn}(L) = [T_{phys}(l)] = \int{T_{phys} dp } $.
+For all physics layers l in dynamics layer L, $T_{dyn}(L) = [T_{phys}(l)] = \int{T_{phys} dp } $.\\
 
 Where $\{\}$ is defined as the dynamics-to-physics operator and $[ ]$ is the physics-to-dynamics operator, $T$ stands for any state variable, and the subscripts $phys$ and $dyn$ stand for variables on
 the physics and dynamics grids, respectively.
 
 \subsubsection {Key subroutines, parameters and files } 
 
+\noindent
+One of the central elements of the gridalt package is the routine which 
+is called from subroutine gridalt\_initialise to define the grid to be
+used for the high end physics calculations. Routine make\_phys\_grid
+passes back the parameters which define the grid, ultimately stored 
+in the common block gridalt\_mapping.
+
+\begin{verbatim}
+       subroutine make_phys_grid(drF,hfacC,im1,im2,jm1,jm2,Nr,
+     . Nsx,Nsy,i1,i2,j1,j2,bi,bj,Nrphys,Lbot,dpphys,numlevphys,nlperdyn)
+c***********************************************************************
+c Purpose: Define the grid that the will be used to run the high-end
+c          atmospheric physics.
+c
+c Algorithm: Fit additional levels of some (~) known thickness in
+c          between existing levels of the grid used for the dynamics
+c
+c Need:    Information about the dynamics grid vertical spacing
+c
+c Input:   drF         - delta r (p*) edge-to-edge
+c          hfacC       - fraction of grid box above topography
+c          im1, im2    - beginning and ending i - dimensions
+c          jm1, jm2    - beginning and ending j - dimensions
+c          Nr          - number of levels in dynamics grid
+c          Nsx,Nsy     - number of processes in x and y direction
+c          i1, i2      - beginning and ending i - index to fill
+c          j1, j2      - beginning and ending j - index to fill
+c          bi, bj      - x-dir and y-dir index of process
+c          Nrphys      - number of levels in physics grid
+c
+c Output:  dpphys      - delta r (p*) edge-to-edge of physics grid
+c          numlevphys  - number of levels used in the physics
+c          nlperdyn    - physics level number atop each dynamics layer
+c
+c NOTES: 1) Pressure levs are built up from bottom, using p0, ps and dp:
+c              p(i,j,k)=p(i,j,k-1) + dp(k)*ps(i,j)/p0(i,j)
+c        2) Output dp's are aligned to fit EXACTLY between existing
+c           levels of the dynamics vertical grid
+c        3) IMPORTANT! This routine assumes the levels are numbered
+c           from the bottom up, ie, level 1 is the surface.
+c           IT WILL NOT WORK OTHERWISE!!!
+c        4) This routine does NOT work for surface pressures less
+c           (ie, above in the atmosphere) than about 350 mb
+c***********************************************************************
+\end{verbatim}
+
+\noindent In the case of the grid used to compute the atmospheric physical
+forcing (fizhi package), the locations of the grid points move in time with 
+the MITgcm $p^*$ coordinate, and subroutine gridalt\_update is called during 
+the run to update the locations of the grid points:
+
+\begin{verbatim}
+       subroutine gridalt_update(myThid)
+c***********************************************************************
+c Purpose: Update the pressure thicknesses of the layers of the
+c          alternative vertical grid (used now for atmospheric physics).
+c
+c Calculate: dpphys    - new delta r (p*) edge-to-edge of physics grid
+c                        using dpphys0 (initial value) and rstarfacC
+c***********************************************************************
+\end{verbatim}
+
+\noindent The gridalt package also supplies utility routines which perform
+the mappings from one grid to the other. These routines are called from the 
+code which computes the fields on the alternative (fizhi) grid.
+
+\begin{verbatim}
+      subroutine dyn2phys(qdyn,pedyn,im1,im2,jm1,jm2,lmdyn,Nsx,Nsy,
+     . idim1,idim2,jdim1,jdim2,bi,bj,windphy,pephy,Lbot,lmphy,nlperdyn,
+     . flg,qphy)
+C***********************************************************************
+C Purpose:
+C   To interpolate an arbitrary quantity from the 'dynamics' eta (pstar)
+C               grid to the higher resolution physics grid
+C Algorithm:
+C   Routine works one layer (edge to edge pressure) at a time.
+C   Dynamics -> Physics retains the dynamics layer mean value,
+C   weights the field either with the profile of the physics grid
+C   wind speed (for U and V fields), or uniformly (T and Q)
+C
+C Input:
+C   qdyn..... [im,jm,lmdyn] Arbitrary Quantity on Input Grid
+C   pedyn.... [im,jm,lmdyn+1] Pressures at bottom edges of input levels
+C   im1,2 ... Limits for Longitude Dimension of Input
+C   jm1,2 ... Limits for Latitude  Dimension of Input
+C   lmdyn.... Vertical  Dimension of Input
+C   Nsx...... Number of processes in x-direction
+C   Nsy...... Number of processes in y-direction
+C   idim1,2.. Beginning and ending i-values to calculate
+C   jdim1,2.. Beginning and ending j-values to calculate
+C   bi....... Index of process number in x-direction
+C   bj....... Index of process number in x-direction
+C   windphy.. [im,jm,lmphy] Magnitude of the wind on the output levels
+C   pephy.... [im,jm,lmphy+1] Pressures at bottom edges of output levels
+C   lmphy.... Vertical  Dimension of Output
+C   nlperdyn. [im,jm,lmdyn] Highest Physics level in each dynamics level
+C   flg...... Flag to indicate field type (0 for T or Q, 1 for U or V)
+C
+C Output:
+C   qphy..... [im,jm,lmphy] Quantity at output grid (physics grid)
+C
+C Notes:
+C   1) This algorithm assumes that the output (physics) grid levels
+C      fit exactly into the input (dynamics) grid levels
+C***********************************************************************
+\end{verbatim}
+
+\noindent And similarly, gridalt contains subroutine phys2dyn.
+
 \subsubsection {Dos and donts}
 
 \subsubsection {Gridalt Reference}