{"id":13699398,"url":"https://github.com/ac-tuwien/pymhlib","last_synced_at":"2025-12-14T05:04:23.247Z","repository":{"id":62581718,"uuid":"169210689","full_name":"ac-tuwien/pymhlib","owner":"ac-tuwien","description":"pymhlib - A Toolbox for Metaheuristics and Hybrid Optimization Methods","archived":false,"fork":false,"pushed_at":"2023-06-06T07:34:52.000Z","size":776,"stargazers_count":26,"open_issues_count":0,"forks_count":11,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-10-13T11:57:45.951Z","etag":null,"topics":["discrete-optimization","metaheuristic-framework","metaheuristics","optimization-algorithm-library","python"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ac-tuwien.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-02-05T08:34:53.000Z","updated_at":"2024-10-01T08:57:40.000Z","dependencies_parsed_at":"2024-01-12T19:50:07.370Z","dependency_job_id":"8a2480bf-9334-4b73-b58b-2d8077d14637","html_url":"https://github.com/ac-tuwien/pymhlib","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ac-tuwien%2Fpymhlib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ac-tuwien%2Fpymhlib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ac-tuwien%2Fpymhlib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ac-tuwien%2Fpymhlib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ac-tuwien","download_url":"https://codeload.github.com/ac-tuwien/pymhlib/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224398824,"owners_count":17304661,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["discrete-optimization","metaheuristic-framework","metaheuristics","optimization-algorithm-library","python"],"created_at":"2024-08-02T20:00:32.226Z","updated_at":"2025-12-14T05:04:18.161Z","avatar_url":"https://github.com/ac-tuwien.png","language":"Jupyter Notebook","funding_links":[],"categories":["\u003cspan id=\"head24\"\u003e3.2. Optimization\u003c/span\u003e"],"sub_categories":["\u003cspan id=\"head25\"\u003e3.2.1. Metaheuristic\u003c/span\u003e"],"readme":"## `pymhlib` - A Toolbox for Metaheuristics and Hybrid Optimization Methods\n\n[![BuildStatus](https://github.com/ac-tuwien/pymhlib/actions/workflows/CI.yml/badge.svg?branch=master)](https://github.com/ac-tuwien/pymhlib?branch=master)\n[![codecov.io](http://codecov.io/github/ac-tuwien/pymhlib/coverage.svg?branch=master)](http://codecov.io/github/ac-tuwien/pymhlib?branch=master)\n\n_This project is still in early development, any feedback is much appreciated!_\n\n`pymhlib` is a collection of modules supporting the efficient implementation of metaheuristics \nand certain hybrid optimization approaches for solving primarily combinatorial optimization \nproblems in Python 3.7+.\n\n![ ](mh.png)\n\nThis Python `mhlib` version emerged from the \n[C++ `mhlib`](https://bitbucket.org/ads-tuwien/mhlib) to which it has certain similarities \nbut also many differences.\n\nNote that there also exists a more recent efficient **Julia-implementation** of this libraries, \nfollowing a similar design concept: [Julia MHLib.jl](https://github.com/ac-tuwien/MHLib.jl)\n\nThe main purpose of the library is to support rapid prototyping and teaching. \nWhile ultimately efficient implementations of such algorithms in compiled \nlanguages like Julia or C++ will in general be much faster, an advantage of \nthe Python implementation lies in the possibly quicker development cycle.\n\n\n`pymhlib` is developed primarily by the \n[Algorithms and Complexity Group of TU Wien](https://www.ac.tuwien.ac.at), \nVienna, Austria, since 2019.\n\n#### Contributors:\n- [Günther Raidl](https://www.ac.tuwien.ac.at/raidl) (primarily responsible)\n- [Nikolaus Frohner](https://www.ac.tuwien.ac.at/nfrohner)\n- Thomas Jatschka\n- Daniel Obszelka\n- Andreas Windbichler\n\n### Installation\n\nMajor versions of `pymhlib` can be installed from `PyPI` via\n\n    python3 -m pip install -U pymhlib\n    \nand development versions are available at https://github.com/ac-tuwien/pymhlib.\n\n### Major Components\n\n- **solution.py**:\n    An abstract base class `Solution`that represents a candidate solution to an optimization problem and\n    derived classes `VectorSolution`, `BinaryVectorSolution`, and `SetSolution` for solutions which are\n    represented bei general fixed-length vectors, boolean vectors or sets of arbitrary elements.\n- **binvec_solution.py**:\n    A more specific solution class `BinaryVectorSolution` for problems in which solutions are represented by\n    fixed-length binary vectors.\n- **subsetvec_solution.py**:\n    A more specific solution class `SubsetVectorSolution` for problems in which solutions are subsets of a \n    larger set. The set is realized by an efficient numpy array which is split into two parts, \n    the one with the included elements in sorted order and the one with the remaining elements.\n- **permutation_solution.py**:\n    A more specific solution class `PermutationSolution` for problems in which solutions are permutations of a\n    set of elements.\n- **scheduler.py**:\n    A an abstract framework for single metaheuristics that rely on iteratively applying certain \n    methods to a current solution. Modules like gvns.py and alns.py extend this abstract class towards\n    more specific metaheuristics.\n- **gvns.py**:\n    A framework for local search, iterated local search, (general) variable neighborhood \n    search, GRASP, etc.\n- **alns.py**:\n    A framework for adaptive large neighborhood search (ALNS).\n- **par_alns.py**:\n    A multi-process implementation of the ALNS where destroy+repair operations are parallelized.\n- **population.py**\n    A population class for population-based metaheuristics.\n- **pbig.py**:\n    A population based iterated greedy (PBIG) algorithm.\n- **ssga.py**:\n    A steady-state genetic algorithm (SSGA).\n- **sa.py**:\n    A simulated annealing (SA) algorithm with geometric cooling.\n- **decision_diag.py**:\n    A generic class for (relaxed) decision diagrams for combinatorial optimization.\n- **log.py**:\n    Provides two logger objects, one for writing out general log information, which is typically\n    written into a `*.out`  file, and one for iteration-wise information, which is typically\n    written into a `*.log` file. The latter is buffered in order to work also efficiently, e.g., \n    on network drives and massive detailed log information. \n    A class `LogLevel` is provided for indented writing of log information according to a current level, \n    which might be used for hierarchically embedded components of a larger optimization framework,\n    such as a local search that is embedded in a population-based approach.   \n- **settings.py**:\n    Allows for defining module-specific parameters directly in each module in an independent  distributed\n    way, while values for these parameters can be provided as program arguments or in\n    configuration files. Most `pymhlib` modules rely on this mechanism for their external parameters.\n\nModules/scripts for analyzing results of many runs:\n\n- **multi_run_summary.py**:\n    Collects essential information from multiple `pymhlib` algorithm runs found in the respective out and log files\n    and returns a corresponding pandas `DataFrame` if used as a module or as a plain ASCII table when used as\n    independent script. The module can be easily configured to extract also arbitrary application-specific data.\n    \n- **aggregate_results.py**:\n    Calculate grouped basic statistics for one or two dataframes/TSV files obtained e.g. from `multi-run-summary.py`.\n    In particular, two test series with different algorithms or different settings can be statistically\n    compared, including Wilcoxon signed rank tests. The module can be used as standalone script as well \n    as module called, e.g., from a jupyter notebook.\n\n\n#### Demos\n\nFor demonstration purposes, simple metaheuristic approaches are provided in the `demo` subdirectory for the following\nwell-known combinatorial optimization problems. They can be started by\n\n    python3 -m pymhlib.demos.\u003cproblem\u003e ...\n\nwhere `\u003cproblem\u003e` is one of the following and `...` represents further parameters that can be seen by providing \nthe option `-h`.\nIt is recommended to take such a demo as template \nfor solving your own problem.\n\n- **`maxsat`**: maximum satisfiability problem based on `BinaryVectorSolution`\n- **`tsp`**: traveling salesperson problem based on `PermutationSolution`\n- **`qap`**: quadratic assignment problem based on `PermutationSolution`\n- **`vertex_cover`**: minimum vertex cover problem based on `SetSolution`\n- **`graph_coloring`**: graph coloring problem based on `VectorSolution`\n- **`misp`**: maximum (weighted) independent set problem based on `SubsetVectorSolution`\n- **`mkp`**: multidimensional 0-1 knapsack problem based on `SubsetVectorSolution`\n\nShared code of these demos is found in the submodules `pymhlib.demos.common` and `pymhlib.demos.graphs`,\ntest instance data in `pymhlib.demos.data`.\n\nMoreover, `julia-maxsat.py` and `julia-maxsat.jl` demonstrate the integration with the Julia programming language.\nImplementing time-critical parts of an application in Julia may accelerate the code substantially.\nTo run this demo, Julia must be set up correctly and Python's `julia` package must be installed.\nWhile this demo derives a whole solution class in Julia, `julia-maxsat2.py` is a variant where only two functions \nare realized in Julia.\n \n\n### Changelog\n\nMajor changes in releases:\n\n#### Version 0.1.5\n- bug fix in `settings: repeated `parse_settings` now resets former settings correctly\n- bug fix in `common.py/run_optimization`: seed now correctly passed to `add_general_arguments_and_parse_settings`\n- automatic installation of required other packages fixed \n\n#### Version 0.1.4\n- cleaning according to pylint warnings\n- settings.parse_args may now be called multiple times\n\n#### Version 0.1.3\n- bug fix in 2-opt neighborhood search of permutation representation\n\n#### Version 0.1.2\n- directory renamed to pymhlib to correspond to module name\n- bug fix in Metropolis criterion of ALNS\n- boolean arguments must now be specified in the command line as any other parameter\n\n#### Version 0.1.1\n- basic functionality test `tests/test_all.py` for all problems and\n  algorithms added\n- polishing, minor fixes\n\n#### Version 0.1.0 \n- ALNS and parallel ALNS added\n- graph coloring, TSP, and minimum vertex cover demos added\n- population based iterated greedy and steady state genetic algorithms added\n- SA with geometric cooling added\n- demos.graphs introduced\n- mhlib renamed to pymhlib\n- demo for interfacing with Julia added\n- many smaller improvements, bug fixes, improvements in documentation \n\n#### Version 0.0.1 \n- Initial version\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fac-tuwien%2Fpymhlib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fac-tuwien%2Fpymhlib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fac-tuwien%2Fpymhlib/lists"}