Getting started
Running SHOT from the command line
Assuming you have the SHOT executable (SHOT.exe on Windows) installed on your system, you can call SHOT with the following syntax:
If you need instructions the flag --help shows SHOT's syntax.
Options
The valid options for SHOT are listed here.
Pass options using a file
Settings for SHOT can be specified either through an options file (either as a text file or as an OSoL-file in XML syntax).
To generate an example options file pass the flag --opt which will create the file options.opt in the current directory. To use an option file pass the parameter --opt options.opt.
To create an empty OSoL-file add the flag --osol, which creates the file options.xml. To use this file pass the parameter --osol options.xml.
Pass options using the command line
It is also possible to pass options through the command line using the following syntax
Note that the options are case sensitive and that there are no spacing between option names, =, and value.
There are also a number of short hand options available.
Results
OSrL (Optimization Services result Language) file
After a successful termination, SHOT will create an result file <problemname>.osrl in the current directory. This file is in the Optimization Services OSrL syntax, which is an XML-based format. It is also possible to specify where the result file should be written by adding the parameter --osrl path/to/resultfile.osrl as an argument when calling SHOT.
GAMS trace file
It is also possible to create a GAMS trace file in a similar way by adding the --trc <filename.trc> flag. If no filename is specified, a filename consisting of the problem file and the suffix .trc is created in the current directory.
AMPL solution file
To create a file in AMPL sol-format add the parameter --sol <filename.sol>.
Console output
The level of output that SHOT writes to the console can be controlled with the setting Output.Console.LogLevel , where values between 0 and 6 are allowed. Assuming that the default value 2 is used, first some basic information about the solver, including the current version is provided:
Then information about the modeling system or file format used is given as well as information about possible bound tightening performed on the variable bounds.
Then information about the provided problem instance is shown. SHOT automatically reformulates the problem into a form that is more suitable for the underlying algorithm, and statistics about the reformulated problem is given as well.
After this, the (nondefault) settings used are shown; here the MIP solver utilized (CPLEX) considered all variable bounds over +/- 1e20 to be infinite, so this setting will be used by SHOT as well.
Below the used settings, the names and versions of the utilized subsolvers are shown.
Now, since the ESH algorithm was used for generating linearizations of nonlinear expressions in SHOT, an interior point is required, which will be found by utilizing a minimax solver implemented by solving linear programming (LP) problems.
The
Iterationcolumn shows the current iteration number, as well as the problem type solved (LP=linear programming).The
Timecolumn shows the wall clock time in seconds.In the
Cutscolumn, the number of linear constraints added in each iteration, as well as the total number of added constraints, are shown.In the
Objective valuecolumn, there are two values, the first corresponding to the solution of the LP problem and the other of the minimal value on the line between the previous solution point and the current.The last column gives the absolute and relative difference between the two objective values in the previous column.
So, in the example above, 13 LP problems were solved and a total of 48 linear constraints were generated to find an integer-relaxed interior point to the reformulated MINLP problem. Now we can continue to solve the actual problem.
The first thing to notice is that not all iterations are written to console, but this condensed output can be deactivated with the switch Output.Console.Iteration.Detail=0.
The columns are similar to those of the minimax solver mentioned above.
The
Iterationcolumn shows the iteration number and type. The type identifier consists of a part showing the problem type, and a part showing the solution status of the iteration.The following types are available for the linearized problem solved in SHOT's dual strategy:
LP: linear programming problem.
QP: quadratic programming problem.
QCQP: quadratically constrained quadratic programming problem.
MILP: mixed-integer linear programming problem.
MIQP: mixed-integer quadratic program.
MIQCQP: mixed-integer quadratically constrained quadratic program.
CB: New incumbent solution candidate found in callback by MIP solver. For some solvers, also the thread number of the callback is shown.
The following types are available for the primal heuristic in SHOT:
NLPSOLPT: An NLP problem has been solved with fixed integer values originating from a MIP solution that is classified as optimal (or found in a callback).
NLPNEWDB: An NLP problem has been solved with fixed integer values originating from a MIP solution that has improved the lower bound of a minimization problem (or upper bound of a maximization problem).
The following statuses are appended after the dash:
O: Solved to optimality.
F: Solved to feasibility.
I: Infeasible problem detected.
U: Unbounded problem detected.
TL: Time limit reached.
IL: Iteration limit reached.
SL: Solution limit reached.
The
Timecolumn shows the wall clock time in seconds.In the
Cutscolumn, the number of linear constraints added in each iteration, as well as the total number of added constraints, are shown.In the
Objective value - dualcolumn, the current lower bound (if minimizing) on the objective value is shown. Unless an asterisk*is added to the value, this is a global lower bound. This value is provided by the underlying MIP solver.In the
Objective value - primalcolumn, the current upper bound (if minimizing) on the objective value is shown. This value is the current best know solution to the problem and is given by either the MIP solver's solution pool or a primal heuristic, such as solving integer-fixed NLP problems.The
objective gapcolumn shows the absolute and relative gap between the lower and upper bounds in the previous columns.The final column
Current solutionprovides some insight into the objective value and constraint fulfillment of the current iteration (either from the MIP or NLP solver).In the
max.errcolumn, the nonlinear constraint index with the maximal error in the solution point is shown in addition to the error.
Finally, after terminating the iterative solution procedure, SHOT shows a final report that explains the status of the solution, and why the solver terminated.
In the case above, the single-tree strategy was used, and the linearizations were added during the solution of only one MILP problem, which was solved to optimality.
After this some insight into the number of primal solutions, i.e., solutions to the original MINLP problem, found, and which method was used to find them:
A report over how much time the individual components took is also provided:
Finally, SHOT shows where the log file and solution file(s) have been written:
File output
By default SHOT creates a log file SHOT.log in the current directory containing the same type of output as is written to the console. To specify the location of this file use the parameter --log <filename.log>. It is possible to control the verbosity of the log file with the parameter Output.File.LogLevel setting.
Debugging information and intermediate problems
SHOT does not normally create any auxiliary files during run-time so it might be difficult to debug what is happening, e.g. in each dual iteration. There is however a setting Output.Debug flag that, if activated, creates a folder SHOT_debug_***** in the system temp folder. The destination folder can be specified with the parameter Output.Debug.Path. or with--debug=<directory>, where directory is where the debug files should be saved.
For example, there is the file originalproblem.txt and reformulatedproblem.txt which shows how SHOT interprets the given problem and how it is reformulated by SHOT. Also, the intermediate linearized problems solved by the MIP solver in each iteration is provided as LP*.lp.
Using SHOT in Pyomo
To use SHOT in Python, you need to have a SHOT executable installed somewhere on your system.
The location can either be somewhere in your path (so that you can call SHOT from a terminal in any directory), or you will need to specify where the SHOT executable is.
Assuming SHOT is in your path, you can solve problems with the following command:
Otherwise you will need to specify where the SHOT executable is with the command
The solution will be written to a file results.yml in the current directory. You can also write the solution to the screen by adding the flag --show-result.
Specifying solver options
You can specify any of SHOT's options (as described here) by adding the --solver-optionsflag. For example: --solver-options="Termination.TimeLimit=100.0" will set a time limit of 100 seconds.
If you want to specify multiple settings, separate them with a space, e.g. --solver-options="Termination.TimeLimit=100.0 Termination.ObjectiveGap.Relative=0.01".
Note that some given parameters may not always be considered; the used settings are indicated at the top of the log file SHOT.log.
Using SHOT in GAMS
If you have a GAMS version with built in support of SHOT, you can simply specify <problem-class> = SHOT (e.g. MINLP=SHOT), either in the model itself or in the command line.
Use your own SHOT version
To use your own version of SHOT with GAMS, you can modify the gamsconfig.yaml file. See the GAMS documentation for instructions.
In short, you need to create a file called gamsconfig.yaml in either the GAMS system directory or one of the other directories specified here.
On Windows
To make available a solver named SHOT2 in GAMS, which uses the SHOT library from D:\Users\janeDoe\Downloads\gamslink\GamsShot-20.dll, add the following contents to the yaml file:
On Linux/MAC
To make available a solver named SHOT2 in GAMS, which uses the SHOT library from /path/to/libSHOTSolver.so , add the following contents to the yaml file:
The settings are explained in detail here.
Using SHOT in JuMP
It is possible to get SHOT working together with the Julia-based optimization modeling system JuMP using its AmplNLWriter.jl subproject. For more information see the Github repository.
In short, assuming you have everything set up and a version of SHOT installed and working on your system you can use the following command.
This assumes that the SHOT executable is found in your path, otherwise you will need to specify the full path to where the executable is, i.e.
Call SHOT from JuMP using GAMS
If you have GAMS installed you can also use SHOT from JuMP and Pyomo by using the GAMS interface described in this blog post.
Using SHOT through ASL (AMPL Solver Library)
SHOT should be compatible with any modeling system using ASL (models in nl and solution in sol formats). In practice this works so that the following syntax is used:
Then SHOT solves the problem given in the nl-file and writes a solution file problemfile.sol. This file is written in the same directory as the nl-file.
Last updated