Merge branch 'fdlf_tutorial_v24'

doc/source/index.rst

@@ -34,7 +34,7 @@ Table of Contents
 
    quickstart
    user_guide/_user_guide
-   tutorials
+   tutorials/_tutorials
    developer_guide/_developer_guide
    glossary
    references

doc/source/tutorials/_tutorials.rst

@@ -0,0 +1,19 @@
+.. _tutorials:
+
+Tutorials
+=========
+
+The following tutorials are provided to familiarize beginners with the features 
+and typical workflow of NekRS. For a user brand new to NekRS, we strongly 
+recommend beginning with the fully developed laminar flow tutorial.
+
+N.B. Some of these tutorials have been adapted from those in the Nek5000
+documentation (https://nek5000.github.io/NekDoc/tutorials.html)
+
+.. toctree::
+    :maxdepth: 1
+
+    fdlf
+    tutorial_2
+    tutorial_3
+    tutorial_4

doc/source/tutorials/fdlf.rst

@@ -0,0 +1,302 @@
+.. _fdlf:
+
+Fully Developed Laminar Flow
+============================
+
+In this tutorial we will be building a case that involves incompressible laminar flow in a channel with a constant heat flux applied.
+This case uses air as a working fluid and will be simulated using fully dimensional quantities.
+A diagram of the case is provided in :numref:`fig:setup` and the necessary case parameters are provided in :numref:`tab:setup`.
+Note that round numbers have been selected for the fluid properties and simulation parameters for the sake of simplicity.
+
+.. _fig:setup:
+
+.. figure:: ../_static/img/tutorials/fdlf/setup.png
+   :align: center
+   :figclass: align-center
+   :alt: flow diagram
+   :width: 500
+
+   Diagram describing the case setup for fully developed laminar flow in a channel.
+
+.. _tab:setup:
+
+.. csv-table:: Fluid properties and simulation parameters
+   :align: center
+   :header: "Parameter name","variable","value"
+   :widths: 15, 15, 15
+
+   "channel height",":math:`H`","1 cm"
+   "channel length",":math:`L`","20 cm"
+   "mean velocity",":math:`U_m`","0.5 m/s"
+   "heat flux",":math:`q''`","300 W/m\ :sup:`2`"
+   "inlet temperature",":math:`T_{in}`","10 C"
+   "density",":math:`\rho`","1.2 kg/m\ :sup:`3`"
+   "viscosity",":math:`\mu`","0.00002 kg/m-s"
+   "thermal conductivity",":math:`\lambda`","0.025 W/m-K"
+   "specific heat",":math:`c_p`","1000 J/kg-K"
+
+This case has analytic solutions to the momentum and energy equations which makes it easy to confirm if the problem is setup correctly.
+These expressions will be used to test the accuracy of the solution.
+
+.. math::
+   :label: fdlf_vel
+
+   u(y) = \frac{3}{2} U_m \left( 1 - 4\left(\frac{y}{H}\right)^2\right)
+
+.. math::
+   :label: fdlf_temp
+
+   T(x,y)-T_b(x) = \frac{q'' H}{2\lambda}\left( 3\left(\frac{y}{H}\right)^2 - 2\left(\frac{y}{H}\right)^4-\frac{39}{280}\right)
+
+where the bulk temperature is given by the expression
+
+.. math::
+
+   T_b(x) = \left(\frac{2q''}{U_m \rho c_p H}\right)x + T_{in}
+
+.. Additionally, we will extract the predicted Darcy friction factor and Nusselt number from the simulation and confirm that they match the expected values.
+
+.. .. math::
+
+   f = \frac{96}{Re}
+
+.. .. math::
+
+   Nu = \frac{140}{17}
+
+Before You Begin
+________________
+
+This tutorial assumes that you have installed *NekRS* in your home directory and 
+have setup your :ref:`PATH <nekrs_home>`. You can either follow the example 
+with the files in the fdlf directory within examples directory of nekRS, or create 
+it within a directory of your choice.
+
+If you have chosen to create the example as following along, you will need to 
+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 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. 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}`. 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``:
+
+.. code-block:: console
+
+   $ mv box.re fdlf.re2
+
+.. Once we have the mesh file, we need to run the domain partitioning tool, ``genmap``.
+
+.. .. code-block:: console
+
+..    $ genmap
+
+.. On input specify ``fdlf`` as your casename and press enter to use the default tolerance. 
+.. This step will produce ``fdlf.ma2`` which contains the element partitioning information.
+.. 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>`_.
+
+Control parameters
+__________________
+
+The control parameters for any case are given in the ``.par`` file. For this case,
+create a new file called ``fdlf.par`` with the following:
+
+.. literalinclude:: ../../../examples/fdlf/fdlf.par
+
+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 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)
+_______________________________________
+
+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 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: 5,15,20
+
+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++
+   :lines: 117-132
+   :emphasize-lines: 12,16
+
+As with the boundary conditions, the inlet temperature and mean velocity are set
+from the list of user defined parameters in the ``.par`` file. 
+
+Running the case
+________________
+
+You should now be all set to run your case! As a final check, you should have the following files:
+
+ * :download:`fdlf.re2 <../../../examples/fdlf/fdlf.re2>`
+ * :download:`fdlf.par <../../../examples/fdlf/fdlf.par>`
+ * :download:`fdlf.udf <../../../examples/fdlf/fdlf.udf>`
+ * :download:`fdlf.usr <../../../examples/fdlf/fdlf.usr>`
+
+If for some reason you encountered an insurmountable error and were unable to 
+generate any of the required files, you may use the provided links to download them. 
+Now you can run the case
+
+.. code-block:: console
+
+   $ mpirun -np 4 nekrs --setup fdlf.par | tee logfile
+
+To launch an MPI jobs on your local machine using 4 ranks. The output will be 
+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:
+
+.. code-block:: none
+
+   fdlf0.f00001
+   fdlf0.f00002
+   ...
+
+The preferred mode for data visualization and analysis with *NekRS* is to use
+Visit or ParaView. One can use the script *visnek*, to be found in ``/scripts``. 
+It is sufficient to run:
+
+.. code-block:: console
+
+   $ visnek fdlf
+
+to obtain a file named ``fdlf.nek5000`` which can be recognized in Visit/ParaView. 
+In the viewing window one can visualize the flow-field as depicted in 
+:numref:`fig:velocity_paraview` as well as the temperature profile as depicted 
+in :numref:`fig:temperature_paraview` below.
+
+.. _fig:velocity_paraview:
+
+.. figure:: ../_static/img/tutorials/fdlf/velocity_paraview.png
+   :align: center
+   :figclass: align-center
+
+   Steady-State flow field visualized in Visit/ParaView. Colors represent velocity magnitude.
+
+.. _fig:temperature_paraview:
+
+.. figure:: ../_static/img/tutorials/fdlf/temp.png
+   :align: center
+   :figclass: align-center
+
+   Temperature profile visualized in Visit/ParaView.
+
+Plots of the velocity and temperature varying along the y-axis as evaluated by *Nek5000* compared to the analytic solutions provided by Eqs. :eq:`fdlf_vel` and :eq:`fdlf_temp` respectively are shown below in :numref:`fig:velocity_lineplot` and :numref:`fig:temperature_lineplot`.
+
+.. _fig:velocity_lineplot:
+
+.. figure:: ../_static/img/tutorials/fdlf/velocity_lineplot.png
+   :align: center
+   :figclass: align-center
+
+   *Nek5000* velocity solutions plotted against analytical solutions.
+
+.. _fig:temperature_lineplot:
+
+.. figure:: ../_static/img/tutorials/fdlf/temperature_lineplot.png
+   :align: center
+   :figclass: align-center
+
+   *Nek5000* temperature solutions plotted against analytical solutions.

doc/source/tutorials/tutorial_2.rst

@@ -0,0 +1,4 @@
+.. _tutorial_2:
+
+Tutorial 2
+==========

doc/source/tutorials/tutorial_3.rst

@@ -0,0 +1,4 @@
+.. _tutorial_3:
+
+Tutorial 3
+==========

doc/source/tutorials/tutorial_4.rst

@@ -0,0 +1,4 @@
+.. _tutorial_4:
+
+Tutorial 4
+==========

examples/fdlf/fdlf.box

@@ -0,0 +1,14 @@
+-3                     spatial dimension (will create box.re2)
+2                      number of fields
+#
+#    comments: periodic laminar flow
+#
+#========================================================
+#
+Box                                       fdlf
+-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, cbz0, cbz1)
+t  ,O  ,I  ,f  ,P  ,P                     Temperature BC's:  (cbx0, cbx1, cby0, cby1, cbz0, cb1)

examples/fdlf/fdlf.par

@@ -0,0 +1,26 @@
+#
+# nek parameter file
+#
+[GENERAL]
+polynomialOrder = 7
+cubaturePolynomialOrder = 11
+dt = 1.0e-4
+numsteps = 10000
+writeInterval = 2000
+
+[PRESSURE]
+residualTol = 1e-4
+
+[VELOCITY]
+density = 1.2        #kg/m3
+viscosity = 0.00002  #kg/m-s
+
+[TEMPERATURE]
+rhoCp = 1200.0       #J/m3-K
+conductivity = 0.025 #W/m-K
+
+[CASEDATA]
+height = 0.01
+Umean = 0.5
+Tflux = 300.0
+Tin = 10.0