ParMOO

ParMOO: A Python library for parallel multiobjective simulation optimization - Published in JOSS (2023)

https://github.com/parmoo/parmoo

Keywords

Repository

Python library for parallel multiobjective simulation optimization

README.rst

.. image:: docs/img/logo-ParMOO.svg
    :align: center
    :alt: ParMOO

|

.. image:: https://img.shields.io/badge/License-BSD_3--Clause-green.svg
    :target: https://opensource.org/licenses/BSD-3-Clause
    :alt: License

.. image:: https://img.shields.io/pypi/v/parmoo.svg?color=green
    :target: https://pypi.org/project/parmoo

.. image:: https://github.com/parmoo/parmoo/actions/workflows/parmoo-ci.yml/badge.svg?/branch=main
    :target: https://github.com/parmoo/parmoo/actions

.. image:: https://readthedocs.org/projects/parmoo/badge/?maxAge=2592000
    :target: https://parmoo.readthedocs.org/en/latest
    :alt: Documentation Status

.. image:: https://joss.theoj.org/papers/10.21105/joss.04468/status.svg
   :target: https://doi.org/10.21105/joss.04468
   :alt: JOSS DOI

.. image:: https://coveralls.io/repos/github/parmoo/parmoo/badge.svg?branch=main
   :target: https://coveralls.io/github/parmoo/parmoo?branch=main

|

ParMOO: Python library for parallel multiobjective simulation optimization
==========================================================================

ParMOO is a parallel multiobjective optimization solver that seeks to
exploit simulation-based structure in objective and constraint functions.

To exploit structure, ParMOO models *simulations* separately from
*objectives* and *constraints*. In our language:

 * a **design variable** is an input to the problem, which we can directly
   control;
 * a **simulation** is an expensive or time-consuming process, including
   real-world experimentation, which is treated as a blackbox function
   of the design variables and evaluated sparingly;
 * an **objective** is an algebraic function of the design variables
   and/or simulation outputs, which we would like to optimize; and
 * a **constraint** is an algebraic function of the design variables
   and/or simulation outputs, which cannot exceed a specified bound.

.. figure:: docs/img/des-sim-obj-space.png
    :alt: Designs, simulations, and objectives
    :align: center

|

To solve a multiobjective optimization problem (MOOP), we use surrogate
models of the simulation outputs, together with the algebraic definition of
the objectives and constraints.

ParMOO is implemented in Python. In order to achieve scalable parallelism,
we use libEnsemble_ to distribute batches of simulation evaluations across
parallel resources.

Dependencies
------------

ParMOO has been tested on Unix/Linux and MacOS systems.

ParMOO's base has the following dependencies:

 * Python_ 3.8+
 * 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

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

The easiest way to install ParMOO is via the Python package index, PyPI
(commonly called ``pip``):

.. code-block:: bash

    pip install < --user > parmoo

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

To install *all* dependencies (including libEnsemble) use:

.. code-block:: bash

    pip install < --user > "parmoo[extras]"

You can also clone this project from our GitHub_ and ``pip`` install it
in-place, so that you can easily pull the latest version or checkout
the ``develop`` branch for pre-release features.
On Debian-based systems with a bash shell, this looks like:

.. code-block:: bash

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

Alternatively, the latest release of ParMOO (including all required and
optional dependencies) can be installed from the ``conda-forge`` channel using:

.. code-block:: bash

   conda install --channel=conda-forge parmoo

Before doing so, it is recommended to create a new conda environment using:

.. code-block:: bash

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

Testing
-------

If you have pytest_ with the pytest-cov_ plugin and flake8_ installed,
then you can test your installation.

.. code-block:: bash

   python3 setup.py test

These tests are run regularly using GitHub Actions_.

Basic Usage
-----------

ParMOO uses numpy_ and jax_ in an object-oriented design, based around the
``MOOP`` class.

Before getting started, note that jax_ runs in single (32-bit) precision
by default. To run in double precision, the following code is needed at
startup:

.. code-block:: python

    import jax
    jax.config.update("jax_enable_x64", True)

This will be done automatically when importing certain modules in ParMOO,
which are only compatible with double precision.
However, in many use cases, 32-bit precision may be enough and provides
substantial speedup in iteration tasks.

Once the precision is set, to get started, create a ``MOOP`` object.

.. code-block:: python

   from parmoo import MOOP
   from parmoo.optimizers import LocalGPS

   my_moop = MOOP(LocalGPS)

To summarize the framework, in each iteration ParMOO models each simulation
using a computationally cheap surrogate, then solves one or more scalarizations
of the objectives, which are specified by acquisition functions.
Read more about this framework at our ReadTheDocs_ page.
In the above example, ``LocalGPS`` is the class of optimizers that the
``my_moop`` will use to solve the scalarized surrogate problems.

Next, add design variables to the problem as follows using the
``MOOP.addDesign(*args)`` method. In this example, we define one continuous
and one categorical design variable.
Other options include integer, custom, and raw (using raw variables is not
recommended except for expert users).

.. code-block:: python

   # Add a single continuous design variable in the range [0.0, 1.0]
   my_moop.addDesign({'name': "x1", # optional, name
                      'des_type': "continuous", # optional, type of variable
                      'lb': 0.0, # required, lower bound
                      'ub': 1.0, # required, upper bound
                      'tol': 1.0e-8 # optional tolerance
                     })
   # Add a second categorical design variable with 3 levels
   my_moop.addDesign({'name': "x2", # optional, name
                      'des_type': "categorical", # required, type of variable
                      'levels': ["good", "bad"] # required, category names
                     })

Next, add simulations to the problem as follows using the
``MOOP.addSimulation`` method. In this example, we define a toy simulation
``sim_func(x)``.

.. code-block:: python

   import numpy as np
   from parmoo.searches import LatinHypercube
   from parmoo.surrogates import GaussRBF

   # Define a toy simulation for the problem, whose outputs are quadratic
   def sim_func(x):
      if x["x2"] == "good":
         return np.array([(x["x1"] - 0.2) ** 2, (x["x1"] - 0.8) ** 2])
      else:
         return np.array([99.9, 99.9])
   # Add the simulation to the problem
   my_moop.addSimulation({'name': "MySim", # Optional name for this simulation
                          'm': 2, # This simulation has 2 outputs
                          'sim_func': sim_func, # Our sample sim from above
                          'search': LatinHypercube, # Use a LHS search
                          'surrogate': GaussRBF, # Use a Gaussian RBF surrogate
                          'hyperparams': {}, # Hyperparams passed to internals
                          'sim_db': { # Optional dict of precomputed points
                                     'search_budget': 10 # Set search budget
                                    },
                         })

Now we can add objectives and constraints using ``MOOP.addObjective(*args)``
and ``MOOP.addConstraint(*args)``. In this example, there are 2 objectives
(each corresponding to a single simulation output) and one constraint.

.. code-block:: python

   # First objective just returns the first simulation output
   def f1(x, s): return s["MySim"][0]
   my_moop.addObjective({'name': "f1", 'obj_func': f1})
   # Second objective just returns the second simulation output
   def f2(x, s): return s["MySim"][1]
   my_moop.addObjective({'name': "f2", 'obj_func': f2})
   # Add a single constraint, that x[0] >= 0.1
   def c1(x, s): return 0.1 - x["x1"]
   my_moop.addConstraint({'name': "c1", 'constraint': c1})

Finally, we must add one or more acquisition functions using
``MOOP.addAcquisition(*args)``. These are used to scalarize the surrogate
problems. The number of acquisition functions typically determines the
number of simulation evaluations per batch. This is useful to know if you
are using a parallel solver.

.. code-block:: python

   from parmoo.acquisitions import RandomConstraint

   # Add 3 acquisition functions
   for i in range(3):
      my_moop.addAcquisition({'acquisition': RandomConstraint,
                              'hyperparams': {}})

Finally, the MOOP is solved using the ``MOOP.solve(budget)`` method, and the
results can be viewed using ``MOOP.getPF()`` method.

.. code-block:: python

   import pandas as pd

   my_moop.solve(5) # Solve with 5 iterations of ParMOO algorithm
   results = my_moop.getPF(format="pandas") # Extract the results as pandas df

After executing the above block of code, the ``results`` variable points to
a pandas_ dataframe, each of whose rows corresponds to a nondominated
objective value in the ``my_moop`` object's final database.
You can reference individual columns in the ``results`` array by using the
``name`` keys that were assigned during ``my_moop``'s construction, or
plot the results by using the viz_ library.

Congratulations, you now know enough to get started solving MOOPs with
ParMOO!

Next steps:

 * Learn more about all that ParMOO has to offer (including saving and
   checkpointing, INFO-level logging, advanced problem definitions, and
   different surrogate and solver options) at our ReadTheDocs_ page.
 * Explore the advanced examples (including a ``libEnsemble`` example)
   in the ``examples`` directory.
 * Install libEnsemble_ and get started solving MOOPs in parallel.
 * See some of our pre-built solvers in the parmoo_solver_farm_.
 * To interactively explore your solutions, install its extra dependencies and
   use our built-in viz_ tool.
 * For more advice, consult our FAQs_.

Resources
---------

To seek support or report issues, e-mail:

 * ``parmoo@lbl.gov``

Our full documentation is hosted on:

 * ReadTheDocs_

Recent versions of ParMOO are also incorporated in:

 * BANDFramework_

Please read our LICENSE_ and CONTRIBUTING_ files.

Citing ParMOO
-------------

Please use one or more of the following to cite ParMOO.

Our JOSS paper:

.. code-block:: bibtex

    @article{parmoo,
        author={Chang, Tyler H. and Wild, Stefan M.},
        title={{ParMOO}: A {P}ython Library for Parallel Multiobjective Simulation Optimization},
        journal = {Journal of Open Source Software},
        volume = {8},
        number = {82},
        pages = {4468},
        year = {2023},
        doi = {10.21105/joss.04468}
    }

Our online documentation:

.. code-block:: bibtex

    @techreport{parmoo-docs,
        title       = {{ParMOO}: {P}ython Library for Parallel Multiobjective Simulation Optimization},
        author      = {Chang, Tyler H. and Wild, Stefan M. and Dickinson, Hyrum},
        institution = {Argonne National Laboratory},
        number      = {Version 0.4.1},
        year        = {2024},
        url         = {https://parmoo.readthedocs.io/en/latest}
    }

Our design principles paper:

.. code-block:: bibtex

    @techreport{ParMOODesign24,
        title = {Designing a Framework for Solving Multiobjective Simulation Optimization Problems},
        author = {Tyler H. Chang and Stefan M. Wild},
        institution = {arXiv},
        number = {2304.06881},
        year = {2024},
        url = {https://arxiv.org/abs/2304.06881},
    }


.. _Actions: https://github.com/parmoo/parmoo/actions
.. _BANDFramework: https://github.com/bandframework/bandframework
.. _CONTRIBUTING: https://github.com/parmoo/parmoo/blob/main/CONTRIBUTING.rst
.. _dash: https://dash.plotly.com
.. _FAQs: https://parmoo.readthedocs.io/en/latest/faqs.html
.. _flake8: https://flake8.pycqa.org/en/latest
.. _GitHub: https://github.com/parmoo/parmoo
.. _jax: https://jax.readthedocs.io/en/latest/
.. _kaleido: https://github.com/plotly/Kaleido
.. _libEnsemble: https://github.com/Libensemble/libensemble
.. _LICENSE: https://github.com/parmoo/parmoo/blob/main/LICENSE
.. _numpy: https://numpy.org
.. _pandas: https://pandas.pydata.org
.. _parmoo_solver_farm: https://github.com/parmoo/parmoo-solver-farm
.. _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
.. _viz: https://parmoo.readthedocs.io/en/latest/modules/viz.html

Owner

JOSS Publication

ParMOO: A Python library for parallel multiobjective simulation optimization

Published

February 03, 2023

DOI

10.21105/joss.04468

Volume 8, Issue 82, Page 4468

Authors

Tyler H. Chang
Mathematics and Computer Science Division, Argonne National Laboratory, USA

Stefan M. Wild
Applied Mathematics and Computational Research Division, Lawrence Berkeley National Laboratory, USA, Mathematics and Computer Science Division, Argonne National Laboratory, USA, NAISE, Northwestern University, USA

Editor

Kelly Rowland

Tags

numerical optimization multiobjective optimization response surface methodology parallel simulations

View PDF Review Thread Software Archive

GitHub Events

Committers

Last synced: 5 months ago

Issues and Pull Requests

Last synced: 4 months ago

Packages