Callable library API reference
The various objects offered by the callable library API are listed here.
The file knitro.h is also a good source of information, and
the ultimate reference. In addition, the examples provided with the
Knitro distribution highlight most of the key features of the API and
are a good starting point.
Introduction and Philosophy
The callable library API for Knitro is designed to provide you maximum flexibility and ease-of-use in building a model. In addition, and just as importantly, it is designed to provide Knitro a great amount of structural information about your model, so that Knitro can exploit special structures wherever possible to improve performance. The API is designed so that you can build up a model in pieces based on what is most convenient for you. This means not only allowing you to add constraints one at a time (or in several blocks), but also allowing you to add special structures within constraints separately if desired.
The API is designed so that you can load constant, linear, quadratic, and conic structures as well as complementarity constraints separately. This allows Knitro to mark these structure types internally and provide special care to different structure types. For example, conic structures and complementarities are notoriously difficult if not handled with special care. In addition, the more structural information Knitro has, the more extensive presolve operations Knitro can perform to try to simplify the model internally. For this reason we always recommend making use of the API functions to provide as much fine-grained structural information as possible to Knitro. More general nonlinear structure must be handled through callback evaluation routines.
Structures of the same type can be added in individual pieces, in groups, or all together. Likewise, general nonlinear structures can all be handled by one callback object or broken up into separate callback objects if there are natural groupings that you want to treat differently. For example, you may be able to provide a callback routine to evaluate the exact analytic derivatives for some group of nonlinear constraints, while having Knitro approximate the derivatives for another group of nonlinear constraints using finite-differences. Implementing such a scheme is possible in the Knitro API.
The overhead costs for loading your model by pieces should be trivial in most cases – even for large models. However, if not, it is always possible – and most efficient – to load all the structures of one type together in one API function call.
All functions offered by the Knitro callable library are described in detail below.
Index
Here is a summary of Knitro API functions grouped by functionality.
Creating and destroying solver objects
API function name |
Purpose |
|---|---|
Create a new Knitro solver object |
|
Free/destroy an existing Knitro solver object |
Changing and reading solver parameters
API function name |
Purpose |
|---|---|
Reset all user options to their default values |
|
Read user options from a Knitro options file |
|
Read user options and values to explore for Knitro-Tuner |
|
Write all current user options to a file |
|
Set integer valued option using its string name |
|
Set character valued option using its string name |
|
Set double valued option using its string name |
|
Set integer or doubled valued option using its string name |
|
Set integer valued option using its integer identifier |
|
Set character valued option using its integer identifier |
|
Set double valued option using its integer identifier |
|
Get integer valued option using its string name |
|
Get double valued option using its string name |
|
Get integer valued option using its integer identifier |
|
Get double valued option using its integer identifier |
|
Get string name associated with user option |
|
Get documentation string associated with user option |
|
Get type (KN_PARAM_TYPE_*) associated with user option |
|
Get number of possible values associated with integer valued user option |
|
Get documentation string associated with user option value |
|
Get integer identifier associated with user option |
Basic problem construction
API function name |
Purpose |
|---|---|
Add new variables to a model |
|
Add new constraints to a model |
|
Add new residuals to a least-squares model |
|
Set lower bounds on variables |
|
Set upper bounds on variables |
|
Set fixed bounds on variables |
|
Set variable types (e.g., continuous, integer, etc) |
|
Set variable properties (e.g., linear) |
|
Set lower bounds on constraints |
|
Set upper bounds on constraints |
|
Set equality bounds on constraints |
|
Set constraint properties (e.g., convex) |
|
Set objective properties (e.g., convex) |
|
Specify minimize of maximize |
|
Set initial values for primal variables |
|
Set initial values for dual variables |
|
Set initial values for constraint multipliers |
Adding/removing/changing constant structure
API function name |
Purpose |
|---|---|
Add a constant to the objective |
|
Delete a constant from the objective |
|
Change a constant term in the objective |
|
Add constants to the constraints |
|
Delete constants from the constraints |
|
Change constant terms in the constraints |
|
Add constants to the residuals for least-squares models |
Adding/removing/changing linear structure
API function name |
Purpose |
|---|---|
Add linear structure to the objective |
|
Delete linear structure from the objective |
|
Change linear structure in the objective |
|
Add linear structure to the constraints |
|
Delete linear structure from the constraints |
|
Change linear structure in the constraints |
|
Add linear structure to the residuals for least-squares models |
Adding quadratic structure
API function name |
Purpose |
|---|---|
Add quadratic structure to the objective |
|
Add quadratic structure to the constraints |
Adding conic structure
API function name |
Purpose |
|---|---|
Add L2norm structure used to define conic constraints |
Adding complementarity constraints
API function name |
Purpose |
|---|---|
Set all complementarity constraints for a model |
Adding evaluation callbacks
API function name |
Purpose |
|---|---|
Add a callback for nolinear evaluations |
|
Add a callback for nolinear evaluations of all functions |
|
Add a callback for nolinear evaluations of one function |
|
Add a callback for nolinear least-squares evaluations |
|
Add a callback for nolinear least-squares evaluations of all functions |
|
Add a callback for nolinear least-squares evaluations of one function |
|
Set callback for objective gradient and constraint Jacobian |
|
Set callback for Hessian of the Lagrangian matrix |
|
Set callback for least-squares residual Jacobian |
|
Set a user parameters structure for evaluation callback |
|
Specify how to evaluate gradients in evaluation callback |
|
Specify finite-difference relative stepsizes |
|
Get the number of constraints evaluated through the callback |
|
Get the number of residuals evaluated through the callback |
|
Get the number of non-zero objective gradient elements evaluated through the callback |
|
Get the number of non-zero Jacobian elements evaluated through the callback |
|
Get the number of non-zero residual Jacobian elements evaluated through the callback |
|
Get the number of non-zero Hessian elements evaluated through the callback |
|
Other user callbacks
API function name |
Purpose |
|---|---|
Callback to perform some user-defined task after new solution estimate |
|
Callback to perform some user-defined task after MIP node solve |
|
Callback to perform some user-defined task after multi-start solve |
|
Callback to specify custom initial points for multi-start |
|
Callback to specify custom handling of output |
|
Callback to specify custom linear system solver |
Other algorithmic/modeling features
API function name |
Purpose |
|---|---|
Set custom feasibility tolerances for variables |
|
Set custom feasibility tolerances for constraints |
|
Set custom feasibility tolerances for complementarity constraints |
|
Set custom scalings for variables |
|
Set custom scalings for constraints |
|
Set custom scalings for complementarity constraints |
|
Set a custom scaling for the objective |
|
Set names for variables |
|
Set names for constraints |
|
Set names for complementarity constraints |
|
Set a name for the objective |
|
Enforce variables satisfy bounds throughout optimization |
|
Enforce (inequality) constraints satisfy bounds throughout optimization |
|
Set initial primal variable values for MIP |
|
Set branching priorities for integer variables |
|
Set strategies for handling integer variables |
Solving
API function name |
Purpose |
|---|---|
Call Knitro to solve/optimize the current model |
|
Call Knitro to update the current model |
Reading model/solution properties
API function name |
Purpose |
|---|---|
Get Knitro release number |
|
Get the number of variables in the model |
|
Get the number of constraints in the model |
|
Get the number of residuals in the model |
|
Get the number of function evaluations during the solve |
|
Get the number of gradient evaluations during the solve |
|
Get the number of Hessian evaluations during the solve |
|
Get the number of Hessian-vector product evaluations during the solve |
|
Get the solution status, objective and variables |
|
Get the value of the objective function |
|
Get the objective function type (e.g. linear, quadratic, general, etc.) |
|
Return the primal (“x”) variables |
|
Return the dual (“lambda”) values (i.e. Lagrange multipliers) for the variables |
|
Get the value of the constraint functions |
|
Get the constraint function types (e.g. linear, quadratic, general, etc.) |
|
Get the value of the residual functions |
|
Get the number of iterations (continuous models only) |
|
Get the number of conjugate gradient iterations (continuous models only) |
|
Get the absolute feasibility error (continuous models only) |
|
Get the relative feasibility error (continuous models only) |
|
Get the absolute optimality error (continuous models only) |
|
Get the relative optimality error (continuous models only) |
|
Get the objective gradient values (continuous models only) |
|
Get the objective gradient values in dense form (continuous models only) |
|
Get the constraint Jacobian values (continuous models only) |
|
Get the residual Jacobian values (continuous models only) |
|
Get the Hessian values (continuous models only) |
|
Get the number of MIP nodes explored (MIP models only) |
|
Get the number of MIP subproblem solves (MIP models only) |
|
Get the absolute optimality gap (MIP models only) |
|
Get the relative optimality gap (MIP models only) |
|
Get the objective value of the incumbent solution (MIP models only) |
|
Get the current relaxation bound (MIP models only) |
|
Get the objective value from the most recently solved node (MIP models only) |
|
Get the MIP incumbent solution variables (MIP models only) |
-
KN_get_release()
int KNITRO_API KN_get_release (const int length,
char * const release);
Copy the Knitro release name into release. This variable must be
preallocated to have length elements, including the string termination
character. For compatibility with future releases, please allocate at
least 15 characters.
Returns 0 if OK, nonzero if error.
Creating and destroying solver objects
-
KN_new()
int KNITRO_API KN_new (KN_context_ptr * kc);
This function must be called first. It returns a pointer to an object
(the Knitro “context pointer”) that is used in all other calls.
If you enable Knitro with the floating network license handler,
then this call also checks out a license and reserves it until
KN_free() is called with the context pointer, or the program ends.
The contents of the context pointer should never be modified by a calling
program. Returns 0 if OK, nonzero if error.
-
KN_free()
int KNITRO_API KN_free (KN_context_ptr * kc);
This function should be called last and will free the context pointer. The address of the context pointer is passed so that Knitro can set it to NULL after freeing all memory. This prevents the application from mistakenly calling Knitro functions after the context pointer has been freed. Returns 0 if OK, nonzero if error.
Changing and reading solver parameters
All methods return 0 if OK, nonzero if there was an error.
In most cases, parameter values are not validated until
KN_solve() is called.
-
KN_reset_params_to_defaults()
int KNITRO_API KN_reset_params_to_defaults (KN_context_ptr kc);
Reset all parameters to default values.
-
KN_load_param_file()
int KNITRO_API KN_load_param_file
(KN_context_ptr kc, const char * const filename);
Set all parameters specified in the given file.
-
KN_load_tuner_file()
int KNITRO_API KN_load_tuner_file
(KN_context_ptr kc, const char * const filename);
Similar to KN_load_param_file() but specifically allows user to
specify a file of options (and option values) to explore for
the Knitro-Tuner (see The Knitro-Tuner).
-
KN_save_param_file()
int KNITRO_API KN_save_param_file
(KN_context_ptr kc, const char * const filename);
Write all current parameter values to a file.
-
KN_set_int_param_by_name()
int KNITRO_API KN_set_int_param_by_name
(KN_context_ptr kc, const char * const name, const int value);
Set an integer valued parameter using its string name.
-
KN_set_char_param_by_name()
int KNITRO_API KN_set_char_param_by_name
(KN_context_ptr kc, const char * const name, const char * const value);
Set a character valued parameter using its string name.
-
KN_set_double_param_by_name()
int KNITRO_API KN_set_double_param_by_name
(KN_context_ptr kc, const char * const name, const double value);
Set a double valued parameter using its string name.
-
KN_set_param_by_name()
int KNITRO_API KN_set_param_by_name
(KN_context_ptr kc, const char * const name, const double value);
Set an integer or double valued parameter using its string name.
-
KN_set_int_param()
int KNITRO_API KN_set_int_param
(KN_context_ptr kc, const int param_id, const int value);
Set an integer valued parameter using its integer identifier (see Knitro user options).
-
KN_set_char_param()
int KNITRO_API KN_set_char_param
(KN_context_ptr kc, const int param_id, const char * const value);
Set a character valued parameter using its integer identifier (see Knitro user options).
-
KN_set_double_param()
int KNITRO_API KN_set_double_param
(KN_context_ptr kc, const int param_id, const double value);
Set a double valued parameter using its integer identifier (see Knitro user options).
-
KN_get_int_param_by_name()
int KNITRO_API KN_get_int_param_by_name
(KN_context_ptr kc, const char * const name, int * const value);
Get an integer valued parameter using its string name.
-
KN_get_double_param_by_name()
int KNITRO_API KN_get_double_param_by_name
(KN_context_ptr kc, const char * const name, double * const value);
Get a double valued parameter using its string name.
-
KN_get_int_param()
int KNITRO_API KN_get_int_param
(KN_context_ptr kc, const int param_id, int * const value);
Get an integer valued parameter using its integer identifier (see Knitro user options).
-
KN_get_double_param()
int KNITRO_API KN_get_double_param
(KN_context_ptr kc, const int param_id, double * const value);
Get a double valued parameter using its integer identifier (see Knitro user options).
-
KN_get_param_name()
int KNITRO_API KN_get_param_name
( KN_context_ptr kc,
const int param_id,
char * const param_name,
const size_t output_size);
Sets the string param_name to the name of parameter indexed by integer
identifier param_id (see Knitro user options) and returns 0. Returns an error if
param_id does not correspond to any parameter, or if the parameter output_size
(the size of char array param_name) is less than the size of the parameter’s
description.
-
KN_get_param_doc()
int KNITRO_API KN_get_param_doc
( KN_context_ptr kc,
const int param_id,
char * const description,
const size_t output_size);
Sets the string description to the description of the parameter indexed by
integer identifier param_id (see Knitro user options) and its possible values and
returns 0. Returns an error if param_id does not correspond to any parameter, or
if the parameter output_size (the size of char array description) is less than
the size of the parameter’s description.
-
KN_get_param_type()
int KNITRO_API KN_get_param_type
( KN_context_ptr kc,
const int param_id,
int * const param_type);
Sets the int * param_type to the type of the parameter indexed by
integer identifier param_id (see Knitro user options). Possible values are
KN_PARAMTYPE_INT, KN_PARAMTYPE_FLOAT, KN_PARAMTYPE_STRING. Returns an error
if param_id does not correspond to any parameter.
-
KN_get_num_param_values()
int KNITRO_API KN_get_num_param_values
( KN_context_ptr kc,
const int param_id,
int * const num_param_values);
Set the int * num_param_values to the number of possible parameter values for
the parameter indexed by integer identifier param_id and returns 0. If there is not
a finite number of possible values, num_param_values will be zero. Returns an
error if param_id does not correspond to any parameter.
-
KN_get_param_value_doc()
int KNITRO_API KN_get_param_value_doc
( KN_context_ptr kc,
const int param_id,
const int value_id,
char * const param_value_string,
const size_t output_size);
Set string param_value_string to the description of the parameter value indexed by
[param_id][value_id]. Returns an error if param_id does not correspond to any
parameter, or if value_id is greater than the number of possible parameter
values, or if there are not a finite number of possible parameter values, or if
the parameter output_size (the size of char array param_value_string) is less
than the size of the parameter’s description.
-
KN_get_param_id()
int KNITRO_API KN_get_param_id
( KN_context_ptr kc,
const char * const name,
int * const param_id);
Gets the integer value corresponding to the parameter name input and copies it
into param_id input. Returns zero if successful and an error code otherwise.
Basic problem construction
Problem structure is passed to Knitro using KN API functions.
The problem is solved by calling KN_solve(). Applications must
provide a means of evaluating the nonlinear objective, constraints,
first derivatives, and (optionally) second derivatives. (First
derivatives are also optional, but highly recommended.)
The typical calling sequence is:
KN_new
KN_add_vars/KN_add_cons/KN_set_*bnds, etc. (problem setup)
KN_add_*_linear_struct/KN_add_*_quadratic_struct (add special structures)
KN_add_eval_callback (add callback for nonlinear evaluations if needed)
KN_set_cb_* (set properties for nonlinear evaluation callbacks)
KN_set_xxx_param (set any number of parameters/user options)
KN_solve
KN_free
Generally, as long as no structural changes beyond linear changes are made to the model,
KN_solve() can be called in succession to re-solve a model after small changes.
For example, user options, variable bounds, and
constraint bounds can be changed between calls to KN_solve(), without
having to first call KN_free() and reload the model from scratch.
In addition, constant and linear structures in the model may be added, deleted,
or changed without having to reconstruct the model.
More extensive additions or changes to the model (such as adding quadratic structures or
callbacks) require freeing the existing
Knitro solver object and rebuilding the model from scratch.
See Problem modification and re-solving for more details on this topic.
-
KN_add_vars()
int KNITRO_API KN_add_vars ( KN_context_ptr kc,
const KNINT nV,
KNINT * const indexVars);
int KNITRO_API KN_add_var ( KN_context_ptr kc,
KNINT * const indexVar);
Add variables to the model. The parameter indexVars may be set to NULL.
Otherwise, on return it holds the global indices associated with the
variables that were added (indices are typically allocated sequentially).
Parameter indexVars can then be passed into other API routines that operate
on the set of variables added through a particular call to KN_add_vars().
Returns 0 if OK, nonzero if error.
-
KN_add_cons()
int KNITRO_API KN_add_cons ( KN_context_ptr kc,
const KNINT nC,
KNINT * const indexCons);
int KNITRO_API KN_add_con ( KN_context_ptr kc,
KNINT * const indexCon);
Add constraints to the model. The parameter indexCons may be set to NULL.
Otherwise, on return it holds the global indices associated with the
constraints that were added (indices are typically allocated sequentially).
Parameter indexCons can then be passed into other API routines that operate
on the set of constraints added through a particular call to KN_add_cons().
Returns 0 if OK, nonzero if error.
-
KN_add_rsds()
int KNITRO_API KN_add_rsds ( KN_context_ptr kc,
const KNINT nR,
KNINT * const indexRsds);
int KNITRO_API KN_add_rsd ( KN_context_ptr kc,
KNINT * const indexRsd);
Add residuals for least squares optimization. The parameter indexRsds may
be set to NULL. Otherwise, on return it holds the global indices associated
with the residuals that were added (indices are typically allocated sequentially).
Parameter indexRsds can then be passed into other API routines that operate
on the set of residuals added through a particular call to KN_add_rsds().
Note that the current Knitro API does not support adding both constraints
and residuals.
Returns 0 if OK, nonzero if error.
-
KN_set_var_lobnds()
int KNITRO_API KN_set_var_lobnds ( KN_context_ptr kc,
const KNINT nV,
const KNINT * const indexVars,
const double * const xLoBnds);
int KNITRO_API KN_set_var_lobnds_all ( KN_context_ptr kc,
const double * const xLoBnds);
int KNITRO_API KN_set_var_lobnd ( KN_context_ptr kc,
const KNINT indexVar,
const double xLoBnd);
Set lower bounds on variables – either in groups, all at once, or individually.
If not set, variables are assumed to be unbounded (e.g. lower bounds
are assumed to be -KN_INFINITY).
Returns 0 if OK, nonzero if error.
-
KN_set_var_upbnds()
int KNITRO_API KN_set_var_upbnds ( KN_context_ptr kc,
const KNINT nV,
const KNINT * const indexVars,
const double * const xUpBnds);
int KNITRO_API KN_set_var_upbnds_all ( KN_context_ptr kc,
const double * const xUpBnds);
int KNITRO_API KN_set_var_upbnd ( KN_context_ptr kc,
const KNINT indexVar,
const double xUpBnd);
Set upper bounds on variables – either in groups, all at once, or individually.
If not set, variables are assumed to be unbounded (e.g. upper bounds
are assumed to be KN_INFINITY).
Returns 0 if OK, nonzero if error.
-
KN_set_var_fxbnds()
int KNITRO_API KN_set_var_fxbnds ( KN_context_ptr kc,
const KNINT nV,
const KNINT * const indexVars,
const double * const xFxBnds);
int KNITRO_API KN_set_var_fxbnds_all ( KN_context_ptr kc,
const double * const xFxBnds);
int KNITRO_API KN_set_var_fxbnd ( KN_context_ptr kc,
const KNINT indexVar,
const double xFxBnd);
Set fixed bounds on variables – either in groups, all at once, or individually.
Adding a fixed bound creates a fixed variable and is equivalent to
adding identical lower and upper bounds on the same variable. If the Knitro presolver
is enabled, fixed variables will typically be presolved out of the model.
If not set, variables are assumed to be unbounded (e.g. lower bounds are assumed
to be -KN_INFINITY and upper bounds are assumed to be KN_INFINITY).
Returns 0 if OK, nonzero if error.
-
KN_get_var_lobnds()
int KNITRO_API KN_get_var_lobnds (const KN_context_ptr kc,
const KNINT nV,
const KNINT * const indexVars,
double * const xLoBnds);
int KNITRO_API KN_get_var_lobnds_all (const KN_context_ptr kc,
double * const xLoBnds);
int KNITRO_API KN_get_var_lobnd (const KN_context_ptr kc,
const KNINT indexVar,
double xLoBnd);
Get lower bounds on variables – either in groups, all at once, or individually. Returns 0 if OK, nonzero if error.
-
KN_get_var_upbnds()
int KNITRO_API KN_get_var_upbnds (const KN_context_ptr kc,
const KNINT nV,
const KNINT * const indexVars,
double * const xUpBnds);
int KNITRO_API KN_get_var_upbnds_all (const KN_context_ptr kc,
double * const xUpBnds);
int KNITRO_API KN_get_var_upbnd (const KN_context_ptr kc,
const KNINT indexVar,
double xUpBnd);
Get upper bounds on variables – either in groups, all at once, or individually. Returns 0 if OK, nonzero if error.
-
KN_get_var_fxbnds()
int KNITRO_API KN_get_var_fxbnds (const KN_context_ptr kc,
const KNINT nV,
const KNINT * const indexVars,
double * const xFxBnds);
int KNITRO_API KN_get_var_fxbnds_all (const KN_context_ptr kc,
double * const xFxBnds);
int KNITRO_API KN_get_var_fxbnd (const KN_context_ptr kc,
const KNINT indexVar,
double xFxBnd);
Get fixed bounds on variables – either in groups, all at once, or individually. Returns 0 if OK, nonzero if error.
-
KN_set_var_types()
int KNITRO_API KN_set_var_types ( KN_context_ptr kc,
const KNINT nV,
const KNINT * const indexVars,
const int * const xTypes);
int KNITRO_API KN_set_var_types_all ( KN_context_ptr kc,
const int * const xTypes);
int KNITRO_API KN_set_var_type ( KN_context_ptr kc,
const KNINT indexVar,
const int xType);
Set variable types (e.g. KN_VARTYPE_CONTINUOUS, KN_VARTYPE_BINARY,
KN_VARTYPE_INTEGER). If not set, variables are assumed to be continuous.
When a variable is set as binary, its lower bound is automatically
set to 0 and its upper bound is automatically set to 1 at the same time.
Returns 0 if OK, nonzero if error.
-
KN_get_var_types()
int KNITRO_API KN_get_var_types (const KN_context_ptr kc,
const KNINT nV,
const KNINT * const indexVars,
int * const xTypes);
int KNITRO_API KN_get_var_types_all (const KN_context_ptr kc,
int * const xTypes);
int KNITRO_API KN_get_var_type (const KN_context_ptr kc,
const KNINT indexVar,
int * const xType);
Return the variable types. The array xTypes must be allocated
by the user.
Returns 0 if OK, nonzero if error.
-
KN_set_var_properties()
int KNITRO_API KN_set_var_properties ( KN_context_ptr kc,
const KNINT nV,
const KNINT * const indexVars,
const int * const xProperties);
int KNITRO_API KN_set_var_properties_all ( KN_context_ptr kc,
const int * const xProperties);
int KNITRO_API KN_set_var_property ( KN_context_ptr kc,
const KNINT indexVar,
const int xProperty);
Specify some properties of the variables. Currently this API routine is only used to mark variables as linear, but other variable properties will be added in the future. Note: use bit-wise specification of the features:
bit |
value |
meaning |
|---|---|---|
0 |
1 |
KN_VAR_LINEAR |
default = 0 (variables are assumed to be nonlinear)
If a variable only appears linearly in the model, it can be very helpful to mark this by enabling bit 0. This information can then be used by Knitro to perform more extensive preprocessing. If a variable appears nonlinearly in any constraint or the objective (or if the user does not know) then it should not be marked as linear. Variables are assumed to be nonlinear variables by default. Knitro makes a local copy of all inputs, so the application may free memory after the call. Returns 0 if OK, nonzero if error.
-
KN_set_con_lobnds()
int KNITRO_API KN_set_con_lobnds ( KN_context_ptr kc,
const KNINT nC,
const KNINT * const indexCons,
const double * const cLoBnds);
int KNITRO_API KN_set_con_lobnds_all ( KN_context_ptr kc,
const double * const cLoBnds);
int KNITRO_API KN_set_con_lobnd ( KN_context_ptr kc,
const KNINT indexCon,
const double cLoBnd);
Set lower bounds on constraints – either in groups, all at once, or individually.
If not set, constraints are assumed to be unbounded (e.g. lower bounds
are assumed to be -KN_INFINITY).
Returns 0 if OK, nonzero if error.
-
KN_set_con_upbnds()
int KNITRO_API KN_set_con_upbnds ( KN_context_ptr kc,
const KNINT nC,
const KNINT * const indexCons,
const double * const cUpBnds);
int KNITRO_API KN_set_con_upbnds_all ( KN_context_ptr kc,
const double * const cUpBnds);
int KNITRO_API KN_set_con_upbnd ( KN_context_ptr kc,
const KNINT indexCon,
const double cUpBnd);
Set upper bounds on constraints – either in groups, all at once, or individually.
If not set, constraints are assumed to be unbounded (e.g. upper bounds
are assumed to be KN_INFINITY).
Returns 0 if OK, nonzero if error.
-
KN_set_con_eqbnds()
int KNITRO_API KN_set_con_eqbnds ( KN_context_ptr kc,
const KNINT nC,
const KNINT * const indexCons,
const double * const cEqBnds);
int KNITRO_API KN_set_con_eqbnds_all ( KN_context_ptr kc,
const double * const cEqBnds);
int KNITRO_API KN_set_con_eqbnd ( KN_context_ptr kc,
const KNINT indexCon,
const double cEqBnd);
Set equality bounds on constraints – either in groups, all at once, or individually.
Adding an equality bound creates an equality constraint and is equivalent to
adding identical lower and upper bounds on the same constraint.
If not set, constraints are assumed to be unbounded (e.g. lower bounds
are assumed to be -KN_INFINITY and upper bounds are assumed to be KN_INFINITY).
Returns 0 if OK, nonzero if error.
-
KN_get_con_lobnds()
int KNITRO_API KN_get_con_lobnds (const KN_context_ptr kc,
const KNINT nC,
const KNINT * const indexCons,
double * const cLoBnds);
int KNITRO_API KN_get_con_lobnds_all (const KN_context_ptr kc,
double * const cLoBnds);
int KNITRO_API KN_get_con_lobnd (const KN_context_ptr kc,
KNINT indexCon,
const double cLoBnd);
Get lower bounds on constraints – either in groups, all at once, or individually. Returns 0 if OK, nonzero if error.
-
KN_get_con_upbnds()
int KNITRO_API KN_get_con_upbnds (const KN_context_ptr kc,
const KNINT nC,
const KNINT * const indexCons,
double * const cUpBnds);
int KNITRO_API KN_get_con_upbnds_all (const KN_context_ptr kc,
double * const cUpBnds);
int KNITRO_API KN_get_con_upbnd (const KN_context_ptr kc,
const KNINT indexCon,
double cUpBnd);
Get upper bounds on constraints – either in groups, all at once, or individually. Returns 0 if OK, nonzero if error.
-
KN_get_con_eqbnds()
int KNITRO_API KN_get_con_eqbnds (const KN_context_ptr kc,
const KNINT nC,
const KNINT * const indexCons,
double * const cEqBnds);
int KNITRO_API KN_get_con_eqbnds_all (const KN_context_ptr kc,
double * const cEqBnds);
int KNITRO_API KN_get_con_eqbnd (const KN_context_ptr kc,
const KNINT indexCon,
double cEqBnd);
Get equality bounds on constraints – either in groups, all at once, or individually. Returns 0 if OK, nonzero if error.
-
KN_set_con_properties()
int KNITRO_API KN_set_con_properties ( KN_context_ptr kc,
const KNINT nC,
const KNINT * const indexCons,
const int * const cProperties);
int KNITRO_API KN_set_con_properties_all ( KN_context_ptr kc,
const int * const cProperties);
int KNITRO_API KN_set_con_property ( KN_context_ptr kc,
const KNINT indexCon,
const int cProperty);
Specify some properties of the constraint functions. Note: use bit-wise specification of the features:
bit |
value |
meaning |
|---|---|---|
0 |
1 |
KN_CON_CONVEX |
1 |
2 |
KN_CON_CONCAVE |
2 |
4 |
KN_CON_CONTINUOUS |
3 |
8 |
KN_CON_DIFFERENTIABLE |
4 |
16 |
KN_CON_TWICE_DIFFERENTIABLE |
5 |
32 |
KN_CON_NOISY |
6 |
64 |
KN_CON_NONDETERMINISTIC |
default = 28 (bits 2-4 enabled: e.g. continuous, differentiable, twice-differentiable)
-
KN_set_obj_property()
int KNITRO_API KN_set_obj_property ( KN_context_ptr kc,
const int objProperty);
Specify some properties of the objective function. Note: use bit-wise specification of the features:
bit |
value |
meaning |
|---|---|---|
0 |
1 |
KN_OBJ_CONVEX |
1 |
2 |
KN_OBJ_CONCAVE |
2 |
4 |
KN_OBJ_CONTINUOUS |
3 |
8 |
KN_OBJ_DIFFERENTIABLE |
4 |
16 |
KN_OBJ_TWICE_DIFFERENTIABLE |
5 |
32 |
KN_OBJ_NOISY |
6 |
64 |
KN_OBJ_NONDETERMINISTIC |
default = 28 (bits 2-4 enabled: e.g. continuous, differentiable, twice-differentiable)
-
KN_set_obj_goal()
int KNITRO_API KN_set_obj_goal ( KN_context_ptr kc,
const int objGoal);
Set the objective goal (KN_OBJGOAL_MINIMIZE or KN_OBJGOAL_MAXIMIZE).
If not called, minimization assumed by default.
Returns 0 if OK, nonzero if error.
-
KN_set_var_primal_init_values()
int KNITRO_API KN_set_var_primal_init_values ( KN_context_ptr kc,
const KNINT nV,
const KNINT * const indexVars,
const double * const xInitVals);
int KNITRO_API KN_set_var_primal_init_values_all ( KN_context_ptr kc,
const double * const xInitVals);
int KNITRO_API KN_set_var_primal_init_value ( KN_context_ptr kc,
const KNINT indexVar,
const double xInitVal);
Set initial values for primal variables. If not set, variables may be initialized as 0 or initialized by Knitro based on some initialization strategy (perhaps determined by a user option). Returns 0 if OK, nonzero if error.
-
KN_set_var_dual_init_values()
int KNITRO_API KN_set_var_dual_init_values ( KN_context_ptr kc,
const KNINT nV,
const KNINT * const indexVars,
const double * const lambdaInitVals);
int KNITRO_API KN_set_var_dual_init_values_all ( KN_context_ptr kc,
const double * const lambdaInitVals);
int KNITRO_API KN_set_var_dual_init_value ( KN_context_ptr kc,
const KNINT indexVar,
const double lambdaInitVal);
Set initial values for dual variables (i.e. the Lagrange multipliers corresponding to the potentially bounded variables). 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). Returns 0 if OK, nonzero if error.
-
KN_set_con_dual_init_values()
int KNITRO_API KN_set_con_dual_init_values ( KN_context_ptr kc,
const KNINT nC,
const KNINT * const indexCons,
const double * const lambdaInitVals);
int KNITRO_API KN_set_con_dual_init_values_all ( KN_context_ptr kc,
const double * const lambdaInitVals);
int KNITRO_API KN_set_con_dual_init_value ( KN_context_ptr kc,
const KNINT indexCon,
const double lambdaInitVal);
Set initial values for constraint dual variables (i.e. the Lagrange multipliers for the constraints). If not set, constraint dual variables may be initialized as 0 or initialized by Knitro based on some initialization strategy (perhaps determined by a user option). Returns 0 if OK, nonzero if error.
Adding/removing/changing constant structure
-
KN_add_obj_constant()
int KNITRO_API KN_add_obj_constant ( KN_context_ptr kc,
const double constant);
Add a constant to the objective function.
-
KN_del_obj_constant()
int KNITRO_API KN_del_obj_constant ( KN_context_ptr kc);
Delete all constant terms from the objective function.
Only constant terms existing from a previous solve (i.e. added before the most
recent call to KN_solve()) may be removed.
-
KN_chg_obj_constant()
int KNITRO_API KN_chg_obj_constant ( KN_context_ptr kc,
const double constant);
Change constant term in the objective function.
Equivalent to calling KN_del_obj_constant() + KN_add_obj_constant().
-
KN_add_con_constants()
int KNITRO_API KN_add_con_constants ( KN_context_ptr kc,
const KNINT nC,
const KNINT * const indexCons, /* size = nC */
const double * const constants); /* size = nC */
int KNITRO_API KN_add_con_constants_all ( KN_context_ptr kc,
const double * const constants);
int KNITRO_API KN_add_con_constant ( KN_context_ptr kc,
const KNINT indexCon,
const double constant);
Add constants to the body of constraint functions.
Each component i of arrays indexCons and constants adds a constant term
constants[i] to the constraint c[indexCons[i]].
-
KN_del_con_constants()
int KNITRO_API KN_del_con_constants ( KN_context_ptr kc,
const KNINT nC,
const KNINT * const indexCons); /* size = nC */
int KNITRO_API KN_del_con_constants_all ( KN_context_ptr kc);
int KNITRO_API KN_del_con_constant ( KN_context_ptr kc,
const KNINT indexCon);
Delete constant terms from the body of constraint functions.
Each component i of array indexCons deletes all constant terms
from the constraint c[indexCons[i]].
Only constant terms existing from a previous solve (i.e. added before the most
recent call to KN_solve()) may be removed.
-
KN_chg_con_constants()
int KNITRO_API KN_chg_con_constants ( KN_context_ptr kc,
const KNINT nC,
const KNINT * const indexCons, /* size = nC */
const double * const constants); /* size = nC */
int KNITRO_API KN_chg_con_constants_all ( KN_context_ptr kc,
const double * const constants);
int KNITRO_API KN_chg_con_constant ( KN_context_ptr kc,
const KNINT indexCon,
const double constant);
Change constant terms in the body of constraint functions.
Each component i of arrays indexCons and constants changes the constant term
in the constraint c[indexCons[i]] to constants[i].
Equivalent to calling KN_del_con_constants() + KN_add_con_constants().
-
KN_add_rsd_constants()
int KNITRO_API KN_add_rsd_constants ( KN_context_ptr kc,
const KNINT nR,
const KNINT * const indexRsds, /* size = nR */
const double * const constants); /* size = nR */
int KNITRO_API KN_add_rsd_constants_all ( KN_context_ptr kc,
const double * const constants);
int KNITRO_API KN_add_rsd_constant ( KN_context_ptr kc,
const KNINT indexRsd,
const double constant);
Add constants to the body of residual functions.
Each component i of arrays indexRsds and constants adds a constant term
constants[i] to the residual r[indexRsds[i]].
Adding/removing/changing linear structure
-
KN_add_obj_linear_struct()
int KNITRO_API KN_add_obj_linear_struct ( KN_context_ptr kc,
const KNINT nnz,
const KNINT * const indexVars, /* size = nnz */
const double * const coefs); /* size = nnz */
int KNITRO_API KN_add_obj_linear_term ( KN_context_ptr kc,
const KNINT indexVar,
const double coef);
Add linear structure to the objective function.
Each component i of arrays indexVars and coefs adds a linear
term coefs[i]*x[indexVars[i]] to the objective.
Use KN_add_obj_linear_struct() to add several linear objective structures
at once, and KN_add_obj_linear_term() to add a single linear objective
term.
-
KN_del_obj_linear_struct()
int KNITRO_API KN_del_obj_linear_struct ( KN_context_ptr kc,
const KNINT nnz,
const KNINT * const indexVars); /* size = nnz */
int KNITRO_API KN_del_obj_linear_term ( KN_context_ptr kc,
const KNINT indexVar);
Delete linear structure from the objective function.
Each component i of array indexVars removes the linear objective terms
corresponding to variable x[indexVars[i]].
Only linear terms existing from a previous solve (i.e. added before the most
recent call to KN_solve()) may be removed.
Use KN_del_obj_linear_struct() to delete several linear objective structures
at once, and KN_del_obj_linear_term() to delete a single linear objective
term.
-
KN_chg_obj_linear_struct()
int KNITRO_API KN_chg_obj_linear_struct ( KN_context_ptr kc,
const KNINT nnz,
const KNINT * const indexVars, /* size = nnz */
const double * const coefs); /* size = nnz */
int KNITRO_API KN_chg_obj_linear_term ( KN_context_ptr kc,
const KNINT indexVar,
const double coef);
Change linear structure in the objective function.
Each component i of arrays indexVars and coefs changes the coefficient
value of the linear term coefs[i]*x[indexVars[i]] in the objective.
Equivalent to calling KN_del_obj_linear_struct() + KN_add_obj_linear_struct().
Use KN_chg_obj_linear_struct() to change several linear objective structures
at once, and KN_chg_obj_linear_term() to change a single linear objective
term.
-
KN_add_con_linear_struct()
int KNITRO_API KN_add_con_linear_struct ( KN_context_ptr kc,
const KNLONG nnz,
const KNINT * const indexCons, /* size = nnz */
const KNINT * const indexVars, /* size = nnz */
const double * const coefs); /* size = nnz */
int KNITRO_API KN_add_con_linear_struct_one ( KN_context_ptr kc,
const KNLONG nnz,
const KNINT indexCon,
const KNINT * const indexVars, /* size = nnz */
const double * const coefs); /* size = nnz */
int KNITRO_API KN_add_con_linear_term ( KN_context_ptr kc,
const KNINT indexCon,
const KNINT indexVar,
const double coef);
Add linear structure to the constraint functions.
Each component i of arrays indexCons, indexVars and coefs adds a linear
term coefs[i]*x[indexVars[i]] to constraint c[indexCons[i]].
Use KN_add_con_linear_struct() to add linear structure for a group of
constraints at once, KN_add_con_linear_struct_one() to add linear
structure for just one constraint, and KN_add_con_linear_term() to
add a single linear constraint term.
-
KN_del_con_linear_struct()
int KNITRO_API KN_del_con_linear_struct ( KN_context_ptr kc,
const KNLONG nnz,
const KNINT * const indexCons, /* size = nnz */
const KNINT * const indexVars); /* size = nnz */
int KNITRO_API KN_del_con_linear_struct_one ( KN_context_ptr kc,
const KNLONG nnz,
const KNINT indexCon,
const KNINT * const indexVars); /* size = nnz */
int KNITRO_API KN_del_con_linear_term ( KN_context_ptr kc,
const KNINT indexCon,
const KNINT indexVar);
Delete linear structure from the constraint functions.
Each component i of arrays indexCons and indexVars removes the linear constraint
terms corresponding to variable x[indexVars[i]] in constraint c[indexCons[i]].
Only linear terms existing from a previous solve (i.e. added before the most
recent call to KN_solve()) may be removed.
Use KN_del_con_linear_struct() to delete linear structure from a group of
constraints at once, KN_del_con_linear_struct_one() to delete linear
structure from just one constraint, and KN_del_con_linear_term() to
delete a single linear constraint term.
-
KN_chg_con_linear_struct()
int KNITRO_API KN_chg_con_linear_struct ( KN_context_ptr kc,
const KNLONG nnz,
const KNINT * const indexCons, /* size = nnz */
const KNINT * const indexVars, /* size = nnz */
const double * const coefs); /* size = nnz */
int KNITRO_API KN_chg_con_linear_struct_one ( KN_context_ptr kc,
const KNLONG nnz,
const KNINT indexCon,
const KNINT * const indexVars, /* size = nnz */
const double * const coefs); /* size = nnz */
int KNITRO_API KN_chg_con_linear_term ( KN_context_ptr kc,
const KNINT indexCon,
const KNINT indexVar,
const double coef);
Change linear structure in the constraint functions.
Each component i of arrays indexCons, indexVars and coefs changes the coefficient
value of the linear term coefs[i]*x[indexVars[i]] in constraint c[indexCons[i]].
Equivalent to calling KN_del_con_linear_struct() + KN_add_con_linear_struct().
Use KN_chg_con_linear_struct() to change linear structure for a group of
constraints at once, KN_chg_con_linear_struct_one() to change linear
structure for just one constraint, and KN_chg_con_linear_term() to
change a single linear constraint term.
-
KN_add_rsd_linear_struct()
int KNITRO_API KN_add_rsd_linear_struct ( KN_context_ptr kc,
const KNLONG nnz,
const KNINT * const indexRsds, /* size = nnz */
const KNINT * const indexVars, /* size = nnz */
const double * const coefs); /* size = nnz */
int KNITRO_API KN_add_rsd_linear_struct_one ( KN_context_ptr kc,
const KNLONG nnz,
const KNINT indexRsd,
const KNINT * const indexVar, /* size = nnz */
const double * const coefs); /* size = nnz */
int KNITRO_API KN_add_rsd_linear_term ( KN_context_ptr kc,
const KNINT indexRsd,
const KNINT indexVar,
const double coef);
Add linear structure to the residual functions.
Each component i of arrays indexRsds, indexVars and coefs adds a linear
term coefs[i]*x[indexVars[i]] to residual r[indexRsds[i]].
Use KN_add_rsd_linear_struct() to add linear structure for a group of
residuals at once, KN_add_rsd_linear_struct_one() to add linear
structure for just one residual, and KN_add_rsd_linear_term() to
add a single linear residual term.
Adding quadratic structure
-
KN_add_obj_quadratic_struct()
int KNITRO_API KN_add_obj_quadratic_struct ( KN_context_ptr kc,
const KNLONG nnz,
const KNINT * const indexVars1, /* size = nnz */
const KNINT * const indexVars2, /* size = nnz */
const double * const coefs); /* size = nnz */
int KNITRO_API KN_add_obj_quadratic_term ( KN_context_ptr kc,
const KNINT indexVar1,
const KNINT indexVar2,
const double coef);
Add quadratic structure to the objective function.
Each component i of arrays indexVars1, indexVars2 and coefs adds a quadratic
term coefs[i]*x[indexVars1[i]]*x[indexVars2[i]] to the objective.
Use KN_add_obj_quadratic_struct() to add several quadratic objective
structures at once, and KN_add_obj_quadratic_term() to add a single
quadratic objective term.
Note: if indexVars2[i] is < 0 then it adds a linear
term coefs[i]*x[indexVars1[i]] instead.
-
KN_add_con_quadratic_struct()
int KNITRO_API KN_add_con_quadratic_struct ( KN_context_ptr kc,
const KNLONG nnz,
const KNINT * const indexCons, /* size = nnz */
const KNINT * const indexVars1, /* size = nnz */
const KNINT * const indexVars2, /* size = nnz */
const double * const coefs); /* size = nnz */
int KNITRO_API KN_add_con_quadratic_struct_one ( KN_context_ptr kc,
const KNLONG nnz,
const KNINT indexCon,
const KNINT * const indexVars1, /* size = nnz */
const KNINT * const indexVars2, /* size = nnz */
const double * const coefs); /* size = nnz */
int KNITRO_API KN_add_con_quadratic_term ( KN_context_ptr kc,
const KNINT indexCon,
const KNINT indexVar1,
const KNINT indexVar2,
const double coef);
Add quadratic structure to the constraint functions.
Each component i of arrays indexCons, indexVars1, indexVars2 and coefs adds a
quadratic term coefs[i]*x[indexVars1[i]]*x[indexVars2[i]] to the constraint c[indexCons[i]].
Use KN_add_con_quadratic_struct() to add quadratic structure for a group of
constraints at once, KN_add_con_quadratic_struct_one() to add quadratic
structure for just one constraint, and KN_add_con_quadratic_term() to
add a single quadratic constraint term.
- Note: if
indexVars2[i]is < 0 then it adds a linear term coefs[i]*x[indexVars1[i]]instead.
Adding conic structure
-
KN_add_con_L2norm()
int KNITRO_API KN_add_con_L2norm ( KN_context_ptr kc,
const KNINT indexCon,
const KNINT nCoords,
const KNLONG nnz,
const KNINT * const indexCoords, /* size = nnz */
const KNINT * const indexVars, /* size = nnz */
const double * const coefs, /* size = nnz */
const double * const constants); /* size = nCoords or NULL */
Add L2 norm structure of the form ||Ax + b||_2 to a constraint.
Parameter |
Description |
|---|---|
indexCon: |
The constraint index that the L2 norm term will be added to. |
nCoords: |
The number of rows in “A” (or dimension of “b”) |
nnz: |
The number of sparse non-zero elements in “A” |
indexCoords: |
The coordinate (row) index for each non-zero element in “A”. |
indexVars: |
The variable (column) index for each non-zero element in “A” |
coefs: |
The coefficient value for each non-zero element in “A” |
constants: |
The array “b” - may be set to NULL to ignore “b” |
Note: L2 norm structure can currently only be added to constraints that
otherwise only have linear (or constant) structure. In this way
they can be used to define conic constraints of the form
||Ax + b|| <= c'x + d. The c coefficients should be added through
KN_add_con_linear_struct() and d can be set as a constraint bound
or through KN_add_con_constants().
Note: Models with L2 norm structure are currently only handled by the
Interior/Direct (KN_ALG_BAR_DIRECT) algorithm in Knitro. Any model
with structure defined with KN_add_L2norm() will automatically be
forced to use this algorithm.
Adding complementarity constraints
-
KN_set_compcons()
int KNITRO_API KN_set_compcons ( KN_context_ptr kc,
const KNINT nCC,
const int * const ccTypes,
const KNINT * const indexComps1,
const KNINT * const indexComps2);
This function adds complementarity constraints to the problem.
The two lists are of equal length, and contain matching pairs of
variable indices. Each pair defines a complementarity constraint
between the two variables. The function can only be called once.
The array ccTypes specifies 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.
Returns 0 if OK, or a negative value on error.
Loading MPS file
-
KN_load_mps_file()
int KNITRO_API KN_load_mps_file ( KN_context_ptr kc,
const char * const filename);
This function loads the problem specified in the MPS file filename.
The number of variables and constraints is specified in the MPS file,
as well as the nature of the objective and the different constraints
(should they be linear or quadratic).
Return 0 if OK, or a negative value on error.
Defining evaluation callbacks
Applications may define functions for evaluating problem elements
at a trial point. The functions must match the prototype defined
below, and passed to Knitro with the appropriate KN_set_cb_* call.
Knitro may request different types of evaluation information,
as specified in evalRequest.type:
KN_RC_EVALFC - return objective and constraint function values
KN_RC_EVALGA - return first derivative values in "objGrad" and "jac"
KN_RC_EVALFCGA - return objective and constraint function values
AND first derivative "objGrad" and "jac"
KN_RC_EVALH - return second derivative values in "hessian"
KN_RC_EVALH_NO_F (this version excludes the objective term)
KN_RC_EVALHV - return a Hessian-vector product in "hessVector"
KN_RC_EVALHV_NO_F (this version excludes the objective term)
KN_RC_EVALR - return residual function values for least squares
KN_RC_EVALRJ - return residual Jacobian values for least squares
The argument lambda is not defined when requesting EVALFC, EVALGA,
EVALFCGA, EVALR or EVALRJ.
Usually, applications for standard optimization models define three
callback functions: one for EVALFC, one for EVALGA, and one for EVALH / EVALHV.
The last function is only used when providing the Hessian (as opposed to
using one of the Knitro options to approximate it) and evaluates H or HV
depending on the value of evalRequest.type. For least squares models,
the application defines the two callback functions for EVALR and EVALRJ
(instead of EVALFC and EVALGA). Least squares applications do not provide
a callback for the Hessian as it is always approximated.
It is possible in most cases to combine EVALFC and EVALGA into a single
callback function. This may be advantageous if the application evaluates
functions and their derivatives at the same time. In order to do this, set
the user option eval_fcga=KN_EVAL_FCGA_YES, and define one callback set in
KN_add_eval_callback() that evaluates BOTH the functions and gradients
(i.e. have it populate obj, c, objGrad, and jac in the evalResult
structure), and do not set a callback in KN_set_cb_grad(). Whenever Knitro
needs a function + gradient evaluation, it will callback to the function
passed to KN_add_eval_callback() with an EVALFCGA request.
Combining function and gradient evaluations in one callback is not currently allowed if hessopt=KN_HESSOPT_PRODUCT_FINDIFF. It is not possible to combine EVALH / EVALHV because lambda may change after the EVALFC call. Generally it is most efficient to separate function and gradient callbacks, since a gradient evaluation is not needed at every x value where functions are evaluated.
The userParams argument is an arbitrary pointer passed from the Knitro
KN_solve() call to the callback. It should be used to pass parameters
defined and controlled by the application, or left NULL if not used.
Knitro does not modify or dereference the userParams pointer.
For simplicity, the following user-defined evaluation callback functions
all use the same KN_eval_callback() function prototype defined below:
funcCallback
gradCallback
hessCallback
rsdCallback (for least squares)
rsdJacCallback (for least squares)
Callbacks should return 0 if successful, a negative error code if not. Possible unsuccessful (negative) error codes for the func/grad/hess/rsd/rsdJac callback functions include:
KN_RC_CALLBACK_ERR (for generic callback errors)
KN_RC_EVAL_ERR (for evaluation errors, e.g log(-1))
In addition, for the “func” (as well as the “newpoint”, “ms_process” and “mip_node” user callbacks), the user may set the following return code to force Knitro to terminate based on some user-defined condition.:
KN_RC_USER_TERMINATION (to use a callback routine
for user specified termination)
typedef struct KN_eval_request {
int type;
int threadID;
const double * x;
const double * lambda;
const double * sigma;
const double * vec;
} KN_eval_request, *KN_eval_request_ptr;
Structure used to pass back evaluation information for evaluation callbacks.
Parameter |
Description |
|---|---|
type: |
indicates the type of evaluation requested |
threadID: |
the thread ID associated with this evaluation request; useful for multi-threaded, concurrent evaluations |
x: |
values of unknown (primal) variables used for all evaluations |
lambda: |
values of unknown dual variables/Lagrange multipliers used for the evaluation of the Hessian |
sigma: |
scalar multiplier for the objective component of the Hessian |
vec: |
vector array value for Hessian-vector products (only used when user option hessopt=KN_HESSOPT_PRODUCT) |
typedef struct KN_eval_result {
double * obj;
double * c;
double * objGrad;
double * jac;
double * hess;
double * hessVec;
double * rsd;
double * rsdJac;
} KN_eval_result, *KN_eval_result_ptr;
Structure used to return results information for evaluation callbacks. The arrays (and their indices and sizes) returned in this structure are local to the specific callback structure used for the evaluation.
Parameter |
Description |
|---|---|
obj: |
objective function evaluated at “x” for EVALFC or EVALFCGA request (funcCallback) |
c: |
(length nC) constraint values evaluated at “x” for EVALFC or EVALFCGA request (funcCallback) |
objGrad: |
(length nV) objective gradient evaluated at “x” for EVALGA request (gradCallback) or EVALFCGA request (funcCallback) |
jac: |
(length nnzJ) constraint Jacobian evaluated at “x” for EVALGA request (gradCallback) or EVALFCGA request (funcCallback) |
hess: |
(length nnzH) Hessian evaluated at “x”, “lambda”, “sigma” for EVALH or EVALH_NO_F request (hessCallback) |
hessVec: |
(length n=number variables in the model) Hessian-vector product evaluated at “x”, “lambda”, “sigma” for EVALHV or EVALHV_NO_F request (hessCallback) |
rsd: |
(length nR) residual values evaluated at “x” for EVALR request (rsdCallback) |
rsdJac: |
(length nnzJ) residual Jacobian evaluated at “x” for EVALRJ request (rsdJacCallback) |
typedef struct CB_context CB_context, *CB_context_ptr;
The callback structure/object. Note the CB_context_ptr is allocated and
managed by Knitro: the user does not have to free it.
typedef int KN_eval_callback (KN_context_ptr kc,
CB_context_ptr cb,
KN_eval_request_ptr const evalRequest,
KN_eval_result_ptr const evalResult,
void * const userParams);
Function prototype for evaluation callbacks.
-
KN_add_eval_callback()
int KNITRO_API KN_add_eval_callback ( KN_context_ptr kc,
const KNBOOL evalObj,
const KNINT nC,
const KNINT * const indexCons, /* nullable if nC=0 */
KN_eval_callback * const funcCallback,
CB_context_ptr * const cb);
This is the routine for adding a callback for (nonlinear) evaluations
of objective and constraint functions. This routine can be called
multiple times to add more than one callback structure (e.g. to create
different callback structures to handle different blocks of constraints).
This routine specifies the minimal information needed for a callback, and
creates the callback structure cb, which can then be passed to other
callback functions to set additional information for that callback.
Parameter |
Description |
|---|---|
evalObj |
boolean indicating whether or not any part of the objective function is evaluated in the callback |
nC |
number of constraints evaluated in the callback |
indexCons |
(length nC) index of constraints evaluated in the callback (set to NULL if nC=0) |
funcCallback |
a pointer to a function that evaluates the objective parts (if evalObj=KNTRUE) and any constraint parts (specified by nC and indexCons) involved in this callback; when eval_fcga=KN_EVAL_FCGA_YES, this callback should also evaluate the relevant first derivatives/gradients |
cb |
(output) the callback structure that gets created by calling this function; all the memory for this structure is handled by Knitro |
After a callback is created by KN_add_eval_callback(), the user can then specify
gradient information and structure through KN_set_cb_grad() and Hessian
information and structure through KN_set_cb_hess(). If not set, Knitro will
approximate these. However, it is highly recommended to provide a callback routine
to specify the gradients if at all possible as this will greatly improve the
performance of Knitro. Even if a gradient callback is not provided, it is still
helpful to provide the sparse Jacobian structure through KN_set_cb_grad() to
improve the efficiency of the finite-difference gradient approximations.
Other optional information can also be set via KN_set_cb_*() functions as
detailed below.
Returns 0 if OK, nonzero if error.
-
KN_add_eval_callback_all()
int KNITRO_API KN_add_eval_callback_all ( KN_context_ptr kc,
KN_eval_callback * const funcCallback,
CB_context_ptr * const cb)
Simplified version of KN_add_eval_callback() to create a callback that applies to the
objective function and all constraints.
-
KN_add_eval_callback_one()
int KNITRO_API KN_add_eval_callback_one ( KN_context_ptr kc,
const KNINT index, /* -1 for obj */
KN_eval_callback * const funcCallback,
CB_context_ptr * const cb)
Version of KN_add_eval_callback() to create a callback that only applies to a
single objective function or constraint. Set index to the corresponding
constraint index or use -1 for the objective.
-
KN_add_lsq_eval_callback()
int KNITRO_API KN_add_lsq_eval_callback ( KN_context_ptr kc,
const KNINT nR,
const KNINT * const indexRsds,
KN_eval_callback * const rsdCallback,
CB_context_ptr * const cb);
Add an evaluation callback for a least-squares models. Similar to
KN_add_eval_callback()
above, but for least-squares models.
Parameter |
Description |
|---|---|
nR |
number of residuals evaluated in the callback |
indexRsds |
(length nR) index of residuals evaluated in the callback |
rsdCallback |
a pointer to a function that evaluates any residual parts (specified by nR and indexRsds) involved in this callback |
cb |
(output) the callback structure that gets created by calling this function; all the memory for this structure is handled by Knitro |
After a callback is created by KN_add_lsq_eval_callback(), the user can then
specify residual Jacobian information and structure through KN_set_cb_rsd_jac().
If not set, Knitro will approximate the residual Jacobian. However, it is highly
recommended to provide a callback routine to specify the residual Jacobian if at all
possible as this will greatly improve the performance of Knitro. Even if a callback
for the residual Jacobian is not provided, it is still helpful to provide the sparse
Jacobian structure for the residuals through KN_set_cb_rsd_jac() to improve the
efficiency of the finite-difference Jacobian approximation. Other optional
information can also be set via KN_set_cb_*() functions as detailed below.
Returns 0 if OK, nonzero if error.
-
KN_add_lsq_eval_callback_all()
int KNITRO_API KN_add_lsq_eval_callback_all ( KN_context_ptr kc,
KN_eval_callback * const rsdCallback,
CB_context_ptr * const cb)
Simplified version of KN_add_lsq_eval_callback() to create a callback that applies to
all residual functions.
-
KN_add_lsq_eval_callback_one()
int KNITRO_API KN_add_lsq_eval_callback_one ( KN_context_ptr kc,
const KNINT indexRsd,
KN_eval_callback * const rsdCallback,
CB_context_ptr * const cb);
Version of KN_add_lsq_eval_callback() to create a callback that only applies to
a single residual function. Set indexRsd to the corresponding residual index.
-
KN_set_cb_grad()
int KNITRO_API KN_set_cb_grad ( KN_context_ptr kc,
CB_context_ptr cb,
const KNINT nV, /* or KN_DENSE */
const KNINT * const objGradIndexVars,
const KNLONG nnzJ, /* or KN_DENSE_* */
const KNINT * const jacIndexCons,
const KNINT * const jacIndexVars,
KN_eval_callback * const gradCallback); /* nullable */
This API function is used to set the objective gradient and constraint Jacobian structure and also (optionally) a callback function to evaluate the objective gradient and constraint Jacobian provided through this callback.
Parameter |
Description |
|---|---|
cb |
a callback structure created from a previous call to KN_add_eval_callback() |
nV |
number of nonzero components in the objective gradient for this callback if providing in sparse form; set to KN_DENSE to provide the full objective gradient |
objGradIndexVars |
(length nV) the nonzero indices of the objective gradient; set to NULL if nV=KN_DENSE or nV=0 (i.e. evalObj=KNFALSE) |
nnzJ |
number of nonzeroes in the sparse constraint Jacobian computed through this callback; 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) |
jacIndexCons |
(length nnzJ) constraint index (row) of each nonzero; set to NULL if nnzJ=KN_DENSE_ROWMAJOR/KN_DENSE_COLMAJOR or nnzJ=0 |
jacIndexVars |
(length nnzJ) variable index (column) of each nonzero; set to NULL if nnzJ=KN_DENSE_ROWMAJOR/KN_DENSE_COLMAJOR or nnzJ=0 |
gradCallback |
a pointer to a function that evaluates the objective gradient parts and any constraint Jacobian parts involved in this callback; set to NULL if using finite-difference gradient approximations (specified via KN_set_cb_gradopt()), or if gradients and functions are provided together in the funcCallback (i.e. eval_fcga=KN_EVAL_FCGA_YES). |
The user should generally always try to define the sparsity structure
for the Jacobian (nnzJ, 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. However, if the user is unable to
provide this sparsity structure, then one can set nnzJ to
KN_DENSE_ROWMAJOR or
KN_DENSE_COLMAJOR and set jacIndexCons and jacIndexVars to NULL.
-
KN_set_cb_hess()
int KNITRO_API KN_set_cb_hess ( KN_context_ptr kc,
CB_context_ptr cb,
const KNLONG nnzH, /* or KN_DENSE_* */
const KNINT * const hessIndexVars1,
const KNINT * const hessIndexVars2,
KN_eval_callback * const hessCallback);
This API function is used to set the structure and a callback function to evaluate the components of the Hessian of the Lagrangian provided through this callback. KN_set_cb_hess() should only be used when defining a user-supplied Hessian callback function (via the “hessopt=KN_HESSOPT_EXACT” user option), or a callback function to compute the Hessian-vector product array (via the “hessopt=KN_HESSOPT_PRODUCT” user option). When providing a callback function for Hessian-vector products, the Hessian is not stored or used internally, so in this case set “nnzH”=0, “hessIndexVars1”=NULL, and “hessIndexVars2”=NULL. When Knitro is approximating the Hessian, it cannot make use of the Hessian sparsity structure.
Parameter |
Description |
|---|---|
cb |
a callback structure created from a previous call to KN_add_eval_callback() |
nnzH |
number of nonzeroes in the sparse Hessian of the Lagrangian computed through this callback; 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. |
hessIndexVars1 |
(length nnzH) first variable index of each nonzero; set to NULL if nnzH=KN_DENSE_ROWMAJOR/KN_DENSE_COLMAJOR |
hessIndexVars2 |
(length nnzH) second variable index of each nonzero; set to NULL if nnzH=KN_DENSE_ROWMAJOR/KN_DENSE_COLMAJOR |
hessCallback |
a pointer to a function that evaluates the components of the Hessian of the Lagrangian (or Hessian-vector product array) provided in this callback |
-
KN_set_cb_rsd_jac()
int KNITRO_API KN_set_cb_rsd_jac ( KN_context_ptr kc,
CB_context_ptr cb,
const KNLONG nnzJ, /* or KN_DENSE_* */
const KNINT * const jacIndexRsds,
const KNINT * const jacIndexVars,
KN_eval_callback * const rsdJacCallback); /* nullable */
This API function is used to set the residual Jacobian structure and also (optionally) a callback function to evaluate the residual Jacobian provided through this callback.
Parameter |
Description |
|---|---|
cb |
a callback structure created from a previous call to KN_add_lsq_eval_callback() |
nnzJ |
number of nonzeroes in the sparse residual Jacobian computed through this callback; set to KN_DENSE_ROWMAJOR to provide the full Jacobian in row major order (i.e. ordered by rows/residuals), or KN_DENSE_COLMAJOR to provide the full Jacobian in column major order (i.e. ordered by columns/ variables) |
jacIndexRsds |
(length nnzJ) residual index (row) of each nonzero; set to NULL if nnzJ=KN_DENSE_ROWMAJOR/KN_DENSE_COLMAJOR or nnzJ=0 |
jacIndexVars |
(length nnzJ) variable index (column) of each nonzero; set to NULL if nnzJ=KN_DENSE_ROWMAJOR/KN_DENSE_COLMAJOR or nnzJ=0 |
rsdJacCallback |
a pointer to a function that evaluates any residual Jacobian parts involved in this callback; set to NULL if using a finite- difference Jacobian approximation (specified via KN_set_cb_gradopt()) |
The user should generally always try to define the sparsity structure
for the Jacobian (nnzJ, jacIndexRsds, jacIndexVars). Even when
using a finite-difference approximation to compute the Jacobian, knowing the
sparse structure of the Jacobian can allow Knitro to compute this
finite-difference approximation faster. However, if the user is unable to
provide this sparsity structure, then one can set nnzJ to
KN_DENSE_ROWMAJOR or
KN_DENSE_COLMAJOR and set jacIndexRsds and jacIndexVars to NULL.
-
KN_set_cb_user_params()
int KNITRO_API KN_set_cb_user_params (KN_context_ptr kc,
CB_context_ptr cb,
void * const userParams);
Define a userParams structure for an evaluation callback.
-
KN_set_cb_gradopt()
int KNITRO_API KN_set_cb_gradopt ( KN_context_ptr kc,
CB_context_ptr cb,
const int gradopt);
Specify which gradient option gradopt will be used to evaluate
the first derivatives of the callback functions. If gradopt=:c:macro:KN_GRADOPT_EXACT
then a gradient evaluation callback must be set by KN_set_cb_grad()
(or KN_set_cb_rsd_jac() for least squares).
-
KN_set_cb_relstepsizes()
int KNITRO_API KN_set_cb_relstepsizes ( KN_context_ptr kc,
CB_context_ptr cb,
const KNINT nV,
const KNINT * const indexVars,
const double * const xRelStepSizes);
int KNITRO_API KN_set_cb_relstepsizes_all ( KN_context_ptr kc,
CB_context_ptr cb,
const double * const xRelStepSizes);
int KNITRO_API KN_set_cb_relstepsize ( KN_context_ptr kc,
CB_context_ptr cb,
const KNINT indexVar,
const double xRelStepSize);
Set an array of relative stepsizes to use for the finite-difference gradient/Jacobian computations when using finite-difference first derivatives. Finite-difference step sizes “delta” in Knitro are computed as:
delta[i] = relStepSizes[i]*max(abs(x[i]),1)
The default relative step sizes for each component of “x” are sqrt(eps) for forward finite differences, and eps^(1/3) for central finite differences. Use this function to overwrite the default values. Any zero values will use Knitro default values, while non-zero values will overwrite default values.
Note that this API function has no affect on the finite-difference derivatives computed for the derivative checker (default values are always used here). It is only used for the finite-difference derivatives computed during the optimization. Knitro makes a local copy of all inputs, so the application may free memory after the call. Returns 0 if OK, nonzero if error.
-
KN_get_cb_number_cons()
int KNITRO_API KN_get_cb_number_cons (const KN_context_ptr kc,
const CB_context_ptr cb,
KNINT * const nC);
Retrieve the number of constraints nC being evaluated through callback cb.
Returns 0 if OK, nonzero if error.
-
KN_get_cb_number_rsds()
int KNITRO_API KN_get_cb_number_rsds (const KN_context_ptr kc,
const CB_context_ptr cb,
KNINT * const nR);
Retrieve the number of residuals nR being evaluated through callback cb.
Returns 0 if OK, nonzero if error.
-
KN_get_cb_objgrad_nnz()
int KNITRO_API KN_get_cb_objgrad_nnz (const KN_context_ptr kc,
const CB_context_ptr cb,
KNINT * const nnz);
Retrieve the number of non-zero objective gradient elements nnz
evaluated through callback cb.
Returns 0 if OK, nonzero if error.
-
KN_get_cb_jacobian_nnz()
int KNITRO_API KN_get_cb_jacobian_nnz (const KN_context_ptr kc,
const CB_context_ptr cb,
KNLONG * const nnz);
Retrieve the number of non-zero Jacobian elements nnz
evaluated through callback cb.
Returns 0 if OK, nonzero if error.
-
KN_get_cb_rsd_jacobian_nnz()
int KNITRO_API KN_get_cb_rsd_jacobian_nnz (const KN_context_ptr kc,
const CB_context_ptr cb,
KNLONG * const nnz);
Retrieve the number of non-zero residual Jacobian elements nnz
evaluated through callback cb.
Returns 0 if OK, nonzero if error.
-
KN_get_cb_hessian_nnz()
int KNITRO_API KN_get_cb_hessian_nnz (const KN_context_ptr kc,
const CB_context_ptr cb,
KNLONG * const nnz);
Retrieve the number of non-zero Hessian elements nnz
evaluated through callback cb.
Returns 0 if OK, nonzero if error.
Other user callbacks
Other user callbacks that aren’t involved in evaluations use the
KN_user_callback() or other function protoypes. These include:
KN_set_newpt_callback
KN_set_mip_node_callback
KN_set_ms_process_callback
KN_set_ms_initpt_callback
KN_set_puts_callback
KN_set_linsolver_callback
Callbacks should return 0 if successful, a negative error code if not. The “linsolver” callback may use the return code:
KN_RC_LINEAR_SOLVER_ERR
if it encounters a linear system it is unable to solve or prefers Knitro to handle. In this case, Knitro will revert to its own internal linear solver for that linear system.
In addition, for the “newpoint”, “ms_process” and “mip_node” callbacks, the user may set the following return code to force Knitro to terminate based on some user-defined condition.:
KN_RC_USER_TERMINATION (to use a callback routine
for user specified termination)
typedef int KN_user_callback ( KN_context_ptr kc,
const double * const x,
const double * const lambda,
void * const userParams);
Type declaration for several non-evaluation user callbacks defined below.
-
KN_set_newpt_callback()
int KNITRO_API KN_set_newpt_callback (KN_context_ptr kc,
KN_user_callback * const fnPtr,
void * const userParams);
Set the callback function that is invoked after Knitro computes a
new estimate of the solution point (i.e., after every iteration).
The function should not modify any Knitro arguments.
Argument kc passed to the callback from inside Knitro is the
context pointer for the current problem being solved inside Knitro
(either the main single-solve problem, or a subproblem when using
multi-start, Tuner, etc.).
Arguments x and lambda contain the latest solution estimates.
Other values (such as objective, constraint, jacobian, etc.) can be
queried using the corresonding KN_get_XXX_values() methods.
Note: Currently only active for continuous models.
Return 0 if successful, a negative error code if not.
-
KN_set_mip_node_callback()
int KNITRO_API KN_set_mip_node_callback (KN_context_ptr kc,
KN_user_callback * const fnPtr,
void * const userParams);
This callback function is for mixed integer (MIP) problems only.
Set the callback function that is invoked after Knitro finishes
processing a node on the branch-and-bound tree (i.e., after a relaxed
subproblem solve in the branch-and-bound procedure).
Argument kc passed to the callback from inside Knitro is the
context pointer for the last node subproblem solved inside Knitro.
The function should not modify any Knitro arguments.
Arguments x and lambda contain the solution from the node solve.
Return 0 if successful, a negative error code if not.
-
KN_set_ms_process_callback()
int KNITRO_API KN_set_ms_process_callback (KN_context_ptr kc,
KN_user_callback * const fnPtr,
void * const userParams);
This callback function is for multi-start (MS) problems only.
Set the callback function that is invoked after Knitro finishes
processing a multi-start solve. Argument kc passed to the callback
from inside Knitro is the context pointer for the last multi-start
subproblem solved inside Knitro. The function should not modify any
Knitro arguments. Arguments x and lambda contain the solution from
the last solve.
Return 0 if successful, a negative error code if not.
-
KN_set_ms_initpt_callback()
typedef int KN_ms_initpt_callback ( KN_context_ptr kc,
const KNINT nSolveNumber,
double * const x,
double * const lambda,
void * const userParams);
int KNITRO_API KN_set_ms_initpt_callback (KN_context_ptr kc,
KN_ms_initpt_callback * const fnPtr,
void * const userParams);
This callback allows applications to
specify an initial point before each local solve in the multi-start
procedure. On input, arguments x and lambda are the randomly
generated initial points determined by Knitro, which can be overwritten
by the user. The argument nSolveNumber is the number of the
multi-start solve. Return 0 if successful, a negative error code if not.
Use KN_ms_initpt_callback() type declaration for this callback.
-
KN_set_puts_callback()
typedef int KN_puts (const char * const str,
void * const userParams);
/** Return 0 if successful, a negative error code if not.
*/
int KNITRO_API KN_set_puts_callback (KN_context_ptr kc,
KN_puts * const fnPtr,
void * const userParams);
This callback allows applications to handle/redirect
output. Applications can set a “put string” callback function to handle
output generated by the Knitro solver. By default Knitro prints to
stdout or a file named knitro.log, as determined by
KN_PARAM_OUTMODE.
The KN_puts() function takes a userParams argument which is a pointer
passed directly from KN_solve(). The function should return the number of
characters that were printed.
Use KN_puts() type declaration for this callback.
-
KN_set_linsolver_callback()
Applications may define a function for solving sparse linear systems of equations M*x=b, which need to be solved internally by Knitro. The solution of these linear systems may be a significant cost for some algorithms (e.g. interior-point algorithms), especially for large problems. The symmetric n-by-n coefficient matrix “M” for the linear system uses compressed sparse column (CSC) format and only the lower triangle plus diagonal is stored. Row indices are not necessarily ordered within each column. The matrix M may often have the following generic 2-by-2 block structure:
M = | H A' |
| A D |
where H is a n11-by-n11 symmetric matrix, A is a (n-n11)-by-n11 matrix, A’ is the transpose of A, and D is a diagonal matrix of dimension (n-n11). The Knitro callback for linear system solves provides the sparse structure for the full matrix “M”, and also provides the (1,1) block dimension n11, which can be used to access sub-blocks.
/** Possible linsolver phases.
*/
#define KN_LINSOLVER_PHASE_INIT 0
#define KN_LINSOLVER_PHASE_ANALYZE 1
#define KN_LINSOLVER_PHASE_FACTOR 2
#define KN_LINSOLVER_PHASE_SOLVE 3
#define KN_LINSOLVER_PHASE_FREE 4
typedef struct KN_linsolver_request {
int phase;
int linsysID;
int threadID;
KNINT n; /* dimension of coef matrix */
KNINT n11; /* dimension of (1,1) block */
const double * rhs; /* right-hand side vector (size = n) */
const double * values; /* coefficient matrix values (size = nnz) */
const KNINT * indexRows; /* coefficient matrix row indices (size = nnz) */
const KNLONG * ptrCols; /* coefficient matrix column pointers (size = n+1) */
} KN_linsolver_request, *KN_linsolver_request_ptr;
Structure used to pass back information for linear system solver callbacks.
Parameter |
Description |
|---|---|
phase: |
indicates the linear system solve phase (e.g., init, analyze, factor, solve, free) |
linsysID: |
the linear system ID associated with the request in the current local optimization |
threadID: |
the thread ID associated with this request; threadID (along with linsysID) can be used to identify a unique linear system, which can be useful for multi-threaded, concurrent solves |
n: |
dimension of M |
n11: |
dimension of (1,1) block H inside M; useful for extracting submatrices H, A, and D for 2-by-2 block structure (n11=n if no block structure) |
rhs: |
right-hand-side values needed for “solve” phase only |
values: |
coefficient matrix values |
indexRows: |
coefficient matrix row indices |
ptrCols: |
coefficient matrix column pointers; number of nonzero elements (nnz) = ptrCols[n] |
typedef struct KN_linsolver_result {
double * solution;
KNINT negeig;
KNINT poseig;
KNINT rank;
} KN_linsolver_result, *KN_linsolver_result_ptr;
Structure used to return results for linear system solver callbacks.
Parameter |
Description |
|---|---|
solution: |
solution values (required for “solve” phase) |
negeig: |
number of negative eigenvalues (required for “factor” phase) |
poseig: |
number of positive eigenvalues (optional for “factor” phase) |
rank: |
coefficient matrix rank (optional for “factor” phase) |
/** Function prototype for linear system solve callbacks.
* Information/values needed for the linear system solve are provided in
* "linsolverRequest". Solution values should be returned in "linsolverResult".
*
* Return 0 if successful, a negative error code if not.
* KN_RC_CALLBACK_ERR (use for fatal callback errors)
* KN_RC_LINEAR_SOLVER_ERR (non-fatal for analyze phase;
* causes Knitro to revert to one
* of its own internal linear solvers)
*/
typedef int KN_linsolver_callback (KN_context_ptr kc,
KN_linsolver_request_ptr const linsolverRequest,
KN_linsolver_result_ptr const linsolverResult,
void * const userParams);
/** This callback function is for solving linear systems inside Knitro.
* Return 0 if successful, a negative error code if not.
*/
int KNITRO_API KN_set_linsolver_callback (KN_context_ptr kc,
KN_linsolver_callback * const fnPtr,
void * const userParams);
Loading full models
-
KN_load_lp()
int KNITRO_API KN_load_lp ( KN_context_ptr kc,
const KNINT n,
const double * const lobjCoefs, /* size = n */
const double * const xLoBnds, /* size = n */
const double * const xUpBnds, /* size = n */
const KNINT m,
const double * const cLoBnds, /* size = m */
const double * const cUpBnds, /* size = m */
const KNLONG nnzJ,
const KNINT * const ljacIndexCons, /* size = nnzJ */
const KNINT * const ljacIndexVars, /* size = nnzJ */
const double * const ljacCoefs); /* size = nnzJ */
This function loads all the basic data for a linear program (LP) in a single function call. It can only be called on a newly created Knitro problem object. After calling this function, the model may be augmented through additional Knitro API calls before solving. Returns 0 if OK, or a negative value on error.
-
KN_load_qp()
int KNITRO_API KN_load_qp ( KN_context_ptr kc,
const KNINT n,
const double * const lobjCoefs, /* size = n */
const double * const xLoBnds, /* size = n */
const double * const xUpBnds, /* size = n */
const KNINT m,
const double * const cLoBnds, /* size = m */
const double * const cUpBnds, /* size = m */
const KNLONG nnzJ,
const KNINT * const ljacIndexCons, /* size = nnzJ */
const KNINT * const ljacIndexVars, /* size = nnzJ */
const double * const ljacCoefs, /* size = nnzJ */
const KNLONG nnzH,
const KNINT * const qobjIndexVars1, /* size = nnzH */
const KNINT * const qobjIndexVars2, /* size = nnzH */
const double * const qobjCoefs); /* size = nnzH */
This function loads all the data for a quadratic program (QP) in a single function call. It can only be called on a newly created Knitro problem object. After calling this function, the model may be augmented through additional Knitro API calls before solving. Returns 0 if OK, or a negative value on error.
-
KN_load_qcqp()
int KNITRO_API KN_load_qcqp ( KN_context_ptr kc,
const KNINT n,
const double * const lobjCoefs, /* size = n */
const double * const xLoBnds, /* size = n */
const double * const xUpBnds, /* size = n */
const KNINT m,
const double * const cLoBnds, /* size = m */
const double * const cUpBnds, /* size = m */
const KNLONG nnzJ,
const KNINT * const ljacIndexCons, /* size = nnzJ */
const KNINT * const ljacIndexVars, /* size = nnzJ */
const double * const ljacCoefs, /* size = nnzJ */
const KNLONG nnzH,
const KNINT * const qobjIndexVars1, /* size = nnzH */
const KNINT * const qobjIndexVars2, /* size = nnzH */
const double * const qobjCoefs, /* size = nnzH */
const KNLONG nnzQ,
const KNINT * const qconIndexCons, /* size = nnzQ */
const KNINT * const qconIndexVars1, /* size = nnzQ */
const KNINT * const qconIndexVars2, /* size = nnzQ */
const double * const qconCoefs); /* size = nnzQ */
This function loads all the data for a quadratically constrained quadratic program (QCQP) in a single function call. It can only be called on a newly created Knitro problem object. After calling this function, the model may be augmented through additional Knitro API calls before solving. Returns 0 if OK, or a negative value on error.
Other algorithmic/modeling features
-
KN_set_var_feastols()
int KNITRO_API KN_set_var_feastols ( KN_context_ptr kc,
const KNINT nV,
const KNINT * const indexVars,
const double * const xFeasTols);
int KNITRO_API KN_set_var_feastols_all ( KN_context_ptr kc,
const double * const xFeasTols);
int KNITRO_API KN_set_var_feastol ( KN_context_ptr kc,
const KNINT indexVar,
const double xFeasTol);
Set an array of absolute feasibility tolerances for variable bounds
to use for the termination tests.
The user options KN_PARAM_FEASTOL / KN_PARAM_FEASTOLABS
define a single tolerance that is applied equally to every constraint
and variable. This API function allows the user to specify
separate feasibility termination tolerances for each variable.
Values specified through this function will override
the value determined by KN_PARAM_FEASTOL / KN_PARAM_FEASTOLABS.
The tolerances should be positive values. If a non-positive value is
specified, that variable will use the standard tolerances
based on KN_PARAM_FEASTOL / KN_PARAM_FEASTOLABS.
The variables are considered to be satisfied when:
x[i] - xUpBnds[i] <= xFeasTols[i] for all i=1..n, and
xLoBnds[i] - x[i] <= xFeasTols[i] for all i=1..n.
Returns 0 if OK, nonzero if error.
-
KN_set_con_feastols()
int KNITRO_API KN_set_con_feastols ( KN_context_ptr kc,
const KNINT nC,
const KNINT * const indexCons,
const double * const cFeasTols);
int KNITRO_API KN_set_con_feastols_all ( KN_context_ptr kc,
const double * const cFeasTols);
int KNITRO_API KN_set_con_feastol ( KN_context_ptr kc,
const KNINT indexCon,
const double cFeasTol);
Set an array of absolute constraint feasibility tolerances
to use for the termination tests.
The user options KN_PARAM_FEASTOL / KN_PARAM_FEASTOLABS
define a single tolerance that is applied equally to every constraint
and variable. This API function allows the user to specify
separate feasibility termination tolerances for each constraint.
Values specified through this function will override
the value determined by KN_PARAM_FEASTOL / KN_PARAM_FEASTOLABS.
The tolerances should be positive values. If a non-positive value is
specified, that constraint will use the standard tolerances
based on KN_PARAM_FEASTOL / KN_PARAM_FEASTOLABS.
The regular constraints are considered to be satisfied when:
c[i] - cUpBnds[i] <= cFeasTols[i] for all i=1..m, and
cLoBnds[i] - c[i] <= cFeasTols[i] for all i=1..m
Returns 0 if OK, nonzero if error.
-
KN_set_compcon_feastols()
int KNITRO_API KN_set_compcon_feastols ( KN_context_ptr kc,
const KNINT nCC,
const KNINT * const indexCompCons,
const double * const ccFeasTols);
int KNITRO_API KN_set_compcon_feastols_all ( KN_context_ptr kc,
const double * const ccFeasTols);
int KNITRO_API KN_set_compcon_feastol ( KN_context_ptr kc,
const KNINT indexCompCon,
const double ccFeasTol);
Set an array of absolute feasibility tolerances
to use for the complementarity constraint termination tests.
The user options KN_PARAM_FEASTOL / KN_PARAM_FEASTOLABS
define a single tolerance that is applied equally to every constraint
and variable. This API function allows the user to specify
separate feasibility termination tolerances for each complementarity constraint.
Values specified through this function will override
the value determined by KN_PARAM_FEASTOL / KN_PARAM_FEASTOLABS.
The tolerances should be positive values. If a non-positive value is
specified, that complementarity constraint will use the standard tolerances
based on KN_PARAM_FEASTOL / KN_PARAM_FEASTOLABS.
The complementarity constraints are considered to be satisfied when:
min(x1_i, x2_i) <= ccFeasTols[i] for all i=1..ncc,
where x1 and x2 are the arrays of complementary pairs. Returns 0 if OK, nonzero if error.
-
KN_set_var_scalings()
int KNITRO_API KN_set_var_scalings ( KN_context_ptr kc,
const KNINT nV,
const KNINT * const indexVars,
const double * const xScaleFactors,
const double * const xScaleCenters);
int KNITRO_API KN_set_var_scalings_all ( KN_context_ptr kc,
const double * const xScaleFactors,
const double * const xScaleCenters);
int KNITRO_API KN_set_var_scaling ( KN_context_ptr kc,
const KNINT indexVar,
const double xScaleFactor,
const double xScaleCenter);
Set an array of variable scaling and centering values to perform a linear scaling:
x[i] = xScaleFactors[i] * xScaled[i] + xScaleCenters[i]
for each variable. 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.
Returns 0 if OK, nonzero if error.
-
KN_set_con_scalings()
int KNITRO_API KN_set_con_scalings ( KN_context_ptr kc,
const KNINT nC,
const KNINT * const indexCons,
const double * const cScaleFactors);
int KNITRO_API KN_set_con_scalings_all ( KN_context_ptr kc,
const double * const cScaleFactors);
int KNITRO_API KN_set_con_scaling ( KN_context_ptr kc,
const KNINT indexCon,
const double cScaleFactor);
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. Scaling factors for
standard constraints can be provided with cScaleFactors.
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).
Returns 0 if OK, nonzero if error.
-
KN_set_compcon_scalings()
int KNITRO_API KN_set_compcon_scalings ( KN_context_ptr kc,
const KNINT nCC,
const KNINT * const indexCompCons,
const double * const ccScaleFactors);
int KNITRO_API KN_set_compcon_scalings_all ( KN_context_ptr kc,
const double * const ccScaleFactors);
int KNITRO_API KN_set_compcon_scaling ( KN_context_ptr kc,
const KNINT indexCompCons,
const double ccScaleFactor);
Set an array of complementarity constraint scaling values to perform a scaling:
ccScaled[i] = ccScaleFactors[i] * c[i]
for each complementarity 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 (ccScaled) used
internally by Knitro are close to one. Scaling factors for
complementarity constraints can be provided with ccScaleFactors.
The values for ccScaleFactors
should be positive. If a non-positive value is specified, that
complementarity constraint will use either the standard Knitro scaling
(KN_SCALE_USER_INTERNAL), or no scaling (KN_SCALE_USER_NONE).
Returns 0 if OK, nonzero if error.
-
KN_set_obj_scaling()
int KNITRO_API KN_set_obj_scaling ( KN_context_ptr kc,
const double objScaleFactor);
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).
Returns 0 if OK, nonzero if error.
-
KN_set_var_names()
int KNITRO_API KN_set_var_names ( KN_context_ptr kc,
const KNINT nV,
const KNINT * const indexVars,
char * const xNames[]);
int KNITRO_API KN_set_var_names_all ( KN_context_ptr kc,
char * const xNames[]);
int KNITRO_API KN_set_var_name ( KN_context_ptr kc,
const KNINT indexVars,
char * const xName);
Set names for model variables passed in by the user/modeling language so that Knitro can internally print out these variable names. Knitro makes a local copy of all inputs, so the application may free memory after the call. Returns 0 if OK, nonzero if error.
-
KN_set_con_names()
int KNITRO_API KN_set_con_names ( KN_context_ptr kc,
const KNINT nC,
const KNINT * const indexCons,
char * const cNames[]);
int KNITRO_API KN_set_con_names_all ( KN_context_ptr kc,
char * const cNames[]);
int KNITRO_API KN_set_con_name ( KN_context_ptr kc,
const KNINT indexCon,
char * const cName);
Set names for model constraints passed in by the user/modeling language so that Knitro can internally print out these constraint names. Knitro makes a local copy of all inputs, so the application may free memory after the call. Returns 0 if OK, nonzero if error.
-
KN_set_compcon_names()
int KNITRO_API KN_set_compcon_names ( KN_context_ptr kc,
const KNINT nCC,
const KNINT * const indexCompCons,
char * const ccNames[]);
int KNITRO_API KN_set_compcon_names_all ( KN_context_ptr kc,
char * const ccNames[]);
int KNITRO_API KN_set_compcon_name ( KN_context_ptr kc,
const int indexCompCon,
char * const ccName);
Set names for model complementarity constraints passed in by the user/modeling language so that Knitro can internally print out these complementarity constraint names. Knitro makes a local copy of all inputs, so the application may free memory after the call. Returns 0 if OK, nonzero if error.
-
KN_set_obj_name()
int KNITRO_API KN_set_obj_name ( KN_context_ptr kc,
const char * const objName);
Set name for model objective passed in by the user/modeling language so that Knitro can internally print out the objective name. Returns 0 if OK, nonzero if error.
-
KN_get_var_names()
int KNITRO_API KN_get_var_names (const KN_context_ptr kc,
const KNINT nV,
const KNINT * const indexVars,
const KNINT nBufferSize,
char * const xNames[]);
int KNITRO_API KN_get_var_names_all (const KN_context_ptr kc,
const KNINT nBufferSize,
char * const xNames[]);
int KNITRO_API KN_get_var_name (const KN_context_ptr kc,
const KNINT indexVars,
const KNINT nBufferSize,
char * const xName);
Get names for model variables passed in by the user/modeling language. Returns 0 if OK, nonzero if error.
-
KN_get_con_names()
int KNITRO_API KN_get_con_names (const KN_context_ptr kc,
const KNINT nC,
const KNINT * const indexCons,
const KNINT nBufferSize,
char * const cNames[]);
int KNITRO_API KN_get_con_names_all (const KN_context_ptr kc,
const KNINT nBufferSize,
char * const cNames[]);
int KNITRO_API KN_get_con_name (const KN_context_ptr kc,
const KNINT indexCon,
const KNINT nBufferSize,
char * const cName);
Get names for model constraints passed in by the user/modeling language. Returns 0 if OK, nonzero if error.
-
KN_set_var_honorbnds()
int KNITRO_API KN_set_var_honorbnds ( KN_context_ptr kc,
const KNINT nV,
const KNINT * const indexVars,
const int * const xHonorBnds);
int KNITRO_API KN_set_var_honorbnds_all ( KN_context_ptr kc,
const int * const xHonorBnds);
int KNITRO_API KN_set_var_honorbnd ( KN_context_ptr kc,
const KNINT indexVar,
const int xHonorBnd);
This API function can be used to identify which variables
should satisfy their variable bounds throughout the optimization
process (KN_HONORBNDS_ALWAYS). The user option KN_PARAM_HONORBNDS
can be used to set ALL variables to honor their bounds. This
routine takes precedence over the setting of KN_PARAM_HONORBNDS
and is used to customize the settings for individual variables.
Knitro makes a local copy of all inputs, so the application may
free memory after the call.
Returns 0 if OK, nonzero if error.
-
KN_set_con_honorbnds()
int KNITRO_API KN_set_con_honorbnds ( KN_context_ptr kc,
const KNINT nC,
const KNINT * const indexCons,
const int * const cHonorBnds);
int KNITRO_API KN_set_con_honorbnds_all ( KN_context_ptr kc,
const int * const cHonorBnds);
int KNITRO_API KN_set_con_honorbnd ( KN_context_ptr kc,
const KNINT indexCon,
const int cHonorBnd);
This API function can be used to identify which constraints
should satisfy their bounds throughout the optimization process.
Note that this feature currently only applies to INEQUALITY
constraints when using one of the barrier/interior-point algorithms.
The user option KN_PARAM_BAR_FEASIBLE can be used to set ALL
inequality constraints to honor their bounds (i.e. stay feasible).
This routine takes precedence over the setting of KN_PARAM_BAR_FEASIBLE
and is used to customize the settings for individual inequality
constraints.
The initial point must satisfy the inequality constraints specified through this API function to a sufficient degree; if not, Knitro may generate infeasible iterates and does not enable the “honorbnds” procedure until a sufficiently feasible point is found. Sufficient satisfaction occurs at a point x if it is true for all specified inequalities constraints that
The constant tol is determined by the option bar_feasmodetol.
Knitro makes a local copy of all inputs, so the application may free memory after the call. Returns 0 if OK, nonzero if error.
-
KN_set_mip_var_primal_init_values()
int KNITRO_API KN_set_mip_var_primal_init_values ( KN_context_ptr kc,
const KNINT nV,
const KNINT * const indexVars,
const double * const xInitVals);
int KNITRO_API KN_set_mip_var_primal_init_values_all ( KN_context_ptr kc,
const double * const xInitVals);
int KNITRO_API KN_set_mip_var_primal_init_value ( KN_context_ptr kc,
const KNINT indexVar,
const double xInitVal);
This function can be used to set initial primal variable values for MIP. This point may be used to search for an initial feasible point and may be different from the starting point for the root relaxation subproblem. Returns 0 if OK, nonzero if error.
-
KN_set_mip_branching_priorities()
int KNITRO_API KN_set_mip_branching_priorities
( KN_context_ptr kc,
const KNINT nV,
const KNINT * const indexVars,
const int * const xPriorities);
int KNITRO_API KN_set_mip_branching_priorities_all
( KN_context_ptr kc,
const int * const xPriorities);
int KNITRO_API KN_set_mip_branching_priority
( KN_context_ptr kc,
const KNINT indexVar,
const int xPriority);
This function can be used to set the branching priorities for integer variables
when using the MIP features in Knitro. You must first
set the types of variables (e.g. by calling KN_set_var_types()) before
calling this function so that integer variables are marked. Priorities must be positive numbers
(variables with non-positive values are ignored). Variables with higher priority
values will be considered for branching before variables with lower priority values.
When priorities for a subset of variables are equal, the branching rule is
applied as a tiebreaker. Values for
continuous variables are ignored. Knitro makes a local copy of all inputs,
so the application may free memory after the call.
Returns 0 if OK, nonzero if error.
-
KN_set_mip_intvar_strategies()
int KNITRO_API KN_set_mip_intvar_strategies
( KN_context_ptr kc,
const KNINT nV,
const KNINT * const indexVars,
const int * const xStrategies);
int KNITRO_API KN_set_mip_intvar_strategies_all
( KN_context_ptr kc,
const int * const xStrategies);
int KNITRO_API KN_set_mip_intvar_strategy
( KN_context_ptr kc,
const KNINT indexVar,
const int xStrategy);
Set strategies for dealing with individual integer variables. Possible strategy values include:
KN_MIP_INTVAR_STRATEGY_NONE 0 (default)
KN_MIP_INTVAR_STRATEGY_RELAX 1
KN_MIP_INTVAR_STRATEGY_MPEC 2 (binary variables only)
The parameter indexVars should be an index value corresponding to an integer variable
(nothing is done if the index value corresponds to a continuous variable),
and xStrategies should correspond to one of the strategy values listed above.
The default strategy is KN_MIP_INTVAR_STRATEGY_NONE, and the strategy
KN_MIP_INTVAR_STRATEGY_MPEC can only be applied to binary variables.
Returns 0 if OK, nonzero if error.
Solving
-
KN_solve()
int KNITRO_API KN_solve (KN_context_ptr kc);
Call Knitro to solve the problem. The return value indicates the final exit code from the optimization process:
0: the final solution is optimal to specified tolerances;
-100 to -109: a feasible solution was found (but not verified optimal);
-200 to -209: Knitro terminated at an infeasible point;
-300 to -301: the problem was determined to be unbounded;
-400 to -409: Knitro terminated because it reached a pre-defined limit
(a feasible point was found before reaching the limit);
-410 to -419: Knitro terminated because it reached a pre-defined limit
(no feasible point was found before reaching the limit);
-500 to -599: Knitro terminated with an input error or some non-standard error.
A detailed description of the possible return values is given in Return codes.
-
KN_update()
int KNITRO_API KN_update (KN_context_ptr kc);
Call Knitro to update the problem.
If the model has been modified (e.g. via adding, changing, deleting
structures), since the last solve, calling KN_update() will update the
internal model to incorporate all the changes since the most recent
solve, but will not proceed with solving. Typically, for efficiency,
the model is not actually updated with the most recent modifications
until KN_solve() is called, but KN_update() allows
for updating of the model without solving.
Returns 0 if OK, nonzero if error.
Reading model/solution properties
-
KN_get_number_vars()
int KNITRO_API KN_get_number_vars (const KN_context_ptr kc,
int * const nV);
Retrieve the number of variables nV in the model.
Returns 0 if OK, nonzero if error.
-
KN_get_number_cons()
int KNITRO_API KN_get_number_cons (const KN_context_ptr kc,
int * const nC);
Retrieve the number of constraints nC in the model.
Returns 0 if OK, nonzero if error.
-
KN_get_number_compcons()
int KNITRO_API KN_get_number_cons (const KN_context_ptr kc,
int * const nCC);
Retrieve the number of complementarity constraints nCC in the model.
Returns 0 if OK, nonzero if error.
-
KN_get_number_rsds()
int KNITRO_API KN_get_number_rsds (const KN_context_ptr kc,
int * const nR);
Retrieve the number of residuals nR in the model.
Returns 0 if OK, nonzero if error.
-
KN_get_number_FC_evals()
int KNITRO_API KN_get_number_FC_evals (const KN_context_ptr kc,
int * const numFCevals);
Return the number of function evaluations requested by KN_solve()
in numFCevals. One evaluation count includes a single evaluation of the
objective and all the constraints defined via callbacks (whether evaluated
altogether in one callback or evaluated using several separate callbacks).
Returns 0 if OK, nonzero if error.
-
KN_get_number_GA_evals()
int KNITRO_API KN_get_number_GA_evals (const KN_context_ptr kc,
int * const numGAevals);
Return the number of gradient evaluations requested by KN_solve()
in numGAevals. One evaluation count includes a single evaluation of the
first derivatives of the objective and all the constraints defined via
gradient callbacks (whether evaluated altogether in one callback or
evaluated using several separate callbacks).
Returns 0 if OK, nonzero if error.
-
KN_get_number_H_evals()
int KNITRO_API KN_get_number_H_evals (const KN_context_ptr kc,
int * const numHevals);
Return the number of Hessian evaluations requested by KN_solve()
in numHevals. One evaluation count includes a single evaluation of all
the components of the Hessian of the Lagrangian matrix defined via
callbacks (whether evaluated altogether in one callback or evaluated using
several separate callbacks).
Returns 0 if OK, nonzero if error.
-
KN_get_number_HV_evals()
int KNITRO_API KN_get_number_HV_evals (const KN_context_ptr kc,
int * const numHVevals);
Return the number of Hessian-vector products requested by KN_solve()
in numHVevals. One evaluation count includes a single
evaluation of the product of the Hessian of the Lagrangian matrix with a
vector submitted by Knitro (whether evaluated altogether in one callback
or evaluated using several separate callbacks).
Returns 0 if OK, nonzero if error.
-
KN_get_solve_time_cpu()
int KNITRO_API KN_get_solve_time_cpu(const KN_context_ptr kc,
double * const time);
Retrieve the Knitro CPU solve time.
-
KN_get_solve_time_real()
int KNITRO_API KN_get_solve_time_real(const KN_context_ptr kc,
double * const time);
Retrieve the Knitro real solve time.
-
KN_get_solution()
int KNITRO_API KN_get_solution (const KN_context_ptr kc,
int * const status,
double * const obj,
double * const x,
double * const lambda);
Return the solution status, objective, primal and dual variables.
The status and objective value scalars are returned as pointers
that need to be de-referenced to get their values. The arrays
x and lambda must be allocated by the user.
Returns 0 if call is successful; <0 if there is an error.
-
KN_get_obj_value()
int KNITRO_API KN_get_obj_value (const KN_context_ptr kc,
double * const obj);
Return the value of the objective obj(x) in obj.
Returns 0 if call is successful; <0 if there is an error.
-
KN_get_obj_type()
int KNITRO_API KN_get_obj_type (const KN_context_ptr kc,
int * const objType);
Return the type (e.g. KN_OBJTYPE_GENERAL, KN_OBJTYPE_LINEAR,
KN_OBJTYPE_QUADRATIC, etc.) of the objective obj(x) in objType.
Returns 0 if call is successful; <0 if there is an error.
-
KN_get_var_primal_values()
int KNITRO_API KN_get_var_primal_values (const KN_context_ptr kc,
const KNINT nV,
const KNINT * const indexVars,
double * const x);
int KNITRO_API KN_get_var_primal_values_all (const KN_context_ptr kc,
double * const x);
int KNITRO_API KN_get_var_primal_value (const KN_context_ptr kc,
const KNINT indexVar,
double * const x);
Return the primal (“x”) variables. Returns 0 if call is successful; <0 if there is an error.
-
KN_get_var_dual_values()
int KNITRO_API KN_get_var_dual_values (const KN_context_ptr kc,
const KNINT nV,
const KNINT * const indexVars,
double * const lambda);
int KNITRO_API KN_get_var_dual_values_all (const KN_context_ptr kc,
double * const lambda);
int KNITRO_API KN_get_var_dual_value (const KN_context_ptr kc,
const KNINT indexVar,
double * const lambda);
Return the dual (“lambda”) values (i.e. Lagrange multipliers) for the variables. Returns 0 if call is successful; <0 if there is an error.
-
KN_get_con_dual_values()
int KNITRO_API KN_get_con_dual_values (const KN_context_ptr kc,
const KNINT nC,
const KNINT * const indexCons,
double * const lambda);
int KNITRO_API KN_get_con_dual_values_all (const KN_context_ptr kc,
double * const lambda);
int KNITRO_API KN_get_con_dual_value (const KN_context_ptr kc,
const KNINT indexCons,
double * const lambda);
Return the dual (“lambda”) values (i.e. Lagrange multipliers) for the constraints. Returns 0 if call is successful; <0 if there is an error.
-
KN_get_con_values()
int KNITRO_API KN_get_con_values (const KN_context_ptr kc,
const KNINT nC,
const KNINT * const indexCons,
double * const c);
int KNITRO_API KN_get_con_values_all (const KN_context_ptr kc,
double * const c);
int KNITRO_API KN_get_con_value (const KN_context_ptr kc,
const KNINT indexCon,
double * const c);
Return the values of the constraint vector c(x) in c.
The array c must be allocated by the user.
Returns 0 if call is successful; <0 if there is an error.
-
KN_get_con_types()
int KNITRO_API KN_get_con_types (const KN_context_ptr kc,
const KNINT nC,
const KNINT * const indexCons,
int * const cTypes);
int KNITRO_API KN_get_con_types_all (const KN_context_ptr kc,
int * const cTypes);
int KNITRO_API KN_get_con_type (const KN_context_ptr kc,
const KNINT indexCon,
int * const cType);
Return the types (e.g. KN_CONTYPE_GENERAL, KN_CONTYPE_LINEAR,
KN_CONTYPE_QUADRATIC, etc.) of the constraint vector c(x) in cTypes.
The array cTypes must be allocated by the user.
Returns 0 if call is successful; <0 if there is an error.
-
KN_get_rsd_values()
int KNITRO_API KN_get_rsd_values (const KN_context_ptr kc,
const KNINT nR,
const KNINT * const indexRsds,
double * const r);
int KNITRO_API KN_get_rsd_values_all (const KN_context_ptr kc,
double * const r);
int KNITRO_API KN_get_rsd_value (const KN_context_ptr kc,
const KNINT indexRsd,
double * const r);
Return the values of the residual vector r(x) in r.
The array r must be allocated by the user.
Returns 0 if call is successful; <0 if there is an error.
-
KN_get_var_viols()
int KNITRO_API KN_get_var_viols (const KN_context_ptr kc,
const KNINT nV,
const KNINT * const indexVars,
KNINT * const bndInfeas,
KNINT * const intInfeas,
double * const viols);
int KNITRO_API KN_get_var_viols_all (const KN_context_ptr kc,
KNINT * const bndInfeas,
KNINT * const intInfeas,
double * const viols);
int KNITRO_API KN_get_var_viol (const KN_context_ptr kc,
const KNINT indexVar,
KNINT * const bndInfeas,
KNINT * const intInfeas,
double * const viol);
Return information about the feasibility of the variables x after solving.
The integer array bndInfeas indicates whether or not the variable
was deemed to be infeasible with respect to its bounds by the Knitro
termination test.
Possible values of bndInfeas are:
-1: The variable is considered infeasible with respect to its lower bound (or is less than its fixed value if fixed).
0: The variable is considered feasible with respect to the feasibility tolerances.
1: The variable is considered infeasible with respect to its upper bound (or is greater than its fixed value if fixed).
Note that even if the variable is deemed feasible it may still have a
non-zero violation returned in viols since the feasibility
tolerances allow for small violations.
The integer array intInfeas indicates whether or not an integer
variable was deemed to be infeasible with respect to integrality.
Possible values of intInfeas are:
-1: The integer variable is considered infeasible with respect to the integrality tolerance and is closer to its floor.
0: The integer variable is considered feasible with respect to the integrality tolerance (or the variable is continuous).
1: The integer variable is considered infeasible with respect to the integrality tolerance and is closer to its ceiling.
The non-negative array viols returns the amount by which the
variable violates its lower or upper bound. If the variable is an
integer variable that satisfies its lower and upper bounds, viols
returns the integrality error (i.e. the distance to the nearest
integer value inside its bounds).
The arrays bndInfeas, intInfeas and viols must be allocated by
the user to retrieve these values. Any of these arrays set to NULL
will not be returned.
Returns 0 if call is successful; <0 if there is an error.
-
KN_get_con_viols()
int KNITRO_API KN_get_con_viols (const KN_context_ptr kc,
const KNINT nC,
const KNINT * const indexCons,
KNINT * const infeas,
double * const viols);
int KNITRO_API KN_get_con_viols_all (const KN_context_ptr kc,
KNINT * const infeas,
double * const viols);
int KNITRO_API KN_get_con_viol (const KN_context_ptr kc,
const KNINT indexCon,
KNINT * const infeas,
double * const viol);
Return information about the feasibility of the constraints c(x) after solving.
The integer array infeas indicates whether or not the constraint
was deemed to be infeasible by the Knitro termination test.
Possible values of infeas are:
-1: The constraint is considered infeasible with respect to its lower bound (or is less than the right-hand side if it is an equality).
0: The constraint is considered feasible with respect to the feasibility tolerances.
1: The constraint is considered infeasible with respect to its upper bound (or is greater than the right-hand side if it is an equality).
Note that even if the constraint is deemed feasible it may still
have a non-zero violation returned in viols since the feasibility
tolerances allow for small violations.
The non-negative array viols returns the amount by which the
constraint violates its lower or upper bound.
The arrays infeas and viols must be allocated by the user to
retrieve these values. Any of these arrays set to NULL will not be
returned.
Returns 0 if call is successful; <0 if there is an error.
-
KN_get_presolve_error()
int KNITRO_API KN_get_presolve_error (const KN_context_ptr kc,
KNINT * const component,
KNINT * const index,
KNINT * const error,
double * const viol);
Return information about any errors detected by the Knitro presolver. Parameters have the following values.
component: The component involved in the error
(e.g., KN_COMPONENT_VAR, KN_COMPONENT_OBJ
KN_COMPONENT_CON, KN_COMPONENT_RSD).
Set to 0 if no error.
index: The component index involved in the error (set to -1 if no error).
error: Return code associated with the error
(e.g., KN_RC_INFEAS_VAR_BOUNDS, KN_RC_INFEAS_CON_BOUNDS,
KN_RC_UNBOUNDED_OR_INFEAS). Set to 0 if no error.
viol: If there was an infeasibility error, it returns the
amount of infeasibility deduced by the presolve for the
given component (otherwise set to 0).
Returns 0 if no presolve errors were detected; 1 if an error was detected in the presolve phase; <0 if there is an error in the function call.
-
KN_get_number_iters()
int KNITRO_API KN_get_number_iters (const KN_context_ptr kc,
int * const numIters);
Return the number of iterations made by KN_solve() in numIters.
Returns 0 if OK, nonzero if error.
For continuous problems only.
-
KN_get_number_cg_iters()
int KNITRO_API KN_get_number_cg_iters (const KN_context_ptr kc,
int * const numCGiters);
Return the number of conjugate gradients (CG) iterations made by KN_solve()
in numCGiters.
Returns 0 if OK, nonzero if error.
For continuous problems only.
-
KN_get_abs_feas_error()
int KNITRO_API KN_get_abs_feas_error (const KN_context_ptr kc,
double * const absFeasError);
Return the absolute feasibility error at the solution in absFeasError.
Refer to the Knitro manual section Termination criteria for a
detailed definition of this quantity.
Returns 0 if OK, nonzero if error.
For continuous problems only.
-
KN_get_rel_feas_error()
int KNITRO_API KN_get_rel_feas_error (const KN_context_ptr kc,
double * const relFeasError);
Return the relative feasibility error at the solution in relFeasError.
Refer to the Knitro manual section Termination criteria for a
detailed definition of this quantity.
Returns 0 if OK, nonzero if error.
For continuous problems only.
-
KN_get_abs_opt_error()
int KNITRO_API KN_get_abs_opt_error (const KN_context_ptr kc,
double * const absOptError);
Return the absolute optimality error at the solution in absOptError.
Refer to the Knitro manual section Termination criteria for a
detailed definition of this quantity.
Returns 0 if OK, nonzero if error.
For continuous problems only.
-
KN_get_rel_opt_error()
int KNITRO_API KN_get_rel_opt_error (const KN_context_ptr kc,
double * const relOptError);
Return the relative optimality error at the solution in relOptError.
Refer to the Knitro manual section Termination criteria for a
detailed definition of this quantity.
Returns 0 if OK, nonzero if error.
For continuous problems only.
-
KN_get_objgrad_values()
int KNITRO_API KN_get_objgrad_nnz (const KN_context_ptr kc,
KNINT * const nnz);
int KNITRO_API KN_get_objgrad_values (const KN_context_ptr kc,
KNINT * const indexVars,
double * const objGrad);
Return the values of the objective gradient vector in indexVars
and objGrad. The objective gradient values returned correspond
to the non-zero sparse objective gradient indices provided by the user.
The arrays indexVars and objGrad must be allocated by the user.
The size of these arrays is obtained by first calling
KN_get_objgrad_nnz().
Returns 0 if call is successful; <0 if there is an error.
For continuous problems only.
-
KN_get_objgrad_values_all()
int KNITRO_API KN_get_objgrad_values_all (const KN_context_ptr kc,
double * const objGrad);
Return the values of the full (dense) objective gradient in objGrad.
The array objGrad must be allocated by the user (the size is equal
to the total number of variables in the problem).
Returns 0 if call is successful; <0 if there is an error.
For continuous problems only.
-
KN_get_jacobian_values()
int KNITRO_API KN_get_jacobian_nnz (const KN_context_ptr kc,
KNLONG * const nnz);
int KNITRO_API KN_get_jacobian_values (const KN_context_ptr kc,
KNINT * const indexCons,
KNINT * const indexVars,
double * const jac);
int KNITRO_API KN_get_jacobian_nnz_one (const KN_context_ptr kc,
KNINT indexCon,
KNINT * const nnz);
int KNITRO_API KN_get_jacobian_values_one (const KN_context_ptr kc,
KNINT indexCon,
KNINT * const indexVars,
double * const jac);
Return the values of the constraint Jacobian in indexCons, indexVars,
and jac. The Jacobian values returned correspond to the non-zero
sparse Jacobian indices provided by the user.
The arrays indexCons, indexVars, and jac must be allocated by
the user. The size of these arrays is obtained by first calling
KN_get_jacobian_nnz().
Use KN_get_jacobian_nnz_one() / KN_get_jacobian_values_one() to
get the gradient/Jacobian values corresponding to just one constraint.
Returns 0 if call is successful; <0 if there is an error. For continuous problems only.
-
KN_get_rsd_jacobian_values()
int KNITRO_API KN_get_rsd_jacobian_nnz (const KN_context_ptr kc,
KNLONG * const nnz);
int KNITRO_API KN_get_rsd_jacobian_values (const KN_context_ptr kc,
KNINT * const indexRsds,
KNINT * const indexVars,
double * const rsdJac);
Return the values of the residual Jacobian in indexRsds, indexVars,
and rsdJac. The Jacobian values returned correspond to the non-zero
sparse Jacobian indices provided by the user.
The arrays indexRsds, indexVars and rsdJac must be allocated
by the user. The size of these arrays is obtained by first calling
KN_get_rsd_jacobian_nnz().
Returns 0 if call is successful; <0 if there is an error.
For continuous least-squares problems only.
-
KN_get_hessian_values()
int KNITRO_API KN_get_hessian_nnz (const KN_context_ptr kc,
KNLONG * const nnz);
int KNITRO_API KN_get_hessian_values (const KN_context_ptr kc,
KNINT * const indexVars1,
KNINT * const indexVars2,
double * const hess);
Return the values of the Hessian (or possibly Hessian
approximation) in hess. This routine is currently only valid
if one of the following cases holds:
KN_HESSOPT_EXACT, or;it’s a least squares model using the Gauss-Newton Hessian and the Gauss-Newton Hessian is explicitly computed and stored in Knitro.
In all other cases, either Knitro does not have an internal
representation of the Hessian (or Hessian approximation),
or the internal Hessian approximation corresponds only to
the presolved problem form and may not be valid for the
original problem form. In these cases indexVars1, indexVars2,
and hess are left unmodified, and the routine has return code 1.
The Hessian values
returned correspond to the non-zero sparse Hessian indices
returned by the arrays indexVars1 and indexVars2.
These arrays and the hess array must be allocated by the user.
The size of these arrays is obtained by first calling KN_get_hessian_nnz().
Returns 0 if call is successful;
1 if hess was not set because Knitro does not have a valid Hessian for the model stored;
<0 if there is an error.
For continuous problems only.
-
KN_get_mip_number_nodes()
int KNITRO_API KN_get_mip_number_nodes (const KN_context_ptr kc,
int * const numNodes);
Return the number of nodes processed in the MIP solve
in numNodes.
Returns 0 if OK, nonzero if error.
-
KN_get_mip_number_solves()
int KNITRO_API KN_get_mip_number_solves (const KN_context_ptr kc,
int * const numSolves);
Return the number of continuous subproblems processed in the
MIP solve in numSolves.
Returns 0 if OK, nonzero if error.
-
KN_get_mip_abs_gap()
int KNITRO_API KN_get_mip_abs_gap (const KN_context_ptr kc,
double * const absGap);
Return the final absolute optimality gap in the MIP solve
in absGap. Refer to the Knitro manual section Termination criteria
for a detailed definition of this quantity. Set to
KN_INFINITY if no incumbent (i.e., integer feasible) point found.
Returns 0 if OK, nonzero if error.
-
KN_get_mip_rel_gap()
int KNITRO_API KN_get_mip_rel_gap (const KN_context_ptr kc,
double * const relGap);
Return the final absolute optimality gap in the MIP solve
in relGap. Refer to the Knitro manual section Termination criteria
for a detailed definition of this quantity. Set to
KN_INFINITY if no incumbent (i.e., integer feasible) point found.
Returns 0 if OK, nonzero if error.
-
KN_get_mip_incumbent_obj()
int KNITRO_API KN_get_mip_incumbent_obj (const KN_context_ptr kc,
double * const incumbentObj);
Return the objective value of the MIP incumbent solution in
incumbentObj. Set to KN_INFINITY if no incumbent (i.e., integer
feasible) point found.
Returns 0 if incumbent solution exists and call is successful;
1 if no incumbent (i.e., integer feasible) exists;
<0 if there is an error.
-
KN_get_mip_relaxation_bnd()
int KNITRO_API KN_get_mip_relaxation_bnd (const KN_context_ptr kc,
double * const relaxBound);
Return the value of the current MIP relaxation bound in relaxBound.
Returns 0 if OK, nonzero if error.
-
KN_get_mip_lastnode_obj()
int KNITRO_API KN_get_mip_lastnode_obj (const KN_context_ptr kc,
double * const lastNodeObj);
Return the objective value of the most recently solved MIP
node subproblem in lastNodeObj.
Returns 0 if OK, nonzero if error.
-
KN_get_mip_incumbent_x()
int KNITRO_API KN_get_mip_incumbent_x (const KN_context_ptr kc,
double * const x);
Return the MIP incumbent solution in x if one exists.
Returns 0 if incumbent solution exists and call is successful;
1 if no incumbent (i.e., integer feasible) point exists
and leaves x unmodified; <0 if there is an error.
Problem definition defines
-
type
KN_INFINITY
#define KN_INFINITY DBL_MAX
Use to set infinite variable and constraint bounds in Knitro.
-
type
KN_PARAMTYPE
#define KN_PARAMTYPE_INTEGER 0
#define KN_PARAMTYPE_FLOAT 1
#define KN_PARAMTYPE_STRING 2
Possible parameter types.
-
type
KN_OBJGOAL
#define KN_OBJGOAL_MINIMIZE 0
#define KN_OBJGOAL_MAXIMIZE 1
Possible objective goals for the solver (objGoal in KN_set_obj_goal()).
-
type
KN_OBJTYPE
#define KN_OBJTYPE_CONSTANT -1
#define KN_OBJTYPE_GENERAL 0
#define KN_OBJTYPE_LINEAR 1
#define KN_OBJTYPE_QUADRATIC 2
Possible values for the objective type.
-
type
KN_CONTYPE
#define KN_CONTYPE_CONSTANT -1
#define KN_CONTYPE_GENERAL 0
#define KN_CONTYPE_LINEAR 1
#define KN_CONTYPE_QUADRATIC 2
#define KN_CONTYPE_CONIC 3
Possible values for the constraint type.
-
type
KN_RSDTYPE
#define KN_RSDTYPE_CONSTANT -1
#define KN_RSDTYPE_GENERAL 0
#define KN_RSDTYPE_LINEAR 1
Possible values for the residual type.
-
type
KN_CCTYPE
#define KN_CCTYPE_VARVAR 0
#define KN_CCTYPE_VARCON 1 /* NOT SUPPORTED YET */
#define KN_CCTYPE_CONCON 2 /* NOT SUPPORTED YET */
Possible values for the complementarity constraint type
(ccTypes in KN_set_compcons()). Currently only KN_CCTYPE_VARVAR
is supported. The other types will be supported in future releases.
-
type
KN_VARTYPE
#define KN_VARTYPE_CONTINUOUS 0
#define KN_VARTYPE_INTEGER 1
#define KN_VARTYPE_BINARY 2
Possible values for the variable type (xTypes in KN_set_var_types()).
-
type
KN_VAR_
#define KN_VAR_LINEAR 1 /*-- LINEAR ONLY EVERYWHERE */
Possible values for enabling bits to set variable properties
via KN_set_var_properties().
-
type
KN_OBJ_
#define KN_OBJ_CONVEX 1 /*-- CONVEX OBJECTIVE */
#define KN_OBJ_CONCAVE 2 /*-- CONCAVE OBJECTIVE */
#define KN_OBJ_CONTINUOUS 4 /*-- OBJECTIVE IS CONTINUOUS */
#define KN_OBJ_DIFFERENTIABLE 8 /*-- (ONCE) DIFFERENTIABLE OBJECTIVE */
#define KN_OBJ_TWICE_DIFFERENTIABLE 16 /*-- TWICE DIFFERENTIABLE OBJECTIVE */
#define KN_OBJ_NOISY 32 /*-- OBJECTIVE FUNCTION IS NOISY */
#define KN_OBJ_NONDETERMINISTIC 64 /*-- OBJECTIVE IS NONDETERMINISTIC */
Possible values for bit flags used to set objective
function properties via KN_set_obj_properties().
-
type
KN_CON_
#define KN_CON_CONVEX 1 /*-- CONVEX CONSTRAINT */
#define KN_CON_CONCAVE 2 /*-- CONCAVE CONSTRAINT */
#define KN_CON_CONTINUOUS 4 /*-- CONSTRAINT IS CONTINUOUS */
#define KN_CON_DIFFERENTIABLE 8 /*-- (ONCE) DIFFERENTIABLE CONSTRAINT */
#define KN_CON_TWICE_DIFFERENTIABLE 16 /*-- TWICE DIFFERENTIABLE CONSTRAINT */
#define KN_CON_NOISY 32 /*-- CONSTRAINT FUNCTION IS NOISY */
#define KN_CON_NONDETERMINISTIC 64 /*-- CONSTRAINT IS NONDETERMINISTIC */
Possible values for bit flags used to set constraint
function properties via KN_set_con_properties().
-
type
KN_DENSE
#define KN_DENSE -1 /*-- GENERIC DENSE (e.g. FOR ARRAYS) */
#define KN_DENSE_ROWMAJOR -2 /*-- DENSE MATRIX IN ROW MAJOR ORDER */
#define KN_DENSE_COLMAJOR -3 /*-- DENSE MATRIX IN COLUMN MAJOR ORDER */
Possible values for dense arrays or matrices.
-
type
KN_RC_
#define KN_RC_EVALFC 1 /*-- OBJECTIVE AND CONSTRAINT FUNCTIONS */
#define KN_RC_EVALGA 2 /*-- OBJ. GRADIENT AND CONSTRAINT JACOBIAN */
#define KN_RC_EVALH 3 /*-- HESSIAN OF THE LAGRANGIAN */
#define KN_RC_EVALHV 7 /*-- HESSIAN-VECTOR PRODUCT */
#define KN_RC_EVALH_NO_F 8 /*-- NO OBJECTIVE COMPONENT INCLUDED */
#define KN_RC_EVALHV_NO_F 9 /*-- NO OBJECTIVE COMPONENT INCLUDED */
#define KN_RC_EVALR 10 /*-- RESIDUAL FUNCTIONS (LEAST SQUARES) */
#define KN_RC_EVALRJ 11 /*-- RESIDUAL JACOBIAN (LEAST SQUARES) */
#define KN_RC_EVALFCGA 12 /*-- BOTH FUNCTIONS AND GRADIENTS */
Possible evaluation request codes for evaluation callbacks.