qemcmc.model.constraint_model
=============================

.. py:module:: qemcmc.model.constraint_model


Classes
-------

.. autoapisummary::

   qemcmc.model.constraint_model.ConstraintModel


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

.. py:class:: ConstraintModel(n: int, constraint_couplings: list[numpy.ndarray], constraint_signs: list[float], couplings: list[numpy.ndarray], constraint_func: Callable[[str], bool], **kwargs)

   Bases: :py:obj:`qemcmc.model.energy_model.EnergyModel`


   A subclass of EnergyModel that incorporates a constraint function to define valid configurations.

   The constraint function takes a state as input and returns True if the state is valid
   (satisfies the constraint) and False otherwise. The energy of invalid states is set to
   infinity, effectively excluding them from the Boltzmann distribution.

   :param n: Number of spins in the model.
   :type n: int
   :param constraint_couplings: List of coupling tensors (numpy arrays) defining the constraint.
   :type constraint_couplings: list[np.ndarray]
   :param constraint_signs: Sign convention(s) for the constraint couplings.
   :type constraint_signs: list[float]
   :param couplings: List of coupling tensors (numpy arrays) defining the energy function.
   :type couplings: list[np.ndarray]
   :param constraint_func: A function that takes a state (string representation of spin configuration)
                           and returns True if the state satisfies the constraint, and False otherwise.
   :type constraint_func: typing.Callable[[str], bool]
   :param name: Optional label for the model (used in plotting / logging).
   :type name: str, optional
   :param cost_function_signs: Sign convention(s) used by downstream components (e.g. proposal/acceptance conventions).
   :type cost_function_signs: list[float], optional
   :param model_type: Type of model, either 'ising' or 'binary'. This determines how the binary states are interpreted
                      and how the energy is calculated. 'ising' models use spin values {-1, +1}, while 'binary'
                      models use binary values {0, 1}.
   :type model_type: str, optional

   .. rubric:: Notes

   - The energy of any state that does not satisfy the constraint is set to infinity, which means
     such states will have zero probability in the Boltzmann distribution.
   - This class can be used to model systems with hard constraints on the configurations, such as
     certain combinatorial optimization problems or physical systems with forbidden states.


   .. py:attribute:: constraint_func


   .. py:attribute:: get_initial_states

      Generates a list of random initial states.

      :param num_initial_states: The number of initial states to generate.

      :returns: A list of random initial states.
      :rtype: list


   .. py:attribute:: constraint_couplings


   .. py:attribute:: constraint_signs


   .. py:attribute:: constraint_coupling_alphas


   .. py:attribute:: normalised_couplings


   .. py:attribute:: total_couplings


   .. py:method:: get_initial_states_constraint(num_initial_states: int)

      Generates a list of random initial states that satisfy the constraint function.

      :param num_initial_states: The number of initial states to generate.

      :returns: A list of random initial states that are valid according to the constraint.
      :rtype: list



   .. py:method:: get_constraint_energy(state: str) -> float

      Calculate the energy contribution from the constraint couplings for a given state.

      :param state: The state for which to calculate the constraint energy.
      :type state: str

      :returns: The energy contribution from the constraint couplings for the given state.
      :rtype: float



   .. py:method:: get_total_energy(state: str) -> float

      Calculate the total energy of a given state, including both the regular energy and the constraint energy.

      :param state: The state for which to calculate the total energy.
      :type state: str

      :returns: The total energy of the given state, including contributions from both the regular couplings and the constraint couplings.
      :rtype: float