Continuing fdlf tutorial. Tidied box file.

doc/source/tutorials/fdlf.rst

@@ -73,41 +73,48 @@ with the files in the fdlf directory within examples directory of nekRS, or crea
 it within a directory of your choice.
 
 If you have chosen to create the example as following along, you will need to 
-compile the two *Nek5000* tools ``genbox`` for the initial mesh generation and 
-``visnek`` to visualise the final result. Please follow the instructions in the
-:ref:`Building the Nek5000 Tool Scripts <scripts>` section.
+compile the *Nek5000* tool ``genbox`` for the initial mesh generation and have
+access to the ``visnek`` tool to visualise the final result. Please follow the 
+instructions in the :ref:`Building the Nek5000 Tool Scripts <scripts>` section.
 
 Mesh Generation
 _______________
 
-This tutorial uses a simple rectangular box mesh generated by ``genbox``. 
+This tutorial uses a simple 3D cuboid box mesh generated by ``genbox``. 
 To create the input file, copy the following script and save the file as ``fdlf.box``.
 
 .. literalinclude:: ../../../examples/fdlf/fdlf.box
    :language: none
 
 For this mesh we are specifying 50 uniform elements in the stream-wise (:math:`x`) 
-direction and 5 uniform elements in the span-wise (:math:`y`) direction. The 
-velocity boundary conditions in the x-direction are a standard Dirichlet 
+direction and 5 uniform elements in the span-wise (:math:`y`) direction. As 
+*NekRS* can only solve 3D problems we also create a single element in the z-direction.
+
+The velocity boundary conditions in the x-direction are a standard Dirichlet 
 velocity boundary condition at :math:`x_{min}` and an open boundary condition 
-with zero pressure at :math:`x_{max}`. The velocity boundary conditions in the 
-y-direction are a symmetric boundary at :math:`y_{min}` and a wall with no slip
-condition at :math:`y_{max}`. The temperature boundary conditions in the 
-x-direction are a standard Dirichlet boundary condition at :math:`x_{min}`
-and an outflow condition with zero gradient at :math:`x_{max}`. The temperature
-boundary conditions in the y-direction are an insulated condition with zero
-gradient at :math:`y_{min}` and a constant heat flux at :math:`y_{max}`. Note 
-that the boundary conditions specified with lower case letters must have values
-assigned in userbc, which will be shown later in this tutorial. Now we can run
-``genbox`` with
+with zero pressure at :math:`x_{max}`. In the y-direction the velocity boundary
+conditions are a symmetric boundary at :math:`y_{min}` and a wall with no slip
+condition at :math:`y_{max}`. In the z-direction there is a periodic velocity 
+boundary condition at both :math:`z_{min}` and :math:`z_{max}`.
+
+The temperature boundary conditions in the x-direction are a standard Dirichlet 
+boundary condition at :math:`x_{min}` and an outflow condition with zero gradient
+at :math:`x_{max}`. In the y-direction the temperature boundary conditions are
+an insulated condition with zero gradient at :math:`y_{min}` and a constant heat
+flux at :math:`y_{max}`. The z direction boundary conditions are periodic at
+both :math:`z_{min}` and :math:`z_{max}`.
+
+Note that the boundary conditions specified with lower case letters must have
+values assigned in relevant functions in the udf file, which will be shown later
+in this tutorial (see :ref:`bc_ic_udf`). Now we can generate the mesh with:
 
 .. code-block:: console
 
    $ genbox
 
 When prompted provide the input file name, which for this case is ``fdlf.box``.
 The tool will produce binary mesh and boundary data file ``box.re2`` which should 
-be renamed to ``fdlf.re2``.
+be renamed to ``fdlf.re2``:
 
 .. code-block:: console
 
@@ -124,7 +131,9 @@ be renamed to ``fdlf.re2``.
 .. You do not have to specify the number of MPI-ranks you plan to run the case with when you use ``genmap``, as it contains the partitioning for all possible choices.
 
 .. :tip: If either ``genbox`` or ``genmap`` cannot be located by your shell, check to make sure the ``Nek5000/tools`` directory is in your path. For help see :ref:`here<sec:PATH>`.
-.. tip:: If ``genbox`` cannot be located by your shell, check to make sure the ``Nek5000/tools`` directory is in your path. For help see `here <https://nek5000.github.io/NekDoc/quickstart.html#sec-path>`_.
+.. tip:: If ``genbox`` cannot be located by your shell, check to make sure the 
+         ``Nek5000/tools`` directory is in your path. For help see 
+         `here <https://nek5000.github.io/NekDoc/quickstart.html#sec-path>`_.
 
 Control parameters
 __________________
@@ -134,16 +143,22 @@ create a new file called ``fdlf.par`` with the following:
 
 .. literalinclude:: ../../../examples/fdlf/fdlf.par
 
-For this case the properties evaluated are for air at ~20 C. 
-Note that ``rhoCp`` is the product of density and specific heat.
-The ``CASEDATA`` list represents an easy way of passing data to *NekRS* that
-can later be used throughout the ``.udf`` file. Additionally, like all values
-specified in the ``.par`` file, they can be changed without the need to recompile *NekRS*.
+Here we have set our polynomial order to be :math:`N=7` which indicates that
+there are 8 points in each spatial dimension of every element. The case has been
+configured to have a time step of `0.1` milliseconds, with a maximum of 10000 
+steps and an output file produced every 2000 steps.
+
+.. TODO cubaturePolynomialOrder and pressureTol
+
+For this case the properties evaluated are for air at ~20 C and ``rhoCp`` is the 
+product of density and specific heat.
 
 The required values for the initial and boundary conditions specified by lower 
-case letters in the  ``.box`` file are defined here as a list of user given
-parameters, as well as the height of the channel. These initial and boundary
-conditions will later be called in respective subroutines of the ``.udf`` file.
+case letters in the  ``.box`` file are defined here as part of the ``CASEDATA``
+section. This provides an easy way of passing data to *NekRS* that can later be
+used throughout the ``.udf`` file where the conditions will later be set.
+Additionally, like all values specified in the ``.par`` file, they can be
+changed without the need to recompile *NekRS*.
 
 User-Defined Host Functions File (.udf)
 _______________________________________
@@ -152,27 +167,49 @@ The user-defined host functions file implements various subroutines to allow the
 user to interact with the solver. For more information on the ``.udf`` file and 
 the available subroutines see :ref:`here <udf_functions>`.
 
+Loading parameters
+^^^^^^^^^^^^^^^^^^
+
+Firstly, the channel height, mean velocity, heat flux, and mean inlet temperature 
+parameters that were set in the ``.par`` file must be loaded for later use. 
+These are loaded through the ``UDF_Setup0`` method.
+
+.. literalinclude:: ../../../examples/fdlf/fdlf.udf
+   :language: c++
+   :lines: 82-88
+
+The ``UDF_LoadKernels`` function is used to load the remaining parameters
+of the temperature density and diffusivity/conductivity.
+
+.. literalinclude:: ../../../examples/fdlf/fdlf.udf
+   :language: c++
+   :lines: 65-71
+
+All these values can then be set as variables for use within the device kernel.
+
+.. literalinclude:: ../../../examples/fdlf/fdlf.udf
+   :language: c++
+   :lines: 73-80
+
+.. _bc_ic_udf:
+
 Boundary and initial conditions
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The boundary conditions can be setup in function ``UDF_Setup`` as shown below, 
-where the highlighted lines indicate where the actual boundary condition is specified.
-The velocity and temperature are set to the analytic profiles given by Eqs. :
-eq:`fdlf_vel` and :eq:`fdlf_temp` and the heat flux is set to a constant value.
+The boundary conditions are setup in ``velocityDirichletConditions``,  
+``scalarDirichletConditions`` and ``scalarNeumannConditions`` device functions
+as shown below, where the highlighted lines indicate where the actual boundary condition
+is specified. The velocity and temperature are set to the analytic profiles given
+by Eqs. :eq:`fdlf_vel` and :eq:`fdlf_temp` and the heat flux is set to a constant value.
 
 .. literalinclude:: ../../../examples/fdlf/fdlf.udf
    :language: c++
    :lines: 41-61
-   :emphasize-lines: 3-5,12-15,20
+   :emphasize-lines: 5,15,20
 
-*The channel height, mean velocity, heat flux, and mean inlet temperature are all 
-called from the list of user defined parameters in the ``.par`` file.
-The thermal conductivity is set from the :ref:`field coefficient array<tab:cpfld>`, 
-which is set from the conductivity specified for the temperature field in the ``.par`` file.*
-
-The next step is to specify the initial conditions.
-This can also be done in the ``UDF_Setup`` function as shown. 
-Again, the actual inlet condition is specified with the highlighted lines.
+The next step is to specify the initial conditions. This is done in the 
+``UDF_Setup`` function as shown. Again, the actual inlet condition is specified 
+with the highlighted lines.
 
 .. literalinclude:: ../../../examples/fdlf/fdlf.udf
    :language: c++
@@ -206,6 +243,8 @@ redirected to ``logfile``.
 Post-processing the results
 ___________________________
 
+.. TODO tidy how to get visnek
+
 Once execution is completed your directory should now contain 5 checkpoint files 
 that look like this:
 

examples/fdlf/fdlf.box

@@ -6,9 +6,9 @@
 #========================================================
 #
 Box                                       fdlf
--50 -5 -1                                 Nelx  Nely
+-50 -5 -1                                 Nelx  Nely Nelz
 0.0 0.2 1.0                               x0 x1 ratio
 0.0 0.005 0.7                             y0 y1 ratio
 0.0 1.0 1.0                               z0 z1 ratio
-v  ,O  ,SYM,W  ,P  ,P                     Velocity BC's:  (cbx0, cbx1, cby0, cby1)
-t  ,O  ,I  ,f  ,P  ,P                     Temperature BC's:  (cbx0, cbx1, cby0, cby1)
+v  ,O  ,SYM,W  ,P  ,P                     Velocity BC's:  (cbx0, cbx1, cby0, cby1, cbz0, cbz1)
+t  ,O  ,I  ,f  ,P  ,P                     Temperature BC's:  (cbx0, cbx1, cby0, cby1, cbz0, cb1)