gflownet.envs.ising
===================

.. py:module:: gflownet.envs.ising

.. autoapi-nested-parse::

   Ising model: The sample space is an ensemble of discrete variables that can take two
   values (-1 or +1), arranged spatially in a D-dimensional grid. The state space includes
   intermediate states with variables at a neutral (not yet selected) spin and states that
   indicate the variable to be set or unset.



Attributes
----------

.. autoapisummary::

   gflownet.envs.ising.TOGGLE_VARIABLE
   gflownet.envs.ising.SET_SPIN
   gflownet.envs.ising.UNSET
   gflownet.envs.ising.TOGGLED
   gflownet.envs.ising.STATE_TYPES


Classes
-------

.. autoapisummary::

   gflownet.envs.ising.Ising


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

.. py:data:: TOGGLE_VARIABLE
   :value: 0


.. py:data:: SET_SPIN
   :value: 1


.. py:data:: UNSET
   :value: 0


.. py:data:: TOGGLED
   :value: 3


.. py:data:: STATE_TYPES

.. py:class:: Ising(n_dim = 2, length = 4, **kwargs)

   Bases: :py:obj:`gflownet.envs.base.GFlowNetEnv`


   Initializes an Ising environment.

   :param n_dim: The dimensionality of the Ising model. Default: 2
   :type n_dim: int
   :param length: The number of variables or cells per dimension. Default: 4
   :type length: int


   .. py:attribute:: n_dim
      :value: 2



   .. py:attribute:: length
      :value: 4



   .. py:attribute:: source


   .. py:attribute:: eos


   .. py:method:: get_action_space()

      Constructs list with all possible actions, including EOS.

      Actions are represented by two elements:
          - Action type: select variable (``TOGGLE_VARIABLE``) or set spin
            (``SET_SPIN``)
          - Value: value of the action, namely the index of the variable for
            selecting variables and -1 or 1 for setting the spin.

      :returns: *list* -- A list of tuples representing the actions.



   .. py:method:: get_mask_invalid_actions_forward(state = None, done = None)

      Returns a list of length the action space indicating which actions are invalid
      (True) and which are not invalid (False).

      :param state: Input state. If None, self.state is used.
      :type state: np.array
      :param done: Whether the trajectory is done. If None, self.done is used.
      :type done: bool

      :returns: *A list of boolean values.*



   .. py:method:: get_parents(state = None, done = None, action = None)

      Determines all parents and actions that lead to state.

      :param state: Input state. If None, self.state is used.
      :type state: np.array
      :param done: Whether the trajectory is done. If None, self.done is used.
      :type done: bool
      :param action: Ignored
      :type action: None

      :returns: * **parents** (*list*) -- List of parents in state format. This environment has a single parent per
                  state.
                * **actions** (*list*) -- List of actions that lead to state for each parent in parents. This
                  environment has a single parent per state.



   .. py:method:: step(action, skip_mask_check = False)

      Executes step given an action.

      Variables follow the following cycle in order to be assigned a spin:
          1. An unselected variable (0) is toggled, turning its value into 3.
          2. A spin is assigned, turning its value into -2 (for spin -1) or 2 (for
          spin 1). This is a transitory state where the variable has been assigned a
          spin but is still toggled.
          3. The variable is toggled and receives its final value (-1 from -2) or (1
          from 2).

      :param action: Action to be executed. An action is a tuple with two elements indicating
                     the action type and action value.
      :type action: tuple
      :param skip_mask_check: If True, skip computing forward mask of invalid actions to check if the
                              action is valid.
      :type skip_mask_check: bool

      :returns: * **self.state** (*list*) -- The state after executing the action
                * **action** (*tuple*) -- Action executed
                * **valid** (*bool*) -- False, if the action is not allowed for the current state.



   .. py:method:: states2policy(states)

      Prepares a batch of states in "environment format" for the policy model: states
      are one-hot encoded.

      The one-hot-encoding is a 2D tensor, with as many rows as entries in the state,
      that is length * n_dim. Each row is a one-hot-encoding of each variable. There
      are 6 possible values: 0, 3, -2, -1, 1, 2.

      :param states: A batch of states in environment format
      :type states: list

      :returns: *A tensor containing all the states in the batch.*



   .. py:method:: readable2state(readable, alphabet={})

      Converts a human-readable string representing a state into a state as a list of
      positions.



   .. py:method:: state2readable(state = None, alphabet={})

      Converts a state (a list of positions) into a human-readable string
      representing a state.