Framework-LED-Matrix 0.1.1__py3-none-any.whl

framework_led_matrix/simulations/HardyPomeauPazzis.py

@@ -0,0 +1,241 @@
+#!/usr/bin/env python3
+
+"""
+hpp_lga_model.py
+
+Implements the HPP (Hardy-Pomeau-Pazzis) Lattice Gas Automaton (LGA)
+for the 34x9 LED matrix, using the cellpylib library.
+
+This automaton models fluid dynamics using 4-bit particle states
+and specific collision/propagation rules. It is NOT a totalistic
+automaton and requires a custom 'apply_rule' function.
+"""
+
+import cellpylib as cpl
+import numpy as np
+import time
+import random
+from typing import List, Optional
+from framework_led_matrix.core.led_commands import log, clear_graph, WIDTH, HEIGHT, draw_matrix_on_board, reset_modules
+
+# --- HPP Particle States (Bitmasks) ---
+# A cell's state is the bitwise OR of the particles it contains.
+EMPTY      = 0b0000  # 0
+W_PARTICLE = 0b0001  # 1 (West-moving)
+E_PARTICLE = 0b0010  # 2 (East-moving)
+S_PARTICLE = 0b0100  # 4 (South-moving)
+N_PARTICLE = 0b1000  # 8 (North-moving)
+
+# --- HPP Collision States ---
+# These are the only two states that result in a collision
+WE_COLLIDE = W_PARTICLE | E_PARTICLE # 3 (West + East)
+NS_COLLIDE = N_PARTICLE | S_PARTICLE # 12 (North + South)
+
+
+def draw_hpp_board(board: List[List[int]], which: str):
+    """
+    Converts the 16-state HPP board to a regular matrix
+    (0-1) and draws it.
+    """
+    matrix = [[0 for _ in range(WIDTH)] for _ in range(HEIGHT)]
+    for r in range(HEIGHT):
+        for c in range(WIDTH):
+            state = board[r][c]
+            if state != EMPTY:
+                matrix[r][c] = 1  # Occupied
+            else:
+                matrix[r][c] = 0  # Empty
+    draw_matrix_on_board(matrix, which)
+
+
+def hpp_collide(state: int) -> int:
+    """
+    Computes the post-collision state for a single HPP cell.
+    This is the first half of the HPP rule.
+    """
+    # N+S collision (12)
+    if state == NS_COLLIDE: 
+        return WE_COLLIDE  # Becomes E+W (3)
+        
+    # E+W collision (3)
+    if state == WE_COLLIDE:
+        return NS_COLLIDE  # Becomes N+S (12)
+        
+    # All other states (0, 1, 2, 4, 5, 6, 7, 8, 9, 10, 11, 13, 14, 15)
+    # pass through unchanged.
+    return state
+
+
+def hpp_lga_rule(neighbourhood: np.ndarray, c_coord: tuple, t: int) -> int:
+    """
+    The HPP rule function for cellpylib's evolve2d.
+    This is the "Propagation" step. It calculates the new state of
+    the center cell (1,1) by "gathering" all particles that will
+    propagate *into* it from its 4 neighbors' *post-collision* states.
+    
+    Args:
+        neighbourhood: The 2D (3x3) NumPy array (Moore neighborhood).
+        c_coord (tuple): The (row, col) coordinate (unused).
+        t (int): The current timestep (unused).
+    """
+    
+    # 1. Get the pre-collision state of the 4 neighbors we care about.
+    north_cell_pre_collide = neighbourhood[0, 1]
+    south_cell_pre_collide = neighbourhood[2, 1]
+    east_cell_pre_collide  = neighbourhood[1, 2]
+    west_cell_pre_collide  = neighbourhood[1, 0]
+    
+    # 2. Compute the post-collision state for each neighbor.
+    # This determines what particles are *available to move*
+    n_post_collide = hpp_collide(north_cell_pre_collide)
+    s_post_collide = hpp_collide(south_cell_pre_collide)
+    e_post_collide = hpp_collide(east_cell_pre_collide)
+    w_post_collide = hpp_collide(west_cell_pre_collide)
+    
+    # 3. "Gather" the particles that will arrive at the center cell.
+    
+    # The new North particle comes from the South neighbor's post-collision North particle.
+    from_south = s_post_collide & N_PARTICLE
+    
+    # The new South particle comes from the North neighbor's post-collision South particle.
+    from_north = n_post_collide & S_PARTICLE
+    
+    # The new West particle comes from the East neighbor's post-collision West particle.
+    from_east = e_post_collide & W_PARTICLE
+    
+    # The new East particle comes from the West neighbor's post-collision East particle.
+    from_west = w_post_collide & E_PARTICLE
+    
+    # The new state of the center cell is the bitwise OR 
+    # of all particles that have propagated into it.
+    new_center_state = from_north | from_south | from_east | from_west
+    
+    return new_center_state
+
+
+def create_hpp_board_np(density: float = 0.5, initial_state: Optional[np.ndarray] = None) -> np.ndarray:
+    """
+    Creates a new random board for the HPP model, or uses a provided one.
+    
+    If initial_state is provided, it is used directly.
+    If initial_state is None, a new random board is generated
+    based on the density.
+    """
+    if initial_state is not None:
+        #take initial board, provide random particles movements
+        for r in range(HEIGHT):
+            for c in range(WIDTH):
+                if initial_state[r, c] != EMPTY:
+                    #random particle type to the occupied cell
+                    initial_state[r, c] = random.choice([W_PARTICLE, E_PARTICLE, S_PARTICLE, N_PARTICLE])
+        return initial_state
+
+    log(f"HPP: Creating new NumPy board with particle density {density}")
+    board = np.full((HEIGHT, WIDTH), EMPTY, dtype=int)
+    
+    total_cells = WIDTH * HEIGHT
+    num_particles = int(total_cells * density)
+    
+    # Get a list of all possible single-particle states
+    particle_types = [W_PARTICLE, E_PARTICLE, S_PARTICLE, N_PARTICLE]
+    
+    # Get a list of unique cells to populate
+    cells_to_populate = random.sample(
+        [(r, c) for r in range(HEIGHT) for c in range(WIDTH)], 
+        num_particles
+    )
+    
+    for r, c in cells_to_populate:
+        # Assign a random particle type to the chosen cell
+        board[r, c] = random.choice(particle_types)
+        
+    log(f"HPP: Seeded board with {num_particles} random particles.")
+    return board
+
+
+def run_hpp_simulation(
+    initial_state: Optional[np.ndarray] = None,
+    density: float = 0.5,
+    timesteps: int = 500,
+    delay_sec: float = 0.1,
+    which: str = 'both'
+):
+    """
+    Runs the HPP Lattice Gas Automaton simulation using cellpylib.
+    """
+    log(f"HPP: Starting simulation. density={density}, steps={timesteps}")
+    
+    # Use the create function, which respects the initial_state override
+    initial_state_2d = create_hpp_board_np(density, initial_state)
+    
+    # Wrap in 3D array for cellpylib's evolve2d function
+    initial_state_3d = np.array([initial_state_2d]) 
+    
+    log(f"HPP: Evolving {timesteps} steps...")
+    
+    # Evolve the cellular automaton
+    all_generations = cpl.evolve2d(
+        cellular_automaton=initial_state_3d,
+        timesteps=timesteps,
+        neighbourhood='Moore', # We need N,S,E,W neighbors
+        apply_rule=hpp_lga_rule,
+        r=1 # Radius 1
+    )
+    
+    log(f"HPP: Evolution complete. Result shape: {all_generations.shape}")
+    
+    try:
+        stable_counter = 0
+        total_frames = all_generations.shape[0]
+
+        for i in range(total_frames):            
+            current_board_np = all_generations[i]            
+            current_board_list = current_board_np.tolist()            
+            
+            # Draw the state to the LED matrix
+            draw_hpp_board(current_board_list, which)
+            time.sleep(delay_sec)
+            
+            if i % 20 == 0 or i == total_frames - 1:
+                log(f"HPP: Step {i}/{timesteps}.")
+
+            # Check for stable state (gridlock or empty)
+            if i > 0:
+                if np.array_equal(current_board_np, all_generations[i-1]):
+                    stable_counter += 1
+                else:
+                    stable_counter = 0
+            
+            if stable_counter >= 20:
+                log("HPP: State stable for 20 steps. Halting.")
+                time.sleep(2)
+                break
+                
+    except KeyboardInterrupt:
+        log("HPP: KeyboardInterrupt received, stopping.")
+    finally:
+        log(f"HPP: simulation finished.")
+        clear_graph()
+        log("HPP: cleared display.")
+
+def run_test_hpp():
+    """
+    Test function to run a sample HPP simulation.
+    """
+    matrix = [[0 for _ in range(WIDTH)] for _ in range(HEIGHT)]
+    matrix[HEIGHT // 2][WIDTH // 2] = N_PARTICLE | S_PARTICLE
+    matrix[HEIGHT // 2][(WIDTH // 2) - 1] = E_PARTICLE | W_PARTICLE
+    board = create_hpp_board_np(initial_state=np.array(matrix))
+    try:
+        run_hpp_simulation(
+            initial_state=board,
+            density=0.3, 
+            timesteps=200, 
+            delay_sec=0.05, 
+            which='both'
+        )
+    finally:
+        reset_modules()
+
+if __name__ == "__main__":
+    run_test_hpp()

framework_led_matrix/simulations/inner_totalistic.py

@@ -0,0 +1,47 @@
+import numpy as np
+import cellpylib as cpl
+from framework_led_matrix.core.led_commands import log, WIDTH, HEIGHT
+
+
+
+def create_simple_state(k: int = 2, val: int = 1) -> np.ndarray:
+    """Creates a 2D (HEIGHT, WIDTH) array of zeros with a single 'val' at the center."""
+    log(f"CPL Helpers: Creating simple center-seed state (val={val})")
+    board = np.zeros((HEIGHT, WIDTH), dtype=int)
+    board[HEIGHT // 2, WIDTH // 2] = val
+    return board
+
+def run_totalistic_ca(initial_state: np.ndarray, timesteps: int, rule_number: int) -> np.ndarray:
+    """
+    Runs a k=2 (binary) totalistic CA for 'timesteps'.
+    
+    The rule is based on the *sum* of the 8 'Moore' neighbors + center.
+    'rule_number' is the NKS-style rule number for k=2.
+    
+    Returns:
+        A 3D NumPy array of shape (timesteps + 1, HEIGHT, WIDTH)
+    """
+    k = 2
+    log(f"Totalistic CA (k=2): Running (rule={rule_number}) for {timesteps} steps.")
+    
+    rule_func = lambda n, c_coord, t: cpl.totalistic_rule(n, k=k, rule=rule_number)
+    
+    initial_state_3d = np.array([initial_state])
+    
+    all_generations = cpl.evolve2d(
+        cellular_automaton=initial_state_3d,
+        timesteps=timesteps,
+        neighbourhood='Moore',
+        apply_rule=rule_func
+    )
+    return all_generations
+
+
+if __name__ == "__main__":
+    # Test block
+    log("--- Testing Totalistic CA ---")
+    init_state = create_simple_state(k=3, val=1)
+    # Rule 777 is a 3-color replicator
+    history = run_totalistic_ca(init_state, timesteps=50, rule_number=777)
+    log(f"History shape: {history.shape}")
+    log("Test complete.")

framework_led_matrix/simulations/outer_totalistic.py

@@ -0,0 +1,112 @@
+import numpy as np
+import cellpylib as cpl
+from framework_led_matrix.core.led_commands import log, WIDTH, HEIGHT, coordinates_to_matrix
+
+STARTING_STATES_GOF = {
+    "blinker": coordinates_to_matrix([[17, 3], [17, 4], [17, 5]]),
+    "toad": coordinates_to_matrix([[17, 3], [17, 4], [17, 5], [18, 2], [18, 3], [18, 4]]),
+    "pentadecathlon": coordinates_to_matrix([
+        [12, 4], [13, 4], [14, 2], [14, 4], [14, 6], [15, 4], [16, 4],
+        [17, 4], [18, 4], [19, 2], [19, 4], [19, 6], [20, 4], [21, 4]
+    ]),
+    "glider": coordinates_to_matrix([[1, 2], [2, 3], [3, 1], [3, 2], [3, 3]]),
+    "lwss": coordinates_to_matrix([
+        [17, 3], [17, 5], [18, 2], [19, 2], [19, 5],
+        [20, 2], [20, 3], [20, 4], [20, 5]
+    ]),
+    "r_pentomino": coordinates_to_matrix([[17, 4], [17, 5], [18, 3], [18, 4], [19, 4]]),
+    "diehard": coordinates_to_matrix([
+        [17, 7], [18, 1], [18, 2], [19, 2], [19, 5], [19, 6], [19, 7]
+    ]),
+    "acorn": coordinates_to_matrix([
+        [17, 2], [18, 4], [19, 1], [19, 2], [19, 5], [19, 6], [19, 7]
+    ]),
+    "block": coordinates_to_matrix([[17, 3], [17, 4], [18, 3], [18, 4]]),
+    "beehive": coordinates_to_matrix([[17, 3], [17, 4], [18, 2], [18, 5], [19, 3], [19, 4]]),
+    "r_pentomino": coordinates_to_matrix([[17, 4], [17, 5], [18, 3], [18, 4], [19, 4]]),
+    "rabbit": coordinates_to_matrix([[17, 3], [17, 4], [18, 2], [18, 5], [19, 5], [20, 5]])
+}
+
+
+game_of_life_rules = {
+    'Original': {'B': [3], 'S': [2, 3]},
+    'HighLife': {'B': [3, 6], 'S': [2, 3]},
+    'Day & Night': {'B': [3, 6, 7, 8], 'S': [3, 4, 6, 7, 8]},
+    'Seeds': {'B': [2], 'S': []},
+}
+
+NAMED_RULES = {
+    "Life": ([3], [2, 3]),
+    "HighLife": ([3, 6], [2, 3]),
+    "Day & Night": ([3, 6, 7, 8], [3, 4, 6, 7, 8]),
+    "Seeds": ([2], []),
+    "Maze": ([3], [1, 2, 3, 4, 5]),
+}
+    
+
+def run_outer_totalistic_ca(
+    initial_state: np.ndarray, 
+    timesteps: int, 
+    b_rule: list[int], 
+    s_rule: list[int]
+) -> np.ndarray:
+    """
+    Runs a general binary Outer-Totalistic (B/S) CA for 'timesteps'.
+    This is the system used by Conway's Game of Life.
+    
+    Args:
+        initial_state: The 2D (H, W) NumPy array to start with.
+        timesteps: The number of generations to evolve.
+        b_rule: A list of neighbor counts to "Birth" a dead cell (e.g., [3]).
+        s_rule: A list of neighbor counts to "Survive" a live cell (e.g., [2, 3]).
+    
+    Returns:
+        A 3D NumPy array of shape (timesteps + 1, HEIGHT, WIDTH)
+    """
+    log(f"Outer-Totalistic CA: Running B{b_rule}/S{s_rule} for {timesteps} steps.")
+    
+    # Use sets for fast 'in' lookups
+    b_set = set(b_rule)
+    s_set = set(s_rule)
+    
+    def outer_totalistic_rule(neighbourhood: np.ndarray, c_coord: tuple, t: int) -> int:
+        """
+        The custom 'apply_rule' function that implements B/S logic.
+        
+        Args:
+            neighbourhood: The 2D (3x3) NumPy array (Moore neighborhood).
+            c_coord (tuple): The (row, col) coordinate (unused).
+            t (int): The current timestep (unused).
+        """
+        
+        # Get the 8-neighbor sum (total sum - center cell)
+        neighbor_sum = np.sum(neighbourhood) - neighbourhood[1, 1]
+        
+        # Get the center cell's current state
+        center_val = neighbourhood[1, 1]
+        
+        if center_val == 1:
+            # Cell is ALIVE, check SURVIVAL rule
+            if neighbor_sum in s_set:
+                return 1  # Survive
+            else:
+                return 0  # Die
+        else:
+            # Cell is DEAD, check BIRTH rule
+            if neighbor_sum in b_set:
+                return 1  # Born
+            else:
+                return 0  # Stay dead
+                
+    # Wrap initial state into a 3D array (shape [1, H, W])
+    initial_state_3d = np.array([initial_state])
+    
+    # Evolve and return the history
+    all_generations = cpl.evolve2d(
+        cellular_automaton=initial_state_3d,
+        timesteps=timesteps,
+        neighbourhood='Moore', # B/S rules require the 8-neighbor Moore
+        apply_rule=outer_totalistic_rule
+    )
+    return all_generations
+

framework_led_matrix/utils/anagrams.py

@@ -0,0 +1,39 @@
+from framework_led_matrix.simulations.outer_totalistic import run_outer_totalistic_ca
+from framework_led_matrix.core.led_commands import start_animation, stop_animation, reset_modules, log
+from framework_led_matrix.utils.text_rendering import draw_text_vertical
+import nltk
+import time
+
+def ensure_nltk_words():
+    """Ensures the 'words' corpus is downloaded."""
+    try:
+        nltk.data.find('corpora/words')
+    except (LookupError, AttributeError):
+        log("NLTK 'words' corpus not found. Downloading...")
+        nltk.download('words', quiet=True)
+
+def draw_anagram_on_matrix(word: str, which: str = 'both', animate: bool = True):
+    """Draws an anagram of the given word on the LED matrix."""
+    log(f"draw_anagram_on_matrix: start word='{word}' which={which}")
+    ensure_nltk_words()
+    ana_lst = anagrams(word)
+    ana_lst.add(word)
+    ana_lst = list(ana_lst)
+    log(f"draw_anagram_on_matrix: will render {len(ana_lst)} strings: {ana_lst}")
+    for w in ana_lst:
+        log(f"draw_anagram_on_matrix: rendering '{w}' on matrix (vertical)")
+        draw_text_vertical(w, which=which)
+        log(f"draw_anagram_on_matrix: rendered '{w}', toggling animation briefly")
+        stop_animation()
+        time.sleep(2)
+        start_animation() if animate else stop_animation()
+        time.sleep(5)
+    log("draw_anagram_on_matrix: finished rendering all anagrams, resetting modules")
+    reset_modules()
+
+def anagrams(word):
+    log(f"anagrams: finding anagrams for '{word}'")
+    word_sorted = sorted(word)
+    result = set(w for w in words.words() if sorted(w) == word_sorted)
+    log(f"anagrams: found {len(result)} candidates")
+    return result