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   scip_nlpi.h
26   	 * @ingroup PUBLICCOREAPI
27   	 * @brief  public methods for NLPI solver interfaces
28   	 * @author Stefan Vigerske
29   	 * @author Thorsten Gellermann
30   	 */
31   	
32   	/*---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
33   	
34   	#ifndef __SCIP_SCIP_NLPI_H__
35   	#define __SCIP_SCIP_NLPI_H__
36   	
37   	#include "scip/type_nlpi.h"
38   	#include "scip/type_misc.h"
39   	#include "scip/type_lp.h"
40   	#include "blockmemshell/memory.h"
41   	#include "scip/pub_nlpi.h"
42   	
43   	#ifdef __cplusplus
44   	extern "C" {
45   	#endif
46   	
47   	/**@addtogroup PublicNLPIInterfaceMethods
48   	 *
49   	 * @{
50   	 */
51   	
52   	/** creates an NLPI and includes it into SCIP */
53   	SCIP_EXPORT
54   	SCIP_RETCODE SCIPincludeNlpi(
55   	   SCIP*                           scip,                        /**< SCIP data structure */
56   	   const char*                     name,                        /**< name of NLP interface */
57   	   const char*                     description,                 /**< description of NLP interface */
58   	   int                             priority,                    /**< priority of NLP interface */
59   	   SCIP_DECL_NLPICOPY              ((*nlpicopy)),               /**< copying an NLPI, can be NULL */
60   	   SCIP_DECL_NLPIFREE              ((*nlpifree)),               /**< free NLPI user data */
61   	   SCIP_DECL_NLPIGETSOLVERPOINTER  ((*nlpigetsolverpointer)),   /**< get solver pointer, can be NULL */
62   	   SCIP_DECL_NLPICREATEPROBLEM     ((*nlpicreateproblem)),      /**< create a new problem instance */
63   	   SCIP_DECL_NLPIFREEPROBLEM       ((*nlpifreeproblem)),        /**< free a problem instance */
64   	   SCIP_DECL_NLPIGETPROBLEMPOINTER ((*nlpigetproblempointer)),  /**< get problem pointer, can be NULL */
65   	   SCIP_DECL_NLPIADDVARS           ((*nlpiaddvars)),            /**< add variables */
66   	   SCIP_DECL_NLPIADDCONSTRAINTS    ((*nlpiaddconstraints)),     /**< add constraints */
67   	   SCIP_DECL_NLPISETOBJECTIVE      ((*nlpisetobjective)),       /**< set objective */
68   	   SCIP_DECL_NLPICHGVARBOUNDS      ((*nlpichgvarbounds)),       /**< change variable bounds */
69   	   SCIP_DECL_NLPICHGCONSSIDES      ((*nlpichgconssides)),       /**< change constraint sides */
70   	   SCIP_DECL_NLPIDELVARSET         ((*nlpidelvarset)),          /**< delete a set of constraints */
71   	   SCIP_DECL_NLPIDELCONSSET        ((*nlpidelconsset)),         /**< delete a set of constraints */
72   	   SCIP_DECL_NLPICHGLINEARCOEFS    ((*nlpichglinearcoefs)),     /**< change coefficients in linear part of a constraint or objective */
73   	   SCIP_DECL_NLPICHGEXPR           ((*nlpichgexpr)),            /**< change nonlinear expression a constraint or objective */
74   	   SCIP_DECL_NLPICHGOBJCONSTANT    ((*nlpichgobjconstant)),     /**< change the constant offset in the objective */
75   	   SCIP_DECL_NLPISETINITIALGUESS   ((*nlpisetinitialguess)),    /**< set initial guess, can be NULL */
76   	   SCIP_DECL_NLPISOLVE             ((*nlpisolve)),              /**< solve NLP */
77   	   SCIP_DECL_NLPIGETSOLSTAT        ((*nlpigetsolstat)),         /**< get solution status */
78   	   SCIP_DECL_NLPIGETTERMSTAT       ((*nlpigettermstat)),        /**< get termination status */
79   	   SCIP_DECL_NLPIGETSOLUTION       ((*nlpigetsolution)),        /**< get solution */
80   	   SCIP_DECL_NLPIGETSTATISTICS     ((*nlpigetstatistics)),      /**< get solve statistics */
81   	   SCIP_NLPIDATA*                  nlpidata                     /**< NLP interface local data */
82   	   );
83   	
84   	/** returns the NLPI of the given name, or NULL if not existing */
85   	SCIP_EXPORT
86   	SCIP_NLPI* SCIPfindNlpi(
87   	   SCIP*                 scip,               /**< SCIP data structure */
88   	   const char*           name                /**< name of NLPI */
89   	   );
90   	
91   	/** returns the array of currently available NLPIs (sorted by priority) */
92   	SCIP_EXPORT
93   	SCIP_NLPI** SCIPgetNlpis(
94   	   SCIP*                 scip                /**< SCIP data structure */
95   	   );
96   	
97   	/** returns the number of currently available NLPIs */
98   	SCIP_EXPORT
99   	int SCIPgetNNlpis(
100  	   SCIP*                 scip                /**< SCIP data structure */
101  	   );
102  	
103  	/** sets the priority of an NLPI */
104  	SCIP_EXPORT
105  	SCIP_RETCODE SCIPsetNlpiPriority(
106  	   SCIP*                 scip,               /**< SCIP data structure */
107  	   SCIP_NLPI*            nlpi,               /**< NLPI */
108  	   int                   priority            /**< new priority of the NLPI */
109  	   );
110  	
111  	/** gets internal pointer to NLP solver
112  	 *
113  	 * Depending on the solver interface, a solver pointer may exist for every NLP problem instance.
114  	 * For this case, a NLPI problem can be passed in as well.
115  	 */
116  	SCIP_EXPORT
117  	SCIP_DECL_NLPIGETSOLVERPOINTER(SCIPgetNlpiSolverPointer);
118  	
119  	/** creates an empty problem instance */
120  	SCIP_EXPORT
121  	SCIP_DECL_NLPICREATEPROBLEM(SCIPcreateNlpiProblem);
122  	
123  	/** frees a problem instance */
124  	SCIP_EXPORT
125  	SCIP_DECL_NLPIFREEPROBLEM(SCIPfreeNlpiProblem);
126  	
127  	/** gets internal pointer to solver-internal problem instance */
128  	SCIP_EXPORT
129  	SCIP_DECL_NLPIGETPROBLEMPOINTER(SCIPgetNlpiProblemPointer);
130  	
131  	/** add variables to nlpi */
132  	SCIP_EXPORT
133  	SCIP_DECL_NLPIADDVARS(SCIPaddNlpiVars);
134  	
135  	/** add constraints to nlpi */
136  	SCIP_EXPORT
137  	SCIP_DECL_NLPIADDCONSTRAINTS(SCIPaddNlpiConstraints);
138  	
139  	/** sets or overwrites objective, a minimization problem is expected */
140  	SCIP_EXPORT
141  	SCIP_DECL_NLPISETOBJECTIVE(SCIPsetNlpiObjective);
142  	
143  	/** change variable bounds */
144  	SCIP_EXPORT
145  	SCIP_DECL_NLPICHGVARBOUNDS(SCIPchgNlpiVarBounds);
146  	
147  	/** change constraint sides */
148  	SCIP_EXPORT
149  	SCIP_DECL_NLPICHGCONSSIDES(SCIPchgNlpiConsSides);
150  	
151  	/** delete a set of variables */
152  	SCIP_EXPORT
153  	SCIP_DECL_NLPIDELVARSET(SCIPdelNlpiVarSet);
154  	
155  	/** delete a set of constraints */
156  	SCIP_EXPORT
157  	SCIP_DECL_NLPIDELCONSSET(SCIPdelNlpiConsSet);
158  	
159  	/** changes or adds linear coefficients in a constraint or objective */
160  	SCIP_EXPORT
161  	SCIP_DECL_NLPICHGLINEARCOEFS(SCIPchgNlpiLinearCoefs);
162  	
163  	/** change the expression in the nonlinear part */
164  	SCIP_EXPORT
165  	SCIP_DECL_NLPICHGEXPR(SCIPchgNlpiExpr);
166  	
167  	/** change the constant offset in the objective */
168  	SCIP_EXPORT
169  	SCIP_DECL_NLPICHGOBJCONSTANT(SCIPchgNlpiObjConstant);
170  	
171  	/** sets initial guess */
172  	SCIP_EXPORT
173  	SCIP_DECL_NLPISETINITIALGUESS(SCIPsetNlpiInitialGuess);
174  	
175  	/** try to solve NLP with all parameters given as SCIP_NLPPARAM struct
176  	 *
177  	 * Typical use is
178  	 *
179  	 *     SCIP_NLPPARAM nlparam = { SCIP_NLPPARAM_DEFAULT(scip); }
180  	 *     nlpparam.iterlimit = 42;
181  	 *     SCIP_CALL( SCIPsolveNlpiParam(scip, nlpi, nlpiproblem, nlpparam) );
182  	 *
183  	 * or, in "one" line:
184  	 *
185  	 *     SCIP_CALL( SCIPsolveNlpiParam(scip, nlpi, nlpiproblem,
186  	 *        (SCIP_NLPPARAM){ SCIP_NLPPARAM_DEFAULT(scip), .iterlimit = 42 }) );
187  	 *
188  	 * To get the latter, also \ref SCIPsolveNlpi can be used.
189  	 */
190  	SCIP_EXPORT
191  	SCIP_DECL_NLPISOLVE(SCIPsolveNlpiParam);
192  	
193  	/** try to solve NLP with non-default parameters given as optional arguments
194  	 *
195  	 * Typical use is
196  	 *
197  	 *     SCIP_CALL( SCIPsolveNlpi(scip, nlpi, nlpiproblem) );
198  	 *
199  	 * to solve with default parameters.
200  	 * Additionally, one or several values of SCIP_NLPPARAM can be set:
201  	 *
202  	 *     SCIP_CALL( SCIPsolveNlpi(scip, nlpi, nlpiproblem, .iterlimit = 42, .verblevel = 1) );  //lint !e666
203  	 */
204  	/* the problem argument has been made part of the variadic arguments, since ISO C99 requires at least one argument for the "..." part and we want to allow leaving all parameters at default
205  	 * for the same reason, we set the .caller argument, so that macro SCIP_VARARGS_REST will have at least one arg to return
206  	 */
207  	#if !defined(_MSC_VER) || _MSC_VER >= 1800
208  	#define SCIPsolveNlpi(scip, nlpi, ...) \
209  	   SCIPsolveNlpiParam(scip, nlpi, SCIP_VARARGS_FIRST((__VA_ARGS__, ignored)), \
210  	      (SCIP_NLPPARAM){ SCIP_NLPPARAM_DEFAULT_INITS(scip), SCIP_VARARGS_REST(__VA_ARGS__, .caller = __FILE__) })
211  	#else
212  	/* very old MSVC doesn't support C99's designated initializers, so have a version of SCIPsolveNlpi() that just ignores given parameters
213  	 * (compilation of scip_nlpi.c will print a warning)
214  	 */
215  	#define SCIPsolveNlpi(scip, nlpi, ...) \
216  	    SCIPsolveNlpiParam(scip, nlpi, SCIP_VARARGS_FIRST((__VA_ARGS__, ignored)), SCIP_NLPPARAM_DEFAULT_STATIC)
217  	#endif
218  	
219  	/** gives solution status */
220  	SCIP_EXPORT
221  	SCIP_DECL_NLPIGETSOLSTAT(SCIPgetNlpiSolstat);
222  	
223  	/** gives termination reason */
224  	SCIP_EXPORT
225  	SCIP_DECL_NLPIGETTERMSTAT(SCIPgetNlpiTermstat);
226  	
227  	/** gives primal and dual solution
228  	 * for a ranged constraint, the dual variable is positive if the right hand side is active and negative if the left hand side is active
229  	 */
230  	SCIP_EXPORT
231  	SCIP_DECL_NLPIGETSOLUTION(SCIPgetNlpiSolution);
232  	
233  	/** gives solve statistics */
234  	SCIP_EXPORT
235  	SCIP_DECL_NLPIGETSTATISTICS(SCIPgetNlpiStatistics);
236  	
237  	
238  	/**@name Convenience methods to setup and update an NLPI problem using NLROWS
239  	 *
240  	 * These methods can be used, for example, to create a NLPI problem that contains only the convex rows of the SCIP NLP relaxation.
241  	 * @{
242  	 */
243  	
244  	/** creates a NLPI problem from given nonlinear rows
245  	 *
246  	 * The function computes for each variable the number of non-linear occurrences and stores it in the nlscore array.
247  	 *
248  	 * @note the first row corresponds always to the cutoff row (even if cutoffbound is SCIPinfinity(scip))
249  	 **/
250  	SCIP_EXPORT
251  	SCIP_RETCODE SCIPcreateNlpiProblemFromNlRows(
252  	   SCIP*                 scip,               /**< SCIP data structure */
253  	   SCIP_NLPI*            nlpi,               /**< interface to NLP solver */
254  	   SCIP_NLPIPROBLEM**    nlpiprob,           /**< buffer to store pointer to created nlpi problem */
255  	   const char*           name,               /**< name to give to problem */
256  	   SCIP_NLROW**          nlrows,             /**< nonlinear rows */
257  	   int                   nnlrows,            /**< number of nonlinear rows */
258  	   SCIP_HASHMAP*         var2idx,            /**< empty hash map to store mapping between variables and indices in nlpiprob */
259  	   SCIP_HASHMAP*         nlrow2idx,          /**< empty hash map to store mapping between variables and indices in nlpiprob, can be NULL */
260  	   SCIP_Real*            nlscore,            /**< array to store the score of each nonlinear variable (NULL if not needed) */
261  	   SCIP_Real             cutoffbound,        /**< cutoff bound */
262  	   SCIP_Bool             setobj,             /**< whether the objective function should be set to one of the SCIP problem */
263  	   SCIP_Bool             onlyconvex          /**< filter only for convex constraints */
264  	   );
265  	
266  	/** updates variable bounds and the cutoff row in a NLPI problem
267  	 *
268  	 * The NLPI problem must have been setup by SCIPcreateNlpiProblemFromNlRows().
269  	 */
270  	SCIP_EXPORT
271  	SCIP_RETCODE SCIPupdateNlpiProblem(
272  	   SCIP*                 scip,               /**< SCIP data structure */
273  	   SCIP_NLPI*            nlpi,               /**< interface to NLP solver */
274  	   SCIP_NLPIPROBLEM*     nlpiprob,           /**< nlpi problem representing the convex NLP relaxation */
275  	   SCIP_HASHMAP*         var2nlpiidx,        /**< mapping between variables and nlpi indices */
276  	   SCIP_VAR**            nlpivars,           /**< array containing all variables of the nlpi */
277  	   int                   nlpinvars,          /**< total number of nlpi variables */
278  	   SCIP_Real             cutoffbound         /**< new cutoff bound */
279  	   );
280  	
281  	/** adds SCIP_ROWs to a NLPI problem */
282  	SCIP_EXPORT
283  	SCIP_RETCODE SCIPaddNlpiProblemRows(
284  	   SCIP*                 scip,               /**< SCIP data structure */
285  	   SCIP_NLPI*            nlpi,               /**< interface to NLP solver */
286  	   SCIP_NLPIPROBLEM*     nlpiprob,           /**< nlpi problem */
287  	   SCIP_HASHMAP*         var2idx,            /**< empty hash map to store mapping between variables and indices in nlpiprob */
288  	   SCIP_ROW**            rows,               /**< rows to add */
289  	   int                   nrows               /**< number of rows to add */
290  	   );
291  	
292  	/** adds SCIP_NLROWs to a NLPI problem */
293  	SCIP_EXPORT
294  	SCIP_RETCODE SCIPaddNlpiProblemNlRows(
295  	   SCIP*                 scip,               /**< SCIP data structure */
296  	   SCIP_NLPI*            nlpi,               /**< interface to NLP solver */
297  	   SCIP_NLPIPROBLEM*     nlpiprob,           /**< nlpi problem */
298  	   SCIP_HASHMAP*         var2idx,            /**< empty hash map to store mapping between variables and indices in nlpiprob */
299  	   SCIP_NLROW**          nlrows,             /**< rows to add */
300  	   int                   nnlrows             /**< number of rows to add */
301  	   );
302  	
303  	/** @} */
304  	
305  	/** @} */
306  	
307  	#ifdef __cplusplus
308  	}
309  	#endif
310  	
311  	#endif /* __SCIP_SCIP_NLPI_H__ */
312