:py:mod:`alhambra.anneal`
=========================

.. py:module:: alhambra.anneal


Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   alhambra.anneal.Annealer



Functions
~~~~~~~~~

.. autoapisummary::

   alhambra.anneal.round_figures
   alhambra.anneal.time_string



.. py:function:: round_figures(x, n)

   Returns x rounded to n significant figures.


.. py:function:: time_string(seconds)

   Returns time in seconds as a string formatted HHHH:MM:SS.


.. py:class:: Annealer(energy, move)


   Performs simulated annealing by calling functions to calculate
   energy and make moves on a state.  The temperature schedule for
   annealing may be provided manually or estimated automatically.

   .. py:method:: anneal(state, Tmax, Tmin, steps, updates=0)

      Minimizes the energy of a system by simulated annealing.

      Keyword arguments:
      state -- an initial arrangement of the system
      Tmax -- maximum temperature (in units of energy)
      Tmin -- minimum temperature (must be greater than zero)
      steps -- the number of steps requested
      updates -- the number of updates to print during annealing

      Returns the best state and energy found.


   .. py:method:: auto(state, minutes, steps=2000)

      Minimizes the energy of a system by simulated annealing with
      automatic selection of the temperature schedule.

      Keyword arguments:
      state -- an initial arrangement of the system
      minutes -- time to spend annealing (after exploring temperatures)
      steps -- number of steps to spend on each stage of exploration

      Returns the best state and energy found.