Updated IIS docs and set up lp-get-iis-galenet for study

Author: jajhall

check/TestIis.cpp

@@ -406,7 +406,7 @@ void testMps(std::string& model, const HighsInt iis_strategy,
   std::string model_file =
       std::string(HIGHS_DIR) + "/check/instances/" + model + ".mps";
   Highs highs;
-  highs.setOptionValue("output_flag", dev_run);
+  //  highs.setOptionValue("output_flag", dev_run);
 
   REQUIRE(highs.readModel(model_file) == HighsStatus::kOk);
   //  if (iis_strategy == kIisStrategyFromRayRowPriority ||

docs/src/guide/advanced.md

@@ -37,7 +37,20 @@ variable/constraint bound information, that cannot be satisfied (so is
 infeasible). It is irreducible in that if any constraint or variable
 bound is removed, then the system can be satisfied (so is feasible).
 
-HiGHS has an IIS facility that is under development. Currently it can only be used for LPs.
+HiGHS has an IIS facility that is under development. Currently it can
+only be used for LPs. The full IIS calculation is expensive, since it
+requires the solution of multiple LPs. Although there is a prototype
+implementation, it is not as robust or efficient as it will
+be. Otherwise, there is a simple, cheap test that looks for
+infeasibility due to incompatible variable oe constraint bounds, or
+constraint bounds that cannot be satisfied given the range of values
+on the constraint activity implied by bounds on variables.
+
+The choice of IIS strategy is defined by the [iis_strategy](@id option-iis-strategy) option, which can take the value
+
+- `kIisStrategyLight` = 0: The cheap test
+- `kIisStrategyFromLpRowPriority` = 1: The full IIS calculation, aiming to have a minimal number of rows in the IIS
+- `kIisStrategyFromLpColPriority` = 2: The full IIS calculation, aiming to have a minimal number of columns in the IIS
 
 ### IIS-related methods in the `Highs` class
 

docs/src/options/definitions.md

@@ -486,7 +486,7 @@
 - Range: [0, inf]
 - Default: 1e-07
 
-## iis\_strategy
+## [iis\_strategy](@id option-iis-strategy)
 - Strategy for IIS calculation: Light test / Full and prioritise rows / Full and prioritise columns (0/1/2)
 - Type: integer
 - Range: {0, 2}

highs/lp_data/HighsIis.h

@@ -13,7 +13,7 @@
 
 #include "model/HighsModel.h"
 
-const bool kIisDevReport = false;
+const bool kIisDevReport = true;  // false;
 
 enum IisBoundStatus {
   kIisBoundStatusDropped = -1,

highs/lp_data/HighsInterface.cpp

@@ -2097,10 +2097,11 @@ HighsStatus Highs::elasticityFilter(
     const bool get_infeasible_row,
     std::vector<HighsInt>& infeasible_row_subset) {
   //  this->writeModel("infeasible.mps");
+  //
   // Solve the feasibility relaxation problem for the given penalties,
-  // continuing to act as the elasticity filter get_infeasible_row is
-  // true, resulting in an infeasibility subset for further refinement
-  // as an IIS
+  // continuing to act as the elasticity filter if get_infeasible_row
+  // is true, resulting in an infeasibility subset for further
+  // refinement as an IIS
   //
   // Construct the e-LP:
   //

highs/lp_data/Iis.md

@@ -2,6 +2,59 @@
 
 Further to documentation in https://ergo-code.github.io/HiGHS/stable/guide/advanced/
 
+The IIS search is rooted in `Highs::getIisInterface()`, which first
+checks whether the `Highs::model_status_` is
+`HighsModelStatus::kOptimal` or `HighsModelStatus::kUnbounded`, in
+which case the model is feasible so no IIS exists. Otherwise, the
+trivial check (for inconsistent bounds or empty infeasible rows) -
+performed by `HighsIis::trivial()` - and infeasible rows based on row
+value bounds - performed by `HighsIis::rowValueBounds()` - are
+performed. If `Highs::options_.iis_strategy` is `kIisStrategyLight`
+then `Highs::getIisInterface()` returns.
 
+The "full" IIS calculation operates in two phases: after a set of
+mutually infeasible rows has been identified, this is reduced to an
+IIS. The set of mutually infeasible rows can be found in two ways.
 
+Firstly, if it is known that the model is infeasible, then the simplex
+solver may have identified a dual ray. If there is a dual ray then its
+nonzeros correspond to a set of mutually infeasible constraints. If
+there is no dual ray - as might happen if the model's infeasibility
+has been identified in presolve - then the incumbent model is solved
+with `Highs::options_.presolve` = "off". Unfortunately the "ray route"
+is not robust, so currently switched off.
+
+Secondly - and the only route at the moment - an elasticity filter
+calculation is done to identify an infeasible subset of rows. This is
+calculation performed in `HighsIis::elasticityFilter`. This method is
+more general than is necessary for finding the set of mutually
+infeasible rows for an IIS calculation, and can be called directly
+using `Highs::feasibilityRelaxation`.
+
+The essence of the `HighsIis::elasticityFilter` is that it allows
+lower bounds, upper bounds and RHS values to be violated. There are
+penalties for doing so that can be global for each of these three
+cases, or local to each column lower bound, upper bound and row
+bound. The "elasticity LP" is constructed by adding elastic variables
+to transform the constraints from
+$$
+L <= Ax <= U;\qquad l <= x <= u
+$$
+to
+$$
+L <= Ax + e_L - e_U <= U;\qquad l <=  x + e_l - e_u <= u,
+$$
+where the elastic variables are not used if the corresponding bound is
+infinite or the local/global penalty is negative. The original bounds
+on the variables $x$ are removed, and the objective is the linear
+function of the elastic variables given by the local/global
+penalties. Note that the model modifications required to achieve this
+formulation, are made by calls to methods in the `Highs` class so that
+the value of any initial basis is maintained.
+
+For the purposes of IIS calculation, each elastic variable has a 
+
+If the original constraints cannot be satisfied, then some 
+
+After the elasticity LP has been solved, each elasticity variable whose optimal value is positive is fixed at zero is