.. image:: https://github.com/AlkiviadisAleiferis/hyperpack/blob/main/docs/source/_static/hyperpack_logo.png?raw=true
:align: center
:width: 40%
:alt: hyperpack
-----------------------------
.. image:: https://img.shields.io/badge/License-Apache_2.0-blue.svg
.. image:: https://img.shields.io/badge/python-3.7|3.8|3.9|3.10|3.11-blue.svg
.. image:: https://img.shields.io/badge/maintainer-alkiviadis.aliferis@gmail.com-blue.svg
.. image:: https://img.shields.io/badge/pypi-v1.2.0-blue.svg
Problem description
-------------------
The hyperpack library is an API for solving instances of the `2D Binpacking problem`_ and
also - as of v1.1.0 - strip packing instances!
The library is **multiprocessing enabled** to minimize execution times and `utilizes only pure python`, making
the package dependency free.
.. _`2D Binpacking problem`: https://citeseerx.ist.psu.edu/document?repid=rep1&type=pdf&doi=2cb8247534c9e889ac42b2362f0ad96c8c6b8c77
Many different variations can be created and solved, accordind to the instantiation data.
The solvable variants can be summarized in the below characteristics:
- Any number and sizes of (rectangular) items.
- Any number and sizes of (rectangular) bins (containers).
- The items can be rotated or not.
The above items' charascteristics can also be applied to strip packing problems.
The bin/strip packing problem has been used in many sectors of the industry, and mostly where manufacturing or
industrial management needs arise.
The theory of this library's implementation and mechanics can be found in author's
document `"A hyper-heuristic for solving variants of the 2D bin packing problem"`_.
.. _`"A hyper-heuristic for solving variants of the 2D bin packing problem"`: https://github.com/AlkiviadisAleiferis/hyperpack-theory
Installation
-------------
Install using pip:
``pip install hyperpack``
Quickstart
------------
A quickstart for testing the library can be made through the ``generate_problem_data``
utility function.
.. code-block:: python
>>> from hyperpack import generate_problem_data, HyperPack
>>> problem_data = hyperpack.generate_problem_data(containers_num=2)
Containers number = 2
Containers:
{
"container-0": {
"W": 48,
"L": 53
},
"container-1": {
"W": 53,
"L": 49
}
}
Items number = 60
>>> problem = HyperPack(**problem_data)
>>> problem.hypersearch()
>>> problem.create_figure(show=True)
>>> # figure opened in default browser
>>>
>>> # to see parameter explanation do:
>>> help(generate_problem_data)
Defining the problem
---------------------
Instantiate your problem with proper arguments
.. code-block:: python
>>> from hyperpack import HyperPack
>>> problem = hyperpack.HyperPack(
>>> containers=containers, # problem parameter
>>> items=items, # problem parameter
>>> settings=settings # solver/figure parameters
>>> )
According to the arguments given, the corresponding problem will be instantiated, ready to be solved
with provided guidelines. The items and containers (bins) structure:
.. code-block:: python
containers = {
"container-0-id": {
"W": int, # > 0 container's width
"L": int # > 0 container's length
},
"container-1-id": {
"W": int, # > 0 container's width
"L": int # > 0 container's length
},
# ... rest of the containers
# minimum 1 container must be provided
}
items = {
"item-0-id": {
"w": int, # > 0 item's width
"l": int, # > 0 item's length
},
"item-1-id": {
"w": int, # > 0 item's width
"l": int, # > 0 item's length
},
# ... rest of the items
# minimum 1 item must be provided
}
See documentation for detailed settings structure.
Usage
-----
Do Local search with default settings:
.. code-block:: python
>>> from hyperpack import HyperPack
>>> problem_data = {
>>> "containers": containers,
>>> "items": items,
>>> "settings": settings
>>> }
>>> problem = HyperPack(**problem_data)
>>> problem.local_search()
After solving has finished, the solution can be found in ``problem.solution`` instance attribute.
Alternatively for a deep search and maximum bin utilization in mind:
.. code-block:: python
>>> problem = HyperPack(**problem_data)
>>> problem.hypersearch()
Solution logging
-----------------
Use the ``log_solution`` method to log an already found solution:
.. code-block:: python
>>> problem.log_solution()
Solution Log:
Percent total items stored : 100.0000%
Container: container-0-id 60x30
[util%] : 100.0000%
Container: container-1-id 60x50
[util%] : 91.2000%
Remaining items : []
Create a figure
-----------------
**Warning** : plotly (5.14.0 or greater) is needed for figure creation and kaleido (0.2.1 or greater)
for figure exportation to image. These libraries are not listed as dependencies providing liberty
of figure implementation.
.. code-block:: python
>>> problem.create_figure(show=True)
The figure below is opened in default browser:
.. image:: https://github.com/AlkiviadisAleiferis/hyperpack/blob/main/docs/source/_static/README_figure.png?raw=true
:align: center
:width: 100%
:alt: example_figure
For more information, visit the documentation page.
Future development
-------------------
Many ideas and concepts can be implemented in this library. The most propable depending on
the community's interest:
- Augmentation of the objective function to deal with a bigger plethora of problems.
- Implementation of the strip packing problem.
- Django integrations.
- Large Neighborhood Search for big instances of the problem.
- Other shapes of the container.
- A dynamic live terminal display.
- Execution speed optimization.
- Multiprocessing for the local search alone (combined with Large Neighborhood Search).
- More detailed figures.
- Figures with other libraries (matplotlib).
If interested with development with some of these features please contact me.
Theoretical foundations
-----------------------
This packages inner mechanics and theoretical design are based upon this `documentation`_.
.. _`documentation`: https://github.com/AlkiviadisAleiferis/hyperpack-theory
Helping
--------
Creating issues wherever bugs are found and giving suggestions for upcoming versions
can surely help in maintaining and growing this package.
Raw data
{
"_id": null,
"home_page": "https://github.com/AlkiviadisAleiferis/hyperpack",
"name": "hyperpack",
"maintainer": "Alkiviadis Aleiferis",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "alkiviadis.aliferis@gmail.com",
"keywords": "2d-binpacking,2DBPP,heuristics,meta-heuristics,local-search,hyper-heuristics,bin-packing,research,AI,algorithms,operations-research",
"author": "Alkiviadis Aleiferis",
"author_email": "alkiviadis.aliferis@gmail.com",
"download_url": "",
"platform": null,
"description": ".. image:: https://github.com/AlkiviadisAleiferis/hyperpack/blob/main/docs/source/_static/hyperpack_logo.png?raw=true\n :align: center\n :width: 40%\n :alt: hyperpack\n\n-----------------------------\n\n.. image:: https://img.shields.io/badge/License-Apache_2.0-blue.svg\n\n.. image:: https://img.shields.io/badge/python-3.7|3.8|3.9|3.10|3.11-blue.svg\n\n.. image:: https://img.shields.io/badge/maintainer-alkiviadis.aliferis@gmail.com-blue.svg\n\n.. image:: https://img.shields.io/badge/pypi-v1.2.0-blue.svg\n\nProblem description\n-------------------\n\nThe hyperpack library is an API for solving instances of the `2D Binpacking problem`_ and\nalso - as of v1.1.0 - strip packing instances!\n\nThe library is **multiprocessing enabled** to minimize execution times and `utilizes only pure python`, making\nthe package dependency free.\n\n.. _`2D Binpacking problem`: https://citeseerx.ist.psu.edu/document?repid=rep1&type=pdf&doi=2cb8247534c9e889ac42b2362f0ad96c8c6b8c77\n\nMany different variations can be created and solved, accordind to the instantiation data.\nThe solvable variants can be summarized in the below characteristics:\n- Any number and sizes of (rectangular) items.\n- Any number and sizes of (rectangular) bins (containers).\n- The items can be rotated or not.\n\nThe above items' charascteristics can also be applied to strip packing problems.\n\nThe bin/strip packing problem has been used in many sectors of the industry, and mostly where manufacturing or\nindustrial management needs arise.\n\nThe theory of this library's implementation and mechanics can be found in author's\ndocument `\"A hyper-heuristic for solving variants of the 2D bin packing problem\"`_.\n\n.. _`\"A hyper-heuristic for solving variants of the 2D bin packing problem\"`: https://github.com/AlkiviadisAleiferis/hyperpack-theory\n\nInstallation\n-------------\n\nInstall using pip:\n\n ``pip install hyperpack``\n\nQuickstart\n------------\n\nA quickstart for testing the library can be made through the ``generate_problem_data``\nutility function.\n\n.. code-block:: python\n\n >>> from hyperpack import generate_problem_data, HyperPack\n >>> problem_data = hyperpack.generate_problem_data(containers_num=2)\n Containers number = 2\n Containers:\n {\n \"container-0\": {\n \"W\": 48,\n \"L\": 53\n },\n \"container-1\": {\n \"W\": 53,\n \"L\": 49\n }\n }\n Items number = 60\n >>> problem = HyperPack(**problem_data)\n >>> problem.hypersearch()\n >>> problem.create_figure(show=True)\n >>> # figure opened in default browser\n >>>\n >>> # to see parameter explanation do:\n >>> help(generate_problem_data)\n\n\nDefining the problem\n---------------------\n\nInstantiate your problem with proper arguments\n\n.. code-block:: python\n\n >>> from hyperpack import HyperPack\n >>> problem = hyperpack.HyperPack(\n >>> containers=containers, # problem parameter\n >>> items=items, # problem parameter\n >>> settings=settings # solver/figure parameters\n >>> )\n\nAccording to the arguments given, the corresponding problem will be instantiated, ready to be solved\nwith provided guidelines. The items and containers (bins) structure:\n\n.. code-block:: python\n\n containers = {\n \"container-0-id\": {\n \"W\": int, # > 0 container's width\n \"L\": int # > 0 container's length\n },\n \"container-1-id\": {\n \"W\": int, # > 0 container's width\n \"L\": int # > 0 container's length\n },\n # ... rest of the containers\n # minimum 1 container must be provided\n }\n\n items = {\n \"item-0-id\": {\n \"w\": int, # > 0 item's width\n \"l\": int, # > 0 item's length\n },\n \"item-1-id\": {\n \"w\": int, # > 0 item's width\n \"l\": int, # > 0 item's length\n },\n # ... rest of the items\n # minimum 1 item must be provided\n }\n\nSee documentation for detailed settings structure.\n\nUsage\n-----\n\nDo Local search with default settings:\n\n.. code-block:: python\n\n >>> from hyperpack import HyperPack\n >>> problem_data = {\n >>> \"containers\": containers,\n >>> \"items\": items,\n >>> \"settings\": settings\n >>> }\n >>> problem = HyperPack(**problem_data)\n >>> problem.local_search()\n\nAfter solving has finished, the solution can be found in ``problem.solution`` instance attribute.\n\nAlternatively for a deep search and maximum bin utilization in mind:\n\n.. code-block:: python\n\n >>> problem = HyperPack(**problem_data)\n >>> problem.hypersearch()\n\nSolution logging\n-----------------\n\nUse the ``log_solution`` method to log an already found solution:\n\n.. code-block:: python\n\n >>> problem.log_solution()\n Solution Log:\n Percent total items stored : 100.0000%\n Container: container-0-id 60x30\n [util%] : 100.0000%\n Container: container-1-id 60x50\n [util%] : 91.2000%\n\n Remaining items : []\n\nCreate a figure\n-----------------\n\n**Warning** : plotly (5.14.0 or greater) is needed for figure creation and kaleido (0.2.1 or greater)\nfor figure exportation to image. These libraries are not listed as dependencies providing liberty\nof figure implementation.\n\n.. code-block:: python\n\n >>> problem.create_figure(show=True)\n\nThe figure below is opened in default browser:\n\n.. image:: https://github.com/AlkiviadisAleiferis/hyperpack/blob/main/docs/source/_static/README_figure.png?raw=true\n :align: center\n :width: 100%\n :alt: example_figure\n\nFor more information, visit the documentation page.\n\nFuture development\n-------------------\n\nMany ideas and concepts can be implemented in this library. The most propable depending on\nthe community's interest:\n\n - Augmentation of the objective function to deal with a bigger plethora of problems.\n - Implementation of the strip packing problem.\n - Django integrations.\n - Large Neighborhood Search for big instances of the problem.\n - Other shapes of the container.\n - A dynamic live terminal display.\n - Execution speed optimization.\n - Multiprocessing for the local search alone (combined with Large Neighborhood Search).\n - More detailed figures.\n - Figures with other libraries (matplotlib).\n\nIf interested with development with some of these features please contact me.\n\nTheoretical foundations\n-----------------------\n\nThis packages inner mechanics and theoretical design are based upon this `documentation`_.\n\n.. _`documentation`: https://github.com/AlkiviadisAleiferis/hyperpack-theory\n\nHelping\n--------\n\nCreating issues wherever bugs are found and giving suggestions for upcoming versions\ncan surely help in maintaining and growing this package.\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "A hyper-heuristic approach on solving the 2D bin packing problem",
"version": "1.2.0",
"project_urls": {
"Documentation": "https://alkiviadisaleiferis.readthedocs.io/en/latest/",
"Homepage": "https://github.com/AlkiviadisAleiferis/hyperpack",
"Repository": "https://github.com/AlkiviadisAleiferis/hyperpack"
},
"split_keywords": [
"2d-binpacking",
"2dbpp",
"heuristics",
"meta-heuristics",
"local-search",
"hyper-heuristics",
"bin-packing",
"research",
"ai",
"algorithms",
"operations-research"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "70329e3597c99c6e4bd3107d436e6b55b589ab2105574d0b14eb2099c1eefcf5",
"md5": "ff385a4b3c91a74b2c9502be698b5d88",
"sha256": "2be8be4406ddba69acc3515a07d57a9764d94792e04a7fd8de34eb93f322a61b"
},
"downloads": -1,
"filename": "hyperpack-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ff385a4b3c91a74b2c9502be698b5d88",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 46977,
"upload_time": "2023-12-26T11:53:34",
"upload_time_iso_8601": "2023-12-26T11:53:34.370262Z",
"url": "https://files.pythonhosted.org/packages/70/32/9e3597c99c6e4bd3107d436e6b55b589ab2105574d0b14eb2099c1eefcf5/hyperpack-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-26 11:53:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AlkiviadisAleiferis",
"github_project": "hyperpack",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "hyperpack"
}
JSON
