Metadata-Version: 2.1
Name: lahc
Version: 1.0.5
Summary: Late Acceptance Hill Climbing in Python
Home-page: https://github.com/gunnstein/lahc
Author: Gunnstein T. Frøseth
Author-email: gunnstein@mailbox.org
License: ISC
Description: |lahc_logo|
        =============================
        Late Acceptance Hill Climbing
        =============================
        
        Implementation of Late Acceptance Hill Climbing (LAHC) algorithm by
        Burke and Bykov [Burke2017]_ in python.
        
        
        Installation
        ------------
        
        Either download the repository to your computer and install, e.g. by **pip**
        
        ::
        
           pip install .
        
        
        or install directly from the python package index.
        
        ::
        
           pip install lahc
        
        
        Usage
        -----
        
        The package provides a base class for subclassing to a specific
        problem. The ``move`` and ``energy`` methods must be implemented by the
        user before the algorithm is applied.
        
        The user controls the algorithm by adjusting a single algorithmic
        parameter, the ``history length``, and the termination criteria for
        the algorithm. See subsection on each of the topics below.
        
        The search is started by calling the ``run`` method.
        
        The example is a good place to start using of the package.
        
        Note
            The implementation relies heavily on copying the state. The
            default copy strategy (``copy_strategy='deepcopy'``) relies on the
            STL ``copy.deepcopy`` method which works for most data structures,
            but is typically quite slow. **Large** performance gains can be
            easily obtained by adapting a different copying strategy, see the
            documentation of the ``copy_state`` method.
        
        
        The history length
        ------------------
        
        The behaviour of the LAHC algorithm is governed by a single parameter,
        the history length. To alter the history length of the algorithm,
        adjust the ``history_length`` parameter of the class.
        
        If the history length is set to one, the LAHC algorithm is equivalent
        to a greedy Hill Climbing algorithm. Increasing the history length
        generally improves the solution quality, but also increases the time to
        convergence.
        
        Selection of the history length should therefore be based on
        requirements for the quality of the solution and time available for
        the analysis.
        
        A useful characteristic of the LAHC heuristic is that the runtime to
        convergence is roughly proportional to the history length. The runtime
        at any history length can therefore be estimated after applying the
        algorithm at a few different history lengths.
        
        As a general recommendation, start at a low history length and
        gradually increase it to determine the runtime and variation in the
        estimated results. Select a shorter history length that allows
        multiple runs in the time allocated for simulations rather than a
        longer history length with a single run.
        
        
        Termination criteria
        --------------------
        
        The algorithm terminates when the ``terminate_search`` method evaluates
        to `True` or when a interupt signal (``Ctrl-C``) is sent to the process.
        
        The default behaviour of the ``terminate_search`` method is to
        terminate the algorithm when a minimum number of attempts has been
        made and the algorithm has not been able to improve the solution for a
        certain number of steps. The minimum number of steps and necessary
        number of idle iterations can be adjusted with the ``steps_minimum``
        and ``steps_idle_fraction`` parameters, respectively.
        
        The default value of the ``steps_idle_fraction`` (0.02) is generally a
        good choice for a variety of problems, but the default
        ``steps_minimum`` value (100000) may have to be adjusted depending on
        the problem. As a general recommendation, the user should reduce the
        ``steps_minimum`` parameter if the algorithm consistently terminates at
        ``steps_minimum`` after running for a long period without improving
        the solution.
        
        
        Acknowledgements
        ----------------
        
        Both the structure and parts of the source code for the
        ``LateAcceptanceHillClimber`` class is copied from the ``Annealer``
        class in the simanneal_ python project. All contributions from the
        simanneal_ project is hereby gratefully acknowledged. Check out the
        simanneal_ project at
        
            https://github.com/perrygeo/simanneal
        
        which implements the widely used and sucessful Simulated Annealing
        metaheuristic.
        
        
        Support
        -------
        
        Please `open an issue <https://github.com/Gunnstein/lahc/issues/new>`_
        for support.
        
        
        Contributing
        ------------
        
        Please contribute using `Github Flow
        <https://guides.github.com/introduction/flow/>`_.
        Create a branch, add commits, and
        `open a pull request <https://github.com/Gunnstein/lahc/compare/>`_.
        
        .. |lahc_logo| image:: https://github.com/Gunnstein/lahc/blob/master/logo.png
            :target: https://github.com/gunnstein/lahc
        
        
        Bibliography
        ------------
        .. [BURKE2017] E. K. Burke, Y. Bykov, The late acceptance Hill-Climbing heuristic.
        	       European Journal of Operational Research. 258, 70–78 (2017).
        
        
        
        
        .. _simanneal: https://github.com/perrygeo/simanneal
        
Platform: UNKNOWN
Classifier: License :: OSI Approved :: ISC License (ISCL)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Topic :: Scientific/Engineering
Description-Content-Type: text/x-rst
