API Reference

HyperPack

class heuristics.HyperPack(containers=None, items=None, settings=None, *, strip_pack_width=None)

Bases: SolutionFigureMixin, PointGenerationSolver, LocalSearchMixin, ItemsManipulationMixin, SolutionLoggingMixin

This class extends BasePointGenSolver, utilizing its solving functionalities by implementing a hypersearch hyper-heuristic using the LocalSearchMixin.

Enables total problem solution and depiction.

get_strategies(*, _exhaustive: bool = True) → tuple: Returns the total potential points strategies to be treversed in hypersearch.

hypersearch(orientation: str = 'wide', sorting_by: tuple = ('area', True), *, throttle: bool = True, _exhaustive: bool = True, _force_raise_error_index=None) → None

Method for solving using using a non-learning, construction heuristic generation hyper-heuristic, utilizing hill climbing local search per generation.

OPERATION

Solves using local_search for different potential_points_strategy values.

Updates self.solution with the best solution found.
Updates self.obj_val_per_container with the best values.
Updates self.best_strategy with the best strategy found.

PARAMETERS

orientation affects the way items are ‘oriented’ before solving operations start. See here for detailed explanation of the method.

sorting_by directive for sorting the items attribute before solving operations start. See here for detailed explanation of the method.

throttle boolean (keyword only) passed to local search. Affects large instances of the problem.

_exhaustive boolean (keyword only) creates exhaustive search for every possible potential points strategy. If false, the search uses predefined strategies from hyperpack.constants.DEFAULT_POTENTIAL_POINTS_STRATEGY_POOL from hyperpack.constants.

_force_raise_error_index (keyword only) is used for testing purposes.

RETURNS

None

PointGenPack

class heuristics.PointGenPack(containers=None, items=None, settings=None, *, strip_pack_width=None): This class enables total problem solution and depiction.

BasePackingProblem

class heuristics.BasePackingProblem(containers=None, items=None, *, strip_pack_width=None)

Base class for initializing/managing the base packing problem instance.

_check_strip_pack(strip_pack_width) → None: This method checks strip_pack_width value and set’s initial values for:

_strip_pack: is the attribute modifying the problem. Used for logic branching in execution. Affects:

_construct: Forces the method to accept container_height as container’s height.

local_search: by lowering the container_height in every new node.

compare_solution: Makes comparison check if all items are in solution.

_containers._get_height: Branches method to return solution height or a minimum.

_container_height: is the actual container’s height used in _construct. Is also updated in every new node solution in local_search, where a lower height is proven feasible.

_container_min_height: is the minimum height that the container can get (not the solution height!).

containers: single container with preset height for strip packing mode.

reset_container_height()

Resets the imaginary (strip packing) container’s height.

If called from bin-packing instace, nothing happens.

PointGenerationSolver

class heuristics.PointGenerationSolver(containers=None, items=None, settings=None, *, strip_pack_width=None)

Class that implements the Point Generation problem solver.

Extends problem’s attributes to provide solving settings.

_validate_settings() → None

Method for validating and applying the settings either provided through: A. instantiation B. explicit assignment to self.settings C. calling self.validate_settings().

OPERATION

Validates settings instance attribute data structure and format.

Applies said settings to correlated private attributes.

PARAMETERS

None

RETURNS

None

solve(sequence=None, debug=False) → None: Solves the problem and updates the corresponding solution attributes.

PointGenerationMixin

class mixins.PointGenerationMixin

Mixin providing the point generation functionality.

Attributes required for solving operation:: _containers attribute of type Containers. _items attribute of type Items. _potential_points_strategy strategy attribute set pre-solving. _rotate attribute for rotation. _strip_pack attribute. _container_height attribute.

_construct_solution(cont_id, container, items, debug=False) → tuple

Point generation construction heuristic for solving single container problem instance.

INPUT

container, items, debug (mode),

implicitly by attribute, the potential points strategy

OUTPUT

returns current_solution with the solution of the container.
returns (remaining non-fitted items, containers utilization) tuple.

_get_container_solution(current_solution): Returns the solution object of the _construct method for the current solving container.

_solve(sequence=None, debug=False) → None

Solves for all the containers, using the point generation construction heuristic.

OPERATION

Populates solution with solution found for every container.

Populates obj_val_per_container with the utilization of every container.

PARAMETERS

sequence : the sequence of ids to create the items to solve for. If None, items will be used. Items used for solving are deepcopied from items with corresponding sequence.

debug : If True, debuging mode will be enabled, usefull only for developing.

RETURNS

solution , obj_val_per_container

NOTES

Solution is deterministic, and solely dependent on these factors:

potential_points_strategy attribute for the potential points strategy.

items_sequence sequence of the items ids.

SolutionFigureMixin

class mixins.SolutionFigureMixin

Mixin implementing the methods for building the figures of the solution.

Extends the settings validation to support the figure operation.

Must be used on leftmost position in the inheritance.

colorgen(index) → str: Method for returning a hexadecimal color for every item in the graph.

create_figure(show=False) → None

Method used for creating figures and showing/exporting them.

WARNING

plotly library at least 5.14.0 must be installed in environment, and for image exportation, at least kaleido 0.2.1.

See here for detailed explanation of the method.

OPERATION

Create’s the solution’s figure.

PARAMETERS

show: if True, the created figure will be displayed in browser after creation.

get_figure_dtick_value(dimension, scale=20): Method for determining the distance between ticks in x or y dimension.

DeepcopyMixin

class mixins.DeepcopyMixin: Mixin class providing copy/deepcopy utilities for certain attributes.

LocalSearchMixin

class mixins.LocalSearchMixin

Mixin implementing the Local Search.

calculate_obj_value()

Calculates the objective value using ‘obj_val_per_container’ attribute.

Returns a float (total utilization).

In case more than 1 bin is used, last bin’s utilization is reduced to push first bin’s maximum utilization.

compare_node(new_obj_value, best_obj_value)

Used in local_search. Compares new solution value to best for accepting new node. It’s the mechanism for propagating towards new accepted better solutions/nodes.

In bin-packing mode, a simple comparison using solution_operator is made.

In strip-packing mode, extra conditions will be tested:

If self._container_min_height is None:
The total of items must be in solution. If not, solution is rejected.

If self._container_min_height is not None:
Number of items in solution doesn’t affect solution choice.

local_search(*, throttle: bool = True, _hypersearch: bool = False, debug: bool = False) → None

Method for deploying a hill-climbing local search operation, using the default potential points strategy. Solves against the self.items and the self.containers attributes.

OPERATION

Updates self.solution with the best solution found.

Updates self.obj_val_per_container with the best values found.

PARAMETERS

throttle affects the total neighbors parsing before accepting that no better node can be found. Aims at containing the total execution time in big instances of the problem. Corresponds to ~ 72 items instance (max 2500 neighbors).

_hypersearch: Either standalone (False), or part of a superset search (used by hypersearch).

debug: for developing debugging.

RETURNS

None