.. _install-mfix-linux:

Linux Installation
------------------

MFiX has been developed and tested on the following linux distributions:

    - Ubuntu 18.10
    - CentOS 7

Other recent releases of Linux are likely to work. If you have an issue running
MFiX works your distro, ask for help at :ref:`support-forum`.


Install Anaconda
""""""""""""""""

**Download** the 64-bit, Python 3, Linux version of `Anaconda
<https://www.anaconda.com/products/individual>`__ (~500 MB download) or `Miniconda
<https://docs.conda.io/en/latest/miniconda.html>`__ (~50 MB download).

For instance, with the Anaconda installer:

    #.  Open a terminal
    #.  ``cd`` to the directory of the downloaded installer (for example ``~/Downloads``)
    #.  Run the downloaded installer (At the time of this writing, ``sh Anaconda3-2021.05-Linux-x86_64.sh⏎``.
    #.  You will be asked to review the License, hit enter
    #.  Hit the space bar until you get to the end of the license agreement.
    #.  Agree to the license by typing ``yes`` and hitting enter
    #.  When prompted for an installation location, hit enter to use the default.
    #.  When prompted to add the conda bin directory to ``PATH``, enter ``yes`` and hit enter.

Anaconda is now installed. In order for the changes to take effect, close the
terminal and open a new one. Verify that your ``PATH`` was updated by running
``conda`` in the new terminal.


Install MFiX
""""""""""""

After installing Anaconda, install MFiX with the following steps:

    #.  Open the Terminal application for your Linux desktop
    #.  Browse to `MFiX Download <https://mfix.netl.doe.gov/mfix/download-mfix>`__ (requires registration and login)
    #.  Copy the conda command.
    #.  Paste it in the Terminal.

.. note:: If you already installed MFiX, you may see the following message. Select ``y`` to confirm.

          .. code-block:: batch

              WARNING: A conda environment already exists
              Remove existing environment (y/[n])? y

MFiX will be installed in a new conda environment. The process will take a few
minutes to complete.


.. _install-build-dependencies-linux:

Install Solver Build Dependencies (optional)
""""""""""""""""""""""""""""""""""""""""""""

Build dependencies are needed for building a :ref:`custom interactive
solver<build-custom>`. If you only use the default solver, you can skip this
step.

Building the MFiX solver requires:

    - Fortran 2003 compiler (GFortran 4.8 or later)
    - GNU Make
    - CMake
    - For DMP support, an MPI implementation (such as OpenMPI)

For building with other compilers, or for building with DMP, see :ref:`build-custom`.

Installing GCC and Make through your system package manager (such as ``apt`` or
``yum``) is recommended.


Install DMP/MPI Solver Build Dependencies
"""""""""""""""""""""""""""""""""""""""""

To build and run MFiX with DMP, you will need an MPI implementation installed,
such as OpenMPI.

To install OpenMPI on Ubuntu/Debian derived distributions:

.. code-block:: bash

    $ sudo apt install openmpi-bin libopenmpi-dev

To install OpenMPI on Fedora/RHEL/Centos derived distributions:

.. code-block:: bash

    $ sudo yum install openmpi-devel
    $ module load mpi

.. _create-environment-linux:

Run MFiX in Conda Environment
"""""""""""""""""""""""""""""

To run MFiX:

    #.  Open a terminal
    #.  Run |conda_act_inline|
    #.  Run ``mfix⏎`` to start MFiX

Your prompt should look something like this:

.. code-block:: bash
      :substitutions:

      > conda env create -n mfix-|version| mfix/mfix-|version|-linux64

      > conda env list
      # conda environments:
      #
      base        *  /home/user/anaconda3
      mfix-|version|      /home/user/anaconda3/envs/mfix-|version|

      > conda activate mfix-|version|
      (mfix-|version|) > conda env list
      # conda environments:
      #
      base           /home/user/anaconda3
      mfix-|version|   *  /home/user/anaconda3/envs/mfix-|version|

      (mfix-|version|) > mfix

You are now ready to proceed to the :ref:`user-guide` and :ref:`tutorials`.

.. note::

    Activating a conda environment sets certain environment variables such as
    PATH in the current shell. It does not create a new shell session.

    You will need to activate the environment every time before running MFiX.


Deactivate Conda Environment
""""""""""""""""""""""""""""

After using MFiX you can just ``exit`` to leave the terminal session. However, if
you need to deactivate the |conda_env_inline| conda environment, you can do so with:

.. code-block:: bash
    :substitutions:

    (mfix-|version|)> deactivate
    >

This returns to the base conda environment.

Uninstall MFiX
""""""""""""""

To uninstall MFiX from a conda environment:

.. code-block:: bash
    :substitutions:

    (mfix-|version|)> conda uninstall mfix

To remove the conda environment (if you have the environment activated,
deactivate it first):

.. code-block:: bash
    :substitutions:

    (mfix-|version|)> conda deactivate
    > conda env remove -n mfix-|version|

To uninstall Anaconda entirely, remove the Anaconda directory. By default,
``~/anaconda3`` in your home directory. From the terminal:

.. code-block:: bash

    > cd ~
    > rm -rf anaconda3/

.. note::

    To learn more about managing conda environments, visit the `conda documentation
    <https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html>`__ .