vodiboi-state-space-visualizer 0.1.6

A state space visualizing tool

A State Space Visualizer

The library provides an interactive visualizer for exploring the state spaces of various games and puzzles. Each game can be visualized with customizable parameters:

• 2048
  • Customize grid size
• Towers of Hanoi
  • Customize number of towers and number of disks
• Sliding block game
  • Customize grid size
• Klotski
  • Can customize initial block configuration
• Aztec Diamonds
  • Customize order

For each of the games, you can either color nodes in the state space using a game-specific "score" function or based on the probability masses from diffusion.

Setup

run

pip install --upgrade vodiboi-state-space-visualizer

If you intend to run the flet vizualizer, independently run

pip install flet-webview==0.1.0

If you are trying to run in a google colab notebook, instead add this to the top of your notebook:

!pip install --upgrade vodiboi-state-space-visualizer

Usage

Basic Usage

The general pattern for using the visualizer is:

1. Import the game and visualizer classes
2. Create a game instance with desired parameters
3. Create a visualizer instance
4. Launch the interactive interface

import flet as ft
from vodiboi_state_space_visualizer.games import Game2048
from vodiboi_state_space_visualizer.visualizers import FletStateSpaceVisualizer

def main(page: ft.Page):
    # Create a game instance
    game = Game2048(shape=(2, 2))
    
    # Create visualizer (verbose=False to suppress output)
    visualizer = FletStateSpaceVisualizer(
        verbose=False,
        is_directed=True,  # is_directed=False for undirected graph behavior
        diffusion_steps=50  # Number of steps for diffusion computation (default: 50)
    )
    
    # Build the UI
    visualizer.build_ui(page, game)

# Run the app
ft.app(target=main)

Jupyter Notebook Usage

For Jupyter notebooks, use the JupyterStateSpaceVisualizer:

from vodiboi_state_space_visualizer.games import Game2048
from vodiboi_state_space_visualizer.visualizers import JupyterStateSpaceVisualizer
# If you are using google colab, you need the below lines to allow for widgets:
from google.colab import output
output.enable_custom_widget_manager()

# Create a game and visualizer
game = Game2048(shape=(2, 2))
visualizer = JupyterStateSpaceVisualizer(
    verbose=False,  # verbose=True for status messages
    is_directed=True,  # is_directed=False for undirected graph behavior
    diffusion_steps=50  # Number of steps for diffusion computation (default: 50)
)

# Launch the visualization
visualizer.visualize(game)

Available Games

2048

Visualize the state space of the 2048 game with customizable grid dimensions.

from vodiboi_state_space_visualizer.games import Game2048

# 2x2 grid (default)
game = Game2048(shape=(2, 2))

Towers of Hanoi

Classic Towers of Hanoi puzzle with configurable number of disks and towers.

from vodiboi_state_space_visualizer.games import TowersOfHanoi

# 4 disks, 3 towers (classic)
game = TowersOfHanoi(num_disks=3, num_towers=3)

Sliding Block Puzzle

from vodiboi_state_space_visualizer.games import SlidingBlockPuzzle

# 2x2 sliding puzzle (4-puzzle)
game = SlidingBlockPuzzle(shape=(2, 2))

# 3x3 sliding puzzle (8-puzzle)
game = SlidingBlockPuzzle(shape=(3, 3))

Klotski

Traditional Klotski block puzzle with different layout configurations.

from vodiboi_state_space_visualizer.games import Klotski

# Original Klotski layout
game = Klotski(layout="Original Klotski")

# Alternatively, (easier to visualize) Medium Layout
game = Klotski(layout="Original Klotski")

# Use with reachable states only for performance
visualizer = FletStateSpaceVisualizer(ALL_STATES=False)

Snake

Snake game state space visualization.

from vodiboi_state_space_visualizer.games import Snake

# 3x3 grid
game = Snake(shape=(3, 3))

Aztec Diamond

Aztec Diamond tiling visualizations.

from vodiboi_state_space_visualizer.games import AztecDiamond

# Order 3 Aztec Diamond
game = AztecDiamond(n=3)

Abstract Graph

Allows you to visualize any graph with support for custom node coloring.

from vodiboi_state_space_visualizer.games import AbstractGraph
import networkx as nx

# Basic usage with a random graph
G = nx.erdos_renyi_graph(10, 0.3)
game = AbstractGraph(G)

# Custom coloring via parameter
custom_colors = {0: 10.0, 1: 20.0, 2: 30.0}  # Node -> color value
game = AbstractGraph(G, custom_coloring=custom_colors)

# Custom coloring via NetworkX node attributes  
nx.set_node_attributes(G, {0: 5.0, 1: 15.0}, 'color')
game = AbstractGraph(G)  # Automatically detects 'color' attribute

# Additional customization
node_labels = {0: "Start", 1: "Middle", 2: "End"}
edge_weights = {(0, 1): 2.0, (1, 2): 1.5}
game = AbstractGraph(G, 
                    node_labels=node_labels,
                    edge_weights=edge_weights, 
                    custom_coloring=custom_colors,
                    initial_node=0)

Custom Coloring Features:

• Pass custom_coloring dict mapping nodes to color values
• Or use NetworkX 'color' node attribute
• Both visualizers automatically use custom colors
• Colorbar title changes to "Custom Color" when enabled
• Hover text includes color information

Visualizer Options

The FletStateSpaceVisualizer accepts several customization parameters:

visualizer = FletStateSpaceVisualizer(
    node_size=4,              # Size of nodes in the graph
    all_edge_width=1,         # Width of edges
    all_edge_opacity=0.08,    # Opacity of edges
    layout_seed=23,           # Random seed for layout
    ignore_leaves=True,       # Whether to ignore leaf nodes
    ALL_STATES=True,          # Use all states vs reachable only
    colorscale='Plasma',      # Color scheme for visualization
    dimension=3               # 2D or 3D visualization
)

Complete Example

Here's a complete example that creates an interactive 2048 visualizer:

import flet as ft
from vodiboi_state_space_visualizer.games import Game2048
from vodiboi_state_space_visualizer.visualizers import FletStateSpaceVisualizer

def run_2048_visualizer():
    def main(page: ft.Page):
        page.title = "2048 State Space Visualizer"
        
        # Create 2x2 2048 game
        game = Game2048(shape=(2, 2))
        
        # Create visualizer with custom settings
        visualizer = FletStateSpaceVisualizer(
            node_size=6,
            colorscale='Viridis',
            dimension=3,
            diffusion_steps=75  # Custom diffusion computation steps
        )
        
        # Build and display the UI
        visualizer.build_ui(page, game)
    
    ft.app(target=main)

if __name__ == "__main__":
    run_2048_visualizer()

Configuration Options

Graph Directionality

Both visualizers support an is_directed parameter that affects how diffusion coloring and random moves work:

• is_directed=True (default): Treats the state space graph as directed

  • Diffusion follows edge directions (probability flows only in the direction of allowed moves)
  • Random moves in Jupyter visualizer only follow outgoing edges from current node
  • More realistic for most games where moves are not reversible

• is_directed=False: Treats the state space graph as undirected

  • Diffusion becomes bidirectional (probability flows in both directions)
  • Random moves can traverse edges in either direction
  • Useful for analyzing symmetric or reversible game mechanics

# Directed behavior (default) - realistic game flow
visualizer = JupyterStateSpaceVisualizer(is_directed=True)

# Undirected behavior - symmetric analysis
visualizer = JupyterStateSpaceVisualizer(is_directed=False)

Diffusion Steps

The diffusion_steps parameter controls how many iterations the diffusion simulation runs when computing probability distributions:

• Higher values (e.g., 100, 200): More accurate probability convergence, but slower computation
• Lower values (e.g., 20, 30): Faster computation, but may not fully converge
• Default: 50: Good balance between accuracy and speed for most use cases

# Fast computation - good for large graphs or quick exploration
visualizer = JupyterStateSpaceVisualizer(diffusion_steps=20)

# High accuracy - for final analysis or research
visualizer = JupyterStateSpaceVisualizer(diffusion_steps=200)

# Default balanced approach
visualizer = JupyterStateSpaceVisualizer(diffusion_steps=50)

Features

• Interactive State Space: Click on nodes to explore different game states
• Multiple Coloring Modes: Color nodes by game score or diffusion probability
• Game Controls: Use move buttons to navigate through the game
• 3D/2D Visualization: Switch between 2D and 3D graph layouts
• Real-time Updates: See how your moves affect the state space in real-time

The visualizer opens in a web browser window and provides an interactive interface where you can:

• Explore the complete state space graph of the game
• Click on nodes to see the corresponding game state
• Use game controls to make moves and see transitions
• Toggle between different coloring schemes
• Restart or use "luck mode" for random exploration