.. _user_run_exodus_mesh:

Exodus-II File Format
---------------------

Nalu-Wind requires the user to provide the computational mesh in `Exodus-II
<http://prod.sandia.gov/techlib/access-control.cgi/1992/922137.pdf>`_ format.
The output and restart files generated by Nalu-Wind are also in Exodus-II format
where the requested fields are output along side the mesh. The restart files
from one Nalu-Wind simulation can serve as the input file for a subsequent
simulation.

Several commercial mesh generation software support output to Exodus-II format.
Two such software used by Nalu-Wind developers are:

  - `CUBIT <https://cubit.sandia.gov/public/13.2/help_manual/WebHelp/cubit_users_manual.html>`_
  - `Pointwise <http://www.pointwise.com>`_

Furthermore, `NaluWindUtils
<http://naluwindutils.readthedocs.io/en/latest/user/abl_mesh.html>`_ provides an
:program:`abl_mesh` utility that can be used to generate simple structured
meshes (output into Exodus-II format) for use with atmospheric boundary layer
simulations.

Examining Exodus-II Files
~~~~~~~~~~~~~~~~~~~~~~~~~

Exodus-II uses the `NetCDF <http://www.unidata.ucar.edu/software/netcdf/>`_
format to store data, therefore, the several NetCDF utilities can be used to
examine the file metadata. For example, the following code snippet shows the use
of :program:`ncdump` to examine the names of the mesh blocks and side sets, as
well as the nodal fields available in a given mesh file.

.. code-block:: bash

   ncdump -v eb_names,ss_names,name_nod_var channel_coarse_ic.g
   # <output truncated to show only relevant parts>
   data:

    eb_names =
     "interior" ;

    ss_names =
     "inlet",
     "outlet",
     "bottomwall",
     "topwall",
     "back",
     "front" ;

    name_nod_var =
     "turbulent_ke",
     "velocity_x",
     "velocity_y",
     "velocity_z" ;

For brevity, the example above has removed the NetCDF ``dimensions`` and
``variables`` sections to show just the contents of the variable names of
interest. The output shows that the mesh in question contains one element block
(``interior``) with six boundary planes (side-sets) and has two nodal fields: the
velocity vector, and the turbulent kinetic energy scalar. :program:`ncdump` can
be invoked with the ``-h`` flag to print just the headers. Of particular
interest is the NetCDF ``dimensions`` section that contains information about
the total number of nodes, element, boundary faces, etc. in the mesh file.

Most visualization programs support loading Exodus-II mesh/solution files and
can be used to visualize the flow fields generated by Nalu-Wind. Two open-source
visualization programs available are:

  - `ParaView <https://www.paraview.org>`_
  - `VisIt <https://wci.llnl.gov/simulation/computer-codes/visit/>`_

Preliminary support for in-situ visualization using `ParaView Catalyst
<https://www.paraview.org/in-situ/>`_ is available within the Nalu-Wind code base and
can be enabled by linking to Catalyst libraries during compile time. See input
file specifications more details on setting up Cataylst for in-situ
visualization of Nalu-Wind solution files.

Other Exodus-II Utilities
~~~~~~~~~~~~~~~~~~~~~~~~~

A brief description of some useful Exodus-II utilities are provided here. Please
consult the documentation of these programs to understand the full range of
options available.

**decomp**

   ``decomp`` is a SEACAS utility (available from a Trilinos install) that can
   be used to decompose a mesh file acros several MPI ranks for use in a
   subsequent paralell simulation.

**epu**

   ``epu`` performs the reverse action of ``decomp``, i.e., it combines parallel
   decomposed files from a simulation into a single Exodus-II database. The
   simplest invocation is

   .. code-block:: bash

      epu -auto nalu_output.e.8.0

   The ``-auto`` flag determines the database structured based on the file
   provided on the command line and combines the files (in the above example
   into ``nalu_output.e``).

**mapvar-kd**

   Map solution fields from one mesh to another mesh.

**percept**

   The `Percept <https://github.com/PerceptTools/percept>`_ project provides
   various tools to perform mesh refinement, higher-order promotion, etc. See
   documentation for ``mesh_adapt`` to determine various options available.