slidingpuzzle.nn package

Submodules

slidingpuzzle.nn.dataset module

Utilities for creating, saving, and loading board datasets.

class SlidingPuzzleDataset(examples: Iterable[tuple[tuple[tuple[int, ...], ...], list[int]]])

build_or_load_dataset(h: int, w: int, num_examples: int | None = None, examples_file: str | None = None, **kwargs) → SlidingPuzzleDataset

Loads examples, constructs a SlidingPuzzleDataset from them, and returns it. If there is a mismatch between the requested num_examples and the loaded examples file, examples may be truncated or new examples may be constructed and saved to disk. No duplicate examples are produced.

Parameters:

• h – The height of the board to locate a dataset for

• w – The width of the board to locate a dataset for

• num_examples – The total number of examples desired. If there are too many, examples will be truncated. If there are too few, new examples will be constructed. If None, the entire dataset loaded will be used.

• examples_file – The name of the examples file to save or load.

• kwargs – Will be forwaded to make_examples() if it is called.

Returns:

A dataset for the requested puzzle size.

generate_examples(h: int, w: int, start: int = 0, stop: int | None = None) → list[tuple[tuple[tuple[int, ...], ...], list[int]]]

Helper to generate all training examples for a board size by performing reverse BFS.

Note

It is safe to interrupt this function any time with a keyboard interrupt and receive back the examples generated so far.

Parameters:

• h – Height of the board

• w – Width of the board

• start – Start index (0 starts at the initial solved board)

• stop – Index to stop at (None will product all boards)

Returns:

A list of examples.

get_examples(h: int, w: int, num_examples: int, prior_examples: list[tuple[tuple[tuple[int, ...], ...], list[int]]], **kwargs) → list[tuple[tuple[tuple[int, ...], ...], list[int]]]

Returns num_examples total unique examples, starting with prior_examples if they are provided. May truncate or produce new examples as necessary.

load_dataset(h: int, w: int, examples_file: str | None = None) → SlidingPuzzleDataset

Loads examples, constructs a SlidingPuzzleDataset from them, and returns it.

Parameters:

• h – The height of the board to locate a dataset for

• w – The width of the board to locate a dataset for

• examples_file – Path to file. Default will check local datasets directory.

Returns:

A dataset for the requested puzzle size.

load_examples(h: int, w: int, examples_file: str | None = None) → list[tuple[tuple[tuple[int, ...], ...], list[int]]]

Loads examples from a JSON file.

random_examples(h: int, w: int, num_examples: int, ignore_examples: list[tuple[tuple[tuple[int, ...], ...], list[int]]] | None = None, **kwargs) → list[tuple[tuple[tuple[int, ...], ...], list[int]]]

Constructs a list of training examples, which are tuples of:

(board, solution)

Parameters:

• h – Height of board.

• w – Width of board.

• num_examples – Number of examples to produce.

• ignore_examples – If any example produced matches one in ignore_examples, it will be discarded.

• kwargs – Args to pass to the search algorithm used to find board solutions.

Returns:

The list of training examples.

save_examples(examples: list[tuple[tuple[tuple[int, ...], ...], list[int]]], examples_file: str | None = None) → None

Save a list of examples to disk as JSON.

slidingpuzzle.nn.eval module

Module used to evaluate model performance vs. other heuristics.

accuracy(expected, predicted) → float

Helper function to estimate accuracy of sliding puzzle model outputs. This function replaces NaNs/infinities with 0s and uses:

\[f(e, p) = 1 - \frac{|e - p|}{1 + |e - p|}\]

It returns the sum along the batch dimension.

Notes

Any NaNs/infs will be replaced by 0.

Parameters:

• expected – A tensor with the expected value

• predicted – A tensor with the predicted value

Returns:

The accuracy as a float in the range [0, 1] summed along batch dim.

eval_checkpoint(model: Module, tag: str = 'acc', num_iters: int | None = None, device: str | None = None, **kwargs) → float

Loads the provided model from the checkpoint at epoch and runs evaluate, returning the result. If epoch is not provided, the latest checkpoint is used.

eval_heuristic(dataset: SlidingPuzzleDataset, heuristic: Callable[[ndarray[Any, dtype[_ScalarType_co]]], int | float]) → float

Runs all examples through heuristic and evaluates accuracy as a function of heuristic proximity to the true distance. Can be used to compare model performance against other heuristics.

evaluate(model: Module, criterion, dataset: Dataset) → tuple[float, float]

Runs the model on provided datatset computing average loss and accuracy.

Parameters:

• model – Model to evaluate

• criterion – The criterion function to use for evaluation

• dataset – The dataset of examples

Returns:

A tuple(avg. loss, avg. accuracy)

slidingpuzzle.nn.heuristics module

Defines neural network-guided heuristics.

get_heuristic(h: int, w: int, version: str) → Callable[[ndarray[Any, dtype[_ScalarType_co]]], int | float]

get_heuristic_key(h: int, w: int, version: str)

make_heuristic(model: Module | ScriptModule)

set_heuristic(model: Module | ScriptModule)

v1_distance(board: ndarray[Any, dtype[_ScalarType_co]]) → float

A neural network that estimates distance to goal

Parameters:

board – The board

Returns:

An estimated number of moves to reach the goal

v2_distance(board: ndarray[Any, dtype[_ScalarType_co]]) → float

A neural network that estimates distance to goal

Parameters:

board – The board

Returns:

An estimated number of moves to reach the goal

slidingpuzzle.nn.models module

Defines a PyTorch model to evaluate sliding puzzle boards.

class Model_v1(h: int, w: int)

A stack of linear layers that accepts a board as input and outputs the estimated distance to the goal.

Trained with:

SGD(lr = 0.001, momentum = 0.9)
MSELoss

Total parameters: 1322496

forward(x)

Defines the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

class Model_v2(h: int, w: int)

A multi-headed attention-based network with about the same number of parameters as v1. (WIP)

Trained with:

SGD(lr = 0.0001, momentum = 0.9)
MSELoss

Total parameters: 1170767

forward(x)

Defines the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

get_num_params(model: Module) → int

Compute the total number of parameters in a model.

Parameters:

model – A model

Returns:

The total number of trainable parameters

load_model(h: int, w: int, version: str, device: str | None = None) → ScriptModule

Reload a pre-trained frozen model.

save_model(model: Module, device: str | None = None) → None

Save a frozen version of the model into the “models” dir.

Parameters:

• model – The trained model.

• device – The device the model is currently loaded on. If not provied, it will be guessed.

slidingpuzzle.nn.paths module

Utilities for dealing with paths required during model training and inference.

clear_training(h: int, w: int) → None

Removes checkpoints and tensorboard logs.

get_board_size_str(h: int, w: int) → str

Helper to get a string encoding height and width.

get_checkpoint_dir(h: int, w: int) → Path

Get the path to store checkpoints for this board size.

Parameters:

• h – Board height

• w – Board width

Returns:

The checkpoint dir path

get_checkpoint_path(h: int, w: int, tag: str) → Path

Get the path to a checkpoint, given a board size and optional tag.

Parameters:

• h – Board height

• w – Board width

• tag – Checkpoint tag to load

Returns:

The path to the checkpoint file

get_examples_path(h: int, w: int) → Path

get_log_dir(h: int, w: int) → Path

get_model_path(h: int, w: int, version: str) → Path

get_path(dirname: str | Path, filename: str | Path) → Path

Creates intermediate directorys for dirname and returns the full path from dirname to filename.

Parameters:

• dirname – A directory or path to a directory.

• filename – The filename the path will point to.

Returns:

The path object.

slidingpuzzle.nn.train module