chore: consistent docstrings

Author: mbrickerd

_2024/solutions/day22.py

@@ -1,9 +1,17 @@
 """Day 22: Monkey Market
 
-This module provides the solution for Day 22 of Advent of Code 2024.
+This module provides the solution for Advent of Code 2024 - Day 22.
 
-It solves a puzzle about analyzing secret codes and price patterns
-in a monkey marketplace.
+It solves a puzzle about analyzing pseudorandom secret number sequences and
+price patterns in a monkey marketplace. Buyers use secret numbers to generate
+prices, and finding optimal price change sequences maximizes banana earnings.
+
+The solution involves simulating pseudorandom number generation through bitwise
+operations (XOR and modulo), tracking price changes across multiple buyers, and
+identifying the most profitable sequence of four consecutive price changes.
+
+The module contains a Solution class that inherits from SolutionBase and
+implements methods to transform secret numbers and analyze price patterns.
 """
 
 from collections import defaultdict
@@ -13,49 +21,50 @@
 
 
 class Solution(SolutionBase):
-    """Solution for the Monkey Market puzzle.
+    """Analyze secret numbers and price patterns in the monkey marketplace.
+
+    This solution implements pseudorandom number analysis:
+    - Part 1: Calculate sum of secret numbers after 2000 transformations
+    - Part 2: Find optimal price change sequence across all buyers
 
-    Methods
-    -------
-        part1: Calculate the sum of transformed secret codes.
-        part2: Find the highest value pattern in price sequences.
+    The solution uses bitwise operations (XOR) and modulo arithmetic to generate
+    pseudorandom sequences, then analyzes price patterns to maximize profits.
     """
 
     rounds: int = 2000
 
     def transform_secret(self, secret: int) -> int:
-        """Transform a secret code through a series of bitwise operations.
+        """Transform a secret number through bitwise operations.
 
-        The transformation consists of three steps:
-        1. Multiply the secret by 64, XOR with the original secret, and take modulo 16777216.
-        2. Integer divide the result by 32, XOR with the previous result, and take modulo 16777216.
-        3. Multiply the result by 2048, XOR with the previous result, and take modulo 16777216.
-
-        The modulo operation ensures that the secret code remains within the range [0, 16777215].
+        Applies three sequential transformations using multiplication, division,
+        XOR (mix), and modulo (prune) operations. Each step mixes a calculated
+        value into the secret using XOR, then prunes the result using modulo
+        16777216 to keep values in range.
 
         Args:
-            secret: The secret code to be transformed.
+            secret (int): The secret number to transform
 
         Returns
         -------
-            The transformed secret code.
+            Transformed secret number after applying all three steps
         """
         secret = ((secret * 64) ^ secret) % 16777216
         secret = ((secret // 32) ^ secret) % 16777216
         return ((secret * 2048) ^ secret) % 16777216
 
     def part1(self, data: list[str]) -> int:
-        """Calculate the sum of transformed secret codes.
+        """Calculate sum of secret numbers after 2000 transformations.
 
-        Processes each input value through the specified number of rounds using the
-        `transform_secret` method.
+        Processes each initial secret number through 2000 rounds of transformation,
+        then sums all final secret values. This simulates the pseudorandom number
+        generation for each buyer over a full day.
 
         Args:
-            data: List of strings containing initial secret codes.
+            data (list[str]): List of strings containing initial secret numbers
 
         Returns
         -------
-            Sum of all transformed secret values.
+            Sum of all secret numbers after 2000 transformation rounds
         """
         secrets = []
         for secret in map(int, data):
@@ -67,20 +76,19 @@ def part1(self, data: list[str]) -> int:
         return sum(secrets)
 
     def part2(self, data: list[str]) -> int:
-        """Find the highest value pattern in price sequences.
-
-        Generates price sequences by applying the `transform_secret` method to each input value
-        and taking the modulo 10 of the result to get price digits.
+        """Find the price change sequence that maximizes total bananas.
 
-        Analyzes sequences of 4 consecutive price changes and finds the pattern that leads to
-        the highest subsequent price.
+        Generates price sequences for each buyer by taking the ones digit of
+        transformed secret numbers. Analyzes all possible sequences of four
+        consecutive price changes and identifies which sequence yields the
+        highest total price across all buyers when they first encounter it.
 
         Args:
-            data: List of strings containing initial secret codes.
+            data (list[str]): List of strings containing initial secret numbers
 
         Returns
         -------
-            Maximum price value associated with any 4-change pattern.
+            Maximum total bananas obtainable from any four-change sequence
         """
         prices = []
         for secret in map(int, data):

_2024/solutions/day23.py

@@ -1,9 +1,18 @@
 """Day 23: LAN Party
 
-Analyze player connections and find gaming groups in a network.
+This module provides the solution for Advent of Code 2024 - Day 23.
 
-This module solves a puzzle about identifying gaming configurations
-based on network connections and group composition rules.
+It solves a puzzle about identifying groups of interconnected computers at a
+LAN party. The puzzle involves finding sets of computers that are all directly
+connected to each other (cliques) and locating the Chief Historian based on
+computer naming patterns.
+
+The solution uses graph theory to analyze network connections, finding both
+small gaming groups (trios) that include specific computers and the largest
+possible fully-connected group representing the actual LAN party location.
+
+The module contains a Solution class that inherits from SolutionBase and
+implements methods using NetworkX to find cliques in the connection graph.
 """
 
 from itertools import combinations
@@ -14,32 +23,30 @@
 
 
 class Solution(SolutionBase):
-    """Solution for Advent of Code 2024 - Day 23: LAN Party.
-
-    This class solves a puzzle about analyzing LAN party connections and finding
-    gaming groups. Part 1 identifies valid gaming trios including teachers, while
-    Part 2 finds the largest possible gaming group.
-
-    Input format:
-        - List of connections, one per line
-        - Each line contains two node IDs separated by a hyphen
-        - Node IDs starting with 't' represent teachers
-        - All other nodes represent students
-        - Connections indicate which players can directly play together
+    """Analyze computer networks and find LAN party groups using graph theory.
+
+    This solution implements clique detection algorithms:
+    - Part 1: Count trios of interconnected computers with Chief Historian hint
+    - Part 2: Find the largest fully-connected group (maximum clique)
+
+    The solution uses NetworkX graph library to model the network and efficiently
+    find all cliques, which represent groups of computers that can all directly
+    communicate with each other.
     """
 
     def construct_graph(self, data: list[str]) -> nx.Graph:
-        """Construct a NetworkX graph from the input connection data.
+        """Construct an undirected graph from connection data.
 
-        Creates an undirected graph where nodes represent players and edges
-        represent possible direct connections for gaming.
+        Creates a NetworkX graph where nodes represent computers and edges
+        represent direct network connections between them. Each connection
+        is bidirectional.
 
         Args:
-            data: List of strings, each containing two node IDs separated by a hyphen
+            data (list[str]): List of connection strings in format "id1-id2"
 
         Returns
         -------
-            NetworkX Graph object representing the connection network
+            NetworkX Graph object representing the computer network
         """
         graph: nx.Graph = nx.Graph()
         edges = []
@@ -50,20 +57,18 @@ def construct_graph(self, data: list[str]) -> nx.Graph:
         return graph
 
     def part1(self, data: list[str]) -> int:
-        """Count valid gaming trios that include at least one teacher.
+        """Count sets of three interconnected computers including the Chief Historian.
 
-        Analyzes the connection graph to find all possible groups of three
-        players that:
-        1. Are fully connected (form a clique)
-        2. Include at least one teacher (node starting with 't')
-        3. Can play together based on direct connections
+        Finds all groups of three computers that are fully connected (each computer
+        connected to the other two) and include at least one computer whose name
+        starts with 't' (indicating the Chief Historian's potential location).
 
         Args:
-            data: List of strings representing player connections
+            data (list[str]): List of connection strings representing the network
 
         Returns
         -------
-            Number of unique valid gaming trios
+            Number of unique trios containing at least one computer starting with 't'
         """
         graph = self.construct_graph(data)
         teacher_cliques = [
@@ -82,19 +87,18 @@ def part1(self, data: list[str]) -> int:
         )
 
     def part2(self, data: list[str]) -> str:
-        """Find the largest possible gaming group.
+        """Find the password by identifying the largest LAN party group.
 
-        Identifies the maximum clique in the connection graph, representing
-        the largest group of players that can all play together directly.
-        Returns the players in alphabetical order as a comma-separated string.
+        Locates the maximum clique in the network graph, representing the largest
+        set of computers where every computer is directly connected to every other
+        computer. Returns the sorted computer names as a comma-separated password.
 
         Args:
-            data: List of strings representing player connections
+            data (list[str]): List of connection strings representing the network
 
         Returns
         -------
-            Comma-separated string of player IDs in the largest gaming group,
-            sorted alphabetically
+            Password string of alphabetically sorted computer IDs joined by commas
         """
         graph = self.construct_graph(data)
         largest_clique = max(nx.find_cliques(graph), key=len)