synth/games/tasks/sudoku

Sudoku Game

Game Description

Sudoku is a popular logic puzzle game where players need to fill a 9×9 grid with digits 1 through 9, ensuring that each row, each column, and each 3×3 subgrid contains all digits from 1 to 9 without repetition. Each puzzle starts with some numbers already filled in, and players must use these clues to deduce the numbers that should go in the remaining empty cells.

Code Logic

Core Classes and Methods

• Sudoku: Inherits from the base Game class, responsible for generating and handling Sudoku games.

  • generate(): Generates Sudoku puzzle and solution, controls the number of empty cells based on difficulty level, can specify whether a unique solution is required.
  • extract_answer(): Extracts the Sudoku solution from the model's response text.
  • _generate_complete_sudoku(): Generates a complete valid 9x9 Sudoku solution.
  • _mask_sudoku_by_difficulty(): Masks some digits based on difficulty level, with option to ensure unique solution.
  • _has_unique_solution(): Checks if the given Sudoku has a unique solution.

• SudokuVerifier: Inherits from the base Verifier class, verifies whether the model's Sudoku solution is correct.

  • verify(): Verifies if the solution follows Sudoku rules and is consistent with the original puzzle.
  • _is_valid_sudoku(): Checks if the Sudoku solution follows the rules.
  • _is_consistent_with_original(): Checks if the solution is consistent with the original puzzle.

Data Generation Process

1. Uses backtracking algorithm to generate a complete, valid 9x9 Sudoku solution.
2. Randomly retains some digits based on specified difficulty level (1-4):
   • Difficulty 1 (Easy): Retains 35-45 hint cells
   • Difficulty 2 (Medium): Retains 30-35 hint cells
   • Difficulty 3 (Hard): Retains 25-30 hint cells
   • Difficulty 4 (Expert): Retains 20-25 hint cells
3. If unique solution is required, uses gradual removal method to ensure the generated Sudoku has a unique solution.
4. Generates puzzle description, randomly selecting Chinese or English templates.
5. Saves the generated puzzle, solution, and metadata to a Data object.

Answer Verification Process

1. Extracts the Sudoku solution from the model's response (usually in tuple form within Python code blocks).
2. Verifies if the solution is a valid 9x9 Sudoku (each row, column, and 3x3 subgrid contains 1-9 without repetition).
3. Verifies if the solution is consistent with the numbers already given in the original puzzle.

Usage Instructions

Generating Sudoku Game Data

Use the following command to generate Sudoku game data:

bash games/tasks/sudoku/run.sh --num_of_data 100 --difficulty 3 --unique_solution

Parameter explanations:

• --num_of_data: Number of puzzles to generate, default is 100.
• --max_attempts: Maximum number of attempts per puzzle, default is 1000.
• --difficulty: Difficulty level (1-4), default is 3.
• --unique_solution: Specifies that generated Sudoku must have a unique solution (default).

Generated data will be saved in games/tasks/sudoku/data/unique_solution_{unique_solution}/difficulty_{difficulty}/num_of_data_{num_of_data}/data.jsonl file.

Features

• Supports different difficulty levels (1-4) for Sudoku generation
• Supports generating Sudoku puzzles with unique or multiple solutions
• Supports random mixed Chinese and English prompt generation
• Strict verification of Sudoku solution correctness
• Performance analysis of model solutions by difficulty level