Tidied

Author: cjohnson-pi

documentation/source/science_guide/tangent_linear_section/index.rst

@@ -9,7 +9,7 @@
 Linear Model Section
 =======================
 
-This describes the details of the tangent-linear model code for GungHo.
+This describes the scientific aspects of the tangent-linear model code for GungHo.
 
 .. toctree::
     :maxdepth: 2
@@ -18,6 +18,6 @@ This describes the details of the tangent-linear model code for GungHo.
     tangent_linear_coding
     tangent_linear_timestepping
     tangent_linear_components
-    tl_ffsl_transport
-    tangent_linear_lin_state
+    tangent_linear_mol_transport
+    tangent_linear_ffsl_transport
     tangent_linear_tests

documentation/source/science_guide/tangent_linear_section/tangent_linear_coding.rst

@@ -1,10 +1,14 @@
 .. _tangent_linear_coding:
 
-Tangent Linear Coding
+General principles
 =====================
 
-To obtain the tangent linear code, we need to differentiate the
-nonlinear model code.
+To obtain the tangent linear model, we need to differentiate the
+nonlinear model. There are two main ways to achieve this: differentiate the nonlinear continuous equations and then discretize, or differentiate the nonlinear discretized equations.
+
+Mainly the approach of differentiating the discretized equations is used here - the so-called line-by-line approach, as each line of code can be treated individually. However, some parts such as the semi-implicit solve take the approach of differentiating the nonlinear equations and then discretizing (although in fact as the solver is already linear, in practice this just means reusing the nonlinear code).
+
+The following examples demonstrate how the line-by-line approach is implemented, to differentiate the discretized equations.
 
 First derivative
 ----------------

documentation/source/science_guide/tangent_linear_section/tangent_linear_components.rst

@@ -1,6 +1,6 @@
 .. _tangent_linear_components:
 
-Components
+Right-hand-side Components
 =====================
 
 Kinetic energy gradient
@@ -163,67 +163,3 @@ The linear model is
    \delta N & = \frac{\partial N}{\partial E} \left( \frac{ \partial E}{\partial \Pi} \delta \Pi + \frac{ \partial E}{\partial \rho} \delta \rho + \frac{ \partial E}{\partial \theta} \delta \theta \right) \\
     &  = - \frac{1}{E} \left( \frac{1-\kappa}{\kappa} \frac{\delta \Pi}{\Pi} - \frac{\delta \rho}{\rho} - \frac{\delta \theta}{\theta} \right)
    \end{aligned}
-
-Method of Lines (MoL) and Runge-Kutta Transport
------------
-
-The nonlinear model is:
-
-.. math::
-
-   \begin{aligned}
-     u^{(i)} & = u^n + \Delta t \sum_{k=0}^{i-1} \beta_{i,k} f(u^{(k)}) \quad i=1,\ldots,m \\
-     u^{n+1} & = u^{(m)}
-     \end{aligned}
-
-In ``rk_alg_timestep``, the :math:`f(u^{(i)})` corresponds to
-``rhs_prediction``, and :math:`\sum_{k=0}^{i-1} \beta_{i,k} f(u^{(k)})`
-corresponds to rhs. (There is also an extra mass matrix inversion, so
-they are not directly equal).
-
-The tangent linear model comprises two steps. First the linearisation
-state is computed:
-
-.. math:: \bar{u}^{(i)} = \bar{u}^n + \Delta t \sum_{k=0}^{i-1} \beta_{i,k} f(\bar{u}^{(k)}) \quad i=1,\ldots,m
-
-then the perturbations are computed:
-
-.. math::
-
-   \begin{aligned}
-     u'^{(i)} & = u'^n + \Delta t \sum_{k=0}^{i-1} \beta_{i,k} f'(u'^{(k)},\bar{u}^{(k)}) \quad i=1,\ldots,m \\
-     u'^{n+1} & = u'^{(m)}
-     \end{aligned}
-
-In the nonlinear model, the method of lines transport code has switches
-to ensure that the transport scheme is upwinding. In the linear model,
-we use the same switches as the nonlinear model. This means that the
-direction is based on the linearisation state wind rather than the
-perturbation wind.
-
-In the nonlinear model,
-
-::
-
-   direction = wind(map_w2(df) + k )*v_dot_n(df)
-   if ( direction > 0.0_r_def ) then
-
-In the linear model,
-
-::
-
-   direction = ls_wind(map_w2(df) + k )*v_dot_n(df)
-   if ( direction > 0.0_r_def ) then
-
-Similarly, where
-
-::
-
-   sign_X(unit_wind,1.0_r_def, advecting_wind)
-
-the corresponding tangent linear uses
-
-::
-
-   sign_X(unit_wind, 1.0_r_def, ls_advecting_wind)
-

…ent_linear_section/tl_ffsl_transport.rst …ection/tangent_linear_ffsl_transport.rstdocumentation/source/science_guide/tangent_linear_section/tl_ffsl_transport.rst renamed to documentation/source/science_guide/tangent_linear_section/tangent_linear_ffsl_transport.rst documentation/source/science_guide/tangent_linear_section/tl_ffsl_transport.rst renamed to documentation/source/science_guide/tangent_linear_section/tangent_linear_ffsl_transport.rst

@@ -22,7 +22,6 @@ the form
 
 .. math::
 
-   \label{eq:advective}
        q^{n+1}_{adv} = \frac{q^{n} - \Delta{t} F(u,q^n)}{\sigma - \Delta{t} F(u,\sigma)}
 
 where :math:`\sigma=1` is the unity field, and therefore
@@ -54,15 +53,12 @@ Leaving the conservative perturbation transport equation as
 
 .. math::
 
-   \label{eq:transport_equation}
        \frac{\partial q'}{\partial t} + \nabla \cdot( \bar{u}q' ) + \nabla \cdot( u'\bar{q} ) = 0
 
 Flux Computation
 ----------------------
 
-The flux computation can be split into two parts, corresponding to the
-two terms in equation
-`[eq:transport_equation] <#eq:transport_equation>`__.
+The flux computation can be split into two parts.
 
 The first term, corresponding to :math:`\bar{u}q'`, can be computed
 using standard FFSL operators, provided the scheme is linear (i.e. no
@@ -91,7 +87,7 @@ We can now use the notation
 Advective Update
 --------------------
 
-Following `[eq:advective] <#eq:advective>`__, if we expand the variables
+If we expand the variables
 into linearisation state and perturbation parts we find the flux
 divergences can be written as
 
@@ -105,7 +101,6 @@ and the advective form becomes
 
 .. math::
 
-   \label{eq:advective_linear}
        q^{n+1}_{adv} = \frac{\bar{q} + q' - \Delta{t} F(\bar{u},\bar{q}) - \Delta{t}F_1(\bar{u},q') - \Delta{t}F_2(u',\bar{q}) }{\sigma - \Delta{t} F(\bar{u},\sigma)- \Delta{t} F_2(u',\sigma)}
 
 Let
@@ -127,7 +122,6 @@ Noting that
 
 .. math::
 
-   \label{eq:adv_ls}
        \bar{q}^{n+1}_{adv} = \frac{\bar{N}}{\bar{D}}
 
 then the advective perturbation field can be found from
@@ -145,7 +139,7 @@ Using the first terms of the expansion
                      =& \frac{N'}{\bar{D}} - \frac{\bar{N}D'}{\bar{D}\bar{D}} - \frac{N'D'}{\bar{D}\bar{D}}
    \end{aligned}
 
-Using `[eq:adv_ls] <#eq:adv_ls>`__, and the fact products of prime
+Using the fact products of prime
 variables equals zero, this simplifies to
 
 .. math:: q'^{n+1}_{adv} = \frac{N' - D' \bar{q}^{n+1}_{adv}}{\bar{D}}

documentation/source/science_guide/tangent_linear_section/tangent_linear_lin_state.rst

@@ -0,0 +1,84 @@
+.. _tangent_linear_mol_transport:
+
+MoL  Transport
+====================
+
+The Method of Lines (MoL) transport scheme is a Finite Volume Scheme that uses Runge-Kutta timestepping. For the linear model, we use the notation that :math:`\bar{u}` is the linearisation state and :math:`u'` is the perturbation.
+
+Nonlinear MoL
+----------
+
+The nonlinear continuous equation is
+
+.. math:: \frac{\partial \theta}{\partial t} = - u. \nabla \theta
+
+which is discretised using an upwind scheme. On each face, 
+
+.. math::  \begin{aligned} \frac{\partial \theta}{\partial t}
+	                  & = - u. \nabla_L \theta & \text{   if } u>0 \\ 
+                          & = - u. \nabla_R \theta & \text{   if } u<0 \\
+			  & =   0                  & \text{   if } u=0 \\
+	  \end{aligned}
+
+where :math:`\nabla_L` uses the upwind reconstruction calculated from the left and :math:`\nabla_R` uses the upwind reconstruction calculated from the right.
+As required, :math:`\frac{\partial \theta}{\partial t}` tends to 0 as u tends to 0.
+			    
+This is implemented by initialising
+:math:`\frac{\partial \theta}{\partial t}` as :math:`0` and then adding
+on an increment if :math:`u>0` or :math:`u<0`.
+
+Linearised MoL
+----------
+
+The linearised continuous equation is
+
+.. math:: \frac{\partial \theta'}{\partial t} = - \bar{u}. \nabla \theta' - u'. \nabla \bar{\theta}
+
+This is discretised as
+
+.. math::  \begin{aligned} \frac{\partial \theta'}{\partial t}
+	                  & = - \bar{u}. \nabla_L \theta' - u'. \frac{1}{2} (\nabla_L + \nabla_R) \bar{\theta}
+			  & \text{   if } \bar{u}>0 \\ 
+                          & = - \bar{u}. \nabla_R \theta' - u'. \frac{1}{2} (\nabla_L + \nabla_R) \bar{\theta}
+			  & \text{   if } \bar{u}<0 \\
+			  & = - u'. \frac{1}{2} (\nabla_L + \nabla_R) \bar{\theta}
+			  & \text{   if } \bar{u}=0 \\
+	  \end{aligned}
+
+which, as required, tends to
+:math:`- u'. \frac{1}{2} (\nabla_L + \nabla_R) \bar{\theta}` as
+:math:`\bar{u}` tends to :math:`0`.
+
+This is implemented by initialising
+:math:`\frac{\partial \theta'}{\partial t}` as
+:math:`- u'. \frac{1}{2} (\nabla_L + \nabla_R) \bar{\theta}` and then
+adding an increment if :math:`\bar{u}>0` or :math:`\bar{u}<0`.
+
+Runge-Kutta
+-----------
+
+The nonlinear Runge Kutta scheme is:
+
+.. math::
+
+   \begin{aligned}
+     u^{(i)} & = u^n + \Delta t \sum_{k=0}^{i-1} \beta_{i,k} f(u^{(k)}) \quad i=1,\ldots,m \\
+     u^{n+1} & = u^{(m)}
+     \end{aligned}
+
+The tangent linear Runge Kutta scheme comprises two steps. First the linearisation
+state is computed:
+
+.. math:: \bar{u}^{(i)} = \bar{u}^n + \Delta t \sum_{k=0}^{i-1} \beta_{i,k} f(\bar{u}^{(k)}) \quad i=1,\ldots,m
+
+then the perturbations are computed:
+
+.. math::
+
+   \begin{aligned}
+     u'^{(i)} & = u'^n + \Delta t \sum_{k=0}^{i-1} \beta_{i,k} f'(u'^{(k)},\bar{u}^{(k)}) \quad i=1,\ldots,m \\
+     u'^{n+1} & = u'^{(m)}
+     \end{aligned}
+
+
+If ``transport_efficiency`` is set to true, then the ``ls_state`` is not updated, so that the same linearisation state is used for all iterations.

documentation/source/science_guide/tangent_linear_section/tangent_linear_mol_transport.rst

@@ -1,6 +1,6 @@
 .. _tangent_linear_overview:
 
-Tangent Linear Model Overview
+Overview
 =======================
 
 In variational data assimilation, the aim is to compute the optimal
@@ -17,7 +17,7 @@ is the observation operator (which we can assume is linear here), and
 :math:`\mathbf{B}` and :math:`\mathbf{R}` are the error covariance
 matrices.
 
-As :math:`N` is nonlinear, there is no unique solution. Therefore, the
+As :math:`N` is nonlinear, there may not be a unique solution and it is difficult to solve. Therefore, the
 problem is rewritten in incremental form, by rewriting the initial state
 in terms of a linearisation state plus a perturbation,
 :math:`\mathbf{x}_0 = \tilde{\mathbf{x}} + \mathbf{\delta x}`, so that