emerentius / sudoku

The Rust sudoku library

Sudoku

Utilities for classical 9x9 sudokus.

This library currently offers extremely fast sudoku solving, a basic sudoku generator and a prototype solver using human strategies. The fast solver is based on jczsolve which is currently and to the best knowledge of the author one of the world's fastest sudoku solver algorithm. A few modifications were made to improve the speed further.
Some competing solvers are fsss2, SK_BFORCE2 and tdoku. The latter is particularly strong for sudokus that don't have a unique solution or that are very hard. See also benchmarks done by tdoku's author: benchmarks (results at time of writing).

The strategy solver is capable of applying a few simple strategies, namely naked and hidden singles, locked candidates, naked and hidden subsets (Pairs, Triples, Quads) and basic fish (X-Wing, Swordfish, Jellyfish). An explanation of these strategies and more can be found at http://www.sudokuwiki.org/Strategy_Families.

A future goal is the extension and further optimization of the strategy solver, so that most sudokus can be graded, hinted and the solution path explained. With the ability to grade sudokus, puzzles of any desired desired difficulty can also be generated.

Example

use sudoku::Sudoku;

// Sudokus can be created from &str's in both block or line formats or directly from bytes.
// here, an example in line format
let sudoku_line = "...2...633....54.1..1..398........9....538....3........263..5..5.37....847...1...";

let sudoku = Sudoku::from_str_line(sudoku_line).unwrap();

// Solve, print or convert the sudoku to another format
if let Some(solution) = sudoku.solution() {
    // print the solution in line format
    println!("{}", solution);

    // or return it as a byte array
    let cell_contents: [u8; 81] = solution.to_bytes();
}

sudoku's Issues

An even faster implementation of the sudoku solver

I don't know if you're already aware of it, but an even faster sudoku solver exists (tdoku). Just wanted to let you know. Feel free to disregard if this isn't useful.

Link to GitHub repo

Link to the article that describes the algorithm

Relicense

As discussed in aochagavia/sudoku#7, this fork is moving to the AGPLv3.

#aochagavia, please answer within this thread that you're ok with that so it's attached to this repo.

Human Strategies

The crate should contain a new public struct for solving sudokus like a human would. This struct is to contain additional information about the state of the sudoku, that allow efficient application of the various strategies. An example would be a cache of the possitions that are still possible for a certain number in a row, column or block so that one does not have to iterate over the entire grid.

It should be possible to supply a set of strategies at runtime i.e. as a Vec<Strategy> and have it solve the sudoku using only these and return the finished sudoku or however far it got.
It should also be possible to simply get a hint, i.e. the result of one strategy being applied only once. The hint should carry the reason why the deduction is valid and not just a set of deduced entries or impossibilities.

I have started work on this in the strategy_solver branch. So far 8 strategies (8 structs) are implemented (not yet unit tested) and a solver that drives the sudoku to completion with the given strategies.

Todo:
- [ ] Decide on function signature of Strategy trait

• Decide how to Implement hinting
  • single hinting
  • full solution as series of deduction steps
• Clean up API and publish v0.7

After that comes the eternal task of implementing more strategies (here is an overview)

Support for pencilmark Sudoku

Hi! Thanks for beautiful crate!
Is there any way to add support for pencilmark Sudoku? Are you planning to do that?

Improve speed

The main solver in this crate is based on BBsudoku / JSolve / fsss (JSolve and fsss are themselves based on BBsudoku). The most important part of the algorithm is the data structure of bitmasks for possible digits for each cell and for each zone (row, column, block). I've experimented with many kinds of caches but nothing was as fast as these data structures.

JSolve is still twice as fast as this crate. In addition to naked and hidden singles it also searches for locked candidates which I don't currently. With that deactivated it is still ~60-70% faster so there is a lot of optimization potential left in the current implementation. All of the programs mentioned above are under some ad-hoc non-free license so I can't check their code for comparison.

On top of that, even faster but more complicated solvers exist that pack bitmasks for multiple cells together which allows for highly optimized search routines. JCZSolve as well as fsss2 fall under that. JCZsolve is 4x as fast as this crate. fsss2 doesn't compile for me. These programs don't even have licenses at all. JCZsolve has very few comments.

Getting the enhancements incorporated requires either

1. Getting permission
   from 3 people in the case of JCZsolve. Hopefully they can be reached via the forum thread (from the JCZsolve link).
2. Doing a cleanroom implementation
   Would need another person to write a detailed spec. The code is just ~1k lines but it's highly optimized so there's not much fluff.
3. A whole lot of reinvention

The majority of runtime for the generator for uniquely solvable sudokus depends on solution finding so this could speed it up by almost the full 4x.

parse_from_grid_state_str doesn't reproduce StrategySolver correctly for unsolvable sudokus

When the grid contains a cell with zero candidates (shown via _ in a grid state print), StrategySolver::parse_from_grid_state_str(string).to_string() doesn't reproduce the original string.

The update methods short circuit at some place.

Generate Sudokus

It's a common requirement to set the difficulty of the generated sudoku. Given that humans use other strategies than the very fast backtracking it's likely better to estimate difficulty by applying the same deductions.

Generating a random sudoku until it can be solved by some set of strategies seems like a good first step. Generation of trivial sudokus can be stopped by requiring some strategies to be used at least once.
With this approach, generation of harder sudokus is blocked on #2.

• Generate random sudokus
• Generate sudokus passing some grading threshold

Locked Candidates strategy misses some cases

Examples from GUI:

Canonicalization

Sudokus can be transformed in ways that do not affect the number of solutions or the applicability of solution strategies and thus their difficulty. One example is relabeling by switching 1 and 2 everywhere. The crate already contains a shuffle function that performs such transformations in a random manner. It should also contain a function to map all equivalent sudokus to the same sudoku, the canonical form.

Todo:
Canonicalizations for

• solved sudokus
• unsolved sudokus based on their (unique) solution
• unsolved sudokus, preserving the pattern of clues