OptFrame

<p align="center"> <a href="https://github.com/optframe/optframe"> <img src="https://tokei.rs/b1/github/optframe/optframe?category=lines" alt="Current total lines."> </a> <a href="https://github.com/optframe/optframe/blob/master/COPYING.LESSERv3"> <img src="https://img.shields.io/badge/License-LGPL%20v3-blue.svg" alt="LGPLv3 License."> </a> <a href="https://github.com/optframe/optframe/blob/master/LICENSE"> <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License."> </a> </p>

OptFrame - C++ Optimization Framework

OptFrame is a multi-language combinatorial optimization framework for metaheuristics written in modern C++.

Ongoing version: development optframe v6 pre-release

OptFrame 5.1.0 is released.

• Python version: For optframe python, just pip install optframe. See github.com/optframe/pyoptframe
• Rust version: See OptFrame Rust (under construction)
• Java version: See JOptFrame on sourceforge

Project uses semantic versioning, so to patch it, run: bumpver update --patch

Now, with newest C++20 features and integrated Unit Testing for user projects and examples (still ongoing work). Scanner++ library is also dettached independent project now. Remember to clone this repo using --recursive option, so you don't miss anything ;)

Major changes happened from v3 to v4, so we will need to update our tutorials...

---

Official Documentation on ReadTheDocs

Try the Demos on ReadTheDocs Quickstart

• 00_SimpleBuild: 00_SimpleBuild -
• 01_QuickstartWelcome: 01_QuickstartWelcome -
• 02_QuickstartKP_SA: 02_QuickstartKP_SA -
• 03_QuickstartTSP_VNS_BRKGA: 03_QuickstartTSP_VNS_BRKGA -
• 05_Advanced_TSP_checkmodule: 05_Advanced_TSP_checkmodule -

Also we provide a C library for Windows, Linux and Mac:

• OptFrameLib: OptFrameLib -

Note that OptFrame website may have obsolete documentation and examples:

~Check https://optframe.github.io/docs/quick-start-guide/~

Intended changes for Major 6

• standard component names (DONE!)
• tested c library (DONE!)
• support c++23 import std and cxx modules (ongoing!)
• fix formatter and ostream for cxxmodules
• support callbacks in metaheuristic and local search implementations (DONE!)
  • onBest
  • onLocalOptimum
  • onFinishLocal
  • onFinishGlobal

Intended changes for Major 5

• support global library for multiple languages (DONE!)
• fix multiple inheritance (DONE!)
• rename src/ to include/ and follow C++ package standards (DONE!)
• no 'using namespace std' (DONE!)
• change to more compact and consistent formatting style (using cpplint tool) - DONE!

Project Structure

Project is organized in three main folders: src, libs, tests and bin.

• On src/OptFrame and tests/OptFrame are code and testing for OptFrame framework itself.
• On Examples you can find code and tests for the provided Examples.
• On MyProjects you can find code and tests for your own codes.
• On bin, you can find classic optframe-mct.sh script, that will generate a new project X on MyProjects/X/src folder (and tests on MyProjects/X/tests).
• On libs you can find third-party libraries (including testing and benchmarking, as they are used widely on examples and subprojects) Tests are provided via catch2, benchmaking via benchmark library, and also scannerpplib (Scanner++ library) for stream/file processing.

OptFrame Functional Core (FCore) is also provided (strict c++20):

• On src/OptFCore and Examples/FCore-Examples are code and testing for FCore framework itself.

C++ and Development Requirements

The following requirements apply for projects (and subprojects):

• OptFrame
  • c++17 - tested on gcc-7 (without flags -fconcepts)
  • c++20 - BEST OPTION!
• FCore - c++20 - tested on gcc-10.1 with flags -fcoroutines
• Scanner++ - c++11 - tested on gcc-7

To install gcc-10.1, see these Instructions.

To learn more about bazel build, versioning and general development requirements, see DEVEL.md.

IMPORTANT: Run make check for full check (need Bazel Build).

Concepts General

To learn a little bit of Optimization Concepts and C++ Concepts behind this project, see OPTCONCEPTS.md

Examples

Please take a deep look at Examples folder, and build them by simply typing make there. Each example is connected to some previous literature work, and can demonstrate how each metaheuristic work on practice. We know some detailed tutorial is still missing, but we hope to provide more info as soon as possible. Feel free to open issues and new discussions on GitHub ;)

Using Bazel

Each example is itself an independent workspace. For this reason, each example has a reference to @OptFrame (as local_repository), while optframe root itself has a self reference for @OptFrame (as local_repository).

This allows building all examples from root, with bazel build ... or bazel build //Examples/... One can also jump into each independent example and build it locally.

See available examples on bazel: bazel query //Examples/...

Here are some examples and build advices for bazel.

FCore-Examples

From root:

• bazel build @FCore-Examples//...
• bazel run @FCore-Examples//src:app_TSPfcore

Binary will be located at ./bazel-bin/external/FCore-Examples/src/app_TSPfcore

From example (cd Examples/FCore-Examples/):

• bazel clean
• bazel build ...
• bazel run //src:app_TSPfcore

Binary will be located at ./Examples/FCore-Examples/bazel-bin/src/app_TSPfcore

EternityII Example

From root:

• bazel build @EternityII//...
• cd ./bazel-bin/external/EternityII/app_Example.runfiles/EternityII/
• ./app_Example

Binary and data will be located at ./bazel-bin/external/EternityII/app_Example.runfiles/EternityII/

From example (cd Examples/EternityII/):

• bazel clean
• bazel build ...
• bazel run //:app_Example

Binary and data will be located at ./Examples/EternityII/bazel-bin/app_Example.runfiles/__main__/

Submodules

Getting submodules: git submodule update --init --recursive and git pull --recurse-submodules.

Using MCT script - Make a Compilable Thing!

Just type cd ./bin && ./mct.sh (or make mct) and follow the instructions on screen. You can find your new project on src/MyProjects/ (and tests on tests/MyProjects/).

A brief history of OptFrame

For a brief history of OptFrame v1, v2, v3, v4 and v5 (current), see HISTORY.md.

Examples

Interesting examples are available (see Examples folder):

• EternityII: Eternity II Puzzle -
• HFM: HFM forecast framework by @vncoelho -
• HFMVRP: Heterogeneous Fleet Vehicle Routing Problem -
• KP: Knapsack Problem (v1) -
• KP2: Knapsack Problem (v2)
• MITSP: Multi Improvement Dynamic Programming