gflownet.proxy.ising
====================

.. py:module:: gflownet.proxy.ising


Classes
-------

.. autoapisummary::

   gflownet.proxy.ising.Ising


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

.. py:class:: Ising(n_dim = None, length = None, J_nn = 1.0, periodic = True, J = None, h = 0.0, **kwargs)

   Bases: :py:obj:`gflownet.proxy.base.Proxy`


   Ising energy model.

   Implements an Ising Hamiltonian of the form

   .. math::

       E(s) = -\frac{1}{2} s^T J s - h \cdot s

   where ``s`` is a spin configuration, ``J`` is the coupling matrix, and ``h`` is
   an external magnetic field.

   The factor ``1/2`` ensures that each pairwise interaction is counted once.

   :param n_dim: Number of spatial dimensions of the lattice. Not needed if J is provided.
   :type n_dim: int
   :param length: Number of sites along each dimension. Not needed if J is provided.
   :type length: int
   :param J_nn: Nearest-neighbor coupling strength.
   :type J_nn: float, default=1.0
   :param periodic: Whether to use periodic boundary conditions.
   :type periodic: bool, default=True
   :param J: Optional full coupling matrix. Overrides Nearest-neighbor coupling matrix
             construction.
   :param h: External magnetic field (scalar or site-dependent tensor).


   .. py:attribute:: n_dim
      :value: None



   .. py:attribute:: length
      :value: None



   .. py:attribute:: J_nn
      :value: 1.0



   .. py:attribute:: periodic
      :value: True



   .. py:attribute:: h


   .. py:method:: nn_adjacency()

      Build the nearest-neighbor adjacency matrix for a hypercubic lattice.

      Constructs a coupling matrix ``J`` for an ``n_dim``-dimensional hypercubic
      lattice of linear size ``length`` (total number of sites ``length**n_dim``),
      where each site is coupled to its nearest neighbors with strength ``J_nn``.

      :returns: * A tensor of shape ``(N, N)``, where ``N = length**n_dim``, representing the
                * *nearest-neighbor coupling matrix.*



   .. py:method:: __call__(states)

      Compute the Ising energy for a batch of spin configurations.

      - Flattens input to shape (batch, state_dim).
      - Computes the quadratic interaction term:
              ``-0.5 * sum( (s @ J) * s)``
      - Computes the field term:
              ``-h * sum(s)``                (if h is scalar)
        or ``-sum(h * s)``                   (if h is per-site)


      :param states: Batch of spin configurations.
      :type states: list or tensor

      :returns: Tensor of shape (batch,) containing energies.