Skip to content

mfgustavo/glompo

Repository files navigation

docs/_static/banner.gif


https://img.shields.io/github/v/tag/mfgustavo/glompo?style=for-the-badge

https://img.shields.io/github/last-commit/mfgustavo/glompo?style=for-the-badge

https://img.shields.io/github/issues-raw/mfgustavo/glompo?style=for-the-badge

https://img.shields.io/github/license/mfgustavo/glompo?style=for-the-badge

GloMPO (Globally Managed Parallel Optimization) is an optimisation framework which supervises and controls traditional optimization routines in real-time using customisable heuristics. By monitoring the performance of each of these optimizers in real time, the GloMPO manager is able to make decisions to terminate and start new optimizers in better locations.

GloMPO is designed to be used on high-dimensional, expensive, multimodal, black-box optimization problems but simpler problems are not precluded.

The three main advantages to optimization in this way:

  1. Optimizers are pushed out of local minima, thus more and better solutions are more likely to be found;
  2. Through terminations of optimizers stuck in local minima, function evaluations can be used more efficiently;
  3. The use of multiple optimizers allows multiple competitive/equivalent solutions to be found.

docs/_static/demo.gif

[Back to Top]

The most straightforward method to download and install GloMPO into your Python environment is to install GloMPO directly using:

pip install git+https://github.com/mfgustavo/glompo

If you would like access to the test suite, examples, or wish to have a separate editable copy of the source code, you may want to download the code separately. This may be done directly from GitHub, or it may be cloned into a target directory using:

git clone https://github.com/mfgustavo/glompo.git

Installation is easy after download:

cd /path/to/glompo
pip install .

This will copy the GloMPO source code into your Python environment. If you are developing for GloMPO, you may prefer to install in developer mode:

cd /path/to/glompo
pip install -e .

This will not copy the source code and GloMPO will be read directly from the directory into which it was downloaded or extracted.

The installation will only install core GloMPO dependencies. Packages required for optional features must be installed manually. These features and their dependencies can be consulted in the documentation.

To install GloMPO with optional dependencies:

pip install .[cma,checkpointing,...]

You should confirm that everything is working correctly by running the tests in the tests folder. Running the tests requires pytest be installed to your Python environment. This is not installed automatically with GloMPO, but can be done with the testing install option.

cd /path/to/glompo
pytest

Note

Tests which require optional components will be automatically skipped if the required packages are not installed.

Note

If your tests fail, please raise an issue as detailed in the Issues section.

[Back to Top]

Usage of GloMPO requires, at a minimum:

  1. Specification of the task to be minimised;
  2. The bounds of the parameters;
  3. The local optimizers to be used.

GloMPO includes a set of common multidimensional global optimization test functions which are useful to benchmark different configurations of the manager. In this example the Shubert function will be used.

from glompo.core.manager import GloMPOManager
from glompo.opt_selectors import CycleSelector
from glompo.optimizers import CMAOptimizer  # Requires cma package
from glompo.benchmark_fnc import Shubert

task = Shubert()

manager = GloMPOManager(task=task,
                        opt_selector=CycleSelector([CMAOptimizer]),
                        bounds=task.bounds)

result = manager.start_manager()

print(f"Minimum found: {result.fx}")

For a more detailed explanation of GloMPO's use, please consult the examples folder and the documentation.

Below is a brief introduction to the most important components of the code to orientate first-time users. GloMPO is implemented in a modular way such that all decision criteria is customizable.

core

This package contains the most important GloMPO components:

manager.py
Contains GloMPOManager the primary point of entry into the code. The manager performs the actual optimzation, accepts all settings, and produces all the output.
checkpointing.py
Contains CheckpointingControl which configures GloMPO's ability to save a snapshot of itself during an optimization from which it can resume later.
function.py
An API template for the optimization task from which it may, but need not, inherit.
scope.py
GloMPO infrastructure to produce real-time video recordings of optimizations.
opt_selectors
Each file contains a different BaseSelector child-class. These objects decide which optimizer configuration to start from a list of options.
optimizers
Each file contains a different BaseOptimizer child-class. These are implementations or wrappers around actual optimization algorithms.
generators
Each file contains a different BaseGenerator child-class. These are algorithms which decide where optimizers are started within the search domain.
convergence

Each file contains a different BaseChecker child-class. These are simple conditions which control GloMPO's overall termination conditions. These classes/conditions can be combined into more sophisticated ones, for example:

MaxSeconds(6000) | MaxFuncCalls(30_000) & MaxOptStarted(5)
hunters
Each file contains a different BaseHunter child-class. These are termination conditions which, if satisfied, will get GloMPO to trigger an early termination of a particular optimizer. These classes/conditions can be combined similarly to BaseCheckers:
benchmark_fncs
A collection of well-known global optimization test functions. These are often faster to evaluate than the actual function one wishes to minimize. Using these can be helpful to quickly configure GloMPO before applying it to more time-consuming tasks.

[Back to Top]

Raise any issues encountered on the appropriate GitHub page. Please include a MWE of the problem, a list of packages installed in your python environment, and a detailed description of the workflow which led to the error.

[Back to Top]

Contributions are welcome and can be submitted as pull requests here. Before contributing new material, please raise a new issue and tag it as enhancement. This will provide an opportunity to discuss the proposed changes with other contributors before a new feature is introduced.

Pull request checklist:

  1. Please ensure that your contributions follow general PEP 8 style guidelines;
  2. Only submit documented code;
  3. Make sure that all existing tests still pass or update the failing ones if they are no longer relevant;
  4. Include new tests if the current suite does not cover your contributions;
  5. Keep each pull request small and linked to a single issue.

[Back to Top]

GloMPO is licensed under GPL-3.0.

If you find GloMPO useful, please cite the follow article in your work:

Freitas Gustavo, M., Verstraelen, T. GloMPO (Globally Managed Parallel Optimization): a tool for expensive, black-box optimizations, application to ReaxFF reparameterizations. J Cheminform 14, 7 (2022). https://doi.org/10.1186/s13321-022-00581-z