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 enduser. 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:
interiordirect
interiorcg
activeset
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 theoptions
dictionnary which itself takes precedence over theoptionsFile
.
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 nonpositive 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
orKN_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 nonpositive 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 nonpositive 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 (nonnegative) variablesKN_CCTYPE_VARCON
: a variable and a constraintKN_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 nonpositive 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 finitedifferencing. 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), orKN_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 finitedifference approximations to compute the gradients, knowing the sparse structure of the Jacobian can allow Knitro to compute these finitedifference 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 finitedifference. However, providing a callback for the exact Hessian (as well as the nonzero 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, orKN_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 predefined limit(40x codes indicate that a feasible point was found before reaching thelimit, while 41x codes indicate that no feasible point was found beforereaching the limit).
500 to 599: Knitro terminated with an input error or some nonstandard 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 Hessianvector 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.