optframe


Nameoptframe JSON
Version 5.0.28rc0 PyPI version JSON
download
home_page
SummaryPython bindings for OptFrame Functional Core
upload_time2023-12-07 20:37:25
maintainer
docs_urlNone
author
requires_python>=3.9
licenseCopyright (c) 2023 OptFrame Developers Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
keywords optframe optimization metaheuristics
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # pyoptframe-dev

[![Documentation Status](https://readthedocs.org/projects/optframe/badge/?version=latest)](https://pyoptframe.readthedocs.io/en/latest/?badge=latest)

Development repo for draft versions of Python bindings for OptFrame Functional Core C++.


Install: `python -m pip install optframe`

Version: `pyoptframe v5.0.28rc0`

Play on Jupyter Notebook: [BRKGA Traveling Salesman Problem Example](demo/OptFrame_BRKGA_Official.ipynb)

Documentation and Tutorials: see [PyOptFrame Quickstart](https://pyoptframe.readthedocs.io/en/latest/quickstart.html)

Beware that, after officially launched, this project may be migrated into [Official Optframe C++](https://github.com/optframe/optframe) repo (and same strategy applies to other future external language bindings).

### About OptFrame C++

[OptFrame](https://github.com/optframe/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.

## For Developers

If you want to help, please see instructions on [Development.md](./Development.md).


### Advice for online environments

OptFrame now supports both `c++17` and `c++20`.

Before installing optframe online (such as google colab), 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

### Demos

Documentation and Tutorials: see [PyOptFrame Quickstart](https://pyoptframe.readthedocs.io/en/latest/quickstart.html)

Please see the demos on demo/ folder.

We also include some jupyter notebooks for playing.


### Example with 0-1 Knapsack Problem (tests)

Also see file `tests/test_engine_kp.py` for an example with 0-1 Knapsack Problem,
used on internal tests.

### More tutorials

Please read the official tutorials for OptFrame C++, 
as they may give ideas for python too: https://optframe.readthedocs.io/

Also see the Examples and demo folders on C++ project: [github.com/optframe/optframe](https://github.com/optframe/optframe).


## Technical discussions and Roadmap
### 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.

## 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:

- [LICENSE-MIT](./LICENSE-MIT.txt)
- [LICENSE-LGPLv3+](./LICENSE-LGPL-3.0-or-later.txt)

Copyleft 2023

Igor Machado Coelho


            

Raw data

            {
    "_id": null,
    "home_page": "",
    "name": "optframe",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.9",
    "maintainer_email": "",
    "keywords": "optframe,optimization,metaheuristics",
    "author": "",
    "author_email": "Igor Machado Coelho <igormcoelho@proton.me>",
    "download_url": "https://files.pythonhosted.org/packages/1f/3b/5c5fc22fc40b450dc22df2e8018445eef89351831c02d2b609eba8e84859/optframe-5.0.28rc0.tar.gz",
    "platform": null,
    "description": "# pyoptframe-dev\n\n[![Documentation Status](https://readthedocs.org/projects/optframe/badge/?version=latest)](https://pyoptframe.readthedocs.io/en/latest/?badge=latest)\n\nDevelopment repo for draft versions of Python bindings for OptFrame Functional Core C++.\n\n\nInstall: `python -m pip install optframe`\n\nVersion: `pyoptframe v5.0.28rc0`\n\nPlay on Jupyter Notebook: [BRKGA Traveling Salesman Problem Example](demo/OptFrame_BRKGA_Official.ipynb)\n\nDocumentation and Tutorials: see [PyOptFrame Quickstart](https://pyoptframe.readthedocs.io/en/latest/quickstart.html)\n\nBeware that, after officially launched, this project may be migrated into [Official Optframe C++](https://github.com/optframe/optframe) repo (and same strategy applies to other future external language bindings).\n\n### About OptFrame C++\n\n[OptFrame](https://github.com/optframe/optframe) is a C++ framework for optimization problems, including techniques such as classic metaheuristics Simulated Annealing, Genetic Algorithm, \nVariable Neighborhood Search, Iterated Local Search, Tabu Search, Particle Swarm Optimization, NSGA-II, and other single and multi-objective methods.\nThis is a 10+ year project with several practical applications in industry and academia, so feel free to use it.\n\n## For Developers\n\nIf you want to help, please see instructions on [Development.md](./Development.md).\n\n\n### Advice for online environments\n\nOptFrame now supports both `c++17` and `c++20`.\n\nBefore installing optframe online (such as google colab), check C++ compiler (typically GCC) version:\n\n`x86_64-linux-gnu-gcc -v`\n\nAt least gcc-10 is required for C++20... if not enough, try to install g++-10 and make it default.\n*Considering Jupyter notebook syntax*:\n```\n!apt install -y g++-10\n!g++-10 --version\n!update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-10 10\n!update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-10 10\n!update-alternatives --install /usr/bin/x86_64-linux-gnu-gcc gcc /usr/bin/gcc-10 10\n```\n\n## Tutorials\n\n### Demos\n\nDocumentation and Tutorials: see [PyOptFrame Quickstart](https://pyoptframe.readthedocs.io/en/latest/quickstart.html)\n\nPlease see the demos on demo/ folder.\n\nWe also include some jupyter notebooks for playing.\n\n\n### Example with 0-1 Knapsack Problem (tests)\n\nAlso see file `tests/test_engine_kp.py` for an example with 0-1 Knapsack Problem,\nused on internal tests.\n\n### More tutorials\n\nPlease read the official tutorials for OptFrame C++, \nas they may give ideas for python too: https://optframe.readthedocs.io/\n\nAlso see the Examples and demo folders on C++ project: [github.com/optframe/optframe](https://github.com/optframe/optframe).\n\n\n## Technical discussions and Roadmap\n### C++ Standard and Compiler Support\n\nWe love Concepts and Optionals, so we require `C++20` as default. \nHowever, it is possible to adapt `setup.py` in order to allow for `C++17` with `-fconcepts` on GCC. \nIf necessary (only C++17 is available), add this line on `setup.py`:\n\n```\nextra_compile_args=['--std=c++17', '-fconcepts']\n```\n\nFor the moment, GCC and CLANG are officially supported, but more compilers can be added to the list, if demand exists.\n\n\n### `optframe_lib` API Organization\n\nThe API on `optframe_lib` is organized in distict **API levels**.\n\nEvery function on `optframe_lib` API starts with the prefix `optframe_apiXy`, where\n`X` represents the level and `y` represents the main evaluation type considered.\nFor now, we support `X=1` and `y=d`, meaning that API is meant for `float64` (or `double`) evaluation\nspaces (but we certainly plan to add support for `i32`, `i64` and other types).\n\nRegarding the API level strategy:\n\n- level 0: only for raw (an unsecure) access to internal OptFrame functions\n   * only use this for testing new features or making extremely efficient and direct function calls to OptFrame internals\n- level 1 (STANDARD): this level must provide basic access to fundamental search techniques\nand to all basic examples\n- level 2 (ADVANCED): this level WILL (in the future) also include re-evaluation strategies and other more advanced features of OptFrame C++\n- level 3+ (???): maybe we can use this to split advanced functionalities from API2, but only future can tell\n\nIn the future, we can also use greater API number to implement possible compatibility breaking features... only future will tell.\n\n### Versioning Strategy\n\nVersioning should follow OptFrame C++ project on MAJOR and MINOR, leaving PATCH field to be different, if necessary. Examples: \n\n- v 5 dot 1 dot 3 should include OptFrame C++ 5 dot 1.\n- 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.\n\n## Known Issues\n\nAll known issues fixed :)\n\n## Thanks\n\nThanks 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).\n\nAlso thanks for the encouragement and fruitful discussions with my students, specially, Rafael Albuquerque, Marcos Souza, Victor Silva and Fellipe Pessanha.\n\n## License\n\nAt your choice:\n\n- [LICENSE-MIT](./LICENSE-MIT.txt)\n- [LICENSE-LGPLv3+](./LICENSE-LGPL-3.0-or-later.txt)\n\nCopyleft 2023\n\nIgor Machado Coelho\n\n",
    "bugtrack_url": null,
    "license": "Copyright (c) 2023 OptFrame Developers  Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:  The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.  THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
    "summary": "Python bindings for OptFrame Functional Core",
    "version": "5.0.28rc0",
    "project_urls": {
        "Homepage": "https://github.com/optframe/pyoptframe-dev"
    },
    "split_keywords": [
        "optframe",
        "optimization",
        "metaheuristics"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "1f3b5c5fc22fc40b450dc22df2e8018445eef89351831c02d2b609eba8e84859",
                "md5": "d7eb8105a3f67efca3c88bc6e7c8f270",
                "sha256": "fff4fb8ea6c9489abbfdf5b622b65b8ea4acf18b4cb2ae0cbece8b37cb69068f"
            },
            "downloads": -1,
            "filename": "optframe-5.0.28rc0.tar.gz",
            "has_sig": false,
            "md5_digest": "d7eb8105a3f67efca3c88bc6e7c8f270",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.9",
            "size": 40042,
            "upload_time": "2023-12-07T20:37:25",
            "upload_time_iso_8601": "2023-12-07T20:37:25.612403Z",
            "url": "https://files.pythonhosted.org/packages/1f/3b/5c5fc22fc40b450dc22df2e8018445eef89351831c02d2b609eba8e84859/optframe-5.0.28rc0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2023-12-07 20:37:25",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "optframe",
    "github_project": "pyoptframe-dev",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "optframe"
}
        
Elapsed time: 0.18952s