Package: crossword-generator
MCTS Crossword GeneratorThis package provides a pure Python implementation for generating crosswords using
Monte Carlo Tree Search (MCTS).A good overview about the project can be found in thisblog post.The pip package can be found onPyPIQuickstartA: Install package:Create and activate a virtual environment based on Python >= 3.8Install crossword_generator package:pip install crossword_generatorB: Generate crossword with default settings:You can generate a crossword without providing any arguments.
This will fill a 4x5 layout without any black squares using words from an English dictionary.To do so, activate your virtual environment and chose one of the following (equivalent) options:Call application directly:crosswordExecute package:python -m crossword_generatorRun the main function in a python shell or your own script:>>> from crossword_generator import generate_crossword
>>> generate_crossword()For the next examples I assume you are using the first option to interact with the package.ExamplesTo get started and see which input formats are required, you can download someenglish(comma-separated) orgerman(semicolon-separated) sample data.Let's assume you have downloaded the sample files into a directory called "crossword_input" inside your working directory.A: Use your own layoutsIn order to use your own layouts, you will need to set argumentpath_to_layoutto a CSV file on your local machine.the CSV file must have an index column and a header rowpotential letters are marked with "_" (underscore)black squares are marked with "" (empty)Fill anempty 5x12 layout:crossword --path_to_layout "crossword_input/layout_5_12_empty.csv"Fill aprefilled 5x12 layout:crossword --path_to_layout "crossword_input/layout_5_12_prefilled.csv"Fill an entire NYT-style15x15 layout:crossword --path_to_layout "crossword_input/layout_15_15_empty.csv"Of course, you can also provide arguments from within your code:generate_crossword(
  path_to_layout="crossword_input/layout_15_15_empty.csv",
)B: Use your own wordsIn order to use your own set of words, you will need to set argumentpath_to_wordsto a CSV file (or pattern of CSV files) on your local machine.the CSV file(s) must contain a column named "answer" with the relevant wordsFill anempty 5x12 layoutwithwords from a listcrossword --path_to_layout "crossword_input/layout_5_12_empty.csv" --path_to_words "crossword_input/sample_words.csv"Again, you can do the same from within your code:generate_crossword(
  path_to_layout="crossword_input/layout_5_12_empty.csv",
  path_to_words="crossword_input/sample_words.csv",
)C: Other arguments you might want to play with:num_rows & num_cols [int]number of rows / columns the layout should havewill only be considered ifpath_to_layoutis not specifiedmax_num_words [int]limits the number of words to improve runtimemax_mcts_iterations [int]sets the maximum number of MCTS iterationscan be increased to get a better solution or decreased to improve runtimerandom_seed [int]change the seed to obtain different filled crosswordsoutput_path [str]if provided, save the final grid and a summary as CSV files into the provided directoryModulesoptimizer.pyscript that contains the main functiongenerate_crossword()layout_handler.pyProvides the layout that will later be filled with wordsNewLayoutHandler: creates a new layout from scratchExistingLayoutHandler: reads an existing layout from a CSV fileword_handler.pyProvides the words that will later be filled into the layoutDictionaryWordHandler: get words from NLTK corpusFileWordHandler: read words from CSV filesstate.pyEntry: class that represents the current state of one entry of the crosswordCrosswordState: class that represents the current state of whole crosswordtree_search.pyTreeNode: represents one node of the MCTS treeMCTS: represents the whole MCTS tree and provides all necessary functionalities such asSelectionExpansionSimulation / RolloutBackpropagationReferences & DependenciesThe MCTS implementation intree_search.pyis based on the algorithm provided bypbsinclair42,
which I adapted in several ways:Convert from 2-player to 1-player domainAdjust reward function + exploration termAdd additional methods to analyze the game treeUse PEP 8 code styleHave a look atpyproject.tomlfor a list of all required and optional dependenciesPython >= 3.8Required packagesnltk>=3.5pandas>=1.4.0numpy>=1.22.0tqdm>=4.41.0