|
358 | 358 | * - @subpage CUTSEL "Cut selectors" |
359 | 359 | * - @subpage NODESEL "Node selectors" |
360 | 360 | * - @subpage HEUR "Primal heuristics" |
| 361 | + * - @subpage IISFINDER "IIS finders" |
361 | 362 | * - @subpage DIVINGHEUR "Diving heuristics" |
362 | 363 | * - @subpage RELAX "Relaxation handlers" |
363 | 364 | * - @subpage READER "File readers" |
|
4061 | 4062 |
|
4062 | 4063 | /*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/ |
4063 | 4064 |
|
| 4065 | +/**@page IISFINDER How to add IIS finders |
| 4066 | + * |
| 4067 | + * IIS finders are used to generate an (I)IS ((irreducible) infeasible subsystem) for an infeasible instance. |
| 4068 | + * \n |
| 4069 | + * A complete list of all iis finders contained in this release can be found \ref IISFINDERS "here". |
| 4070 | + * |
| 4071 | + * We now explain how users can add their own iis finders. |
| 4072 | + * Take the greedy iis finder (src/scip/iisfinder_greedy.c) as an example. |
| 4073 | + * As all other default plugins, it is written in C. C++ users can easily adapt the code by using the scip::ObjIISfinder wrapper |
| 4074 | + * base class and implement the `scip_...()` virtual methods instead of the `SCIP_DECL_IISFINDER...` callback methods. |
| 4075 | + * |
| 4076 | + * Additional documentation for the callback methods of an iis finder can be found in the file type_iisfinder.h. |
| 4077 | + * |
| 4078 | + * Here is what you have to do to implement an iis finder: |
| 4079 | + * -# Copy the template files `src/scip/iisfinder_xyz.c` and `src/scip/iisfinder_xyz.h` into files named `iisfinder_myiisfinder.c` |
| 4080 | + * and `iisfinder_myiisfinder.h`. |
| 4081 | + * \n |
| 4082 | + * Make sure to adjust your build system such that these files are compiled and linked to your project. \n |
| 4083 | + * If you are adding a new default plugin for SCIP, this means updating the `src/CMakeLists.txt` and `Makefile` files in the SCIP distribution. |
| 4084 | + * -# Use `SCIPincludeIIsfinderMyiisfinder()` in order to include the iis finder into your SCIP instance, |
| 4085 | + * e.g., in the main file of your project (see, e.g., `src/cmain.c` in the Binpacking example). \n |
| 4086 | + * If you are adding a new default plugin, this include function must be added to `src/scipdefplugins.c`. |
| 4087 | + * -# Open the new files with a text editor and replace all occurrences of "xyz" by "myiisfinder". |
| 4088 | + * -# Adjust the properties of the iis finder (see \ref IISFINDER_PROPERTIES). |
| 4089 | + * -# Define the iis finder data (see \ref IISFINDER_DATA). This is optional. |
| 4090 | + * -# Implement the interface methods (see \ref IISFINDER_INTERFACE). |
| 4091 | + * -# Implement the fundamental callback methods (see \ref IISFINDER_FUNDAMENTALCALLBACKS). |
| 4092 | + * -# Implement the additional callback methods (see \ref IISFINDER_ADDITIONALCALLBACKS). This is optional. |
| 4093 | + * |
| 4094 | + * |
| 4095 | + * @section IISFINDER_PROPERTIES Properties of an IIS finder |
| 4096 | + * |
| 4097 | + * At the top of the new file `iisfinder_myiisfinder.c` you can find the iis finder properties. |
| 4098 | + * These are given as compiler defines. |
| 4099 | + * In the C++ wrapper class, you have to provide the iis finder properties by calling the constructor |
| 4100 | + * of the abstract base class scip::ObjIISfinder from within your constructor. |
| 4101 | + * The properties you have to set have the following meaning: |
| 4102 | + * |
| 4103 | + * \par IISFINDER_NAME: the name of the iis finder. |
| 4104 | + * This name is used in the interactive shell to address the iis finder. |
| 4105 | + * Additionally, if you are searching for an iis finder with SCIPfindIISfinder(), this name is looked up. |
| 4106 | + * Names have to be unique: no two iis finders may have the same name. |
| 4107 | + * |
| 4108 | + * \par IISFINDER_DESC: the description of the iis finder. |
| 4109 | + * This string is printed as a description of the iis finder in the interactive shell. |
| 4110 | + * |
| 4111 | + * \par IISFINDER_PRIORITY: the priority of the iis finder. |
| 4112 | + * When an IIS is desired, SCIP orders the IIS finders by priority. |
| 4113 | + * The iis finders are then called in this order (highest goes first), until depending on the users settings, |
| 4114 | + * one succeeds in finding an infeasible subsystem, an irreducible infeasible subsystem is found, |
| 4115 | + * all iis finders have been run, or some limit has been hit. |
| 4116 | + * \n |
| 4117 | + * Note that this property only defines the default value of the priority. The user may change this value arbitrarily by |
| 4118 | + * adjusting the corresponding parameter setting. Whenever, even during solving, the priority of an iis finder is |
| 4119 | + * changed, then when a call is made to generate an IIS, the iis finders are resorted by the new priorities. |
| 4120 | + * |
| 4121 | + * |
| 4122 | + * @section IISFINDER_DATA IIS Finder Data |
| 4123 | + * |
| 4124 | + * Below the header "Data structures" you can find a struct which is called `struct SCIP_IISfinderData`. |
| 4125 | + * In this data structure, you can store the data of your iis finder. For example, you should store the adjustable |
| 4126 | + * parameters of the iis finder in this data structure. |
| 4127 | + * If you are using C++, you can add iis finder data as usual as object variables to your class. |
| 4128 | + * \n |
| 4129 | + * Defining iis finder data is optional. You can leave the struct empty. |
| 4130 | + * |
| 4131 | + * |
| 4132 | + * @section IISFINDER_INTERFACE Interface Methods |
| 4133 | + * |
| 4134 | + * At the bottom of `iisfinder_myiisfinder.c`, you can find the interface method `SCIPincludeIISfinderMyiisfinder()`, |
| 4135 | + * which also appears in `iisfinder_myiisfinder.h` |
| 4136 | + * `SCIPincludeIISfinderMyiisfinder()` is called by the users, if they want to include the iis finder, i.e., if they want |
| 4137 | + * to use the iis finder in their application. |
| 4138 | + * |
| 4139 | + * This method only has to be adjusted slightly. |
| 4140 | + * It is responsible for notifying SCIP of the presence of the iis finder. For this, you can either call |
| 4141 | + * SCIPincludeIISfinder() |
| 4142 | + * or SCIPincludeIISfinderBasic(). In the latter variant, \ref IISFINDER_ADDITIONALCALLBACKS "additional callbacks" |
| 4143 | + * must be added via setter functions as, e.g., SCIPsetIISfinderCopy(). We recommend this latter variant because |
| 4144 | + * it is more stable towards future SCIP versions which might have more callbacks, whereas source code using the first |
| 4145 | + * variant must be manually adjusted with every SCIP release containing new callbacks for iis finders in order to compile. |
| 4146 | + * |
| 4147 | + * |
| 4148 | + * If you are using iis finder data, you have to allocate the memory for the data at this point. |
| 4149 | + * You can do this by calling: |
| 4150 | + * \code |
| 4151 | + * SCIP_CALL( SCIPallocBlockMemory(scip, &iisfinderdata) ); |
| 4152 | + * \endcode |
| 4153 | + * You also have to initialize the fields in struct SCIP_IISfinderData afterwards. |
| 4154 | + * |
| 4155 | + * You may also add user parameters for your iis finder, see the method SCIPincludeIISfinderGreedy() in |
| 4156 | + * src/scip/iisfinder_greedy.c for an example. |
| 4157 | + * |
| 4158 | + * |
| 4159 | + * @section IISFINDER_FUNDAMENTALCALLBACKS Fundamental Callback Methods of an IIS Finder |
| 4160 | + * |
| 4161 | + * The fundamental callback methods of the plugins are the ones that have to be implemented in order to obtain |
| 4162 | + * an operational algorithm. |
| 4163 | + * They are passed together with the iis finder itself to SCIP using SCIPincludeIISfinder() or SCIPincludeIISfinderBasic(), |
| 4164 | + * see @ref IISFINDER_INTERFACE. |
| 4165 | + * |
| 4166 | + * IIS finder plugins have a single fundamental callback method, namely the IISFINDEREXEC method. |
| 4167 | + * This method has to be implemented for every iis funder; the other callback methods are optional. |
| 4168 | + * It implements the single contribution every iis finder has to provide: Generating an (I)IS from an infeasible instance. |
| 4169 | + * In the C++ wrapper class scip::ObjIISfinder, the scip_exec() method is a virtual abstract member function. |
| 4170 | + * You have to implement it in order to be able to construct an object of your iis finder class. |
| 4171 | + * |
| 4172 | + * @subsection IISFINDEREXEC |
| 4173 | + * |
| 4174 | + * The IISFINDEREXEC callback should generate an (I)IS from an infeasible instance. |
| 4175 | + * The callback receives the IIS object, which contains the infeasible subscip that should be reduced in size, |
| 4176 | + * as well as multiple parameters that limit how the IIS finder procedure should be performed. |
| 4177 | + * The contained subscip should be transformed such that it remains infeasible and decreases in size, |
| 4178 | + * and information about the current state of the subscip, e.g., is it still infeasible, should be recorded. |
| 4179 | + * |
| 4180 | + * Additional documentation for this callback can be found in type_iisfinder.h. |
| 4181 | + * |
| 4182 | + * @section IISFINDER_ADDITIONALCALLBACKS Additional Callback Methods of an IIS Finder |
| 4183 | + * |
| 4184 | + * The additional callback methods do not need to be implemented in every case. However, some of them have to be |
| 4185 | + * implemented for most applications. They can be used, for example, to initialize and free private data. |
| 4186 | + * Additional callbacks can either be passed directly with SCIPincludeIISfinder() to SCIP or via specific |
| 4187 | + * <b>setter functions</b> after a call of SCIPincludeIISfinderBasic(), see also @ref IISFINDER_INTERFACE. |
| 4188 | + * |
| 4189 | + * @subsection IISFINDERFREE |
| 4190 | + * |
| 4191 | + * If you are using iis finder data, you have to implement this method in order to free the iis finder data. |
| 4192 | + * This can be done by the following procedure: |
| 4193 | + * |
| 4194 | + * @refsnippet{src/scip/iisfinder_greedy.c,SnippetIISfinderFreeGreedy} |
| 4195 | + * |
| 4196 | + * If you have allocated memory for fields in your iis finder data, remember to free this memory |
| 4197 | + * before freeing the iis finder data itself. |
| 4198 | + * If you are using the C++ wrapper class, this method is not available. |
| 4199 | + * Instead, just use the destructor of your class to free the member variables of your class. |
| 4200 | + * |
| 4201 | + * @subsection IISFINDERCOPY |
| 4202 | + * |
| 4203 | + * The IISFINDERCOPY callback is executed when a SCIP instance is copied, e.g., to solve a sub-SCIP. By defining this |
| 4204 | + * callback as `NULL` the user disables the execution of the specified iis finder for all copied SCIP |
| 4205 | + * instances |
| 4206 | + */ |
| 4207 | + |
| 4208 | +/*--+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+----0----+----1----+----2*/ |
| 4209 | + |
4064 | 4210 | /**@page EXPRHDLR How to add expression handlers |
4065 | 4211 | * |
4066 | 4212 | * Expression handlers define basic expression types and provide additional functionality to work with expressions, |
|
0 commit comments