gfn.gym.perfect_tree
====================

.. py:module:: gfn.gym.perfect_tree


Classes
-------

.. autoapisummary::

   gfn.gym.perfect_tree.PerfectBinaryTree


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

.. py:class:: PerfectBinaryTree(reward_fn, depth = 4, device = None, debug = False)

   Bases: :py:obj:`gfn.env.DiscreteEnv`


   Perfect Tree Environment.

   This environment is a perfect binary tree, where there is a bijection between
   trajectories and terminating states. Nodes are represented by integers, starting
   from 0 for the root. States are represented by a single integer tensor
   corresponding to the node index. Actions are integers: 0 (left child), 1 (right
   child), 2 (exit).

   e.g.:

              0 (root)
         /         \
        1           2
      /   \       /   \
     3     4     5     6
    / \   / \   / \   / \
   7   8  9  10 11 12 13 14 (terminating states if depth=3)

   Recommended preprocessor: `OneHotPreprocessor`.

   .. attribute:: reward_fn

      A function that computes the reward for a given state.

      :type: Callable

   .. attribute:: depth

      The depth of the tree.

      :type: int

   .. attribute:: branching_factor

      The branching factor of the tree.

      :type: int

   .. attribute:: n_actions

      The number of actions.

      :type: int

   .. attribute:: n_nodes

      The number of nodes in the tree.

      :type: int

   .. attribute:: transition_table

      A dictionary that maps (state, action) to the next state.

      :type: dict

   .. attribute:: inverse_transition_table

      A dictionary that maps (state, action) to the previous state.

      :type: dict

   .. attribute:: term_states

      The terminating states.

      :type: DiscreteStates


   .. py:attribute:: States
      :type:  type[gfn.env.DiscreteStates]


   .. py:method:: _build_tree()

      Builds the tree and the transition tables.

      :returns: A tuple containing the transition table, the inverse transition table,
                and the terminating states.



   .. py:property:: all_states
      :type: gfn.env.DiscreteStates


      Returns all the states of the environment.


   .. py:method:: backward_step(states, actions)

      Performs a backward step in the environment.

      :param states: The current states.
      :param actions: The actions to take.

      :returns: The previous states.



   .. py:attribute:: branching_factor
      :value: 2



   .. py:attribute:: depth
      :value: 4



   .. py:method:: get_states_indices(states)

      Returns the indices of the states.

      :param states: The states to get the indices of.

      :returns: The indices of the states.



   .. py:method:: make_states_class()

      Returns the DiscreteStates class for the PerfectBinaryTree environment.



   .. py:attribute:: n_actions
      :value: 3



   .. py:attribute:: n_nodes
      :value: 31



   .. py:method:: reward(final_states)

      Computes the reward for a batch of final states.

      :param final_states: The final states.

      :returns: The reward of the final states.



   .. py:attribute:: reward_fn


   .. py:attribute:: s0


   .. py:attribute:: sf


   .. py:method:: step(states, actions)

      Performs a step in the environment.

      :param states: The current states.
      :param actions: The actions to take.

      :returns: The next states.



   .. py:property:: terminating_states
      :type: gfn.env.DiscreteStates


      Returns the terminating states of the environment.