.. _user-guide:

==============
First tutorial
==============

This section illustrates how to launch the GUI, open a project, run it, and
visualize the results.

This section assumes MFiX is already installed. To install MFiX, see the
:ref:`Setup Guide <setup-guide>`.

Everything in this section applies to all platforms (Linux, macOS, Windows)
unless otherwise noted.

Starting the MFiX GUI
---------------------

Starting the GUI requires first to activate the environment (to select a given installed version of MFiX):

On Windows, open the Miniforge Prompt and activate the :ref:`mfix environment <activate-env-windows>`

On Linux open a terminal and activate the :ref:`mfix environment <activate-env-linux>`

On macOS open a terminal and activate the :ref:`mfix environment <activate-env-macos>`

Next, type ``mfix`` at the prompt. The two steps are shown below for each Operating System:

**Windows**

.. substitution-code-block:: doscon

    conda activate mfix-|release|
    (mfix-|release|) C:\> mfix

**Linux or Mac**

.. substitution-code-block:: doscon

    conda activate mfix-|release|
    (mfix-|release|) > mfix

If this is the first time opening the GUI, the main menu will automatically
open. Otherwise, the previous project will automatically open.

Creating a project
------------------

-  Click |new| (:ref:`new-project`)

A list of project templates is displayed.

The templates are tagged with the following icons. (Some templates have more
than one icon).

.. include:: /template_icons.rst

.. note::
   The blank template is the default, but it won't run without customization. It
   requires a pressure outflow, among other things.

-  Filter the templates by de-selecting the |single| (single-phase), and
   |chemistry| (chemistry) icons
-  Double-click on ``hopper_3d (3D DEM granular flow hopper)`` to create a new project
-  Enter a project name (or keep the existing name) and browse to a location for
   the new project.
-  Click Ok

A new project directory will be created in the selected directory, with the name
being the project name. Here, a DEM Hopper simulation setup has been loaded and
is ready to run. You should see the model geometry in the "model" window
(top-right).

Running the solver
------------------

-  Click the |play| (Start) button to open the :ref:`run-dialog`.

-  Click Ok to use the default mfixsolver: ``[default]/mfixsolver``

The solver will begin to run, with output displayed in the
:ref:`terminal-window`. There is a progress bar along the bottom of the screen
where it says `MFiX running: elapsed time`.


View results
------------

Results can be viewed, and plotted, while the simulation is running.

-  Select the ``VTK`` results tab. The visibility and representation of the
   ``*.vtk`` files can be controlled with the menu on the side.


-  Change frames with the |first|, |back|, |next|, and |last| buttons
-  Click the |play| button to play the available vtk files.
-  Change the playback speed under the |speed| section on the sidebar.

Pausing/unpausing
-----------------

-  Click the |pause| (pause) button to pause the solver.

   ``MFiX paused`` will be displayed in the :ref:`terminal-window`. The solver
   process still exists, but is waiting for you to unpause it.

   While the solver is paused, you can change the project. For instance, on the
   :ref:`run-pane` Pane you could change ``Stop time`` to another value to have the
   solver run for a different amount of time.

-  Click the |play| (run) button to unpause the solver and continue running.


Stopping/resuming
-----------------

-  Click the |stop| (stop) button to stop the solver.

``MFiX stopped`` will be displayed in the :ref:`terminal-window`. The solver
process has ended, with the output files still in the project directory.

You can then resume the solver by:

-  Clicking the |play| (run) button to open the :ref:`run-dialog`.

-  Check ``Restart`` and select ``Resume`` from the drop down list.

-  Click Ok to use the default mfixsolver.

The solver process will start and continue from the point at which the output
files were last written.