%\subsection{Design and Implementation Notes}

Regrid has been designed to be as efficient as possible during its
Run routine.  Although the initial calculation during the Store routines
can be computationally intensive, the {\tt ESMF\_RouteHandle} object
it creates is designed to be reused by similar Fields on the same Grids.
And, as long as the Grids are static, RegridStore can be called once
and reused throughout a simulation.  It leverages internal structures
and methods used throughout ESMF for communication so that algorithmic
and programming improvements can be focused on a single location.

Because many methods are supported for regridding, the main Store function
branches to a specific creation function based on the regrid method requested
(e.g. bilinear, conservative, spectral).  Each of these regrid methods are in
a separate module to prevent the main Regrid module from becoming too
large.  The user is unaware of this hierarchy as the top-level module provides
a unified API.

The RouteHandle object created by the RegridStore function contains a set of
"links" which identify how a Field at a point on the destination Grid is
related to a Field at a point on the source Grid.  As such, a "link"
consists of a source address, a destination address and a weight.  The addresses
are stored as indices to allow reuse by different Fields on the same Grids.
Because the Grids are generally distributed very differently, the Regrid object
also contains communication information for data motion required for the
regridding.

Our early application codes use static computational meshes, so initial
optimization efforts have been focused on making the Regrid run routines
fast, at the expense of the Store routines if necessary.  Therefore, Regrid
has been designed to move as much work as possible to the calculation of weights
that takes place inside Store.  In initial timings, typical RegridStore calls
take on the order of seconds while the application routines themselves require
more on the order of milliseconds.  Scaling on parallel architectures is
reasonably good up until communication overhead dominates timings (see
Figure~\ref{fig:RegridScaling} for scaling curves from an example application).

\begin{center}
\begin{figure}
\scalebox{0.9}{\includegraphics{RegridScaling}}
\caption{Sample scaling graphs for Regrid Run and Store routines. }
\label{fig:RegridScaling}
\end{figure}
\end{center}

\subsubsection{Bilinear Regridding Algorithm}
\label{sec:BilinearRegrid}

     The bilinear regridding method uses a local bilinear approximation
     to interpolate to a point in a quadrilateral grid.  This is applicable
     only for logically-rectangular or block-structured logically-rectangular
     grids.  Standard bilinear interpolation schemes can be found in many textbooks.
     Here we present a more general scheme which uses a local bilinear approximation
     to interpolate to a point in a quadrilateral grid.  Consider the grid points
     shown in Figure~\ref{fig:quad} labeled with logically-rectangular indices
     (e.g. $(i,j)$).

\begin{figure}
\caption{A general quadrilateral grid. \label{fig:quad}}
\begin{picture}(10,10)

\put(1.0,1.0){\line(2,1){5.0}}
\put(6.0,3.5){\line(1,2){2.5}}
\put(1.0,1.0){\line(1,2){2.5}}
\put(3.5,6.0){\line(2,1){5.0}}

\put(1.0,1.0){\circle*{0.1}}
\put(6.0,3.5){\circle*{0.1}}
\put(3.5,6.0){\circle*{0.1}}
\put(8.5,8.5){\circle*{0.1}}
\put(5.25,5.0){\circle*{0.1}}

\put(0.75,0.5 ){1 $(i,j)$}
\put(6.25,3.25){2 $(i+1,j)$}
\put(1.75,6.0 ){$(i,j+1)$ 4}
\put(8.75,8.5 ){3 $(i+1,j+1)$}
\put(5.0 ,5.0 ){$P$}

\end{picture}
\end{figure}

     Let the latitude-longitude coordinates of point 1 be $(\theta(i,j),\phi(i,j))$,
     the coordinates of point 2 be $(\theta(i+1,j),\phi(i+1,j))$, etc.
     Now let $\alpha$ and $\beta$ be
     continuous local coordinates such that the coordinates $(\alpha,\beta)$
     of point 1 are $(0,0)$, point 2 are $(1,0)$, point 3 are $(1,1)$ and
     point 4 are $(0,1)$.  If point $P$ lies inside the cell formed by the four
     points above, the function $f$ at point $P$ can be approximated by
\begin{eqnarray}\label{eq:bilinear}
f_P & = & (1-\alpha)(1-\beta)f(i,j) + \alpha(1-\beta)f(i+1,j) + \nonumber \\
    &   & \alpha\beta f(i+1,j+1) + (1-\alpha)\beta f(i,j+1)  \\
    & = & w_1 f(i,j) + w_2 f(i+1,j) + w_3 f(i+1,j+1) + w_4 f(i,j+1). \nonumber
\end{eqnarray}

     The remapping weights must therefore be computed by finding $\alpha$ and
     $\beta$ at point $P$.

     The latitude-longitude coordinates $(\theta,\phi)$ of point $P$ are known
     and can also be approximated by
\begin{eqnarray}\label{eq:thetaphi}
\theta & = & (1-\alpha)(1-\beta)\theta_1 + \alpha(1-\beta)\theta_2 + \nonumber
          \alpha\beta \theta_3 + (1-\alpha)\beta \theta_4 \\
\phi   & = & (1-\alpha)(1-\beta)\phi_1   + \alpha(1-\beta)\phi_2 +
          \alpha\beta \phi_3 + (1-\alpha)\beta \phi_4.
\end{eqnarray}

     Because (\ref{eq:thetaphi}) is nonlinear in $\alpha$ and $\beta$, we must
     linearize and iterate toward a solution.  Differentiating
     (\ref{eq:thetaphi}) results in
\begin{equation}
\left[\begin{array}{c} \delta\theta \\ \delta\phi \end{array}\right] = A
\left[\begin{array}{c} \delta\alpha \\ \delta\beta \end{array}\right],
\end{equation}

     where

\begin{equation}
A = \left[\begin{array}{cc}
(\theta_2-\theta_1) + (\theta_1-\theta_4+\theta_3-\theta_2)\beta &
(\theta_4-\theta_1) + (\theta_1-\theta_4+\theta_3-\theta_2)\alpha \\
(\phi_2-\phi_1) + (\phi_1-\phi_4+\phi_3-\phi_2)\beta &
(\phi_4-\phi_1) + (\phi_1-\phi_4+\phi_3-\phi_2)\alpha
\end{array}\right].
\end{equation}

     Inverting this system,

\begin{equation}\label{eq:dalpha}
\delta\alpha = \left|\begin{array}{cc}
\delta\theta &
(\theta_4-\theta_1) + (\theta_1-\theta_4+\theta_3-\theta_2)\alpha \\
\delta\phi &
(\phi_4-\phi_1) + (\phi_1-\phi_4+\phi_3-\phi_2)\alpha
\end{array}\right| \div \det(A),
\end{equation}

     and

\begin{equation}\label{eq:dbeta}
\delta\beta = \left|\begin{array}{cc}
(\theta_2-\theta_1) + (\theta_1-\theta_4+\theta_3-\theta_2)\beta &
\delta\theta \\
(\phi_2-\phi_1) + (\phi_1-\phi_4+\phi_3-\phi_2)\beta &
\delta\phi
\end{array}\right| \div \det(A).
\end{equation}

     Starting with an initial guess for $\alpha$ and $\beta$ (say
     $\alpha=\beta=0$), equations~(\ref{eq:dalpha}) and (\ref{eq:dbeta})
     can be iterated until $\delta\alpha$ and $\delta\beta$ are suitably small.
     The weights can then be computed from (\ref{eq:bilinear}).  Note that
     for simple latitude-longitude grids, this iteration will converge in the
     first iteration.

     In order to compute the weights using this general bilinear iteration,
     it must be determined in which box the point $P$ resides.  Because this
     method is valid only for logically-rectangular grids, the sweep algorithm
     can be optimized to take advantage of this restriction.  The sweep
     method currently in ESMF steps through each data point $P$ on the destination
     grid.  For each destination point, it then loops through the cells on the
     source grid, comparing the coordinates of point $P$ with the bounding box
     formed by each cell's minimum and maximum coordinates.  Most source cells can
     be efficiently eliminated from the sweep via this simple test.  This loop is
     further optimized by tracking the index of the source cell containing the
     previous point and using that as the initial starting index for the next
     point's sweep, since both grids are logically ordered.  Please see
     Figure~\ref{fig:BilinearSweep} for an illustration of the sweep algorithm.

\begin{center}
\begin{figure}
\scalebox{0.9}{\includegraphics{BilinearSweep}}
\caption{Illustration of the Bilinear Sweep Algorithm. }
\label{fig:BilinearSweep}

\end{figure}
\end{center}

\subsubsection{Bicubic Regridding Algorithm}  Not yet implemented!
\label{sec:BicubicRegrid}

     Like the bilinear remapping, bicubic remapping is applicable
     only for logically-rectangular or block-structured logically-rectangular
     grids.  The bicubic remapping exactly follows the bilinear remapping except
     that four weights for each corner point are required.  Thus, num\_wts
     is set to four for this option.  The bicubic remapping is

\begin{eqnarray}\label{eq:bicubic}
f_P & = &
    (1 - \beta^2(3-2\beta))(1 - \alpha^2(3-2\alpha))f(i  ,j  ) + \nonumber \\
& & (1 - \beta^2(3-2\beta))     \alpha^2(3-2\alpha) f(i+1,j  ) + \nonumber \\
& &      \beta^2(3-2\beta)      \alpha^2(3-2\alpha) f(i+1,j+1) + \nonumber \\
& &      \beta^2(3-2\beta) (1 - \alpha^2(3-2\alpha))f(i  ,j+1) + \nonumber \\
& & (1 - \beta^2(3-2\beta))\alpha  (\alpha-1)^2
                        {{\partial f}\over{\partial i}}(i  ,j  ) + \nonumber \\
& & (1 - \beta^2(3-2\beta))\alpha^2(\alpha-1)
                        {{\partial f}\over{\partial i}}(i+1,j  ) + \nonumber \\
& &      \beta^2(3-2\beta) \alpha^2(\alpha-1)
                        {{\partial f}\over{\partial i}}(i+1,j+1) + \nonumber \\
& &      \beta^2(3-2\beta) \alpha  (\alpha-1)^2
                        {{\partial f}\over{\partial i}}(i  ,j+1) + \nonumber \\
& & \beta  (\beta-1)^2(1 - \alpha^2(3-2\alpha))
                        {{\partial f}\over{\partial j}}(i  ,j  ) + \nonumber \\
& & \beta  (\beta-1)^2     \alpha^2(3-2\alpha)
                        {{\partial f}\over{\partial j}}(i+1,j  ) + \nonumber \\
& & \beta^2(\beta-1)       \alpha^2(3-2\alpha)
                        {{\partial f}\over{\partial j}}(i+1,j+1) + \nonumber \\
& & \beta^2(\beta-1)  (1 - \alpha^2(3-2\alpha))
                        {{\partial f}\over{\partial j}}(i  ,j+1) + \nonumber \\
& & \alpha  (\alpha-1)^2\beta  (\beta-1)^2
           {{\partial^2 f}\over{\partial i \partial j}}(i  ,j  ) + \nonumber \\
& & \alpha^2(\alpha-1)  \beta  (\beta-1)^2
           {{\partial^2 f}\over{\partial i \partial j}}(i+1,j  ) + \nonumber \\
& & \alpha^2(\alpha-1)  \beta^2(\beta-1)
           {{\partial^2 f}\over{\partial i \partial j}}(i+1,j+1) + \nonumber \\
& & \alpha  (\alpha-1)^2\beta^2(\beta-1)
           {{\partial^2 f}\over{\partial i \partial j}}(i  ,j+1)
\end{eqnarray}

     where $\alpha$ and $\beta$ are identical to those found in the bilinear
     case and are found using an identical algorithm.  Note that unlike the
     conservative remappings, the gradients here are gradients with respect to
     the {\em logical} variable and not latitude or longitude.  Lastly, the four
     weights corresponding to each address pair correspond to the weight
     multiplying the field value at the point, the weight multiplying the
     gradient with respect to $i$, the weight multiplying the gradient with
     respect to $j$, and the weight multiplying the cross gradient in that order.

\subsubsection{Conservative Regridding Algorithms}
\label{sec:ConserveRegrid}

     First-order and second-order conservative remapping share a common
     algorithm, though currently only first-order has been implemented.
     ESMF implements a conservative remapping scheme described in detail
     elsewhere \cite{Jones1999}.  A brief outline will be given
     here to aid the user in understanding this regridding algorithm.

     To compute a flux on a new (destination) grid which results in the same
     energy or water exchange as a flux $f$ on an old (source) grid, the
     destination flux $F$ at a destination grid cell $k$ must satisfy

\begin{equation}\label{eq:local}
\overline{F}_k = {1\over{A_k}}\int\int_{A_k} fdA,
\end{equation}

     where $\overline{F}$ is the area-averaged flux and $A_k$ is the area of
     cell $k$. Because the integral in (\ref{eq:local}) is over the area of
     the destination grid cell, only those cells on the source grid that are
     covered at least partly by the destination grid cell contribute to the
     value of the flux on the destination grid.  If cell $k$ overlaps $N$ cells
     on the source grid, the remapping can be written as

\begin{equation}\label{eq:rmpsum}
\overline{F}_k =
{1\over{A_k}} \sum_{n=1}^N \int\int_{A_{nk}} f_ndA,
\end{equation}

     where $A_{nk}$ is the area of the source grid cell $n$ covered by the
     destination grid cell $k$, and $f_n$ is the local value of the flux in the
     source grid cell (see Figure~\ref{fig:grids}).  Note that (\ref{eq:rmpsum})
     is normalized by the destination area $A_k$ corresponding to the
     {\tt ESMF\_RegridNormOpt} value of {\tt ESMF\_REGRID\_NORM\_DSTAREA}.  The
     sum of the weights for a destination cell $k$ in this case would be between
     0 and 1 and would be the area fraction if $f_n$ were identically 1
     everywhere on the source grid.  The normalization option
     {\tt ESMF\_REGRID\_NORM\_FRACAREA} would actually divide by the area of the
     source grid overlapped by cell $k$:

\begin{equation}
\sum_{n=1}^N \int\int_{A_{nk}}dA.
\end{equation}

     For this normalization option, remapping a function $f$ which is 1
     everywhere on the source grid would result in a function $F$ that is
     exactly one wherever the destination grid overlaps a non-masked source
     grid cell and zero otherwise.  A normalization option of
     {\tt ESMF\_REGRID\_NORM\_NONE} would result in the actual angular area
     participating in the remapping.

     Assuming $f_n$ is constant across a source grid cell, (\ref{eq:rmpsum})
     would lead to the first-order area-weighted schemes used in current coupled
     models.  A more accurate form of the remapping is obtained by using

\begin{equation}\label{eq:gradient}
f_n = \overline{f}_n +
                   \nabla_n f\cdot({\vec{r}} - \vec{r}_n),
\end{equation}

     where $\nabla_n f$ is the gradient of the flux in cell $n$ and $\vec{r}_n$
     is the centroid of cell $n$ defined by

 \begin{equation}\label{eq:centroid}
\vec{r}_n = {1\over{A_n}}\int\int_{A_n}\vec{r}dA.
\end{equation}

     Such a distribution satisfies the conservation constraint and is equivalent
     to the first terms of a Taylor series expansion of $f$ around $\vec{r}_n$.
     The remapping is thus second-order accurate if $\nabla_n f$ is at least a
     first-order approximation to the gradient.

     The remapping can now be expanded in spherical coordinates as

\begin{equation}\label{eq:remap}
\overline{F}_k = \sum_{n=1}^{N} \left[\overline{f}_n w_{1nk} +
\left({{\partial f}\over{\partial \theta}}\right)_n w_{2nk} +
\left({1\over{\cos\theta}}{{\partial f}\over{\partial \phi}}\right)_n w_{3nk}
\right],
\end{equation}

     where $\theta$ is latitude, $\phi$ is longitude and the three remapping
     weights are

\begin{equation}\label{eq:weights1}
w_{1nk} = {1\over{A_k}}\int\int_{A_{nk}}dA, \\
\end{equation}
\begin{eqnarray}\label{eq:weights2}
w_{2nk} & = & {1\over{A_k}}\int\int_{A_{nk}}(\theta-\theta_n)dA \nonumber \\
        & = & {1\over{A_k}}\int\int_{A_{nk}}\theta dA -
              {{w_{1nk}}\over{A_n}}\int\int_{A_n}\theta dA,
\end{eqnarray}

     and

\begin{eqnarray}\label{eq:weights3}
w_{3nk} & = & {1\over{A_k}}\int\int_{A_{nk}}\cos\theta(\phi-\phi_n)dA \nonumber \\
        & = & {1\over{A_k}}\int\int_{A_{nk}}\phi\cos\theta dA -
              {{w_{1nk}}\over{A_n}}\int\int_{A_n}\phi\cos\theta dA .
\end{eqnarray}

     Again, if the gradient is zero, ({\ref{eq:remap}}) reduces to a first-order
     area-weighted remapping.

     The area integrals in equations~(\ref{eq:weights1})--(\ref{eq:weights3})
     are computed by converting the area integrals into line integrals using the
     divergence theorem.  Computing line integrals around the overlap regions
     is much simpler; one simply integrates first around every grid cell on the
     source grid, keeping track of intersections with destination grid lines,
     and then one integrates around every grid cell on the destination grid in
     a similar manner.  After the sweep of each grid, all overlap regions have
     been integrated.

     Choosing appropriate functions for the divergence, the integrals in
     equations~(\ref{eq:weights1})--(\ref{eq:weights3}) become

\begin{equation}
\int\int_{A_{nk}}dA = \oint_{C_{nk}} -\sin\theta d\phi,
\end{equation}
\begin{equation}
\int\int_{A_{nk}}\theta dA =
 \oint_{C_{nk}} [-\cos\theta-\theta\sin\theta]d\phi,
\end{equation}
\begin{equation}
\int\int_{A_{nk}}\phi\cos\theta dA =
\oint_{C_{nk}} -{\phi\over 2}[\sin\theta\cos\theta + \theta]d\phi,
\end{equation}

     where $C_{nk}$ is the counterclockwise path around the region $A_{nk}$.
     Computing these three line integrals during the sweeps of each grid
     provides all the information necessary for computing the remapping weights.

\begin{figure}
  \caption{An example of a triangular destination grid cell $k$ overlapping
           a quadrilateral source grid.  The region $A_{kn}$
           is where cell $k$ overlaps the quadrilateral cell $n$.
           Vectors used by search and intersection routines are
           also labeled. \label{fig:grids}}

\begin{picture}(10,10)

\put(2.5 ,0   ){\line(2,1){7.5}}
\put(1.25,2.5 ){\line(2,1){7.5}}
\put(0   ,5.0 ){\line(2,1){7.5}}
%\put(0   ,3.75){\line(2,1){10.0}}

\put(  0,5.0 ){\line(1,-2){2.5}}
\put(2.5,6.25){\line(1,-2){2.5}}
\put(5.0,7.5 ){\line(1,-2){2.5}}
\put(7.5,8.75){\line(1,-2){2.5}}

\put(1.25,3.125){\line(1,0){5.0}}
\put(6.25,3.125){\line(1,4){1.0}}
{\thicklines
\put(7.25,7.125){\vector(-3,-2){6.0}}
\put(5.0 ,7.5  ){\vector(1,-2){1.25}}
%\put(5.0 ,7.5  ){\vector(6,-1){2.25}}
\put(5.0 ,7.5  ){\vector(4,-1){2.25}}
}

\put(6.25 ,7.375){$\vec{r}_{1b}$}
\put(4.875,6.75 ){$\vec{r}_{12}$}
\put(4.375,5.625){$\vec{r}_{be}$}

\put(4.25 ,7.75 ){$(\theta_1,\phi_1)$}
\put(6.375,5.0  ){$(\theta_2,\phi_2)$}
\put(7.5  ,7.125){$(\theta_b,\phi_b)$}
\put(0.25 ,3.125){$(\theta_e,\phi_e)$}

\put(5.0 ,7.5  ){\circle*{0.1}}
\put(6.25,5.0  ){\circle*{0.1}}
\put(7.25,7.125){\circle*{0.1}}
\put(1.25,3.125){\circle*{0.1}}

\put(5.625,5.625){Cell $k$}
\put(6.25 ,2.5  ){Cell $n$}
\put(5.0  ,3.75 ){$A_{kn}$}

\end{picture}
\end{figure}

     As described above, the algorithm for computing the remapping weights
     is relatively simple.  The process amounts to finding the location of
     the endpoint of a segment and then finding the next intersection with
     the other grid.  The line integrals are then computed and summed according
     to which grid cells are associated with that particular subsegment.  The
     most time-consuming portion of the algorithm is finding which cell on one
     grid contains an endpoint from the other grid.  This process consists
     of sweeping through lists of cells from the other grid, hunting for
     intersections with an identified subsegment.   Much of the potential for
     optimization of regridding algorithms comes from limiting the range of
     cells to sweep.  Optimal methods can be more easily written when the grid
     is well structured and regular.  However, for a general grid, a hierarchy
     of methods appears to work best.  In the ESMF
     implementation, two algorithms are used to restrict the range of cells
     that are swept.  First, prior to looping through the cells on either grid,
     coordinate bins are created from the other grid.  In this process, the local
     physical domain of the grid being swept is divided into logical blocks, each
     one represented by a bin.  The cells of the grid being swept are looped through
     to determine the minimum and maximum grid indices corresponding to each bin's
     range of physical coordinates.  Each bin therefore identifies an index range
     corresponding to a physical coordinate range.  Then when the sweep begins,
     only those cells in the index range belonging to the same coordinate bin as
     the identified subsegment are used.  Please reference
     Figure~\ref{fig:ConservSweep} for an illustration of binning and the sweep
     algorithm.

\begin{center}
\begin{figure}
\scalebox{0.9}{\includegraphics{ConservSweep}}
\caption{Illustration of the Conservative Sweep Algorithm. }
\label{fig:ConservSweep}
\end{figure}
\end{center}

     Note that currently ESMF creates bins based
     only on coordinates in the second grid direction (typically "y" or "latitude").
     The second stage checks the bounding box of each grid cell in the determined
     bin.  The bounding box is formed by the cell's minimum and maximum coordinates.
     This process further restricts the actual sweep to a small number of cells.

     Once the sweep has been restricted, a robust algorithm that works for most
     cases is a cross-product test.  In this test, a cross product is computed
     between the vector corresponding to a cell side ($\vec{r}_{12}$ in
     Figure~\ref{fig:grids}) and a vector extending from the beginning of the
     cell side to the search point ($\vec{r}_{1b}$).  If

\begin{equation}\label{eq:cross}
\vec{r}_{12} \times \vec{r}_{1b} > 0,
\end{equation}

     the point lies to the left of the cell side.  If (\ref{eq:cross}) holds for
     every cell side, the point is enclosed by the cell.  This test is not
     completely robust and will fail for grid cells that are non-convex.

% \subsubsection{Intersections}\label{sec:intersect}

     Once the location of an initial endpoint is found, it is necessary to check
     to see if the segment intersects with the cell side.  If the segment is
     parametrized as
\begin{eqnarray}
\theta &=& \theta_b + s_1 (\theta_e - \theta_b) \nonumber \\
\phi   &=& \phi_b + s_1 (\phi_e - \phi_b)
\end{eqnarray}
     and the cell side as
\begin{eqnarray}
\theta &=& \theta_1 + s_2 (\theta_2 - \theta_1) \nonumber \\
\phi   &=& \phi_1 + s_2 (\phi_2 - \phi_1),
\end{eqnarray}
     where $\theta_1, \phi_1, \theta_2, \phi_2, \theta_b,$ and $\theta_e$ are
     endpoints as shown in Figure~\ref{fig:grids}, the intersection of the two
     lines occurs when $\theta$ and $\phi$ are equal.  The linear system
\begin{equation}
\left[ \begin{array}{cc}
(\theta_e - \theta_b) & (\theta_1 - \theta_2) \\
(\phi_e - \phi_b) & (\phi_1 - \phi_2) \\
\end{array} \right]
\left[ \begin{array}{c} s_1 \\ s_2 \\ \end{array} \right] =
\left[ \begin{array}{c}
(\theta_1 - \theta_b) \\ (\phi_1 - \phi_b)  \\
\end{array} \right]
\end{equation}
     is then solved to determine $s_1$ and $s_2$ at the intersection point.  If
     $s_1$ and $s_2$ are between zero and one, an intersection occurs with that
     cell side.

     It is important also to compute identical intersections during the sweeps
     of each grid.  To ensure that this will occur, the entire line segment is
     used to compute intersections rather than using a previous or next
     intersection as an endpoint.

% \subsubsection{Coincidences}

     Often, pairs of grids will share common lines (e.g. the Equator).  When
     this is the case, the method described above will double-count the
     contribution of these line segments.  Coincidences can be detected when
     computing cross products for the search algorithm described above.  If
     the cross product is zero in this case, the endpoint lies on the cell
     side.  A second cross product between the line segment and the cell side
     can then be computed.  If the second cross product is also zero, the
     lines are coincident.  Once a coincidence has been detected, the
     contribution of the coincident segment can be computed during the
     first sweep and ignored during the second sweep.

% \subsubsection{Spherical coordinates}\label{sec-sphere}

     Some aspects of the spherical coordinate system introduce additional
     problems for the method described above.  Longitude is multiple valued
     on one line on the sphere, and this branch cut may be chosen differently
     by different grids.  Care must be taken when calculating intersections
     and line integrals to ensure that the proper longitude values are used.
     A simple method is to always check to make sure the longitude is in the
     same interval as the source grid cell center.

     Another problem with computing weights in spherical coordinates is the
     treatment of the pole.  First, note that although the pole is physically
     a point, it is a line in latitude-longitude space and has a nonzero
     contribution to the weight integrals.  If a grid does not contain the
     pole explicitly as a grid vertex, the pole contribution must be added
     to the appropriate cells.  The pole contribution can be computed analytically.

     The pole also creates problems for the search and intersection algorithms
     described above.  For example, a grid cell that overlaps the pole can
     result in a nonconvex cell in latitude-longitude coordinates.  The
     cross-product test described above will fail in this case.  In addition,
     segments near the pole typically exhibit large changes in longitude even
     for very short segments.  In such a case, the linear parametrizations used
     above result in inaccuracies for determining the correct intersections.

     To avoid these problems, a coordinate transformation can be used poleward
     of a given threshold latitude (typically within one degree of the pole).
     A possible transformation is the Lambert equivalent azimuthal projection
\begin{eqnarray}
X &=& 2\sin\left({\pi \over 4} - {\theta \over 2}\right)\cos\phi \nonumber \\
Y &=& 2\sin\left({\pi \over 4} - {\theta \over 2}\right)\sin\phi
\end{eqnarray}
     for the North Pole.  The transformation for the South Pole is similar.
     This transformation is only used to compute intersections; line integrals
     are still computed in latitude-longitude coordinates.  Because intersections
     computed in the transformed coordinates can be different from those computed
     in latitude-longitude coordinates, line segments which cross the latitude
     threshold must be treated carefully.  To compute the intersections
     consistently for such a segment, intersections with the threshold latitude
     are detected and used as a normal grid intersection to provide a clean break
     between the two coordinate systems.

\subsubsection{Overview of Parallelization of Regrid}
On parallel processing platforms, the physical domains of the source and
destination Grids are decomposed into logical Decomposition Elements (DEs), as
illustrated in Figure~\ref{fig:ParallelRegrid}.  In order to calculate
interpolation weights, each destination DE will require coordinate
data from any of the source Grid that
overlaps it in physical space, which may span several DEs from the source Grid.
Corresponding source Field data is necessary later for regridding calculations
using the regridding weights.  The DEs for each Grid are mapped to sets of PETs,
which can be either shared or unique.  However, RegridStore and Regrid must
be called with a VM encompassing the union of the sets of PETs, typically from
a CouplerComponent.  In any case, most situations will require data transfer
between PETs for regridding.  Once source data is available locally, the
regridding algorithms discussed earlier can be applied.

\begin{center}
\begin{figure}
\scalebox{0.9}{\includegraphics{ParallelRegrid}}
\caption{Illustration of Parallel Regridding. }
\label{fig:ParallelRegrid}
\end{figure}
\end{center}

There are four major sections of regridding that are impacted by the
parallelization process: identifying necessary data, transferring that data, the
sweep algorithms, and then calculating and applying the interpolation weights to
calculate regridded Fields.  Each will be discussed below.

\subsubsection{Parallelization of Regrid: Identification of Necessary Data}

The calculation of interpolation weights requires coordinate information from
both source and destination Grids, and the application of those weights to
determine regridded values needs corresponding source data.  In a serial
implementation of regridding, the complete source and destination Grids, with
all their related data, are stored on a single processor.  In a parallel
implementation, the Grids and their corresponding data have been decomposed as
DEs on a number of PETs.  In this situation, none of the PETs responsible for
part of the destination Grid, represented as a DE, necessarily has all the source
data needed for the calculation or application of interpolation weights.  The
easiest approach to making the necessary source information available is to
simply transfer or maintain copies of all of the source Grid coordinate and Field
data on each of those PETs.  However, this tends to be inefficient in terms of
either communication or memory usage, and computational time spent in search
algorithms.  It requires only a slight bit more work to identify which source DEs
intersect the the local destination DE in physical space and then transfer all
the data from those DEs.  In some cases, this will save communication and memory
overhead.  But in other cases, like between one Grid decomposed in rows and
another decomposed by columns as illustrated in Figure~\ref{fig:RToCRegrid}, that
still ultimately means copying all of the source Grid to each destination PET.
It often makes more sense to identify and transfer only the data from the
source Grid that is required by the destination DE.  In a parallel environment,
this means determining which source DEs intersect the local destination DE in
physical space, determining the extent of the data on that source DE that must
be transferred, and then gathering it to the local PET.  Both of these
approaches, either identifying the exact extent of the data that must be
communicated or communicating data as entire DEs, are currently implemented in
the framework.  By default the framework will transfer only the necessary data,
and the option is currently not readily available to users but is set internally
in the Grid code using a parameter called "domainOption."

\begin{center}
\begin{figure}
\scalebox{0.9}{\includegraphics{RToCRegrid}}
\caption{Example of parallel regridding requiring transfer of all data,
         when transferring all data between intersecting DEs. }
\label{fig:RToCRegrid}
\end{figure}
\end{center}

This intersection of DEs is calculated in physical space, using a private Grid
method.  In complicated Grids, these intersections could be non-rectangular, but
for the current logically rectangular Grids each intersection is defined as the
block of the source DE that encompasses any physical overlap with the destination
DE's domain.  Future Grid types would need appropriate methods to identify
intersections, based on their topologies as well as communication issues.  As
shown in Figure~\ref{fig:RegridIntersection},
the intersection is often a subset of both the source and destination DEs'
domains, which means that each destination DE must receive and process data from
multiple source DEs.  Each PET involved in a regridding process must calculate
which other PETs it must send data to and how much (if it has a source DE) and
which it must receive data from and how much (if it has a destination DE).  The
current Grid structures contain enough global information to individually
determine the sending data, but the calculation of the data to be received takes
some global communication.

\begin{center}
\begin{figure}
\scalebox{0.9}{\includegraphics{RegridIntersection}}
\caption{Intersection of DE Domains in Parallel Regridding. }
\label{fig:RegridIntersection}
\end{figure}
\end{center}

Regridding algorithms that are point-based (as opposed to cell-based), like
bilinear or bicubic interpolation, require an extra layer of cells around the
identified region, because those algorithms need the location of all surrounding
data points (see Figure~\ref{fig:RegridExtraLayer}).

\begin{center}
\begin{figure}
\scalebox{0.9}{\includegraphics{RegridExtraLayer}}
\caption{Illustration of the extra layer of points required by point-based Regrid
          algorithms. }
\label{fig:RegridExtraLayer}
\end{figure}
\end{center}

Points in this extra layer are assigned internal mask values and are used in the
calculation of interpolation weights for data locations inside the identified
region, but are not assigned weights themselves.  However, these points could be
used in the future as a mechanism for regridding of periodic grids or to avoid
extrapolation issues near the edges of computational grids.

\subsubsection{Parallelization of Regrid: Data Transfer}
Once a block of data to send or receive has been identified, it is stored as an
internal structure called a {\tt domain} and added to a {\tt domainList}.  There
are separate send and receive domainLists for each DE.  From the domainLists,
all the sending and receiving information between PETs is stored internally as a
Route, so that it can leverage other ESMF code for efficient communication.
Internal to the Regrid Store routines, this Route is used to gather necessary
Grid coordinate information.  However, since Routes apply offsets in memory from
a base address rather than addresses themselves, these Routes are reusable by
structures that are distributed in the same way.  The Route to transfer Field
data is similar to that to move Grid coordinates but must be modified for any
Field ranks that do not correspond to a Grid axis and the Field's halo width and
lower bounds.   The modified Route is added to the RouteHandle that is returned
to users and applied later during the routine that actually regrids data from
one Field to another.

Each PET has its own unique Route.  The data it gathers, either Grid coordinates
or Field values, are stored locally as single 1D Arrays.

\subsubsection{Parallelization of Regrid: Sweep Algorithms}
The conservative regrid schemes create coordinate bins to decrease the
number of cells that must be swept, as described earlier.  SCRIP
had an input parameter to set the number of bins to be created, but for a
parallel implementation that number needs to be dynamic.  Dynamic binning
balances the cost, in terms of computational efficiency and storage, of setting
up bins with the savings of having fewer points in each bin to sweep through.
Rather than specify a number of bins, ESMF added a parameter to set a targeted
number of cells per bin, called {\tt targetBinSize}.  The number of bins on any
PET is set by the local number of cells divided by the targetBinSize.  Currently
this parameter is hard-coded in Regrid, but could be made available to users.
It has been set to 250, based on some preliminary timings on its effect on
Regrid Store (see Figure~\ref{fig:TargetBinSize}).

\begin{center}
\begin{figure}
\scalebox{0.9}{\includegraphics{TargetBinSize}}
\caption{Effect of TargetBinSize on RegridStore timing. }
\label{fig:TargetBinSize}
\end{figure}
\end{center}

Because the conservative regrid algorithm is based on cells and assumes data
values at the vertices, it can operate on the entire set of 1D Arrays of Grid
coordinate information at once.

The bilinear algorithm, on the other hand, is point-based and must assume the
data is logically rectangular.  For that reason, its sweep routine operates on
a single domain at a time, which typically represents just a part of the 1D
gathered Arrays.  It is otherwise unaffected by parallelization.

\subsubsection{Parallelization of Regrid: Calculation and Application of
               Interpolation Weights}

Once the necessary data has been identified and gathered, the calculation and
application of interpolation weights are entirely local operations, requiring no
inter-processor communication.  Once an interpolation weight has been determined
using one of the algorithms described earlier, the weight is stored as part of a
local list of links (described previously) in an object called an
{\tt ESMF\_TransformValues}.  This object is itself part of the
{\tt ESMF\_RouteHandle} object, and contains:
\begin{description}
   \item [numlist]
         The number of links included in the object.  It also represents the
         size of the corresponding arrays.
   \item [srcindex]
         An array of indices into the local array of source data.
         This array is of size [numlist] and kind ESMF\_KIND\_I4.  Only a single
         integer is required to identify the source index because the source data
         has been gathered as a vector.
   \item [dstindex]
         An array of indices into the local array of destination data.
         This array is of size [2*numlist] and kind ESMF\_KIND\_I4.  Each
         destination index address requires two integers, one for each rank
         of the data array that corresponds to a Grid axis.  However, rather
         than being an array of rank 2, the index pairs are stored sequentially
         in the [dstindex] array.
   \item [weights]
         An array of interpolation weights.  This array is of size [numlist] and
         kind ESMF\_KIND\_R8.
\end{description}
Each link is represented by an entry in this set of arrays.  Also note that there
is a single link for each unique combination of source and destination indices.

The application of the interpolation weights occurs during the Regrid run
routines.  The only necessary communication is that to gather the required source
data locally into a one-dimensional array, using a precomputed Route.
Fundamentally, the application of the weights is a vector multiply of a sparse
matrix, with indirect addressing of the indices.  The main calculation is a loop
over the number of links that effectively sums the product of the source data and
the interpolation weights and loads the result into the corresponding destination
address.  A sample code fragment below illustrates the simplest case, where both
the source and destination data are two-dimensional arrays whose data axes
correspond to the grids' exactly, with no reordering:

\begin{verbatim}
      do n = 1,numlinks
        d1 = dstIndex((n-1)*2 + 1)
        d2 = dstIndex((n-1)*2 + 2)
        s1 = srcIndex(n)
        dstData2D(d1,d2) = dstData2D(d1,d2) &
                         + (gatheredData(s1) * weights(n))
      enddo  ! numlinks
\end{verbatim}

The coding becomes increasingly more complicated for data arrays of higher rank,
but is inherently similar.

\subsubsection{Regrid Objects}

There is no {\tt ESMF\_Regrid} object per se.  Users are returned an
{\tt ESMF\_RouteHandle} object, which contains one or more {\tt ESMF\_Routes}
used to gather source data, an {\tt ESMF\_TransformValues} object with the
list of links, and an identifier for the type of RouteHandle.  All of these
objects are private and users are not expected to access or modify them.


% !TeX spellcheck = en_GB
% !TeX root = ../main-scirep.tex
\section{Results}
\label{section:results}

\subsection{Dynamic network model of legislation}\label{subsection:model}
\label{subsection:datamodel}
We model 25 years of statutory materials from two advanced industrial countries, the United States and Germany, as time-evolving document networks.
To build our original datasets,
for the United States, we collect annual snapshots of the United States Code (US Code) from 1994 to 2018 from the Office of the Law Revision Counsel of the U.S. House of Representatives.
For Germany, we create a parallel set of yearly snapshots for all federal statutory laws in effect at the beginning of the year in question based on documents from Germany's primary legal data provider, \emph{juris GmbH}.
For details on our data sources, see Section~1 of the Supplementary Information (SI).

Each individual law or section (that has not been repealed) contains at least some text,
and it may contain nested subsections as well as ingoing and outgoing references.
For each country and yearly snapshot, we construct a network of all federal statutes.
The entities in this network are the structural elements of the statutes we collect, some of which contain text (i.e., the stipulation of a legal rule).
These entities are interconnected by inclusion relationships (e.g., a section containing several paragraphs) and cross-references (i.e., the text of an element referencing another element),
and they can be sequentially ordered by their labels.
Notably, only one level of the inclusion hierarchy in legislative corpora is uniquely sequentially labelled (this is the Section level in the United States and the § or Article level in Germany).
We refer to the structural elements in this layer as \emph{seqitems}.
For excerpts from United States law and German law that illustrate their inherent structure, see Section~1.3 of the \suppi.

In the legislative process,
the structure of legislative texts is controlled by the administrative officials drafting the rules.
Therefore, \emph{hierarchy}, \emph{reference}, and \emph{sequence} within a corpus of legislative documents contain information about the content of the corpus
that is less noisy and easier to parse than its language.
To unlock this information for large-scale comparative and dynamic analysis,
we model a body of legislation at a certain point in time as a document collection following the Document Object Model (DOM) standard \cite{domspec} (for our domain-specific XML Schema Definition [XSD], see Section~2.4 of the~\suppi).
With each document collection, we associate four graphs
as depicted in Figure~\ref{fig:conceptual_sequence_graph}~(a),
whose formal definitions are given in Section~\ref{subsection:methods:modelling}.
Our simplest graph is the \emph{hierarchy graph},
which models the inclusion relationships between the structural elements of legal texts.
It is a subgraph of the \emph{reference graph}, which models inclusion and cross-reference relationships.
From a network science perspective, the reference graph is perhaps the most intuitive representation of a legislative document collection, and all of our other graphs can be derived from it.
The \emph{sequence graph} contains only the \emph{seqitems} from the reference graph,
which are connected by cross-reference edges and bidirectional \emph{sequence edges}
(Section~\ref{subsection:methods:modelling} introduces a parametrized definition of this graph for greater analytical flexibility).
The cross-reference edges are unweighted,
while the sequence edges have weights proportional to the distance between their endpoints in the undirected version of the hierarchy graph
(e.g., a sequence edge between Section $i-1$ and Section $i$ in Chapter $A$ weighs more than a sequence edge between Section $i$ in Chapter $A$ and Section $i+1$ in Chapter $B$).
The sequence graph expresses how legal practitioners work with a legal text (i.e., they approach a topic through one particular rule,
scan its vicinity as long as it is also hierarchically close,
possibly follow a cross-reference,
then scan the hierarchically close vicinity of a referenced rule).
Finally, we define \emph{quotient graphs} based on attributes attached to the elements of our reference graphs.
In these graphs, all elements with the same attribute value(s) (e.g., all \emph{seqitems} belonging to the same Chapter) are collapsed into one node,
and edges are rerouted accordingly.

The graphs sketched above allow us to compare legislative document collections both \emph{horizontally} (i.e., across nations) and \emph{vertically} (i.e., across time).
In particular, hierarchy graphs and reference graphs let us track basic statistics over time (cf. Section~\ref{subsection:methods:growth}),
which change when lawmakers add, update, or delete legal rules as depicted in Figure~\ref{fig:conceptual_sequence_graph}~(b).
Sequence graphs help us align basic elements of legal texts across years (cf. Section~\ref{subsubsection:methods:temporal}).
Along with quotient graphs, they also facilitate the reorganisation of legislative materials via graph clustering (cf. Section~\ref{subsubsection:methods:clustering}),
where they allow us to focus on different topics or levels of granularity depending on the research question to be investigated.
To the best of our knowledge, there exists no comparably flexible explicit model for legislative document collections in the document network analysis literature.
Since we do not use all features of the model in our analysis,
exploiting the power of our data model to a greater extent is a natural direction for future work (see Section~\ref{section:discussion} for details).

\subsection{Substantial growth in volume, connectivity, and hierarchical structure}
\label{subsection:growth}

The data model introduced in Section~\ref{subsection:model} enables us to track the development of our legislative corpora over time.
As Table~\ref{tab:descriptive-statistics} shows, the absolute size of these corpora has grown substantially in the past two and a half decades,
whether measured by the number of tokens (whitespace-delimited chunks of text that roughly correspond to words),
the number of structural elements, or the number of cross-references contained therein.
Judging merely by the number of tokens,
in both jurisdictions,
the law in 2018 is more than $1.5$ times as large as the law in 1994.
Given the fact that the legal systems of both countries were already fully developed twenty-five years ago,
the sheer magnitude of this growth is striking.

Inspecting the statistics in Table~\ref{tab:descriptive-statistics} along with the relative growth over time illustrated in Figure~\ref{fig:legislative-growth}
further reveals two distinct growth patterns:
In the United States, the number of tokens and the number of cross-references grow at the same rate,
which is considerably lower than the growth rate for the number of structural elements.
In contrast, the German corpus exhibits its highest growth rate for the number of cross-references,
and growth in the number of tokens is noticeably faster than growth in the number of structural elements.
Thus, the volume increase in the federal statutory legislation of the United States is accompanied primarily by an increase in the number of entities,
whereas the volume increase in the federal statutory legislation of Germany is accompanied primarily by an increase in the number of relationships in the legislative network.
This suggests that cross-references and hierarchical elements function as substitutes when it comes to integrating new content into an existing legal corpus.

However, increasing the number of hierarchical elements or the number of cross-references also tends to correlate with a decrease in navigability as it may be indicative of content fragmentation:
Anyone trying to understand a legal rule will more often be forced to combine information from multiple places in the law to obtain a complete picture of its content.
This difficulty is only exacerbated by the dominant legal information systems,
which often force users to click through hierarchies of legal elements and seldom allow them to display a custom selection of structural units in a single browser tab for joint appreciation.
Therefore, our statistics for both countries support the intuition that their legislative apparatuses are growing also in complexity---%
although the complexity increase is driven by different design choices in both jurisdictions.
While the difference in legislative drafting styles is of natural interest for comparative legal scholarship,
the common growth trend we observe begs a broader question:
What is its source?

This question has no meaningful answer within the current formal organisation of the legislative materials.
In fact, the US Code as the primary organisational system for legislation in the United States has barely changed in the time period under study.
The US Code comprised 50~Titles in 1994;
since then, three Titles have been added (51, 52, and 54),
two formerly empty Titles have been reassigned (6, 34),
and two Titles have experienced small name changes (36, 47).
Apart from that, US federal legislation has been codified in the same Titles since 1994,
with the total number of Chapters existing across all Titles rising from 2000 to 2723 (for an average growth of 30 Chapters per year).
Figure~\ref{fig:us-tokens-per-title} localizes the growth over four-year intervals within the existing,
content-based organisation of the US code.
Based on raw token counts (excluding notes and appendices),
the biggest growth has occurred in Title~42 (The Public Health and Welfare),
Title~7 (Agriculture),
and Title~15 (Commerce and Trade).
The relative growth in the number of tokens has been highest in
Title~4 (Flag and Seal, Seat of Government, and the States),
Title~46 (Shipping),
and Title~7 (Agriculture).

This gives an interesting first impression on the macro level,
but the Title headings are so general,
and the content placed in the individual Titles is so diverse (e.g., the current Title~42 contains provisions on~Social Security [Chapter~7], Energy Policy [Chapter 134], and Aeronautics and Space Activities [Chapter 155]),
that it tells us little about the triggers and the nature of the growth we observe.
The situation further deteriorates if we want to compare the German developments with those in the United States:
Germany does not codify its federal legislation in a single official collection but publishes only individual acts and classifies them into subject areas for navigation
(details can be found in Section~1.2 of the~\suppi).
The number of consolidated acts with more than $500$ characters (roughly a paragraph, effectively excluding laws with purely formal content) grew from around $1550$ to over $1800$ in the period from 1994 to 2005,
then was intentionally shrunk to around $1550$ until 2011,
and has resumed slow growth since 2011, reaching around $1600$ in 2018---%
so we do not even see a monotone growth pattern in this data.
To uncover the sources of the growth of the law,
and compare our findings between the United States and Germany,
we thus need to reorganise the legislative materials of both nations.

\subsection{Clustering for comparative and dynamic analysis}
\label{subsection:reorganisation}

A first, straightforward way to reorganise the US Code is to aggregate it not at the Title level but rather at the Chapter level.
This is especially convenient because the number of Chapters in the US Code is comparable to the number of individual laws in Germany,
which we only break up into smaller units if they contain several Books (a common feature of large German codifications such as the German Civil Code [BGB] and the German Commercial Code [HGB]).
The node-link diagrams of the quotient graphs corresponding to this reorganisation for the United States and Germany in 1994 and 2018 are shown in Figure~\ref{fig:us-de-chapter-quotient}.
In these graphs, nodes share the same colour if they belong to the same \emph{cluster family}.
Broadly speaking, cluster families are sets of clusters (a cluster is a set of nodes),
mostly from different snapshots,
which contain many identical, similar, or related rules (cf. Definition~\ref{def:cluster-family} in Section~\ref{subsubsection:methods:temporal})%
---and as such, they approximate legal topics.
We identify cluster families using node and cluster alignments (cf. Section~\ref{subsubsection:methods:temporal}).
Cluster families will help us assess which legal topics are driving the growth we report in Section~\ref{subsection:growth}.
The cluster family colouring scheme will be used in all remaining graphics;
a full legend mapping colours to legal topics can be found in Section 5.1 of the~\suppi.
In Figure~\ref{fig:us-de-chapter-quotient},
nodes of the same colour can generally be thought of as belonging together (i.e., \emph{same colour} $\Leftrightarrow$ \emph{(roughly) same legal topic}),
and node colours can be compared across years but not across nations (e.g., the legal topic of red nodes in the graphs for the United States may differ from the legal topic of red nodes in the graphs for Germany).

The node-link diagrams in Figure~\ref{fig:us-de-chapter-quotient} allow us to identify interesting connections between individual parts of the law at the Chapter level---%
e.g., Book Three of the German Commercial Code (HGB/Drittes Buch), which regulates books of accounts, is much more central as a reference target in 2018 than it was in 1994,
and the central role of Title 42, Chapter 6 of the US Code in 1994 (The Children's Bureau) has been taken by Title 42, Chapter 6A (Public Health Service) and Chapter 7 (Social Security) in 2018.
But since there are well over $1000$ nodes in both jurisdictions,
the quotient graphs are difficult to analyse in their entirety,
related content remains scattered over different nodes,
and the changes between snapshots are difficult to trace.
Hence, the main conclusion from Figure~\ref{fig:us-de-chapter-quotient} is that the quotient graphs by Title/Chapter (United States) and Law Name/Book (Germany) alone are unsuited to unveil the temporal dynamics of legislative corpora in full detail.
To coherently group related content and investigate change over time,
we thus need a more sophisticated reorganisation method.
Therefore, we cluster our annual Chapter quotient graphs for each country based on their cross-references.

In (non-overlapping) graph clustering,
the goal is to divide the elements of the graph (typically the nodes, here: Chapters in the United States and Books or individual laws in Germany)
into groups such that elements in the same group are relatively densely connected,
whereas elements in different groups are relatively sparsely connected.
We use the \emph{Infomap} algorithm based on the \emph{map equation} \cite{rosvall2008,rosvall2009} to find our clusters for three reasons.
First, in using random walks (i.e, sequences of random steps using the edges of the graph) as a basic ingredient,
\emph{Infomap} mimics how lawyers navigate legal texts.
The legal navigation process is similar to how scholars navigate papers or web surfers navigate the World Wide Web (WWW),
with the additional quirk that sequence edges play a large role in steering the search
(think of reading the next paper in the special issue of a journal or clicking through a series of blog posts).
Second, by leveraging the connection between finding clusters in a graph and minimizing the description length of a random walk on the graph, \emph{Infomap} has a solid information-theoretic foundation.
And third, the algorithm scales to large graphs.

When running \emph{Infomap}, we use the default configuration, with one exception:
We pass $100$ as a parameter for the preferred number of clusters,
which roughly corresponds to the number of top-level categories with which legal databases structure their content.
This parameter choice allows us to determine the legal topics driving the growth we observe at a sufficiently high granularity while maintaining an overview of the entire corpus,
and it protects against sudden jumps in the cluster granularity between years due to small differences in the description lengths of competing solutions, which are more likely to occur when no preferred cluster size is given.
As detailed in the sensitivity analysis included in Section~4.1 of the~\suppi,
the precise number of input clusters has little impact on the overall results,
as long as the numbers of clusters are comparable across years (e.g., tracing changes between a clustering in which most of the text is contained in $5$ clusters and a clustering with $50$ clusters is an invidious task).
To increase the stability of our results, we obtain our final clustering for each country and year as the consensus clustering of $1000$ \emph{Infomap} runs,
where the consensus clusters are the connected components of a graph whose nodes are the quotient graph nodes,
and whose edges indicate which nodes co-occurred in the same cluster in $95~\%$ of all runs.
As shown in Section~4.2 of the~\suppi,
there is little variance both across those runs and across multiple consensus clusterings using $1000$ runs to find the consensus,
indicating that our results are robust against the randomness inherent in the \emph{Infomap} algorithm.

Based on our consensus clusterings,
we can compute alignments between the clusters we find in subsequent snapshots for each of our countries.
These \emph{cluster} alignments allow us to track the temporal evolution of individual clusters.
They are based on \emph{node} alignments of a fine-grained variant of sequence graphs,
which leverage that most rules do not change most of the time---%
i.e., we can match many \emph{seqitems} between adjacent snapshots based on their (nearly) identical texts or (nearly) identical keys.
For details on our node alignment heuristic and the cluster alignment procedure that builds upon it, see Section~\ref{subsubsection:methods:temporal}.

The fine-grained year-to-year cluster alignment facilitates a meso-level analysis of the growth reported in Section~\ref{subsection:growth}.
Figure~\ref{fig:sankey} provides a comprehensive overview of the aligned clusters for the entire United States corpus (an analogue figure for the German corpus can be found in Section~3.3 of the~\suppi):
The corpus in a certain year is modelled by a horizontal bar,
which is composed of blocks representing clusters with width proportional to the number of tokens they contain.
The year-to-year movement of tokens between clusters---%
i.e. the volume of text associated with one cluster in one year and another cluster in the next year, identified using the alignment between the items below the \emph{seqitem} level (\emph{subseqitems}) of the clusters---%
is indicated by splines connecting the blocks of adjacent years,
where we only plot token movements corresponding to at least $15~\%$ of the tokens from both the ingoing and the outgoing cluster to filter out noise and isolate largely self-contained strands of the law as cluster families (see also Section~\ref{subsubsection:methods:temporal}).
The width of the plotted splines is again proportional to the number of tokens moving.
Within each horizontal bar,
the blocks representing the clusters are sorted in descending order by their size,
i.e., the clusters with the largest numbers of tokens are always pushed to the left.
To reduce visual clutter, we summarize very small clusters in one  \emph{miscellaneous} cluster.
This cluster is always the rightmost cluster, depicted in light grey;
more information on its contents can be found in Section~5.2 of the~\suppi.
The blocks and splines belonging to the $20$ largest cluster families are uniquely coloured,
whereas smaller cluster families are alternately coloured in alternating greys.
The absolute growth of the United States corpus is reflected in the increasing width of the bars over time,
whereas changes in cluster compositions and relative cluster sizes are visible as diagonal year-to-year movements.

Inspecting the numbers behind Figure~\ref{fig:sankey},
we find that our clusters grow linearly with respect to their size,
i.e., bigger clusters gain more tokens than smaller clusters,
but that the growth rates differ depending on the legal topic represented by the cluster.
To understand which legal topics are driving the overall growth,
we determine the growth rate of our cluster families via an ordinary least squares (OLS) regression.
We select the 20 largest cluster families for both countries,
where the size of a cluster family is the size of its largest cluster (measured in tokens), called its \emph{leading cluster}.
For each of these cluster families, we inspect its content composition,
and label it with the dominant legal topic.
More information on our labelling process, including a list of all labels, can be found in Section~5.1 of the~\suppi.
Together, the labelled cluster families account for roughly $50~\%$ of the total growth in the United States and roughly $80~\%$ of the total growth in Germany.
Figure~\ref{fig:legislative-growth-cluster} displays a selection of the most and least growing cluster families in the United States and Germany,
while detailed results can be found in Section~3.4 of the~\suppi.
The colouring scheme for the United States is identical to that used in Figure~\ref{fig:sankey},
while the colours for Germany are chosen to match those for the United States for similar topics and avoid colour clashes otherwise.

Notably, in both jurisdictions,
growth rates are highest for the cluster families concerning social welfare and financial regulation,
and cluster families dealing with taxes, environmental protection, and immigration also display strong growth in both countries.
In addition to these similarities, we also find some differences in the growth patterns of both countries.
As one might expect,
the United States has cluster families concerned with Native Americans (shrinking) and student loans (growing),
while no analogous families exist in Germany.
Likewise, Germany has a cluster family concerned with war restitution (shrinking) that has no counterpart in the United States.
The unmatched growth of the criminal law and corporate and insurance law cluster families in Germany, which may be counterintuitive at first sight,
is probably a result of differences in legislative competencies (criminal law and corporate law including insurance are largely state law in the United States, while they are federal law in Germany).
In addition, insurance regulatory law on the federal level in the United States is primarily enforced through federal regulations,
which are not part of our dataset as they are kept in a separate collection (the Code of Federal Regulations).
That the United States has a growing cluster family concerned, inter alia, with foreign assistance and export control will not surprise those working in international development or international politics,
and the fast-growing cluster dealing with renewable energy, power grid regulation, and related administrative procedures in Germany will not surprise those following the nation's political discourse (although in both cases, the unexpectedness could be impacted by hindsight bias).
Overall, the differences we observe seem to be in line with differences in the prominence of certain policy debates in both countries,
reflecting social, political, and cultural divergences.
As such, they invite in-depth analysis by subject matter experts.

Finally, the year-to-year cluster alignment underlying Figure~\ref{fig:sankey} allows us to observe different types of growth.
For example, some clusters or cluster families witness \emph{intrinsic growth},
i.e., growth by addition of tokens without large gains of tokens from other areas;
the cluster family containing veteran's benefits is a case in point,
as is a cluster family on small business support and civil and military public procurement.
Such cluster families, which have been rather self-contained in the past $25$ years, address issues of sustained or increasing societal importance.
Other clusters or cluster families, however, witness \emph{extrinsic growth},
i.e., growth by gaining tokens from clusters in other families.
One example is a United States cluster concerned with the environmental protection of national parks and rivers,
which grew substantially when rules about national forests as well as prospecting permits and leases joined it from clusters concerned with forestry and mining,
indicating a shift in perspective from land use as resource exploitation to land use as resource conservation.
To capture such differences in change processes,
an elaborate cluster change event taxonomy is needed.
Such a taxonomy could build on the work by Palla et~al. \cite{palla2007},
and developing it provides an interesting opportunity for further research.


\begin{chapter}{\LaTeX}

Producing high quality mathematical documents that show equations, figures and references clearly is very difficult in standard word processing packages. Instead the standard is to use \LaTeX, a ``document prepartion language''. Most notes, such as these, and mathematical papers, use \LaTeX.

\section{What is \LaTeX}

\LaTeX\ takes a plain text file and converts it into a document, often in PDF format, containing all the equations, figures and cross-references. In this sense it's similar to Python: you start from a plain text file and \emph{build} it to produce a result.

\LaTeX\ documents are often complex, but many are available online. A standard technique is to find a \LaTeX document that does what you want online, and take the key commands from that.

\section{Installing or finding}
\label{sec:installing}

\LaTeX\ is free software and there's lots of available implementations. As with Python, a \LaTeX\ document is plain text and can be written using any text editor. However, specific \LaTeX\ editors can help in rapidly writing documents with fewer errors.

\subsection{University machines}

Use the search function to look for \texttt{TeXnicCentre}. When first running, choose all the default options. Some of the instructions below on building a document are specific to TeXnicCentre, as it's provided on the university machines, but similar methods should work in all editors.

\subsection{Personal machines}

If using a Linux or Mac, \LaTeX\ should be installed automatically. There are many editors you can use -- \href{http://www.xm1math.net/texmaker/}{TeXMaker} is one example -- and you can experiment with which you prefer. If using a Windows machine, you can freely download \href{http://www.texniccenter.org/}{TeXnicCentre} which will install \LaTeX\ for you, or use TeXMaker as above.

\subsection{Online}

There are browser-based \LaTeX\ editors which can be used, such as \href{https://www.overleaf.com/}{Overleaf} and \href{https://www.sharelatex.com/}{ShareLaTeX}. There are obvious advantages -- there's no need to install anything, it's backed up externally, and it builds the document for you. The balancing disadvantages are also there -- needs a network connection, the online editor isn't as full featured as special desktop versions, and keeping your work private requires paying.

Overleaf also \href{https://www.overleaf.com/latex/learn/free-online-introduction-to-latex-part-1}{hosts an online tutorial on \LaTeX} that works through the essential points.

\subsection{\LaTeX\ in other formats}

A full \LaTeX\ document can be very complex as it controls \emph{every} aspect of the document appearance. Many simpler document formats have been written, often based around \href{http://daringfireball.net/projects/markdown/}{Markdown} (see also \href{https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet}{this cheatsheet}). To typeset mathematics within these document formats, \LaTeX\ \emph{syntax} is used: one particular example is \href{https://www.authorea.com}{Authorea} where a simple Markdown-based document format can be mixed with \LaTeX\ syntax to create documents both for online and offline use. We have already seen how \LaTeX\ syntax can be used within, e.g., \texttt{matplotlib}.

\section{Getting Started}

\subsection{A basic document}

Download a simple \LaTeX\ document \href{https://raw.githubusercontent.com/IanHawke/maths-with-python/master/latex/BasicLatex.tex}{from this link}. Open it in whichever editor you are using, and build it so you can see the output (which should look like \href{https://github.com/IanHawke/maths-with-python/raw/master/latex/BasicLatex.pdf}{this pdf file}). If using TeXnicCentre on the University machines, you should be able to do this by running ``Build and View'' from the ``Build'' menu.

You should compare the document with the built PDF file. In particular note, as stated in the document,
%
\begin{itemize}
  \item that anything before the ``\verb|\begin{document}|'' (the \emph{preamble}) doesn't show explicitly, but changes global properties of the document,
  \item how whitespace works,
  \item how anything ``special'' starts ``\verb|\|'',
  \item how quote characters behave (compare with ''this''),
  \item how curly braces \verb|{| and \verb|}| are used without
    appearing,
  \item how \emph{environments} always \verb|\begin| and
      \verb|\end|,
  \item and how the \verb|\section| command works.
\end{itemize}
%
You should edit and re-build the document so that you can see the effects of adding standard text, new sections (or subsections), and so on.

\subsection{Mathematics and references}

Now download \emph{both} \href{https://raw.githubusercontent.com/IanHawke/maths-with-python/master/latex/BasicLatexBibtex.tex}{this \LaTeX\ document} and \href{https://raw.githubusercontent.com/IanHawke/maths-with-python/master/latex/nummeth.bib}{this bibliography file}. The bibliography file must be saved in the same directory as the \LaTeX\ document, must have a \texttt{.bib} extension, and (in this case) should be called \texttt{nummeth.bib}. Again, build this document and view the results.

\subsubsection{The build process}

Some editors will (or will let you) build the document one step at a time. In this case you may have perform multiple build steps. For example, the first build step will produce a document that \href{https://raw.githubusercontent.com/IanHawke/maths-with-python/master/latex/BasicLatexBibtex_pass1.pdf}{looks like this}. At this point none of the cross-references are correct, but appear as ``\textbf{?}'', and there is no bibliography. The second build step will create the bibliography, but will not change the document. The third build step will produce a document that \href{https://raw.githubusercontent.com/IanHawke/maths-with-python/master/latex/BasicLatexBibtex_pass2.pdf}{looks like this}. At this point cross-references to sections and equations are correct, and the bibliography is included. However, the cross-references to the bibliography are not correct. A fourth build step will produce a document that \href{https://raw.githubusercontent.com/IanHawke/maths-with-python/master/latex/BasicLatexBibtex_pass3.pdf}{looks like this}, with all references correct.

\subsubsection{Mathematics}

To include mathematical notation inline, commands should be placed between dollar signs, \verb|$...$|, so that \verb|$\pi$| gives $\pi$. To create a \emph{displayed} equation, use the \texttt{equation} environment, as in
%
\begin{verbatim}
\begin{equation}
  \label{eq:label_example}
  x = y + z.
\end{equation}
\end{verbatim}
%
which gives
%
\begin{equation}
  \label{eq:label_example}
  x = y + z.
\end{equation}
%
Note that the ``\verb|\label{...}|'' command allows the equation to be cross-referenced using the ``\verb|\ref{...}|'' command, giving equation \ref{eq:label_example}.

As seen above, Greek characters in mathematics are the letter preceded by the backslash, so \verb|$\theta$| gives $\theta$. To produce subscripts, use the underscore \verb|_|, and for superscripts the caret \verb|^|. So \verb|$x_1^2$| gives $x_1^2$. To group characters together, use the curly braces \verb|{}|. You need to do this, for example, if you want more than one character to appear in sub- or superscripts. Hence \verb|$F_n-2$| gives $F_n-2$, but \verb|$F_{n-2}$| gives $F_{n-2}$.

Standard mathematical commands and symbols are also preceded by backslashes, such as \verb|$\int$| ($\int$), \verb|$\sum$| ($\sum$), and \verb|$\infty$| ($\infty$). A more complete list \href{https://en.wikibooks.org/wiki/LaTeX/Mathematics}{can be found online}, and for more obscure symbols the online \href{http://detexify.kirelabs.org/classify.html}{handwriting recognition trick} is very useful.

\subsection{Cross-referencing and bibliographies}

We saw above how the \texttt{equation} environment could include a \verb|\label| which allowed it to be cross-referenced using the \verb|\ref| command. This can be done for any environment which takes a number; for example, the section on installing \LaTeX\ above has the label \verb|\label{sec:installing}|, and can be cross-referenced using \verb|\ref{sec:installing}|, giving section~\ref{sec:installing}.

For citing references -- books, papers, websites etc.\ -- we instead use the \verb|\cite| command. This looks for the article within the \emph{Bibtex} file that has the specific \emph{key}. In the document here, the command \verb|\cite{godunov}| tells \LaTeX\ that the key is ``\verb|godunov|'', and the command \verb|\bibliography{nummeth}| tells it that the Bibtex file is in \texttt{nummeth.bib}.

The structure of the Bibtex file can look complex. There are many shortcuts -- for example, by searching for the reference on Google Scholar, and then clicking on the ``Cite'' link, it will give the Bibtex entry that you can simply copy and paste into your file. For alternatives, see section~\ref{sec:Citations}.

\LaTeX\ is most useful for creating long documents (journal articles, theses, etc.) containing substantial mathematics. Sectioning, cross-referencing and bibliographies we have already seen. There are a number of additional features to make the creation of long documents easier.

These are gathered in a logical order below, but for most purposes the discussion of commands (section~\ref{sec:commands}), provided packages (section~\ref{sec:packages_provided}), and modularity (section~\ref{sec:modularity}) will be of most use.

\section{Commands}
\label{sec:commands}

\subsection{Defining commands}
\label{sec:commands_defn}

Firstly, user-defined commands can replace long sequences with a short, or more memorable, version. For example, a simple partial derivative
%
\begin{equation}
  \label{eq:example_pd_1}
  \frac{\partial y}{\partial x}
\end{equation}
%
can be written \verb|\frac{\partial y}{\partial x}|. The equivalent shorthand
%
\begin{equation}
  \label{eq:example_pd_2}
  \pda{y}{x}
\end{equation}
%
can be written, for example, \verb|\pda{y}{x}|. This is both clearer and shorter.

The command \verb|\pda| is defined in the \emph{document preamble}: after the \verb|\documentclass| command but before the \verb|\begin{document}| statement. The definition used here is
%
\begin{center}
  \verb|\newcommand{\pda}[2]{\frac{\partial {#1}}{\partial {#2}}}|
\end{center}
%
which requires some explanation:
\begin{itemize}
\item Obviously \verb|\newcommand{\pda}| defines the new command
  \verb|\pda|.
\item The statement \verb|[2]| says that the command has two arguments
  (in the example \verb|\pda{y}{x}| the arguments are \verb|y| and
  \verb|x| respectively). For commands that take no arguments (e.g.\
  where you are just defining a shorthand, such as the command
  \verb|\uos| defined at the start of this document which expands to
  \uos) this part is absent.
\item The rest of the line defines the command, and is enclosed in
  braces \verb|{...}| for safety. The arguments are referred to by the
  \verb|#| statements; e.g., in the example above \verb|#1|
  corresponds to \verb|y| and \verb|#2| to \verb|x|. Again, the
  arguments are typically enclosed in braces \verb|{...}| for safety.
\end{itemize}

\subsection{Redefining commands}
\label{sec:commands_redefn}

Sometimes a command already exists with the shorthand name that you want to use, but does not do what you expect or want. In this case it can be redefined using the command \verb|\renewcommand|. This works in exactly the same way as \verb|\newcommand|, except the command must already exist (note that if the command already exists then trying to (re)define it with \verb|\newcommand| will give an error).

The classic example is typesetting vectors using the \LaTeX\ command \verb|\vec|. By default this puts an arrow above the argument, similar to (but smaller than) the command \verb|\overrightarrow| which produces, e.g., $\overrightarrow{AB}$. Many people typeset vectors use bold fonts, which can be done using e.g.\
%
\begin{center}
  \verb|\renewcommand{\vec}[1]{\mathbf{#1}}|
\end{center}
%
which produces the output $\vec{a}$.

\section{Environments}
\label{sec:environments}

As we have seen, commands are not the only things that \LaTeX\ provides. It also provides \emph{environments} which are enclosed within \verb|\begin{...}| and \verb|\end{...}| statements. Standard environments are \verb|equation| and \verb|document|.

Just as with commands it is possible to define new environments (using the \verb|\newenvironment| command in the document preamble) or redefine old ones (using the \verb|\renewenvironment| command). The usage is similar to that of \verb|\newcommand| as well: the main difference is that instead of defining what the command does, you define what should happen before entering and after exiting the environment.

A simple example is
%
\begin{verbatim}
\newenvironment{solution}[1]{%
  \begin{center}
    \rule{#1}{.1pt}
  \end{center}
}{%
  \begin{center}
    \rule{0.9\textwidth}{.1pt}
  \end{center}
}
\end{verbatim}
%
which defines a \verb|solution| environment.

The explanation of each piece is as follows:
\begin{itemize}
\item \verb|\newenvironment{solution}|: the definition of the name of the new environment.
\item \verb|[1]|: the number of arguments pass in (here 1).
\item \verb|{\begin{center} \rule{#1}{.1pt} \end{center} }|: in the definition these are spaced using carriage returns and comment markers for clarity, but by matching the curly braces this can be seen to be just one argument. These are the commands issued before entering the environment. \verb|#1| is the first argument passed in.
\item \verb|{\begin{center} \rule{\rule{0.9\textwidth}{.1pt} \end{center} }|: again this was spaced for clarity in the definition. These are the commands issued after exiting the environment. No arguments can be used at this point.
\end{itemize}

This environment, used as
%
\begin{verbatim}
\begin{solution}{0.9\textwidth}
  This is the solution.
\end{solution}
\end{verbatim}
%
produces the output
%
\begin{solution}{0.9\textwidth}
  This is the solution.
\end{solution}
%

\section{Packages}
\label{sec:packages}

In essence a package is just a file containing a number of useful commands and environments, as explained in sections~\ref{sec:commands} and \ref{sec:environments}. So, rather than hand-defining a large number of commands you can import them all by including code such as
%
\begin{verbatim}
\usepackage{amsmath}
\end{verbatim}
%
in the document preamble.

This is particularly important when producing journal articles. Many journals require (or strongly encourange) you to submit articles fitting in with their in-house style. Many scientific journals will therefore provide a \LaTeX\ package to use in the production of your article.

\subsection{Useful packages}
\label{sec:packages_provided}

Most \LaTeX\ distributions will include the following packages which are extremely useful:
\begin{itemize}
\item \texttt{graphicx} or \texttt{graphics}: commands to import and manipulate graphics files.
\item \texttt{amsmath} (and \texttt{amssymb} and \texttt{amsthm}): The American Mathematical Society \LaTeX\ package. A large number of useful commands, especially for aligning equations (see \verb|\align| and related).
\item \texttt{fancyhdr}, \texttt{enumerate}, \texttt{caption}, \texttt{geometry}: control the document layout and appearance in a more transparent fashion. \texttt{fancyhdr} in particular is useful for producing headers for theses.
\item \texttt{babel}: if you want to typeset anything in a language other than English, this package provides a lot of support.
\item \texttt{hyperref}: transforms citations and cross-references into hyperlinks. Particularly useful when compiling direct to PDF.
\item \texttt{natbib} or \texttt{biblatex}: most will find the default citation styles sufficient (or, for articles, journals will frequently provide their own). If you require something more controllable then these packages give you that power (\texttt{natbib} is much older and practically obsolete, but has lots of examples and is in widespread use. \texttt{biblatex} is much newer and very powerful but with far fewer examples and requires a modern \LaTeX\ distribution).
\end{itemize}

\subsection{Creating packages}
\label{sec:packages_creating}

At its heart a package just contains the commands you would have placed in the document preamble. However, there are a few additional commands and points to be careful of.

\begin{itemize}
\item \verb|\ProvidesPackage{<name>}[<string>]|: this command defines the name of the package \verb|<name>| (which should match its filename) and an optional description \verb|<string>|.
\item \verb|\RequirePackage{<package>}|: instead of putting \verb|\usepackage{<package>}| inside a package, this command allows \LaTeX\ to check if \verb|<package>| has already been loaded, and if not, does so.
\item \verb|\DeclareOption|, \verb|ExecuteOptions|, \verb|\ProcessOptions|: allows you to pass options to the package (and hence options to commands in the package).
\end{itemize}

Package files should have a \verb|.sty| extension.

\section{Modularity}
\label{sec:modularity}

Long documents are typically composed of many chapters and sections using a variety of data. Working on a single long document is inefficient and confusing. It is better to split the document into multiple chunks corresponding to the structure of the document. \LaTeX\ has two ways of doing this.

\subsection{Input}
\label{sec:modularity_input}

The command \verb|\input| simply imports a file, as if it were ``cut and paste'' into the current document. This could be done right here, with a file imported into the middle of a paragraph. The \verb|\input| command takes the name of the file to be imported without the \texttt{.tex} extension. Once the file is imported the document continues as normal.

The \verb|\input| command is somewhat inflexible. My personal viewpoint is that its main use is for importing data produced by or stored in external formats. For example, if you have a code that produces a table with 50 entries, it will be safer to make your code output the results directly into a \LaTeX\ table format which can then be \verb|\input| into a document, rather than trying to copy all the data by hand.

\subsection{Include}
\label{sec:modularity_include}

The alternative to the \verb|\input| command is the \verb|\include| command. Its use is exactly the same as the \verb|\input| command -- the only argument is the name of the file to be included, without the \texttt{.tex} extension. There are two main differences.

The first difference, as is clear from this document, is that the text imported via the \verb|\include| command always starts on a new page, and there will be a new page inserted (via a page break) after the included content as well. For this reason the \verb|\include| statement is typically used in long documents -- reports or theses -- where each included file contains a full chapter.

The second difference is the main advantage of the \verb|\include| command. You can selectively include only certain files whilst leaving all the \verb|\include| statements in place. For example, consider an outline document
%
\begin{verbatim}
\documentclass{book}

\includeonly{chapter2}

\begin{document}

\include{chapter1}
\include{chapter2}
\include{chapter3}

\end{document}
\end{verbatim}
%
This document should consist of three chapters. If we are working just on chapter 2 then we can concentrate solely on that by using the \verb|\includeonly| command to produce only the output for that chapter. However, all cross-references to the other chapters will still be correctly resolved (provided that they have been compiled at least once).

\section[Additional commands]{Additional commands for long documents}
\label{sec:additional}

This contains a list of commands that are often useful for long reports and theses.
%
\begin{itemize}
\item \verb|\maketitle|: Produces a title page based on the \verb|\author|, \verb|\title| and \verb|\date| (which must be set after the \verb|\begin{document}| but before the \verb|\maketitle|).
\item \verb|\appendix|: as just used here, this converts the section or chapter numbering to use letters instead of numbers.
\item \verb|\tableofcontents|: inserts a table of contents containing the titles of chapters, sections, subsections (there are parameters to control the depth).

Note that if a title is extremely long it may not fit in the table of contents (or in the headers). All sectioning commands provide an option for a short title to be used in headers, table of contents and similar circumstances. An example is the title for this appendix where a short title of ``Additional commands'' can be produced using
\begin{verbatim}
\section[Additional commands]{Additional commands for long documents}
\end{verbatim}
\item \verb|\listoffigures|, \verb|\listoftables|: inserts the appropriate lists based on the captions of figures and tables. Here you will almost certainly want to use the optional short form for the captions.
\item \verb|\frontmatter|, \verb|\mainmatter|, \verb|\backmatter|: only avaiable for \verb|book| class, this explicitly changes the page numbering to Roman letters or Arabic numerals respectively.
\end{itemize}

\section{Citations and bibliographies}
\label{sec:Citations}

One of \LaTeX's strengths is its cross-referencing. However, the mechanism for including and organizing the bibliography is out-dated, so requires a little work to use in the best fashion.

The command to reference a bibliography citation is \verb|\cite|. Some
additional packages (such as \verb|natbib|) introduce additional
citation commands which allow for more control of the appearance of
the reference within the text. The \verb|\cite| command takes at least
one argument, which is the \emph{key} to the article in the
bibliography.

This section introduces the two most basic ways of building a bibliography in \LaTeX. Only the \verb|Bibtex| method of section~\ref{sec:bibtex} is recommended, and it is best to look at tools mentioned later for ease. Later sections will mainly focus on tools to build, maintain and control bibliographies using the underlying \verb|Bibtex| technology.

Note that when using \LaTeX\ to build a document containing a bibliography it is usually necessary to build the document at least twice, and usually three times. On the first pass it looks in the document and finds which citations are needed. On the second pass it looks in the database and extracts the citations, putting them in the appropriate form. The third pass finalizes the document.

\subsection{Direct inclusion}
\label{sec:Direct}

The bibliography can be written directly into the \LaTeX\ document using the commands (for example)
%
\begin{verbatim}
\begin{thebibliography}{99}

\bibitem{Duncan98} R. C. Duncan, Astrophys. J. {\bf 498}, L45 (1998).

\end{thebibliography}
\end{verbatim}
%
In this case there is only one item in the bibliography. The \verb|{99}| at the beginning gives the maximum number of entries in the bibliography -- this could be increased if needed. The article key is here \verb|Duncan98|, and would be cross-referenced in the text using \verb|\cite{Duncan98}|.

The advantages of this citation method are
\begin{enumerate}
\item speed; you can directly and rapidly change the document,
\item control; you can control exactly how it appears.
\end{enumerate}

The disadvantages are numerous.
\begin{enumerate}
\item Reuse; for every document you need to copy the reference without error.
\item Modification; for every different use you need to manually change the appearance of the reference, and do it consistently.
\item Completeness; there is no simple way to store all additional information about the reference that is not explicitly required (e.g.\ the abstract).
\item Errors; if you delete the reference from the text you must consistently remove it from the bibliography. If an unpublished article is published, you must consistently update the reference in all documents.
\item Etc...
\end{enumerate}

\subsection{Bibtex}
\label{sec:bibtex}

\verb|Bibtex| was the original solution for the \LaTeX referencing issues outlined above. An example of using \verb|Bibtex| is given in the \verb|BasicLatexBibtex| document, combined with the \verb|nummeth.bib| database file.

In brief, the \verb|Bibtex| file is a database. Written as a plain-text file, each entry is a single reference. An example entry would be
%
\begin{verbatim}
@article{Pareschi2005,
author = {Pareschi, Lorenzo and Russo, Giovanni},
doi = {10.1007/s10915-004-4636-4},
issn = {0885-7474},
journal = {Journal of Scientific Computing},
keywords = {65c20,82d25,ams subject classification,high order shock capturing,
hyperbolic systems with relaxation,kutta methods,runge,schemes,stiff,systems},
month = oct,
number = {1},
pages = {129--155},
title = {{Implicit-Explicit Runge-Kutta Schemes and Applications to
Hyperbolic Systems with Relaxation}},
url = {http://www.springerlink.com/index/10.1007/s10915-004-4636-4},
volume = {25},
year = {2005}
}
\end{verbatim}
%
The \emph{document type} is \verb|article|, as denoted by the \verb|@article|. There are many other possible, including books, reports, theses, unpublished, and many more. The \emph{key} is \verb|Pareschi2005|, to be cited \verb|\cite{Pareschi2005}| in the \LaTeX\ file. Some of the information included is required, but precisely what depends on the document type. For articles the minimum is the key, the author, the journal and the year. All other information \emph{may} be used (if available).

Inside the \LaTeX\ document only two lines are required. For example, in \verb|BasicLatexBibtex| the two lines are
%
\begin{verbatim}
\bibliographystyle{plain}
\bibliography{nummeth}
\end{verbatim}
%
The first controls the appearance of the bibliography; what order the references appear (e.g.\ alphabetical or in citation order), what information is included, and so on. It also controls how the citations appear in the text (e.g.\ author-date or numerical). The second line says that the references are stored in the \verb|nummeth.bib| file. Multiple \verb|bibtex| files can be referenced, separated by commas (e.g. \verb|\bibliography{file1,file2,file3}|).

The advantages of the \verb|bibtex| database are clear.
%
\begin{enumerate}
\item Reuse across multiple documents is easy.
\item Additional information is stored with the reference.
\item Changing styles is simple.
\item Errors can be corrected in a single place.
\end{enumerate}
%

Some disadvantages remain.
%
\begin{enumerate}
\item The \verb|bibtex| database format is difficult to maintain by hand.
\item Control over the appearance of the reference is less straightforward.
\item Producing a database from scratch is a lengthy and tedious process.
\end{enumerate}

\subsection{Constructing and maintaining a database}
\label{sec:maintaining}

When starting you will build your own database from everything you read, and also inherit a database from your supervisor, group and office-mates. Merging disparate databases by hand, and typing all the details of references into a plain-text database, is a recipe for mistakes and a huge waste of time. Better tools include the following.

\subsubsection{Journal websites}
\label{sec:journals}

Most published papers have a webpage through the journal, and many of these will export all of the reference information in a standard format. For \verb|bibtex| this typically means the website sends you a plain text file which you can copy and paste into your database.

It is often the case that a little tweaking of the entry will be required -- frequently the article key is not memorable, and the appearance of special characters can be problematic. But this approach can save considerable time, as well as giving you information (DOI, URLs) that other \LaTeX\ tools can use.

\subsubsection{Endnote and similar}
\label{sec:endnote}

Many people and groups use software such as \href{http://www.endnote.com/}{Endnote} to maintain their bibliographical database. There are free tools to convert between database formats -- see, for example, the \href{http://dret.net/bibconvert/}{ShaRef} service at \verb|http://dret.net/bibconvert/|.

The advantages of packages like Endnote are their wide use (in certain fields), their tools for maintaining the database, and their tools for use with other word-processing packages such as Word. The conversion process will often require a little tweaking, as above.

\subsubsection{Cloud and social reference managers}
\label{sec:cloud}

Online reference managers are available and are, for basic services, often free. These services include the basic functions of desktop packages such as Endnote, but have two major additional advantages. Firstly, the database is stored online and so available to you anywhere, on any device. Secondly, the tools are frequently well integrated with journal websites. This means that saving a reference to the database is just a single button click.

Examples include
%
\begin{enumerate}
\item \href{http://www.citeulike.org/}{CiteULike} at \verb|http://www.citeulike.org/|
\item \href{http://www.mendeley.com/}{Mendeley} at \verb|http://www.mendeley.com/|
\item \href{http://www.zotero.org/}{Zotero} at \verb|http://www.zotero.org/|
\end{enumerate}
%
Each has their own internal database format and will export to other formats, such as \verb|bibtex|, on demand.

The advantages of online reference managers for groups of collaborators and for web integration are obvious; it is definitely worth investigating such tools, and finding out which are standard in your field and group.

\subsection{Controlling the appearance}
\label{sec:appearance}

Usually when writing a document there is a template to follow, and often that template will be prescriptive. For example, many journals provide \LaTeX\ style files to use, combined with \verb|bibtex| style files as well. In these cases there is no need to control how the references appear.

However, in certain cases (such as your thesis) you may wish for more control. There are three basic methods: using the original \verb|bibtex| styles, using the \verb|natbib| package, or using the \verb|biblatex| package.

\subsubsection{Bibtex styles}
\label{sec:bibtex_styles}

The original \verb|bibtex| package came with a small selection of styles, and a number of additional styles have been made publically available. Many can be found online -- \href{http://www.cs.stir.ac.uk/~kjt/software/latex/showbst.html}{a sample list} can be found at \verb|http://www.cs.stir.ac.uk/~kjt/software/latex/showbst.html|, and many others exist.

If you are interested in the style being approximately correct, this is usually sufficient.

\subsubsection{Natbib}
\label{sec:natbib_styles}

The \verb|natbib| package contains additional citation commands, and additional software to build a style file that does exactly what you want. I would say it is now out of date, and \verb|biblatex| is a better package, but it is still widely used.

A few examples of the \href{http://merkel.zoneo.net/Latex/natbib.php}{citation commands provided} include
%
\begin{enumerate}
\item \verb|\citet{Jones90}|, producing ``Jones et al.\ (1990)''
\item \verb|\citet[chap. 2]{Jones90}|, producing ``Jones et al.\ (1990, chap.\ 2)''
\item \verb|\citep{Jones90}|, producing ``(Jones et al.\ 1990)''
\end{enumerate}
%
The distinction is between \emph{textual} (\verb|\citet|) and \emph{parenthetical} (\verb|citep|) citations.

In addition, \verb|natbib| has tools for sorting and compressing multiple citations in a single cross-reference, for modifying the appearance of parentheses, for aliasing a citation (i.e.\ replacing a key reference by ``Paper I'' throughout), and much more.

\subsubsection{Biblatex}
\label{sec:biblatex_styles}

All of the features mentioned above, and more, have been implemented in the \verb|biblatex| package. This allows the use of standard \LaTeX\ macros and commands for controlling the layout and appearance of citations and the bibliography. The \href{http://ctan.org/pkg/biblatex}{package description} can be found at \verb|http://ctan.org/pkg/biblatex|, with \href{http://mirror.ctan.org/macros/latex/contrib/biblatex/doc/biblatex.pdf}{full documentation} at
\verb|http://mirror.ctan.org/macros/latex/contrib/biblatex/doc/biblatex.pdf|.

There are changes that can be made at the detail level when updating the \verb|biblatex|; see, for example, the \href{http://tex.stackexchange.com/questions/5091/what-to-do-to-switch-to-biblatex}{comments at StackExchange} at \\ \verb|http://tex.stackexchange.com/questions/5091/what-to-do-to-switch-to-biblatex|. This allows you to take advantage of the full features of \verb|biblatex|.

\end{chapter}