gfn.gym.bitSequence

Classes

BitSequence	Append-only BitSequence environment.
BitSequencePlus	Prepend-Append version of BitSequence env.
BitSequenceStates	A class representing states of bit sequences in a discrete state space.

Module Contents

class gfn.gym.bitSequence.BitSequence(word_size=4, seq_size=120, n_modes=60, temperature=1.0, H=None, device_str='cpu', seed=0, debug=False)

Bases: 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.

Parameters:

• word_size (int)

• seq_size (int)

• n_modes (int)

• temperature (float)

• H (Optional[torch.Tensor])

• device_str (str)

• seed (int)

• debug (bool)

word_size

The size of each binary word in the sequence.

seq_size

The total number of digits of the sequence.

n_modes

The number of unique modes in the sequence.

temperature

The temperature parameter for reward calculation.

H

A tensor used to create the modes.

device_str

The device to run the computations on (“cpu” or “cuda”).

words_per_seq

The number of words per sequence.

modes

The set of modes written as binary.

H = None

States: type[BitSequenceStates]

_backward_step(states, actions)

Perform a backward step in the environment by undoing the given actions to the current states.

Parameters:

• states (BitSequenceStates) – The current states of the environment.

• actions (gfn.actions.Actions) – The actions to be applied to the current states.

Returns:

The new states after performing the backward step.

_step(states, actions)

Perform a step in the environment by applying the given actions to the current states.

Parameters:

• states (BitSequenceStates) – The current states of the environment.

• actions (gfn.actions.Actions) – The actions to be applied to the current states.

Returns:

The new states of the environment after applying the actions.

backward_step(states, actions)

Performs a backward step in the environment.

Parameters:

• states (BitSequenceStates) – The current states.

• actions (gfn.actions.Actions) – The actions to take.

Returns:

The previous states.

Return type:

BitSequenceStates

static binary_to_integers(binary_tensor, k)

Convert a binary tensor to a tensor of integers.

Parameters:

• binary_tensor (torch.Tensor) – A tensor containing binary values. The tensor must be of type int64.

• k (int) – The number of bits in each integer.

Returns:

A tensor of integers obtained from the binary tensor.

Return type:

torch.Tensor

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.

Parameters:

• k (int) – Number of variations per mode.

• seed (int) – Seed for reproducibility. If None, randomness is not fixed.

Returns:

The generated test set in the decimal representation.

Return type:

BitSequenceStates

static hamming_distance(candidates, reference)

Compute the smallest edit distance from each candidate row to any reference row.

Parameters:

• candidates (torch.Tensor) – Tensor of shape (*batch_shape, length).

• reference (torch.Tensor) – Tensor of shape (n_ref, length).

Returns:

Tensor of shape (*batch_shape) containing the smallest edit distance for each candidate row.

Return type:

torch.Tensor

static integers_to_binary(tensor, k)

Convert a tensor of integers to their binary representation using k bits.

Parameters:

• tensor (torch.Tensor) – A tensor containing integers.

• k (int) – The number of bits to use for the binary representation of each integer.

Returns:

A tensor containing the binary representation of the input integers.

Return type:

torch.Tensor

log_reward(final_states)

Calculates the log-reward for the given final states.

Parameters:

final_states (BitSequenceStates) – The final states for which to calculate the log-reward.

Returns:

The calculated log-reward.

Return type:

torch.Tensor

make_modes_set(seed)

Generates a set of unique mode sequences based on the predefined tensor H.

Parameters:

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.

Return type:

torch.Tensor

make_states_class()

Creates a BitSequenceStates class implementation.

Returns:

A BitSequenceStates class implementation.

Return type:

type[BitSequenceStates]

modes

n_actions = 17

n_modes: int = 60

property n_states3: int

Returns the total number of states in the environment.

Return type:

int

property n_terminating_states: int

Returns the number of terminating states.

Return type:

int

reset(batch_shape=None, sink=False)

Generates initial or sink states from batch_shape.

Parameters:

• batch_shape (int | Tuple[int] | None) – The shape of the batch. If None, defaults to (1,). If an integer is provided, it is converted to a tuple.

• sink (bool) – If True, sink state is created. Defaults to False.

Returns:

The initial states of the environment after reset.

Return type:

BitSequenceStates

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.

Parameters:

final_states (BitSequenceStates) – The final states for which the reward is to be calculated.

Returns:

The calculated reward for the given final states.

seq_size: int = 120

states_from_tensor(tensor, length=None)

Wraps the supplied Tensor in a States instance.

Parameters:

• tensor (torch.Tensor) – The tensor of shape state_shape representing the states.

• length (Optional[torch.Tensor]) – The length of each state in the tensor.

Returns:

An instance of States.

Return type:

BitSequenceStates

step(states, actions)

Performs a step in the environment.

Parameters:

• states (BitSequenceStates) – The current states.

• actions (gfn.actions.Actions) – The actions to take.

Returns:

The next states.

Return type:

BitSequenceStates

temperature = 1.0

property terminating_states: BitSequenceStates

Returns all terminating states of the environment.

Return type:

BitSequenceStates

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.

Parameters:

terminating_states_tensor (torch.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.

Return type:

gfn.containers.Trajectories

true_dist(condition=None)

Returns the true probability mass function of the reward distribution.

Return type:

torch.Tensor

word_size: int = 4

words_per_seq: int = 30

class gfn.gym.bitSequence.BitSequencePlus(word_size=4, seq_size=120, n_modes=60, temperature=1.0, H=None, device_str='cpu', seed=0)

Bases: BitSequence

Prepend-Append version of BitSequence env.

This environment is similar to BitSequence, but allows to prepend and append words to the sequence.

Parameters:

• word_size (int)

• seq_size (int)

• n_modes (int)

• temperature (float)

• H (Optional[torch.Tensor])

• device_str (str)

• seed (int)

H = None

backward_step(states, actions)

Performs a backward step in the environment.

Parameters:

• states (BitSequenceStates) – The current states.

• actions (gfn.actions.Actions) – The actions to take.

Returns:

The previous states.

Return type:

BitSequenceStates

make_states_class()

Creates a BitSequenceStates class implementation for BitSequencePlus.

Returns:

A BitSequenceStates class implementation with prepend-append mask logic.

Return type:

type[BitSequenceStates]

modes

n_modes: int = 60

seq_size: int = 120

step(states, actions)

Performs a step in the environment.

Parameters:

• states (BitSequenceStates) – The current states.

• actions (gfn.actions.Actions) – The actions to take.

Returns:

The next states.

Return type:

BitSequenceStates

temperature = 1.0

abstract trajectory_from_terminating_states(terminating_states_tensor)

Generates trajectories from terminating states. Not implemented for this environment.

Parameters:

terminating_states_tensor (torch.Tensor) – A tensor of terminating states.

Raises:

NotImplementedError – This method is not implemented for this environment.

Return type:

gfn.containers.Trajectories

word_size: int = 4

words_per_seq: int = 30

class gfn.gym.bitSequence.BitSequenceStates(tensor, length=None, conditions=None, debug=False)

Bases: gfn.states.DiscreteStates

A class representing states of bit sequences in a discrete state space.

Parameters:

• tensor (torch.Tensor)

• length (Optional[torch.Tensor])

• conditions (Optional[torch.Tensor])

• debug (bool)

word_size

The size of each word in the bit sequence.

Type:

ClassVar[int]

words_per_seq

The number of words per sequence.

Type:

ClassVar[int]

tensor

The tensor representing the states.

Type:

torch.Tensor

length

The tensor representing the length of each bit sequence.

Type:

torch.Tensor

__getitem__(index)

Returns a subset of the BitSequenceStates object based on the given index.

Parameters:

index (int | slice | tuple | Sequence[int] | Sequence[bool] | torch.Tensor) – The index to use for subsetting.

Returns:

A subset of the BitSequenceStates object.

Return type:

BitSequenceStates

__setitem__(index, states)

Sets a subset of the BitSequenceStates object based on the given index and states.

Parameters:

• index (int | Sequence[int] | Sequence[bool]) – The index to use for subsetting.

• states (BitSequenceStates) – The states to set.

Return type:

None

_compute_backward_masks()

Computes backward masks for BitSequence states.

Return type:

torch.Tensor

_compute_forward_masks()

Computes forward masks for BitSequence states.

Return type:

torch.Tensor

clone()

Returns a clone of the current BitSequenceStates object.

Returns:

A clone of the current BitSequenceStates object.

Return type:

BitSequenceStates

extend(other)

Extends the current BitSequenceStates object with another BitSequenceStates object.

Parameters:

other (BitSequenceStates) – The BitSequenceStates object to extend with.

Return type:

None

flatten()

Flattens the BitSequenceStates object.

Returns:

The flattened BitSequenceStates object.

Return type:

BitSequenceStates

length: torch.Tensor

pad_dim0_with_sf(required_first_dim)

Extends the current BitSequenceStates object with sink states.

Parameters:

required_first_dim (int) – The required first dimension of the extended states.

Return type:

None

classmethod stack(states)

Stacks a list of BitSequenceStates objects into a single BitSequenceStates object.

Parameters:

states (Sequence[BitSequenceStates]) – A list of BitSequenceStates objects.

Returns:

A single stacked BitSequenceStates object.

Return type:

BitSequenceStates

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.

Return type:

List[str]

word_size: ClassVar[int]

words_per_seq: ClassVar[int]