1 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 2 /* */ 3 /* This file is part of the program and library */ 4 /* SCIP --- Solving Constraint Integer Programs */ 5 /* */ 6 /* Copyright (C) 2002-2021 Konrad-Zuse-Zentrum */ 7 /* fuer Informationstechnik Berlin */ 8 /* */ 9 /* SCIP is distributed under the terms of the ZIB Academic License. */ 10 /* */ 11 /* You should have received a copy of the ZIB Academic License */ 12 /* along with SCIP; see the file COPYING. If not visit scipopt.org. */ 13 /* */ 14 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 15 16 /**@file nlpioracle.h 17 * @brief methods to store an NLP and request function, gradient, and hessian values 18 * @author Stefan Vigerske 19 * 20 * Not a full NLPI, but implements a common part of many NLPIs that takes care 21 * of the problem storage and function, gradient, and hessian evaluation. 22 */ 23 24 #ifndef __SCIP_NLPI_ORACLE_H__ 25 #define __SCIP_NLPI_ORACLE_H__ 26 27 #include "scip/type_message.h" 28 #include "nlpi/type_nlpi.h" 29 #include "nlpi/type_exprinterpret.h" 30 31 32 #ifdef __cplusplus 33 extern "C" { 34 #endif 35 36 typedef struct SCIP_NlpiOracle SCIP_NLPIORACLE; /**< NLPI oracle data structure */ 37 38 /** creates an NLPIORACLE data structure */ 39 SCIP_EXPORT 40 SCIP_RETCODE SCIPnlpiOracleCreate( 41 BMS_BLKMEM* blkmem, /**< block memory */ 42 SCIP_NLPIORACLE** oracle /**< pointer to store NLPIORACLE data structure */ 43 ); 44 45 /** frees an NLPIORACLE data structure */ 46 SCIP_EXPORT 47 SCIP_RETCODE SCIPnlpiOracleFree( 48 SCIP_NLPIORACLE** oracle /**< pointer to NLPIORACLE data structure */ 49 ); 50 51 /** sets the value for infinity */ 52 SCIP_EXPORT 53 SCIP_RETCODE SCIPnlpiOracleSetInfinity( 54 SCIP_NLPIORACLE* oracle, /**< pointer to NLPIORACLE data structure */ 55 SCIP_Real infinity /**< value to use for infinity */ 56 ); 57 58 /** gets the value for infinity */ 59 SCIP_EXPORT 60 SCIP_Real SCIPnlpiOracleGetInfinity( 61 SCIP_NLPIORACLE* oracle /**< pointer to NLPIORACLE data structure */ 62 ); 63 64 /** sets the problem name (used for printing) */ 65 SCIP_EXPORT 66 SCIP_RETCODE SCIPnlpiOracleSetProblemName( 67 SCIP_NLPIORACLE* oracle, /**< pointer to NLPIORACLE data structure */ 68 const char* name /**< name of problem */ 69 ); 70 71 /** gets the problem name, or NULL if none set */ 72 SCIP_EXPORT 73 const char* SCIPnlpiOracleGetProblemName( 74 SCIP_NLPIORACLE* oracle /**< pointer to NLPIORACLE data structure */ 75 ); 76 77 /** adds variables */ 78 SCIP_EXPORT 79 SCIP_RETCODE SCIPnlpiOracleAddVars( 80 SCIP_NLPIORACLE* oracle, /**< pointer to NLPIORACLE data structure */ 81 int nvars, /**< number of variables to add */ 82 const SCIP_Real* lbs, /**< array with lower bounds of new variables, or NULL if all -infinity */ 83 const SCIP_Real* ubs, /**< array with upper bounds of new variables, or NULL if all +infinity */ 84 const char** varnames /**< array with names of new variables, or NULL if no names should be stored */ 85 ); 86 87 /** adds constraints 88 * 89 * linear coefficients: row(=constraint) oriented matrix; 90 * quadratic coefficients: row oriented matrix for each constraint 91 */ 92 SCIP_EXPORT 93 SCIP_RETCODE SCIPnlpiOracleAddConstraints( 94 SCIP_NLPIORACLE* oracle, /**< pointer to NLPIORACLE data structure */ 95 int nconss, /**< number of constraints to add */ 96 const SCIP_Real* lhss, /**< array with left-hand sides of constraints, or NULL if all -infinity */ 97 const SCIP_Real* rhss, /**< array with right-hand sides of constraints, or NULL if all +infinity */ 98 const int* nlininds, /**< number of linear coefficients for each constraint, may be NULL in case of no linear part */ 99 int* const* lininds, /**< indices of variables for linear coefficients for each constraint, may be NULL in case of no linear part */ 100 SCIP_Real* const* linvals, /**< values of linear coefficient for each constraint, may be NULL in case of no linear part */ 101 const int* nquadelems, /**< number of elements in matrix of quadratic part for each constraint, 102 * may be NULL in case of no quadratic part in any constraint */ 103 SCIP_QUADELEM* const* quadelems, /**< quadratic elements specifying quadratic part for each constraint, entry of array may be NULL in case of no quadratic part, 104 * may be NULL in case of no quadratic part in any constraint */ 105 int* const* exprvaridxs, /**< NULL if no nonquadratic parts, otherwise epxrvaridxs[.] maps variable indices in expression tree to indices in nlp */ 106 SCIP_EXPRTREE* const* exprtrees, /**< NULL if no nonquadratic parts, otherwise exprtrees[.] gives nonquadratic part, 107 * or NULL if no nonquadratic part in this constraint */ 108 const char** consnames /**< names of new constraints, or NULL if no names should be stored */ 109 ); 110 111 /** sets or overwrites objective, a minimization problem is expected 112 * 113 * May change sparsity pattern. 114 */ 115 SCIP_EXPORT 116 SCIP_RETCODE SCIPnlpiOracleSetObjective( 117 SCIP_NLPIORACLE* oracle, /**< pointer to NLPIORACLE data structure */ 118 const SCIP_Real constant, /**< constant part of objective */ 119 int nlin, /**< number of linear variable coefficients */ 120 const int* lininds, /**< indices of linear variables, or NULL if no linear part */ 121 const SCIP_Real* linvals, /**< coefficients of linear variables, or NULL if no linear part */ 122 int nquadelems, /**< number of entries in matrix of quadratic part */ 123 const SCIP_QUADELEM* quadelems, /**< entries in matrix of quadratic part, may be NULL in case of no quadratic part */ 124 const int* exprvaridxs, /**< maps variable indices in expression tree to indices in nlp, or NULL if no nonquadratic part */ 125 const SCIP_EXPRTREE* exprtree /**< expression tree of nonquadratic part, or NULL if no nonquadratic part */ 126 ); 127 128 /** change variable bounds */ 129 SCIP_EXPORT 130 SCIP_RETCODE SCIPnlpiOracleChgVarBounds( 131 SCIP_NLPIORACLE* oracle, /**< pointer to NLPIORACLE data structure */ 132 int nvars, /**< number of variables to change bounds */ 133 const int* indices, /**< array with indices of variables to change bounds */ 134 const SCIP_Real* lbs, /**< array with new lower bounds, or NULL if all should be -infty */ 135 const SCIP_Real* ubs /**< array with new upper bounds, or NULL if all should be +infty */ 136 ); 137 138 /** change constraint sides */ 139 SCIP_EXPORT 140 SCIP_RETCODE SCIPnlpiOracleChgConsSides( 141 SCIP_NLPIORACLE* oracle, /**< pointer to NLPIORACLE data structure */ 142 int nconss, /**< number of constraints to change sides */ 143 const int* indices, /**< array with indices of constraints to change sides */ 144 const SCIP_Real* lhss, /**< array with new left-hand sides, or NULL if all should be -infty */ 145 const SCIP_Real* rhss /**< array with new right-hand sides, or NULL if all should be +infty */ 146 ); 147 148 /** deletes a set of variables */ 149 SCIP_EXPORT 150 SCIP_RETCODE SCIPnlpiOracleDelVarSet( 151 SCIP_NLPIORACLE* oracle, /**< pointer to NLPIORACLE data structure */ 152 int* delstats /**< array with deletion status of vars in input (1 if var should be deleted, 0 if not); 153 * new position of var in output (-1 if var was deleted) */ 154 ); 155 156 /** deletes a set of constraints */ 157 SCIP_EXPORT 158 SCIP_RETCODE SCIPnlpiOracleDelConsSet( 159 SCIP_NLPIORACLE* oracle, /**< pointer to NLPIORACLE data structure */ 160 int* delstats /**< array with deletion status of rows in input (1 if row should be deleted, 0 if not); 161 * new position of row in output (-1 if row was deleted) */ 162 ); 163 164 /** changes (or adds) linear coefficients in one constraint or objective */ 165 SCIP_EXPORT 166 SCIP_RETCODE SCIPnlpiOracleChgLinearCoefs( 167 SCIP_NLPIORACLE* oracle, /**< pointer to NLPIORACLE data structure */ 168 int considx, /**< index of constraint where linear coefficients should be changed, or -1 for objective */ 169 int nentries, /**< number of coefficients to change */ 170 const int* varidxs, /**< array with indices of variables which coefficients should be changed */ 171 const SCIP_Real* newcoefs /**< array with new coefficients of variables */ 172 ); 173 174 /** changes (or adds) coefficients in the quadratic part of one constraint or objective */ 175 SCIP_EXPORT 176 SCIP_RETCODE SCIPnlpiOracleChgQuadCoefs( 177 SCIP_NLPIORACLE* oracle, /**< pointer to NLPIORACLE data structure */ 178 int considx, /**< index of constraint where quadratic coefficients should be changed, or -1 for objective */ 179 int nquadelems, /**< number of entries in quadratic constraint to change */ 180 const SCIP_QUADELEM* quadelems /**< new elements in quadratic matrix (replacing already existing ones or adding new ones) */ 181 ); 182 183 /** replaces expression tree of one constraint or objective */ 184 SCIP_EXPORT 185 SCIP_RETCODE SCIPnlpiOracleChgExprtree( 186 SCIP_NLPIORACLE* oracle, /**< pointer to NLPIORACLE data structure */ 187 int considx, /**< index of constraint where expression tree should be changed, or -1 for objective */ 188 const int* exprvaridxs, /**< problem indices of variables in expression tree */ 189 const SCIP_EXPRTREE* exprtree /**< new expression tree, or NULL */ 190 ); 191 192 /** changes one parameter of expression tree of one constraint or objective 193 */ 194 SCIP_EXPORT 195 SCIP_RETCODE SCIPnlpiOracleChgExprParam( 196 SCIP_NLPIORACLE* oracle, /**< pointer to NLPIORACLE data structure */ 197 int considx, /**< index of constraint where parameter should be changed in expression tree, or -1 for objective */ 198 int paramidx, /**< index of parameter */ 199 SCIP_Real paramval /**< new value of parameter */ 200 ); 201 202 /** changes the constant value in the objective function 203 */ 204 SCIP_EXPORT 205 SCIP_RETCODE SCIPnlpiOracleChgObjConstant( 206 SCIP_NLPIORACLE* oracle, /**< pointer to NLPIORACLE data structure */ 207 SCIP_Real objconstant /**< new value for objective constant */ 208 ); 209 210 /** gives the current number of variables */ 211 SCIP_EXPORT 212 int SCIPnlpiOracleGetNVars( 213 SCIP_NLPIORACLE* oracle /**< pointer to NLPIORACLE data structure */ 214 ); 215 216 /** gives the current number of constraints */ 217 SCIP_EXPORT 218 int SCIPnlpiOracleGetNConstraints( 219 SCIP_NLPIORACLE* oracle /**< pointer to NLPIORACLE data structure */ 220 ); 221 222 /** gives the variables lower bounds */ 223 SCIP_EXPORT 224 const SCIP_Real* SCIPnlpiOracleGetVarLbs( 225 SCIP_NLPIORACLE* oracle /**< pointer to NLPIORACLE data structure */ 226 ); 227 228 /** gives the variables upper bounds */ 229 SCIP_EXPORT 230 const SCIP_Real* SCIPnlpiOracleGetVarUbs( 231 SCIP_NLPIORACLE* oracle /**< pointer to NLPIORACLE data structure */ 232 ); 233 234 /** gives the variables names, or NULL if not set */ 235 SCIP_EXPORT 236 char** SCIPnlpiOracleGetVarNames( 237 SCIP_NLPIORACLE* oracle /**< pointer to NLPIORACLE data structure */ 238 ); 239 240 /** Gives maximum degree of a variable w.r.t. objective and all constraints. 241 * The degree of a variable is the degree of the summand where it appears in, and is infinity for nonpolynomial terms. 242 */ 243 SCIP_EXPORT 244 int SCIPnlpiOracleGetVarDegree( 245 SCIP_NLPIORACLE* oracle, /**< pointer to NLPIORACLE data structure */ 246 int varidx /**< the variable for which the degree is returned */ 247 ); 248 249 /** Gives maximum degree of all variables w.r.t. objective and all constraints. 250 * The degree of a variable is the degree of the summand where it appears in, and is infinity for nonpolynomial terms. 251 */ 252 SCIP_EXPORT 253 int* SCIPnlpiOracleGetVarDegrees( 254 SCIP_NLPIORACLE* oracle /**< pointer to NLPIORACLE data structure */ 255 ); 256 257 /** gives left-hand side of a constraint */ 258 SCIP_EXPORT 259 SCIP_Real SCIPnlpiOracleGetConstraintLhs( 260 SCIP_NLPIORACLE* oracle, /**< pointer to NLPIORACLE data structure */ 261 int considx /**< constraint index */ 262 ); 263 264 /** gives right-hand side of a constraint */ 265 SCIP_EXPORT 266 SCIP_Real SCIPnlpiOracleGetConstraintRhs( 267 SCIP_NLPIORACLE* oracle, /**< pointer to NLPIORACLE data structure */ 268 int considx /**< constraint index */ 269 ); 270 271 /** gives name of a constraint, may be NULL */ 272 SCIP_EXPORT 273 char* SCIPnlpiOracleGetConstraintName( 274 SCIP_NLPIORACLE* oracle, /**< pointer to NLPIORACLE data structure */ 275 int considx /**< constraint index */ 276 ); 277 278 /** gives maximum degree of a constraint or objective 279 * The degree is the maximal degree of all summands,, and is infinity for nonpolynomial terms. 280 */ 281 SCIP_EXPORT 282 int SCIPnlpiOracleGetConstraintDegree( 283 SCIP_NLPIORACLE* oracle, /**< pointer to NLPIORACLE data structure */ 284 int considx /**< index of constraint for which the degree is requested, or -1 for objective */ 285 ); 286 287 /** Gives maximum degree over all constraints and the objective (or over all variables, resp.). 288 * Thus, if this function returns 0, then the objective and all constraints are constant. 289 * If it returns 1, then the problem in linear. 290 * If it returns 2, then its a QP, QCP, or QCQP. 291 * And if it returns > 2, then it is an NLP. 292 */ 293 SCIP_EXPORT 294 int SCIPnlpiOracleGetMaxDegree( 295 SCIP_NLPIORACLE* oracle /**< pointer to NLPIORACLE data structure */ 296 ); 297 298 /** Gives the evaluation capabilities that are shared among all expression trees in the problem. */ 299 SCIP_EXPORT 300 SCIP_EXPRINTCAPABILITY SCIPnlpiOracleGetEvalCapability( 301 SCIP_NLPIORACLE* oracle /**< pointer to NLPIORACLE data structure */ 302 ); 303 304 /** evaluates the objective function in a given point */ 305 SCIP_EXPORT 306 SCIP_RETCODE SCIPnlpiOracleEvalObjectiveValue( 307 SCIP_NLPIORACLE* oracle, /**< pointer to NLPIORACLE data structure */ 308 const SCIP_Real* x, /**< point where to evaluate */ 309 SCIP_Real* objval /**< pointer to store objective value */ 310 ); 311 312 /** evaluates one constraint function in a given point */ 313 SCIP_EXPORT 314 SCIP_RETCODE SCIPnlpiOracleEvalConstraintValue( 315 SCIP_NLPIORACLE* oracle, /**< pointer to NLPIORACLE data structure */ 316 int considx, /**< index of constraint to evaluate */ 317 const SCIP_Real* x, /**< point where to evaluate */ 318 SCIP_Real* conval /**< pointer to store constraint value */ 319 ); 320 321 /** evaluates all constraint functions in a given point */ 322 SCIP_EXPORT 323 SCIP_RETCODE SCIPnlpiOracleEvalConstraintValues( 324 SCIP_NLPIORACLE* oracle, /**< pointer to NLPIORACLE data structure */ 325 const SCIP_Real* x, /**< point where to evaluate */ 326 SCIP_Real* convals /**< pointer to store constraint values */ 327 ); 328 329 /** computes the objective gradient in a given point 330 * 331 * @return SCIP_INVALIDDATA, if the function or its gradient could not be evaluated (domain error, etc.) 332 */ 333 SCIP_EXPORT 334 SCIP_RETCODE SCIPnlpiOracleEvalObjectiveGradient( 335 SCIP_NLPIORACLE* oracle, /**< pointer to NLPIORACLE data structure */ 336 const SCIP_Real* x, /**< point where to evaluate */ 337 SCIP_Bool isnewx, /**< has the point x changed since the last call to some evaluation function? */ 338 SCIP_Real* objval, /**< pointer to buffer objective value */ 339 SCIP_Real* objgrad /**< pointer to buffer (dense) objective gradient */ 340 ); 341 342 /** computes a constraints gradient in a given point 343 * 344 * @return SCIP_INVALIDDATA, if the function or its gradient could not be evaluated (domain error, etc.) 345 */ 346 SCIP_EXPORT 347 SCIP_RETCODE SCIPnlpiOracleEvalConstraintGradient( 348 SCIP_NLPIORACLE* oracle, /**< pointer to NLPIORACLE data structure */ 349 const int considx, /**< index of constraint to compute gradient for */ 350 const SCIP_Real* x, /**< point where to evaluate */ 351 SCIP_Bool isnewx, /**< has the point x changed since the last call to some evaluation function? */ 352 SCIP_Real* conval, /**< pointer to store constraint value */ 353 SCIP_Real* congrad /**< pointer to store (dense) constraint gradient */ 354 ); 355 356 /** gets sparsity pattern (rowwise) of Jacobian matrix 357 * 358 * Note that internal data is returned in *offset and *col, thus the user does not need to allocate memory there. 359 * Adding or deleting constraints destroys the sparsity structure and make another call to this function necessary. 360 */ 361 SCIP_EXPORT 362 SCIP_RETCODE SCIPnlpiOracleGetJacobianSparsity( 363 SCIP_NLPIORACLE* oracle, /**< pointer to NLPIORACLE data structure */ 364 const int** offset, /**< pointer to store pointer that stores the offsets to each rows sparsity pattern in col, can be NULL */ 365 const int** col /**< pointer to store pointer that stores the indices of variables that appear in each row, 366 * offsets[nconss] gives length of col, can be NULL */ 367 ); 368 369 /** evaluates the Jacobi matrix in a given point 370 * 371 * The values in the Jacobi matrix are returned in the same order as specified by the offset and col arrays obtained by SCIPnlpiOracleGetJacobianSparsity. 372 * The user need to call SCIPnlpiOracleGetJacobianSparsity at least ones before using this function. 373 * 374 * @return SCIP_INVALIDDATA, if the Jacobian could not be evaluated (domain error, etc.) 375 */ 376 SCIP_EXPORT 377 SCIP_RETCODE SCIPnlpiOracleEvalJacobian( 378 SCIP_NLPIORACLE* oracle, /**< pointer to NLPIORACLE data structure */ 379 const SCIP_Real* x, /**< point where to evaluate */ 380 SCIP_Bool isnewx, /**< has the point x changed since the last call to some evaluation function? */ 381 SCIP_Real* convals, /**< pointer to store constraint values, can be NULL */ 382 SCIP_Real* jacobi /**< pointer to store sparse jacobian values */ 383 ); 384 385 /** gets sparsity pattern of the Hessian matrix of the Lagrangian 386 * 387 * Note that internal data is returned in *offset and *col, thus the user must not to allocate memory there. 388 * Adding or deleting variables, objective, or constraints may destroy the sparsity structure and make another call to this function necessary. 389 * Only elements of the lower left triangle and the diagonal are counted. 390 */ 391 SCIP_EXPORT 392 SCIP_RETCODE SCIPnlpiOracleGetHessianLagSparsity( 393 SCIP_NLPIORACLE* oracle, /**< pointer to NLPIORACLE data structure */ 394 const int** offset, /**< pointer to store pointer that stores the offsets to each rows sparsity pattern in col, can be NULL */ 395 const int** col /**< pointer to store pointer that stores the indices of variables that appear in each row, 396 * offsets[nconss] gives length of col, can be NULL */ 397 ); 398 399 /** evaluates the Hessian matrix of the Lagrangian in a given point 400 * 401 * The values in the Hessian matrix are returned in the same order as specified by the offset and col arrays obtained by SCIPnlpiOracleGetHessianLagSparsity. 402 * The user must call SCIPnlpiOracleGetHessianLagSparsity at least ones before using this function. 403 * Only elements of the lower left triangle and the diagonal are computed. 404 * 405 * @return SCIP_INVALIDDATA, if the Hessian could not be evaluated (domain error, etc.) 406 */ 407 SCIP_EXPORT 408 SCIP_RETCODE SCIPnlpiOracleEvalHessianLag( 409 SCIP_NLPIORACLE* oracle, /**< pointer to NLPIORACLE data structure */ 410 const SCIP_Real* x, /**< point where to evaluate */ 411 SCIP_Bool isnewx, /**< has the point x changed since the last call to some evaluation function? */ 412 SCIP_Real objfactor, /**< weight for objective function */ 413 const SCIP_Real* lambdas, /**< array with weights (Lagrangian multipliers) for the constraints */ 414 SCIP_Real* hessian /**< pointer to store sparse hessian values */ 415 ); 416 417 /** prints the problem to a file. */ 418 SCIP_EXPORT 419 SCIP_RETCODE SCIPnlpiOraclePrintProblem( 420 SCIP_NLPIORACLE* oracle, /**< pointer to NLPIORACLE data structure */ 421 SCIP_MESSAGEHDLR* messagehdlr, /**< message handler */ 422 FILE* file /**< file to print to, or NULL for standard output */ 423 ); 424 425 /** prints the problem to a file in GAMS format 426 * If there are variable (equation, resp.) names with more than 9 characters, then variable (equation, resp.) names are prefixed with an unique identifier. 427 * This is to make it easier to identify variables solution output in the listing file. 428 * Names with more than 64 characters are shorten to 64 letters due to GAMS limits. 429 */ 430 SCIP_EXPORT 431 SCIP_RETCODE SCIPnlpiOraclePrintProblemGams( 432 SCIP_NLPIORACLE* oracle, /**< pointer to NLPIORACLE data structure */ 433 SCIP_Real* initval, /**< starting point values for variables or NULL */ 434 SCIP_MESSAGEHDLR* messagehdlr, /**< message handler */ 435 FILE* file /**< file to print to, or NULL for standard output */ 436 ); 437 438 #ifdef __cplusplus 439 } 440 #endif 441 442 #endif 443