doc tweaking

Author: derailed-dash

src/AoC_2024/Dazbo's_Advent_of_Code_2024.ipynb

@@ -64,7 +64,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 28,
+   "execution_count": 41,
    "metadata": {
     "id": "p5Ki_HvOJUWk",
     "tags": []
@@ -258,7 +258,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 31,
+   "execution_count": 44,
    "metadata": {
     "id": "lwP0r3BAaxjt",
     "tags": []
@@ -331,7 +331,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 32,
+   "execution_count": 45,
    "metadata": {
     "id": "Y6nbd6WMryWi",
     "tags": []
@@ -359,7 +359,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 33,
+   "execution_count": 46,
    "metadata": {
     "id": "A8sU4Ez_bBKl",
     "tags": []
@@ -529,7 +529,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 34,
+   "execution_count": 47,
    "metadata": {
     "id": "DT5FSYliC9wp",
     "tags": []
@@ -8963,7 +8963,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 37,
+   "execution_count": 50,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -9147,7 +9147,7 @@
     "\n",
     "E.g. we might need to do swaps like this:\n",
     "\n",
-    "<img src=\"https://aoc.just2good.co.uk/assets/images/gate-pairs.png\" width=\"480\" alt=\"Gate swaps\" />\n",
+    "<img src=\"https://aoc.just2good.co.uk/assets/images/gate-pairs.png\" width=\"420\" alt=\"Gate swaps\" />\n",
     "\n",
     "E.g. from:\n",
     "\n",
@@ -9229,11 +9229,11 @@
     "\n",
     "A single adder can be depicted like this:\n",
     "\n",
-    "<img src=\"https://aoc.just2good.co.uk/assets/images/1-bit-fa.png\" width=\"420\" alt=\"Full Adder\" />\n",
+    "<img src=\"https://aoc.just2good.co.uk/assets/images/1-bit-fa.png\" width=\"280px\" alt=\"Full Adder\" />\n",
     "\n",
     "So we can implement a multi-bit ripple adder like this:\n",
     "\n",
-    "<img src=\"https://aoc.just2good.co.uk/assets/images/ripple-adder.png\" width=\"420\" alt=\"Ripple Adder\" />\n",
+    "<img src=\"https://aoc.just2good.co.uk/assets/images/ripple-adder.png\" width=\"480px\" alt=\"Ripple Adder\" />\n",
     "\n",
     "And this is how we can generate a single 5-bit number from the addition of two 4-bit numbers.\n",
     "\n",
@@ -9250,42 +9250,42 @@
    "source": [
     "op_by_ouput = {}\n",
     "\n",
-    "def get_code_for_output(wire: str) -> str:\n",
+    "def get_code_for_wire(wire: str) -> str:\n",
     "    \"\"\" Generate a string representation of the logical operations needed \n",
     "    to compute the value of a given wire. Uses recursion to handle dependencies between operations. \"\"\"\n",
     "    \n",
     "    # Base case - exit once we have a wire that requires no further op to calculate\n",
-    "    if wire not in op_by_ouput:\n",
+    "    if wire not in op_by_ouput: # I.e. this wire is not the output of an operation\n",
     "        return wire\n",
     "    \n",
+    "    # Otherwise, get the operation required to output to this wire\n",
     "    left, right, gate = op_by_ouput[wire]\n",
     "    \n",
-    "    # Recursive calls\n",
     "    # If the left or right inputs are themselves the result of other operations, \n",
     "    # these recursive calls will generate the code for those operations first.\n",
-    "    left_code = get_code_for_output(left)\n",
-    "    right_code = get_code_for_output(right)\n",
-    "    \n",
-    "    # Prevents (a & b) and (b & a) from being different strings.\n",
-    "    left_code, right_code = sorted((left_code, right_code))\n",
+    "    # Sort so that (a & b) and (b & a) are the same.\n",
+    "    left_code, right_code = sorted((get_code_for_wire(left), get_code_for_wire(right)))\n",
     "    \n",
     "    match gate:\n",
-    "        case \"AND\":\n",
-    "            return f\"({left_code} & {right_code})\"\n",
-    "        case \"OR\":\n",
-    "            return f\"({left_code} | {right_code})\"\n",
-    "        case \"XOR\":\n",
-    "            return f\"({left_code} ^ {right_code})\"\n",
+    "        case \"AND\": gate_code = \"&\"\n",
+    "        case \"OR\": gate_code = \"|\"\n",
+    "        case \"XOR\": gate_code = \"^\"\n",
+    "\n",
+    "    return f\"({left_code} {gate_code} {right_code})\"\n",
     "        \n",
     "def create_vis(wires: dict):\n",
+    "    \"\"\" Creates a visual representation of a circuit using Graphviz. \"\"\"\n",
+    "    \n",
     "    dot = graphviz.Digraph(format='png', engine='dot')\n",
     "    \n",
-    "    # Define gate shapes, colors, and output styles\n",
+    "    # Define gate shapes, colors, and output styles for different types of gate\n",
     "    gate_styles = {\n",
     "        \"AND\": {\"shape\": \"invtrapezium\", \"fillcolor\": \"lightblue\"},\n",
     "        \"OR\": {\"shape\": \"invtriangle\", \"fillcolor\": \"lightgreen\"},\n",
     "        \"XOR\": {\"shape\": \"box\", \"fillcolor\": \"lightyellow\"},\n",
     "    }\n",
+    "    \n",
+    "    # Define styles for output nodes based on their initial character\n",
     "    output_styles = {\n",
     "        \"z\": {\"fillcolor\": \"black\", \"fontcolor\": \"white\"},\n",
     "        \"x\": {\"fillcolor\": \"blue\", \"fontcolor\": \"white\"},\n",
@@ -9301,7 +9301,7 @@
     "    for output in op_by_ouput:\n",
     "        left, right, gate = op_by_ouput[output]\n",
     "\n",
-    "        # Create gate node in a box\n",
+    "        # Create gate node\n",
     "        gate_label = f'{gate}'\n",
     "        gate_name = f'{left}_{right}_{gate}'  # Unique gate name\n",
     "        gate_style = gate_styles.get(gate, {\"shape\": \"box\"})\n",
@@ -9317,12 +9317,12 @@
     "\n",
     "        # Connect gate to output\n",
     "        output_style = output_styles.get(output[0], {}) \n",
-    "        dot.node(output, output, shape='circle', style='filled', **output_style)  # Output node as circle\n",
+    "        dot.node(output, output, shape='circle', style='filled', **output_style)\n",
     "        dot.edge(gate_name, output)\n",
     "\n",
     "    # Render the graph to a file\n",
     "    output_path = 'adder_operations'\n",
-    "    dot.render(f\"{locations.output_dir}/{output_path}\")  # Saves the output to 'circuit_graph.png'\n",
+    "    dot.render(f\"{locations.output_dir}/{output_path}\")  # Saves the output as a png\n",
     "    display(Image(f\"{locations.output_dir}/{output_path}.png\"))\n",
     "\n",
     "def visualise_operations(data: str):\n",
@@ -9331,10 +9331,11 @@
     "        for output in outputs:\n",
     "            op_by_ouput[output] = (left, right, gate)\n",
     "    \n",
+    "    # View text-based representation of all wires\n",
     "    for output in sorted(op_by_ouput.keys()):\n",
-    "        logger.info(f\"{output} = {get_code_for_output(output)}\")\n",
+    "        print(f\"{output} = {get_code_for_wire(output)}\")\n",
     "    \n",
-    "    create_vis(wires)\n",
+    "    create_vis(wires) # Create a graphical representation\n",
     "    \n",
     "soln = visualise_operations(input_data)"
    ]