This example demonstrates the solution of a particular nonlinear
time-dependent fourth-order equation, known as the Cahn-Hilliard
equation. In particular it demonstrates the use of

* The built-in Newton solver
* Advanced use of the base class ``NonlinearProblem``
* Automatic linearisation
* A mixed finite element method
* The :math:`\theta`-method for time-dependent equations
* User-defined Expressions as Python classes
* Form compiler options
* Interpolation of functions


Equation and problem definition
-------------------------------

The Cahn-Hilliard equation is a parabolic equation and is typically used
to model phase separation in binary mixtures.  It involves first-order
time derivatives, and second- and fourth-order spatial derivatives.
The equation reads:

.. math::
   \frac{\partial c}{\partial t} - \nabla \cdot M \left(\nabla\left(\frac{d f}{d c}
             - \lambda \nabla^{2}c\right)\right) &= 0 \quad {\rm in} \ \Omega, \\
   M\left(\nabla\left(\frac{d f}{d c} - \lambda \nabla^{2}c\right)\right) &= 0 \quad {\rm on} \ \partial\Omega, \\
   M \lambda \nabla c \cdot n &= 0 \quad {\rm on} \ \partial\Omega.

where :math:`c` is the unknown field, the function :math:`f` is usually
non-convex in :math:`c` (a fourth-order polynomial is commonly used),
:math:`n` is the outward directed boundary normal, and :math:`M` is a
scalar parameter.

Mixed form
^^^^^^^^^^

The Cahn-Hilliard equation is a fourth-order equation, so casting it
in a weak form would result in the presence of second-order spatial
derivatives, and the problem could not be solved using a standard
Lagrange finite element basis.  A solution is to rephrase the problem
as two coupled second-order equations:

.. math::
   \frac{\partial c}{\partial t} - \nabla \cdot M \nabla\mu  &= 0 \quad {\rm in} \ \Omega, \\
   \mu -  \frac{d f}{d c} + \lambda \nabla^{2}c &= 0 \quad {\rm in} \ \Omega.

The unknown fields are now :math:`c` and :math:`\mu`. The weak
(variational) form of the problem reads: find :math:`(c, \mu) \in V
\times V` such that

.. math::
   \int_{\Omega} \frac{\partial c}{\partial t} q \, {\rm d} x + \int_{\Omega} M \nabla\mu \cdot \nabla q \, {\rm d} x
          &= 0 \quad \forall \ q \in V,  \\
   \int_{\Omega} \mu v \, {\rm d} x - \int_{\Omega} \frac{d f}{d c} v \, {\rm d} x - \int_{\Omega} \lambda \nabla c \cdot \nabla v \, {\rm d} x
          &= 0 \quad \forall \ v \in V.

Time discretisation
^^^^^^^^^^^^^^^^^^^

Before being able to solve this problem, the time derivative must be
dealt with. Apply the :math:`\theta`-method to the mixed weak form of
the equation:

.. math::

   \int_{\Omega} \frac{c_{n+1} - c_{n}}{dt} q \, {\rm d} x + \int_{\Omega} M \nabla \mu_{n+\theta} \cdot \nabla q \, {\rm d} x
          &= 0 \quad \forall \ q \in V  \\
   \int_{\Omega} \mu_{n+1} v  \, {\rm d} x - \int_{\Omega} \frac{d f_{n+1}}{d c} v  \, {\rm d} x - \int_{\Omega} \lambda \nabla c_{n+1} \cdot \nabla v \, {\rm d} x
          &= 0 \quad \forall \ v \in V

where :math:`dt = t_{n+1} - t_{n}`
and :math:`\mu_{n+\theta} = (1-\theta) \mu_{n} + \theta \mu_{n+1}`.
The task is: given :math:`c_{n}` and :math:`\mu_{n}`, solve the above
equation to find :math:`c_{n+1}` and :math:`\mu_{n+1}`.


Demo parameters
^^^^^^^^^^^^^^^

The following domains, functions and time stepping parameters are used
in this demo:

* :math:`\Omega = (0, 1) \times (0, 1)` (unit square)
* :math:`f = 100 c^{2} (1-c)^{2}`
* :math:`\lambda = 1 \times 10^{-2}`
* :math:`M = 1`
* :math:`dt = 5 \times 10^{-6}`
* :math:`\theta = 0.5`

With the above input the solution for :math:`c` will look as follows:

.. image:: ../cahn-hilliard_c.png
    :scale: 75
    :align: center
