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   nlpi.h
26   	 * @ingroup INTERNALAPI
27   	 * @brief  internal methods for NLP 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_NLPI_H__
35   	#define __SCIP_NLPI_H__
36   	
37   	#include "scip/type_nlpi.h"
38   	#include "scip/type_misc.h"
39   	#include "scip/type_set.h"
40   	#include "scip/type_stat.h"
41   	#include "blockmemshell/memory.h"
42   	
43   	#ifdef __cplusplus
44   	extern "C" {
45   	#endif
46   	
47   	/** creates an NLP solver interface */
48   	SCIP_RETCODE SCIPnlpiCreate(
49   	   SCIP_NLPI**                     nlpi,                        /**< pointer to NLP interface data structure */
50   	   const char*                     name,                        /**< name of NLP interface */
51   	   const char*                     description,                 /**< description of NLP interface */
52   	   int                             priority,                    /**< priority of NLP interface */
53   	   SCIP_DECL_NLPICOPY              ((*nlpicopy)),               /**< copying of NLPI, can be NULL */
54   	   SCIP_DECL_NLPIFREE              ((*nlpifree)),               /**< free NLPI user data */
55   	   SCIP_DECL_NLPIGETSOLVERPOINTER  ((*nlpigetsolverpointer)),   /**< get solver pointer, can be NULL */
56   	   SCIP_DECL_NLPICREATEPROBLEM     ((*nlpicreateproblem)),      /**< create a new problem instance */
57   	   SCIP_DECL_NLPIFREEPROBLEM       ((*nlpifreeproblem)),        /**< free a problem instance */
58   	   SCIP_DECL_NLPIGETPROBLEMPOINTER ((*nlpigetproblempointer)),  /**< get problem pointer, can be NULL */
59   	   SCIP_DECL_NLPIADDVARS           ((*nlpiaddvars)),            /**< add variables */
60   	   SCIP_DECL_NLPIADDCONSTRAINTS    ((*nlpiaddconstraints)),     /**< add constraints */
61   	   SCIP_DECL_NLPISETOBJECTIVE      ((*nlpisetobjective)),       /**< set objective */
62   	   SCIP_DECL_NLPICHGVARBOUNDS      ((*nlpichgvarbounds)),       /**< change variable bounds */
63   	   SCIP_DECL_NLPICHGCONSSIDES      ((*nlpichgconssides)),       /**< change constraint sides */
64   	   SCIP_DECL_NLPIDELVARSET         ((*nlpidelvarset)),          /**< delete a set of constraints */
65   	   SCIP_DECL_NLPIDELCONSSET        ((*nlpidelconsset)),         /**< delete a set of constraints */
66   	   SCIP_DECL_NLPICHGLINEARCOEFS    ((*nlpichglinearcoefs)),     /**< change coefficients in linear part of a constraint or objective */
67   	   SCIP_DECL_NLPICHGEXPR           ((*nlpichgexpr)),            /**< change nonlinear expression a constraint or objective */
68   	   SCIP_DECL_NLPICHGOBJCONSTANT    ((*nlpichgobjconstant)),     /**< change the constant offset in the objective */
69   	   SCIP_DECL_NLPISETINITIALGUESS   ((*nlpisetinitialguess)),    /**< set initial guess, can be NULL */
70   	   SCIP_DECL_NLPISOLVE             ((*nlpisolve)),              /**< solve NLP */
71   	   SCIP_DECL_NLPIGETSOLSTAT        ((*nlpigetsolstat)),         /**< get solution status */
72   	   SCIP_DECL_NLPIGETTERMSTAT       ((*nlpigettermstat)),        /**< get termination status */
73   	   SCIP_DECL_NLPIGETSOLUTION       ((*nlpigetsolution)),        /**< get solution */
74   	   SCIP_DECL_NLPIGETSTATISTICS     ((*nlpigetstatistics)),      /**< get solve statistics */
75   	   SCIP_NLPIDATA*                  nlpidata                     /**< NLP interface local data */
76   	   );
77   	
78   	/** sets NLP solver priority */
79   	void SCIPnlpiSetPriority(
80   	   SCIP_NLPI*            nlpi,               /**< NLP interface structure */
81   	   int                   priority            /**< new priority of NLPI */
82   	   );
83   	
84   	/** copies an NLPI and includes it into another SCIP instance */
85   	SCIP_RETCODE SCIPnlpiCopyInclude(
86   	   SCIP_NLPI*            sourcenlpi,         /**< the NLP interface to copy */
87   	   SCIP_SET*             targetset           /**< global SCIP settings where to include copy */
88   	   );
89   	
90   	/** frees NLPI */
91   	SCIP_RETCODE SCIPnlpiFree(
92   	   SCIP_NLPI**           nlpi,               /**< pointer to NLPI data structure */
93   	   SCIP_SET*             set                 /**< global SCIP settings */
94   	   );
95   	
96   	/** initializes NLPI */
97   	void SCIPnlpiInit(
98   	   SCIP_NLPI*            nlpi                /**< solver interface */
99   	   );
100  	
101  	/** gets pointer for NLP solver */
102  	void* SCIPnlpiGetSolverPointer(
103  	   SCIP_SET*             set,                /**< global SCIP settings */
104  	   SCIP_NLPI*            nlpi,               /**< solver interface */
105  	   SCIP_NLPIPROBLEM*     problem             /**< problem instance, or NULL */
106  	   );
107  	
108  	/** creates a problem instance */
109  	SCIP_RETCODE SCIPnlpiCreateProblem(
110  	   SCIP_SET*             set,                /**< global SCIP settings */
111  	   SCIP_NLPI*            nlpi,               /**< solver interface */
112  	   SCIP_NLPIPROBLEM**    problem,            /**< problem pointer to store the problem data */
113  	   const char*           name                /**< name of problem, can be NULL */
114  	   );
115  	
116  	/** frees a problem instance */
117  	SCIP_RETCODE SCIPnlpiFreeProblem(
118  	   SCIP_SET*             set,                /**< global SCIP settings */
119  	   SCIP_NLPI*            nlpi,               /**< solver interface */
120  	   SCIP_NLPIPROBLEM**    problem             /**< pointer where problem instance is stored */
121  	   );
122  	
123  	/** gets pointer to solver-internal problem instance */
124  	void* SCIPnlpiGetProblemPointer(
125  	   SCIP_SET*             set,                /**< global SCIP settings */
126  	   SCIP_NLPI*            nlpi,               /**< solver interface */
127  	   SCIP_NLPIPROBLEM*     problem             /**< problem instance */
128  	   );
129  	
130  	/** add variables to nlpi */
131  	SCIP_RETCODE SCIPnlpiAddVars(
132  	   SCIP_SET*             set,                /**< global SCIP settings */
133  	   SCIP_NLPI*            nlpi,               /**< solver interface */
134  	   SCIP_NLPIPROBLEM*     problem,            /**< problem instance */
135  	   int                   nvars,              /**< number of variables */
136  	   const SCIP_Real*      lbs,                /**< lower bounds of variables, can be NULL if -infinity */
137  	   const SCIP_Real*      ubs,                /**< upper bounds of variables, can be NULL if +infinity */
138  	   const char**          varnames            /**< names of variables, can be NULL */
139  	   );
140  	
141  	/** add constraints to nlpi */
142  	SCIP_RETCODE SCIPnlpiAddConstraints(
143  	   SCIP_SET*             set,                /**< global SCIP settings */
144  	   SCIP_NLPI*            nlpi,               /**< solver interface */
145  	   SCIP_NLPIPROBLEM*     problem,            /**< problem instance */
146  	   int                   nconss,             /**< number of constraints */
147  	   const SCIP_Real*      lhss,               /**< left hand sides of constraints, can be NULL if -infinity */
148  	   const SCIP_Real*      rhss,               /**< right hand sides of constraints, can be NULL if +infinity */
149  	   const int*            nlininds,           /**< number of linear coefficients for each constraint, may be NULL in case of no linear part */
150  	   int* const*           lininds,            /**< indices of variables for linear coefficients for each constraint, may be NULL in case of no linear part */
151  	   SCIP_Real* const*     linvals,            /**< values of linear coefficient for each constraint, may be NULL in case of no linear part */
152  	   SCIP_EXPR**           exprs,              /**< expressions for nonlinear part of constraints, entry of array may be NULL in case of no nonlinear part, may be NULL in case of no nonlinear part in any constraint */
153  	   const char**          names               /**< names of constraints, may be NULL or entries may be NULL */
154  	   );
155  	
156  	/** sets or overwrites objective, a minimization problem is expected */
157  	SCIP_RETCODE SCIPnlpiSetObjective(
158  	   SCIP_SET*             set,                /**< global SCIP settings */
159  	   SCIP_NLPI*            nlpi,               /**< solver interface */
160  	   SCIP_NLPIPROBLEM*     problem,            /**< problem instance */
161  	   int                   nlins,              /**< number of linear variables */
162  	   const int*            lininds,            /**< variable indices, may be NULL in case of no linear part */
163  	   const SCIP_Real*      linvals,            /**< coefficient values, may be NULL in case of no linear part */
164  	   SCIP_EXPR*            expr,               /**< expression for nonlinear part of objective function, may be NULL in case of no nonlinear part */
165  	   const SCIP_Real       constant            /**< objective value offset */
166  	   );
167  	
168  	/** change variable bounds */
169  	SCIP_RETCODE SCIPnlpiChgVarBounds(
170  	   SCIP_SET*             set,                /**< global SCIP settings */
171  	   SCIP_NLPI*            nlpi,               /**< solver interface */
172  	   SCIP_NLPIPROBLEM*     problem,            /**< problem instance */
173  	   const int             nvars,              /**< number of variables to change bounds */
174  	   const int*            indices,            /**< indices of variables to change bounds */
175  	   const SCIP_Real*      lbs,                /**< new lower bounds */
176  	   const SCIP_Real*      ubs                 /**< new upper bounds */
177  	   );
178  	
179  	/** change constraint sides */
180  	SCIP_RETCODE SCIPnlpiChgConsSides(
181  	   SCIP_SET*             set,                /**< global SCIP settings */
182  	   SCIP_NLPI*            nlpi,               /**< solver interface */
183  	   SCIP_NLPIPROBLEM*     problem,            /**< problem instance */
184  	   int                   nconss,             /**< number of constraints to change sides */
185  	   const int*            indices,            /**< indices of constraints to change sides */
186  	   const SCIP_Real*      lhss,               /**< new left hand sides */
187  	   const SCIP_Real*      rhss                /**< new right hand sides */
188  	   );
189  	
190  	/** delete a set of variables */
191  	SCIP_RETCODE SCIPnlpiDelVarSet(
192  	   SCIP_SET*             set,                /**< global SCIP settings */
193  	   SCIP_NLPI*            nlpi,               /**< solver interface */
194  	   SCIP_NLPIPROBLEM*     problem,            /**< problem instance */
195  	   int*                  dstats,             /**< deletion status of vars; 1 if var should be deleted, 0 if not */
196  	   int                   dstatssize          /**< size of the dstats array */
197  	   );
198  	
199  	/** delete a set of constraints */
200  	SCIP_RETCODE SCIPnlpiDelConsSet(
201  	   SCIP_SET*             set,                /**< global SCIP settings */
202  	   SCIP_NLPI*            nlpi,               /**< solver interface */
203  	   SCIP_NLPIPROBLEM*     problem,            /**< problem instance */
204  	   int*                  dstats,             /**< deletion status of constraints; 1 if constraint should be deleted, 0 if not */
205  	   int                   dstatssize          /**< size of the dstats array */
206  	   );
207  	
208  	/** changes or adds linear coefficients in a constraint or objective */
209  	SCIP_RETCODE SCIPnlpiChgLinearCoefs(
210  	   SCIP_SET*             set,                /**< global SCIP settings */
211  	   SCIP_NLPI*            nlpi,               /**< solver interface */
212  	   SCIP_NLPIPROBLEM*     problem,            /**< problem instance */
213  	   int                   idx,                /**< index of constraint or -1 for objective */
214  	   int                   nvals,              /**< number of values in linear constraint to change */
215  	   const int*            varidxs,            /**< indices of variables which coefficient to change */
216  	   const SCIP_Real*      vals                /**< new values for coefficients */
217  	   );
218  	
219  	/** change the expression in the nonlinear part */
220  	SCIP_RETCODE SCIPnlpiChgExpr(
221  	   SCIP_SET*             set,                /**< global SCIP settings */
222  	   SCIP_NLPI*            nlpi,               /**< solver interface */
223  	   SCIP_NLPIPROBLEM*     problem,            /**< problem instance */
224  	   int                   idxcons,            /**< index of constraint or -1 for objective */
225  	   SCIP_EXPR*            expr                /**< new expression for constraint or objective, or NULL to only remove previous tree */
226  	   );
227  	
228  	/** change the constant offset in the objective */
229  	SCIP_RETCODE SCIPnlpiChgObjConstant(
230  	   SCIP_SET*             set,                /**< global SCIP settings */
231  	   SCIP_NLPI*            nlpi,               /**< solver interface */
232  	   SCIP_NLPIPROBLEM*     problem,            /**< problem instance */
233  	   SCIP_Real             objconstant         /**< new value for objective constant */
234  	   );
235  	
236  	/** sets initial guess for primal variables */
237  	SCIP_RETCODE SCIPnlpiSetInitialGuess(
238  	   SCIP_SET*             set,                /**< global SCIP settings */
239  	   SCIP_NLPI*            nlpi,               /**< solver interface */
240  	   SCIP_NLPIPROBLEM*     problem,            /**< problem instance */
241  	   SCIP_Real*            primalvalues,       /**< initial primal values for variables, or NULL to clear previous values */
242  	   SCIP_Real*            consdualvalues,     /**< initial dual values for constraints, or NULL to clear previous values */
243  	   SCIP_Real*            varlbdualvalues,    /**< initial dual values for variable lower bounds, or NULL to clear previous values */
244  	   SCIP_Real*            varubdualvalues     /**< initial dual values for variable upper bounds, or NULL to clear previous values */
245  	   );
246  	
247  	/** tries to solve NLP */
248  	SCIP_RETCODE SCIPnlpiSolve(
249  	   SCIP_SET*             set,                /**< global SCIP settings */
250  	   SCIP_STAT*            stat,               /**< problem statistics */
251  	   SCIP_NLPI*            nlpi,               /**< solver interface */
252  	   SCIP_NLPIPROBLEM*     problem,            /**< problem instance */
253  	   SCIP_NLPPARAM*        param               /**< solve parameters */
254  	   );
255  	
256  	/** gives solution status */
257  	SCIP_NLPSOLSTAT SCIPnlpiGetSolstat(
258  	   SCIP_SET*             set,                /**< global SCIP settings */
259  	   SCIP_NLPI*            nlpi,               /**< solver interface */
260  	   SCIP_NLPIPROBLEM*     problem             /**< problem instance */
261  	   );
262  	
263  	/** gives termination reason */
264  	SCIP_NLPTERMSTAT SCIPnlpiGetTermstat(
265  	   SCIP_SET*             set,                /**< global SCIP settings */
266  	   SCIP_NLPI*            nlpi,               /**< solver interface */
267  	   SCIP_NLPIPROBLEM*     problem             /**< problem instance */
268  	   );
269  	
270  	/** gives primal and dual solution
271  	 * 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
272  	 */
273  	SCIP_RETCODE SCIPnlpiGetSolution(
274  	   SCIP_SET*             set,                /**< global SCIP settings */
275  	   SCIP_NLPI*            nlpi,               /**< solver interface */
276  	   SCIP_NLPIPROBLEM*     problem,            /**< problem instance */
277  	   SCIP_Real**           primalvalues,       /**< buffer to store pointer to array to primal values, or NULL if not needed */
278  	   SCIP_Real**           consdualvalues,     /**< buffer to store pointer to array to dual values of constraints, or NULL if not needed */
279  	   SCIP_Real**           varlbdualvalues,    /**< buffer to store pointer to array to dual values of variable lower bounds, or NULL if not needed */
280  	   SCIP_Real**           varubdualvalues,    /**< buffer to store pointer to array to dual values of variable lower bounds, or NULL if not needed */
281  	   SCIP_Real*            objval              /**< pointer to store the objective value, or NULL if not needed */
282  	   );
283  	
284  	/** gives solve statistics */
285  	SCIP_RETCODE SCIPnlpiGetStatistics(
286  	   SCIP_SET*             set,                /**< global SCIP settings */
287  	   SCIP_NLPI*            nlpi,               /**< solver interface */
288  	   SCIP_NLPIPROBLEM*     problem,            /**< problem instance */
289  	   SCIP_NLPSTATISTICS*   statistics          /**< pointer to store statistics */
290  	   );
291  	
292  	#ifdef __cplusplus
293  	}
294  	#endif
295  	
296  	#endif /* __SCIP_NLPI_H__ */
297