bolib3 3.0.1

Welcome to BOLIB3, a benchmarking library of continuous bilevel optimization problems.

BOLIB-3

Bilevel Optimisation Library

• BOLIB-3
  • Bilevel optimisation
  • Installation
  • Contributing
  • Unit tests
  • Authors

Bilevel optimisation

The bilevel program is defined as an upper-level program with a second lower-level program embedded in its constraints. It is written as follows:

minimise_{x,y} F(x,y);  
subject to     G(x,y)>=0;  
               H(x,y)==0;  
               y ∈ argmin_{y}{ f(x,y):
                             { g(x,y)>=0;  
                             { h(x,y)=0.

The choice between representing inequality constraints as non-negative (>=0) or non-positive (<=0) remains inconsistent throughout the literature. In this library we follow the non-negative (>=0) formulation. The notation defined in the table below is consistent thought the library:

Symbol	Level	Represent	Dimension
x	Upper-level	Decision variables	n_x
y	Lower-level	Decision variables	n_x
F(x,y)	Upper-level	Objective function	1
f(x,y)	Lower-level	Objective function	1
G(x,y)	Upper-level	Inequality constraint functions	m_G
g(x,y)	Lower-level	Inequality constraint functions	m_g
H(x,y)	Upper-level	Equality constraint functions	m_H
h(x,y)	Lower-level	Equality constraint functions	m_h

Requirements

Depending on your usage, you may require:

• A LaTeX and BibTeX compiler (miktex.org)
• Python 3 (python.org) (pip install -r requirements.txt)
• GAMS (gams.com)
• MATLAB (matlab.mathworks.com)

Contributing

This is a community project to gather an extensive collection of bilevel programs for robust benchmarking. Please do contribute! There are a few things to note. You will need to request collaborator access from [e-mail]. Please follow the standard file layouts found in the template folder.

1. Clone the repository (git clone https://github.com/bolib3/bolib3)
2. Create a personal branch (git checkout -b BranchName)
3. Commit your Changes (git commit -m 'comment')
4. Push to the Branch (git push origin BranchName)
5. Open a Pull Request

ALL file and directory names are to be lowercase!!

Unit tests

The unit tests check that the library is set up correctly. From the top level directory run:

python -m unittest "automation\unit_tests\python_unit_tests.py"

matlab -r "run('automation\unit_tests\matlab_test_suite.m')"

1. Test 001: Check that the file structure is consistent. For example the folder 'latex' should only contain '.tex' files.
2. Test 002: Checks that each bilevel program has a complete set of non-empty files. For example every instance 'example' must have a corresponding 'example.json' and 'example.pdf' file.
3. Test 003: Checks that each python module (respectively matlab class) representing a bilevel program implements all the necessary properties (e.g. 'name', 'category') and methods (e.g. F, G, ...).
4. Test 004: Checks that the JSON metadata files are consistent. They should fulfill the schema file and the properties should match the properties in the python/matlab files.
5. Test 005: Some bilevel programs have a list of datasets. This tests that there exists a file for each of them within /bolib3/data/.
6. Test 006: Checks the functions F,G,H,f,g,h return arrays of the correct dimension.
7. Test 007: Checks the solutions recorded in the JSON metadata are feasible.

Authors

Name	Email
Samuel Ward	[e-mail]
Yaru Qian	[e-mail]
Jordan Fisher	[e-mail]
Alain Zemkoho	[e-mail]