Get started

The SHOTpy wheels include SHOT with the open-source subsolvers Cbc, Ipopt and HiGHS, and need Python 3.11 or later. They are built for Linux (x86-64) and macOS (Apple silicon, macOS 14 and later). On other Linux and macOS systems, pip builds SHOT from source, which needs the compiler and dependencies in the compilation instructions. Windows is not supported; use the Windows Subsystem for Linux.

pip install SHOTpy

Public wheels cannot include CPLEX, Gurobi or GAMS. If one of them is installed and licensed on your computer, build SHOTpy from source with it:

pip install SHOTpy --no-binary SHOTpy \
    --config-settings=cmake.define.HAS_GUROBI=on \
    --config-settings=cmake.define.GUROBI_DIR=/opt/gurobi1103/linux64

Use the same pattern with HAS_CPLEX and CPLEX_DIR, or HAS_GAMS and GAMS_DIR.

SHOT is included in GAMS, and inside GAMS it can use any licensed NLP solver as subsolver. In GAMSPy, the Python modeling library of GAMS, SHOT is an add-on solver that you install separately. This is the easiest way to use SHOT.

pip install gamspy
gamspy install solver shot

GAMSPy documentationSHOT in the GAMS documentation

To try SHOT without installing anything, submit a model in GAMS format to SHOT on the NEOS Server, a free internet-based service for numerical optimization.

SHOT on the NEOS Server

SHOT compiles on Linux and macOS with CMake and a C++17 compiler; on Windows, use the Windows Subsystem for Linux. It needs a MIP solver and an NLP solver; the open-source Cbc, HiGHS and Ipopt are enough. HiGHS is compiled from its submodule by default.

git clone https://github.com/coin-or/SHOT.git
cd SHOT
git submodule update --init --recursive

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release \
  -DCBC_DIR=/path/to/cbc \
  -DIPOPT_DIR=/path/to/ipopt
cmake --build build --parallel

CBC_DIR and IPOPT_DIR give the locations of Cbc and Ipopt, if CMake does not find them itself. To use an installed HiGHS instead of the submodule, add -DUSE_EXTERNAL_HIGHS=on and -DHIGHS_EXTERNAL_DIR=/path/to/highs. This builds the SHOT executable and the libSHOTSolver library in build/; add -DHAS_PYTHON=on to also build SHOTpy. Check the CMake output for lines saying that a solver was not found; such a solver is left out of the build.

SHOT reads AMPL (.nl) and OSiL (.osil) files out of the box. Reading GAMS (.gms) files requires SHOT to be compiled with a GAMS installation.

Full compilation instructions

import SHOTpy

solver = SHOTpy.Solver()
problem = SHOTpy.Problem(solver)

x = problem.addVariable("x", SHOTpy.VariableType.Real, 0.0, 10.0)
y = problem.addVariable("y", SHOTpy.VariableType.Integer, 0.0, 10.0)

problem.setObjective(SHOTpy.exp(x) + (y - 2.5)**2)
problem.addConstraint(x + y >= 3, "c")
problem.finalize()

solver.setProblem(problem)
solver.solveProblem()

print(solver.getModelReturnStatus(), solver.getPrimalSolution().point)

Build the problem with the API, or read it from a file with solver.setProblem("problem.nl"), which also accepts .gms and .osil files. The tutorial notebook covers nonlinear expressions, settings and callbacks.

SHOTpy tutorial

import gamspy as gp

m = gp.Container()

x = gp.Variable(m, name="x", type="integer")
y = gp.Variable(m, name="y", type="positive")
x.up = 10
y.up = 10

con = gp.Equation(m, name="con")
con[...] = gp.math.sqr(x - 4) + gp.math.sqr(y - 3) <= 4

model = gp.Model(m, name="model", equations=[con], problem="MINLP",
                 sense=gp.Sense.MIN, objective=2 * x + y)
model.solve(solver="SHOT")
print(model.objective_value)

Install SHOT in GAMSPy with gamspy install solver shot, then pass solver="SHOT" to solve() for MINLP and MIQCP models.

GAMSPy documentation

* Select SHOT for the problem class, in the model or on the command line
option minlp = shot;

solve mymodel using minlp minimizing obj;

You can also set it on the command line, e.g., gams model.gms minlp=shot.

SHOT in the GAMS documentation

import pyomo.environ as pyo

model = pyo.ConcreteModel()
# ... variables, constraints and objective ...

# SHOT is called through the AMPL Solver Library (ASL) interface
solver = pyo.SolverFactory("asl:SHOT")  # or add executable="/path/to/SHOT"
solver.solve(model, tee=True)

The SHOT executable must be on your path, or given with executable. With GAMS installed, you can also use SHOT through the Pyomo GAMS interface.

Pyomo

using JuMP, AmplNLWriter

model = Model(() -> AmplNLWriter.Optimizer("SHOT"))  # or the full path to SHOT
# ... variables, constraints and objective ...
optimize!(model)

JuMP calls SHOT through AmplNLWriter.jl, which writes the model in AMPL .nl format. A native JuMP interface is on the roadmap after SHOT 2.0.

AmplNLWriter.jl

# SHOT reads the .nl file and writes problem.sol next to it
./SHOT problem.nl --AMPL

SHOT works with any modeling system that uses the AMPL Solver Library: models in .nl format and solutions in .sol format. In AMPL, set SHOT as the solver with option solver.

AMPL

./SHOT problem.osil                 # OSiL is always supported
./SHOT problem.nl --timelimit=60    # AMPL
./SHOT problem.gms --mip=highs      # GAMS
./SHOT --help                       # what this build supports

SHOT prints the dual and primal bounds as it iterates, and writes the solution in OSrL format and a log to SHOT.log.

Command-line reference

#include "Solver.h"

auto solver = std::make_unique<SHOT::Solver>();
solver->updateSetting("Termination.TimeLimit", 60.0);

if(solver->setProblem("problem.osil") && solver->solveProblem())
{
    double primal = solver->getPrimalBound();
    double dual = solver->getCurrentDualBound();
}

Link against libSHOTSolver to embed SHOT in other software; the console application is a thin wrapper around this API. Callbacks are registered with registerCallback.

Callbacks