Add module doc for some puzzles, tidy up.

11.py

@@ -1,5 +1,18 @@
 #!/usr/bin/python3
 
+"""Solution for day 11 of Advent of Code 2016.
+
+Performs a breadth-first search of possible moves. Because of the "elevator stops at each floor to charge" mechanic,
+moves are treated as up or down a single floor.
+
+To avoid backtracking, a set of previously visited states is maintained. Before being recorded, each state is
+'serialised' by stripping away the element names in a deterministic manner. This is because a puzzle with a
+Foo-generator and Bar-chip on floor 1 and a Bar-generator and Foo-chip on floor 2, has an identical solution to
+a puzzle with a Bar-Generator and Foo-chip on floor 1, and a Foo-generator and Bar-chip on floor 2. That is, the
+elements don't matter, just the relative positions of the pairs. This dramatically reduces the number of states
+that have to be checked.
+"""
+
 import itertools, re
 
 # Marker used to show the position of the lift
@@ -33,8 +46,7 @@ items = lambda floor: set(floor) - {lift}
 pickups = lambda items: map(set, itertools.chain(itertools.combinations(items, 2), itertools.combinations(items, 1)))
 
 # Returns an enumeration of possible destinations for the lift (up or down one floor)
-dests = lambda layout: filter(is_floor, [my_floor_index(layout) + 1, my_floor_index(layout) - 1])
-is_floor = lambda i: 0 <= i < len(floors)
+dests = lambda layout: filter(lambda i: 0 <= i < len(floors), [my_floor_index(layout) + 1, my_floor_index(layout) - 1])
 
 # Returns an enumeration of possible moves that could be made from the given state
 moves = lambda layout: itertools.product(pickups(items(my_floor(layout))), dests(layout))
@@ -78,16 +90,15 @@ def run(floors):
             if valid_layout(new_layout):
                 serialised = serialise(new_layout)
                 if serialised not in distances:
-                    distances[serialised] = steps
+                    distances.add(serialised)
                     queued.append(new_layout)
                     if target(new_layout):
-
                         return False
         return queued
 
     # Run repeated iterations until we hit a winning result, then immediately returns the step
     # count.
-    distances = {serialise(floors): 0}
+    distances = {serialise(floors)}
     step = 1
     queued = [floors]
     while True:

12.py

@@ -1,30 +1,40 @@
 #!/usr/bin/python3
 
+"""Solution for day 12 of Advent of Code 2016.
+
+Models a simple virtual machine. Each of the four operations is defined as a method, and called using reflection.
+The current line number is kept in a special 'pc' (for 'program counter') register, which means that each operation is
+a simple mutation of a register.
+
+All values are handled by first trying to parse the input as an integer; if that fails then it is treated as a register
+name and the value of the register is returned. This allows any argument to be numerical or a register, not just those
+shown int he question example.
+"""
+
+
 with open('data/12.txt', 'r') as file:
     instr = list(map(str.split, map(str.strip, file.readlines())))
 
-def value(x):
-    try:
-        return int(x)
-    except ValueError:
-        return registers[x]
+def run(values):
+    registers = values
+    registers['pc'] = 0
 
-def cpy(args): registers[args[1]] = value(args[0])
-def inc(args): registers[args[0]] += 1
-def dec(args): registers[args[0]] -= 1
-def jnz(args): registers['pc'] += 0 if value(args[0]) == 0 else value(args[1]) - 1
+    def value(x):
+        try:
+            return int(x)
+        except ValueError:
+            return registers[x]
+
+    def cpy(args): registers[args[1]] = value(args[0])
+    def inc(args): registers[args[0]] += 1
+    def dec(args): registers[args[0]] -= 1
+    def jnz(args): registers['pc'] += 0 if value(args[0]) == 0 else value(args[1]) - 1
 
-def run():
     while registers['pc'] < len(instr):
-        globals()[instr[registers['pc']][0]](instr[registers['pc']][1:])
+        locals()[instr[registers['pc']][0]](instr[registers['pc']][1:])
         registers['pc'] += 1
 
-registers = {'a': 0, 'b': 0, 'c': 0, 'd': 0, 'pc': 0}
-run()
-
-print("Stage 1: %s" % registers['a'])
-
-registers = {'a': 0, 'b': 0, 'c': 1, 'd': 0, 'pc': 0}
-run()
+    return registers['a']
 
-print("Stage 2: %s" % registers['a'])
+print("Stage 1: %s" % run({'a': 0, 'b': 0, 'c': 0, 'd': 0}))
+print("Stage 2: %s" % run({'a': 0, 'b': 0, 'c': 1, 'd': 0}))

13.py

@@ -1,5 +1,11 @@
 #!/usr/bin/python3
 
+"""Solution for day 13 of Advent of Code 2016.
+
+Performs a breadth-first search of the maze, for up to 100 steps. Distances of each square are kept in a dictionary,
+which is also used to prevent back-tracking.
+"""
+
 import itertools
 
 input = 1364
@@ -9,19 +15,13 @@ wall = lambda x, y: high(x*x + 3*x + 2*x*y + y + y*y + input) % 2 == 1
 all_moves = lambda x, y: [(x-1, y), (x+1, y), (x, y-1), (x, y+1)]
 moves = lambda x, y: (m for m in all_moves(x, y) if m[0] >= 0 and m[1] >= 0 and not wall(*m))
 queue = {(1, 1)}
-visited = set()
 distance = {}
-steps = 0
-
-while steps < 100:
-	for c in queue:
-		if c not in distance:
-			distance[c] = steps
 
-	visited = visited.union(queue)
-	next_queue = set(itertools.chain.from_iterable(moves(*c) for c in queue)) - visited
-	queue = next_queue
-	steps += 1
+for step in range(100):
+    # Merge in all the new distances from the queue, if they're not present
+    distance = dict(list(distance.items()) + list(dict.fromkeys(queue, step).items()))
+    # Calculate all moves from all places in the queue, and skip any places we've already visited
+    queue = set(itertools.chain.from_iterable(moves(*c) for c in queue)) - set(distance.keys())
 
 print("Part 1: %s" % distance[(31, 39)])
 print("Part 2: %s" % sum(1 for s in distance.values() if s <= 50))

14.py

@@ -1,5 +1,18 @@
 #!/usr/bin/python3
 
+"""Solution for day 14 of Advent of Code 2016.
+
+The actual logic for this solution is contained in the matches lambda, which returns an infinite-length generator
+containing all of the matching hashes. The implementation is very basic, calling the hash functions and triple-digit
+matcher multiple times for the same inputs. This avoids having to manually keep a second list of hashes to check for
+five letter matches.
+
+To avoid the massive slowness that would happen if we recomputed up to 1,000 hashes each step, the hash methods (and
+triple-finding method) themselves are cached using functools.lru_cache. The caches can hold 1024 entries, so
+comfortably hold the results of the 1,000 hash look-forward.
+"""
+
+
 import functools
 import hashlib
 import itertools

15.py

@@ -1,5 +1,16 @@
 #!/usr/bin/python3
 
+"""Solution for day 15 of Advent of Code 2016.
+
+To simplify a lot of the logic in this solution, disc positions are offset according to their position. So if we have
+discs that start at positions [0, 1, 2] at t=0, when calculating positions the entry for t=0 will read [1, 3, 5]
+because the first disc will have moved one position before the capsule reaches it, the second disc two positions,
+and so on.
+
+Offsetting the positions means that a successful solution is represented as [0, 0, 0] instead of [n, n-1, n-2] etc.
+The latter case becomes particularly ugly when you consider that the discs may wrap around at different places.
+"""
+
 import itertools
 import re
 
@@ -21,7 +32,7 @@ def run(lines):
     combos = zip(*map(positions, discs))
 
     # Find a time when all discs will be at position 0 for the arrival of the capsule.
-    times = (i for i, c in enumerate(combos) if all(p == 0 for p in c))
+    times = (i for i, c in enumerate(combos) if not(sum(c)))
     return next(times)
 
 with open('data/15.txt', 'r') as file:

16.py

@@ -1,5 +1,11 @@
 #!/usr/bin/python3
 
+"""Solution for day 16 of Advent of Code 2016.
+
+This is a straightforward, brute-searching solution. It expands the input as defined in the puzzle, and then
+computes checksums until it finds an odd-length one.
+"""
+
 import itertools
 
 

17.py

@@ -1,5 +1,12 @@
 #!/usr/bin/python3
 
+"""Solution for day 17 of Advent of Code 2016.
+
+Implements an A* search algorithm for finding the shortest path (which wasn't really necessary given part two!)
+The heapq module is used to keep the queue sorted in priority order, with the priorities calculated as the
+current distance travelled plus the Manhattan distance to the end (so the first path found will be the shortest).
+"""
+
 import functools
 import hashlib
 import heapq