Skip to content

xlm.tasks.maze.generate

Generate the maze-planning datasets from the Insertion Process paper.

The implementation follows Appendix D.1 of "Variational Learning for Insertion-based Generation" and the recursive-division listing in FlexMDM. The paper does not publish its generator or exact easy/medium/hard settings, so the tier defaults in this module are explicit, reproducible choices.

Each dataset repository contains one fixed maze. Examples contain:

  • path: a valid trajectory represented by flattened cell indices;
  • subgoals: an ordered subset of cells that the path visits; and
  • subgoal_pos: the corresponding positions in path.

Run python -m xlm.tasks.maze.generate --help for the CLI.

TierConfig dataclass

Published and inferred difficulty controls for one dataset tier.

perfect_maze(maze_size, seed=2025)

Generate the recursive-division base maze on a (2m+1)-square grid.

imperfect_maze(grid, door_fraction=0.3, seed=2025)

Open a fraction of walls separating two passages to create cycles.

braided_maze(grid, braid_fraction=1.0, seed=2025)

Remove walls at a fraction of dead ends to connect existing passages.

generate_maze(family, maze_size, seed=2025, door_fraction=0.3, braid_fraction=1.0)

Generate one fixed maze from the requested family.

open_neighbors(grid, cell)

Return traversable 4-neighbours of cell.

free_cells(grid)

List all traversable cells in row-major order.

shortest_path(grid, start, goal, *, forbidden=None, rng=None)

Find a BFS shortest path, or return an empty list if none exists.

connect_subgoals(grid, subgoals)

Join subgoals with BFS segments and return path/anchor positions.

alternative_simple_paths(grid, shortest, *, count, rng, max_attempts=500)

Create longer paths by replacing a shortest-path segment with a detour.

The replacement cannot touch the remainder of the original path, except at the selected segment endpoints. This is the path-first construction described in Appendix D.1 of the Insertion Process paper.

subgoals_from_path(path, count, rng)

Select path endpoints and uniformly sampled interior positions.

flatten_cell(cell, width)

Map (row, col) to the token used by the benchmark.

unflatten_cell(token, width)

Invert flatten_cell.

generate_examples(grid, *, strategy, split_sizes, min_subgoals, max_subgoals, max_path_length, paths_per_pair=10, seed=2025, max_attempts_per_example=1000)

Generate exact split sizes with endpoint pairs kept split-disjoint.

write_dataset(output_dir, examples, metadata)

Write JSONL splits and maze metadata.

push_dataset(repo_id, examples, metadata_path, *, private=False)

Push split rows and maze.json to one Hugging Face dataset repository.

plot_maze(grid, output_path, *, path=None, subgoals=None)

Save a maze image, optionally overlaying one path and its subgoals.

build_parser()

Build the command-line parser.

main(argv=None)

CLI entry point.