Tutorial

This tutorial explains how to use Kombilo 0.5. If you are just looking for more information on this program before downloading it, you should find it here too.

Contents

New features in version 0.5
Getting started
The first search
More complicated search patterns
The SGF editor
Export search results/current position/SGF
The game list window
Analyzing a game
Game info search
Signature search
The database list
The custom menus
Guess next move mode
Configuring Kombilo

Installation
Requirements on SGF files
Troubleshooting
Tips and tricks
The search algorithm
Index

New features in version 0.5

Getting started

After installing Kombilo, you should execute the file 'kombilo.py' (under Windows: 'kombilo.pyw' (if you downloaded Python separately) or 'kombilo.exe', respectively, if you used the installer). Three windows will pop up: The main window, with a go board and some buttons for navigation, the game list window with an (initially empty) game list, and some buttons for the search function, and the data window which contains several lists and buttons related to the SGF editor.

The first thing you have to do now is to add a database to the database list; choose the 'Edit DB list' command in the File menu.

A database corresponds to a directory of SGF files; it contains all the SGF files in that directory. Kombilo does not come with any games. You can either download a game collection from the net, or buy a commercial one.

See also the section about requirements on SGF files in order to understand which kind of SGF files the program can handle; basically, it handles simple game records, they may contain variations, but the variations are ignored for the search.

When you add a directory for the first time, the SGF files will be 'translated' into a format that makes the search more efficient. This processing takes quite some time; if you have thousands of games, it will take several minutes even on a very fast machine. But this has only to be done once. The data will be written to several .db files in the same directory. Look here for more information on the buttons in this window.

Of course the sgf files remain in the directory, and Kombilo will never change them (unless you change the game info or edit the games yourself, of course). After the processing, the pattern search function actually does not use them anymore, but they are needed for the game info search and if you want to play through games with the SGF viewer.

Note: (As far as I can tell, this is not an issue anymore with recent Python versions; in particular if you used the Windows installer, you should be fine.) In some Python versions the widget for selecting a directory is not available. (Technically speaking, they come with an old Tk version; Tk is the programming language underlying the GUI toolkit.) As a consequence, the program will crash once you press the 'Add DB' button in the 'Edit DB list' window. I think that this is mainly a problem on Windows95/98 systems, but it may happen on other systems, too.
There is the following work-around: Check the 'Old Tk version'-option in the 'Advanced' submenu of the options menu. Now the 'Add DB' button will bring up a widget to select a file; this widget is always available. In order to select a certain directory which should be added as a database, you have to select any file in it.
It is still possible to add all subdirectories of some directory at the same time, by the 'Add subdir's recursively' option. To do so, you have to select a file in the main directory. (If it doesn't contain any files, but only the subdirectories you want to add, you have to copy any file to that directory first. Don't take an sgf file because (probably) you don't want that sgf file to show up in the database.)

The first search

Place stones on the board by clicking. Ctrl-click to remove stones, and Shift-click to place wildcards. Mark the search-relevant region by right-click and drag
Now the game list should contain some files, and you can start the first search.
With the right mouse key (click and drag) you can select the search-relevant region; the rest of the board will be grayed out. (If you prefer to have the relevant region itself to be darker, as was the case in previous Kombilo versions, select the "Invert selection" option in the options menu.) Everything outside that region is ignored: on the one hand it does not matter if there are additional stones on the main board, on the other hand all games will be found which feature the given pattern in the relevant region, no matter what else is on the board. Of course, mirroring and rotating the board is automatically taken into account.

You can either place black and white stones alternatingly, or stones of one color only.
When no region is selected, the whole board is relevant.
After defining the pattern and the relevant region, just press the search button (in the lower left corner of the game list window). Then the game list will be erased, and afterwards all games in which the given pattern occurs will be inserted again. In order to go back to the complete game list, use the "reset game list" button in the first row of the "Pattern search" window.

If you click on a game in the game list, the game info (players, result, komi, event, date etc.) is displayed below the game list.

By double-clicking on a game in the game list, you load the game to the SGF editor and you can look at that game. You can also start the viewer by selecting a game (by a single click) and pressing the return key. If you prefer to open the game in a new window, use Shift-Click instead of double-clicking; cf. the Open game in external viewer option. (If you like, you can use your customary SGF editor instead of the simple SGF viewer coming with Kombilo; use the 'Alternative SGF viewer' command in the Options menu. (Linux/Windows only,I think))

By clicking on a game with the right mouse key, a window will pop up where the complete game info is displayed, and can be edited.

Furthermore, below the game list some statistics will be shown about the continuations in the given position. In the first line you find the number of hits (which, obviously, can be bigger than the number of games in the list); after this number, in parentheses, is the number of matches with colors as on the board respectively reversed colors. Finally, you get the B/W winning percentages corresponding to the hits (i.e. a game where the pattern occurs several times, is counted that often).
Below some information on the continuations in the search position is given. For the ten most frequent continuations, you get
- the number of hits in which this continuation is played
- graphically, it is shown, how often white played at this point after a tenuki (light gray), how often white played there directly
after the pattern was finished (white), how often black played there directly after the pattern was finished (black), and finally how often black played after tenuki at the given point.
- finally, below the letter labelling the corresponding point on the board (use the ABC button to display the labels on the board), you get the black winning percentage for white playing at this point, and then the black winning percentage for black playing there. (Because there is not enough space, the winning percentage for white is not given, but of course (neglecting jigos etc.) it will be 100% - black winning percentage.
You can disable the 'show tenuki' feature by setting the colors used for it to white resp. black in the Options menu (Advanced - Customize appearance).
Click on the 'ABC' button above the board in order to display the corresponding labels on the board. The labels are ordered by the number of occurrences of the corresponding continuation. (Unless there were already labels present in the search pattern: in that case Kombilo will use those labels to refer to the same intersections, and thus will not sort by frequency.)

If you have a sufficient number of games in your databases, this lets you create fuseki and joseki dictionaries very easily: The color of the label indicates whether black or white (or both, depending on the game, in case of the gray labels) played on this point.

After a search, you can clear the board with the 'start' button above the board. You can reset the game list (such that it contains all the games again) with the "reset game list" button in the pattern search window (left of the statistics display). In the file menu, you can also choose to do a "complete reset" - that will reset Kombilo to the state right after it started up.

More complicated search patterns

There are several buttons to customize the search in the game list window: Usually the pattern obtained by reversing the colors is searched for too, but you can disable that with the 'fixed color' option.
As a default, Kombilo uses the 'smart fixed color' option, which automatically enables 'fixed color' for whole board searches, and disables it for all other searches. You can change that in the options menu; see also below. Furthermore, for a pattern on the edge or in the middle of the board, the program also looks for translations; this can be disabled by the 'fixed anchor' option.

With the "black/white", "black" and "white" buttons in the line below you can limit the search to patterns where black plays next or white plays next. This is sometimes useful, in particular for joseki searches with very few stones on the board. The default is to allow either a black or a white continuation (or no continuation at all). Finally, you can impose a move limit, such that only games are found where the pattern occurs before the given limit.

You can also add wildcards to the search pattern, by shift-clicking on some point. These will be marked by small green circles, and mean that in the search these points may be either empty or contain a stone of either color.

For example, the following pattern finds all kos (that are not on the edge):

The SGF editor

You place stones by clicking (with the left mouse key) on an intersection. The four left-most buttons above the board control if you play black/white (resp. white/black) stones alternatingly, or if you place black (resp. white) stones, in order to set up a position.

In order to delete stones or to place labels, you have to select the appropriate tool among the 'edit tools' in the data window. Then you can perform the corresponding operation by holding down the Control key and clicking on an intersection.

With Shift + right-click you can go to the node where some move was/will be played.

Kombilo's main board has two more features which are related to the pattern search: You can place wildcards on the board (resp. delete them) by shift+click, and you can select the relevant area for the pattern search by clicking the right mouse key, and dragging.

The navigation keys above the board let you move around in the current game record: one move back, one move forward, 10 moves back, 10 moves forward, to the beginning resp. to the end of the current game. All these can also be done by using keys: left, right, up, down, home, end.

In order to clear the board, use the "start" button.

If the current SGF file contains variations, you can switch between the alternatives for the current move with the PageUp and PageDown keys.

Pass: Insert a pass move.

Game info: View/edit the game information which is stored in the root node of the current game (black/white players, ranks, result, komi, date, rules, etc.)

DATA: Open/withdraw the data window.

The data window

In the toolbar at the top you can choose which of the following frames you actually want to see. For example, if your SGF files all contain only one game each, you will not need the game list. Thus you can save some space on your screen by hiding some of the components of the data window.

File list

This is a list of all SGF files that have been loaded during the current session. The currently active file is highlighted; you can change that by clicking on another item in the list. The buttons on the right let you create a new file, open a file from disk, delete a file, or split a collection. Deleting a file just means deleting it from this file list. The file on your disk will not be deleted. Splitting a collection serves to split an SGF file which contains several games into many files with one game each. You will be asked for a filename, and the files will then be saved under the names filename0.sgf, filename1.sgf, filename2.sgf, etc.

If changes have been made to a file after it has been saved, the file name is preceded by a *. Kombilo will never ask you if you want to save the changes, so you have to pay attention to the *, and save the files yourself, if you want to keep the changes!

Game list

This is a list of game records in the current SGF file. You can select games by clicking on them, and change the order by drag and drop. The buttons on the right let you create new games and delete games from the list.

Game info

This shows part of the game information (names of players, result, date, etc.) of the current game. In order to see the full game information, or to edit it, use the "i" button above the go board.

Game tree

Here the tree structure of the current game is shown. Nodes with a black/white move are shown black resp. white; others are red. Nodes with a comment or a label on the board have a small blue dot in the center.
The green mark shows the current move (i.e. it corresponds to the position currently shown on the main board).
By clicking on a node, you can go to the corresponding move.

Edit tools:

The first few buttons in this frame control the behavior of Ctrl-click on the board: you can either delete a stone or place/remove one of several types of labels. Furthermore, there is a button to delete a node in the SGF tree and all nodes following it, and there are three buttons to mirror/rotate the current SGF file. Finally there is the button to enter/leave the guess mode.

Comments

In this window the comments which the SGF file contains for the current node are displayed.

Kombilo: Search history

This frame contains a list of previous search patterns. Click on one of the small boards to go back to the corresponding pattern search (i.e. the pattern and the game list are restored to what they have been right after the search).

A right-click on one of the board brings up a small menu, which lets you delete that entry, put the entry on hold resp. release it. Since storing these patterns and the lists of results consumes quite some memory (though less than it used to in previous versions), on machines with little memory it is useful to set a maximum number of searches which are remembered. Entries on hold will not be affected by this automatical deletion. These entries are marked by a blue frame.

Export search results/current position/SGF

If you want to save some information on a pattern search, you can use the 'Export search results' function in the File menu. This will open a new window with a very simple text editor. It will contain the search pattern, the search pattern with the continuations, some statistical information on the search, and the number of hits in each database.
You can edit the information and in the end save the text to a file. I would be interested in hearing your opinion if other or additional information should be given, or if the information should be presented in another format.
Before the text editor opens, you will be asked if you want "ASCII" or "Wiki" style output. Usually you will choose 'ASCII', which produces plain text. If you want to use the output for Sensei's Library, choose 'Wiki' instead. You can also choose if all continuations, or if only ten of them should be displayed.

The text editor has a button which lets you include the complete current game list (names of players, etc.). Similarly, you can "Export current position": this will open a text editor with the current position. Again, you can choose "ASCII" or "Wiki" type. In addition, Kombilo can put the next moves (up to 9 moves) on the board, marked by the numbers 1 to 9. Finally, you can also export the SGF source of the current game, in a text editor.

With Copy current SGF files to folder in the file menu you can copy the SGF files corresponding to the games currently in the game list to some folder (e.g. in order to use them with a different program).

The game list window

At the top, the game list window shows the number of games currently in the list, and the B/W winning percentages (the two numbers will often not add up to 100% since there might be Jigo's, unfinished games etc.) Right below the list, there is a frame where (part of) the game information for the currently selected game in the list is shown (just click on a game to select it). Below that, there is a "notebook" with one sheet each for the pattern search and the game info search. In the pattern search window, there are several buttons and switches.
The 'back' and the 'reset' button.
The 'back' button jumps back to the previous search: the position on the board is restored as well as the game list. (Previous search patterns are also shown on small boards in the "History" frame of the data window.)
The 'reset' button serves to reset the game list, i.e. to put all the games from the currently active databases in it, again.

With the ABC button, you can display the labels showing the continuations in the current search pattern (resp. remove them again). The "1-cl." button toggles the 1-click mode. If this mode is active, every click on the board triggers a search. That can be quite practical in order to play through joseki sequences, say. If this mode is inactive, single clicks will just place a stone on the board. In this case, you can place a stone and start a search at the same time by double-clicking. Below these buttons there are several buttons to control the behavior of the pattern search engine. Last but not least, in the game list window there is the button to start a pattern search. In the game info search window, you see entry fields for the search criteria: white/black player, player, event, etc. If you select the 'Referenced' option, only games with a reference to a commentary will be shown. You can make the game info search case insensitive by checking the corresponding box. The "clear" button clears all entries; the back and forward buttons restore the entries from previous searches. Unlike the back button for pattern searches, they do not change the game list. Last but not least, there is the button to start a search; you can also start the search by pressing Enter in one of the entry fields. The "Go to:" field makes it easy to find specific games in the game list quickly. In order to use this feature you should ensure that the complete database is ordered (you can always do that by unchecking the 'sort by database' option; if the order of the databases is consistent with the sort criterion, that might not be necessary, though). The 'Go to' entry always works with respect to the current sort criterion. Let's assume that you sorted the database by filename. Then entering something in the 'Go to' field will jump to the closest game in the game list the filename of which starts with what you entered. Finally there is the button to start a signature search.

References to commentaries

Kombilo has built in a list of references to game commentaries in the english go literature. The games are referenced by the Dyer signature (a signature assigned to the game which encodes the positions of move 20, 40, 60, 31, 51, 71, and which in practice characterizes a game uniquely); in particular Kombilo does not contain the game records. If Kombilo recognizes a game for which it has a reference, hte corresponding line in the game list is preceded by a star, and a line which gives the actual reference is appended to the game info which is shown when that line in the game list is selected. (This is printed in blue, to show that it is not part of the game info proper, but was added by Kombilo.) Currently, the list contains around 1200 references; in particular all but 10 issues of Go World, and most English books with game commentaries that I know of.

The references are stored in the file "references" in the main Kombilo directory. This file consists of two parts: first, a list of journals and books for which references should be shown. The second list contains the actual references, in the form 'signature journal/book issue'.

If you want only references to sources which you own to be shown, you can delete those books/journals which you don't own from the first list, without changing the second list, and then the corresponding references will be ignored by Kombilo. Differentiating between different issues of a journal is more complicated: in that case you have to edit the second list, and delete all references to those issues which you don't have.

Of course, additions to the list of references are very welcome. I think it would make sense to add references to other journals, like the American Go Journal, the British Go Journal, the Deutsche Go-Zeitung, the Revue Francaise de Go, etc. I will probably start adding more references to Go Review, myself. Your help to make the list more complete would be appreciated. If you are interested, please contact me, so that we can agree in which format you could send me the references, and to avoid that any references are collected twice. (Thanks to Uwe Richter for indexing 10 issues of Go World!)

Analyzing a game

If you want to analyze a game of your own, just load it into the main board with the 'Open' command in the file menu (or use the 'Open' button next to the file list in the data window). Use the navigation buttons to navigate through the file, and search for patterns appearing in your game: for the first few moves you may want to do a whole board search, in order to see up to which point the fuseki you played also occurs in professional games, and afterwards you have to select an appropriate relevant region.

You can also load a fuseki or joseki dictionary For example, Kombilo works quite well with Kogo's joseki dictionary. To navigate all the variations, you should enable the 'Show next move' option.

Game Info search

If you are looking for games by a particular player, from a particular event or from a certain time period, you can use the game info search. This is basically a text search in the SGF game records.

The games have to match all the requirements (Black Player, Event, ...) simultaneously. The corresponding string does not have to occur at the beginning of the data (i.e. if you enter 'Chikun' as player, games where Cho Chikun plays will be found).
The 'Anywhere' entry is simply a text search in the SGF file. This allows you to search for the result (use 'RE[W' or 'RE[B'), for games which have a game comment (use 'GC['), etc.

Signature search

In order to check for duplicates in the database, Kombilo computes a modified Dyer signature of every game in the database. The signature of a game is given by the coordinates (in SGF format) of the moves 20, 40, 60, 31, 51, 71. This almost always characterizes a game uniquely.
In order to detect games which differ only by a symmetry of the board, Kombilo uses a symmetrized Dyer signature: the Dyer signatures for the game and for all rotations/reflections of the game are computed, and then the smallest of these (with respect to the lexicographic order) is stored.
You can also search for the signature. This might be useful to see if a certain game is in the database if you have the game record in some (foreign-language) book, say, and cannot read the player's names.
Press the 'signature search' button, and a window will pop up, where you can enter the coordinates of the corresponding moves. If you click on an intersection on the board, the corresponding coordinates will be entered in the currently active text entry below, and the next entry will be made active. So you can enter the signature simply by clicking on the places where moves 20, 40, ... were played. You can also omit some of them (in most cases, two or three of the moves will be enough to characterize a game uniquely).

The database list

For Kombilo, a database is just a directory with SGF files in it. The database list is thus a list of directories. These contain the SGF files in which Kombilo will search for a given pattern.
Before you start working with Kombilo, you have to choose the databases (i.e. you have to tell Kombilo where your SGF files are). This is done in the 'Edit DB list' window (available via the File menu). In this window, the list of databases is shown, and you can

Add databases This lets you choose a directory of SGF files which is then added to Kombilo's database list. Because the SGF files have to be translated into a format which is more suitable for the pattern search, this takes some time.
If you check the 'add subdir's recursively' option, then all subdirectories (and their subdirectories ...) of the directory you choose will be added, too.
The optimal size (i.e. number of SGF files) of the databases depends mostly on the amount of memory in your computer. I recommend a size of 1000-2000 SGF files per database; that should be fine on almost every system. If you have a lot of memory, you can experiment with larger databases, but the performance gains are usually not that big.

Toggle normal/disabled If you want to temporarily exclude a database from some searches, select it and use this button to set its status to 'disabled'. It will then be marked as 'DISABLED' in the database list. Its games will not show up anymore in the game list, and will not be found by any search. Nevertheless, Kombilo's database files written during the processing are still available, and if you toggle the status back to 'normal', you can use that database again without processing it again.

Remove a database If you want to remove a database from Kombilo's list completely, select it and press this button. The database files Kombilo has written will then be deleted. Of yourse, the SGF files themselves will not be deleted (Kombilo will actually never change them.) If you want to add this database again later, it will have to be processed again.

Reprocess a database If you made any changes to the SGF files in one of the database directories (or added/deleted SGF files in there), you should reprocess the database, so that the pattern search really uses the information corresponding to the current version of the SGF files.

Stop processing If you chose to add a lot of subdirectories of some directory at the same time (with the 'add subdir's recursively' option), and see that the processing takes too long, you can interrupt it with this button. The currently processed database will be finished, and then the processing will stop.

Save messages If there are errors in the SGF files, or if Kombilo finds duplicates, a message is issued. The 'save messages' button allows you to save these messages into a file, such that you can look at them later again in order to correct the errors. (After correcting any errors, you should reprocess the corresponding databases.)

With Ctrl-click and Shift-click you can select several databases in the list simultaneously. The "Toggle normal/disabled", "Remove" and "Reprocess" buttons will then apply to all the selected databases.

Changing the order of the databases: You can use "drag and drop" for the items in the database list and thus change the order of the databases. If you sort the game list per database, the order of the databases will be reflected in the game list.

Processing options You can choose to add all files with file names anding in .sgf, or files with filenames ending in .mgt or .sgf, or to add all files in the concerning directories. Furthermore you can have all subdirectories of the chosen directory added, too. Finally, you can specify a place where the Kombilo database files should be written. The default is to write them to the same directory as the SGF files they are associated to. (This choice has to be made before adding the database; it's not possible to change it, later.)

Character encodings If your SGF files are not plain ASCII, but contain other characters, you have to tell Kombilo in which way they are encoded in the file. The best way to do this is with a CA[] tag in the root node of the SGF file (e.g. CA[gb2312]). However, since there are many SGF files out there without the correct tag, you can also tell Kombilo about the encoding when you process your SGF databases.

You have to know in which way your files are encoded, and all SGF files in the directory which is to be processed have to have the same encoding. Choose the encoding from the list, and choose what Kombilo should do with your SGF files.

- Do not change SGF: In this case, Kombilo will not touch your files. It will remember the encoding of the files in this database however, so Kombilo will know about the right encoding.

- Add CA tag: This will add a tag in the root node of the SGF file which contains the encoding of this file. This is probably a good idea if you are sure that you know the right encoding. (Right now, if you have Kombilo add a wrong CA tag, you will have to remove it manually, because Kombilo will always obey a CA tag if present.)

- Transcode to utf-8: In this case Kombilo will replace the SGF file with a transcoded version. CA tag?!

Note: If a file already has a CA tag, Kombilo will not touch it.

In order to use codecs for asian languages (like gb2312 or big5 for Chinese, shift-jis for Japanese or euc-kr for Korean), you have to install the cjkcodecs package. (In the Windows installer, this is already included.) This package may be available as a package in your Linux distribution; for Mac OS X users it is available via fink. Otherwise, you can get it at http://cjkpython.i18n.org/.

The custom menus

The custom menus can be used to add your own menu entries. Upon selecting a menu entry, Kombilo can do a pattern search for some pre-defined pattern and/or a game info search and/or open a html file in your web browser. For example, you could create entries for fuseki or joseki patterns, for players, or for titles.

To edit the custom menus, select the corresponding entry in the Options menu. You see a list of the currently existing menus, submenus and entries. The first line with a * represents the Kombilo main menu. You can add submenus or entries to the menus, or delete them.

When an entry is selected, you can

Guess next move mode

One fun way to study go is to replay professional games by guessing the next move. If you click on the corresponding button in the SGF edit toolbar in the data window, you enter Kombilo's guess mode. That means that clicks on the board will be interpreted as guesses - if it coincides with the next move in the current SGF file, that move is played; otherwise no stone is placed on the board.

When you switch to the 'guess next move' mode, a small frame appears next to the game tree, which gives you some feedback on your guesses. If your guess is right, it displays a green square (and the move is played on the board).
If the guess is wrong, it displays a red rectangle; the rectangle is roughly centered at the position of the next move, and the closer your guess was, the smaller is that rectangle. Furthermore the number of correct guesses and the number of all guesses, as well as the success percentage are given.

Of course, if you just can't find the next move, you can always use the 'Next move' button above the board.

Configuring Kombilo

You can configure Kombilo by changing the options in the options menu.

Edit custom menus See above.

Fuzzy stone placement Place the stones on the main board slightly off the exact point, in a random direction, to make the position look more natural. (Well, some people might think that it is just ugly, so you can switch it off here).

Shaded stone mouse pointer (Don't) Show the current position of the mouse pointer on the board and the color of the next stone to be played by a shaded stone.

Use 3d stones By default, Kombilo uses the realistic looking stone pictures provided by Patrice Fontaine (thanks!). You can switch this off; then Kombilo will use "flat" stones, i.e. just black and white circles.

Show next move In case a SGF file has been loaded, show the position of the next move with a circle.

Show last move This marks the most recent move with a small circle. Thanks to Bernd Schmidt who provideda a patch for this. (The SGF file is not changed.) Show Coordinates Show coordinates around the board.

The 'Game list' submenu:

---Sorting the game list

First of all, in the 'Game list' submenu of the Options menu, you can choose how to sort the game list. For one thing, you can either sort the list per database, or sort the complete list. Second, you can choose the sort criterion: name of white or black player, date or filename.
Having the game list sorted per database and by filename is the fastest, since that is the order in which the data is actually stored on your hard disk. With all other choices, the process of resetting the game list after a search will slow down a bit. Of course that depends on the number of games as well as on your machine, so you have to see yourself which choice is best for you.
Finally, you can reverse the whole game list by selecting the "Revert order" option. So if you would like to sort the whole list by date, with the most current games at the top, you could disable 'Sort per database', choose 'Sort by date', and select 'Revert order'. (Of course, if the file names of your SGF files and the databases reflect the date, as is the case with GoGoD, for example, you should 'sort per database' and 'sort by filename' and 'reverte order', since that's faster).

---Show date/show filename

Depending on where your SGF files come from, it might be interesting to include the filename in the game list (as was done automatically in previous Kombilo versions), or to omit it. Similarly, it might be interesting to include the date (if it cannot be read off from the file name, say, or to omit it). These two options allow you to control this. Changing one of these options will reset the game list.

Invert selection By default, when the relevant region for a pattern search is selected, the rest of the board is grayed out. If you prefer to have the relevant region itself grayed out (as was the case in previous versions), you can use this option.

Uppercase labels If you want to use the 'Export search results' function to produce output for Sensei's Library, it is useful to use lowercase labels for the continuations, since only lowercase letters are automatically understood by Sensei's Library. If you do not want to do that, and find that uppercase labels look better, you can use this option.

Ask before discarding unsaved changes If this option is enabled, Kombilo will ask for confirmation before discarding unsaved changes in an SGF file (i.e. before deleting the game from the game list, and before exiting Kombilo). Jump to match This controls the behaviour of the SGF viewer when you open a game from the game lis tafter a pattern search. If this option is checked, the viewer will jump directly to the position where the pattern you searched for was found in that game.

Smart fixed color If this option is enabled, the 'fixed color' option will be automatically enabled when you select the whole board as search-relevant region, and disabled when you select a smaller region. (You can nevertheless change that after selecting the region and before starting the search.) This is useful because if 'fixed color' is not used, Kombilo regards a position and the same position with swapped colors as equivalent; in the case of whole board searches that can lead to counter-intuitive results when you look at the continuations (e.g. place a black resp. white stone on the upper left resp. upper right hoshi, do a whole board search without 'fixed color', and look at the continuations).

Show color swap If this is active, in the list of results for a pattern search hits for the pattern with reversed colors will have a minus sign.

Advanced: This is a submenu with options that are seldom changed.

Number of previous searches remembered As we have seen, with the 'back' button you can jump back to the previous search. This option controls the number of previous searches that are remembered. The default is 10, and if your machine has only a small amount of memory (less them 64MB, say), you probably should not set it much higher, or Kombilo might run out of memory and crash.
On the other hand, if you have lots of memory, it might be convenient to set it to a higher number, or even to 0, which means 'no limit': all searches are remembered, as long as there is enough memory.

Open game in external SGF viewer: By default, by double-clicking on a game in a game list, the game is opened in Kombilo's main window. (You can open the game in an external viewer, by shift-clicking, though). If this option is active, double-clicking opens the game in an external viewer (v.py or an alternative SGF viewer). In that case, shift-clicking opens the game in the Kombilo main window.

Alternative SGF viewer (Unix/Windows only): If you want to use your customary SGF viewer/editor instead of the viewer coming with Kombilo, enter the command to start it and the command line options that tell it to open a certain sgf file here (put an %f where the filename should be). (If your viewer supports it, you can also put an %n where the move number the viewer should jump to directly should be put.)
For example, on my Linux machine, I could use 

/home/ug/cgoban-1.9.11/cgoban
-edit %f
in order to use CGoban. In order to use WinMGT under Windows, enter something like 
c:\winmgt\winmgt.exe
%f
Of course, in both cases you may have to adjust the path, and possibly the command itself.
If your viewer supports jumping directly to a certain move in a game, you can use %n as a placeholder for the move number of the first hit. Similarly, if your viewer supports SGF collection, you can use %g as a placeholder for the number of the concerning game in the given SGF file.
Delete the command in order to use v.py.

On Windows boxes, the file name is put in quotes. This is necessary if the path contains spaces. If you don't want the quotes (or want to set them yourself), you can use %F instead. (E.g. SmartGo apparently wants file name and move number in the format filename.sgf#123, so in that case you should use %F#%n, or maybe "%F#%n".)

Use C search routine Enable or disable the (much faster) C search routine. If the C search function could not be imported, this option is disabled. See the file install.txt for information on how to install the C search function.
If you have good ideas how to improve the search algorithm, I am very interested in hearing them.

Sloppy SGF parsing If this is enabled, Kombilo will accept SGF files which have multiple occurrences of the same tag in a node, or which have line breaks in move tags. (Both of these are forbidden by the SGF standard, and other SGF readers may not be able to read such files.)

Duplicates This option says what the program should do with games that are already in the database, but are about to be inserted again (by 'AddDB'). You can either completely omit the duplicate check (to save some time during the processing), always accept (but get a warning message) or always reject duplicates, or have the program ask in each single case.
If you use the 'strict duplicate check' option, Kombilo will not only compare the symmetrized Dyer signatures of the games, but also the final positions. This makes is much less likely that different games are shown as duplicates. On the other hand, if the same game occurs twice, but with a different orientation, or with minor errors in the game record, the strict duplicate check will not find it. Thus you probably should use this option only in special cases.

Old Tk version On (some?) Windows9x systems, Python doesn't come with a widget to select a directory. If this is the case for your system, and the 'Old Tk version' option is not checked, the program will crash when you press the 'AddDB' button. If you enable this option, a widget to select a file will be used instead. (See the note above).

Only one mouse button Some Mac OS X users have a mouse with only one button. Using this option, they can mark the search-relevant region with Alt + (left) mouse button instead of the right mouse button.

Do not change window title Usually, when an SGF file is loaded, Kombilo displays the player names as the window title. With this option, you can disable this behavior. (This is useful for BettyGo users; BettyGo is a program written by Max Durbano which provides a user interface to access several go related programs, see http://perso.wanadoo.fr/gib.explore/BettyGo/BettyGo.htm.)

Ask before starting time consuming search Since there is no way to interrupt a pattern search, you can enable this option in order to save you from starting a very time consuming search by accident. (The worst you can do is searching for a search relevant region with only one intersection, and a stone on it. Then (almost) every move in every game will become a match ...)

Customize appearance On choosing this item, you get a window where you can fine tune several fonts, font sizes, and colors that Kombilo uses. See also the section on the global GUI options.

Changing global GUI properties You can change some 'global properties' like background color, type and size of the font used in the game list and in the text windows etc. by editing the file 'kombilo.app' in the main Kombilo directory. This is a plain text file; if you change it, please make sure to save the new version as plain text (ASCII), too. The format of the file should be pretty obvious. Before you change it, make a backup which you can restore in case Kombilo won't start with the changed version.

Installation

To install Kombilo on a Windows system, you can just download the installer and run it. It will copy the Kombilo files to your hard disk, (optionally) create a shortcut in the start menu and/or an icon on the desktop, and you are all set ... and can continue with the Getting started section above.

If you want to use Python for other purposes too, or on other platforms, you have to install Python and Kombilo separately. Read on to learn how to do this.

Installing Python

Python is a high-level programming language. It is freely available from the Python website. There you can also find more detailed information on Python. You may also go directly to the Download area.

If you have to install Python, you should take the most recent version (2.2.2 at the moment). Kombilo will also run under version 2.1.

--- Windows If you are using Windows, just download the Python installer, and run it. It should then only take a few mouse clicks to install Python.
If you are not sure whether you succeeded to install Python properly, here is how you can test it:
Start c:\python22\python in a DOS box (you might have to replace c:\python22 by the path where you installed Python). The python interpreter will then start:

You can quit the Python interpreter with Ctrl-Z plus Return.

--- Unix/Linux The chances are good that Python comes with your distribution, and maybe it is already installed on your system. To check this, just try to start 'python' in a terminal window. The Python interpreter should then start. You also need the GUI toolkit Tkinter. After starting the Python interpreter, you can check if it works as follows:

ug@ugoertz:~$ python
Python 2.1.2 (#1, Jan 18 2002, 18:05:45) 
[GCC 2.95.4  (Debian prerelease)] on linux2
Type "copyright", "credits" or "license" for more information.
>>> from Tkinter import *
>>> root = Tk()
>>>

A small empty window should then pop up. You can leave the interpreter with Ctrl-D. If Python does not come with your distribution, or you want to install a more recent version, download the source tarball and build Python yourself. Detailed instructions are given in the Python README file.

--- Mac OS X Patrice Fontaine wrote a step-by-step description how to get Kombilo working on Macs running OS X.

--- Other platforms Python is available for most current platforms. Unfortunately I cannot give you any hints on the installation procedure, but they should be readily available from the Python website.

Installing Pmw (Python megawidgets)

Pmw is a suite of widgets for the graphical user interface. It is free software; see the Pmw web site. In order to install it, you need to download the file Pmw.1.1.tar.gz and unpack it in the Lib/site-packages subdirectory of your Python directory. (On Unix, you can unpack the file with 'tar xvfz Pmw.1.1.tar.gz', on Windows for example Winzip is able to unpack tar.gz files.) If you are using Linux, chances are good that Pmw is included with your distribution, so you should try that first.

Installing PIL (the Python Imaging Library)

PIL is a library for image manipulation. It is free software; see the PIL web site. For Unix systems, you can download the PIL source from the web site as a tarball, unpack it and follow the install instructions (you have to compile the main library, and can then install PIL by using the Python distutils. If you are using Linux, chances are good that PIL is included with your distribution, so you should try that first. For Windows systems, you should use the installer from the PIL website (PIL version 1.1.2 is fine for Kombilo).

Installing Kombilo

Download the Kombilo archive (kombilo05.tar.gz, kombilo04win.zip or kombilo05.zip, depending on which operating system you use), and unzip it. A new directory named kombilo05 will be created, and the Kombilo files will be put there.

The Kombilo subdirectory should contain the following files: 

kombilo.py, v.py, board1.py, sgfparser.py, 
sgfpars.cc, sgfpars.py, sgfpars.i, sgfpars.h, sgfpars_wrap.cxx,
matchC.cc, setup-ext.py,
kombilo.app, v.app, menus.def, references,
unixinst.py (Unix only)
doc/ license.txt, readme.txt, tutorial.html, 
     *.jpg, onepixel.gif
gifs/ *.gif
If you had installed the prior version of Kombilo, you should nevertheless install Kombilo 0.5 as explained above, in a directory kombilo05. You can just delete the kombilo01/2/3/4 directory. The sgf databases have to be added and processed anew. (If this doesn't work, try to delete the files namelist.db, finalpos.db and lists.db from the directories with SGF files.)

Now you can already try Kombilo: On Windows, start it by clicking on the kombilo.pyw icon in the Explorer (or from a DOS box by c:\python22\pythonw kombilo.pyw).

On a Linux system, simply python kombilo.py should do. You could also make the file kombilo.py executable and if necessary adjust the Python path in its first line. Then you can simply start it directly as kombilo.py

For installation on Mac OS X systems, confer Patrice Fontaine's instructions.

Faster pattern search

Finally, you should install the faster pattern search function. It is not written in Python, but in C++ (another programming language), which makes things a little bit more complicated, but it's well worth it.

--- Windows Download the file Cextxy.zip (where x.y is the version of your Python distribution, i.e. 2.1 or 2.2) from the main Kombilo page. It is important that you take the file corresponding to your version.
Then simply put it in the kombilo04 directory and unzip it (there are two files in it: matchC.pyd and _sgfpars.pyd). That's all you have to do - the fast search function should work now.
If you have got a C++ compiler, you can also compile the C++ extension yourself. Brief instructions how to do this with the free MinGW package based on the GNU C/C++ compiler gcc follow.

If you just want to compile the extensions, you can use the python distutils. In that case, just do 

c:\python22\python setup-ext.py build_ext --compiler=mingw32
(and copy the files matchC.pyd and _sgfpars.pyd from the build\lib.linux-i686-2.2 directory to the main Kombilo directory). If you want to make changes to the files to do experiments of your own, things become a little bit more complicated. The C++ search engine is contained in matchC.cc. It should be straightforward to make changes to that file and recompile it as explained above. On the other hand, the extension containing the SGF parses uses SWIG, a utility to wrap C++ classes as Python extensions. You should only modify the files sgfpars.cc, sgfpars.h and sgfpars.i. The files sgfpars_wrap.cxx and sgfpars.py can then automatically be generated by SWIG. If you have questions about this, don't hesitate to contact me.

Finally, you can also compile the extensions and run Python/Kombilo in the Cygwin environment. In that case you should just proceed along the Linux instructions below. In particular, the '--compiler=mingw32' option is not needed. Compiled extensions for plain Windows respectively Cygwin are not exchangeable.

--- Linux It's probably easiest to compile the extensions yourself using the distutils: 

 
python setup-ext.py build_ext
(executed in the main kombilo directory) should do it: it will create a build subdirectory, and put the binaries matchC.so and _sgfpars.so into build/lib.linux-i686-2.2 (or something like that). Just copy these two files to the main Kombilo directory, and the C++ extensions will work.
You can also download the compiled version from the main kombilo page. (Make sure to download the file corresponding to the Python version that you use.) This is not recommended, though. Because everything you need to compile them yourself is actually installed on your system, you should compile them yourself. I have actually received one report that the binaries from my web site fail in a certain situation on a certain system (but I'm not sure exactly why, yet).

If you want to make changes to the SGF parser extension, the same remarks as for Windows systems apply: you need to install SWIG, and can then change sgfpars.cc/sgfpars.h/sgfpars.i. The files sgfpars.py and sgfpars_wrap.cxx are automatically generated files.

--- Mac OS X Installing the C++ extension on Mac OS X should be easy too. Just start the setup-ext.py script which comes with Kombilo with "python setup-ext.py build".

This will produce two files: matchC.so and _sgfpars.so. Put them in the directory where you installed Kombilo. Kombilo will then recognize them automatically and use the fast pattern search.

--- Other platforms It should not be hard to install the C++ extension on other systems if you have a C++ compiler. But I cannot give you any advice on that. If you succeed to do it, e.g. for the Mac, please let me know. I'd also be glad to put a binary file on my web site.

System-wide installation (Unix)

To install Kombilo system-wide (in /usr/local/share, for instance), proceed as follows:

Put the Kombilo files in /usr/local/share/kombilo05 (if you put them somewhere else, you have to adapt the unixinst.py script accordingly).

Carefully read, and -if/where necessary- edit the script unixinst.py . (I think that you probably will not want to change much.) Basically, the unixinst.py script writes a 'global' kombilo.def file (in the kombilo05 directory) which tells Kombilo to look for individual .def files (in $HOME/.kombilo ) when it is started. So for every user who uses Kombilo, a subdirectory called .kombilo will be created in the user's home directory. In this directory, the individual .def file (which stores mainly the database list, and some additional information about paths etc.) and the .opt file (which stored the saved options), and the .dat files are stored.

Furthermore the unixinst.py script creates a link in /usr/local/bin, pointing to kombilo.py.

After you edited the unixinst.py script, execute it with 'python unixinst.py'. The only other thing you might have to do (if your python interpreter is not in /usr/bin), is to change the very first line of the files kombilo.py, (and v.py if you want to use the viewer separately, too) which must contain the location of the python interpreter, so that kombilo can be started by 'kombilo.py'.

Requirements on SGF files

There are a few requirements on the SGF files that are used in the databases. They will be satisfied by ordinary game records, but might not be satisfied by "strange" SGF files.

First of all, the filename of an SGF file always has to end in '.sgf'.

The program does not handle several game records in a single SGF file. All but the first record are simply ignored.

The program expects that in the game record there are alternating black and white plays. Variations are ignored; only the first (main) variation is followed.

In addition, at the very beginning an initial position can be set up. This is what happens in handicap games, for example. So handicap stones are treated correctly. It is also possible to set up an initial position consisting of black and white stones, like a go problem. On the other hand, "during the game", i.e. after the first black or white move has been played, no stones may be added or removed except for the ordinary alternating black/white moves (and except for captures, of course). In particular, all stones in the initial position have to be set up in the same node of the SGF file. Unfortunately, in a few handicap games of the Go Teaching Ladder, this is not the case; you will have to edit these files manually if you want to use them with Kombilo.

Empty nodes are skipped. When the usual 'black play' - 'white play' - 'black play' ... order is broken, Kombilo will stop processing the game in question at that point. This is another problem with games of the Go Teaching Ladder: in some of them, after a variation forked off a black/white move is not shown with the usual B/W tag, but with a AB/AW tag (which should be used to set up stones like handicap stones). Kombilo will process these games only until the first variation.

All moves after a pass (or after an illegal move) are ignored.

SGF collections: Kombilo's SGF editor can handle SGF files with several games in them, and so can the search engine. Nevertheless it is not a good idea to use games in that form, for performance reasons. It is better to split the collections, and then feed them into Kombilo. The problem with collections is that whenever the SGF file has to be read (for game info searches or to display the game info), the whole collection has to be read from disk, and has to be parsed. The viewer does accept most SGF features, I think. In particular it handles variations (the navigation has to be done by clicking on the concerning points on the board), and adding/removal of stones during the game. It displays labels, but it does not properly display text labels with more than one letter/digit.

It ignores some of the new SGF tags like "good for black", "bad for white", ... .

Kombilo ignores everything before the first '(;'. In particular, it will accept files with am email header and an SGF file after that. Be aware, though, that the header will be lost when you change the game info of that game: whenever Kombilo writes an SGF file, it will only write the game (resp. the game collection) itself. (Do you think that this should be changed? Please tell me!)

Troubleshooting

I am not sure if the following descriptions are too technical. If you have a problem and these hints do not help you, feel free to ask me, and I'll try to help.

The program doesn't start:
First you should make sure that Python is installed properly on your system (see the section on installing python). If Python works, you should try to start Kombilo from a DOS box (with a command like c:\python22\python kombilo.pyw). Then all error messages are written to that DOS box, and they might provide a clue what's going wrong (see below (the program doesn't quit properly ...), though). If you can't solve the problem yourself, feel free to email me; please include any error messages you get as well as a description when the problem occurs.

The program crashes when I press 'Add DB'
This happens if your Python distribution doesn't include a widget to select a directory; as far as I know, this is the case on (some?) Windows95/98 systems. As a work-around, check the 'Old Tk version' option in the Advanced options menu (and save the options). Then 'Add DB' will bring up a widget to select a file, which is always available. In order to select a database, just select any file in the corresponding directory. See this note above too.

The program doesn't quit properly when started from a DOS box
This is a known (and unfortunately non-resolvable) bug on Win9x systems. Sometimes, when you start the program (or any other Python program that uses Tkinter) from a DOS box via c:\python22\python kombilo.py, after quitting the program the DOS box will hang. You can kill it by killing the Winoldap application in the task manager. Unfortunately there are even more processes which remain alive, but which the task manager doesn't show. This may cause Windows to not shut down properly. The bottom line is that you should not start Kombilo from a DOS box, or should use pythonw instead of python. (This problem won't occur after c:\python22\pythonw kombilo.py, but that command will not give you the error messages, either.) More information on this bug can be found here.

Other problems
If you have a problem that is not mentioned here, one thing you could do is to start Kombilo from a DOS box (with a command like c:\python22\python kombilo.pyw). Then all error messages are written to that DOS box, and they might provide a clue what's going wrong. If you can't solve the problem yourself, feel free to email me; please include any error messages you get as well as a description when the problem occurs.

Tips and tricks

I closed the "data window" - how do I get it back?
You can show resp. hide the data window with the rightmost button ("DATA") above the board.

I don't like the "more beautiful" go stones.
You can get back the plain stones by switching the option "Use 3D stones" off. You could also replace the files "black.gif" and "white.gif" in the "gifs" subdirectory with other files.

I'd like to use Kombilo with non-latin (Unicode) characters
Kombilo works out of the box with UTF-8 encoded SGF files (although, admittedly, I didn't test this very carefully).

Command line arguments
You can give file names of SGF files as command line arguments, and Kombilo will open these files upon startup. The file names should be given with the complete path. If blanks occur in the path or in the file name, it has to be quoted.

How can I reset the correct/wrong counter in the "guess next move" mode?
Currently, you can only reset the counter by quitting and reentering the "guess next move" mode.

My screen is too small to arrange the three Kombilo windows without overlap ...
What I found relatively convenient in that case is to place the board window and the game list window next to each other, so that they will (almost) cover the whole screen. If you use only a very small part of the data window, you can place it below the board. Otherwise, you can place it over the game list window and hide resp. display the data window depending on which of the two windows you need.
If you have suggestions how to better arrange the widgets in the Kombilo windows, I'm interested in hearing them.

The search algorithm

What follows is an outline of the search algorithm that Kombilo uses. I am not sure if anybody finds this interesting, but I include these notes anyway. I am certainly interested to hear your suggestions for a faster/more efficient algorithm.

I. Basic algorithm

The first step of each search is to check in which games (and at which positions) the search pattern could have occured given the final position of the game. Then the program plays through all those games which could yield a hit, and checks if the search pattern really occured there.

Thus during the processing of the SGF files, the final position of each game is stored. But because of captures and under the stones plays, one has to be a bit careful here. We do not need the actual final position, but rather a record on which intersections at some time in the game a black (resp. a white) stone has been placed. In particular, in this sense an intersection can "contain" a black as well as a white stone.

To be able to play through the game as fast as possible, the information in the SGF file is translated to a list of moves and captured stones at each move (the information about captured stones is not explicitly contained in the SGF file, and it would take quite some time to check for captures at each move when going through a game).

II. Hash tables

a) The general principle

The one additional feature that is currently used to speed up searches in certain situations is the use of hash tables for joseki and fuseki searches.

Let me explain the principle in the case of a full board search. Hashing means to associate to some data a (numerical) value which is easily computable from the data and which is practically unique. In the case of a go board position, one way to do this, is the following: Create a table which contains a large random number for each intersection on the board. Now, given a position, compute the hash value by adding all the numbers for intersections with black stones, and subtracting those for intersections with white stones. Although it is of course theoretically possible that the resulting number can be obtained starting from several different positions, in practice it uniquely describes the position.

So when Kombilo translates the SGF files to its own format, it computes this hash value for all positions with at most 30 stones on the board (and for certain corner positions; see below). This information is stored in a table, which for each hash value which occurs contains a list of all the games featuring that value. Now if a full-board search with at most 30 stones is requested, Kombilo computes the hash value of the search pattern, looks for the list of games which yield this value, and then searches only through this small list.

b) In which situations are hash tables used?

Kombilo produces (and uses) hash values for the following situations:
- Full board positions with at most 30 stones
- Positions which include at least one 7x7 corner square with at most 25 stones in it.

Index

Analyzing a game
Configuring Kombilo
The custom menus
The database list
The data window
Export search results
Export current position
Export SGF
External SGF viewer
First search
Game info search
The game list window
Getting started
Go to field
Guess next move mode
Installation
More complicated search patterns
New features in version 0.5
One-click mode
Requirements on SGF files
The search algorithm
The SGF editor
Signature search
System-wide installation (Unix)
Tips and tricks
Troubleshooting

Last modified: 16-March-2004 Contact: u@g0ertz.de. To my homepage.