:py:mod:`omnisolver.pt.replica`
===============================

.. py:module:: omnisolver.pt.replica

.. autoapi-nested-parse::

   Implementation of replica used in parallel tempering.



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

Classes
~~~~~~~

.. autoapisummary::

   omnisolver.pt.replica.Replica



Functions
~~~~~~~~~

.. autoapisummary::

   omnisolver.pt.replica._create_replica_cls
   omnisolver.pt.replica.initialize_replica



.. py:class:: Replica(model: omnisolver.pt.model.IsingModel, initial_state, beta)

   Replica of Ising spin-glass used in parallel tempering algorithm.

   :ivar model: Instance of Ising model this replica uses.
   :ivar beta: inverse temperature used for sampling.
   :ivar current_state: current state of the replica.
   :ivar current_energy: current energy of the replica. This energy always corresponds to
    replica's current state.
   :ivar best_state_so_far: best state the replica was in so far. This information is updated
    (if necessary) in every Monte-Carlo iteration.
   :ivar best_energy_so_far: energy corresponding to the best state seen by this replica so far.

   .. py:method:: should_accept_flip(energy_diff: float) -> bool

      Determine if this replica should accept spin flip resulting in given energy difference.

      :param energy_diff: energy difference between current state of replica and the
       state with flipped spin.
      :return: True if replica should accept the change and False otherwise.

      .. note::
         Obviously, this method is non-deterministic. Energy differences greater than 0
         (i.e. changes that improve energy) are always accepted, while flips worsening
         current energy are accepted with the usual Metropolis-Hastings probability.


   .. py:method:: perform_mc_sweep() -> None

      Perform single Monte-Carlo sweep in this replica.

      Performing MC sweep involves triaging every possible spin flip and deciding whether it
      should be accepted or not. The replica's current state and energy, as well as
      replica's best state and energy are update accordingly.



.. py:function:: _create_replica_cls(spec)


.. py:function:: initialize_replica(model: omnisolver.pt.model.IsingModel, initial_state, beta) -> Replica

   Initialize an instance of jit-compiled Replica class.

   :param model: Ising model used by the replica.
   :param initial_state: initial state of the replica. This is expected to be
    a 1D array of +/-1 integers of size N, where N is the number of spins
    in the model. If this requirement is not met, `ValueError` is raised.
   :param beta: inverse temperature of the replica.
   :raises ValueError: If initial state is not of shape (N,), where N
    is the number of spins in the system.
   :return: An instance of jit-compiled Replica class.

   .. note::
      Jit-compiled class definitions are reused, provided that the types
      of model coefficients are the same. Hence, in typical run all replicas
      are of the same numba type.