env

Rubik's Cube Environment

Este módulo define a classe Cube3 que representa um Cubo de Rubik 3x3x3 na Métrica de Meia Volta (Half-Turn Metric).

Classe: Cube3: Uma classe para o Cubo de Rubik 3x3x3 na Métrica de Meia Volta.

Cube3

class Cube3()

Uma classe para o Cubo de Rubik 3x3x3 na Métrica de Meia Volta (HTM).

Esta classe fornece métodos para manipular e resolver um Cubo de Rubik 3x3x3 usando a métrica de meia volta. Ela define os estados inicial e final do cubo, os movimentos disponíveis e os métodos para a manipulação do cubo.

Representação:

Ordem das faces:

   0
 2 5 3 4
   1

Ordem dos adesivos em cada face:

  2   5   8
  1   4   7
 [0]  3   6

Índices do estado (cada um começando com 9 * (n-1)):

                2   5   8
                1   4   7
               [0]  3   6
  20  23  26   47  50  53  29  32  35  38  41  44
  19  22  25   46  49  52  28  31  34  37  40  43
 [18] 21  24  [45] 48  51 [27] 30  33 [36] 39  42
               11  14  17
               10  13  16
               [9] 12  15

Cores (indices // 9):

                0   0   0
                0   0   0
                0   0   0
   2   2   2    5   5   5   3   3   3   4   4   4
   2   2   2    5   5   5   3   3   3   4   4   4
   2   2   2    5   5   5   3   3   3   4   4   4
                1   1   1
                1   1   1
                1   1   1

Atributos:

• state ndarray - Estado atual do cubo representado como um array de cores dos adesivos.
• GOAL ndarray - Estado final fixo representado como um array de cores dos adesivos.
• moves list - Lista de movimentos possíveis do cubo (face e direção).
• allow_wide bool - Flag que indica se movimentos largos (wide) são permitidos.
• max_depth int - A profundidade máxima de embaralhamento para o gerador de dados.
• sticker_target dict - Um dicionário que mapeia strings de movimento para listas de índices dos adesivos de destino.
• sticker_source dict - Um dicionário que mapeia strings de movimento para listas de índices dos adesivos de origem.
• sticker_target_ix ndarray - Um array numpy 2D que mapeia índices de movimento para os índices dos adesivos de destino para movimentos normais.
• sticker_source_ix ndarray - Um array numpy 2D que mapeia índices de movimento para os índices dos adesivos de origem para movimentos normais.
• sticker_target_ix_wide ndarray - Um array numpy 2D que mapeia índices de movimento para os índices dos adesivos de destino para movimentos largos (wide).
• sticker_source_ix_wide ndarray - Um array numpy 2D que mapeia índices de movimento para os índices dos adesivos de origem para movimentos largos (wide).

show

def show(
    flat=False,
    palette=["white", "yellow", "orange1", "red", "blue", "green"]
)

Exibe o estado atual do cubo.

Argumentos:

• flat bool - Se o estado deve ser exibido de forma planificada.
• palette list - Lista de cores para representar os adesivos.

validate

def validate(
    state=None,
    centered=True
)

Valida o estado e a disposição do cubo.

Argumentos:

• centered bool - Se os centros devem estar centralizados ou não.

Lança:

• ValueError - Se o estado ou a disposição do cubo for inválido.

reset

def reset()

Redefine o estado do cubo para o estado resolvido.

reset_axes

def reset_axes()

Redefine os índices de cor de acordo com as cores dos centros fornecidas. Útil quando movimentos largos (fat moves) são aplicados ou quando uma perspectiva inesperada é especificada.

is_solved

def is_solved()

Verifica se o cubo está no estado resolvido.

finger

def finger(move)

Aplica um único movimento no estado do cubo usando uma string de movimento.

Argumentos:

• move str - String de movimento na notação HTM.

finger_ix

def finger_ix(ix)

Aplica um único movimento usando seu índice para uma execução mais rápida que .finger. Verifica se o índice do movimento corresponde a um movimento normal (ix < 18) ou a um movimento largo (wide) e aplica a mudança de estado usando arrays de índices pré-calculados.

Argumentos:

• ix int - Índice do movimento a ser aplicado.

apply_scramble

def apply_scramble(scramble)

Aplica uma sequência de movimentos (embaralhamento) ao estado do cubo.

Argumentos:

• scramble str ou list - Sequência de movimentos na notação HTM ou em uma lista.

__iter__

def __iter__()

Cria um gerador infinito de estados embaralhados e sequências de solução.

Este método destina-se ao treinamento do modelo. A cada iteração, ele gera um novo embaralhamento aleatório de max_depth movimentos, evitando sequências de movimentos triviais. Ele produz o histórico de estados e o movimento correspondente que levou a cada estado.

Produz:

tuple[np.ndarray, np.ndarray]: Uma tupla contendo:

• X (np.ndarray): Um array (max_depth, 54) de estados do cubo.
• y (np.ndarray): Um array (max_depth,) de índices de movimento que geraram os estados.

__vectorize_moves

def __vectorize_moves()

Vetoriza as operações de substituição de grupos de adesivos para um cálculo mais rápido. Este método define self.sticker_target e self.sticker_source para gerenciar as cores dos adesivos (o destino é substituído pela origem). Eles definem os índices dos adesivos de destino e de origem para que os movimentos possam ser vetorizados.

Dataset

class Dataset(torch.utils.data.Dataset)

Classe de pseudo-dataset para produzir infinitamente embaralhamentos aleatórios.

Exemplo

batch_size = 1024
dl = get_dataloader(batch_size)
for i, (batch_x, batch_y) in zip(range(1000), dl):
    batch_x, batch_y = batch_x.to(device), batch_y.device().reshape(-1)

get_dataloader

def get_dataloader(
    batch_size,
    num_workers=min(os.cpu_count(), 32), max_depth=20,
    **dl_kwargs
)

Cria uma instância de DataLoader para gerar embaralhamentos aleatórios do Cubo de Rubik.

Argumentos:

• batch_size int - O número de amostras por lote.
• num_workers int, opcional - O número de processos de trabalho (workers) a serem usados para o carregamento de dados. O padrão é o número de núcleos da CPU ou 32 (além do qual o retorno diminuirá), o que for menor.
• max_depth int, opcional - A profundidade máxima dos embaralhamentos. O padrão é 20.
• **dl_kwargs - Argumentos de palavra-chave adicionais para passar ao construtor do DataLoader.

Retorna:

• torch.utils.data.DataLoader - Uma instância de DataLoader que produz lotes de embaralhamentos aleatórios.