~theonlymrcat/adventofcode

#TheOnlyMrCat's Advent of Code Solutions

All my solutions should be runnable with my run.rs script. Required dependencies are listed in flake.nix, if you can read Nix. And if you can read Nix, you probably already have Nix installed, so you can just use the dev shell provided by the flake.

My solutions generally print two lines, one for each part. Sometimes I have progress bars printed to stderr if I decided to brute force the solution. My solutions do pull in external dependencies, if I can figure out how to make them work with my run.rs. (e.g. Rust uses cargo -Zscript, Python has dependencies specified in the Nix flake)

#`run.rs`

Opinionated Advent of Code input fetcher and solution runner

Usage: run [OPTIONS] [FILE]...

Arguments:
  [FILE]...  The solution file(s) to execute (default: most recently modified)

Options:
  -y, --year <YEAR>            The year(s) to execute solution files from (default: all years)
  -d, --day <DAY>              The day(s) to execute solution files from (default: all days)
  -e, --extension <EXTENSION>  The file extension(s) of solutions to execute (default: all solutions)
  -i, --input <INPUT>          The input file to pass to the solution (default: fetches from adventofcode.com)
  -b, --bench                  Benchmark the solution
  -v, --visual                 Run a visualisation
  -s, --submit                 Submit answer to adventofcode.com
  -h, --help                   Print help

For the input-fetch and answer-submission features, your session cookie (excluding the leading session=) is expected to be in the SESSION env variable.

#Repository structure

run.rs expects and manages a directory structure similar to this repository:

.
+-- 2023
|   +-- 1
|   |   +-- input.txt
|   |   \-- solution.py
|   \-- 2
|       +-- input.txt
|       +-- visual.py
|       \-- solution.py
\-- 2024
    +-- 1
    |   +-- build
    |   |   \-- haskell
    |   |       +-- solution
    |   |       +-- solution.hi
    |   |       +-- solution.hs
    |   |       \-- solution.o
    |   +-- input.txt
    |   \-- solution.hs
    +-- 2
    |   +-- input.txt
    |   +-- solution.hs
    |   \-- solution.py
    \-- 3
        +-- input.txt
        +-- solution-parsec.hs
        \-- solution-regex.hs

Solution files are expected in {year}/{day}/solution{suffix}.{extension}. Solutions have to be prefixed with solution, and visualisations with visual for the script to recognise them automatically.

input.txt files, as well as build directories (for languages that need them) are generated by the script, and stored in their respective {year}/{day} directory.

#Benchmarking solutions

The benchmarker outputs a table that looks like this (example: 2023/19/solution.py):

 Solution phase | Mean ± σ           | Range              
==========================================================
          Start | 13.06 ms ± 1.61 ms | 9.73 ms – 16.82 ms 
          Parse | 1.12 ms ± 188.1 µs | 872.4 µs – 1.75 ms 
         Part 1 | 6.83 ms ± 1.46 ms  | 5.73 ms – 14.85 ms 
         Part 2 | 1.52 ms ± 231.4 µs | 1.29 ms – 3.00 ms

It distinguishes between phases of the solution cooperatively: the solution outputs marker escape sequences to stderr to inform the benchmarker when each phase has finished.

ESC 0 Start: The process/interpreter has finished initialising and we are executing solution code now
ESC 1 Parse: We've finished reading stdin, or at least the reusable part of it
ESC 2 Part 1: We've calculated the answer to part 1 and have printed it to stdout
ESC 3 Part 2: As above, for part 2

#Automation guidelines

This tool does follow the automation guidelines on the /r/adventofcode community wiki

Once inputs are downloaded, they are cached on the local filesystem (see get_input())
- If you suspect your input is corrupted, you can manually request a fresh copy by deleting the cached input.txt
The User-Agent header in const USER_AGENT is set to me since I maintain this tool :)

#Solution tiles

These tiles are clickable and lead to the solution of the corresponding day! They were generated by the script in AoCTiles/create_aoc_tiles.py, which comes from LiquidFun's Advent of Code repository.