gfn.containers.base
===================

.. py:module:: gfn.containers.base


Classes
-------

.. autoapisummary::

   gfn.containers.base.Container


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

.. py:class:: Container

   Bases: :py:obj:`abc.ABC`


   Base class for state containers (states, transitions, or trajectories).


   .. py:method:: __getitem__(index)
      :abstractmethod:


      Returns a subset of the container based on the provided index.

      :param index: An integer, slice, tuple, sequence of indices or booleans,
                    or a torch.Tensor specifying which elements to select.

      :returns: A new container containing the selected elements and associated data.



   .. py:method:: __len__()
      :abstractmethod:


      Returns the number of elements in the container.

      :returns: The number of elements in the container.



   .. py:property:: device
      :type: torch.device

      :abstractmethod:


      The device on which the container is stored.

      :returns: The device on which the container is stored.


   .. py:method:: extend(other)
      :abstractmethod:


      Extends the current container with elements from another container object.

      :param other: The other container whose elements will be added.



   .. py:method:: from_tensordict(env, td)
      :classmethod:

      :abstractmethod:


      Reconstruct a container from a TensorDict.

      :param env: The environment needed to reconstruct States/Actions.
      :param td: The TensorDict produced by :meth:`to_tensordict`.

      :returns: A new container instance.



   .. py:property:: has_log_probs
      :type: bool


      Whether the container has log probabilities.

      :returns: True if log probabilities are present and non-empty, False otherwise.


   .. py:method:: load(env, path)
      :classmethod:


      Loads a container from a ``.pt`` file saved by :meth:`save`.

      :param env: The environment needed to reconstruct States/Actions.
      :param path: File path to the saved container.

      :returns: A new container instance.



   .. py:property:: log_rewards
      :type: torch.Tensor

      :abstractmethod:


      The log rewards associated with the container.

      :returns: The log rewards tensor.


   .. py:method:: sample(n_samples)

      Randomly samples a subset of elements from the container.

      :param n_samples: The number of elements to sample.

      :returns: A new container with the sampled elements.



   .. py:method:: save(path)

      Saves the container to a single ``.pt`` file.

      :param path: File path (e.g. ``"trajectories.pt"``).



   .. py:property:: terminating_states
      :type: gfn.states.States

      :abstractmethod:


      The last (terminating) states of the container.

      :returns: The terminating states.


   .. py:method:: to_tensordict()
      :abstractmethod:


      Serialize the container's data into a TensorDict.

      :returns: A TensorDict containing all tensor data and scalar metadata.
                The ``env`` reference is not included; it must be supplied
                when reconstructing via :meth:`from_tensordict`.