animora 0.1.0__py3-none-any.whl

animora/__init__.py

@@ -0,0 +1,189 @@
+"""Animora: High-level declarative animation framework built on Manim.
+
+Democratizing the creation of high-quality educational, technical,
+mathematical, and algorithmic animations.
+"""
+
+from __future__ import annotations
+
+from animora.algorithms.backtracking import n_queens, n_queens_trace
+from animora.algorithms.dynamic_programming import fibonacci_dp, fibonacci_dp_trace
+from animora.algorithms.graph_traversal import bfs, bfs_trace, dfs, dfs_trace
+from animora.algorithms.pathfinding import (
+    a_star,
+    a_star_trace,
+    dijkstra,
+    dijkstra_trace,
+)
+from animora.algorithms.search import binary_search, binary_search_trace
+from animora.algorithms.sorting import (
+    bubble_sort,
+    bubble_sort_trace,
+    insertion_sort,
+    insertion_sort_trace,
+    merge_sort,
+    merge_sort_trace,
+    quick_sort,
+    quick_sort_trace,
+    selection_sort,
+    selection_sort_trace,
+)
+from animora.algorithms.trace import (
+    OperationStep,
+    OperationTrace,
+    OperationType,
+)
+from animora.components.arrow import Arrow
+from animora.components.connector import Connector
+from animora.components.group import Group
+from animora.components.label import Label
+from animora.components.panel import Panel
+from animora.components.shape import Shape, ShapeType
+from animora.components.text import Text
+from animora.core.animation import Animation
+from animora.core.component import Component
+from animora.core.config import BoundingBox, ComponentConfig
+from animora.core.scene import Scene
+from animora.datastructures.array import Array, ArrayListModel
+from animora.datastructures.bst import BST, BSTModel, BSTNode
+from animora.datastructures.graph import Graph, GraphModel
+from animora.datastructures.hash_table import HashEntry, HashTable, HashTableChainingModel
+from animora.datastructures.heap import Heap, HeapModel
+from animora.datastructures.linked_list import LinkedList, LinkedListModel, ListNode
+from animora.datastructures.queue import Queue, QueueModel
+from animora.datastructures.stack import Stack, StackModel
+from animora.datastructures.tree import GenericTreeModel, Tree, TreeNode
+from animora.dataviz.axes import Axes
+from animora.dataviz.bar_chart import BarChart
+from animora.dataviz.histogram import Histogram
+from animora.dataviz.line_chart import LineChart
+from animora.dataviz.scatter_plot import ScatterPlot
+from animora.dataviz.table import Table
+from animora.layout.base import BaseLayout, LayoutItem, LayoutResult
+from animora.layout.circular import CircularLayout
+from animora.layout.flow import FlowLayout
+from animora.layout.graph import GraphLayout
+from animora.layout.grid import GridLayout
+from animora.layout.horizontal import HorizontalLayout
+from animora.layout.tree import TreeLayout
+from animora.layout.vertical import VerticalLayout
+from animora.theme.builtin import (
+    Cyberpunk,
+    DefaultTheme,
+    ModernDark,
+    Monokai,
+    PaperLight,
+)
+from animora.theme.context import (
+    get_active_theme,
+    set_active_theme,
+    use_theme,
+)
+from animora.theme.theme import (
+    AnimationTiming,
+    ColorPalette,
+    CornerRadius,
+    SpacingScale,
+    StrokeScale,
+    Theme,
+    Typography,
+)
+
+__version__ = "0.1.0"
+
+__all__: list[str] = [
+    "BST",
+    "Animation",
+    "AnimationTiming",
+    "Array",
+    "ArrayListModel",
+    "Arrow",
+    "Axes",
+    "BSTModel",
+    "BSTNode",
+    "BarChart",
+    "BaseLayout",
+    "BoundingBox",
+    "CircularLayout",
+    "ColorPalette",
+    "Component",
+    "ComponentConfig",
+    "Connector",
+    "CornerRadius",
+    "Cyberpunk",
+    "DefaultTheme",
+    "FlowLayout",
+    "GenericTreeModel",
+    "Graph",
+    "GraphLayout",
+    "GraphModel",
+    "GridLayout",
+    "Group",
+    "HashEntry",
+    "HashTable",
+    "HashTableChainingModel",
+    "Heap",
+    "HeapModel",
+    "Histogram",
+    "HorizontalLayout",
+    "Label",
+    "LayoutItem",
+    "LayoutResult",
+    "LineChart",
+    "LinkedList",
+    "LinkedListModel",
+    "ListNode",
+    "ModernDark",
+    "Monokai",
+    "OperationStep",
+    "OperationTrace",
+    "OperationType",
+    "Panel",
+    "PaperLight",
+    "Queue",
+    "QueueModel",
+    "ScatterPlot",
+    "Scene",
+    "Shape",
+    "ShapeType",
+    "SpacingScale",
+    "Stack",
+    "StackModel",
+    "StrokeScale",
+    "Table",
+    "Text",
+    "Theme",
+    "Tree",
+    "TreeLayout",
+    "TreeNode",
+    "Typography",
+    "VerticalLayout",
+    "__version__",
+    "a_star",
+    "a_star_trace",
+    "bfs",
+    "bfs_trace",
+    "binary_search",
+    "binary_search_trace",
+    "bubble_sort",
+    "bubble_sort_trace",
+    "dfs",
+    "dfs_trace",
+    "dijkstra",
+    "dijkstra_trace",
+    "fibonacci_dp",
+    "fibonacci_dp_trace",
+    "get_active_theme",
+    "insertion_sort",
+    "insertion_sort_trace",
+    "merge_sort",
+    "merge_sort_trace",
+    "n_queens",
+    "n_queens_trace",
+    "quick_sort",
+    "quick_sort_trace",
+    "selection_sort",
+    "selection_sort_trace",
+    "set_active_theme",
+    "use_theme",
+]

animora/algorithms/__init__.py

@@ -0,0 +1,65 @@
+"""Algorithm visualizations and operation tracing for Animora.
+
+Provides educational animations and discrete operation traces for searching,
+sorting, graph traversals, pathfinding, dynamic programming, and backtracking.
+"""
+
+from __future__ import annotations
+
+from animora.algorithms.backtracking import n_queens, n_queens_trace
+from animora.algorithms.dynamic_programming import fibonacci_dp, fibonacci_dp_trace
+from animora.algorithms.graph_traversal import bfs, bfs_trace, dfs, dfs_trace
+from animora.algorithms.pathfinding import (
+    a_star,
+    a_star_trace,
+    dijkstra,
+    dijkstra_trace,
+)
+from animora.algorithms.search import binary_search, binary_search_trace
+from animora.algorithms.sorting import (
+    bubble_sort,
+    bubble_sort_trace,
+    insertion_sort,
+    insertion_sort_trace,
+    merge_sort,
+    merge_sort_trace,
+    quick_sort,
+    quick_sort_trace,
+    selection_sort,
+    selection_sort_trace,
+)
+from animora.algorithms.trace import (
+    OperationStep,
+    OperationTrace,
+    OperationType,
+)
+
+__all__: list[str] = [
+    "OperationStep",
+    "OperationTrace",
+    "OperationType",
+    "a_star",
+    "a_star_trace",
+    "bfs",
+    "bfs_trace",
+    "binary_search",
+    "binary_search_trace",
+    "bubble_sort",
+    "bubble_sort_trace",
+    "dfs",
+    "dfs_trace",
+    "dijkstra",
+    "dijkstra_trace",
+    "fibonacci_dp",
+    "fibonacci_dp_trace",
+    "insertion_sort",
+    "insertion_sort_trace",
+    "merge_sort",
+    "merge_sort_trace",
+    "n_queens",
+    "n_queens_trace",
+    "quick_sort",
+    "quick_sort_trace",
+    "selection_sort",
+    "selection_sort_trace",
+]

animora/algorithms/backtracking.py

@@ -0,0 +1,124 @@
+"""Backtracking algorithm visualization with animated state decision trees (N-Queens)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from animora.algorithms.trace import OperationTrace, OperationType
+from animora.core.animation import Animation
+from animora.dataviz.table import Table
+from animora.theme.context import get_active_theme
+
+if TYPE_CHECKING:
+    pass
+
+
+# -----------------------------------------------------------------------------
+# 1. Pure Algorithm Logic with Operation Tracing (Dual-Correctness)
+# -----------------------------------------------------------------------------
+def n_queens_trace(n: int = 4) -> tuple[list[list[int]], OperationTrace]:
+    """Solve N-Queens backtracking problem, recording placements and backtracks.
+
+    Returns (solutions, operation_trace) where each solution is a list of column
+    indices for each row.
+    """
+    trace = OperationTrace()
+    solutions: list[list[int]] = []
+    board: list[int] = [-1] * n
+
+    def _is_safe(row: int, col: int) -> bool:
+        for prev_row in range(row):
+            prev_col = board[prev_row]
+            # Column conflict or diagonal conflict
+            if prev_col == col or abs(prev_col - col) == abs(prev_row - row):
+                return False
+        return True
+
+    def _solve(row: int) -> None:
+        if row == n:
+            solutions.append(list(board))
+            trace.add_step(
+                OperationType.HIGHLIGHT,
+                f"Valid N-Queens solution found: {list(board)}",
+                targets=tuple(enumerate(board)),
+                solution=list(board),
+            )
+            return
+
+        for col in range(n):
+            trace.add_step(
+                OperationType.TRY_CHOICE,
+                f"Try placing Queen at row {row}, column {col}",
+                targets=(row, col),
+                row=row,
+                col=col,
+            )
+
+            if _is_safe(row, col):
+                board[row] = col
+                _solve(row + 1)
+                # Backtrack
+                board[row] = -1
+                trace.add_step(
+                    OperationType.BACKTRACK,
+                    f"Backtrack from row {row}, column {col}",
+                    targets=(row, col),
+                    row=row,
+                    col=col,
+                )
+            else:
+                trace.add_step(
+                    OperationType.BACKTRACK,
+                    f"Conflict detected at row {row}, column {col}",
+                    targets=(row, col),
+                    row=row,
+                    col=col,
+                )
+
+    _solve(0)
+    return solutions, trace
+
+
+# -----------------------------------------------------------------------------
+# 2. Animation Generator Orchestration
+# -----------------------------------------------------------------------------
+def n_queens(
+    n: int = 4,
+    table: Table | None = None,
+    run_time: float | None = None,
+) -> list[Animation]:
+    """Generate animations for N-Queens backtracking exploration."""
+    active_theme = get_active_theme()
+    duration = run_time or active_theme.timing.fast
+
+    _solutions, trace = n_queens_trace(n)
+    animations: list[Animation] = []
+
+    if table is not None:
+        for step in trace:
+            if step.op_type == OperationType.TRY_CHOICE:
+                r, c = step.targets
+                anim = table.animate_highlight_cell(
+                    r, c, color=active_theme.colors.warning, run_time=duration
+                )
+                animations.append(anim)
+            elif step.op_type == OperationType.BACKTRACK:
+                r, c = step.targets
+                anim = table.animate_highlight_cell(
+                    r, c, color=active_theme.colors.error, run_time=duration
+                )
+                animations.append(anim)
+            elif step.op_type == OperationType.HIGHLIGHT:
+                for r, c in step.targets:
+                    anim = table.animate_highlight_cell(
+                        r, c, color=active_theme.colors.success, run_time=duration
+                    )
+                    animations.append(anim)
+
+    return animations
+
+
+__all__ = [
+    "n_queens",
+    "n_queens_trace",
+]

animora/algorithms/dynamic_programming.py

@@ -0,0 +1,81 @@
+"""Dynamic Programming visualization with animated memoization table filling."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from animora.algorithms.trace import OperationTrace, OperationType
+from animora.core.animation import Animation
+from animora.dataviz.table import Table
+from animora.theme.context import get_active_theme
+
+if TYPE_CHECKING:
+    pass
+
+
+# -----------------------------------------------------------------------------
+# 1. Pure Algorithm Logic with Operation Tracing (Dual-Correctness)
+# -----------------------------------------------------------------------------
+def fibonacci_dp_trace(n: int) -> tuple[int, list[int], OperationTrace]:
+    """Compute N-th Fibonacci number using bottom-up DP, recording cell fills."""
+    if n < 0:
+        raise ValueError("n must be non-negative")
+    if n == 0:
+        trace = OperationTrace()
+        trace.add_step(OperationType.TABLE_FILL, "Base case: dp[0] = 0", targets=(0,), value=0)
+        return 0, [0], trace
+
+    dp = [0] * (n + 1)
+    dp[0] = 0
+    dp[1] = 1
+
+    trace = OperationTrace()
+    trace.add_step(OperationType.TABLE_FILL, "Base case: dp[0] = 0", targets=(0,), value=0)
+    trace.add_step(OperationType.TABLE_FILL, "Base case: dp[1] = 1", targets=(1,), value=1)
+
+    for i in range(2, n + 1):
+        dp[i] = dp[i - 1] + dp[i - 2]
+        trace.add_step(
+            OperationType.TABLE_FILL,
+            f"Compute dp[{i}] = dp[{i - 1}] ({dp[i - 1]}) + dp[{i - 2}] ({dp[i - 2]}) = {dp[i]}",
+            targets=(i,),
+            value=dp[i],
+            operand_a=dp[i - 1],
+            operand_b=dp[i - 2],
+        )
+
+    return dp[n], dp, trace
+
+
+# -----------------------------------------------------------------------------
+# 2. Animation Generator Orchestration
+# -----------------------------------------------------------------------------
+def fibonacci_dp(
+    n: int,
+    table: Table | None = None,
+    run_time: float | None = None,
+) -> list[Animation]:
+    """Generate animations filling a Table component cell-by-cell for DP Fibonacci."""
+    active_theme = get_active_theme()
+    duration = run_time or active_theme.timing.fast
+
+    _result, _dp_array, trace = fibonacci_dp_trace(n)
+    animations: list[Animation] = []
+
+    if table is not None:
+        for step in trace:
+            idx = step.targets[0]
+            if idx < table.num_cols:
+                # Row 1 is the DP values row (Row 0 is header)
+                anim = table.animate_highlight_cell(
+                    1, idx, color=active_theme.colors.success, run_time=duration
+                )
+                animations.append(anim)
+
+    return animations
+
+
+__all__ = [
+    "fibonacci_dp",
+    "fibonacci_dp_trace",
+]

animora/algorithms/graph_traversal.py

@@ -0,0 +1,125 @@
+"""Breadth-First Search (BFS) and Depth-First Search (DFS) graph traversals."""
+
+from __future__ import annotations
+
+from collections import deque
+from typing import TYPE_CHECKING, Any
+
+from animora.algorithms.trace import OperationTrace, OperationType
+from animora.core.animation import Animation
+from animora.datastructures.graph import Graph, GraphModel
+from animora.theme.context import get_active_theme
+
+if TYPE_CHECKING:
+    pass
+
+
+# -----------------------------------------------------------------------------
+# 1. Breadth-First Search (BFS)
+# -----------------------------------------------------------------------------
+def bfs_trace(graph_model: GraphModel, start: Any) -> tuple[list[Any], OperationTrace]:
+    """Execute BFS traversal on GraphModel, returning (visited_order, operation_trace)."""
+    visited_order: list[Any] = []
+    trace = OperationTrace()
+    visited: set[Any] = {start}
+    queue: deque[Any] = deque([start])
+
+    trace.add_step(OperationType.VISIT_NODE, f"Start BFS at node {start}", targets=(start,))
+    visited_order.append(start)
+
+    while queue:
+        u = queue.popleft()
+        for v in graph_model.neighbors(u):
+            trace.add_step(OperationType.HIGHLIGHT_EDGE, f"Explore edge ({u}, {v})", targets=(u, v))
+            if v not in visited:
+                visited.add(v)
+                visited_order.append(v)
+                queue.append(v)
+                trace.add_step(OperationType.VISIT_NODE, f"Visit node {v}", targets=(v,))
+
+    return visited_order, trace
+
+
+def bfs(graph: Graph, start: Any, run_time: float | None = None) -> list[Animation]:
+    """Generate animations for BFS on a Graph component."""
+    active_theme = get_active_theme()
+    duration = run_time or active_theme.timing.normal
+
+    _, trace = bfs_trace(graph.model, start)
+    animations: list[Animation] = []
+
+    for step in trace:
+        if step.op_type == OperationType.VISIT_NODE:
+            node = step.targets[0]
+            animations.append(
+                graph.animate_mark_visited(
+                    node, color=active_theme.colors.success, run_time=duration
+                )
+            )
+        elif step.op_type == OperationType.HIGHLIGHT_EDGE:
+            u, v = step.targets
+            animations.append(
+                graph.animate_highlight_edge(
+                    u, v, color=active_theme.colors.accent, run_time=duration
+                )
+            )
+
+    return animations
+
+
+# -----------------------------------------------------------------------------
+# 2. Depth-First Search (DFS)
+# -----------------------------------------------------------------------------
+def dfs_trace(graph_model: GraphModel, start: Any) -> tuple[list[Any], OperationTrace]:
+    """Execute DFS traversal on GraphModel, returning (visited_order, operation_trace)."""
+    visited_order: list[Any] = []
+    trace = OperationTrace()
+    visited: set[Any] = set()
+
+    def _dfs_rec(u: Any) -> None:
+        visited.add(u)
+        visited_order.append(u)
+        trace.add_step(OperationType.VISIT_NODE, f"Visit node {u}", targets=(u,))
+
+        for v in graph_model.neighbors(u):
+            trace.add_step(OperationType.HIGHLIGHT_EDGE, f"Explore edge ({u}, {v})", targets=(u, v))
+            if v not in visited:
+                _dfs_rec(v)
+
+    _dfs_rec(start)
+    return visited_order, trace
+
+
+def dfs(graph: Graph, start: Any, run_time: float | None = None) -> list[Animation]:
+    """Generate animations for DFS on a Graph component."""
+    active_theme = get_active_theme()
+    duration = run_time or active_theme.timing.normal
+
+    _, trace = dfs_trace(graph.model, start)
+    animations: list[Animation] = []
+
+    for step in trace:
+        if step.op_type == OperationType.VISIT_NODE:
+            node = step.targets[0]
+            animations.append(
+                graph.animate_mark_visited(
+                    node, color=active_theme.colors.success, run_time=duration
+                )
+            )
+        elif step.op_type == OperationType.HIGHLIGHT_EDGE:
+            u, v = step.targets
+            animations.append(
+                graph.animate_highlight_edge(
+                    u, v, color=active_theme.colors.accent, run_time=duration
+                )
+            )
+
+    return animations
+
+
+__all__ = [
+    "bfs",
+    "bfs_trace",
+    "dfs",
+    "dfs_trace",
+]