gflownet.envs.choice
====================

.. py:module:: gflownet.envs.choice

.. autoapi-nested-parse::

   A very simple environment to sample one element from a given set of options.

   Given a set of options, the environment proceeds to select one of the options from the
   source state and then only the end-of-sequence action is valid.



Classes
-------

.. autoapisummary::

   gflownet.envs.choice.Choice


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

.. py:class:: Choice(options = None, n_options = 3, source_readable = '<source>', options_available = None, **kwargs)

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


   Initializes a Choice environment.

   :param options: The descrption of the options. If None, the options are simply described by
                   their indices. In this case, ``n_options`` must be not None.
   :type options: iterable (optional)
   :param n_options: The number of options, if ``options`` is None. Ignored otherwise.
   :type n_options: int
   :param source_readable: The string to be used to represent the source state as a human-readable
                           string. By default: <source>
   :type source_readable: str
   :param options_available: A subset of the options to restrict the available options for the
                             environment instance. The elements of the iterable are integers
                             referring to the option indices.
   :type options_available: iterable (optional)


   .. py:attribute:: source_readable
      :value: '<source>'



   .. py:attribute:: options
      :value: None



   .. py:attribute:: n_options


   .. py:attribute:: options_indices


   .. py:attribute:: source
      :value: [0]



   .. py:attribute:: eos


   .. py:method:: get_action_space()

      Constructs list with all possible actions, including EOS.

      Actions are represented by one element, namely the index of the option to be
      selected, starting from 1. The end of sequence action is (-1,).

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



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

      Returns which actions are invalid (True) and which are not invalid (False).

      :param state: Input state. If None, self.state is used.
      :type state: list
      :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.

      There are only three types of states:
          - Done trajectories: the only parent is the state itself with action EOS.
          - Source state: no parents
          - Option selected: the only parent is the source state.

      :param state: Input state. If None, self.state is used.
      :type state: list
      :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.
                * **actions** (*list*) -- List of actions that lead to state for each parent in parents.



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

      Executes step given an action.

      :param action: Action to be executed. An action is a tuple with a single element indicating
                     the the index of the option to be set.
      :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:: set_available_options(options)

      Updates the attribute
      :py:meth:`~gflownet.envs.choice.Choice.options_available`.



   .. py:method:: states2policy(states)

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

      :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 into a human-readable string representing a state.

      The readable representation is taken from ``self.options``, except if the state
      is the source state in which case ``self.source_readable`` is returned.



   .. py:method:: get_all_terminating_states()

      Returns a list with all the terminating states in environment format.

      :returns: *list* -- The list of all terminating states.



   .. py:method:: get_uniform_terminating_states(n_states, seed = None)

      Constructs a batch of n states uniformly sampled in the sample space of the
      environment.

      :param n_states: The number of states to sample.
      :type n_states: int
      :param seed: Random seed.
      :type seed: int