.. _install-mfix-osx:

MFiX Installation on Mac
------------------------

MFiX is supported on the MacOS platform as of MFiX release 22.2.  We provide installable packages for both Intel and M1-based Macs.  In the following, ``arm64`` refers to M1 (Apple Silicon) and ``x86_64`` refers to Intel CPUs.

If you have an issue running or installing MFiX on your system, ask for help at :ref:`support-forum`.

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

**Download** the Python 3, Mac 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). Either
the Graphical Installer or Command Line Installer would work.  Choose the M1 version
if you have a newer Mac with Apple Silicon CPU.

For instance, with the Anaconda Graphical Installer:

    #.  Open up Finder and navigate to the Download directory.
    #.  Double-click the downloaded file. (At the time of writing,
        ``Anaconda3-2022.10-MacOSX-x86_64.pkg`` or ``Anaconda3-2022.10-MacOSX-arm64.pkg`` for
        for Graphical Installer).
    #.  Follow the installation guide, using the default settings.


Alternative:  Install Miniforge/mamba
=====================================

`Miniforge <https://conda-forge.org/miniforge/>`__ is a version of
miniconda which is set up by default to use the ``conda-forge`` package
repository (which MFiX uses), and also the ``mamba`` package manager,
which is a version of ``conda`` that was rewritten for better
performance.

If you already have an Anaconda installation, you may continue to use
it, but if you have never installed MFiX before you may want to try
miniforge, for smaller download and faster installation.

**Download** the Mambaforge MacOSX installer for either ``arm64`` (Apple Silicon) or ``x86_64`` (Intel), depending on your hardware, from the `Miniforge release page <https://conda-forge.org/miniforge/>`__, and run it.

At the time of writing, the current mambaforge release is 22.11.1-2 and the files are ``Mambaforge-22.11.1-2-MacOSX-arm64.sh`` and ``Mambaforge-22.11.1-2-MacOSX-x86_64.sh``.

In order to use ``mamba``, replace the ``conda`` command by ``mamba`` in the following instructions.  If there is any problem with a ``mamba`` command, you can try again with ``conda`` - note that ``mamba`` is still somewhat new and may occasionally exhibit bugs.


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

After installing Anaconda or Miniforge, install MFiX:

    #.  Open a Terminal (Type "⌘-Spacebar", type "terminal")
    #.  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.
    #.  If using Miniforge, change ``conda`` to ``mamba`` at the start of the command.
    #.  Press enter to run the command

.. 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 may take a few
minutes to complete.

.. _create-environment-osx:

Run MFiX
""""""""

Open Terminal (if not open already), and run the following commands:

    #.  Run |conda_act_inline|
    #.  Run ``mfix⏎``

Your prompt should look something like this:

.. code-block:: bash
      :substitutions:

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

      > conda activate mfix-|version|
      (mfix-|version|) > conda env list
      # conda environments:
      #
      base           /Users/user/anaconda3
      mfix-|version|   *  /Users/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|)> conda deactivate
    >

This returns to the base conda environment.

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

To remove an MFiX version installed with Conda, 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/

If using Miniforge, note that the directory is ``~/mambaforge``

.. 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>`__ .