Python bindings for OptFrame Functional Core
Project description
pyoptframe-dev
Development repo for draft versions of Python bindings for OptFrame Functional Core.
Beware that, after officially launched, this project will be migrated into Official Optframe C++ repo (and same strategy applies to other future external language bindings).
Install: python -m pip install optframe
Version: pyoptframe v5.0.24rc0
Documentation and Tutorials: see Draft PyOptFrame Quickstart
Play on Jupyter Notebook: BRKGA TSP Example
OptFrame is a C++ framework for optimization problems, including techniques such as classic metaheuristics Simulated Annealing, Genetic Algorithm, Variable Neighborhood Search, Iterated Local Search, Tabu Search, Particle Swarm Optimization, NSGA-II, and other single and multi-objective methods. This is a 10-year project with several practical applications in industry and academia, so feel free to use it.
How to test locally (devs only)
With Local Package Manager
make install
or pip install .
make test
Without Package Manager (local only)
make optframe_lib
make demo_local
Advice for online environments
Before installing, check C++ compiler (typically GCC) version:
x86_64-linux-gnu-gcc -v
At least gcc-10 is required for C++20... if not enough, try to install g++-10 and make it default. Considering Jupyter notebook syntax:
!apt install -y g++-10
!g++-10 --version
!update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-10 10
!update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-10 10
!update-alternatives --install /usr/bin/x86_64-linux-gnu-gcc gcc /usr/bin/gcc-10 10
Tutorials
Please read the official tutorials for OptFrame C++: https://optframe.readthedocs.io/
Tutorials specific for OptFrame Python is coming!
Example with 0-1 Knapsack Problem
Please see file tests/test_engine_kp.py
for an example with 0-1 Knapsack Problem.
Technical discussions
C++ Standard and Compiler Support
We love Concepts and Optionals, so we require C++20
as default.
However, it is possible to adapt setup.py
in order to allow for C++17
with -fconcepts
on GCC.
If necessary (only C++17 is available), add this line on setup.py
:
extra_compile_args=['--std=c++17', '-fconcepts']
For the moment, GCC and CLANG are officially supported, but more compilers can be added to the list, if demand exists.
optframe_lib
API Organization
The API on optframe_lib
is organized in distict API levels.
Every function on optframe_lib
API starts with the prefix optframe_apiXy
, where
X
represents the level and y
represents the main evaluation type considered.
For now, we support X=1
and y=d
, meaning that API is meant for float64
(or double
) evaluation
spaces (but we certainly plan to add support for i32
, i64
and other types).
Regarding the API level strategy:
- level 0: only for raw (an unsecure) access to internal OptFrame functions
- only use this for testing new features or making extremely efficient and direct function calls to OptFrame internals
- level 1 (STANDARD): this level must provide basic access to fundamental search techniques and to all basic examples
- level 2 (ADVANCED): this level WILL (in the future) also include re-evaluation strategies and other more advanced features of OptFrame C++
- level 3+ (???): maybe we can use this to split advanced functionalities from API2, but only future can tell
In the future, we can also use greater API number to implement possible compatibility breaking features... only future will tell.
Versioning Strategy
Versioning should follow OptFrame C++ project on MAJOR and MINOR, leaving PATCH field to be different, if necessary. Examples:
- v 5 dot 1 dot 3 should include OptFrame C++ 5 dot 1.
- v 5 dot 4 dot 5 could include OptFrame C++ 5 dot 4 dot 8 OR 5 dot 4 dot 1, but NOT 5 dot 6 dot x.
Packaging instructions
Edit setup.py
.
Edit pyproject.toml
.
virtualenv venv
source venv/bin/activate
python -m pip install pip-tools
pip-compile pyproject.toml
pip-sync
For versioning:
python3 -m pip install bumpver
bumpver init
To increase PATCH number:
bumpver update --patch
Test locally:
python3 -m pip install -e .
Build:
python3 -m pip install build twine
python3 -m build
twine check dist/*
twine upload -r testpypi dist/* --verbose
Error: Binary wheel 'optframe-5.0.24rc0-cp39-cp39-linux_x86_64.whl' has an unsupported platform tag 'linux_x86_64'. See 1 and 2.
Solution: rm -f dist/*.whl
twine upload -r testpypi dist/* --verbose
Test if OK on test package website:
python3 -m pip install -i https://test.pypi.org/simple optframe --upgrade
Finally:
twine upload dist/*
python3 -m pip install optframe --upgrade
Thanks again to: https://realpython.com/pypi-publish-python-package/
Known Issues
All known issues fixed :)
Thanks
Thanks to the general help from Internet posts, this project could be packaged on Python (there are many links all around the source code mentioning the respective authors).
Also thanks for the encouragement and fruitful discussions with my students, specially, Rafael Albuquerque, Marcos Souza, Victor Silva and Fellipe Pessanha.
License
At your choice:
Copyleft 2023
Igor Machado Coelho
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.