Knitro / Python reference

See Getting started with Python for a quick introduction to Knitro Python and exampleSingleCall.py in the Python repository of the Knitro distribution for additional examples.

Knitro Python single call function

knitro.optimize(variables, objective=None, constraints=None, compConstraints=None, callbacks=None, algorithm=None, options=None, optionsFile=None)

Solve an optimization problem using Artelys Knitro.

This function is designed to provide maximal flexibility to the end-user. Note that the user should try to provide as much information as possible as it usualy leads to improve the performance of Knitro.

Parameters

variables: Variables object

Structure containing all the knitro.Variables related information.

objective: Objective object, optionnal

Structure containing all the knitro.Objective related information.

constraints: Constraints object, optional

Structure containing all the knitro.Constraints related information

compConstraints: ComplementarityConstraints object, optional

Structure containing all the knitro.ComplementarityConstraints related information.

callbacks: array, Callback object, optional

Structure containing all the knitro.Callback related information.

algorithm: int or str, optional

The algorithms to be used by knitro:

interior-direct
interior-cg
active-set
sqp

options: dict, optional

A dictionary of solver options.

optionsFile: str, optional

A file containing solver options.

Returns

solution: Solution object: Structure containing solve related information. See Solution for a detailed description.

Notes

Regarding the options setting, algorithm takes precedence over the options dictionnary which itself takes precedence over the optionsFile.

Variables

class knitro.Variables(nV, xLoBnds=None, xUpBnds=None, xTypes=None, xInitVals=None, lambdaInitVals=None, xScale=None, xHonorBnds=None, xProperties=None, xNames=None)

Store mathematical definition of the variables.

nV: int

Number of variables.

xTypes: array, optional

The type of the variables (e.g. KN_VARTYPE_CONTINUOUS, KN_VARTYPE_BINARY, KN_VARTYPE_INTEGER). There are two ways to specify the types:

array, shape (nV, 1): define all the variables type.

2. array, shape (2, n_vars): define the type for a subset of n_vars variables using two arrays. The first array defines the variables index and the second one their types. For example, variables 0 and 2 are defined as binary:

xTypes=[[0, 2], [KN_VARTYPE_BINARY, KN_VARTYPE_BINARY]]

If not set, variables are assumed to be continuous by default.

xLoBnds: array, optional

The lower bounds of the variables. There are two ways to specify the lower bounds:

array, shape (nV, 1): define all the variables lower bound.

2. array, shape (2, n_vars): define the lower bound for n_vars variables using two arrays. The first array defines the variables index and the second one their lower bounds. For examples, variables 0 and 2 have their lower bounds set to 0:

xLoBnds=[[0, 2], [0, 0]]

If not set, lower bounds are assumed to be -KN_INFINITY.

xUpBnds: array, optional

The upper bounds of the variables. There are two ways to specify the upper bounds:

array, shape (nV, 1): define all the variables upper bound.

2. array, shape (2, n_vars): define the upper bound for n_vars variables using two arrays. The first array defines the variables index and the second one their upper bounds. For example, variables 0 and 2 have their upper bounds set to 10:

xUpBnds=[[0, 2], [10, 10]]

If not set, upper bounds are assumed to be KN_INFINITY.

xInitVals: array, optional

The initial primal values of the variables. There are two ways to specify the initial values:

array, shape (nV, 1): define all the variables initial values.

2. array, shape (2, n_vars): define the initial values for n_vars variables using two arrays. The first array defines the variables index and the second one their values. For example, variables 0 and 2 are initially set to -1 and 3:

xInitVals=[[0, 2], [-1, 3]]

If not set, variables may be initialized as 0 or initialized by Knitro based on some initialization strategy (perhaps determined by a user option).

lambdaInitVals: array, optional

The initial dual values of the variables (i.e. the Lagrange multipliers corresponding to the bounded variables). There are two ways to specify the initial dual values:

array, shape (nV, 1): defines all the variables initial values.

2. array, shape (2, n_vars): defines the initial values for n_vars variables only using two arrays. The first array defines the variables index and the second one their values. For example, variables 0 and 2 are initially set to -1 and 3:

lambdaInitVals=[[0, 2], [-1, 3]]

If not set, dual variables may be initialized as 0 or initialized by Knitro based on some initialization strategy (perhaps determined by a user option).

xScale: array, optional

Define scaling of variables to perform a linear scaling around specified centering values:

x[i] = xScaleFactors[i] * xScaled[i] + xScaleCenters[i]

These scaling factors should try to represent the typical values of the x variables so that the scaled variables (xScaled) used internally by Knitro are close to one. The values for xScaleFactors should be positive. If a non-positive value is specified, that variable will not be scaled. There are two ways to specify the scaling value:

1. array, shape (2, nV): define all the variables xScaleFactors and xScaleCenters as two arrays.

2. array, shape (3, n_vars): define the scaling values for n_vars variables only using three arrays. The first array defines the variables index, the second one their scaling factor and the third one their scaling center. For example, variables 0 and 2 only are scaled:

xScale=[[0, 2], [2, 2], [0, 0]]

xHonorBnds: array, optional

Indicates whether to enforce satisfaction of simple variable bounds throughout the optimization (e.g KN_HONORBNDS_NO, KN_HONORBNDS_ALWAYS, KN_HONORBNDS_INITPT). There are two ways to specify the honor bounds values:

array, shape (nV, 1): defines all the variables honor bounds.

2. array, shape (2, n_vars): defines the honor bounds for n_vars variables only using two arrays. The first array defines the variables index and the second one their values. For example, we enforce that variables 0 and 2 satisfy their bounds at initial point:

xHonorBnds=[[0, 2], [KN_HONORBNDS_INITPT, KN_HONORBNDS_INITPT]]

xProperties: array, optional

Specify some properties of the variables. Currently this routine is only used to mark variables as linear (e.g KN_VAR_LINEAR). There are two ways to specify the properties:

array, shape (nV, 1): define all the variables properties.

2. array, shape (2, n_vars): define the properties for n_vars variables using two arrays. The first array defines the variables index and the second one their properties. For example, we mark variables 0 and 2 as linear:

xProperties=[[0, 2], [KN_VAR_LINEAR, KN_VAR_LINEAR]]

Variables are assumed to be nonlinear variables by default.

xNames: array, optional

Specify the name of the variables so that Knitro can internally print out these names. There are two ways to specify the names of the variables:

array, shape (nV, 1): define all the variables names.

2. array, shape (2, n_vars): define the names for n_vars variables using two arrays. The first array defines the variables index and the second one their names. For example, we name variables 0 and 2:

xNames=[[0, 2], ['var0', 'var2']]).

Objective

class knitro.Objective(objGoal=None, objConstant=None, objLinear=None, objQuadratic=None, objScaleFactor=None)

Store mathematical definition of the problem objective.

objGoal: int, optional

Set the objective goal (KN_OBJGOAL_MINIMIZE or KN_OBJGOAL_MAXIMIZE). If not set, the default goal is set to minimization.

objConstant: float, optional

Add a constant to the objective function.

objLinear: array shape (2, n_vars), optional

Add linear structure to the objective function. The first array defines n_vars variables index and the second one n_vars coefficient values. For example, two linear structures are added to the objective, 2*x[0] and -x[3]:

objLinear=[[[0, 3], [2, -1]]

objQuadratic: array shape (3,n_vars), optional

Add quadratic structure to the objective function. The first two arrays define n_vars variables indices and the last one n_vars coefficient values. For example, one quadratic structure is added to the objective 2*x[0]*x[1]:

objQuadratic=[[0], [1], [2]]

objScaleFactor: float, optional

Set a scaling value for the objective function:

objScaled = objScaleFactor * obj

This scaling factor should try to represent the typical value of the inverse of the objective function value obj so that the scaled objective (objScaled) used internally by Knitro is close to one. The value for objScaleFactor should be positive. If a non-positive value is specified, then the objective will use either the standard Knitro scaling (KN_SCALE_USER_INTERNAL), or no scaling (KN_SCALE_USER_NONE).

Constraints

class knitro.Constraints(nC, cType=None, cLoBnds=None, cUpBnds=None, cEqBnds=None, cConstant=None, cLinear=None, cQuadratic=None, lambdaInitVals=None, cScaleFactors=None, cNames=None)

Store mathematical definition of the contraints.

nC: int

The number of constraints

cType: array, optional

The type of the constraints (e.g. KN_CONTYPE_GENERAL, KN_CONTYPE_LINEAR, KN_CONTYPE_QUADRATIC). There are two ways to specify the types:

array, shape (nC, 1): define all the constraints types.

2. array, shape (2, n_cons): define the types for n_cons constraints using two arrays. The first array defines the constraints index and the second one their types. For example, constraints 0 and 2 are defined as linear:

cType=[[0, 2], [KN_CONTYPE_LINEAR, KN_CONTYPE_LINEAR]]

If not set, constraints are assumed to be general.

cLoBnds: array, optional

The lower bounds of the constraints. There are two ways to specify the lower bounds:

array, shape (nC, 1): define all the constraints lower bounds.

2. array, shape (2, n_cons): define the lower bounds for n_cons constraints using two arrays. The first array defines the constraints index and the second one their lower bounds. For example, constraints 0 and 2 have their lower bounds set to 0:

cLoBnds=[[0, 2], [0, 0]]

If not set, lower bounds are assumed to be -KN_INFINITY.

cUpBnds: array, optional

The upper bounds of the constraints. There are two ways to specify the upper bounds:

array, shape (nC, 1): define all the constraints upper bounds.

2. array, shape (2, n_cons): define the upper bound for n_cons constraints using two arrays. The first array defines the constraints index and the second one their upper bounds. For example, constraints 0 and 2 have their upper bounds set to 10:

cUpBnds=[[0, 2], [10, 10]]

If not set, upper bounds are assumed to be KN_INFINITY.

cEqBnds: array, optional

The equality bounds of the constraints. There are two ways to specify the equality bounds:

array, shape (nC, 1): define all the constraints equality bounds.

2. array, shape (2, n_cons): define the equality bound for n_cons constraints using two arrays. The first array defines the constraints index and the second one their equality bounds. For example, constraints 0 and 2 have their equality bounds set to 10:

cEqBnds=[[0, 2], [10, 10]]

cConstant: array, optional

Add constants to the body of constraint functions. There are two ways to specify the constants:

array, shape (nC, 1): define all the constraints constants.

2. array, shape (2, n_cons): define the constant structure for n_cons constraints using two arrays. The first array defines the constraints index and the second one their values. For example, constraints 0 and 2 have a constant term equal to respectively -1 and 3:

cConstant=[[0, 2], [-1, 3]]

cLinear: array, optional

Add linear structure to the constraints. There are two ways to specify the linear structure:

array, shape (nC, 1): define all the constraints linear structure.

2. array, shape (3, n_cons): define the linear structure for n_cons constraints using three arrays. The first array defines the constraint index, the second one the variable index and the third one the coefficient values. For example, constraints 1 and 2 have one linear structure respectively equal to 2*x[0] and -x[3]:

cLinear=[[1, 2], [0, 3], [2, -1]]

cQuadratic: array, optional

Add quadratic structure to the constraint functions. There are two ways to specify the quadratic structure:

array, shape (nC, 1): define all the constraints quadratic structure.

2. array, shape (4, n_cons): define the quadratic structure for n_cons constraints using four arrays. The first array defines the constraint index, the second one the first variable index, the third one the second variable index and the last one the coefficient values. For example, constraint 1 has one quadratic structure equal to 2*x[0]*x[1]:

cQuadratic=[[1], [0], [1], [2]]

lambdaInitVals: array, optional

The initial dual values of the constraints (i.e. the Lagrange multipliers for the constraints). There are two ways to specify the initial dual values:

array, shape (nC, 1): define all the constraints initial values.

2. array, shape (2, n_cons): define the initial values for n_cons constraints using two arrays. The first array defines the constraints index and the second one their values. For example, constraints 0 and 2 are initially set to -1 and 3:

lambdaInitVals=[[0, 2], [-1, 3]]

If not set, constraints dual variables may be initialized as 0 or initialized by Knitro based on some initialization strategy (perhaps determined by a user option).

cScaleFactors: array, optional

Set an array of constraint scaling values to perform a scaling:

cScaled[i] = cScaleFactors[i] * c[i]

for each constraint. These scaling factors should try to represent the typical values of the inverse of the constraint values c so that the scaled constraints (cScaled) used internally by Knitro are close to one. The values for cScaleFactors should be positive. If a non-positive value is specified, that constraint will use either the standard Knitro scaling (KN_SCALE_USER_INTERNAL), or no scaling (KN_SCALE_USER_NONE). Scaling factors for standard constraints can be provided with cScaleFactors, while scalings for complementarity constraint can be specified with ccScaleFactors (see Complementarity constraints). There are two ways to specify the scaling value:

array, shape (nC, 1): define all the constraints cScaleFactors.

2. array, shape (2, n_cons): define the scaling values for n_cons constraints using two arrays. The first array defines the constraints index and the second one their scaling factor (e.g constraints 0 and 2 only are scaled):

cScaleFactors=[[0, 2], [2, 2]

cNames: array, optional

Specify the names of the constraints so that Knitro can internally print out them. There are two ways to specify the constraints names:

array, shape (nC, 1): define all the constraints names.

2. array, shape (2, n_cons): define the names for n_cons constraints using two arrays. The first array defines the constraints index and the second one their names. For example, we name constraints 0 and 2:

cNames=[[0, 2], ['con0', 'con2']]

Complementarity Constraints

class knitro.ComplementarityConstraints(ccTypes=None, indexComps1=None, indexComps2=None, ccScaleFactors=None, cNames=None)

Store mathematical definition of the complementarity constraints.

nCc: int

The number of complementarity constraints

ccTypes: array, optional

Specify the type of complementarity:

KN_CCTYPE_VARVAR: two (non-negative) variables

KN_CCTYPE_VARCON: a variable and a constraint

KN_CCTYPE_CONCON: two constraints

Note: Currently only KN_CCTYPE_VARVAR is supported. The other ccTypes will be added in future releases. The length of ccTypes must be equal to indexComps1 and indexComps2 length.

indexComps1: array, optional

Specify the variable indice of the first element of each complementarity constraint. Each pair (indexComps1, indexComps2) defines a complementarity constraint between the two variables. The two array of variable indices must be of equal length, and contain matching pairs of variable indices.

indexComps2: array, optional

Specify the variable indice of the second element of each complementarity constraint. Each pair (indexComps1, indexComps2) defines a complementarity constraint between the two variables. The two array of variable indices must be of equal length, and contain matching pairs of variable indices.

ccScaleFactors: array, optional

Set an array of constraint scaling values to perform a scaling:

ccScaled[i] = ccScaleFactors[i] * cc[i]

for each constraint. These scaling factors should try to represent the typical values of the inverse of the complementarity constraint values c so that the scaled complementarity constraints (cScaled) used internally by Knitro are close to one. The values for ccScaleFactors should be positive. If a non-positive value is specified, that constraint will use either the standard Knitro scaling (KN_SCALE_USER_INTERNAL), or no scaling (KN_SCALE_USER_NONE). There are two ways to specify the scaling value:

array, shape (nCc, 1): define all the constraints ccScaleFactors.

2. array, shape (2, n_cons): define the scaling values for n_cons complementarity constraints using two arrays. The first array defines the constraints index and the second one their scaling factor. For example, complementarity constraints 0 and 2 only are scaled:

ccScaleFactors=[[0, 2], [2, 2]]

cNames: array, optional

Specify the name of the complementarity constraints so that Knitro can internally print out these names. There are two ways to specify the complementarity constraints names:

array, shape (nCc, 1): define all the constraints names.

2. array, shape (2, n_cons): define the names for n_cons complementarity constraints only using two arrays. The first array defines the constraints index and the second one their names. For example, we name complementarity constraints 0 and 2:

cNames=[[0, 2], ['compCon0', 'compCon2']]

Callback

class knitro.Callback(funcCallback, evalObj=None, indexCons=None, evalFCGA=False, gradCallback=None, objGradIndexVars=None, jacIndexCons=None, jacIndexVars=None, hessCallback=None, hessIndexVars1=None, hessIndexVars2=None, hessianNoFAllow=False)

Store the definition of optimization callbacks.

funcCallback: Function

Function evaluating the objective and any constraint parts involved in this callback. If evalFCGA is equal to True, the callback should also evaluate the relevant first derivatives/gradients.

evalObj: boolean, optional

Indicate whether any part of the objective function is evaluated in the callback. If not specified, evalObj is set to False. If both, evalObj and indexCons are not specified, the funcCallback is considered to provide a generic callback evaluating the objective function and all constraints.

indexCons: array of shape (n_cons,), optional

Index of the n_cons constraints evaluated in the callback. If not specified, indexCons is set to None. If both evalObj and indexCons are not specified, the funcCallback is considered to provide a callback for objective function and all constraints.

evalFCGA: boolean, optional

Indicate if the first derivatives/gradients are also evaluated in the funcCallBack.

Note: It is generally more efficient and recommended to have separate callback routines for functions and gradients since a gradient evaluation is not always needed for every function evaluations. However, in some cases, it may be more convenient to compute them together if most of the work for computing the gradients is already done while evaluating the function.

gradCallback: Function, optional

Function evaluating the components of the first derivatives/gradients of the objective and the constraint involved in this callback. If not specified, Knitro will approximate the gradient using finite-differencing. However, we recommend providing callbacks to evaluate the exact gradients whenever possible as this can drastically improve the performance of Knitro. If evalFCGA is True, the first derivatives are expected to be evaluated in the funcCallback and gradCallback is not required.

objGradIndexVars: array of shape (n_vars,), optionnal

The n_vars nonzero indices of the objective gradient. If the objective gradient evaluated in gradCallback is dense, objGradIndexVars should be set to KN_DENSE.

jacIndexCons: array of shape (nnzj,), optional

Store nnzj indexes (row) of each nonzero in the Jacobian of the constraints involved in this callback. If the Jacobian evaluated in gradCallback is dense, jacIndexCons should be set to KN_DENSE_ROWMAJOR to provide the full Jacobian in row major order (i.e. ordered by rows/constraints), or KN_DENSE_COLMAJOR to provide the full Jacobian in column major order (i.e. ordered by columns/variables). The user should always try to define the sparsity structure for the Jacobian (jacIndexCons, jacIndexVars). Even when using finite-difference approximations to compute the gradients, knowing the sparse structure of the Jacobian can allow Knitro to compute these finite-difference approximations faster.

jacIndexVars: array of shape (nnzj,), optional

Store nnzj index (column) of each nonzero in the Jacobian of the constraints parts involved in this callback. If the Jacobian evaluated in gradCallback is dense, jacIndexVars is not required.

hessCallback: Function, optional

Function evaluating the components of the Hessian of the Lagrangian corresponding to the objective and any constraint involved in this callback. If not specified, Knitro will approximate the Hessian by finite-difference. However, providing a callback for the exact Hessian (as well as the non-zero sparsity structure) can greatly improve Knitro performance and is recommended if possible.

hessIndexVars1: array of shape (nnzh,), optional

Store nnzh index of each nonzero in the Hessian of the Lagrangian. If the Hessian evaluated in hessCallback is dense, hessIndexVars1 should be set to KN_DENSE_ROWMAJOR to provide the full upper triangular Hessian in row major order, or KN_DENSE_COLMAJOR to provide the full upper triangular Hessian in column major order. Note that the Hessian is symmetric, so the lower triangular components are the same as the upper triangular components with row and column indices swapped.

hessIndexVars2: array of shape (nnzh,), optional

Store nnzh index of of each nonzero in the Hessian of the Lagrangian. If the Hessian evaluated in hessCallback is dense, hessIndexVars2 is not required.

hessianNoFAllow: boolean, optional

Specify that the user is able to provide evaluations of the Hessian matrix without the objective component. Turned off by default but should be enabled if possible.

Solution

class knitro.Solution(kc)

Store the solution returned by Knitro.

status: int

The solution status return codes are organized as follows.

0: the final solution satisfies the termination conditions for verifying optimality.
-100 to -199: a feasible approximate solution was found.
-200 to -299: Knitro terminated at an infeasible point.
-300: the problem was determined to be unbounded.
-400 to -499: Knitro terminated because it reached a pre-defined limit

(-40x codes indicate that a feasible point was found before reaching the

limit, while -41x codes indicate that no feasible point was found before

reaching the limit).
-500 to -599: Knitro terminated with an input error or some non-standard error.

obj: double

Final objective value.

x: array

Primal variables optimal values.

lambdaVals: array

Dual variables optimal values.

iter: int

Number of iterations.

numFCevals: int

Number of function evaluations.

numGAevals: int

Number of gradient evaluations.

numHevals: int

Number of Hessian evaluations.

numHVevals: int

Number of Hessian-vector products evaluations.

absFeasError: double

Absolute feasibility error at the solution.

relFeasError: double

Relative feasibility error at the solution.

absOptError: double

Absolute optimality error at the solution.

relOptError: double

Relative optimality error at the solution.

solveTimeCPU: double

Retrieve Knitro solve time as CPU time.

solveTimeReal: double

Retrieve Knitro solve time as real time.