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   heur_multistart.h
26   	 * @ingroup PRIMALHEURISTICS
27   	 * @brief  multistart heuristic for convex and nonconvex MINLPs
28   	 * @author Benjamin Mueller
29   	 *
30   	 * The heuristic applies multiple NLP local searches to a mixed-integer nonlinear program with, probably nonconvex,
31   	 * constraints of the form \f$g_j(x) \le 0\f$. The algorithm tries to identify clusters which approximate the boundary
32   	 * of the feasible set of the continuous relaxation by sampling and improving randomly generated points. For each
33   	 * cluster we use a local search heuristic to find feasible solutions. The algorithm consists of the following four
34   	 * steps:
35   	 *
36   	 * 1. sample points
37   	 *
38   	 *    Sample random points \f$ x^1, \ldots, x^n \f$ in the box \f$ [\ell,u] \f$. For an unbounded variable \f$ x_i \f$
39   	 *    we consider \f$ [\ell_i,\ell_i + \alpha], [u_i - \alpha,u_i], \f$ or \f$ [-\alpha / 2, \alpha / 2]\f$ for an \f$
40   	 *    \alpha > 0 \f$ depending on which bound is infinite.
41   	 *
42   	 * 2. reduce infeasibility
43   	 *
44   	 *   For each point \f$ x^i \f$ we use a gradient descent method to reduce the maximum infeasibility. We first compute
45   	 *
46   	 *    \f[
47   	 *        d_j = -\frac{g_j(x^i)}{||\nabla g_j(x^i)||^2} \nabla g_j(x^i)
48   	 *    \f]
49   	 *
50   	 *    and update the current point \f$ x^i \f$ with
51   	 *
52   	 *    \f[
53   	 *        x^i := x^i + \frac{1}{n_j} \sum_{j} d_j
54   	 *    \f]
55   	 *
56   	 *    where \f$ n_j \f$ is the number of strictly positive \f$ d_j \f$. The algorithm is called Constraint Consensus
57   	 *    Method and has been introduced by <a
58   	 *    href="http://www.sce.carleton.ca/faculty/chinneck/docs/ConstraintConsensusJoC.pdf">here </a>.
59   	 *
60   	 * 3. cluster points
61   	 *
62   	 *    We use a greedy algorithm to all of the resulting points of step 3. to find clusters which (hopefully) approximate
63   	 *    the boundary of the feasible set locally. Points with a too large violations will be filtered.
64   	 *
65   	 * 4. solve sub-problems
66   	 *
67   	 *    Depending on the current setting, we solve a sub-problem for each identified cluster. The default strategy is to
68   	 *    compute a starting point for the sub-NLP heuristic (see @ref heur_subnlp.h) by using a linear combination of the
69   	 *    points in a cluster \f$ C \f$, i.e.,
70   	 *
71   	 *    \f[
72   	 *        s := \sum_{x \in C} \lambda_x x
73   	 *    \f]
74   	 *
75   	 *    Since the sub-NLP heuristic requires a starting point which is integer feasible we round each fractional
76   	 *    value \f$ s_i \f$ to its closest integer.
77   	 */
78   	
79   	
80   	/*---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/
81   	
82   	#ifndef __SCIP_HEUR_MULTISTART_H__
83   	#define __SCIP_HEUR_MULTISTART_H__
84   	
85   	#include "scip/def.h"
86   	#include "scip/type_retcode.h"
87   	#include "scip/type_scip.h"
88   	
89   	#ifdef __cplusplus
90   	extern "C" {
91   	#endif
92   	
93   	/** creates the multistart primal heuristic and includes it in SCIP
94   	 *
95   	 *  @ingroup PrimalHeuristicIncludes
96   	 */
97   	SCIP_EXPORT
98   	SCIP_RETCODE SCIPincludeHeurMultistart(
99   	   SCIP*                 scip                /**< SCIP data structure */
100  	   );
101  	
102  	#ifdef __cplusplus
103  	}
104  	#endif
105  	
106  	#endif
107