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

KN_new()

Create a new Knitro solver object

KN_free()

Free/destroy an existing Knitro solver object

Changing and reading solver parameters

API function name

Purpose

KN_reset_params_to_defaults()

Reset all user options to their default values

KN_load_param_file()

Read user options from a Knitro options file

KN_load_tuner_file()

Read user options and values to explore for Knitro-Tuner

KN_save_param_file()

Write all current user options to a file

KN_set_int_param_by_name()

Set integer valued option using its string name

KN_set_char_param_by_name()

Set character valued option using its string name

KN_set_double_param_by_name()

Set double valued option using its string name

KN_set_param_by_name()

Set integer or doubled valued option using its string name

KN_set_int_param()

Set integer valued option using its integer identifier

KN_set_char_param()

Set character valued option using its integer identifier

KN_set_double_param()

Set double valued option using its integer identifier

KN_get_int_param_by_name()

Get integer valued option using its string name

KN_get_double_param_by_name()

Get double valued option using its string name

KN_get_int_param()

Get integer valued option using its integer identifier

KN_get_double_param()

Get double valued option using its integer identifier

KN_get_param_name()

Get string name associated with user option

KN_get_param_doc()

Get documentation string associated with user option

KN_get_param_type()

Get type (KN_PARAM_TYPE_*) associated with user option

KN_get_num_param_values()

Get number of possible values associated with integer valued user option

KN_get_param_value_doc()

Get documentation string associated with user option value

KN_get_param_id()

Get integer identifier associated with user option

Basic problem construction

API function name

Purpose

KN_add_vars()

Add new variables to a model

KN_add_cons()

Add new constraints to a model

KN_add_rsds()

Add new residuals to a least-squares model

KN_set_var_lobnds()

Set lower bounds on variables

KN_set_var_upbnds()

Set upper bounds on variables

KN_set_var_fxbnds()

Set fixed bounds on variables

KN_set_var_types()

Set variable types (e.g., continuous, integer, etc)

KN_set_var_properties()

Set variable properties (e.g., linear)

KN_set_con_lobnds()

Set lower bounds on constraints

KN_set_con_upbnds()

Set upper bounds on constraints

KN_set_con_eqbnds()

Set equality bounds on constraints

KN_set_con_properties()

Set constraint properties (e.g., convex)

KN_set_obj_property()

Set objective properties (e.g., convex)

KN_set_obj_goal()

Specify minimize of maximize

KN_set_var_primal_init_values()

Set initial values for primal variables

KN_set_var_dual_init_values()

Set initial values for dual variables

KN_set_con_dual_init_values()

Set initial values for constraint multipliers

Adding/removing/changing constant structure

API function name

Purpose

KN_add_obj_constant()

Add a constant to the objective

KN_del_obj_constant()

Delete a constant from the objective

KN_chg_obj_constant()

Change a constant term in the objective

KN_add_con_constants()

Add constants to the constraints

KN_del_con_constants()

Delete constants from the constraints

KN_chg_con_constants()

Change constant terms in the constraints

KN_add_rsd_constants()

Add constants to the residuals for least-squares models

Adding/removing/changing linear structure

API function name

Purpose

KN_add_obj_linear_struct()

Add linear structure to the objective

KN_del_obj_linear_struct()

Delete linear structure from the objective

KN_chg_obj_linear_struct()

Change linear structure in the objective

KN_add_con_linear_struct()

Add linear structure to the constraints

KN_del_con_linear_struct()

Delete linear structure from the constraints

KN_chg_con_linear_struct()

Change linear structure in the constraints

KN_add_rsd_linear_struct()

Add linear structure to the residuals for least-squares models

Adding quadratic structure

API function name

Purpose

KN_add_obj_quadratic_struct()

Add quadratic structure to the objective

KN_add_con_quadratic_struct()

Add quadratic structure to the constraints

Adding conic structure

API function name

Purpose

KN_add_con_L2norm()

Add L2norm structure used to define conic constraints

Adding complementarity constraints

API function name

Purpose

KN_set_compcons()

Set all complementarity constraints for a model

Adding evaluation callbacks

API function name

Purpose

KN_add_eval_callback()

Add a callback for nolinear evaluations

KN_add_eval_callback_all()

Add a callback for nolinear evaluations of all functions

KN_add_eval_callback_one()

Add a callback for nolinear evaluations of one function

KN_add_lsq_eval_callback()

Add a callback for nolinear least-squares evaluations

KN_add_lsq_eval_callback_all()

Add a callback for nolinear least-squares evaluations of all functions

KN_add_lsq_eval_callback_one()

Add a callback for nolinear least-squares evaluations of one function

KN_set_cb_grad()

Set callback for objective gradient and constraint Jacobian

KN_set_cb_hess()

Set callback for Hessian of the Lagrangian matrix

KN_set_cb_rsd_jac()

Set callback for least-squares residual Jacobian

KN_set_cb_user_params()

Set a user parameters structure for evaluation callback

KN_set_cb_gradopt()

Specify how to evaluate gradients in evaluation callback

KN_set_cb_relstepsizes()

Specify finite-difference relative stepsizes

KN_get_cb_number_cons()

Get the number of constraints evaluated through the callback

KN_get_cb_number_rsds()

Get the number of residuals evaluated through the callback

KN_get_cb_objgrad_nnz()

Get the number of non-zero objective gradient elements evaluated through the callback

KN_get_cb_jacobian_nnz()

Get the number of non-zero Jacobian elements evaluated through the callback

KN_get_cb_rsd_jacobian_nnz()

Get the number of non-zero residual Jacobian elements evaluated through the callback

KN_get_cb_hessian_nnz()

Get the number of non-zero Hessian elements evaluated through the callback

Other user callbacks

API function name

Purpose

KN_set_newpt_callback()

Callback to perform some user-defined task after new solution estimate

KN_set_mip_node_callback()

Callback to perform some user-defined task after MIP node solve

KN_set_ms_process_callback()

Callback to perform some user-defined task after multi-start solve

KN_set_ms_initpt_callback()

Callback to specify custom initial points for multi-start

KN_set_puts_callback()

Callback to specify custom handling of output

KN_set_linsolver_callback()

Callback to specify custom linear system solver

Other algorithmic/modeling features

API function name

Purpose

KN_set_var_feastols()

Set custom feasibility tolerances for variables

KN_set_con_feastols()

Set custom feasibility tolerances for constraints

KN_set_compcon_feastols()

Set custom feasibility tolerances for complementarity constraints

KN_set_var_scalings()

Set custom scalings for variables

KN_set_con_scalings()

Set custom scalings for constraints

KN_set_compcon_scalings()

Set custom scalings for complementarity constraints

KN_set_obj_scaling()

Set a custom scaling for the objective

KN_set_var_names()

Set names for variables

KN_set_con_names()

Set names for constraints

KN_set_compcon_names()

Set names for complementarity constraints

KN_set_obj_name()

Set a name for the objective

KN_set_var_honorbnds()

Enforce variables satisfy bounds throughout optimization

KN_set_con_honorbnds()

Enforce (inequality) constraints satisfy bounds throughout optimization

KN_set_mip_var_primal_init_values()

Set initial primal variable values for MIP

KN_set_mip_branching_priorities()

Set branching priorities for integer variables

KN_set_mip_intvar_strategies()

Set strategies for handling integer variables

Solving

API function name

Purpose

KN_solve()

Call Knitro to solve/optimize the current model

KN_update()

Call Knitro to update the current model

Reading model/solution properties

API function name

Purpose

KN_get_release()

Get Knitro release number

KN_get_number_vars()

Get the number of variables in the model

KN_get_number_cons()

Get the number of constraints in the model

KN_get_number_rsds()

Get the number of residuals in the model

KN_get_number_FC_evals()

Get the number of function evaluations during the solve

KN_get_number_GA_evals()

Get the number of gradient evaluations during the solve

KN_get_number_H_evals()

Get the number of Hessian evaluations during the solve

KN_get_number_HV_evals()

Get the number of Hessian-vector product evaluations during the solve

KN_get_solution()

Get the solution status, objective and variables

KN_get_obj_value()

Get the value of the objective function

KN_get_obj_type()

Get the objective function type (e.g. linear, quadratic, general, etc.)

KN_get_var_primal_values()

Return the primal (“x”) variables

KN_get_var_dual_values()

Return the dual (“lambda”) values (i.e. Lagrange multipliers) for the variables

KN_get_con_values()

Get the value of the constraint functions

KN_get_con_types()

Get the constraint function types (e.g. linear, quadratic, general, etc.)

KN_get_rsd_values()

Get the value of the residual functions

KN_get_number_iters()

Get the number of iterations (continuous models only)

KN_get_number_cg_iters()

Get the number of conjugate gradient iterations (continuous models only)

KN_get_abs_feas_error()

Get the absolute feasibility error (continuous models only)

KN_get_rel_feas_error()

Get the relative feasibility error (continuous models only)

KN_get_abs_opt_error()

Get the absolute optimality error (continuous models only)

KN_get_rel_opt_error()

Get the relative optimality error (continuous models only)

KN_get_objgrad_values()

Get the objective gradient values (continuous models only)

KN_get_objgrad_values_all()

Get the objective gradient values in dense form (continuous models only)

KN_get_jacobian_values()

Get the constraint Jacobian values (continuous models only)

KN_get_rsd_jacobian_values()

Get the residual Jacobian values (continuous models only)

KN_get_hessian_values()

Get the Hessian values (continuous models only)

KN_get_mip_number_nodes()

Get the number of MIP nodes explored (MIP models only)

KN_get_mip_number_solves()

Get the number of MIP subproblem solves (MIP models only)

KN_get_mip_abs_gap()

Get the absolute optimality gap (MIP models only)

KN_get_mip_rel_gap()

Get the relative optimality gap (MIP models only)

KN_get_mip_incumbent_obj()

Get the objective value of the incumbent solution (MIP models only)

KN_get_mip_relaxation_bnd()

Get the current relaxation bound (MIP models only)

KN_get_mip_lastnode_obj()

Get the objective value from the most recently solved node (MIP models only)

KN_get_mip_incumbent_x()

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

cl + tol \leq c(x) \leq cu - tol

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:

  1. KN_HESSOPT_EXACT, or;

  2. 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.