Updated documentation of HighsOptions and HighsInfo

Author: jajhall

FEATURES.md

@@ -36,7 +36,9 @@ Scaling the tolerance in forcing row reduction to avoid use of rows with small c
 
 Fixed bug when calculating a coefficient in one of the cuts in `separateImpliedBounds` in `highs/mip/HighsImplications.cpp`
 
-Added `CSECTION` to the exceptions for keywords that are followed by text, and thus cannot be used as names of columns, RHS, ranges, bounds etc,
+Added `CSECTION` to the exceptions for keywords that are followed by text, and thus cannot be used as names of columns, RHS, ranges, bounds etc.
+
+Introduced the following KKT error measures to `HighsInfo`: `num_relative_primal_infeasibilities`; `max_relative_primal_infeasibility`; `num_relative_dual_infeasibilities`; `max_relative_dual_infeasibility`; `num_primal_residual_errors`; `max_primal_residual_error`; `num_dual_residual_errors`; `max_dual_residual_error`; `num_relative_primal_residual_errors`; `max_relative_primal_residual_error`; `num_relative_dual_residual_errors`; `max_relative_dual_residual_error`; `num_complementarity_violations`; `max_complementarity_violation`; `primal_dual_objective_error.` The relative values are used to assess whether a solution deemed to be optimal by the first order LP solver `cuPDLP-C` or interior point solver `IPX` (without crossover) is truly acceptable. They also enable users to determine whether a solution corresponding to `HighsModelStatus::kUnknown` is acceptable to them as optimal. Also introduced options `complementarity_tolerance` used to assess whether the (relative) primal-dual objective error is acceptable, and `kkt_tolerance` which, if set to a value other than `kDefaultKktTolerance = 1e-7` is used as the tolerance for all the KKT error measures. The HiGHS documentation has been updated to reflect the new options and `HighsInfo` data, and logging messages indicate when KKT error measures are not satisfied, despite the solver considering the LP solution to be optimal.
 
 
 

app/RunHighs.cpp

@@ -75,9 +75,12 @@ int main(int argc, char** argv) {
   // call this first so that printHighsVersionCopyright uses reporting
   // settings defined in any options file.
   highs.passOptions(loaded_options);
-  //  highs.writeOptions("Options.md");
   highs.writeOptions("", true);
 
+  // Lines to write out documentation of HighsOptions and HighsInfo
+  // highs.writeOptions("Options.md");
+  // highs.writeInfo("Info.md");
+
   // Load the model from model_file
   HighsStatus read_status = highs.readModel(cmd_options.model_file);
   if (read_status == HighsStatus::kError) {
@@ -107,8 +110,6 @@ int main(int argc, char** argv) {
   HighsStatus run_status = highs.run();
   if (run_status == HighsStatus::kError) return int(run_status);
 
-  // highs.writeInfo("Info.md");
-
   // Shut down task executor for explicit release of memory.
   // Valgrind still reachable otherwise.
   highs.resetGlobalScheduler(true);

docs/src/options/definitions.md

@@ -55,6 +55,12 @@
 - Range: [1, inf]
 - Default: 1e+15
 
+## kkt\_tolerance
+- KKT tolerance
+- Type: double
+- Range: [1e-10, inf]
+- Default: 1e-07
+
 ## primal\_feasibility\_tolerance
 - Primal feasibility tolerance
 - Type: double
@@ -79,6 +85,12 @@
 - Range: [1e-10, inf]
 - Default: 1e-07
 
+## complementarity\_tolerance
+- Primal-dual objective error tolerance
+- Type: double
+- Range: [1e-10, inf]
+- Default: 1e-07
+
 ## dual\_residual\_tolerance
 - Dual residual tolerance
 - Type: double
@@ -130,8 +142,8 @@
 ## simplex\_scale\_strategy
 - Simplex scaling strategy: off / choose / equilibration (default) / forced equilibration / max value (0/1/2/3/4)
 - Type: integer
-- Range: {0, 5}
-- Default: 1
+- Range: {0, 4}
+- Default: 2
 
 ## simplex\_dual\_edge\_weight\_strategy
 - Strategy for simplex dual edge weights: Choose / Dantzig / Devex / Steepest Edge (-1/0/1/2)
@@ -200,11 +212,31 @@
 - Range: {-2, 2147483647}
 - Default: 0
 
+## read\_solution\_file
+- Read solution file
+- Type: string
+- Default: ""
+
+## read\_basis\_file
+- Read basis file
+- Type: string
+- Default: ""
+
 ## write\_model\_file
 - Write model file
 - Type: string
 - Default: ""
 
+## solution\_file
+- Write solution file
+- Type: string
+- Default: ""
+
+## write\_basis\_file
+- Write basis file
+- Type: string
+- Default: ""
+
 ## write\_model\_to\_file
 - Write the model to a file
 - Type: boolean
@@ -230,6 +262,11 @@
 - Type: boolean
 - Default: "true"
 
+## mip\_allow\_feasibility\_jump
+- Whether MIP feasibility jump is permitted
+- Type: boolean
+- Default: "true"
+
 ## mip\_max\_nodes
 - MIP solver max number of nodes
 - Type: integer
@@ -263,6 +300,17 @@
 - Type: string
 - Default: ""
 
+## mip\_root\_presolve\_only
+- Whether MIP presolve is only applied at the root node
+- Type: boolean
+- Default: "false"
+
+## mip\_lifting\_for\_probing
+- Level of lifting for probing that is used
+- Type: integer
+- Range: {-1, 2147483647}
+- Default: -1
+
 ## mip\_max\_leaves
 - MIP solver max number of leaf nodes
 - Type: integer
@@ -306,7 +354,7 @@
 - Default: 100000
 
 ## mip\_feasibility\_tolerance
-- MIP feasibility tolerance
+- MIP integrality tolerance
 - Type: double
 - Range: [1e-10, inf]
 - Default: 1e-06
@@ -317,6 +365,31 @@
 - Range: [0, 1]
 - Default: 0.05
 
+## mip\_heuristic\_run\_rins
+- Run RINS heuristic: Default = true
+- Type: boolean
+- Default: "true"
+
+## mip\_heuristic\_run\_rens
+- Run RENS heuristic: Default = true
+- Type: boolean
+- Default: "true"
+
+## mip\_heuristic\_run\_root\_reduced\_cost
+- Run rootReducedCost heuristic: Default = true
+- Type: boolean
+- Default: "true"
+
+## mip\_heuristic\_run\_zi\_round
+- Run ZI Round heuristic: Default = false
+- Type: boolean
+- Default: "false"
+
+## mip\_heuristic\_run\_shifting
+- Run Shifting heuristic: Default = false
+- Type: boolean
+- Default: "false"
+
 ## mip\_rel\_gap
 - Tolerance on relative gap, |ub-lb|/|ub|, to determine whether optimality has been reached for a MIP instance
 - Type: double
@@ -364,10 +437,10 @@
 - Default: 1
 
 ## pdlp\_d\_gap\_tol
-- Duality gap tolerance for PDLP solver: Default = 1e-4
+- Duality gap tolerance for PDLP solver
 - Type: double
 - Range: [1e-12, inf]
-- Default: 0.0001
+- Default: 1e-07
 
 ## qp\_iteration\_limit
 - Iteration limit for QP solver

docs/src/structures/structs/HighsInfo.md

@@ -18,6 +18,10 @@ Scalar information about a solved model is communicated via an instance of the H
 - The number of crossover iterations performed
 - Type: integer
 
+## pdlp\_iteration\_count
+- The number of PDLP iterations performed
+- Type: integer
+
 ## qp\_iteration\_count
 - The number of QP iterations performed
 - Type: integer
@@ -71,10 +75,74 @@ Scalar information about a solved model is communicated via an instance of the H
 - Type: integer
 
 ## max\_dual\_infeasibility
-- The maximum dual feasibility violation
+- The maximum violation of dual feasibility
 - Type: double
 
 ## sum\_dual\_infeasibilities
-- The sum of dual feasibility violations
+- The sum of violations of dual feasibility
+- Type: double
+
+## num\_relative\_primal\_infeasibilities
+- The number of variables violating a bound by relatively more than the [primal feasibility tolerance](@ref primal_feasibility_tolerance).
+- Type: integer
+
+## max\_relative\_primal\_infeasibility
+- The maximum relative violation of a bound on a variable
+- Type: double
+
+## num\_relative\_dual\_infeasibilities
+- The number of variables violating dual feasibility by relatively more than the [dual feasibility tolerance](@ref dual_feasibility_tolerance).
+- Type: integer
+
+## max\_relative\_dual\_infeasibility
+- The maximum relative violation of dual feasibility
+- Type: double
+
+## num\_primal\_residual\_errors
+- The number of primal equations violated by more than the [primal residual tolerance](@ref primal_residual_tolerance).
+- Type: integer
+
+## max\_primal\_residual\_error
+- The maximum violation of primal equations 
+- Type: double
+
+## num\_dual\_residual\_errors
+- The number of dual equations violated by more than the [dual residual tolerance](@ref dual_residual_tolerance).
+- Type: integer
+
+## max\_dual\_residual\_error
+- The maximum violation of dual equations 
+- Type: double
+
+## num\_relative\_primal\_residual\_errors
+- The number of primal equations violated by relatively more than the [primal residual tolerance](@ref primal_residual_tolerance).
+- Type: integer
+
+## max\_relative\_primal\_residual\_error
+- The maximum relative violation of primal equations 
+- Type: double
+
+## num\_relative\_dual\_residual\_errors
+- The number of dual equations violated by relatively more than the [dual residual tolerance](@ref dual_residual_tolerance).
+- Type: integer
+
+## max\_relative\_dual\_residual\_error
+- The maximum relative violation of dual equations 
+- Type: double
+
+## num\_complementarity\_violations
+- The number of violations of primal-dual complementarity 
+- Type: integer
+
+## max\_complementarity\_violation
+- The maximum primal-dual complementarity violation
+- Type: double
+
+## primal\_dual\_objective\_error
+- The relative difference between the primal and dual objective values (LP only)
+- Type: double
+
+## primal\_dual\_integral
+- The primal-dual integral for MIPs
 - Type: double
 

highs/lp_data/HighsOptions.h

@@ -726,9 +726,11 @@ class HighsOptions : public HighsOptionsStruct {
         advanced, &large_matrix_value, 1e0, 1e15, kHighsInf);
     records.push_back(record_double);
 
-    record_double = new OptionRecordDouble("kkt_tolerance", "KKT tolerance",
-                                           advanced, &kkt_tolerance, 1e-10,
-                                           kDefaultKktTolerance, kHighsInf);
+    record_double = new OptionRecordDouble(
+        "kkt_tolerance",
+        "If not set to 1e-7, this KKT tolerance is used for all feasibility "
+        "and optimality measures",
+        advanced, &kkt_tolerance, 1e-10, kDefaultKktTolerance, kHighsInf);
     records.push_back(record_double);
 
     record_double = new OptionRecordDouble(
@@ -754,8 +756,9 @@ class HighsOptions : public HighsOptionsStruct {
     records.push_back(record_double);
 
     record_double = new OptionRecordDouble(
-        "complementarity_tolerance", "Complementarity tolerance", advanced,
-        &complementarity_tolerance, 1e-10, kDefaultKktTolerance, kHighsInf);
+        "complementarity_tolerance", "Primal-dual objective error tolerance",
+        advanced, &complementarity_tolerance, 1e-10, kDefaultKktTolerance,
+        kHighsInf);
     records.push_back(record_double);
 
     record_double = new OptionRecordDouble(