{"id":18309552,"url":"https://github.com/sfuhrm/sudoku","last_synced_at":"2025-04-05T17:32:53.867Z","repository":{"id":57730933,"uuid":"79741030","full_name":"sfuhrm/sudoku","owner":"sfuhrm","description":"A very fast Java Sudoku library implementation along with a command line client","archived":false,"fork":false,"pushed_at":"2025-03-31T18:36:39.000Z","size":561,"stargazers_count":19,"open_issues_count":1,"forks_count":8,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-31T18:41:55.776Z","etag":null,"topics":["algorithm","fast-algorithm","java","library","riddle","solves-riddles","sudoku","sudoku-generator","sudoku-java-library","sudoku-solution-finder","sudoku-solver"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sfuhrm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-01-22T19:49:12.000Z","updated_at":"2025-03-31T18:36:04.000Z","dependencies_parsed_at":"2025-03-31T18:32:55.759Z","dependency_job_id":"3eb49947-f672-4f77-a5a9-17dfbee13ff5","html_url":"https://github.com/sfuhrm/sudoku","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sfuhrm%2Fsudoku","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sfuhrm%2Fsudoku/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sfuhrm%2Fsudoku/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sfuhrm%2Fsudoku/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sfuhrm","download_url":"https://codeload.github.com/sfuhrm/sudoku/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247375545,"owners_count":20929050,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["algorithm","fast-algorithm","java","library","riddle","solves-riddles","sudoku","sudoku-generator","sudoku-java-library","sudoku-solution-finder","sudoku-solver"],"created_at":"2024-11-05T16:11:47.651Z","updated_at":"2025-04-05T17:32:48.850Z","avatar_url":"https://github.com/sfuhrm.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"Sudoku Java Library\n===================\n[![Java CI with Maven](https://github.com/sfuhrm/sudoku/actions/workflows/maven.yml/badge.svg)](https://github.com/sfuhrm/sudoku/actions/workflows/maven.yml)\n[![Coverage](https://raw.githubusercontent.com/sfuhrm/sudoku/master/.github/badges/jacoco.svg)](https://github.com/sfuhrm/sudoku/actions)\n[![javadoc](https://javadoc.io/badge2/de.sfuhrm/sudoku/javadoc.svg)](https://javadoc.io/doc/de.sfuhrm/sudoku)\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/de.sfuhrm/sudoku/badge.svg)](https://maven-badges.herokuapp.com/maven-central/de.sfuhrm/sudoku)\n[![ReleaseDate](https://img.shields.io/github/release-date/sfuhrm/sudoku)](https://github.com/sfuhrm/sudoku/releases)\n[![License: LGPL v3](https://img.shields.io/badge/License-LGPL%20v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0)\n\nA Java implementation of a very fast algorithm for creating [Sudoku](https://en.wikipedia.org/wiki/Sudoku) riddles.\nHas also the functionality to solve Sudoku riddles.\n\nThe following animation shows how quick the provided command line client can create Sudokus:\n\n![Creating a riddle](http://sfuhrm.de/wp-content/uploads/2017/11/Sudoku-Create-Riddle-SF-1.gif\n \"Creating a riddle\")\n \n The riddles can be of the schema dimensions:\n* 4x4\n* 9x9 (standard size)\n* 16x16 (too slow at the moment)\n* 25x25 (too slow at the moment)\n\n## Building it\n\nFor building the application you need Apache Maven.\nUse the following command line:\n\n    $ mvn clean package\n\n## Features\n\nIn the following list I want to give an overview of the features:\n\n* **Performance**: Very fast algorithm that is using backtracking, but terminates in some fractions of a second. For fully filled boards this is usually less than 1ms on current hardware. For partly-filled riddles this is usually less than 20ms.\n* **Pureness**: Pure Java implementation without any runtime dependencies to other libraries. Runs on Java 8+.\n* **Quality**: High test coverage of \u003e94%. Many (optional) runtime assertions to assure correct operation.\n* **Output**: Plain text, Markdown, LaTeX and JSON output formats. For an example, see [2000-sudokus.pdf](https://github.com/sfuhrm/sudoku/releases/download/v0.1.3/2000-sudokus.pdf), a collection of 2000 Sudokus.\n\n## Usage\n\nYou can review the [javadoc](https://javadoc.io/doc/de.sfuhrm/sudoku) for\ndetailed information.\n\nThe usage for fully set Sudoku boards (no empty fields) is as following:\n\n---------------------------------------\n\n```java\nGameMatrix matrix = Creator.createFull();\n```\n\n---------------------------------------\n\nYou can create a solvable riddle (with empty fields) using\n\n---------------------------------------\n\n```java\nGameMatrix matrix = Creator.createFull(GameSchemas.SCHEMA_9X9);\nRiddle riddle = Creator.createRiddle(matrix);\n```\n\n---------------------------------------\n\nA solvable riddle looks like this:\n\n---------------------------------------\n|  |  |  |  |  |  |  |  |  |\n|---|---|---|---|---|---|---|---|---|\n| . | . | 4 | . | . | . | . | 2 | 9 |\n| . | 2 | . | . | . | 4 | . | . | . |\n| 6 | . | . | . | . | . | . | . | 3 |\n| 2 | 4 | . | . | . | 3 | . | . | . |\n| 5 | . | . | . | . | . | 9 | . | . |\n| . | 7 | . | 5 | . | . | 8 | . | . |\n| . | . | . | . | . | 7 | 1 | 6 | . |\n| 1 | . | . | . | . | 6 | . | 9 | . |\n| . | . | . | 4 | . | 2 | . | . | 8 |\n|  |  |  |  |  |  |  |  |  |\n---------------------------------------\n\nAnd last but not least you can solve a riddle using\n\n---------------------------------------\n\n```java\n    Riddle riddle = new GameMatrixFactory().newRiddle(GameSchemas.SCHEMA_9X9);\n    riddle.setAll(QuadraticArrays.parse(\"000000000\", ...));\n\n    Solver solver = new Solver(riddle);\n    List\u003cGameMatrix\u003e solutions = solver.solve();\n```\n\n---------------------------------------\n\nFor valid riddles you'll find in magazines there is only one solution in the list.\n\nThere is also a [CLI client](sudoku-client) that demonstrates the usage of the library.\n\n## Including it in your projects\n\nPlease note that the current version is experimental. It creates and solves riddles. The API will change.\nThe library could run into a runtime exception.\n\nThere are unit tests for many things, but the code is still young.\n\nThe recommended way of including the library into your project is using maven:\n\n---------------------------------------\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ede.sfuhrm\u003c/groupId\u003e\n    \u003cartifactId\u003esudoku\u003c/artifactId\u003e\n    \u003cversion\u003e4.0.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n---------------------------------------\n\n## Algorithm\n\nThe design idea is to use the narrowest bottleneck of the Sudoku board to prune the backtracking\ntree to the maximum and get the fastest results.\n\n### Initialization\n\nThe algorithm first fills three blocks with numbers in random order to reduce the amount of backtracking.\nAfter that, backtracking for the remaining fields starts.\n\n### Backtracking\n\nThe field with the least number of possible number candidates on the board is searched. \nAll candidates are tried until the first candidate leads to a valid backtracking tree path. Backtracking occurs in this loop.\n\n#### Note on algorithm optimization\n\nIt's enough to restrict each backtracking recursion to one field. \nThis means there are no *field*-dead-ends, only *value*-dead-ends\nthe algorithm runs in.\n\nThis can be proved because as long as the algorithms invariant to only\nadd valid values is true, no fields become dead-ends. The requirement\nfor field-dead-ends is that the surrounding fields have an illegal\nsetup which leads to a rule-violation for each and every value of the\nfield in question.\n\n## Versions\n\nThe version numbers are chosen according to the\n[semantic versioning](https://semver.org/) schema.\nEspecially major version changes come with breaking API\nchanges.\n\n## Author\n\nWritten 2017-2022 by Stephan Fuhrmann. You can reach me via email to s (at) sfuhrm.de\n\n## License\n\nThe project is licensed under [LGPL 3.0](https://www.gnu.org/licenses/lgpl-3.0.en.html).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsfuhrm%2Fsudoku","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsfuhrm%2Fsudoku","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsfuhrm%2Fsudoku/lists"}