.. _basin_hopping:

=============
Basin Hopping
=============

Basin hopping is a Monte Carlo method in which the energy of each configuration
is taken to be the energy of a local minimum. [#wales]_

At each basin hopping step the client will print out the current energy
(current), the trial energy (trial), the lowest energy found (global min), the
number of force calls needed to minimize the structure (fc), the acceptance
ratio (ar), and the current max displacement (md).

[Basin Hopping] Options
=======================

**steps**: Number at steps to take at the assigned temeprature.

    default: ``10000``

**displacement**: Displacement in each degree of freedom.

    default: ``0.5``

**write_unique**: If ``true`` the client will write out all the unique geometries
that it sees and there energies to files named min_xxxxx.con and energy_xxxxx.con
where the number in the filename corresponds to the monte carlo step where
that structure was first seen. For clusters it is important to set **check_rotation**
in the **[Structure Comparison]** section.

    default: ``false``

**initial_state_pool_size**: The number of lowest energy states in the pool from
which the initial structures are drawn.  The default value of 1 corresponds to a
simulation which will always start from the lowest energy found so far.

    default: ``1``

**initial_random_structure_probability**: Probability that the initial structure
is generated at random.

    default: ``0.0``

**push_apart_distance**: Push atoms apart until now atoms are closer than this distance. This critera is enforced for the initial structure and all those generated by random displacements.
trial move.

    default: ``0.4``

**adjust_displacement**: Flag to automatically adjust the displacement to meet
the target acceptance ratio.

    default: ``true``

**adjust_fraction**: The fraction by which to change the step size in order to
meet the target acceptance ratio.

    default: ``0.05``

**adjust_period**: The number of Monte Carlo steps between adjustments of the
step size.

    default: ``10``

**target_ratio**: The target acceptance ratio that will be used to determine
whether to increase or decrease the step size.

    default: ``0.5``

**displacement_distribution**: The distribution used for the displacement of
each atom.

    default: ``gaussian``

    options:

        ``gaussian``: The **displacement** serves as the standard deviation of a
        gaussian distribution used to select displacements.

        ``uniform``: A random number is selected between -**displacement** and **displacement**.

**swap_probability**: The probability in range [0,1] that a swapping step
takes place instead of a displacement step. The swap step selects two atoms of
different elements and swaps their position.

    default: ``0.0``

**single_atom_displace**: Displace only one atom per step.

    default: ``False``

**jump_max**: The number of consecutive rejected steps after which jump steps
should be taken. This serves to provide a more global search when the structure
is stuck in a certain basin. The number of jump steps is assigned in
jump_steps. See paper on the Basin Hopping with Occasional Jumping algorithm by
Iwamatsu and Okabe. [#iwamatsu]_

    default: ``0``

**significant_structure**: Displace from minimized structures. [#white]_

    default: ``True``

**jump_steps**: The number of jump steps to take after the jump_max number of
consecutive rejections have taken place.

    default: ``0``

.. rubric:: References

.. [#wales] D.J. Wales and J.P.K. Doye, "Global optimization by basin-hopping and the lowest energy structures of Lennard-Jones clusters containing up to 110 atoms," *J. Phys. Chem. A* **101**, 5111 (1997). doi:`10.1021/jp970984n <http://dx.doi.org/10.1021/jp970984n>`_

.. [#iwamatsu] M. Iwamatsu and Y. Okabe, "Basin hopping with occasional jumping," *Chem. Phys. Lett.* **399** 396 (2004). doi:`10.1016/j.cplett.2004.10.032 <http://dx.doi.org/10.1016/j.cplett.2004.10.032>`_

.. [#white] R.P. White and H.R. Mayne, "An investigation of two approaches to basin hopping minimization for atomic and molecular clusters," *Chem. Phys. Lett.* **289**, 463 (1998). doi:`10.1016/S0009-2614(98)00431-X <http://dx.doi.org/10.1016/S0009-2614(98)00431-X>`_