Install Guide
=============

Register
--------

Nodeworks is an open-source multiphase flow solver and is free to download and
use. A one-time no-cost registration is required prior to downloading the
software. To register, go to https://mfix.netl.doe.gov/register and submit your
account information. Your application will be manually been reviewed and
accepted, so please allow for 2-3 business days for your registration to be
processed. You will receive a confirmation email when you can login.

OS Support
----------

Nodeworks is a pure python library. As a result, all operating systems that
python and the dependencies can be installed on will run nodeworks.

Installation
------------

There are two methods for installing Nodeworks:
1. Use conda, which will install the required dependencies; or
2. Use poetry, which will create a virtual environment; or
2. From source, which will require you to manually install the dependencies

.. Note::
   If you are install Nodeworks as a plugin to MFiX, please see the `MFiX-plugin
   specific documentation`_.

Conda install
+++++++++++++

The easiest and recommended way to install nodeworks and the dependencies is
through the Anaconda Distribution. Download and install Miniconda_ or Anaconda_.

Once Miniconda_ or Anaconda_ are installed:

- Browse to the `Nodeworks Download Page`_
- Copy the conda install command. The conda command will look similar to this,
  but with your own individual username and hexadecimal token (please do not
  share these unique tokens)::

   conda install nodeworks -c mfix -c https://mfix.netl.doe.gov/s3/HEX/HEX/conda/dist

- Paste the conda install command into your Linux or Mac terminal, or into your
  `Anaconda Prompt` on Windows and Execute the install command.

.. Note::
  On Windows, to open the `Anaconda Prompt`, go to the start menu and search For
  Anaconda Prompt. The `Anaconda Prompt` sets up the correct environment, adding
  `conda` and other commands.

The installation will download other dependencies and Nodeworks. The process
will take a few minutes to complete. Once completed, the application can be
started by entering the following command into your Linux or Mac terminal, or
into your `Anaconda Prompt` on Windows::

  nodeworks

.. Note::
   On Windows, a desktop icon might be created, depending on user permissions.


Using Poetry
++++++++++++

`Poetry <https://python-poetry.org/>`_ is a tool for managing dependencies. To
use poetry, first `install poetry <https://python-poetry.org/docs/#installation>`_
if you do not already have it. Then follow the following steps:

- Browse to the `Nodeworks Download Page`_
- Download the tarball, extract, and go into the top level source directory::

   tar xf nodeworks-*.tar.gz
   cd nodeworks

- install nodeworks with::

   poetry install

- Run Nodeworks with::

   poetry run nodeworks


From source
+++++++++++

If you already have a python environment setup without using Miniconda_ or
Anaconda_, nodeworks can be installed from source:

- Browse to the `Nodeworks Download Page`_
- Download the tarball, extract, and go into the top level source directory::

   tar xf nodeworks-*.tar.gz
   cd nodeworks

- install nodeworks with::

   python setup.py install

Please see the dependencies listed below. Once completed and the dependencies
are met, the application can be started by using the following command::

     nodeworks

.. Note::
  To build the local documentation, the following libraries are required:
  - sphinx
  - sphinx_rtd_theme

Required Dependencies
---------------------

If the `conda install` command was used as recommended above, these dependencies
have already been satisfied. If you installed from source or are missing nodes,
the following libraries are required:

- A Qt wrapper: PyQt4, PyQt5, or PySide
- qtpy

qtpy can easily be installed via::

  pip install qtpy

These requirements can be easily met by using Anaconda_.

Node Dependencies
-----------------

Nodes can have other dependencies, based on their functionality. These
dependencies are soft, meaning that they will not prevent nodeworks from,
loading. They will only prevent nodes that depend on these dependencies from
loading.

If using Miniconda_ or Anaconda_, these dependencies can be easily installed
with the following conda command::

  conda install <dependency>

Surrogate modeling and analysis toolset
+++++++++++++++++++++++++++++++++++++++

.. Note:: If you installed Nodeworks using the conda command (i.e. not from
          source), these dependencies have already been installed. You may skip
          this section.

For the ``Surrogate modeling and analysis toolset``, the following libraries are
required:

- numpy
- matplotlib
- scikit-learn
- scipy
- SALib
- py-earth

most of the libraries are in ``conda`` and can easily be installed with::

  conda install numpy matplotlib scikit-learn scipy

``py-earth`` is an add-on to scikit-learn, providing the MARS response surface
model. It can be installed with conda::

  conda install -c conda-forge sklearn-contrib-py-earth

``salib`` is used to perform sensitivity analysis. It can also be installed with
conda::

  conda install -c conda-forge salib

image processing
++++++++++++++++

For image processing nodes, these libraries are used:

- opencv
- scikit-image
- imageio
- numpy
- scipy

and can easily be installed with conda::

  conda install opencv scikit-image imageio numpy scipy

wavelets
++++++++

For wavelet analysis, the following library is used:

- pywavelets

and can easily be installed with conda::

  conda install pywavelets


Update
------

To update nodeworks, follow the above install instructions

Uninstall
---------

If installed with conda, uninstall by running the following command::

  conda uninstall nodeworks

If installed from source, uninstall by running::

  pip uninstall nodeworks



.. _Anaconda: http://anaconda.com/distribution
.. _Miniconda: https://conda.io/en/latest/miniconda.html
.. _`Nodeworks Download Page`: https://mfix.netl.doe.gov/mfix/download-nodeworks
.. _`MFiX-plugin specific documentation`: ../mfix_plugin/index.html