In esse, ex nihilo. Sic vita est.

Documentation

This document includes external links to Wikipedia – the free encyclopedia.  These links normally appear in green (or dark green once visited).  Other external links are indicated by the presence of the corresponding site name in square brackets, immediately after the link.

Please visit the SokEvo home page [fruise.googlepages.com] for the latest version of the SokEvo program and this document.

Contents

• Introduction
• The set-up form
• Set summary page
• Puzzle detail page
• Ancestral history page
• SokEvo Internet submission
• List of existing sets
• Template editor
• Configuration
• Security
• Log files
• Web browsers
• Glossary

Introduction

The SokEvo program is used to evolve Sokoban puzzles.  It runs in the background and can be controlled and monitored using your web browser.

To get started, change the current directory to be the location of the SokEvo program, run the program and then type http://localhost:2015 in the address bar of your web browser.  This should present you with the set-up form which can be used to initiate the evolver.

The evolver starts with a set of templates.  It chooses a template at random, mutates it and then uses a generator to determine the solution, if any, to the resulting puzzle.  The number of pushes (and lines) required to solve the puzzle is used as its fitness.  If the new puzzle is good enough, it will be retained and will displace the worst template or puzzle in the set.

This process repeats, gradually improving the complexity of the puzzles in the set.  Once the desired complexity has been achieved, the evolver can be stopped and a new set started. Each set is intended to produce a single, best puzzle to be played.

Each set has a snapshot file associated with it, which stores all the information required to continue processing it later.  The list of existing sets can be used to continue processing or delete old snapshot files.  The snapshot file for the active set is regularly updated, allowing processing to continue following a reboot or crash.  It is also possible to enable an "auto-restart" so that the last set to be updated continues processing, without having to select it.

For information on program settings, please refer to the configuration section.

For details on accessing the program remotely (via the Internet, for example), please refer to the security section.

The set-up form

The set-up form is used to define the parameters for a new set and initiate processing by the evolver.  It can also be used to make the program exit, by selecting the "Terminate SokEvo server" button.  If sets have already been created, select Existing sets to access the list of existing sets.

To create a new set and start processing it, check the parameters and then select the "Start evolving" button. The parameters are described individually, below.

Title for set

When the set-up form is loaded, a random title is generated automatically.  If a different title is required, either re-retrieve the page by selecting "Refresh" in your browser or overtype the name with a new value.  The maximum title length is 30.

Set titles may consist of any symbol in the Unicode character set, although some symbols may not display correctly when saving a text-only version of a puzzle.  Any non-alphanumeric symbols will appear encoded when looking at the name of a snapshot file directly.

Open limit

The open limit is used to prevent the generator from spending too much time on a template, particularly one that has a wide open space with many permutations but not much complexity.

A low value helps to increase complexity but will limit the maximum number of pushes that are attainable.  A high value may also limit the maximum number of pushes required to solve the resulting puzzles, because they will lack complexity.

A suggested open limit would be in the range from 50 to 150 thousand, although other values are perfectly acceptable.  Note that the value entered is automatically multiplied by one thousand.  If the size of the open list is to be unlimited, leave the value blank.

The default open limit is a configurable value. For more information on the effect of the open limit, please refer to the open list glossary entry.

Population size

The population size indicates how many templates/puzzles should be stored for the set.  Only the best puzzles are retained and a reasonable number should be available to provide enough diversity for the creation of new puzzles.

When an existing template or puzzle is chosen for mutation, the best entry has the greatest chance of being chosen and the worst is the least likely to make a contribution – so the population does not need to be large.

The default population size is a configurable value.

Memory

The generator requires memory for its transposition table, which is used to keep track of pushes to be expanded (an open list) and those already dealt with (the closed list).

Where little memory is available, 64 MB should be sufficient, otherwise 128 MB is typically required.  The amount of memory specified may be between 1 and 999 MB, but is limited by a configurable setting for security reasons.

If the amount of physical memory required is not actually available then the computer will attempt to use virtual memory.  The computer will move the generator's data to its hard disk but, unfortunately, will have to move it back into memory almost immediately because the generator will be constantly accessing it, essentially at random.

The memory setting has a default configuration value, as well as a configurable security limit imposed upon it. Note that the actual memory used will greater than that specified, increasing gradually with the age of the active set.

Maximum boxes

In a Sokoban puzzle, complexity is mainly introduced by obstacles – usually in the form of a lot of boxes and walls.  Rather than allow a lot of boxes to dominate, creating difficult puzzles, there is the option to choose a "maximum boxes" value.  This can have the effect of increasing the number of wall cells to compensate for the lack of boxes, producing puzzles of medium difficulty that are still quite complex. If the number of boxes is to be unlimited, leave the value blank.

The default maximum number of boxes is a configurable value.

Fast mutations

When generating a new template from an existing template or puzzle, there is a very high probability that SokEvo will apply only one or two mutations, with a much lower chance of additional mutations.

If fast mutations are selected, then a minimum of 2 mutations will be applied every time, otherwise the minimum will be 1 mutation.

Single mutations can often result in great improvements but there is a danger that the diversity of the set will become too low and multiple mutations may become a necessity for improvement.  However, making multiple mutations all of the time could cause the evolver to miss single changes that give an obvious or significant benefit.

The default setting is a configurable value.

Use a template

The template editor can be used to pre-define the initial puzzle template used to seed the population.  Enabling this option brings up a drop-down list of saved templates and hides the options that are not relevant when a template is to be used.  Choose a template in order to use it instead of an empty or random population.

Puzzle size

SokEvo treats each Sokoban puzzle as a rectangular area.  All entries in a set have the same number of rows and columns.  The height and width specified indicate the number of cells, excluding the outer wall.

The minimum size measures 2 rows by 2 columns.  The maximum is 50 rows by 50 columns.  Neither the minimum nor maximum area is a sensible choice, however.

Please note that SokEvo is only capable of creating complex puzzles when the area is relatively small.  For example, a puzzle measuring 6 by 12 cells or 9 by 9 cells would be reasonable, but one measuring 13 by 13 cells is unlikely to be of any interest.  However, it is possible to produce high quality puzzles with a large area by using a small open limit – for example, 75 thousand – and also by selecting the number of lines (with pushes as the tie-breaker) as the fitness type, rather than using pushes (with lines as the tie-breaker).

As the puzzle size increases, so does the amount of processing required.  If the computer being used is slow, it would be sensible to try creating puzzles with a height and width of only 6 or 7 cells before trying larger areas.

The default height and width are configurable values.

Random walls

When the evolver first starts, the new set is populated by templates rather than actual puzzles.

If random walls are selected, these templates will be relatively complex and limit the initial movement of boxes as a result of randomly scattered wall cells.  As the evolver progresses, some of these initial walls may be removed which allows the active area to gradually increase.

If no random walls are used, the initial boxes will be able to roam freely and the number of permutations will be very high, causing the evolver to work much harder to introduce complexity.

The default setting is a configurable value.

Goals

When the evolver first starts, the new set is populated by templates rather than actual puzzles.  These may contain no goal cells or a random scattering of goals.

It is also possible to choose between puzzles that contain randomly placed goals or restrict the set to contain only puzzles that have a single target area, where all the goal cells are linked together – in which case the initial templates will contain no goal cells.

• A single target area can be anchored in the middle of the puzzle.  This is achieved by starting the templates with a single, immutable goal in a central cell – which the target area then spreads out from.  The effect is normally only apparent when the puzzle size is large, but such puzzles tend to include unused areas – which means that the target area is not always central to the active area.  These options are not applicable when a pre-defined template is used.
• For single target areas, the template may occasionally result in a puzzle where a box either cannot move or does not need to move to reach a solution.  In this case the simplified version of the puzzle will contain a wall, which might break the goals into two or more target areas.  To avoid keeping such puzzles, choose a strict single area.

Fitness type

This option gives a choice of fitness calculation to apply when comparing a puzzles to determine which ones should be kept and which should be discarded.  Only the best puzzles are retained in the population, and the best are those with the highest fitness value.

There are two choices, as follows.

• Use the number of pushes, with the number of lines as tie-breaker – this selects for puzzles that have long solutions.
• Use the number of lines, with the number of pushes as tie-breaker – this selects for puzzles where the number of "lines" is maximised, which might result in puzzles with greater complexity.  In the long run, the number of pushes will be forced up by the number of lines.

It is recommended that the second option is chosen where a large, unconstrained puzzle is being produced.

Start evolving

If the set-up form contains valid values, choosing the "Start evolving" button will initiate the evolver.  The set summary page will be displayed for the new, active set – the set-up form will only be displayed again when the evolver is stopped.

Set summary page

The set summary page lists the values used to define a set (as entered on the the set-up form), the current statistics for it (described individually, below) and provides a table that indicates the number of pushes and lines required to solve each (retained) puzzle generated so far.  Each entry in the table is a link to the corresponding puzzle detail page, which allows the puzzle itself to be viewed, saved and played.  Please note that some links – particularly those at the end of the table – may expire when they are replaced by new entries.

• If sets have already been created, select "Existing sets" to access the list of existing sets.
• If the evolver is currently processing a set, the "Stop evolving" button can be used to stop the evolver and return to the set-up form.  If the current summary page is for the active set, this will be indicated – otherwise the name of the active set will be given as a link to its summary page.
• If the evolver is idle, the "Terminate SokEvo server" button can be used to make the program exit.

The entries in the table are highlighted to roughly indicate which "family" each puzzle (or template) belongs to – those with the same background are living relations, and are more likely to share features with each other than with members of other families.  Only the 15 largest families are highlighted.  SokEvo attempts keep the highlights consistent between page refreshes, but the backgrounds may change dramatically when the oldest living member of a family dies – in which case the remaining members will be split into new, separate families when no common ancestor remains – and when re-loading a snapshot file.

The number of columns in the table of puzzle links is a configurable value.

Created

The created date and time indicate when the parameters for the set were submitted.

The date is always shown in ISO 8601 format, i.e. YYYY-MM-DD, with the time as HH:MM:SS.  No time zone is shown.

Updated

For the active set, the updated value will show the elapsed time since its snapshot file was last saved.  For other sets it will be the date and time that the corresponding snapshot file was last updated (according to the computer running the SokEvo program).

The date is always shown in ISO 8601 format, i.e. YYYY-MM-DD, with the time as HH:MM:SS.  No time zone is shown.

Elapsed time

The elapsed time value is the total amount of processing time that has passed for the set, including that from any previous sessions (where the snapshot file has been used to continue processing).

Last addition

The last addition value indicates how much processing time has passed since the table of best puzzles was last updated.  Note that this includes time from any previous sessions.

For the active set, the page will refresh based on the last addition value.  The refresh rate is limited by configuration settings.

Best found

The best found value indicates how much processing time has passed since the first entry in the table was created.  Note that this includes time from any previous sessions.

Ancestors

The ancestors value indicates the total number of templates processed, including those trivially rejected without use of the generator as well as the current population. An ancestor list is used to ensure that each template is only processed once.

The rate shown is the number of ancestors divided by the elapsed time.

Uniformity

The uniformity value is the number of pushes for the worst puzzle (in the current population) as a percentage of the number of pushes for the best puzzle.  It is intended to provide a simple measure of progress.  A high percentage indicates a lack of diversity.

Note that the uniformity can go down as well as up.  If the best puzzle cannot be improved upon, the uniformity will go up as minor improvements on the existing puzzles are found and replace the worst entries.  Often SokEvo will demonstrate punctuated equilibrium, in which case the uniformity value may go down dramatically when a major improvement is suddenly found.

As a rough guide, the best puzzle is normally quite complex when the uniformity indicator reaches 70% or 80% and the probability of improvement decreases noticeably between 90% and 95%.  It is unlikely that the uniformity indicator will actually reach 100%.  Also, although using a faster computer will increase the rate at which a set progresses, the extra speed typically allows larger puzzles (with more rows and/or columns) to be produced in around the same amount of time as a smaller set would take on a slower computer.  Taking this into account, each set typically requires around 30–40 hours to reach its peak, regardless of the computer's speed.  However, both trivial and significant improvements can still be found after 40–50 hours.

In deciding when to stop processing a set, it may also be useful to take account of the elapsed time and the times since the last addition and the best puzzle was found. Please refer to the reasoning behind the evolver design for further details.

Puzzle detail page

The puzzle detail page provides access to the statistics of a specific puzzle (or template) within a set, along with the puzzle itself and any associated solution.  It also provides options to play the puzzle, change the way that it is presented and to save it to file.

The puzzle itself is shown both graphically and as text.  The graphical version may not be shown by some browsers, for example the text-only Lynx web browser. The text version should always be displayed and is represented in the standard Sokoban notation.

If JavaScript is available and enabled, then you can use your keyboard and/or mouse to play the puzzle directly on the page.  The puzzle's solution is pre-loaded into the move history, allowing you to step through it by repeatedly using Redo.

If a solution is known, it is shown as a sequence of moves represented by the letters L (left), R (right), U (up) and D (down) – with upper case letters indicating where a box is to be pushed.  Note that the solutions found by the generator are push-optimal and may require significantly more moves than the minimum possible.

The length of each solution line is a configurable value. Also, the page may be configured to hide the solution by default.

Statistics

The number of pushes and lines relate to the solution for the puzzle shown. They are used to calculate the relative fitness of the puzzle as compared with the others in the same set.

Each puzzle is the result of taking a template and repeatedly applying one or more mutations to create a new puzzle. The number of ancestors indicates the number of related puzzles that were processed before reaching the one shown, and the number of mutations is the total number of mutations applied to them.

The "found after" value is the total amount of processing time that passed before the puzzle was found, including that from any previous sessions (where the snapshot file has been used to continue processing).

Share via permanent link

This URL associated with the Share via permanent link can be used by anyone with Internet access, to play the puzzle directly in their web browser.  You can use this yourself, to keep a puzzle which may otherwise be lost, and send it to other people to play without them having to load the puzzle into their own software.

Note that this option may not be useful in all browsers, for example a text-only browser.  For more information, please refer to the web browsers section.

Download text-only version

Downloads the puzzle by itself, with a file name extension of "xsb".  The file is plain text, containing a title line followed by the puzzle itself in standard Sokoban notation.

Typically a web browser will ask if the file to be downloaded should be opened or saved to a file.  It may be possible to configure the web browser to open the puzzle in an editor, or to pass it to the game program that is normally used to play Sokoban puzzles.  The file will have an content type of "application/x-sokoban" which can be used to associate puzzles with the program to run.

View ancestral history

The view ancestral history link opens the ancestral history page for the current puzzle, which allows you to view all of the mutations leading up to the selected puzzle itself.

Switch to raw version.
Switch to simplified version.

By default, the puzzle is simplified before it is displayed. This means that the solution is used to determine which cells actually contribute to the active area.  Those that do not contribute are converted to either wall or floor cells as appropriate.

The "switch to raw version" option re-displays the puzzle as it is actually stored by SokEvo (and in the snapshot file).  When the raw version is shown, the option changes to read "switch to simplified version". The raw version always includes a fixed outer wall.

The initial method of display is a configurable value. There is also a configuration setting to allow unused areas to be shown as wall cells rather than floor cells.

Upload this puzzle to the SokEvo Internet community

Puzzles with at least 100 pushes in their solution may be uploaded to the Sokoban Internet community.  Use this link to acccess the SokEvo Internet submission page for the current puzzle.  Note that the link will be hidden for all puzzles with less than 100 box pushes in their solution.

Ancestral history page

The ancestral history page displays the complete history of evolutionary stages leading to a puzzle, starting with the first mutations and ending with the puzzle itself.  If JavaScript is enabled, the option to step through the history using the J and K keys is given.

A link is provided to switch between the raw and simplified versions of the puzzles, in the same manner as on the puzzle detail page.  However, unused rows and columns are retained to allow easy comparison when stepping through the history.

The Share/play link against each puzzle in the history is equivalent to the sharing link on the puzzle detail page.

The number of pushes/lines in the history may go down in some cases, rather than always increasing.  This simply means that a puzzle was good (or fit) enough to be added to the population at the time it was discovered, even though it was worse than its immediate ancestor.

SokEvo Internet submission

The SokEvo Internet submission page is used to share a selected puzzle with other Sokoban players.  Submitted puzzles are stored in an on-line database.  Only puzzles with at least 100 pushes in their solutions may be uploaded.

Once a puzzle has been submitted it can only be removed by the administrator, so please only upload one or two puzzles from each set which you believe are worth sharing with others – e.g. those which have had 10 or more hours of processing time dedicated to them.

List of existing sets

The list of existing sets displays the titles of snapshot files, each of which is a link to the corresponding set summary page.  An option is provided to delete each file (excluding the active set if the evolver is currently processing a set) which will ask for confirmation.

If the evolver is idle, an option is provided against each snapshot to continue processing it.  If chosen, the snapshot file will be loaded into memory and the evolver will continue processing it.

Template editor

Although SokEvo is perfectly capable of producing complex puzzles with very little set-up, it also provides a template editor which can be used to pre-define part of the structure of the puzzles in a set.  For example, the positions of the walls can be pre-defined and (if required) locked to prevent later mutation.

Note that JavaScript must be enabled in order to use the template editor.

The editor page consists of 3 main areas.

• The list of stored templates on the left-hand side of the page.
• The template currently being edited in the middle of the page.
• A control panel above the template, which allows the current cell type to be chosen or a lock/unlock action to be selected.  This panel also shows the undo and redo options when applicable.

The editor automatically saves each and every change as it is made, including the edit history.  Usually this will be instantaneous, but may take a noticeable amount of time if there is a problem with the network and/or the or the data has to be sent over the Internet.  An indication is given when the template is being saved, but it is not necessary to wait before making further edits.  However, if the saving of the template appears to get stuck it may be necessary to re-load the page (in which case the latest changes will be lost).

Template list

• Selecting on a template name will open it for editing.  If the name of the template already being edited is selected then an edit box will be shown instead, allowing the name to be changed – press Enter to save the new name.
• Click on the + (plus) icon above the list of template names to add a new template.
• Click on the red deletion icon next to a template name to discard that template.
• Click on the duplication icon above the list of template names to make a copy of the template currently being edited.  The new template will be opened automatically.

Edit area

• Clicking on a cell in the main edit area in the middle of the page will either change its type or lock/unlock it.  The action to be taken should be selected in advance using the control panel, described below.
• New rows and columns can be inserted by clicking on the appropriate + (plus) icons to the left of and above the main edit area.
• Unwanted rows and columns can be removed by clicking on the appropriate red deletion icons to the right of and below the main edit area.

Control panel

• The current cell type can be chosen as either a floor, box/goal or wall.  Note that boxes always start on their goals, and the generator is designed to pull them as far as it can from their initial positions as defined in the template.
• Click on the locked padlock to enter locking mode, or click on the unlocked padlock to enter unlocking mode.  If a cell is locked, it is shown with a red border and will be immutable – i.e. its type will not be mutated by the evolver.
• If changes have been made, click on the left-pointing arrow on the left-hand side of the control panel to undo them.  Similarly, use the right-pointing arrow on the right-hand side of the control panel to redo any edits previously undone.

By default the cells are shown with a slight spacing so that locked cells can be highlighted with a red border.  The size of this spacing can be changed using the controls in the top-left corner of the editor page.

Configuration

When SokEvo starts, it loads its configuration from a file called SETTINGS.txt.  If this file does not exist, it is created by renaming the file called DEFAULTS.txt which is provided with SokEvo – this is to allow a newly-downloaded version of SokEvo to overwrite an old installation without losing existing settings.

Edit the configuration file to have the desired values before starting SokEvo.  If the configuration is changed, SokEvo must be restarted to pick up the new values.

Configuration names and values may also be specified on the command line, in which case the command line value takes precedence.  Options take the format <name>=<value>, for example memory=64.

If a setting is not specified in the configuration file and does not appear on the command line, the default value listed for it will be used.

For further details, please read the comments against each option in the configuration file.

Security

Since SokEvo includes its own web server which is designed for use with a web browser, it is important that it is installed and configured correctly to avoid or limit risk to the computers involved.

By default, SokEvo will only allow access from a web browser, or other client program, that connects from the same computer – known as the local host.  If a request originates from a computer with a host name of localhost or has the IP address 127.0.0.1 then it will have full access to the SokEvo program.  You may also find that access to the SokEvo server port (which defaults to 2015) is blocked by your computer's firewall and/or router/modem, and you should take steps to ensure that such blocks are in place when needed and removed when wider access is required.

If access is to be granted to other computers – over a local area network and/or the Internet – then special care must be taken to limit that access.  In particular, SokEvo will serve files placed in the Public directory (although it does so without any URL encoding translation).

The most important security setting is called MaxMemory.  When a request is made to start the evolver, the amount of memory allocated to the generator can never be greater than MaxMemory – even if an existing snapshot file is used to continue processing.  If the amount of memory requested exceeds the amount of physical memory then the computer serving the requests may become unstable, unresponsive or even crash.

Access to SokEvo by individual computers may be controlled by listing their host name and/or IP address in one of three configuration files, as described below.  Where a computer's host name is not known, it may be determined by use of the log files.

Access to SokEvo may be divided into the following three categories.

1. Full access and control
2. Read-only access (allowed access – but only to view pages, no control)
3. No access, no control

These three types of access may be configured as described in the following sections.  Please remember that changes to the configuration will only take effect when the SokEvo program is started – the program should be terminated and restarted if it is already running.

Care and effort has been taken to make SokEvo as reliable as possible – particularly ensuring that buffer overflows are unlikely. However, it is possible that a flaw may be discovered that allows an individual to gain control of the computer running SokEvo.  It is important to limit access in the first instance, but note that the use of any networked program – including SokEvo – carries some risk.  Please refer to the web_browsers section for more information.

Full access and control

Full access and control may be granted in two ways.  It is recommended that both mechanisms are used together.

First, if the connecting computer's name or IP address is listed in the AdminHosts configuration value, then it is automatically able to retrieve details and control the SokEvo program.

Second, if the connecting host is listed in the AllowHosts configuration value, it is automatically able to retrieve details.  However, in order to control the SokEvo program, the correct user name and password must be provided.  If the password file does not exist, access will be forbidden to any computer that attempts to control the SokEvo program and is not listed using the AdminHosts configuration value (see above).

There is no default user name or password – one must be defined, on the computer running the SokEvo program, by creating a file called PASSWORD.txt in the installation directory from which the SokEvo program starts.  The first line of this file should be the user name and the second line should hold the password.

The password file is recreated (if necessary) by SokEvo when program starts and also when a request is made that requires a password.  The first two lines become blank and the third line holds the MD5 hash corresponding to the original user name and password.  For security, password-based access should be tested at the earliest opportunity to ensure that the user name and password are held in their encoded form.  Longer, more complex passwords provide better security than short, simple ones.

Full access may be granted by use of a user name and password only, by giving a blank AllowHosts value.  If no password is defined and the AllowHosts value is blank, then there will be no authentication at all – this method is not recommended and will produce a warning message.

Note that any host that appears in the DenyHosts configuration value will be denied all access regardless of any other setting.

By default, SokEvo uses digest access authentication, which means that the password is not sent directly across the network but is instead checked by use of MD5 tokens (which have a configurable life-time).  However, some web browsers, for example Lynx, do not support this method of authentication.  The option is provided to configure SokEvo to enable the basic authentication scheme, which assumes that there is a secure, trusted connection between the computers being used – otherwise the user name and password may be intercepted as they are passed from one computer to another.  Basic authentication is disabled by default, but if it is enabled then the more secure digest method should still be used by web browsers that support it.

Read-only access

Where access is to be granted to view pages but no control of the SokEvo program is to be permitted, the computer's name and/or IP address should be listed in the AllowHosts configuration value.

Provided that the computer does not also appear in the AdminHosts configuration value and either no user name and password is defined or the person using that computer does not know the correct user name and password, they will not be able to control the SokEvo program.

Access may also be granted implicitly by giving a blank AllowHosts value, which allows any computer to connect.  This setting is not recommended.

Note that any computer that is listed in the DenyHosts configuration value will be denied all access regardless of any other setting.

Please refer to the full access and control section, above, for more information about access lists and control using a user name and password.

No access, no control

A computer may be denied all access to SokEvo by listing its name and/or IP address should be listed in the DenyHosts configuration value.

Other computers may be able to access or control the SokEvo program if the settings allow them to.  Please refer to the full access and control and read-only access sections, above, for more information.

Log files

SokEvo always logs any system errors that occur.  By default, if an incoming request results in an error (either a failed operation or an authentication failure) then the host name and response will be logged.

Errors are written to the standard error stream (stderr), messages associated with a web request are written to the standard output stream (stdout).

It may be useful to change the configuration to log all requests, for example to log a host name so that it can be entered into the security configuration.

Web browsers

SokEvo is designed to be as simple as possible, both for security and to ensure compatibility with the maximum possible number of web browsers.  Specifically, it uses simple, validated [validator.w3.org] HTML.

SokEvo does not rely on nor require the use of any of the following technologies.

• Cookies
• Cascading style sheets
• Flash / Shockwave
• Frames
• Java
• JavaScript

A few of these technologies are used to improve the program, mainly Javascript and CSS, but they are not required for the creation of puzzles.

• The template editor is written entirely in JavaScript and should be hidden if JavaScript is not available or is disabled.  Existing templates are always shown on the set-up form.
• A JavaScript implementation of the Sokoban game, called Crossoban, may be used to play candidate puzzles on the puzzle detail page and using the sharing link on that page.
• The ancestral history page uses JavaScript to allow stepping through the entries and changing the scale of the images.
• The set summary page attempts to automatically refresh itself when viewing the active set – this may not be supported or may be disabled, although the page may be refreshed manually.

In spite of the simplicity and validity of the pages served by SokEvo, some web browsers may still fail to display them properly.  If this occurs it is recommended that a later version of the browser is tested if one is available.

It is also recommended that all versions of Internet Explorer should be avoided (for whatever purpose), due to the significant number of security problems associated with it and Microsoft's inability to correct them.  The US Department of Homeland Security has released a recommendation [www.kb.cert.org] that any other browser should be used instead.

Glossary

Active area

The active area of a puzzle consists of the cells that are actually involved – and required – when solving the puzzle.

Because SokEvo uses random numbers in the process of creating new puzzles, some cells may not be required by the simplest solution. These may include floor cells that the player can reach and/or boxes that may start on a goal cell and do not need to be moved to solve the puzzle.

Some of these cells may become useful to the evolver when producing new puzzles and are retained, however a simplified version of a puzzle can be displayed which takes the solution into account.

Active set

The evolver may either be inactive or it may be processing a single set, known as the active set.

It is possible to process multiple sets simultaneously on one computer, by running the SokEvo program twice and specifying two port numbers, but it is not possible to update the same set. This should only be done if the computer has multiple processors – or similar technology such as hyper-threading – and extra care should be taken to ensure that sufficient memory is available.  It is also possible to delete the active set from one instance of the program using the other, so care must be taken to avoid the resulting loss of data.

Ancestor list

Each template produced by the evolver is entered into an ancestor list which allows it to avoid wasting time processing the same template again for the same set.

The ancestor list is saved in the snapshot file associated with a set.  It gradually results in additional memory being required and a larger file being saved.  The total number of ancestors is shown on the set summary page.

Auto-restart

If the AutoRestart configuration option is enabled, SokEvo will access the most-recently updated snapshot file and continue processing it soon after the program is started.  If the option is disabled, the the set-up form will be available instead.

The processing may continue immediately or the Delay configuration value may be used introduce a pause that allows the computer to finish starting-up and loading other applications.  It will not be possible to access SokEvo (with a web browser) during this delay.

Cells

A cell is an individual element of a Sokoban puzzle.  It may be filled by a wall, or it may be a floor cell – possibly marked as a goal.  A floor cell may be empty, contain a box or be the current location of the player/pusher.

Please refer to the standard Sokoban notation glossary entry for more information.

Closed list

During a search, the closed list refers to a table containing items already processed, used to avoid duplication of effort and to prevent endless reprocessing of the same items.

The evolver uses a form of closed list, known as the ancestor list, to track which templates have already been processed.  The generator implements a closed list as a transposition table, to track which game positions have already been visited when testing combinations.

Evolver

The evolver creates new puzzles by repeatedly mutating the template for an existing member of the population and testing the fitness fitness of the resulting puzzle produced by the generator. If the new puzzle is good (or fit) enough, it will be kept and the worst entry in the population will be discarded.  Usually the evolver will continue this process almost indefinitely, though it is possible for it to mark a set as "complete" if there do not seem to be many possible mutations for it to try.  For example, if the puzzle size is very small or the maximum number of boxes is low then the evolver might quickly give up.

The evolver implements the process of evolution in its simplest form.  It is intended to demonstrate the emergence of complex "designs" from little more than random numbers – used to create novel mutations – and a trivial selection mechanism.  SokEvo does not use recombination (also known as crossover) nor does it use any intelligence to choose mutations (other than to filter out those that would have no effect, in order to save time).

For comparison, try the full version of Brian Damgaard's YASGen [sourceforge.net] program which implements a genetic algorithm that is capable of both generating new Sokoban puzzles and improving existing ones.

Fitness

SokEvo evaluates uses the number of pushes required to solve a puzzle as its fitness value, with the number of lines as a tie-breaker – or the reverse, where the number of lines takes precedence.  Note that the solutions found by the generator are push-optimal and may require significantly more moves than the minimum possible.

The fitness is used to determine if a puzzle should be added to the set's population or discarded, as well as to give the best puzzles the greatest chance of being chosen by the evolver when testing new mutations.

Generator

SokEvo uses a built-in version of Brian Damgaard's YASGen [sourceforge.net] program as a generator to produce new puzzles from templates.

The generator places a box in each goal cell and pulls (rather than pushes) all of the boxes as far as possible, trying every possible state permitted by the memory available to it until all permutations have been tried or the open limit is reached.  The state with the best solution is returned to the evolver as a new puzzle to be evaluated, based on its fitness.

Using a generator is considerably more efficient than simply creating a puzzle and attempting to automatically solve it, for two main reasons.  First, the final position of the boxes is determined during the search – and the search effectively examines many puzzles in one go.  Second, the resulting puzzle is guaranteed to have a solution, whereas a randomly-mutated puzzle might not.  If no solution existed for a puzzle, attempting to solve it might require an enormous number of permutations to be tested which would waste a considerable amount of processing time.

Lines

The number of lines in a solution refers to the number of times that any box is pushed consecutively in a straight line, ignoring the actual number of pushes made in each direction.

For example, if a box is pushed 3 times in one direction, then 2 times in another then this would count as 5 pushes but only 2 lines.  (Some people refer to "runs" rather than lines).

Open list

During a search, the open list refers to a table containing items waiting to be processed.  Each level of a search may result in a number of different possibilities, so all are placed in the open list and taken off one at a time, each potentially producing several new entries to take their place in the open list.  The open list will dynamically grow and shrink, eventually exhausting all permutations.

The generator implements an open list as part of its transposition table – as a subset of the states in its closed list.

Outer wall

To prevent the player/pusher and any boxes from leaving the Sokoban game area, all puzzles require wall cells to enclose their floor space, surrounding the active_area.

SokEvo always uses a fixed outer wall whose position is based on the height and width associated with the set.  However, when showing the simplified version of a puzzle the wall may be shrunk to enclose only the area that is relevant to the solution.

Processing time

The phrase "processing time" refers to the total amount of time that has elapsed while the evolver has been active. SokEvo only measures and displays the actual amount of time taken, even if it is being slowed-down by other processes.

For example, SokEvo might run for 4 hours but only get half of the computer's processing power, in which case only 2 hours of actual processing would have occurred.  In this case, SokEvo will still show 4 hours as having passed – not 2.

Pushes

The solutions to puzzles produced by the generator are push-optimal – the number of pushes shown indicates the minimum number of box pushes that are required to solve a given puzzle.  Note that the solutions shown may require significantly more moves than the minimum possible.

Set

Rather than simply producing a single puzzle each time it is used, SokEvo maintains a population of the best puzzles that it has found so far for the parameters given.  Each population and the details associated with it are referred to as a set.  However, once a set has progressed far enough the intention is that one of the best puzzles should be chosen and played.  When then puzzle has been saved, the set may be deleted.

SokEvo saves each set to a snapshot file, which allows the processing for any given set to be continued at a later time.  Previously-created sets may be listed and accessed using the list of existing sets.

Snapshot file

The snapshot file for a set contains all of the information required to continue processing it at a later time.  It may also be used to view a summary of the set and examine the detail of each puzzle in it.

The snapshot file contains only plain text and may be viewed using an external editor, though it should not be amended to avoid corruption. The file contains three major sections, as follows.

• Set header, containing parameters and statistics.
• The current population of templates and puzzles.  Each is preceded by a header that includes the solution for a puzzle.  The puzzles are stored in standard Sokoban notation with a fixed outer wall.
• The ancestor list, which is stored as a set of MD5 hashes reduced to 64 bits and encoded in base-64.

Standard Sokoban notation

Sokoban puzzle files are conventionally written in the X-Sokoban format, usually stored with an XSB file extension. If a single target area is used, then non-standard cell types may appear in the corresponding snapshot file to indicate that a central goal cell is immutable.  The definition of each cell is represented by a symbol as shown in the following table.

Some people refer to the basic cell elements by other names.  For example, a box might be instead called a stone or a block, a goal could be called a destination, target, storage spot, etc.  SokEvo refers to a group of connected goal cells as a 'target area'.

Template

The generator places a box in each goal cell and pulls (rather than pushes) all of the boxes as far as possible.  The evolver starts with a template that it passes to the generator, which returns a new puzzle and its solution.

A template differs from a puzzle by having all of its boxes placed in goal cells and it has no player/pusher.  The player's position is determined by the generator.  When the evolver first starts, a set will consist entirely of templates.  When a puzzle is mutated, only its original template is actually used.

© 2009 Lee J Haywood [fruise.googlepages.com].
This page has been validated [validator.w3.org].

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation Licence [www.gnu.org], version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the licence is included along with the SokEvo program.