==============================
  About Sat4j launcher with on the fly configuration
==============================

The on the fly feature has been developed to allow interactive resolution.  
For a specific instance, non-specialists users can have an idea of
what configuration is the most adapted. 
This tool is still in development and might not be totally robust. 
Please report bugs to daniel.leberre@cril.fr or stephanie.roussel@cril.fr.

==============================
  Running Sat4j with on the fly configuration
==============================

To run sat4j with on the fly configuration:

   java -jar sat4j-sat.jar -remote

These instructions should open a java window named Remote Control.  We
assume that the 1.5 version of the java command is in your path.  If
it isn't, then you should either specify the complete path to the java
command or update your PATH environment variable as described in the
installation instructions for the Java 2 SDK.

In order to visualize the different metrics, gnuplot 4.6 is
required. Gnuplot's version can be checked by running it in a
terminal. On top of that, gnuplot should be compatible with launching
a X11 terminal. To see all available terminals of gnuplot, type "set
terminal" in a gnuplot console.


==============================
  Features
==============================

Features depend on the version of sat4j (this version is displayed at
the top right corner of the remote window). Documentation on solvers and
strategies can be found on http://www.sat4j.org/doc.php

--------------
1. Main window

The main window contains 5 tabs: Solver, Restart, Heuristics, Learned 
Constraints and About Solver. It also contains a console where information 
about configurations and solver runs are displayed. If no solver is running, 
only options on tab Solver should be editable. 

--------------
2. Menu bar

The menu bar contains two components : File and Preferences.
In the file menu, it is possible to activate or deactivate gnuplot. 
Activate gnuplot opens a x11 terminal as soon as a solver is running.
Deactivate gnuplot closes all gnuplot windows and does not open any one 
when starting a solver.

Gnuplot preferences can be customized in the Preferences menu. 
Available gnuplot options are: 
 - background color (black by default)
 - foreground color (white by default)
 - use or not use sliding windows (checked by default)
       if use sliding windows is not checked, it is expected that the
       solver becomes very slow after running a few minutes
 - number of lines to display (11000 by default)
       this feature is only available if use sliding windows is checked.
       it is recommended to display at least 2000 lines (it won't be possible 
       to see anything otherwise) and not to display more than 25000 lines 
       (the solver might become very slow otherwise)
 - time before launching gnuplot (8000 by default)
       if gnuplot and the solver are launched exactly at the same time, then 
       some of the files gnuplot is plotting might not exist yet. 
       Thus, a few seconds should elapse before starting gnuplot. The default 
       time is 8000 ms, it is recommended not to go under 3000 ms. 
       Waiting more than 10000ms is not useful.
 - displays restarts (checked by default)
       if checked, restarts are displayed by a vertical bar on the different graphs
 - restart color (dark gray by default)
       allow to change the color restarts are displayed with. 
       
The second set of options selects the graphs that gnuplot displays when 
the solver is running: 
 - clauses evaluation (checked by default)
 - size of learned clauses (checked by default)
 - decision level when a conflict occurs (checked by default)
 - trail level when a conflict occurs (checked by default)
 - index of decision variables (checked by default)
 - number of assignments per second (unchecked by default)
      the number of assignments per second is highly dependent on the number of 
      processes running at the same time. More precisely, the number of assignments 
      per second might be lower if too many graphs are displayed.
      If checked, it is recommended not to display too many other graphs. 
 - variables evaluation (checked by default)

--------------
3. Solver Tab

This tab contains two panels : instance and solver.  
On the instance panel, the instance of the problem can be specified. 
If an instance was given on the command line, then the path to this instance 
should be displayed.  On the solver tab, it is possible to choose a solver
among all pre-built solvers of the Sat4j library. If the chosen instance uses 
pseudo boolean constraints then only pb solvers should be displayed.

If a customized solver has been specified in the command line, then
the "Use customize solver" option should be checked. Until unchecked,
the running solver is the customized one.

If the instance specifies an objective function, then it is possible
to run the solver in optimization mode.

Finally, the solver panel contain 2 buttons: 
- the "Start" button runs
the solver. When pushed (i.e. when the solver is running), this button
becomes a "Stop" button that definitely stops the solver.
- the "Pause" button temporally pauses the solver. When pushed, this
button becomes a "Resume" button. Note that pausing the solver does not change
its state: it is just frozen until it is resumed.

--------------
4. Restart Tab

The restart panel allows to change the restart strategy of the
solver. 
The different strategies available to Sat4j are displayed. Among those
strategies, there should be:
 - ArminRestarts
 - NoRestarts
 - LubyStrategy
 - MiniSATRestarts


To apply the selected strategy, the restart button must be pushed. 

--------------
5. Heuristics Tab

This tab contains 3 panels. 

The first panel is named "Random Walk" and allows to assign the probability 
that a decision variable is picked at random, instead of following the heuristics.
The button "Apply" has to be pushed in order to take the probability into account. 

The second panel is the "Phase Strategy" panel. Available strategies
are displayed. Among them: 
 - NegativeLiteralSelectionStrategy
 - PositiveLiteralSelectionStrategy
 - RSATPhaseSelectionStrategy
 - UserFixedPhaseSelectionStrategy
 - RandomLiteralSelectionStrategy
 - RSATLastLearnedClausesSelectionStrategy
 - PhaseCachingAutoEraseStrategy
 - PhaseInLastLearnedClauseSelectioNStrategy
To apply the selected strategy, click the "Apply" button.

The final panel is the hot solver panel. If checked, the "Keep solver
hot" option prevents the solver to reset it heuristics when a model is
found.

--------------
6. Learned Constraints Tab

This tab is composed of two panels.  First, the "Learned Constraint
Deletion Strategy" panel allows to control the whole deletion
strategy. Every solver is associated with a default deletion
strategy. To keep this strategy, do not uncheck the "Use solver's
original deletion strategy".  When unchecked, it is possible to use a
specific strategy by push the button "Apply changes" after : 
- choosing on the slider the number of clauses after which a clean will
be made 
- choosing the clauses evaluation type (Activity or LBD)

The number of assignments per second is displayed just under the first
checkbox. Note that this number is dependant on the other processes
that run at the same time and on the parameters chosen to run the
remote. 

It is possible to force a clean by using the "Clean now" button. 

The second panel deals with the simplification strategy. It is
possible to choose between three strategies:
 - no reason
 - simple reason
 - expensive reason

--------------
7. About solver

This panel details the running solver configuration. Information are
displayed only while a solver is running.


==============================
   Launching customized solver
==============================

When launching the remote in command line, it is possible to specify
the use of a specific solver. 

The usage is:

java -jar sat4j.jar [-C] [-d <filename>] [-f <filename>] [-H] [-k
       <number>] [-l <libname>] [-m] [-opt] [-r] [-remote] [-rw <number>]
       [-s <solvername>] [-S <solverStringDefinition>] [-T <number>] [-t
       <number>] [-y]

 -C,--conflictbased                    
              conflict based timeout (for
              deterministic behavior)

 -d,--dot <filename>                  
 	      creates a sat4j.dot file in current directory
 	      representing the search

 -f,--filename <filename>               
              specifies the file to use (in conjunction with -d for
              instance)


 -H,--hot                               
              keep the solver hot (do not reset heuristics) when a
              model is found

 -k,--kleast <number>                   
              limit the search to models having at least k variables
              set to false

 -l,--library <libname>                 
              specifies the name of the library used (minisat by
              default)

 -m,--mute                              
              Set launcher in silent mode
 
-opt,--optimize                        
              uses solver in optimize mode instead of sat mode
              (default)

 -r,--trace                             
              traces the behavior of the solver

 -remote,--remoteControl                
              launches remote control

 -rw,--randomWalk <number>              
              specifies the random walk probability

 -s,--solver <solvername>               
              specifies the name of a prebuilt solver from the library

 -S,--Solver <solverStringDefinition>   
              setup a solver using a solver config string
	      Example: -S RESTARTS=LubyRestarts/factor:512,LEARNING=MiniSATLearning
	       - Available restart strategies (RESTARTS):
               	  	   [ArminRestarts[searchParams], NoRestarts[searchParams],
              	  	   LubyRestarts[searchParams, factor],
              	  	   MiniSATRestarts[searchParams]]
	       - Available orders (ORDERS):
               	 	   [VarOrderHeapObjective[variableHeuristics,
              		   phaseSelectionStrategy, vocabulary],
              		   PureOrder[variableHeuristics, phaseSelectionStrategy,
              		   vocabulary, period],
              		   VarOrderHeap[variableHeuristics, phaseSelectionStrategy,
              		   vocabulary]]
               - Available learning (LEARNING): [ClauseOnlyLearning,
               	 	    FixedLengthLearning[maxLength], MiniSATLearning,
              		    NoLearningNoHeuristics, NoLearningButHeuristics,
              		    ActiveLearning[limit, activityPercent],
              		    PercentLengthLearning[limit]]
	       - Available phase strategies (PHASE):
	                     [NegativeLiteralSelectionStrategy,
              		     PositiveLiteralSelectionStrategy,
              		     RSATPhaseSelectionStrategy,
              		     UserFixedPhaseSelectionStrategy,
              		     RandomLiteralSelectionStrategy,
              		     RSATLastLearnedClausesPhaseSelectionStrategy,
              		     PhaseCachingAutoEraseStrategy,
              		     PhaseInLastLearnedClauseSelectionStrategy]
	       - Available search params (PARAMS):
               	 	     [SearchParams[claDecay, initConflictBound, varDecay,
              		     conflictBoundIncFactor]]
	       - Available simplifiers : 
	       	 	     [NO_SIMPLIFICATION, SIMPLE_SIMPLIFICATION, EXPENSIVE_SIMPLIFICATION]
	       - Available building blocks: 
	       	 	     DSF, LEARNING, ORDERS, PHASE, RESTARTS, SIMP, PARAMS 

 -T,--timeoutms <number> 
              specifies the timeout (in milliseconds)

 -t,--timeout <number>                  
              specifies the timeout (in seconds)

 -y,--simplify                          
              simplify the set of clauses is possible

