SudokuStudyLib

This is a python library for studying logic by solving Sudoku and learning the programming of python language. Sudoku is a kind of puzzle game. it is one of the best way to learn logic, and at the same time, the Python language is one of the best computer language to learn logic. So, if we can combine these two kinds of tools to teach children or young men to learn logic, it will be perfect. This is why the project be done and going to.

Welcome to the Purest World of Human: Sudoku and Logic

Contents:

Welcome to SudokuStudyLib’s documentation!

This is a tool and library for studying Logic and Python programming. It includes two packages, one is Sudoku, and another is Matrix. The Sudoku is an oop approaching library, while the Matrix is a traditional function processing library.

This library and document are major for Soduku package, the Matrix package is just a reference for a traditional programmer.

Install

You can use pip to install the library:

pip install SudokuStudyLib

and you can clone the project from:

https://github.com/RobertOfTaiwan/SudokuStudyLib

When you has installed, it will contain two packages, sudoku, and matrix. The following is the file structure:

Usage

1. OOP method: sudoku, in the test.py:

   from sudoku import *
   
   # to solve a sudoku defined in data directory
   solve("m18.data")
   
   pass
   
   # to solve a sudoku and just using the methods which level <= 15 and if can't solve, don't use guess method
   solve("m3.data", level_limit=15, use_try=False)
   
   pass
   
   # to solve a sudoku with emulator methods and print the steps
   solve("m12.data", use_emu=True, print_step=True)
   
   pass
   
   # to solve the world's best difficult sudoku
   # by default method
   solve("m10.data")
   
   # by computer's try error
   try_error(None, file="m10.data")
   
   # by all methods but not using human guessing, it can't solve the sudoku
   solve("m10.data", use_emu=True, use_try=False)
   
   # by basic human methods and guess
   solve("m10.data", level_limit=10, use_try=True)
   solve("m10.data", level_limit=3, use_try=True)
   

2. Traditional method: matrix, in the test.py:

   from matrix import *
   
   # solve it directly
   m, n, p = main("m6.data")
   
   # solve it by limit methods, it can't solve the sudoku
   m, n, p = main("m3.data", methods=8)
   
   # set the limit methods to the 10, and it can solve the sudoku
   m, n, p = main("m3.data", methods=10)
   
   # using the try error's method to solve the best difficult sudoku in the world
   m, n, p = TryError("m10.data")
   

The base knowledge of sudoku

Sudoku is a kind of puzzle game. It is one of the best way to learn logic, and at the same time, the Python language is one of the best computer language to learn logic. So, if we can combine these two kinds of tools to teach children or young men to learn logic, it will be perfect. This is why the project be done and going to.

A classic sudoku

You can study what and how is sudoku in Wiki Page: http://en.wikipedia.org/wiki/Sudoku

The following is a classic sudoku:		and the following is the solution for it:

Rules

The basic rules to solve a sudoku is very easy:

1. Put the number of 1-9 to every line(including x-way and y-way) and every box.
2. every line and every box can’t duplicate of the number of 1-9.

How many possible puzzles in a 9x9 sudoku

If we put the first number in a the position (1, 1), there are must have 9 numbers can be selected to put in. Then we put the second number in the postion (1, 2), there are must have 8 numbers can be selected to put in. So, and as it going on, we can write down the possible numbers we can select in every position:

9!	6!	3!	6!	3!	1!	3!	1!	1!
9	6	3	6	3	1	3	1	1
8	5	2	5	2	1	2	1	1
7	4	1	4	1	1	1	1	1
6	3	1	3	1	1	1	1	1
5	2	1	2	1	1	1	1	1
4	1	1	1	1	1	1	1	1
3	1	1	1	1	1	1	1	1
2	1	1	1	1	1	1	1	1
1	1	1	1	1	1	1	1	1

So the possible combinations are 9!*6!*3!*6!*3!*1!*3!*1!*1* = 4,514,807,808,000

if we use python to caculate it:

>>> def n(x):
    if x==1:
        return 1
    else:
        return x*n(x-1)

>>> n(9)*n(6)*n(3)*n(6)*n(3)*n(1)*n(3)*n(1)*n(1)

About the mathematics of sudoku, you can get it at Wiki, http://en.wikipedia.org/wiki/Mathematics_of_Sudoku

What is logic?

Logic is the most important for a person starting to discover the world

The basic logic is dichotomy, is True or False in human language, or is 0 or 1 in computer language. It is the smallest and simplest classification which human can recognize and communicate with each other. So learning logic for children and young men is very important, because this is the base of all knowledge, and the base of all religion.

If you can’t judge a thing is right or not, is existed or not, in one certain view point, you don’t know the world, as you don’t know yourself either.

Learning Logic by Solving Sudoku

Learning logic can be a very happy thing if we teach it as a game, and Sudoku is the one. There are several good reasons to study logic by Solving sudoku:

• Its rules are so simple, everybody can know it in 5 minutes,
• It is so complicated that have more than billions of combinations.
• It can be separated into different difficult levels easily.

Learning Logic by Learning Python Programming

Learning a computer language is the nature way to learn logic. Python is a interpreter script language, you can get every resource from https://www.python.org/. I recite a period of Python FAQ<https://docs.python.org/3/faq/general.html> about for the beginning programmers:

Q:

Is Python a good language for beginning programmers?

A:

Yes.

It is still common to start students with a procedural and statically typed language such as Pascal, C, or a subset of C++ or Java. Students may be better served by learning Python as their first language. Python has a very simple and consistent syntax and a large standard library and, most importantly, using Python in a beginning programming course lets students concentrate on important programming skills such as problem decomposition and data type design. With Python, students can be quickly introduced to basic concepts such as loops and procedures. They can probably even work with user-defined objects in their very first course.

For a student who has never programmed before, using a statically typed language seems unnatural. It presents additional complexity that the student must master and slows the pace of the course. The students are trying to learn to think like a computer, decompose problems, design consistent interfaces, and encapsulate data. While learning to use a statically typed language is important in the long term, it is not necessarily the best topic to address in the students’ first programming course.

Many other aspects of Python make it a good first language. Like Java, Python has a large standard library so that students can be assigned programming projects very early in the course that do something. Assignments aren’t restricted to the standard four-function calculator and check balancing programs. By using the standard library, students can gain the satisfaction of working on realistic applications as they learn the fundamentals of programming. Using the standard library also teaches students about code reuse. Third-party modules such as PyGame are also helpful in extending the students’ reach.

Python’s interactive interpreter enables students to test language features while they’re programming. They can keep a window with the interpreter running while they enter their program’s source in another window.

Features of this Library

There are so many sudoku’s puzzle games and studying in the world. Some are made for fun, some are for the studying of mathematics, while this library focus on logic learning. And the logic mainly is in human view, not in computer science view. So, there are some features in this package:

1. This is mainly for studying logic for human.
2. It is NOT to plan to be a normal programming courses.
3. It is NOT to plan to be a studying of serious mathematics.
4. The methods of solving a sudoku are mainly in a human view, NOT in computer science view.
5. Let people to find their own methods to solve a sudoku, and name these methods in their own way. (This is not in this package, but should be arranged this in the courses.)
6. Let people learning python to implement their own methods.
7. Studying OOP programming to solve a sudoku. OOP method can be treated as human behavior.

Courses

We can arrange these courses as a sudoku summer camp. We can prepare 1-6 different level sudokus. The learners don’t need to learn all levels. The purpose of these courses is NOT to teach all solving methods of sudoku, its purpose is logic learning. So, we can let different learners have their suitable target to learn.

Who are suitable for these courses

Every one who have studied in an elementary school for three or four years.

First Step: Learn solve a sudoku by hand

Hours:

14 hours, 2 hours/day, 7 days

Purpose:

1. Find the suitable level for every learner
2. Learn the basic computer knowledge

Second Step: Learn to find methods to solve a sudoku

Hours:

14 hours, 2 hours/day, 7 days

Purpose:

1. Nameing the method that they have found a model to solving a sudoku, and write down the description.
2. Let them can express their methods to others.
3. Learn the basic python programming by solving their home work, like solving how add all the value of 1 to 100.

Third Step: Learn to write python code to implement their methods

Hours:

14 hours, 2 hours/day, 7 days

Purpose:

1. Learning Object Oriented Programming(OOP) concept.
2. Learning to use OOP to implement their methods.

How to make a simulator environment in Python to solve a sudoku

We think classes defined is the most difficult for learner in the OOP method of programming. So in these courses of learning to solve sudoku, we don’t explain how to make a class, property, and methods in detail. But just make a explanation of the existed classes, properties and methods in this library to learners. So we can explain these data structures as a simulator environment to solve a sudoku like a human being.

We can first image that there are 9x9 houses in a beautiful valley, and they are build like:

An Imagined World

There are 9 countries, every country has 9 people. They decide to live together in this beautiful valley. And there are 9x9 houses, They want to let every people live in one house, and every X-way line, Y-way line, and every 3x3 box include all countries’ people. And if so, they can say themselves are a real united group in the world, can you help them?

and then we can start to solve the wondeful world for these people...

What is a Class? and an Object?

Class is collective name for a group of objects which have same behaviors, features, forms. So, animal can be a class name, and elephant is an kind of object of this class.

An object is thing which belong a class or multi classes.You can treat an object is an entity of a class, like human is a class, but you is an object, an entity which belong human class.

Depend to the domain which we want to approach,or to define, we will define some different classes to describe the same objects. Like if we want to study a city bioecology system, we may define an animal class, that contain some people, some pets, and so on... But when our domain is to make a phone book application, we may define a person class that contain some people, but no pets, except our pets have a cell phone too.

In this sudoku solving library, we define the following classes:

• Number Class:

  You can treat every number as a different man, there are 9 countries, and every country has 9 men. So we can treat the Number Class as a Country Class. Every country has their ID, here is 1-9, and every country would record the positions where their people live in this valley.

• Point Class:

  Point is a house here. It indicate that there is empty or not, if it is not empty, which country people lives there? if it is empty, which counties’ people can live here?

• GroupBase Class:

  GroupBase is group of X line, Y line or a 3x3 Box. This is base class of Box, lineX, lineY. It indicate which houses are belong to him, how many people have lived in this group? and which counties’ people still not live in this group?

• Box Class:

  Every 3x3 block. Every box has its id, from left to right, from top to down, it is assigned 1-9, as the following picture:

  

• lineX Class:

  Every x-way line. Every x-way line has its id, from left to right, it is assigned 1-9, as the following picture:

  

• lineY Class:

  Every y-way line. Every y-way line has its id, from top to down, it is assigned 1-9, as the following picture:

  

• Matrix Class:

  Matrix Class is the WORLD of a sudoku game. It is the beautiful valley, including 9 countries, every country have 9 people, there are 9x9 houses for all these people.

What is a Property?

Property is in a class to declaim what it cotain and how they look like or their conditions. Like a person class, may have these properties of how much money he have, how many children he have, , and first child is boy or girl, how old are them?

The following are the major properties of all classes in this libryary:

• Number class:

  • v: the id of a country, it is 1-9.
  • p: the list of the houses which these country people have lived in
  • filled: how many people have lived in a house

• Point class:

  • x: the x-way postion of this house
  • y: the y-way position of this house
  • v: which country people has lived here, if it is still empty, its value is 0
  • b: this house belogn which 3x3 box

• GroupBase class:

  • idx: the id of this group
  • p: the list of the houses which belong this group
  • filled: how many people have lived in this group
  • possible: the list of country id which have not lived in this group

What is effects?

Effects of a box are the 4 boxes which the same direction of x or y with it. So, effectsX are the boxes that have the same x-way direction, while effectsY are the boxes that have the same y-way direction of it.

• Box class:

  • All GroupBase Properties
  • effects: the box id list of a box’s neighbors
  • effectsX: the box id list of a box’s neighbors which in x-way direction
  • effectsY: the box id list of a box’s neighbors which in Y-way direction

• lineX class:

  • Having the same properties as GroupBase

• lineY class:

  • Having the same properties as GroupBase

• Matrix class:

  • p: A two dimention of point(house), from p[0][0] to p[8][8] to present all the houses in this valley.
  • lineX: A list of x-way line of the houses
  • lineY: A list of y-way line of the houses
  • b: A list of 3x3 box of the houses
  • n: A list of Country.
  • filled: how many people have lived in a house now.

What is a Method?

Methods are the behaviors of a class or an object. For example, if we define a radio class contain several buttons, then we should define the methods when some button has been pushed. It may start to receive a program from a station, or record a program into CD, etc...

The following are the major methods of the classes in this library:

• Number class:

  • setit(p1): when a country’s people find a house(p1) to live, this method will be called

• Point class:

  • can_see(p1): to check a house can see another house(p1) or not?
  • can_see_those(posList): to check a house can see a list of houses, and return the houses list which it can see them.

  Note

  What is “SEE”?

  the houses in the same x-way or y-way line, or in the same box, of a house, this means that this house can SEE all of them.

• GroupBase class:

  • allow(v): check the group can allow the country people(whose id is v) to live or not?
  • get_num_pos(v): get where the people live in this group who is the country people(whose id is v), if there is no this country’s people, it will return None.
  • count_num_possible(count): get the countries’ id and houses, which are empty now, and are possible to be assigned to a certain country people, and the houses are equal to the number(count)
  • get_all_pos(method): get all houses in this group, if method=”a”; if method=”u”, get all empty houses, if method=”s”, get all not empty houses.

• Box class:

  • All GroupBase methods
  • get_group_number(num): To Check the num in a box’s would form a Group Number or not.

  Note

  What is “Group Number”?

  Group Number is in a box. Those houses in this box can and only can allow some country’s people, and these houses in a same line(x-way line or y-way line), then we call these houses form a Group Number, We don’t know which house is the country’s people should live finally, but we know the other houses in this line will not allow the same country’s people to live.

• lineX class:

  • Having the same methods as GroupBase

• lineY class:

  • Having the same methods as GroupBase

• Matrix class:

  • get_all_pos(method): if method=”a”, get all houses; if method=”u”, get all empty houses; if method=”s”, get all houses where have lived people
  • sort_unassigned_pos_by_possibles(possibles): get all empty houses which are only allowfd for [possibles] countries people, if possibles == 0, it will get all empty houses, and sorted by the possiles from low to high.
  • can_see(p0, method=”u”, num=0): get the houses which cand the house(p0), if the num!=0, mean get the houses only that are allowed the num country’s people.
  • setit(x, y, v): Let the v country’s people live in the the house of the position (x, y).
  • reduce(x, y, v): When a country people find a suitable house to live, then any empty house can SEE the house will reduce their possible countries people to live in.
  • allow(x, y, v): check the v country people can live in the house of the position (x, y) or not?
  • read(file): read the first defined that how many people and where they have lived in this valley.

Game Defined File

You can define sudoku’s game by giving x, y, v line by line in a text file. like the following: its define file is in the [installed directory]/sudoku/data/

A sample define and its original and result matrix

m3.data	Original Matrix	Result Matrix

Start Programming to Solve a Sudoku

When we have created a sudoku simulate world in the computer to solve a sudoku, now we should go ahead to implement some methods which we solve it in our own hands. In other world, programming, is the stuff which we teach computer to do something that we have known it.

We first introduce the solve environment, then we will introduce some basic methods in this library.

Solving Environment

We create a function solve() to do the real solving a sudoku, and we make two exception classes, SudokuDone, SudokuError to capture event happen when we use methods to solve a sudoku.

Note

What is “Exception”?

Exception is an event defined, when the event condition has occurred, system will stop the processing and jump to the exception processing. There are two major exceptions in the environment:

SudokuDone:

when the sudoku has been solved, will raise this exception

SudokuError:

when a country people to set in a house, but will break the rule of game, this will raise this exception

To let the environment know how many methods they can use to solve a sudoku, we create a class, SolveMethod. We use this class to create all methods in a BRAIN. We can treat this BRAIN like the god of this valley. Every time, when people don’t how to choose their suitable houses, you can ask the god of valley, and it will give an answer, or it would say that, “I don’t know how to do either!“

Every method register in the Brain as a SovleMethod object, they have these major properties:

1. fun: the function name of the method in python coding
2. idx: the index of the method, from the easier to the more difficult, the brain will use this sequence to solve a game one by one.
3. name: the name of the method
4. level: the difficult level for human, using to count a game’s difficult level

Solving Process

The following is the flow chart of solve():

Note

WORK or NOT WORK?

A method works or not means that using this method can:

1. let one or more people to find his or their own house,
2. OR can let one or more houses know they are not allowed for some countries’ people.

In this flow chart, we know that:

1. When a method works to set a person or reduce a house’s allowed people, it will return to the first method to restart solving the game.
2. If a method can’t work to solve a game, it will give the game to the next method to solve it.
3. And if final method can’t solve a game, it will go out and say “I can’t figure out this game, sorry!”
4. In the solving process, if “Done” or “Error” event occur, it will go out.

Some Basic Methods

1. fill_only_one_possible:

   Find every house in a group, if there is only one house that one country people can live there, that house must let that country’s people to live in.

2. fill_last_position_of_group:

   When in a group(line or box) are only one left, it must allow only one country people to live there.

3. check_obvious_number:

   Check every country people who has lived in a house, and when these people observe other boxes which has yet not lived their country people, can find an only house that allowed their country people or not?

4. check_inobvious_number:

   It is the same method as check_obvious_number, but some boxes’ houses are formed as a Group Number.

What is a Chain?

Chain is formed by two or above houses. In these houses, the amount of all different possible countries’ people are equal to the amount of the houses. When a chain have formed, we can reduce the possible countries’ people from the other houses in the same group of this chain.

5. reduce_by_group_number:

   If there is a Group Number in a box, the empty houses of its same direction could be reduce the possible country people of this Group Number.

6. update_chain:

   As the houses have been lived some people, this would make some empty houses reduce some possible countries’ people. And then these empty houses in a group(x-way line, y-way line, box) may form a Chain.

How to implement a method?

We could implement a method called check_obvious_for_a_country(m, num) method as an example:

 1  def check_obvious_for_a country(m, num):
 2  checked = list()
 3  for p1 in m.n[num].p:
 4      for b in m.b[p1.b].effects:
 5          possible = []
 6          if b in checked:
 7              continue
 8          else:
 9              checked.add(b)
10          if num not in m.b[b].possible:
11              continue
12          for p2 in m.b[b].p:
13              if p2.v != 0 or p2.can_see(p1) > 0:
14                  continue;
15              if not m.lineX[p2.x].allow(num):
16                  continue
17              if not m.lineY[p2.y].allow(num):
18                  continue
19              possible.append(p2)
20          if len(possible) == 1:
21              m.setit(possible[0].x, possible[0].y, num, d="Obvious For a Country People")

1. line#1, define a method, m is the world of this game, and num is a country id, here is 1-9.
2. line#3, starts to find the all people who have lived in a house of a country.
3. line#4-9, it scan all its effect boxes if those have not been checked.
4. line#10-11, it the country people have live in this box, ignore it.
5. line#12-19, check all empty houses in this box which allow the country’s people or not, if yes, put it in the Possible List.
6. line#20-21, if the Possible List has only one house, it must can be assigned this house to the country’s people.

Package: Sudoku - the OOP method

This is the oop method to solve the Sudoku.

Indices and tables

• Index
• Module Index
• Search Page