IpStdCInterface.h File Reference

#include <stdbool.h>
#include "IpoptConfig.h"
#include "IpTypes.h"
#include "IpReturnCodes.h"

Go to the source code of this file.

Macros
#define	TRUE   (1)
#define	FALSE   (0)

Typedefs
typedef struct IpoptProblemInfo *	IpoptProblem
	Pointer to an Ipopt Problem.
typedef bool	Bool
	define a boolean type for C
typedef void *	UserDataPtr
	A pointer for anything that is to be passed between the called and individual callback function.
typedef bool(*	Eval_F_CB) (ipindex n, ipnumber *x, bool new_x, ipnumber *obj_value, UserDataPtr user_data)
	Type defining the callback function for evaluating the value of the objective function.
typedef bool(*	Eval_Grad_F_CB) (ipindex n, ipnumber *x, bool new_x, ipnumber *grad_f, UserDataPtr user_data)
	Type defining the callback function for evaluating the gradient of the objective function.
typedef bool(*	Eval_G_CB) (ipindex n, ipnumber *x, bool new_x, ipindex m, ipnumber *g, UserDataPtr user_data)
	Type defining the callback function for evaluating the value of the constraint functions.
typedef bool(*	Eval_Jac_G_CB) (ipindex n, ipnumber *x, bool new_x, ipindex m, ipindex nele_jac, ipindex *iRow, ipindex *jCol, ipnumber *values, UserDataPtr user_data)
	Type defining the callback function for evaluating the Jacobian of the constrant functions.
typedef bool(*	Eval_H_CB) (ipindex n, ipnumber *x, bool new_x, ipnumber obj_factor, ipindex m, ipnumber *lambda, bool new_lambda, ipindex nele_hess, ipindex *iRow, ipindex *jCol, ipnumber *values, UserDataPtr user_data)
	Type defining the callback function for evaluating the Hessian of the Lagrangian function.
typedef bool(*	Intermediate_CB) (ipindex alg_mod, ipindex iter_count, ipnumber obj_value, ipnumber inf_pr, ipnumber inf_du, ipnumber mu, ipnumber d_norm, ipnumber regularization_size, ipnumber alpha_du, ipnumber alpha_pr, ipindex ls_trials, UserDataPtr user_data)
	Type defining the callback function for giving intermediate execution control to the user.

Functions
IPOPTLIB_EXPORT IpoptProblem IPOPT_CALLCONV	CreateIpoptProblem (ipindex n, ipnumber *x_L, ipnumber *x_U, ipindex m, ipnumber *g_L, ipnumber *g_U, ipindex nele_jac, ipindex nele_hess, ipindex index_style, Eval_F_CB eval_f, Eval_G_CB eval_g, Eval_Grad_F_CB eval_grad_f, Eval_Jac_G_CB eval_jac_g, Eval_H_CB eval_h)
	Function for creating a new Ipopt Problem object.
IPOPTLIB_EXPORT void IPOPT_CALLCONV	FreeIpoptProblem (IpoptProblem ipopt_problem)
	Method for freeing a previously created IpoptProblem.
IPOPTLIB_EXPORT bool IPOPT_CALLCONV	AddIpoptStrOption (IpoptProblem ipopt_problem, char *keyword, char *val)
	Function for adding a string option.
IPOPTLIB_EXPORT bool IPOPT_CALLCONV	AddIpoptNumOption (IpoptProblem ipopt_problem, char *keyword, ipnumber val)
	Function for adding a Number option.
IPOPTLIB_EXPORT bool IPOPT_CALLCONV	AddIpoptIntOption (IpoptProblem ipopt_problem, char *keyword, ipindex val)
	Function for adding an Integer option.
IPOPTLIB_EXPORT bool IPOPT_CALLCONV	OpenIpoptOutputFile (IpoptProblem ipopt_problem, char *file_name, int print_level)
	Function for opening an output file for a given name with given printlevel.
IPOPTLIB_EXPORT bool IPOPT_CALLCONV	SetIpoptProblemScaling (IpoptProblem ipopt_problem, ipnumber obj_scaling, ipnumber *x_scaling, ipnumber *g_scaling)
	Optional function for setting scaling parameter for the NLP.
IPOPTLIB_EXPORT bool IPOPT_CALLCONV	SetIntermediateCallback (IpoptProblem ipopt_problem, Intermediate_CB intermediate_cb)
	Setting a callback function for the "intermediate callback" method in the TNLP.
IPOPTLIB_EXPORT enum ApplicationReturnStatus IPOPT_CALLCONV	IpoptSolve (IpoptProblem ipopt_problem, ipnumber *x, ipnumber *g, ipnumber *obj_val, ipnumber *mult_g, ipnumber *mult_x_L, ipnumber *mult_x_U, UserDataPtr user_data)
	Function calling the Ipopt optimization algorithm for a problem previously defined with CreateIpoptProblem.
IPOPTLIB_EXPORT bool IPOPT_CALLCONV	GetIpoptCurrentIterate (IpoptProblem ipopt_problem, bool scaled, ipindex n, ipnumber *x, ipnumber *z_L, ipnumber *z_U, ipindex m, ipnumber *g, ipnumber *lambda)
	Get primal and dual variable values of the current iterate.
IPOPTLIB_EXPORT bool IPOPT_CALLCONV	GetIpoptCurrentViolations (IpoptProblem ipopt_problem, bool scaled, ipindex n, ipnumber *x_L_violation, ipnumber *x_U_violation, ipnumber *compl_x_L, ipnumber *compl_x_U, ipnumber *grad_lag_x, ipindex m, ipnumber *nlp_constraint_violation, ipnumber *compl_g)
	Get primal and dual infeasibility of the current iterate.

Variables
IPOPT_DEPRECATED typedef ipnumber	Number
	Type for all number.
IPOPT_DEPRECATED typedef int	Index
	Type for all indices.
IPOPT_DEPRECATED typedef int	Int
	Type for all integers.

Macro Definition Documentation

TRUE

#define TRUE   (1)

Definition at line 57 of file IpStdCInterface.h.

FALSE

#define FALSE   (0)

Definition at line 61 of file IpStdCInterface.h.

Typedef Documentation

IpoptProblem

typedef struct IpoptProblemInfo* IpoptProblem

Pointer to an Ipopt Problem.

Definition at line 49 of file IpStdCInterface.h.

Bool

typedef bool Bool

define a boolean type for C

Deprecated:

Use bool instead.

Definition at line 54 of file IpStdCInterface.h.

UserDataPtr

typedef void* UserDataPtr

A pointer for anything that is to be passed between the called and individual callback function.

Definition at line 65 of file IpStdCInterface.h.

Eval_F_CB

typedef bool(* Eval_F_CB) (ipindex n, ipnumber *x, bool new_x, ipnumber *obj_value, UserDataPtr user_data)

Type defining the callback function for evaluating the value of the objective function.

Return value should be set to false if there was a problem doing the evaluation.

See also Ipopt::TNLP::eval_f.

Definition at line 73 of file IpStdCInterface.h.

Eval_Grad_F_CB

typedef bool(* Eval_Grad_F_CB) (ipindex n, ipnumber *x, bool new_x, ipnumber *grad_f, UserDataPtr user_data)

Type defining the callback function for evaluating the gradient of the objective function.

Return value should be set to false if there was a problem doing the evaluation.

See also Ipopt::TNLP::eval_grad_f.

Definition at line 87 of file IpStdCInterface.h.

Eval_G_CB

typedef bool(* Eval_G_CB) (ipindex n, ipnumber *x, bool new_x, ipindex m, ipnumber *g, UserDataPtr user_data)

Type defining the callback function for evaluating the value of the constraint functions.

Return value should be set to false if there was a problem doing the evaluation.

See also Ipopt::TNLP::eval_g.

Definition at line 101 of file IpStdCInterface.h.

Eval_Jac_G_CB

typedef bool(* Eval_Jac_G_CB) (ipindex n, ipnumber *x, bool new_x, ipindex m, ipindex nele_jac, ipindex *iRow, ipindex *jCol, ipnumber *values, UserDataPtr user_data)

Type defining the callback function for evaluating the Jacobian of the constrant functions.

Return value should be set to false if there was a problem doing the evaluation.

See also Ipopt::TNLP::eval_jac_g.

Definition at line 116 of file IpStdCInterface.h.

Eval_H_CB

typedef bool(* Eval_H_CB) (ipindex n, ipnumber *x, bool new_x, ipnumber obj_factor, ipindex m, ipnumber *lambda, bool new_lambda, ipindex nele_hess, ipindex *iRow, ipindex *jCol, ipnumber *values, UserDataPtr user_data)

Type defining the callback function for evaluating the Hessian of the Lagrangian function.

Return value should be set to false if there was a problem doing the evaluation.

See also Ipopt::TNLP::eval_h.

Definition at line 134 of file IpStdCInterface.h.

Intermediate_CB

typedef bool(* Intermediate_CB) (ipindex alg_mod, ipindex iter_count, ipnumber obj_value, ipnumber inf_pr, ipnumber inf_du, ipnumber mu, ipnumber d_norm, ipnumber regularization_size, ipnumber alpha_du, ipnumber alpha_pr, ipindex ls_trials, UserDataPtr user_data)

Type defining the callback function for giving intermediate execution control to the user.

If set, it is called once per iteration, providing the user with some information on the state of the optimization. This can be used to print some user-defined output. It also gives the user a way to terminate the optimization prematurely. If this method returns false, Ipopt will terminate the optimization.

See also Ipopt::TNLP::intermediate_callback.

Parameters

alg_mod	algorithm mode: 0 is regular, 1 is restoration
iter_count	iteration number
obj_value	objective function value
inf_pr	primal infeasibility
inf_du	dual infeasibility
mu	barrier parameter
d_norm	infinity-norm of primal step
regularization_size	size of regularization of Hessian of Lagrangian
alpha_du	step length for dual variables
alpha_pr	step length for primal variables
ls_trials	number of backtracking line search steps
user_data	user data

Definition at line 159 of file IpStdCInterface.h.

Function Documentation

CreateIpoptProblem()

IPOPTLIB_EXPORT IpoptProblem IPOPT_CALLCONV CreateIpoptProblem	(	ipindex	n,
		ipnumber *	x_L,
		ipnumber *	x_U,
		ipindex	m,
		ipnumber *	g_L,
		ipnumber *	g_U,
		ipindex	nele_jac,
		ipindex	nele_hess,
		ipindex	index_style,
		Eval_F_CB	eval_f,
		Eval_G_CB	eval_g,
		Eval_Grad_F_CB	eval_grad_f,
		Eval_Jac_G_CB	eval_jac_g,
		Eval_H_CB	eval_h
	)

Function for creating a new Ipopt Problem object.

This function returns an object that can be passed to the IpoptSolve call. It contains the basic definition of the optimization problem, such as number of variables and constraints, bounds on variables and constraints, information about the derivatives, and the callback function for the computation of the optimization problem functions and derivatives. During this call, the options file PARAMS.DAT is read as well.

If NULL is returned, there was a problem with one of the inputs or reading the options file.

See also Ipopt::TNLP::get_nlp_info and Ipopt::TNLP::get_bounds_info.

Parameters

n	Number of optimization variables
x_L	Lower bounds on variables

This array of size n is copied internally, so that the caller can change the incoming data after return without that IpoptProblem is modified. Any value less or equal than the number specified by option 'nlp_lower_bound_inf' is interpreted to be minus infinity.

Parameters

x_U	Upper bounds on variables

This array of size n is copied internally, so that the caller can change the incoming data after return without that IpoptProblem is modified. Any value greater or equal than the number specified by option 'nlp_upper_bound_inf' is interpreted to be plus infinity.

Parameters

m	Number of constraints
g_L	Lower bounds on constraints

This array of size m is copied internally, so that the caller can change the incoming data after return without that IpoptProblem is modified. Any value less or equal than the number specified by option 'nlp_lower_bound_inf' is interpreted to be minus infinity.

Parameters

g_U	Upper bounds on constraints

This array of size m is copied internally, so that the caller can change the incoming data after return without that IpoptProblem is modified. Any value greater or equal than the number specified by option 'nlp_upper_bound_inf' is interpreted to be plus infinity.

Parameters

nele_jac	Number of non-zero elements in constraint Jacobian
nele_hess	Number of non-zero elements in Hessian of Lagrangian
index_style	Indexing style for iRow & jCol, 0 for C style, 1 for Fortran style
eval_f	Callback function for evaluating objective function
eval_g	Callback function for evaluating constraint functions
eval_grad_f	Callback function for evaluating gradient of objective function
eval_jac_g	Callback function for evaluating Jacobian of constraint functions
eval_h	Callback function for evaluating Hessian of Lagrangian function

FreeIpoptProblem()

IPOPTLIB_EXPORT void IPOPT_CALLCONV FreeIpoptProblem

(

IpoptProblem

ipopt_problem

)

Method for freeing a previously created IpoptProblem.

After freeing an IpoptProblem, it cannot be used anymore.

AddIpoptStrOption()

IPOPTLIB_EXPORT bool IPOPT_CALLCONV AddIpoptStrOption	(	IpoptProblem	ipopt_problem,
		char *	keyword,
		char *	val
	)

Function for adding a string option.

Returns

false, if the option could not be set (e.g., if keyword is unknown)

AddIpoptNumOption()

IPOPTLIB_EXPORT bool IPOPT_CALLCONV AddIpoptNumOption	(	IpoptProblem	ipopt_problem,
		char *	keyword,
		ipnumber	val
	)

Function for adding a Number option.

Returns

false, if the option could not be set (e.g., if keyword is unknown)

AddIpoptIntOption()

IPOPTLIB_EXPORT bool IPOPT_CALLCONV AddIpoptIntOption	(	IpoptProblem	ipopt_problem,
		char *	keyword,
		ipindex	val
	)

Function for adding an Integer option.

Returns

false, if the option could not be set (e.g., if keyword is unknown) @

OpenIpoptOutputFile()

IPOPTLIB_EXPORT bool IPOPT_CALLCONV OpenIpoptOutputFile	(	IpoptProblem	ipopt_problem,
		char *	file_name,
		int	print_level
	)

Function for opening an output file for a given name with given printlevel.

Returns

false, if there was a problem opening the file.

SetIpoptProblemScaling()

IPOPTLIB_EXPORT bool IPOPT_CALLCONV SetIpoptProblemScaling	(	IpoptProblem	ipopt_problem,
		ipnumber	obj_scaling,
		ipnumber *	x_scaling,
		ipnumber *	g_scaling
	)

Optional function for setting scaling parameter for the NLP.

This corresponds to the TNLP::get_scaling_parameters method. If the pointers x_scaling or g_scaling are NULL, then no scaling for x resp. g is done.

SetIntermediateCallback()

IPOPTLIB_EXPORT bool IPOPT_CALLCONV SetIntermediateCallback	(	IpoptProblem	ipopt_problem,
		Intermediate_CB	intermediate_cb
	)

Setting a callback function for the "intermediate callback" method in the TNLP.

This gives control back to the user once per iteration. If set, it provides the user with some information on the state of the optimization. This can be used to print some user-defined output. It also gives the user a way to terminate the optimization prematurely. If the callback method returns false, Ipopt will terminate the optimization. Calling this set method to set the CB pointer to NULL disables the intermediate callback functionality.

IpoptSolve()

IPOPTLIB_EXPORT enum ApplicationReturnStatus IPOPT_CALLCONV IpoptSolve	(	IpoptProblem	ipopt_problem,
		ipnumber *	x,
		ipnumber *	g,
		ipnumber *	obj_val,
		ipnumber *	mult_g,
		ipnumber *	mult_x_L,
		ipnumber *	mult_x_U,
		UserDataPtr	user_data
	)

Function calling the Ipopt optimization algorithm for a problem previously defined with CreateIpoptProblem.

Returns

outcome of the optimization procedure (e.g., success, failure etc).

Parameters

ipopt_problem

Problem that is to be optimized.

Ipopt will use the options previously specified with AddIpoptOption (etc) for this problem.

Parameters

x	Input: Starting point; Output: Optimal solution
g	Values of constraint at final point (output only; ignored if set to NULL)
obj_val	Final value of objective function (output only; ignored if set to NULL)
mult_g	Input: Initial values for the constraint multipliers (only if warm start option is chosen); Output: Final multipliers for constraints (ignored if set to NULL)
mult_x_L	Input: Initial values for the multipliers for lower variable bounds (only if warm start option is chosen); Output: Final multipliers for lower variable bounds (ignored if set to NULL)
mult_x_U	Input: Initial values for the multipliers for upper variable bounds (only if warm start option is chosen); Output: Final multipliers for upper variable bounds (ignored if set to NULL)
user_data	Pointer to user data.

This will be passed unmodified to the callback functions.

GetIpoptCurrentIterate()

IPOPTLIB_EXPORT bool IPOPT_CALLCONV GetIpoptCurrentIterate	(	IpoptProblem	ipopt_problem,
		bool	scaled,
		ipindex	n,
		ipnumber *	x,
		ipnumber *	z_L,
		ipnumber *	z_U,
		ipindex	m,
		ipnumber *	g,
		ipnumber *	lambda
	)

Get primal and dual variable values of the current iterate.

This method can be used to get the values of the current iterate during the intermediate callback set by SetIntermediateCallback(). The method expects the number of variables (dimension of x), number of constraints (dimension of g(x)), and allocated arrays of appropriate lengths as input.

The method translates the x(), c(), d(), y_c(), y_d(), z_L(), and z_U() vectors from Ipopt::IpoptData::curr() of the internal NLP representation into the form used by the TNLP. For the correspondence between scaled and unscaled solutions, see the detailed description of Ipopt::OrigIpoptNLP. If Ipopt is in restoration mode, it maps the current iterate of restoration NLP (see Ipopt::RestoIpoptNLP) back to the original TNLP.

If there are fixed variables and fixed_variable_treatment=make_parameter, then requesting z_L and z_U can trigger a reevaluation of the Gradient of the objective function and the Jacobian of the constraint functions.

Parameters

ipopt_problem	(in) Problem that is currently optimized.
n	(in) the number of variables \(x\) in the problem; can be arbitrary if skipping x, z_L, and z_U
scaled	(in) whether to retrieve scaled or unscaled iterate
x	(out) buffer to store value of primal variables \(x\), must have length at least n; pass NULL to skip retrieving x
z_L	(out) buffer to store the lower bound multipliers \(z_L\), must have length at least n; pass NULL to skip retrieving z_L and Z_U
z_U	(out) buffer to store the upper bound multipliers \(z_U\), must have length at least n; pass NULL to skip retrieving z_L and Z_U
m	(in) the number of constraints \(g(x)\); can be arbitrary if skipping g and lambda
g	(out) buffer to store the constraint values \(g(x)\), must have length at least m; pass NULL to skip retrieving g
lambda	(out) buffer to store the constraint multipliers \(\lambda\), must have length at least m; pass NULL to skip retrieving lambda

Returns

Whether Ipopt has successfully filled the given arrays

Since

3.14.0

GetIpoptCurrentViolations()

IPOPTLIB_EXPORT bool IPOPT_CALLCONV GetIpoptCurrentViolations	(	IpoptProblem	ipopt_problem,
		bool	scaled,
		ipindex	n,
		ipnumber *	x_L_violation,
		ipnumber *	x_U_violation,
		ipnumber *	compl_x_L,
		ipnumber *	compl_x_U,
		ipnumber *	grad_lag_x,
		ipindex	m,
		ipnumber *	nlp_constraint_violation,
		ipnumber *	compl_g
	)

Get primal and dual infeasibility of the current iterate.

This method can be used to get the violations of constraints and optimality conditions at the current iterate during the intermediate callback set by SetIntermediateCallback(). The method expects the number of variables (dimension of x), number of constraints (dimension of g(x)), and allocated arrays of appropriate lengths as input.

The method makes the vectors behind (unscaled_)curr_orig_bounds_violation(), (unscaled_)curr_nlp_constraint_violation(), (unscaled_)curr_dual_infeasibility(), (unscaled_)curr_complementarity() from Ipopt::IpoptCalculatedQuantities of the internal NLP representation available into the form used by the TNLP. If Ipopt is in restoration mode, it maps the current iterate of restoration NLP (see Ipopt::RestoIpoptNLP) back to the original TNLP.

Note

If in restoration phase, then requesting grad_lag_x can trigger a call to Eval_F_CB.

Ipopt by default relaxes variable bounds (option bound_relax_factor > 0.0). x_L_violation and x_U_violation report the violation of a solution w.r.t. the original unrelaxed bounds. However, compl_x_L and compl_x_U use the relaxed variable bounds to calculate the complementarity.

Parameters

ipopt_problem	(in) Problem that is currently optimized.
scaled	(in) whether to retrieve scaled or unscaled violations
n	(in) the number of variables \(x\) in the problem; can be arbitrary if skipping compl_x_L, compl_x_U, and grad_lag_x
x_L_violation	(out) buffer to store violation of original lower bounds on variables (max(orig_x_L-x,0)), must have length at least n; pass NULL to skip retrieving orig_x_L
x_U_violation	(out) buffer to store violation of original upper bounds on variables (max(x-orig_x_U,0)), must have length at least n; pass NULL to skip retrieving orig_x_U
compl_x_L	(out) buffer to store violation of complementarity for lower bounds on variables ( \((x-x_L)z_L\)), must have length at least n; pass NULL to skip retrieving compl_x_L
compl_x_U	(out) buffer to store violation of complementarity for upper bounds on variables ( \((x_U-x)z_U\)), must have length at least n; pass NULL to skip retrieving compl_x_U
grad_lag_x	(out) buffer to store gradient of Lagrangian w.r.t. variables \(x\), must have length at least n; pass NULL to skip retrieving grad_lag_x
m	(in) the number of constraints \(g(x)\); can be arbitrary if skipping lambda
nlp_constraint_violation	(out) buffer to store violation of constraints \(max(g_l-g(x),g(x)-g_u,0)\), must have length at least m; pass NULL to skip retrieving constraint_violation
compl_g	(out) buffer to store violation of complementarity of constraint ( \((g(x)-g_l)*\lambda^+ + (g_l-g(x))*\lambda^-\), where \(\lambda^+=max(0,\lambda)\) and \(\lambda^-=max(0,-\lambda)\) (componentwise)), must have length at least m; pass NULL to skip retrieving compl_g

Returns

Whether Ipopt has successfully filled the given arrays

Since

3.14.0

Variable Documentation

Number

IPOPT_DEPRECATED typedef ipnumber Number

Type for all number.

Deprecated:

Use ipnumber instead.

Definition at line 31 of file IpStdCInterface.h.

Index

IPOPT_DEPRECATED typedef int Index

Type for all indices.

Deprecated:

Use ipindex instead.

Definition at line 37 of file IpStdCInterface.h.

Int

IPOPT_DEPRECATED typedef int Int

Type for all integers.

Deprecated:

Use int instead.

Definition at line 43 of file IpStdCInterface.h.