Reference · 2.0 development

SHOTpy API

This reference is generated from the SHOTpy module built for this checkout. Start with the SHOTpy tutorial for worked examples.

SHOTpy

class SHOTpy.CallbackContext

The state of the solver and the actions available to a callback. Values that are not available yet, e.g., the dual bound before the first dual problem has been solved, are infinite.

terminate()

Request SHOT to terminate at its next termination check

Return type:

None

property absoluteGap: float

The absolute gap between the current dual bound and the primal bound

property dualBound: float

The current dual bound, which the termination criteria use. For a nonconvex problem it is not a valid bound once cuts have been added to nonconvex functions; globalDualBound is

property elapsedTime: float

The time since SHOT was started, in seconds

property globalDualBound: float

The dual bound that is valid for the whole problem

property hasPrimalSolution: bool

Whether a primal solution has been found

property isFinalizing: bool

Whether SHOT is finalizing the solution, for any reason

property isMinimization: bool

Whether the problem is minimized

property isTerminationPending: bool

Whether termination was requested before SHOT reached the location, so that SHOT is stopping

property isTerminationRequested: bool

Whether terminate() has been called in this context, by this or an earlier callback at the location

property isValid: bool

Whether the context can still be used, i.e., the callback it was given to has not returned

property iterationNumber: int

The number of the current iteration, or 0 before the first iteration

property location: CallbackLocation

The location the callback is called at

property originalProblem: Problem

The problem given to the solver

property primalBound: float

The objective value of the best primal solution, infinite if there is none

property primalSolution: list[float] | None

The best primal solution in the variables of the original problem, or None if there is none

property reformulatedProblem: Problem

The problem that SHOT solves, created from the original one by the reformulation

property relativeGap: float

The relative gap between the current dual bound and the primal bound

property solutionStatistics: SolutionStatistics

A copy of the statistics of the solution process

exception SHOTpy.CallbackContextExpired

class SHOTpy.CallbackLocation(value)

Members:

InteriorPointSearch

DualBoundUpdate

PrimalCandidateSearch

PrimalCandidateCheck

NewPrimalSolution

TerminationCheck

HyperplaneSelection

Parameters:

value (SupportsInt | SupportsIndex)

DualBoundUpdate: ClassVar[CallbackLocation]

HyperplaneSelection: ClassVar[CallbackLocation]

InteriorPointSearch: ClassVar[CallbackLocation]

NewPrimalSolution: ClassVar[CallbackLocation]

PrimalCandidateCheck: ClassVar[CallbackLocation]

PrimalCandidateSearch: ClassVar[CallbackLocation]

TerminationCheck: ClassVar[CallbackLocation]

property name: str

property value: int

class SHOTpy.ConstraintExpression

A constraint lowerBound <= expression <= upperBound created by comparing variables, expressions and numbers, e.g., x1 * x2 <= 5, which Problem.addConstraint() adds to the problem

property expression: Expression

The expression f of the constraint lowerBound <= f <= upperBound

property lowerBound: float

The lower bound, SHOT_DBL_MIN if there is none

property upperBound: float

The upper bound, SHOT_DBL_MAX if there is none

class SHOTpy.ConstraintProperties

property convexity: Convexity

The convexity of the constraint as far as SHOT can determine it, which finalize() calculates

property functionConvexity: Convexity

The convexity of the function f(x) of the constraint L <= f(x) <= U, regardless of its bounds. An equality constraint with a convex function is nonconvex

property hasLinearTerms: bool

Whether it has linear terms

property hasMonomialTerms: bool

Whether it has monomial terms

property hasNonlinearExpression: bool

Whether it has a nonlinear expression

property hasQuadraticTerms: bool

Whether it has quadratic terms

property hasSignomialTerms: bool

Whether it has signomial terms

class SHOTpy.Convexity(value)

Members:

Linear

Convex

Concave

Nonconvex

Unknown

NotSet

Parameters:

value (SupportsInt | SupportsIndex)

Concave: ClassVar[Convexity]

Convex: ClassVar[Convexity]

Linear: ClassVar[Convexity]

Nonconvex: ClassVar[Convexity]

NotSet: ClassVar[Convexity]

Unknown: ClassVar[Convexity]

property name: str

property value: int

class SHOTpy.DualBoundUpdateContext

setDualBound(value)

Propose a dual bound; SHOT uses it if it is better than the current one

Parameters:

value (SupportsFloat | SupportsIndex)

Return type:

None

property proposedDualBound: float | None

The dual bound proposed with setDualBound() in this context, None if none has been

class SHOTpy.Environment

property problem: Problem

The problem given to the solver

property reformulatedProblem: Problem

The problem that SHOT solves, created from the given one by the reformulation

class SHOTpy.Expression

calculate(point: collections.abc.Sequence[SupportsFloat | SupportsIndex]) → float

calculate(box: collections.abc.Sequence[Interval]) → Interval

Helper for @overload to raise when called.

calculateIntervalDerivatives(box, order=2)

Calculate bounds over the box, which has an Interval for each variable, of the value and the derivatives up to the order (0, 1 or 2) with interval arithmetic. See IntervalDerivatives for when they enclose them

Parameters:

• box (Sequence[Interval])

• order (SupportsInt | SupportsIndex)

Return type:

IntervalDerivatives

getBounds()

The bounds of the expression over the bounds of its variables, as calculate(box). Raises IntervalError if the expression is not defined anywhere in the bounds

Return type:

Interval

getConvexity()

The convexity of the expression as far as SHOT can determine it from its structure

Return type:

Convexity

getType()

The type of the expression node, e.g., ExpressionType.Sum

Return type:

ExpressionType

class SHOTpy.ExpressionType(value)

Members:

Constant

Var

Negate

Invert

SquareRoot

Log

Exp

Square

Cos

Sin

Tan

ArcCos

ArcSin

ArcTan

Abs

ErrorFunction

Sinh

Cosh

Tanh

SignPower

Divide

Power

Sum

Product

Parameters:

value (SupportsInt | SupportsIndex)

Abs: ClassVar[ExpressionType]

ArcCos: ClassVar[ExpressionType]

ArcSin: ClassVar[ExpressionType]

ArcTan: ClassVar[ExpressionType]

Constant: ClassVar[ExpressionType]

Cos: ClassVar[ExpressionType]

Cosh: ClassVar[ExpressionType]

Divide: ClassVar[ExpressionType]

ErrorFunction: ClassVar[ExpressionType]

Exp: ClassVar[ExpressionType]

Invert: ClassVar[ExpressionType]

Log: ClassVar[ExpressionType]

Negate: ClassVar[ExpressionType]

Power: ClassVar[ExpressionType]

Product: ClassVar[ExpressionType]

SignPower: ClassVar[ExpressionType]

Sin: ClassVar[ExpressionType]

Sinh: ClassVar[ExpressionType]

Square: ClassVar[ExpressionType]

SquareRoot: ClassVar[ExpressionType]

Sum: ClassVar[ExpressionType]

Tan: ClassVar[ExpressionType]

Tanh: ClassVar[ExpressionType]

Var: ClassVar[ExpressionType]

property name: str

property value: int

class SHOTpy.ExternalHyperplane

property description: str

A description of the hyperplane, used in the log

property rhsValue: float

The right-hand side of the cut

property variableCoefficients: list[float]

The coefficients of the variables, so that the cut is sum(coefficients[i] * x[indexes[i]]) <= rhsValue

property variableIndexes: list[int]

The indexes of the variables of the hyperplane in the reformulated problem

class SHOTpy.Hyperplane

property isGlobal: bool

Whether the hyperplane is valid for the whole problem, e.g., it is generated for a convex function. Adding one that is not means that SHOT no longer proves the solution optimal

property source: HyperplaneSource

Where the hyperplane comes from, e.g., HyperplaneSource.External

class SHOTpy.HyperplaneCutStrategy(value)

Members:

ESH

ECP

Parameters:

value (SupportsInt | SupportsIndex)

ECP: ClassVar[HyperplaneCutStrategy]

ESH: ClassVar[HyperplaneCutStrategy]

property name: str

property value: int

class SHOTpy.HyperplaneSelectionContext

addHyperplane(hyperplane)

Add a hyperplane in the variables of the reformulated problem

Parameters:

hyperplane (ExternalHyperplane)

Return type:

None

property addedHyperplanes: list[ExternalHyperplane]

The hyperplanes added with addHyperplane() in this context

property solutionPoints: list[SolutionPoint]

The solution points of the dual problem, in the variables of the reformulated problem

class SHOTpy.HyperplaneSource(value)

Members:

Unknown

MIPOptimalRootsearch

MIPSolutionPoolRootsearch

LPRelaxedRootsearch

MIPOptimalSolutionPoint

MIPSolutionPoolSolutionPoint

LPRelaxedSolutionPoint

LPFixedIntegers

PrimalSolutionSearch

PrimalSolutionSearchInteriorObjective

InteriorPointSearch

MIPCallbackRelaxed

ObjectiveRootsearch

ObjectiveCuttingPlane

External

Parameters:

value (SupportsInt | SupportsIndex)

External: ClassVar[HyperplaneSource]

InteriorPointSearch: ClassVar[HyperplaneSource]

LPFixedIntegers: ClassVar[HyperplaneSource]

LPRelaxedRootsearch: ClassVar[HyperplaneSource]

LPRelaxedSolutionPoint: ClassVar[HyperplaneSource]

MIPCallbackRelaxed: ClassVar[HyperplaneSource]

MIPOptimalRootsearch: ClassVar[HyperplaneSource]

MIPOptimalSolutionPoint: ClassVar[HyperplaneSource]

MIPSolutionPoolRootsearch: ClassVar[HyperplaneSource]

MIPSolutionPoolSolutionPoint: ClassVar[HyperplaneSource]

ObjectiveCuttingPlane: ClassVar[HyperplaneSource]

ObjectiveRootsearch: ClassVar[HyperplaneSource]

PrimalSolutionSearch: ClassVar[HyperplaneSource]

PrimalSolutionSearchInteriorObjective: ClassVar[HyperplaneSource]

Unknown: ClassVar[HyperplaneSource]

property name: str

property value: int

class SHOTpy.InteriorPointSearchContext

setInteriorPoints(points)

Replace the interior points with at least one point in the variables of the original or the reformulated problem

Parameters:

points (Sequence[Sequence[SupportsFloat | SupportsIndex]])

Return type:

None

property interiorPoints: list[list[float]]

The interior points SHOT has found, in the variables of the reformulated problem

property replacementInteriorPoints: list[list[float]] | None

The points set with setInteriorPoints() in this context, None if none have been

class SHOTpy.Interval(lower: SupportsFloat | SupportsIndex, upper: SupportsFloat | SupportsIndex)

class SHOTpy.Interval(value: SupportsFloat | SupportsIndex)

class SHOTpy.Interval(bounds: tuple)

A closed interval [lower, upper], e.g., the bounds of a function over a box of variable bounds. A tuple (lower, upper) or a number can be used where an Interval is expected. The bounds are not rounded outwards, so the interval is not a verified enclosure of the floating-point calculations.

contains(value)

Whether lower <= value <= upper

Parameters:

value (SupportsFloat | SupportsIndex)

Return type:

bool

property lower: float

The lower bound

property midpoint: float

(lower + upper) / 2

property upper: float

The upper bound

property width: float

upper - lower

class SHOTpy.IntervalDerivatives

Bounds of the value, the gradient and the Hessian of a function over a box, calculated with interval arithmetic. The bounds enclose the derivatives only when isDefinedOnBox is True and differentiableOrder is at least the order of the derivative; otherwise they are not reliable, e.g., the gradient of |x| is [-1, 1] when x = 0 is in the box. The bounds are not rounded outwards, so they are numerical bounds, not verified enclosures of the floating-point calculations.

property differentiableOrder: int

The order (0, 1 or 2) up to which the function is continuously differentiable everywhere in the box, e.g., 0 for |x| or sqrt(x) when x = 0 is in the box

property gradient: dict[int, Interval]

The bounds of the gradient as a dict {variable index: Interval}, without the elements that are zero

property hessian: dict[tuple[int, int], Interval]

The bounds of the upper triangle of the Hessian as a dict {(index1, index2): Interval} with index1 <= index2, without the elements that are zero

property isBounded: bool

Whether the bounds of the value and of the calculated derivatives are finite, i.e., not SHOT_DBL_MIN or SHOT_DBL_MAX

property isDefinedOnBox: bool

Whether the function is defined everywhere in the box, e.g., not if the argument of a logarithm can be 0

property value: Interval

The bounds of the value

exception SHOTpy.IntervalError

class SHOTpy.IterationOutputDetail(value)

Members:

Full

ObjectiveGapUpdates

ObjectiveGapUpdatesAndNLPCalls

Parameters:

value (SupportsInt | SupportsIndex)

Full: ClassVar[IterationOutputDetail]

ObjectiveGapUpdates: ClassVar[IterationOutputDetail]

ObjectiveGapUpdatesAndNLPCalls: ClassVar[IterationOutputDetail]

property name: str

property value: int

class SHOTpy.LinearConstraint(name: str, lhs: SupportsFloat | SupportsIndex, rhs: SupportsFloat | SupportsIndex)

class SHOTpy.LinearConstraint(name: str, linearTerms: LinearTerms, lhs: SupportsFloat | SupportsIndex, rhs: SupportsFloat | SupportsIndex)

add(terms: LinearTerms) → None

add(term: LinearTerm) → None

Helper for @overload to raise when called.

property linearTerms: LinearTerms

The linear terms of the constraint

class SHOTpy.LinearObjectiveFunction(direction: ObjectiveDirection)

class SHOTpy.LinearObjectiveFunction(direction: ObjectiveDirection, constant: SupportsFloat | SupportsIndex)

class SHOTpy.LinearObjectiveFunction(direction: ObjectiveDirection, linearTerms: LinearTerms, constant: SupportsFloat | SupportsIndex)

add(terms: LinearTerms) → None

add(term: LinearTerm) → None

Helper for @overload to raise when called.

property linearTerms: LinearTerms

The linear terms of the objective function

class SHOTpy.LinearTerm(coefficient, variable)

Parameters:

• coefficient (SupportsFloat | SupportsIndex)

• variable (Variable)

property coefficient: float

The coefficient of the term

property variable: Variable

The variable of the term

class SHOTpy.LinearTerms

class SHOTpy.LinearTerms(terms: collections.abc.Sequence[LinearTerm])

class SHOTpy.LinearTerms(coefficients: collections.abc.Sequence[SupportsFloat | SupportsIndex], variables: collections.abc.Sequence[Variable])

add(term: LinearTerm) → None

add(terms: LinearTerms) → None

Helper for @overload to raise when called.

append(term)

Append a term without merging it with an existing term of the same variable

Parameters:

term (LinearTerm)

Return type:

None

extend(terms)

Append the terms of a list without merging them

Parameters:

terms (Sequence[LinearTerm])

Return type:

None

reserve(size)

Reserve room for the given total number of terms

Parameters:

size (SupportsInt | SupportsIndex)

Return type:

None

size()

The number of terms

Return type:

int

class SHOTpy.MIPSolver(value)

Members:

Cplex

Gurobi

Cbc

Highs

NotUsed

Parameters:

value (SupportsInt | SupportsIndex)

Cbc: ClassVar[MIPSolver]

Cplex: ClassVar[MIPSolver]

Gurobi: ClassVar[MIPSolver]

Highs: ClassVar[MIPSolver]

NotUsed: ClassVar[MIPSolver]

property name: str

property value: int

class SHOTpy.ModelReturnStatus(value)

Members:

NotSet

OptimalGlobal

Unbounded

UnboundedNoSolution

InfeasibleGlobal

InfeasibleLocal

FeasibleSolution

NoSolutionReturned

ErrorUnknown

ErrorNoSolution

Parameters:

value (SupportsInt | SupportsIndex)

ErrorNoSolution: ClassVar[ModelReturnStatus]

ErrorUnknown: ClassVar[ModelReturnStatus]

FeasibleSolution: ClassVar[ModelReturnStatus]

InfeasibleGlobal: ClassVar[ModelReturnStatus]

InfeasibleLocal: ClassVar[ModelReturnStatus]

NoSolutionReturned: ClassVar[ModelReturnStatus]

NotSet: ClassVar[ModelReturnStatus]

OptimalGlobal: ClassVar[ModelReturnStatus]

Unbounded: ClassVar[ModelReturnStatus]

UnboundedNoSolution: ClassVar[ModelReturnStatus]

property name: str

property value: int

class SHOTpy.ModelingSystem(value)

Members:

OSiL

GAMS

AMPL

API

Parameters:

value (SupportsInt | SupportsIndex)

AMPL: ClassVar[ModelingSystem]

API: ClassVar[ModelingSystem]

GAMS: ClassVar[ModelingSystem]

OSiL: ClassVar[ModelingSystem]

property name: str

property value: int

class SHOTpy.MonomialTerm(coefficient, variables)

Parameters:

• coefficient (SupportsFloat | SupportsIndex)

• variables (collections.abc.Sequence[Variable])

property coefficient: float

The coefficient of the term

property isBilinear: bool

Whether the term is a product of two different variables

property isBinary: bool

Whether all the variables of the term are binary

property isSquare: bool

Whether the term is the square of a variable

property variables: list[Variable]

The variables whose product the term is

class SHOTpy.MonomialTerms

class SHOTpy.MonomialTerms(terms: collections.abc.Sequence[MonomialTerm])

add(term: MonomialTerm) → None

add(terms: MonomialTerms) → None

Helper for @overload to raise when called.

append(term)

Append a term without merging it with an existing term of the same variables

Parameters:

term (MonomialTerm)

Return type:

None

extend(terms)

Append the terms of a list without merging them

Parameters:

terms (Sequence[MonomialTerm])

Return type:

None

reserve(size)

Reserve room for the given total number of terms

Parameters:

size (SupportsInt | SupportsIndex)

Return type:

None

size()

The number of terms

Return type:

int

class SHOTpy.NewPrimalSolutionContext

property isIncumbent: bool

Whether the solution is better than the best one SHOT had before it

property objectiveValue: float

The objective value of the solution

property point: list[float]

The solution, in the variables of the original problem

property source: PrimalSolutionSource

Where the solution comes from, e.g., PrimalSolutionSource.NLPFixedIntegers

class SHOTpy.NonlinearConstraint(name: str, lhs: SupportsFloat | SupportsIndex, rhs: SupportsFloat | SupportsIndex)

class SHOTpy.NonlinearConstraint(name: str, expression: Expression, lhs: SupportsFloat | SupportsIndex, rhs: SupportsFloat | SupportsIndex)

class SHOTpy.NonlinearConstraint(name: str, linearTerms: LinearTerms, expression: Expression, lhs: SupportsFloat | SupportsIndex, rhs: SupportsFloat | SupportsIndex)

class SHOTpy.NonlinearConstraint(name: str, linearTerms: LinearTerms, quadraticTerms: QuadraticTerms, expression: Expression, lhs: SupportsFloat | SupportsIndex, rhs: SupportsFloat | SupportsIndex)

add(terms: LinearTerms) → None

add(term: LinearTerm) → None

add(terms: QuadraticTerms) → None

add(term: QuadraticTerm) → None

add(expression: Expression) → None

add(terms: MonomialTerms) → None

add(term: MonomialTerm) → None

add(terms: SignomialTerms) → None

add(term: SignomialTerm) → None

Helper for @overload to raise when called.

property monomialTerms: MonomialTerms

The monomial terms of the constraint

property nonlinearExpression: Expression

The nonlinear expression of the constraint, None if it has none

property signomialTerms: SignomialTerms

The signomial terms of the constraint

class SHOTpy.NonlinearObjectiveFunction(direction: ObjectiveDirection)

class SHOTpy.NonlinearObjectiveFunction(direction: ObjectiveDirection, constant: SupportsFloat | SupportsIndex)

class SHOTpy.NonlinearObjectiveFunction(direction: ObjectiveDirection, expression: Expression, constant: SupportsFloat | SupportsIndex)

class SHOTpy.NonlinearObjectiveFunction(direction: ObjectiveDirection, linearTerms: LinearTerms, expression: Expression, constant: SupportsFloat | SupportsIndex)

class SHOTpy.NonlinearObjectiveFunction(direction: ObjectiveDirection, linearTerms: LinearTerms, quadraticTerms: QuadraticTerms, expression: Expression, constant: SupportsFloat | SupportsIndex)

add(terms: LinearTerms) → None

add(term: LinearTerm) → None

add(terms: QuadraticTerms) → None

add(term: QuadraticTerm) → None

add(expression: Expression) → None

add(terms: MonomialTerms) → None

add(term: MonomialTerm) → None

add(terms: SignomialTerms) → None

add(term: SignomialTerm) → None

Helper for @overload to raise when called.

property monomialTerms: MonomialTerms

The monomial terms of the objective function

property nonlinearExpression: Expression

The nonlinear expression of the objective function, None if it has none

property nonlinearExpressionIndex: int

The position of the nonlinear expression among those that SHOT differentiates automatically, -1 if it has none

property signomialTerms: SignomialTerms

The signomial terms of the objective function

property variablesInNonlinearExpression: Variables

The variables in the nonlinear expression

class SHOTpy.NumericConstraint

calculateFunctionValue(point: collections.abc.Sequence[SupportsFloat | SupportsIndex]) → float

calculateFunctionValue(box: collections.abc.Sequence[Interval]) → Interval

Helper for @overload to raise when called.

calculateGradient(point)

Calculate the gradient at the point as a dict {variable index: value} of its nonzeros. A point of the reformulated problem can be used for a function of the original problem, since it has the variables of the original problem first

Parameters:

point (Sequence[SupportsFloat | SupportsIndex])

Return type:

dict[int, float]

calculateHessian(point)

Calculate the Hessian at the point as a dict {(index1, index2): value} of the nonzeros in its upper triangle, i.e., index1 <= index2. The Hessian is symmetric, so the element (index2, index1) has the same value. A point of the reformulated problem can be used for a function of the original problem, since it has the variables of the original problem first

Parameters:

point (Sequence[SupportsFloat | SupportsIndex])

Return type:

dict[tuple[int, int], float]

calculateIntervalDerivatives(box, order=2)

Calculate bounds over the box, which has an Interval for each variable, of the value and the derivatives up to the order (0, 1 or 2) with interval arithmetic. See IntervalDerivatives for when they enclose them

Parameters:

• box (Sequence[Interval])

• order (SupportsInt | SupportsIndex)

Return type:

IntervalDerivatives

calculateNumericValue(point)

Calculate the value of the constraint and how much it deviates from its bounds at the point

Parameters:

point (Sequence[SupportsFloat | SupportsIndex])

Return type:

NumericConstraintValue

getConstraintFunctionBounds()

The bounds of f(x) of the constraint L <= f(x) <= U over the variable bounds of the problem. They are [SHOT_DBL_MIN, SHOT_DBL_MAX] if they cannot be calculated

Return type:

Interval

getGradientSparsityPattern()

Get gradient sparsity pattern as list of variable indices

Return type:

list[int]

getHessianSparsityPattern()

Get Hessian sparsity pattern as list of (var1_index, var2_index)

Return type:

list[tuple[int, int]]

isFulfilled(point)

Whether the constraint is fulfilled at the point

Parameters:

point (Sequence[SupportsFloat | SupportsIndex])

Return type:

bool

property constant: float

The constant term of f(x)

property index: int

The index of the constraint in the problem it has been added to, -1 before that

property name: str

The name of the constraint

property properties: ConstraintProperties

Properties of the constraint, e.g., its convexity, which finalize() calculates

property valueLHS: float

The lower bound L of the constraint L <= f(x) <= U, SHOT_DBL_MIN if there is none

property valueRHS: float

The upper bound U of the constraint L <= f(x) <= U, SHOT_DBL_MAX if there is none

class SHOTpy.NumericConstraintValue

The value of a constraint L <= f(x) <= U at a point, and how much it deviates from its bounds

property constraint: NumericConstraint

The constraint the value is for

property error: float

max(0, L - f(x), f(x) - U)

property functionValue: float

f(x)

property isFulfilled: bool

Whether L <= f(x) <= U

property isFulfilledLHS: bool

Whether L <= f(x)

property isFulfilledRHS: bool

Whether f(x) <= U

property normalizedLHSValue: float

L - f(x)

property normalizedRHSValue: float

f(x) - U

property normalizedValue: float

max(L - f(x), f(x) - U)

class SHOTpy.ObjectiveDirection(value)

Members:

Minimize

Maximize

Parameters:

value (SupportsInt | SupportsIndex)

Maximize: ClassVar[ObjectiveDirection]

Minimize: ClassVar[ObjectiveDirection]

property name: str

property value: int

class SHOTpy.ObjectiveFunction

calculateGradient(point)

Calculate the gradient at the point as a dict {variable index: value} of its nonzeros. A point of the reformulated problem can be used for a function of the original problem, since it has the variables of the original problem first

Parameters:

point (Sequence[SupportsFloat | SupportsIndex])

Return type:

dict[int, float]

calculateHessian(point)

Calculate the Hessian at the point as a dict {(index1, index2): value} of the nonzeros in its upper triangle, i.e., index1 <= index2. The Hessian is symmetric, so the element (index2, index1) has the same value. A point of the reformulated problem can be used for a function of the original problem, since it has the variables of the original problem first

Parameters:

point (Sequence[SupportsFloat | SupportsIndex])

Return type:

dict[tuple[int, int], float]

calculateIntervalDerivatives(box, order=2)

Calculate bounds over the box, which has an Interval for each variable, of the value and the derivatives up to the order (0, 1 or 2) with interval arithmetic. See IntervalDerivatives for when they enclose them

Parameters:

• box (Sequence[Interval])

• order (SupportsInt | SupportsIndex)

Return type:

IntervalDerivatives

calculateValue(point: collections.abc.Sequence[SupportsFloat | SupportsIndex]) → float

calculateValue(box: collections.abc.Sequence[Interval]) → Interval

Helper for @overload to raise when called.

getBounds()

The bounds of the objective function over the variable bounds of the problem. They are [SHOT_DBL_MIN, SHOT_DBL_MAX] if they cannot be calculated

Return type:

Interval

getGradientSparsityPattern()

Get gradient sparsity pattern as list of variable indices

Return type:

list[int]

getHessianSparsityPattern()

Get Hessian sparsity pattern as list of (var1_index, var2_index)

Return type:

list[tuple[int, int]]

property constant: float

The constant term of the objective function

property direction: ObjectiveDirection

Whether the objective function is minimized or maximized

property properties: ObjectiveFunctionProperties

Properties of the objective function, e.g., its convexity, which finalize() calculates

class SHOTpy.ObjectiveFunctionProperties

property convexity: Convexity

The convexity of the objective function as far as SHOT can determine it, which finalize() calculates

property hasLinearTerms: bool

Whether it has linear terms

property hasMonomialTerms: bool

Whether it has monomial terms

property hasNonlinearExpression: bool

Whether it has a nonlinear expression

property hasQuadraticTerms: bool

Whether it has quadratic terms

property hasSignomialTerms: bool

Whether it has signomial terms

property isMaximize: bool

Whether the objective function is maximized

property isMinimize: bool

Whether the objective function is minimized

class SHOTpy.PairIndexValue

property index: int

The index, e.g., of a constraint

property value: float

The value for the index

class SHOTpy.PrimalCandidateCheckContext

rejectCandidate()

SHOT will not check the candidate, so it cannot become a primal solution

Return type:

None

property isCandidateRejected: bool

Whether the candidate has been rejected, by this or an earlier callback

property objectiveValue: float

The objective value of the candidate

property point: list[float]

The candidate, in the variables of the original problem

property source: PrimalSolutionSource

Where the candidate comes from, e.g., PrimalSolutionSource.NLPFixedIntegers

class SHOTpy.PrimalCandidateSearchContext

addPrimalSolution(point)

Add a primal solution candidate in the variables of the original or the reformulated problem

Parameters:

point (Sequence[SupportsFloat | SupportsIndex])

Return type:

None

property addedPrimalSolutions: list[list[float]]

The points added with addPrimalSolution() in this context

class SHOTpy.PrimalNLPFixedPoint(value)

Members:

AllSolutions

FirstSolution

AllFeasibleSolutions

FirstAndFeasibleSolutions

SmallestDeviationSolution

Parameters:

value (SupportsInt | SupportsIndex)

AllFeasibleSolutions: ClassVar[PrimalNLPFixedPoint]

AllSolutions: ClassVar[PrimalNLPFixedPoint]

FirstAndFeasibleSolutions: ClassVar[PrimalNLPFixedPoint]

FirstSolution: ClassVar[PrimalNLPFixedPoint]

SmallestDeviationSolution: ClassVar[PrimalNLPFixedPoint]

property name: str

property value: int

class SHOTpy.PrimalNLPProblemSource(value)

Members:

OriginalProblem

ReformulatedProblem

Both

Parameters:

value (SupportsInt | SupportsIndex)

Both: ClassVar[PrimalNLPProblemSource]

OriginalProblem: ClassVar[PrimalNLPProblemSource]

ReformulatedProblem: ClassVar[PrimalNLPProblemSource]

property name: str

property value: int

class SHOTpy.PrimalNLPSolver(value)

Members:

Ipopt

GAMS

SHOT

Uno

NotUsed

Parameters:

value (SupportsInt | SupportsIndex)

GAMS: ClassVar[PrimalNLPSolver]

Ipopt: ClassVar[PrimalNLPSolver]

NotUsed: ClassVar[PrimalNLPSolver]

SHOT: ClassVar[PrimalNLPSolver]

Uno: ClassVar[PrimalNLPSolver]

property name: str

property value: int

class SHOTpy.PrimalNLPStrategy(value)

Members:

AlwaysUse

IterationOrTime

IterationOrTimeAndAllFeasibleSolutions

Parameters:

value (SupportsInt | SupportsIndex)

AlwaysUse: ClassVar[PrimalNLPStrategy]

IterationOrTime: ClassVar[PrimalNLPStrategy]

IterationOrTimeAndAllFeasibleSolutions: ClassVar[PrimalNLPStrategy]

property name: str

property value: int

class SHOTpy.PrimalSolution

property boundProjectionPerformed: bool

Whether values outside the variable bounds were moved to the bounds

property displayed: bool

Whether the solution has been shown in the log

property integerRoundingPerformed: bool

Whether the values of integer variables were rounded

property iterFound: int

The iteration in which the solution was found

property maxDevatingConstraintLinear: PairIndexValue

The same as maxDeviatingConstraintLinear; the misspelled name is kept for existing code

property maxDevatingConstraintNonlinear: PairIndexValue

The same as maxDeviatingConstraintNonlinear; the misspelled name is kept for existing code

property maxDevatingConstraintQuadratic: PairIndexValue

The same as maxDeviatingConstraintQuadratic; the misspelled name is kept for existing code

property maxDeviatingConstraintLinear: PairIndexValue

The index of the linear constraint the solution violates the most and the violation, index -1 if there is none

property maxDeviatingConstraintNonlinear: PairIndexValue

The index of the nonlinear constraint the solution violates the most and the violation, index -1 if there is none

property maxDeviatingConstraintQuadratic: PairIndexValue

The index of the quadratic constraint the solution violates the most and the violation, index -1 if there is none

property maxIntegerToleranceError: float

The largest distance of an integer variable from an integer value before rounding

property objValue: float

The objective value of the solution

property point: list[float]

The values of the variables, in the order of their indexes

property sourceDescription: str

A description of where the solution comes from

property sourceType: PrimalSolutionSource

Where the solution comes from, e.g., PrimalSolutionSource.NLPFixedIntegers

class SHOTpy.PrimalSolutionSource(value)

Members:

Rootsearch

RootsearchFixedIntegers

NLPFixedIntegers

NLPRelaxed

MIPSolutionPool

LPFixedIntegers

MIPCallback

InteriorPointSearch

ConvexBounding

ExternalPrimalSolution

Parameters:

value (SupportsInt | SupportsIndex)

ConvexBounding: ClassVar[PrimalSolutionSource]

ExternalPrimalSolution: ClassVar[PrimalSolutionSource]

InteriorPointSearch: ClassVar[PrimalSolutionSource]

LPFixedIntegers: ClassVar[PrimalSolutionSource]

MIPCallback: ClassVar[PrimalSolutionSource]

MIPSolutionPool: ClassVar[PrimalSolutionSource]

NLPFixedIntegers: ClassVar[PrimalSolutionSource]

NLPRelaxed: ClassVar[PrimalSolutionSource]

Rootsearch: ClassVar[PrimalSolutionSource]

RootsearchFixedIntegers: ClassVar[PrimalSolutionSource]

property name: str

property value: int

class SHOTpy.Problem(environment: Environment)

class SHOTpy.Problem(solver: Solver)

addConstraint(constraint: NonlinearConstraint) → None

addConstraint(constraint: QuadraticConstraint) → None

addConstraint(constraint: LinearConstraint) → None

addConstraint(constraint: NumericConstraint) → None

addConstraint(constraint: ConstraintExpression, name: str = '') → None

Helper for @overload to raise when called.

addConstraints(constraints: collections.abc.Sequence[NumericConstraint]) → None

addConstraints(constraints: collections.abc.Sequence[ConstraintExpression], names: Sequence[str] = []) → None

Helper for @overload to raise when called.

addSpecialOrderedSet(sos)

Add a special ordered set of variables of the problem

Parameters:

sos (SpecialOrderedSet)

Return type:

None

addVariable(variable: Variable) → None

addVariable(name: str = '', type: VariableType = ..., lowerBound: SupportsFloat | SupportsIndex | None = None, upperBound: SupportsFloat | SupportsIndex | None = None, semiBound: SupportsFloat | SupportsIndex | None = None) → Variable

Helper for @overload to raise when called.

addVariables(variables)

Add all the variables of a list at once. Raises ValueError, adding none of them, if one has already been added to a problem or is in the list twice

Parameters:

variables (Variables)

Return type:

None

finalize()

Finalize the problem: extract terms from expressions, update properties, and prepare for solving. Raises ValueError if a constraint or the objective function has a variable that has not been added to the problem.

Return type:

None

getConstraint(index: SupportsInt | SupportsIndex) → NumericConstraint

getConstraint(name: str) → NumericConstraint

Helper for @overload to raise when called.

getConstraintsHessianSparsityPattern()

Get Hessian sparsity pattern for constraints only as list of (var1_index, var2_index)

Return type:

list[tuple[int, int]]

getConstraintsJacobianSparsityPattern()

Get Jacobian sparsity pattern as list of (constraint_index, [variable_indices])

Return type:

list[tuple[int, list[int]]]

getLagrangianHessianSparsityPattern()

Get Hessian sparsity pattern including objective as list of (var1_index, var2_index)

Return type:

list[tuple[int, int]]

getMostDeviatingNumericConstraint(point)

The value of the constraint that deviates most from its bounds at the point, or None if all constraints are fulfilled

Parameters:

point (Sequence[SupportsFloat | SupportsIndex])

Return type:

NumericConstraintValue | None

getVariable(index)

The variable with the index

Parameters:

index (SupportsInt | SupportsIndex)

Return type:

Variable

getVariableBounds()

The bounds of all the variables as Intervals, in the order of their indexes. It can be used as the box for the interval evaluation of the functions

Return type:

list[Interval]

getVariableLowerBound(index)

The lower bound of the variable with the index

Parameters:

index (SupportsInt | SupportsIndex)

Return type:

float

getVariableLowerBounds()

The lower bounds of all the variables, in the order of their indexes

Return type:

list[float]

getVariableUpperBound(index)

The upper bound of the variable with the index

Parameters:

index (SupportsInt | SupportsIndex)

Return type:

float

getVariableUpperBounds()

The upper bounds of all the variables, in the order of their indexes

Return type:

list[float]

setObjective(objective: NonlinearObjectiveFunction) → None

setObjective(objective: QuadraticObjectiveFunction) → None

setObjective(objective: LinearObjectiveFunction) → None

setObjective(objective: ObjectiveFunction) → None

setObjective(expression: Expression, direction: ObjectiveDirection = ...) → None

setObjective(variable: Variable, direction: ObjectiveDirection = ...) → None

setObjective(constant: SupportsFloat | SupportsIndex, direction: ObjectiveDirection = ...) → None

Helper for @overload to raise when called.

toString()

Get the full string representation of the problem

Return type:

str

updateProperties()

Update problem properties

Return type:

None

property allVariables: Variables

All the variables, in the order of their indexes

property binaryVariables: Variables

The binary variables

property integerVariables: Variables

The integer variables

property isFinalized: bool

Whether finalize() has been called, after which nothing can be added to the problem

property linearConstraints: list[LinearConstraint]

The linear constraints, which finalize() sorts out

property name: str

The name of the problem, used in the log and the results

property nonlinearConstraints: list[NonlinearConstraint]

The nonlinear constraints, which finalize() sorts out

property nonlinearExpressionVariables: Variables

The variables in the nonlinear expressions of the constraints and the objective function, which finalize() collects

property numericConstraints: list[NumericConstraint]

All the constraints, in the order of their indexes

property objectiveFunction: ObjectiveFunction

The objective function. finalize() may replace it with one of another class, so read it after finalize()

property properties: ProblemProperties

Properties of the problem, e.g., its convexity and the numbers of variables and constraints, which finalize() calculates

property quadraticConstraints: list[QuadraticConstraint]

The quadratic constraints, which finalize() sorts out

property realVariables: Variables

The continuous variables

class SHOTpy.ProblemConvexity(value)

Members:

Convex

Nonconvex

NotSet

Parameters:

value (SupportsInt | SupportsIndex)

Convex: ClassVar[ProblemConvexity]

Nonconvex: ClassVar[ProblemConvexity]

NotSet: ClassVar[ProblemConvexity]

property name: str

property value: int

class SHOTpy.ProblemProperties

property convexity: ProblemConvexity

The convexity of the problem as far as SHOT can determine it

property description: str

A description of the problem

property isDiscrete: bool

Whether the problem has binary, integer, semicontinuous or semi-integer variables, or special ordered sets

property isLPProblem: bool

Whether the problem is a continuous linear problem

property isMILPProblem: bool

Whether the problem is a mixed-integer linear problem

property isMINLPProblem: bool

Whether the problem is a mixed-integer problem with nonlinear terms other than quadratic ones

property isMIQCQPProblem: bool

Whether the problem is a mixed-integer problem with quadratic constraints and a linear or quadratic objective function

property isMIQPProblem: bool

Whether the problem is a mixed-integer problem with a quadratic objective function and linear constraints

property isNLPProblem: bool

Whether the problem is a continuous problem with nonlinear terms other than quadratic ones

property isNonlinear: bool

Whether the problem has nonlinear terms other than quadratic ones

property isQCQPProblem: bool

Whether the problem is a continuous problem with quadratic constraints and a linear or quadratic objective function

property isQPProblem: bool

Whether the problem is a continuous problem with a quadratic objective function and linear constraints

property isReformulated: bool

Whether this is the reformulated problem that SHOT solves

property isValid: bool

Whether the properties are up to date; finalize() calculates them

property name: str

The name of the problem

property numberOfBinaryVariables: int

The number of binary variables

property numberOfConvexNonlinearConstraints: int

The number of nonlinear constraints that are convex

property numberOfConvexQuadraticConstraints: int

The number of quadratic constraints that are convex

property numberOfDiscreteVariables: int

The number of binary and integer variables

property numberOfIntegerVariables: int

The number of integer variables, not counting binary or semi-integer ones

property numberOfLinearConstraints: int

The number of linear constraints

property numberOfNonconvexNonlinearConstraints: int

The number of nonlinear constraints that are not convex

property numberOfNonconvexQuadraticConstraints: int

The number of quadratic constraints that are not convex

property numberOfNonlinearConstraints: int

The number of nonlinear constraints

property numberOfNonlinearExpressions: int

The number of nonlinear expressions, including one in the objective function

property numberOfNumericConstraints: int

The number of constraints

property numberOfQuadraticConstraints: int

The number of quadratic constraints

property numberOfRealVariables: int

The number of continuous variables

property numberOfSemicontinuousVariables: int

The number of semicontinuous variables

property numberOfSpecialOrderedSets: int

The number of special ordered sets

property numberOfVariables: int

The number of variables

property numberOfVariablesInNonlinearExpressions: int

The number of variables in the nonlinear expressions

class SHOTpy.QuadraticConstraint(name: str, lhs: SupportsFloat | SupportsIndex, rhs: SupportsFloat | SupportsIndex)

class SHOTpy.QuadraticConstraint(name: str, linearTerms: LinearTerms, quadraticTerms: QuadraticTerms, lhs: SupportsFloat | SupportsIndex, rhs: SupportsFloat | SupportsIndex)

add(terms: LinearTerms) → None

add(term: LinearTerm) → None

add(terms: QuadraticTerms) → None

add(term: QuadraticTerm) → None

Helper for @overload to raise when called.

property quadraticTerms: QuadraticTerms

The quadratic terms of the constraint

class SHOTpy.QuadraticObjectiveFunction(direction: ObjectiveDirection)

class SHOTpy.QuadraticObjectiveFunction(direction: ObjectiveDirection, constant: SupportsFloat | SupportsIndex)

class SHOTpy.QuadraticObjectiveFunction(direction: ObjectiveDirection, linearTerms: LinearTerms, quadraticTerms: QuadraticTerms, constant: SupportsFloat | SupportsIndex)

add(terms: LinearTerms) → None

add(term: LinearTerm) → None

add(terms: QuadraticTerms) → None

add(term: QuadraticTerm) → None

Helper for @overload to raise when called.

property quadraticTerms: QuadraticTerms

The quadratic terms of the objective function

class SHOTpy.QuadraticProblemStrategy(value)

Members:

Nonlinear

QuadraticObjective

ConvexQuadraticallyConstrained

NonconvexQuadraticallyConstrained

Parameters:

value (SupportsInt | SupportsIndex)

ConvexQuadraticallyConstrained: ClassVar[QuadraticProblemStrategy]

NonconvexQuadraticallyConstrained: ClassVar[QuadraticProblemStrategy]

Nonlinear: ClassVar[QuadraticProblemStrategy]

QuadraticObjective: ClassVar[QuadraticProblemStrategy]

property name: str

property value: int

class SHOTpy.QuadraticTerm(coefficient, firstVariable, secondVariable)

Parameters:

• coefficient (SupportsFloat | SupportsIndex)

• firstVariable (Variable)

• secondVariable (Variable)

property coefficient: float

The coefficient of the term

property firstVariable: Variable

The first variable of the term

property isBilinear: bool

Whether the term is a product of two different variables

property isSquare: bool

Whether the term is the square of a variable

property secondVariable: Variable

The second variable of the term

class SHOTpy.QuadraticTerms

class SHOTpy.QuadraticTerms(terms: collections.abc.Sequence[QuadraticTerm])

class SHOTpy.QuadraticTerms(coefficients: collections.abc.Sequence[SupportsFloat | SupportsIndex], firstVariables: collections.abc.Sequence[Variable], secondVariables: collections.abc.Sequence[Variable])

add(term: QuadraticTerm) → None

add(terms: QuadraticTerms) → None

Helper for @overload to raise when called.

append(term)

Append a term without merging it with an existing term of the same variables

Parameters:

term (QuadraticTerm)

Return type:

None

extend(terms)

Append the terms of a list without merging them

Parameters:

terms (Sequence[QuadraticTerm])

Return type:

None

reserve(size)

Reserve room for the given total number of terms

Parameters:

size (SupportsInt | SupportsIndex)

Return type:

None

size()

The number of terms

Return type:

int

class SHOTpy.SOSType(value)

Members:

One

Two

Parameters:

value (SupportsInt | SupportsIndex)

One: ClassVar[SOSType]

Two: ClassVar[SOSType]

property name: str

property value: int

class SHOTpy.SignomialElement(variable, power)

Parameters:

• variable (Variable)

• power (SupportsFloat | SupportsIndex)

property power: float

The power of the factor

property variable: Variable

The variable of the factor

class SHOTpy.SignomialTerm(coefficient: SupportsFloat | SupportsIndex, elements: collections.abc.Sequence[SignomialElement])

class SHOTpy.SignomialTerm(coefficient: SupportsFloat | SupportsIndex, variablePowerPairs: collections.abc.Sequence[tuple[Variable, SupportsFloat | SupportsIndex]])

property coefficient: float

The coefficient of the term

property elements: list[SignomialElement]

The factors variable^power of the term

class SHOTpy.SignomialTerms

class SHOTpy.SignomialTerms(terms: collections.abc.Sequence[SignomialTerm])

add(term: SignomialTerm) → None

add(terms: SignomialTerms) → None

Helper for @overload to raise when called.

append(term)

Append a term without merging it with an existing term of the same variables

Parameters:

term (SignomialTerm)

Return type:

None

extend(terms)

Append the terms of a list without merging them

Parameters:

terms (Sequence[SignomialTerm])

Return type:

None

reserve(size)

Reserve room for the given total number of terms

Parameters:

size (SupportsInt | SupportsIndex)

Return type:

None

size()

The number of terms

Return type:

int

class SHOTpy.SolutionPoint

property hashValue: float

A hash of the point, used to recognize points that have been seen before

property isRelaxedPoint: bool

Whether the point is a solution of a relaxation, e.g., of an LP problem

property iterFound: int

The iteration in which the point was found

property maxDeviation: PairIndexValue

The index of the constraint the point violates the most and the violation

property objectiveValue: float

The objective value at the point

property point: list[float]

The values of the variables, in the order of their indexes

class SHOTpy.SolutionStatistics

getNumberOfTotalDualProblems()

The total number of dual problems solved

Return type:

int

property hasFixedIntegerEnumerationBeenRun: bool

Whether NLP problems have been solved for all combinations of the discrete variables

property hasFixedIntegerEnumerationFallbackBeenRun: bool

Whether this has been done as a fallback when the objective gap could not be closed

property hasInfeasibilityRepairBeenPerformedSincePrimalImprovement: bool

Whether the dual problem has been repaired since the primal bound last improved

property hasReductionCutBeenAddedSincePrimalImprovement: bool

Whether a primal reduction cut has been added since the primal bound last improved

property iterationLastDualBoundUpdate: int

The last iteration in which the dual bound improved

property iterationLastDualCutAdded: int

The last iteration in which a cut was added to the dual problem

property iterationLastLazyAdded: int

The last iteration in which a lazy constraint was added in the single-tree strategy

property iterationLastPrimalBoundUpdate: int

The last iteration in which the primal bound improved

property lastIterationWithSignificantDualUpdate: int

The last iteration in which the dual bound improved significantly

property lastIterationWithSignificantPrimalUpdate: int

The last iteration in which the primal bound improved significantly

property numberOfDualRepairsSinceLastPrimalUpdate: int

The number of repairs of an infeasible dual problem since the primal bound last improved

property numberOfExploredNodes: int

The number of branch-and-bound nodes explored by the MIP solver

property numberOfFixedIntegerEnumerationCombinations: int

The number of combinations of the discrete variables in the exhaustive search

property numberOfFixedIntegerEnumerationCombinationsFeasible: int

The number of combinations whose NLP problem gave a solution

property numberOfFixedIntegerEnumerationCombinationsInfeasible: int

The number of combinations whose NLP problem was infeasible

property numberOfFixedIntegerEnumerationCombinationsSkipped: int

The number of combinations not solved since they had been used in the fixed-integer strategy

property numberOfFixedIntegerEnumerationCombinationsUnresolved: int

The number of combinations whose NLP problem ended at a limit or with an error

property numberOfFoundPrimalSolutions: int

The number of primal solutions found

property numberOfFunctionEvaluations: int

The number of evaluations of nonlinear functions

property numberOfFunctionEvalutions: int

The same as numberOfFunctionEvaluations; the misspelled name is kept for existing code

property numberOfGradientEvaluations: int

The number of evaluations of gradients of nonlinear functions

property numberOfHyperplanesWithConvexSource: int

The number of cuts generated for convex functions

property numberOfHyperplanesWithNonconvexSource: int

The number of cuts generated for nonconvex functions, which are not valid for the whole problem

property numberOfIntegerCuts: int

The number of integer cuts added

property numberOfIterations: int

The number of main iterations

property numberOfIterationsWithDualStagnation: int

The number of iterations since the dual bound last improved significantly

property numberOfIterationsWithPrimalStagnation: int

The number of iterations since the primal bound last improved significantly

property numberOfIterationsWithoutNLPCallMIP: int

The number of iterations with a MIP problem since an NLP problem was last solved

property numberOfOpenNodes: int

The number of open branch-and-bound nodes of the MIP solver

property numberOfOriginalInteriorPoints: int

The number of interior points found for the ESH algorithm

property numberOfPrimalImprovementsAfterInfeasibilityRepair: int

The number of primal bound improvements after a repair of the dual problem

property numberOfPrimalImprovementsAfterReductionCut: int

The number of primal bound improvements after a primal reduction cut

property numberOfPrimalReductionCutsUpdatesWithoutEffect: int

The number of primal reduction cuts that did not improve the primal bound

property numberOfPrimalReductionsPerformed: int

The number of primal reduction cuts added

property numberOfProblemsFeasibleMILP: int

The number of MILP problems solved until a feasible solution was found, e.g., with a solution limit

property numberOfProblemsFeasibleMIQCQP: int

The number of MIQCQP problems solved until a feasible solution was found

property numberOfProblemsFeasibleMIQP: int

The number of MIQP problems solved until a feasible solution was found

property numberOfProblemsFixedNLP: int

The number of NLP problems with fixed integer variables solved to find primal solutions

property numberOfProblemsLP: int

The number of LP problems solved as dual problems

property numberOfProblemsMinimaxLP: int

The number of LP problems solved in the search for an interior point

property numberOfProblemsOptimalMILP: int

The number of MILP problems solved to optimality

property numberOfProblemsOptimalMIQCQP: int

The number of MIQCQP problems solved to optimality

property numberOfProblemsOptimalMIQP: int

The number of MIQP problems solved to optimality

property numberOfProblemsQCQP: int

The number of QCQP problems solved as dual problems

property numberOfProblemsQP: int

The number of QP problems solved as dual problems

property numberOfSuccessfulDualRepairsPerformed: int

The number of successful repairs of an infeasible dual problem

property numberOfUnsuccessfulDualRepairsPerformed: int

The number of unsuccessful repairs of an infeasible dual problem

property timeLastDualBoundUpdate: float

The time in seconds when the dual bound last improved

property timeLastFixedNLPCall: float

The time in seconds when an NLP problem with fixed integer variables was last solved

class SHOTpy.Solver

getAbsoluteObjectiveGap()

The absolute difference between the primal bound and the global dual bound, inf if either is missing

Return type:

float

getBoolSetting(name)

The value of a boolean setting, e.g., ‘Model.Convexity.AssumeConvex’. Raises RuntimeError if there is no boolean setting with the name

Parameters:

name (str)

Return type:

bool

getCurrentDualBound()

The dual bound of the current dual problem, -inf (inf when maximizing) if there is none. For a nonconvex problem, it is not a valid bound for the problem once cuts have been added to nonconvex functions; use getGlobalDualBound() for a valid bound

Return type:

float

getDoubleSetting(name)

The value of a floating point setting, e.g., ‘Termination.TimeLimit’. Raises RuntimeError if there is no floating point setting with the name

Parameters:

name (str)

Return type:

float

getEnvironment()

The environment of the solver, which holds its settings, results and problems. A problem is created in it with Problem(solver)

Return type:

Environment

getGlobalDualBound()

The best dual bound that is valid for the problem, also when it is nonconvex, -inf (inf when maximizing) if there is none. The objective gaps are calculated from it

Return type:

float

getIntSetting(name)

The value of an integer or enum setting, e.g., ‘Dual.MIP.Solver’. Raises RuntimeError if there is no such setting with the name

Parameters:

name (str)

Return type:

int

getModelReturnStatus()

The status of the solution, e.g., ModelReturnStatus.OptimalGlobal when the solution is proven optimal, or FeasibleSolution when a solution has been found without proving it optimal

Return type:

ModelReturnStatus

getOptions()

The settings that differ from their defaults, in the format of an options file

Return type:

str

getOptionsOSoL()

The settings that differ from their defaults, in the OSoL format

Return type:

str

getOriginalProblem()

The problem given to setProblem(), or None before it has been set

Return type:

Problem

getPrimalBound()

The objective value of the best solution found, inf (-inf when maximizing) if none has been found

Return type:

float

getPrimalSolution()

The best solution found. Raises an exception if none has been found; check hasPrimalSolution() first

Return type:

PrimalSolution

getPrimalSolutions()

All the solutions found, the best first

Return type:

list[PrimalSolution]

getReformulatedProblem()

The problem that SHOT solves, created from the original problem by setProblem(), e.g., with auxiliary variables for nonlinear terms, or None before the problem has been set

Return type:

Problem

getRelativeObjectiveGap()

The relative difference between the primal bound and the global dual bound, inf if either is missing

Return type:

float

getResultsOSrL()

The results in the OSrL format

Return type:

str

getResultsSol()

The results in the AMPL .sol format

Return type:

str

getResultsTrace()

The results as a line in the GAMS trace file format

Return type:

str

getSettingsAsMarkup()

All the settings, with descriptions, valid values and defaults, as Markdown

Return type:

str

getSolutionStatistics()

Statistics of the solution process, e.g., the number of iterations and of solved subproblems

Return type:

SolutionStatistics

getStringSetting(name)

The value of a string setting. Raises RuntimeError if there is no string setting with the name

Parameters:

name (str)

Return type:

str

getTerminationReason()

Why SHOT terminated, e.g., TerminationReason.RelativeGap when the objective gap was closed

Return type:

TerminationReason

hasPrimalSolution()

Whether the problem has been solved and a solution has been found

Return type:

bool

outputOptionsReport()

Write the settings that differ from their defaults to the log

Return type:

None

outputProblemInstanceReport()

Write the properties of the problem to the log

Return type:

None

outputSolutionReport()

Write the solution report, with the bounds, the status and the statistics, to the log

Return type:

None

outputSolverHeader()

Write the header of SHOT, with its version and the solvers it uses, to the log

Return type:

None

registerCallback(locations, callback)

Register a callback for one or several locations in the solution process.

The locations are given as a CallbackLocation, several combined with |, or a list of them. The callback is called as fn(context), where the context is of the class for the location, e.g., a PrimalCandidateCheckContext at CallbackLocation.PrimalCandidateCheck, and has the state of the solver and the actions available at the location. The context can only be used while the callback runs. If the callback raises an exception, SHOT terminates and solveProblem() raises it.

Returns a handle for removeCallback().

Parameters:

• locations (CallbackLocation | SupportsInt | SupportsIndex | Iterable[CallbackLocation])

• callback (Callable[[CallbackContext], None])

Return type:

int

removeCallback(handle)

Remove a registered callback; returns False if there is no callback with the handle.

Parameters:

handle (SupportsInt | SupportsIndex)

Return type:

bool

setLogFile(filename)

Also write the log to a file

Parameters:

filename (str)

Return type:

bool

setOptionsFromFile(filename)

Read settings from an options file (.opt) or an OSoL file (.osol or .xml); returns False if it fails

Parameters:

filename (str)

Return type:

bool

setOptionsFromOSoL(osol)

Read settings from a string in the OSoL format; returns False if it fails

Parameters:

osol (str)

Return type:

bool

setOptionsFromString(options)

Read settings from a string in the format of an options file, e.g., ‘Termination.TimeLimit = 10’; returns False if it fails

Parameters:

options (str)

Return type:

bool

setProblem(filename: str) → bool

setProblem(problem: Problem) → bool

setProblem(problem: Problem, reformulatedProblem: Problem) → bool

Helper for @overload to raise when called.

solveProblem()

Solve the problem given to setProblem(). Returns False if it could not be solved, e.g., if no problem has been set; the outcome is given by getModelReturnStatus() and getTerminationReason(). An exception raised in a callback is raised again here

Return type:

bool

updateLogLevels()

Apply the settings Output.Console.LogLevel and Output.File.LogLevel to the log

Return type:

None

updateSetting(name: str, value: bool) → None

updateSetting(name: str, value: SupportsInt | SupportsIndex) → None

updateSetting(name: str, value: str) → None

updateSetting(name: str, value: SupportsFloat | SupportsIndex) → None

Helper for @overload to raise when called.

class SHOTpy.SpecialOrderedSet(sosType, variables, weights=[])

Parameters:

• sosType (SOSType)

• variables (collections.abc.Sequence[Variable])

• weights (collections.abc.Sequence[SupportsFloat | SupportsIndex])

property type: SOSType

The type of the set, SOSType.One or SOSType.Two

property variables: list[Variable]

The variables of the set

property weights: list[float]

The weights of the variables, which give their order

class SHOTpy.TerminationCheckContext

class SHOTpy.TerminationReason(value)

Members:

ConstraintTolerance

ObjectiveStagnation

IterationLimit

TimeLimit

InfeasibleProblem

UnboundedProblem

Error

AbsoluteGap

RelativeGap

UserAbort

NoDualCutsAdded

NotTerminated

NumericIssues

Parameters:

value (SupportsInt | SupportsIndex)

AbsoluteGap: ClassVar[TerminationReason]

ConstraintTolerance: ClassVar[TerminationReason]

Error: ClassVar[TerminationReason]

InfeasibleProblem: ClassVar[TerminationReason]

IterationLimit: ClassVar[TerminationReason]

NoDualCutsAdded: ClassVar[TerminationReason]

NotTerminated: ClassVar[TerminationReason]

NumericIssues: ClassVar[TerminationReason]

ObjectiveStagnation: ClassVar[TerminationReason]

RelativeGap: ClassVar[TerminationReason]

TimeLimit: ClassVar[TerminationReason]

UnboundedProblem: ClassVar[TerminationReason]

UserAbort: ClassVar[TerminationReason]

property name: str

property value: int

class SHOTpy.TreeStrategy(value)

Members:

MultiTree

SingleTree

Parameters:

value (SupportsInt | SupportsIndex)

MultiTree: ClassVar[TreeStrategy]

SingleTree: ClassVar[TreeStrategy]

property name: str

property value: int

class SHOTpy.Variable(name: str, type: VariableType, lowerBound: SupportsFloat | SupportsIndex, upperBound: SupportsFloat | SupportsIndex)

class SHOTpy.Variable(name: str, type: VariableType, lowerBound: SupportsFloat | SupportsIndex, upperBound: SupportsFloat | SupportsIndex, semiBound: SupportsFloat | SupportsIndex)

getBound()

The bounds of the variable as an Interval

Return type:

Interval

property index: int

The index of the variable in the problem it has been added to, -1 before that. It is the position of its value in a point, e.g., of a solution

property lowerBound: float

The lower bound; -inf is stored as SHOT_DBL_MIN, i.e., no bound. Changing it after finalize() updates the bounds of the problem

property name: str

The name of the variable

property properties: VariableProperties

Properties of the variable, e.g., its type and whether it is in nonlinear terms

property semiBound: float

For a semicontinuous or semiinteger variable, the value is 0 or between semiBound and upperBound (or between lowerBound and semiBound if semiBound is negative)

property upperBound: float

The upper bound; inf is stored as SHOT_DBL_MAX, i.e., no bound. Changing it after finalize() updates the bounds of the problem

class SHOTpy.VariableProperties

property inLinearConstraints: bool

Whether the variable is in a linear constraint

property inNonlinearConstraints: bool

Whether the variable is in a nonlinear constraint

property inObjectiveFunction: bool

Whether the variable is in the objective function

property inQuadraticConstraints: bool

Whether the variable is in a quadratic constraint

property isAuxiliary: bool

Whether the variable has been added by the reformulation

property isNonlinear: bool

Whether the variable is in a nonlinear term of a constraint or the objective function

property type: VariableType

The type of the variable, e.g., VariableType.Integer

class SHOTpy.VariableType(value)

Members:

Real

Binary

Integer

Semicontinuous

Semiinteger

Parameters:

value (SupportsInt | SupportsIndex)

Binary: ClassVar[VariableType]

Integer: ClassVar[VariableType]

Real: ClassVar[VariableType]

Semicontinuous: ClassVar[VariableType]

Semiinteger: ClassVar[VariableType]

property name: str

property value: int

class SHOTpy.Variables

class SHOTpy.Variables(variables: collections.abc.Sequence[Variable])

append(variable)

Append a variable

Parameters:

variable (Variable)

Return type:

None

extend(variables)

Append the variables of a list

Parameters:

variables (Sequence[Variable])

Return type:

None

reserve(size)

Reserve room for the given total number of variables

Parameters:

size (SupportsInt | SupportsIndex)

Return type:

None

size()

The number of variables

Return type:

int

SHOTpy.abs(x: Variable) → Expression

SHOTpy.abs(x: Expression) → Expression

Helper for @overload to raise when called.

SHOTpy.acos(x: Variable) → Expression

SHOTpy.acos(x: Expression) → Expression

Helper for @overload to raise when called.

SHOTpy.asin(x: Variable) → Expression

SHOTpy.asin(x: Expression) → Expression

Helper for @overload to raise when called.

SHOTpy.atan(x: Variable) → Expression

SHOTpy.atan(x: Expression) → Expression

Helper for @overload to raise when called.

SHOTpy.cos(x: Variable) → Expression

SHOTpy.cos(x: Expression) → Expression

Helper for @overload to raise when called.

SHOTpy.cosh(x: Variable) → Expression

SHOTpy.cosh(x: Expression) → Expression

Helper for @overload to raise when called.

SHOTpy.errorf(x: Variable) → Expression

SHOTpy.errorf(x: Expression) → Expression

Helper for @overload to raise when called.

SHOTpy.exp(x: Variable) → Expression

SHOTpy.exp(x: Expression) → Expression

Helper for @overload to raise when called.

SHOTpy.getSupportedMIPSolvers()

Returns a list of MIP solvers supported in this build

Return type:

list[MIPSolver]

SHOTpy.getSupportedModelingSystems()

Returns a list of modeling systems supported in this build

Return type:

list[ModelingSystem]

SHOTpy.getSupportedNLPSolvers()

Returns a list of NLP solvers supported in this build

Return type:

list[PrimalNLPSolver]

SHOTpy.inequality(lower: SupportsFloat | SupportsIndex, expression: Variable, upper: SupportsFloat | SupportsIndex) → ConstraintExpression

SHOTpy.inequality(lower: SupportsFloat | SupportsIndex, expression: Expression, upper: SupportsFloat | SupportsIndex) → ConstraintExpression

Helper for @overload to raise when called.

SHOTpy.log(x: Variable) → Expression

SHOTpy.log(x: Expression) → Expression

Helper for @overload to raise when called.

SHOTpy.max(*args)

The maximum of variables, expressions and numbers, given separately or as one list. It is reformulated with absolute values, max(a, b) = (a + b + |a - b|)/2, which need a binary variable only where the optimum does not push the maximum down

Return type:

Expression

SHOTpy.min(*args)

The minimum of variables, expressions and numbers, given separately or as one list. It is reformulated with absolute values, min(a, b) = (a + b - |a - b|)/2, which need a binary variable only where the optimum does not push the minimum up

Return type:

Expression

SHOTpy.signpower(x: Variable, exponent: SupportsFloat | SupportsIndex) → Expression

SHOTpy.signpower(x: Expression, exponent: SupportsFloat | SupportsIndex) → Expression

Helper for @overload to raise when called.

SHOTpy.sin(x: Variable) → Expression

SHOTpy.sin(x: Expression) → Expression

Helper for @overload to raise when called.

SHOTpy.sinh(x: Variable) → Expression

SHOTpy.sinh(x: Expression) → Expression

Helper for @overload to raise when called.

SHOTpy.sqrt(x: Variable) → Expression

SHOTpy.sqrt(x: Expression) → Expression

Helper for @overload to raise when called.

SHOTpy.square(x: Variable) → Expression

SHOTpy.square(x: Expression) → Expression

Helper for @overload to raise when called.

SHOTpy.tan(x: Variable) → Expression

SHOTpy.tan(x: Expression) → Expression

Helper for @overload to raise when called.

SHOTpy.tanh(x: Variable) → Expression

SHOTpy.tanh(x: Expression) → Expression

Helper for @overload to raise when called.