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