$ontext =======================================================================

LAST MODIFIED: 25 November, 2002

FILENAME: plotprof.gms

PURPOSE:  Plots the performance profiles computed in pprofile.gms. Current 
          supported GAMS interface plotting routines include:
 
          -gnuplotxy (windows)

USAGE:    The same as pprofile.gms with the same inputs, except the options

          --gnuplotxy=yes (if specified, plots using gnuplotxy)


PROFILE DESCRIPTION:
          Suppose that we define a performance ratio:

                rho(p,s) =    resource time for problem p for solver s
                            -------------------------------------------------
                             min resource time for problem p over all solvers
 
          which can be thought of the relative solver time for a problem wrt to
          the best possible time.

          Then the performance profile p_s(tau) for a solver s is the probability
          that a performance ratio rho is within a factor of tau of the best possible
          ratio. 

INTERPRETATION OF PERFORMANCE PROFILE:
          If we are only interested in maximizing the number of "wins" (i.e. maximizing
          the number of models solved the fastest), then we need only consider
          p_s(1). If we are interested only in determining if a solver has a high
          probability of success we are interested in 
 
                   lim        p_s(tau)
                   tau_>inf

REFERENCE:
          Dolan, E. and More, J., "Benchmarking optimiation software with performance
          profiles", Mathematical Programming, Vol 91 (2), pp.201-213, 2002. 

REQUIRED INPUTS:
	  --trace1:    trace file of solver 1
	  --trace2:    trace file of solver 2 etc up to --trace8
          --ntrace1:   non-GAMS solver data file 1
          --ntrace2:   non-GAMS solver data file 2 up to --ntrace8

          Users cannot input two tracefile numbers of different type
          with the same (n)trace number, i.e.

          --trace1=... --ntrace1 is not allowed, only --trace1=... --ntrace2=...


OPTIONAL INPUTS:
          --factor     factor for values of tau: 1, factor, factor^2, factor^3 (default 1.25)
          --figname:   name of output figure (default: fig1.*, where * is the format ext.)
	  --modelfile: filename containing subset of models to consider. Useful,
		       if only a subset of models from the tracefile are to
		       be used in the solver square comparison.
          --numpts:    number of data points for each solver for performance profile
                       (default: 25)
          --delta:     considered optimal if objective value is within 
                       --delta % of best objective value using relative
                       obj. difference.
                       (default: Inf, i.e. ignore) 
          --optonly:   Plots only if model is truly optimal (not only
                       feasible). Set to1 if only optimal models. 
                       Otherwise considers both feasible and truly optimal
                       models. (default: 0)
          --otype:     output type: windows, gif, postscript (default is to windows)
          --outfile:   data output filename in .txt format (default: profile.txt)
	  --resmin:    minimum resource time threshold. If a solver reports a
		       resource time below --resmin, then it is increased to
		       resmin before being used in ratios. (default 0.05).
          --topt4:     trace option 4. If specified, then assumes 
                       tracefile is traceopt=4 (default:none)
          --total:     indicator if total models to be solved by any
                       solver should be displayed. Use --total=0
                       if to be ignored. 
                       (default: 1)




REMARKS:  Each tracefile can contain information from only one (1) solver for a
	  given set of models. For example, tracefiles containing solver A and
	  solver B will cause error message upon compilation.

          Users must have a relevant plotting software installed. The program
          currently supports:

          1. gnuplotxy (available from Bruce McCarl's website at
                      http://ageco.tamu.edu/faculty/mccarl/gnuplot/gnuplot.html )

          Users cannot input two tracefile numbers of different type
          with the same (n)trace number, i.e.

          --trace1=... --ntrace1 is not allowed, only --trace1=... --ntrace2=...



$offtext ======================================================================

$include pprofile.gms


$if not set figname     $set  figname       fig1
$if not set gnuplotxy   $set  gnuplotxy     yes
$if not set otype       $set  otype         windows
$if not set delta       $set  delta Inf
$if not set optonly     $set  optonly 0
$if not set total       $set  total 1

$if     set gnuplotxy   $goto plotgnuplotxy


*=== Plot using gnuplotxy
$label plotgnuplotxy


* === Error checks for GNUPLOTXY
$if %system.filesys% == UNIX                     $goto no_unixgnuplot
$if not exist "%gams.sysdir%inclib\gnupltxy.gms" $goto no_gnuplotxy


$setglobal gp_title    'Performance Profile'
$setglobal gp_key      'bottom right' 
$setglobal gp_yrange   '0.0001 : 100' 
$setglobal gp_title    'Performance Profile'
$setglobal gp_xlabel   'Time Factor'
$setglobal gp_ylabel   'Percent Of Models Solved'  
$setglobal gp_lwidth   2 
$setglobal gp_logscale x 

$libinclude gnupltxy plotdata profile cut %figname% %otype%
$goto done


*=== Abort if GNUPLOTXY doesn't exist
$label no_gnuplotxy
$call echo  "ERROR: GNUPLOTXY not found on your system!"
$abort      "ERROR: GNUPLOTXY not found on your system!"
$goto done


*=== Abort if UNIX 
$label no_unixgnuplot
$call echo "ERROR: GNUPLOTXY not found on your system. GNUPLOTXY works only on Windows!" 
$abort     "ERROR: GNUPLOTXY not found on your system. GNUPLOTXY works only on Windows!" 
$goto done


$label done
execute 'mv -f %figname%.%otype% %figname%.%otype%'
execute 'rm -f tracedata'