chore: more descriptive docstrings

Author: mbrickerd

_2025/solutions/day09.py

@@ -1,11 +1,14 @@
-"""Boilerplate solution template for Advent of Code daily challenges.
+r"""Day 9: Movie Theater
 
-This module provides a template class for solving Advent of Code puzzle problems.
-It includes a base structure with two method stubs (part1 and part2) that can be
-implemented for specific day's challenges.
+This module provides the solution for Advent of Code 2025 - Day 9
 
-The template follows the SolutionBase pattern used across the Advent of Code solutions,
-allowing for consistent handling of input parsing and solution execution.
+It finds the largest axis-aligned rectangle that can be formed in a tile grid
+using red tiles as opposite corners (Part 1), then extends the search to allow
+rectangles that include both red and \"green\" tiles (Part 2).
+
+The module contains a Solution class that inherits from SolutionBase and
+implements coordinate compression, flood fill, and rectangle validation
+to efficiently search the space of candidate rectangles.
 """
 
 from collections import deque
@@ -14,43 +17,48 @@
 
 
 class Solution(SolutionBase):
-    """Solution template for Advent of Code daily puzzle.
+    """Find largest valid rectangles in a movie theater tile grid.
 
-    This class provides a standardized structure for implementing solutions to
-    daily Advent of Code challenges. It inherits from SolutionBase and includes
-    method stubs for part1 and part2 of the puzzle.
+    The input is a list of coordinates where tiles are red. Part 1 treats the
+    rest of the grid as unconstrained and finds the largest possible rectangle
+    using any two red tiles as opposite corners. Part 2 connects the red tiles
+    into a loop of red+green tiles and flood-fills the interior to mark all
+    green tiles, then searches for the largest rectangle that only contains
+    red or green tiles.
 
-    Subclasses should override these methods with specific implementation logic
-    for parsing input and solving the puzzle requirements.
+    Coordinate compression is used to keep the grid small, and a brute-force
+    rectangle search is combined with a grid mask to validate candidate areas.
     """
 
     def part1(self, data: list[str]) -> int:
-        """Solve the first part of the daily puzzle.
+        r"""Find largest rectangle area using two red tiles as opposite corners.
+
+        For every pair of red tiles that differ in both x and y, this method
+        computes the area of the axis-aligned rectangle they define and tracks
+        the maximum. The actual grid size does not matter due to the use of
+        red tile coordinates only.
 
         Args:
-            data: List of input strings to be processed
+            data: List of \"X,Y\" strings representing red tile positions
 
         Returns
         -------
-            int: Solution for part 1 of the puzzle
+            int: Largest rectangle area using two red tiles as opposite corners
         """
         tiles = [tuple(map(int, line.split(","))) for line in data]
 
         if len(tiles) < 2:
             return 0
 
-        # Coordinate compression ("space distortion")
+        # Coordinate compression (space distortion)
         xs = sorted({x for x, _ in tiles})
         ys = sorted({y for _, y in tiles})
 
         x_to_idx = {x: i for i, x in enumerate(xs)}
         y_to_idx = {y: i for i, y in enumerate(ys)}
 
-        # Compressed positions of red tiles
         compressed_tiles: list[tuple[int, int]] = [(x_to_idx[x], y_to_idx[y]) for x, y in tiles]
 
-        # Group tiles by compressed row/column if you want small pruning later
-        # but the brute-force over all pairs is already fine for AoC sizes.
         max_area = 0
         n = len(compressed_tiles)
 
@@ -79,35 +87,45 @@ def part1(self, data: list[str]) -> int:
         return max_area
 
     def part2(self, data: list[str]) -> int:
-        """Solve the second part of the daily puzzle.
+        r"""Find largest rectangle area using only red and green tiles.
+
+        First, the red tiles are connected in input order with axis-aligned
+        segments forming a loop; these segments become green tiles. Then, a
+        flood fill from the outside marks all empty tiles reachable from the
+        boundary as \"outside\". Any remaining empty tiles inside the loop are
+        also marked green. Finally, the method checks all red-opposite-corner
+        rectangles and keeps the largest whose interior contains only red or
+        green tiles (no empty tiles).
 
         Args:
-            data: List of input strings to be processed
+            data: List of \"X,Y\" strings representing red tile positions in loop order
 
         Returns
         -------
-            int: Solution for part 2 of the puzzle
+            int: Largest rectangle area that uses red tiles as opposite corners
+                and includes only red or green tiles inside
         """
         tiles = [tuple(map(int, line.split(","))) for line in data if line.strip()]
 
         if len(tiles) < 2:
             return 0
 
+        # Coordinate compression
         xs = sorted({x for x, _ in tiles})
         ys = sorted({y for _, y in tiles})
         x_to_idx = {x: i for i, x in enumerate(xs)}
-        y_to_idx = {y: i for i, y in tiles}
         y_to_idx = {y: i for i, y in enumerate(ys)}
         compressed = [(x_to_idx[x], y_to_idx[y]) for x, y in tiles]
 
         w, h = len(xs), len(ys)
-        grid = [[0] * w for _ in range(h)]  # 0 = empty, 1 = red, 2 = green
+        # 0 = empty, 1 = red, 2 = green
+        grid = [[0] * w for _ in range(h)]
 
         # Mark red tiles
         for cx, cy in compressed:
             grid[cy][cx] = 1
 
-        # Draw green boundary segments between consecutive reds (wrap)
+        # Draw green boundary segments between consecutive reds (wrap around)
         n = len(compressed)
         for i in range(n):
             x1, y1 = compressed[i]
@@ -123,19 +141,22 @@ def part2(self, data: list[str]) -> int:
                     if grid[y1][x] == 0:
                         grid[y1][x] = 2
             else:
-                raise ValueError("Non axis-aligned segment in input")
+                err_msg = "Non axis-aligned segment in input"
+                raise ValueError(err_msg)
 
         # Flood-fill outside empty cells
         outside = [[False] * w for _ in range(h)]
         q: deque[tuple[int, int]] = deque()
 
+        # Seed flood fill from outer boundary
         for x in range(w):
             if grid[0][x] == 0:
                 outside[0][x] = True
                 q.append((x, 0))
             if grid[h - 1][x] == 0:
                 outside[h - 1][x] = True
                 q.append((x, h - 1))
+
         for y in range(h):
             if grid[y][0] == 0:
                 outside[y][0] = True
@@ -158,6 +179,7 @@ def part2(self, data: list[str]) -> int:
                 if grid[y][x] == 0 and not outside[y][x]:
                     grid[y][x] = 2
 
+        # Search for largest valid rectangle (only red/green inside)
         max_area = 0
         n = len(compressed)
 

_2025/tests/test_09.py

@@ -1,19 +1,18 @@
-"""Test suite for Advent of Code daily challenge solution.
+"""Test suite for Day 9: Movie Theater
 
-This module contains the test cases for the solution to the Advent of Code
-daily puzzle. It uses the TestSolutionUtility to run tests for both parts
-of the challenge.
+This module contains tests for the Day 9 solution, which finds the largest
+rectangles in a movie theater tile grid using red tiles as opposite corners.
+The tests verify:
 
-The template provides a structure for defining tests for a specific day's
-solution, ensuring that the implementation meets the expected outputs for
-given test inputs.
+1. Part 1: Largest rectangle area using any two red tiles as opposite corners
+2. Part 2: Largest rectangle area using only red and green tiles
 """
 
 from aoc.models.tester import TestSolutionUtility
 
 
 def test_day09_part1() -> None:
-    """Test the solution for Part 1 of the daily puzzle.
+    """Test finding largest rectangle using red tiles as opposite corners.
 
     This test runs the solution for Part 1 of the puzzle against the
     provided test input and compares the result with the expected output.
@@ -28,7 +27,7 @@ def test_day09_part1() -> None:
 
 
 def test_day09_part2() -> None:
-    """Test the solution for Part 2 of the daily puzzle.
+    """Test finding largest rectangle using only red and green tiles.
 
     This test runs the solution for Part 2 of the puzzle against the
     provided test input and compares the result with the expected output.