
.. _coarse_graining:

================
Coarse Graining
================

In AKMC simulations where there are vastly different rates, the simulation can get stuck in a group of states connected by relatively fast rates. In order to explore slower transitions, a prohibitively large number of KMC steps may be needed. In order to circumvent this problem, eOn implements two methods. The first method, projective dynamics [#novotny]_, groups states that are joined by fast rates into "superbasins". Information about transitions between states in a superbasin is lost, but the rates for transitions across a superbasin are correct. The second method, accelerated superbasining kinetic Monte Carlo (AS-KMC) [#voter]_, artificially raises low barriers. The dynamics between states connected by fast rates are simulated, but an error is introduced in the dynamics direction and time. Both methods cannot be used simultaneously.

Monte Carlo with Absorbing Markov Chains
----------------------------------------

[Coarse Graining] MCAMC Options
===============================

**use_mcamc**: This option determines whether the Monte Carlo with Absorbing Markov Chains (MCAMC) coarse graining method will be used. This mutually excludes the use_askmc option.

    default: ``False``

**state_file**: File name for the state specific data stored within each of the state directories.

    default: ``superbasin``

**superbasin_scheme**: MCAMC provides a method for calculating transition rates across superbasins. An additional method is needed in order to decide when to combine states into a superbasin. eOn provides two methods. The first method, called transition counting, counts the number of times that the simulation has transitioned between a given pair of states. After a critical number of transitions have occured, the pair of states are merged to form a superbasin. (If one is already in a superbasin, the other is added to that superbasin. If both are already in superbasins, the two superbasins are merged). This method can be selected by setting scheme equal to transition_counting.  This method can be elected by setting scheme equal to energy_level.

    default: ``transition_counting``

    Options:

        ``transition_counting``:

        ``energy_level``:

**max_size**: The maximal nr states that will be merger together. If 0 there is no limit.

    default: ``0``

**number_of_transitions**: If the transition counting scheme is being used (scheme=transition_counting), this is the number of transitions that must occur between two states before they are merged into a superbasin.

    default: ``5``

**energy_increment**: If the energy level scheme is being used (superbasin_scheme = energy_level). Each state, the first time it is visited, is assigned an energy level first equal to the energy of the minimum. Every time the state is visited again by the Monte Carlo simulation, the energy level is increased by this amount.

    default: ``0.01``


Accelerated Superbasin Kinetic Monte Carlo
------------------------------------------

The basic process of AS-KMC involves gradually raising process barriers found to be inside of a superbasin such that exiting from the basin gradually becomes more likely. The method is designed to raise all the barriers in the superbasin simultaneously. Once a particular barrier has been crossed a certain number of times, :math:`N_f` (more on determining :math:`N_f` shortly), a check is performed to determine whether or not the current state is part of a superbasin. This is called the Superbasin Criterion. In the Superbasin Criterion, a search is performed, originating at the current state and proceeding outward through all low-barrier processes to adjacent states, and then through all low-barrier processes from each of these states, etc. For each low-barrier process found, if the process has been followed fewer than :math:`N_f` times, the Superbasin Criterion fails and no barriers are raised. Thus, in the outward-expanding search from the originating state, the search continues until either a low-barrier process has been seen fewer than :math:`N_f` times (and the Criterion fails) or until all connected low-barrier processes have been found and have been crossed at least :math:`N_f` times (the edges of the superbasin are then defined and the Criterion passes). If the Superbasin Criterion passes, all the low-barrier processes (each of which as been crossed :math:`N_f` times) are raised.

Several parameters dictate the functioning of the AS-KMC method. These parameters dictate how much the barriers are raised each time the Superbasin Criterion passes(**askmc_barrier_raise_param**), what defines a “low-barrier” for use in the Superbasin Criterion(**askmc_high_barrier_def**), and the approximate amount of error the user might expect in eventual superbasin exit direction and time compared to normal kmc simulation (**askmc_confidence**). 

[Coarse Graining] AS-KMC Options
================================

**use_askmc**: This option determines whether the AS-KMC coarse graining method will be used. This mutually excludes the **use_projective_dynamics** option.

    Default: ``False``

**askmc_confidence**: The confidence for AS-KMC. This value determines the accuracy of the direction of the dynamics trajectory. (:math:`1-\delta` in the reference.)
    
    Default: ``0.9``

**askmc_barrier_raise_param**: This parameter sets how much the barriers are raised during AS-KMC.  (:math:`\alpha` in the reference.)

    Default: ``1.5``

**askmc_high_barrier_def**: This parameter sets how high a barrier must be to be considered “high” in AS-KMC. (:math:`\gamma` in the reference.)

    Default: ``2.0``

**askmc_barrier_test_on**: Because the implemented Superbasin Criterion actually only considers processes which have been passed over at least once, there is some chance that a low-barrier process in a superbasin might have not been visited at all while all other low-barrier processes have been visited at least :math:`N_f` times. This is unlikely, but this test verifies that such has not happened, considering even processes which have not been visited when determining if the Superbasin Criterion has first, because the implemented Superbasin Criterion actually only considers processes which have been passed over at least once, there is some chance that a low-barrier process in a superbasin might have not been visited at all while all other low-barrier processes have been visited at least :math:`N_f` times. This is unlikely, but this test verifies that such has not happened, considering even processes which have not been visited when determining if the Superbasin Criterion has passed. This check should not add significant overhead.

    Default: ``True``
    
**askmc_connections_test_on**: This parameter determines whether to ensure that there are no processes which connect states in the defined superbasin which have not been visited yet and which have a low-barrier. This check is somewhat more computationally expensive than the previous because structure comparisons have to be made when finding product states of unvisited processes.

    Default: ``False``

.. rubric:: References

.. [#novotny] M.A. Novotny "A tutorial on advanced dynamic Monte Carlo methods for systems with discrete state spaces" http://arxiv.org/abs/cond-mat/0109182

.. [#voter] A. Chatterjee and A.F. Voter "Accurate acceleration of kinetic Monte Carlo simulations through the modification of rate constants" J. Chem. Phys. 132, 194101 (2010) doi:`10.1063/1.3409606 <http://dx.doi.org/10.1063/1.3409606>`_
