Advanced Installation

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:

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:

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:

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:

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:

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:

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.

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:

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 extras.libe), you will need to also install libEnsemble.

To install libEnsemble with PyPI, use

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:

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.

These tests are run regularly using GitHub Actions.