gfn.gym.bitSequence =================== .. py:module:: gfn.gym.bitSequence Classes ------- .. autoapisummary:: gfn.gym.bitSequence.BitSequence gfn.gym.bitSequence.BitSequencePlus gfn.gym.bitSequence.BitSequenceStates Module Contents --------------- .. py:class:: BitSequence(word_size = 4, seq_size = 120, n_modes = 60, temperature = 1.0, H = None, device_str = 'cpu', seed = 0, debug = False) Bases: :py:obj:`gfn.env.DiscreteEnv` Append-only BitSequence environment. This environment represents a sequence of binary words and provides methods to manipulate and evaluate these sequences. The possible actions are adding binary words at once. Each binary word is represented as its decimal representation in both states and actions. .. attribute:: word_size The size of each binary word in the sequence. .. attribute:: seq_size The total number of digits of the sequence. .. attribute:: n_modes The number of unique modes in the sequence. .. attribute:: temperature The temperature parameter for reward calculation. .. attribute:: H A tensor used to create the modes. .. attribute:: device_str The device to run the computations on ("cpu" or "cuda"). .. attribute:: words_per_seq The number of words per sequence. .. attribute:: modes The set of modes written as binary. .. py:attribute:: H :value: None .. py:attribute:: States :type: type[BitSequenceStates] .. py:method:: _backward_step(states, actions) Perform a backward step in the environment by undoing the given actions to the current states. :param states: The current states of the environment. :param actions: The actions to be applied to the current states. :returns: The new states after performing the backward step. .. py:method:: _step(states, actions) Perform a step in the environment by applying the given actions to the current states. :param states: The current states of the environment. :param actions: The actions to be applied to the current states. :returns: The new states of the environment after applying the actions. .. 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:method:: binary_to_integers(binary_tensor, k) :staticmethod: Convert a binary tensor to a tensor of integers. :param binary_tensor: A tensor containing binary values. The tensor must be of type int64. :param k: The number of bits in each integer. :returns: A tensor of integers obtained from the binary tensor. .. py:method:: create_test_set(k, seed = 0) Create a test set by altering k times each mode a random number of bits. Test set of size n_modes * k. :param k: Number of variations per mode. :param seed: Seed for reproducibility. If None, randomness is not fixed. :returns: The generated test set in the decimal representation. .. py:method:: hamming_distance(candidates, reference) :staticmethod: Compute the smallest edit distance from each candidate row to any reference row. :param candidates: Tensor of shape `(*batch_shape, length)`. :param reference: Tensor of shape `(n_ref, length)`. :returns: Tensor of shape `(*batch_shape)` containing the smallest edit distance for each candidate row. .. py:method:: integers_to_binary(tensor, k) :staticmethod: Convert a tensor of integers to their binary representation using k bits. :param tensor: A tensor containing integers. :param k: The number of bits to use for the binary representation of each integer. :returns: A tensor containing the binary representation of the input integers. .. py:method:: log_reward(final_states) Calculates the log-reward for the given final states. :param final_states: The final states for which to calculate the log-reward. :returns: The calculated log-reward. .. py:method:: make_modes_set(seed) Generates a set of unique mode sequences based on the predefined tensor H. :param seed: The seed for random number generation. :returns: A tensor containing the unique mode sequences. :raises ValueError: If the number of requested modes exceeds the number of possible unique sequences. .. py:method:: make_states_class() Creates a BitSequenceStates class implementation. :returns: A BitSequenceStates class implementation. .. py:attribute:: modes .. py:attribute:: n_actions :value: 17 .. py:attribute:: n_modes :type: int :value: 60 .. py:property:: n_states3 :type: int Returns the total number of states in the environment. .. py:property:: n_terminating_states :type: int Returns the number of terminating states. .. py:method:: reset(batch_shape = None, sink = False) Generates initial or sink states from batch_shape. :param batch_shape: The shape of the batch. If None, defaults to (1,). If an integer is provided, it is converted to a tuple. :param sink: If True, sink state is created. Defaults to False. :returns: The initial states of the environment after reset. .. py:method:: reward(final_states) Calculate the reward for the given final states. The reward is computed based on the Hamming distance between the binary representation of the final states and the predefined modes. The reward is then scaled using an exponential function with a temperature parameter. :param final_states: The final states for which the reward is to be calculated. :returns: The calculated reward for the given final states. .. py:attribute:: seq_size :type: int :value: 120 .. py:method:: states_from_tensor(tensor, length = None) Wraps the supplied Tensor in a States instance. :param tensor: The tensor of shape `state_shape` representing the states. :param length: The length of each state in the tensor. :returns: An instance of States. .. 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:attribute:: temperature :value: 1.0 .. py:property:: terminating_states :type: BitSequenceStates Returns all terminating states of the environment. .. py:method:: trajectory_from_terminating_states(terminating_states_tensor) Generate trajectories from terminating states. This works because the DAG is a tree in the append-only version of BitSequence. :param terminating_states_tensor: A tensor containing the terminating states from which to generate the trajectories. The shape of the tensor should be `(batch_size, words_per_seq)`. :returns: An object containing the generated trajectories. .. py:method:: true_dist(condition=None) Returns the true probability mass function of the reward distribution. .. py:attribute:: word_size :type: int :value: 4 .. py:attribute:: words_per_seq :type: int :value: 30 .. py:class:: BitSequencePlus(word_size = 4, seq_size = 120, n_modes = 60, temperature = 1.0, H = None, device_str = 'cpu', seed = 0) Bases: :py:obj:`BitSequence` Prepend-Append version of BitSequence env. This environment is similar to BitSequence, but allows to prepend and append words to the sequence. .. py:attribute:: H :value: None .. 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:method:: make_states_class() Creates a BitSequenceStates class implementation for BitSequencePlus. :returns: A BitSequenceStates class implementation with prepend-append mask logic. .. py:attribute:: modes .. py:attribute:: n_modes :type: int :value: 60 .. py:attribute:: seq_size :type: int :value: 120 .. 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:attribute:: temperature :value: 1.0 .. py:method:: trajectory_from_terminating_states(terminating_states_tensor) :abstractmethod: Generates trajectories from terminating states. Not implemented for this environment. :param terminating_states_tensor: A tensor of terminating states. :raises NotImplementedError: This method is not implemented for this environment. .. py:attribute:: word_size :type: int :value: 4 .. py:attribute:: words_per_seq :type: int :value: 30 .. py:class:: BitSequenceStates(tensor, length = None, conditions = None, debug = False) Bases: :py:obj:`gfn.states.DiscreteStates` A class representing states of bit sequences in a discrete state space. .. attribute:: word_size The size of each word in the bit sequence. :type: ClassVar[int] .. attribute:: words_per_seq The number of words per sequence. :type: ClassVar[int] .. attribute:: tensor The tensor representing the states. :type: torch.Tensor .. attribute:: length The tensor representing the length of each bit sequence. :type: torch.Tensor .. py:method:: __getitem__(index) Returns a subset of the BitSequenceStates object based on the given index. :param index: The index to use for subsetting. :returns: A subset of the BitSequenceStates object. .. py:method:: __setitem__(index, states) Sets a subset of the BitSequenceStates object based on the given index and states. :param index: The index to use for subsetting. :param states: The states to set. .. py:method:: _compute_backward_masks() Computes backward masks for BitSequence states. .. py:method:: _compute_forward_masks() Computes forward masks for BitSequence states. .. py:method:: clone() Returns a clone of the current BitSequenceStates object. :returns: A clone of the current BitSequenceStates object. .. py:method:: extend(other) Extends the current BitSequenceStates object with another BitSequenceStates object. :param other: The BitSequenceStates object to extend with. .. py:method:: flatten() Flattens the BitSequenceStates object. :returns: The flattened BitSequenceStates object. .. py:attribute:: length :type: torch.Tensor .. py:method:: pad_dim0_with_sf(required_first_dim) Extends the current BitSequenceStates object with sink states. :param required_first_dim: The required first dimension of the extended states. .. py:method:: stack(states) :classmethod: Stacks a list of BitSequenceStates objects into a single BitSequenceStates object. :param states: A list of BitSequenceStates objects. :returns: A single stacked BitSequenceStates object. .. py:method:: to_str() Converts the tensor to a list of binary strings. The tensor is reshaped according to the state shape and then each row is converted to a binary string, ignoring entries with a value of -1. :returns: A list of binary strings representing the tensor. .. py:attribute:: word_size :type: ClassVar[int] .. py:attribute:: words_per_seq :type: ClassVar[int]