Advanced Installation
=====================

.. _install:

ParMOO can be installed with ``pip`` or directly from its GitHub_ source.

ParMOO's base has the following dependencies, which may be automatically
installed depending on your choice of method:

 * Python_ 3.9+
 * jax_ -- for algorithmic differentiation and just-in-time (jit) compilation
 * numpy_ -- for data structures and performant numerical linear algebra
 * scipy_ -- for scientific calculations needed for specific modules
 * pandas_ -- for exporting the resulting databases

Additional dependencies are needed to use the additional features in
``parmoo.extras``:

 * libEnsemble_ -- for managing parallel simulation evaluations

And for using the Pareto front visualization library in ``parmoo.viz``:

 * plotly_ -- for generating interactive plots
 * dash_ -- for hosting interactive plots in your browser
 * kaleido_ -- for exporting static plots post-interaction

If you want to run the tests (in ``parmoo.tests``), then you will also need:

 * pytest_,
 * pytest-cov_,
 * flake8_, and
 * flake8-pyproject.

Note that the full feature set for libEnsemble_ and kaleido_ may require you to
separately install an MPI implementation (such as Open_MPI_) and Google chrome
(e.g., via kaleido_get_chrome_), respectively.

pip
---

The easiest way to install is via the PyPI package manager (``pip`` utility).
To install the latest release:

.. code-block:: bash

    pip install < --user > parmoo

where the braces around ``< --user >`` indicate that the ``--user`` flag is
optional.

Note that the default install will not install the extra dependencies,
such as libEnsemble_.

To install *all* dependencies, use:

.. code-block:: bash

    pip install < --user > parmoo[extras]

Again, note that the full feature set for libEnsemble_ and kaleido_ may require
you to separately install an MPI implementation (such as Open_MPI_) and Google
chrome (e.g., via kaleido_get_chrome_), respectively.

Conda Forge
-----------

For some users (in particular, this is the recommended method for Windows
users), the preferred method for obtaining the latest release of
ParMOO may be through the ``conda`` package manager.
The latest release of ParMOO is available through the ``conda-forge`` channel.
Note that ``conda`` does not support optional dependencies, so the following
command will automatically fetch all required and optional dependencies:

.. code-block:: bash

   conda install --channel=conda-forge parmoo

Before running the above command, it is recommended to create a new conda
environment to avoid conflicts.
Do so using:

.. code-block:: bash

   conda create --name channel-name
   conda activate channel-name

After performing a ``conda-forge`` installation of ParMOO, you can run
our unit tests to make sure your installation is working:

.. code-block:: bash

   py.test --pyargs parmoo.tests.unit_tests

Install from GitHub source
--------------------------

You may want to install ParMOO from its GitHub_ source code, so that
you can easily pull the latest updates.

The easiest way to do this is to clone it from our GitHub_ and then
``pip`` install it in-place by using the ``-e .`` option.
In a bash shell, that looks like this.

.. code-block:: bash

   git clone https://github.com/parmoo/parmoo
   cd parmoo
   pip install -e .

This command will use the ``pyproject.toml`` file to generate an ``egg`` inside
the ``parmoo`` base directory.

Alternatively, you could just add the ``parmoo`` base directory to your
``PYTHONPATH`` environment variable. In the bash shell, this looks like:

.. code-block:: bash

   git clone https://github.com/parmoo/parmoo
   cd parmoo
   export PYTHONPATH=$PYTHONPATH:`pwd`

However, this technique will not install any of ParMOO's dependencies.

Additionally, if you would like to use libEnsemble_ to handle parallel
function evaluations (from :mod:`extras.libe`),
you will need to also install libEnsemble_.

To install libEnsemble with PyPI, use

.. code-block:: bash

   pip3 install libensemble

or visit the libEnsemble_documentation_ for detailed installation instructions.

Testing
-------

If you've done a full installation using any of the above methods (including
all the ``parmoo[extras]``), you can also run the unit tests to confirm the
installation.
To run the tests, you can install pytest_ with the pytest-cov_ plugin and
flake8_ using the ``tests`` extension, then you can lint the project with
``flake8`` and run the unit tests for your installation using ``pytest``. After
running unit tests, you can view the coverage report using the
``coverage report`` command.
E.g., using ``pip``, running the tests looks something like this:

.. code-block:: bash

   pip install -e ".[tests]"
   flake8 parmoo
   pytest
   coverage report

Running the regression tests and libensemble tests is a bit more involved and
is usually accomplished via the ``-l`` flag for the
``parmoo/tests/run-tests.sh`` script.

To run all the linter, unit tests, regression tests, and generate the coverage
report in a single command, run the script with all 4 flags set.

.. code-block::bash

   ./parmoo/tests/run-tests.sh -curl

These tests are run regularly using GitHub Actions_.


.. _Actions: https://github.com/parmoo/parmoo/actions
.. _dash: https://dash.plotly.com
.. _flake8: https://flake8.pycqa.org/en/latest
.. _GitHub: https://github.com/parmoo/parmoo
.. _jax: https://docs.jax.dev/en/latest/
.. _kaleido: https://github.com/plotly/Kaleido
.. _kaleido_get_chrome: https://pypi.org/project/Kaleido
.. _libEnsemble: https://github.com/Libensemble/libensemble
.. _libEnsemble_documentation: https://libensemble.readthedocs.io/en/main/advanced_installation.html
.. _numpy: https://numpy.org
.. _Open_MPI: https://docs.open-mpi.org/en/v5.0.x/installing-open-mpi/quickstart.html
.. _pandas: https://pandas.pydata.org
.. _plotly: https://plotly.com/python
.. _pytest: https://docs.pytest.org/en/7.0.x
.. _pytest-cov: https://pytest-cov.readthedocs.io/en/latest
.. _Python: https://www.python.org/downloads
.. _ReadTheDocs: https://parmoo.readthedocs.org
.. _scipy: https://scipy.org