lpsolver 0.1.0 → 0.2.1

data/ext/lpsolver-highs/docs/src/guide/basic.md

@@ -0,0 +1,116 @@
+# [Basic features](@id guide-basic)
+
+The minimal use of HiGHS has the following three stages.
+
+* [Define a model](@ref Defining-a-model)
+* [Solve the model](@ref Solving-the-model)
+* [Extract results](@ref Extracting-results)
+
+Although its default actions will be sufficient for most users, HiGHS
+can be controlled by setting [Option values](@ref Option-values).
+
+_Intro to other basic features_
+
+### HiGHS data structures
+
+There are several specialist data structures that can be used to
+interact with HiGHS when using [`C++`](@ref cpp-getting-started) and
+`highspy`. These are defined in the sections on [enums](@ref structures-enums)
+and [classes](@ref classes-overview), and are referred to below.
+
+#### [Enums](@id guide-basic-enums)
+
+Enums are scalar identifier types that can take only a limited range of values.
+
+#### [Classes](@id guide-basic-classes)
+
+The advantage of using the native `C++` classes in HiGHS is that many fewer parameters are needed
+when passing data to and from HiGHS. The binding of the data members
+of these classes to `highspy` structures allows them to be used when
+calling HiGHS from Python, although they are not necessary for the
+basic use of `highspy`. As with the `C` and `Fortran` interfaces,
+there are equivalent methods that use simple scalars and vectors of
+data.
+
+## Defining a model
+
+HiGHS has comprehensive tools for defining models. This can be done by
+either reading a model using a data file created elsewhere, or by
+passing model data to HiGHS. Once a model has been defined in HiGHS,
+it is referred to as the `incumbent model`.
+
+### Reading a model from a file
+
+The simplest way to define a model in HiGHS is to read it from a file using
+the method [`readModel`](@ref Read-a-model). HiGHS infers the file type by the extension. Supported extensions are:
+
+ * `.mps`: for an MPS file
+ * `.lp`: for a CPLEX LP file
+ 
+HiGHS can read compressed files that end in the `.gz` extension, but
+not (yet) files that end in the `.zip` extension.
+
+### Building a model
+
+The model in HiGHS can be built using a sequence of calls to add
+variables and constraints. This is most easily done one-by-one using
+the methods [`addCol` and `addRow`](@ref
+Build-a-model). Alternatively, calls to [`addVar`](@ref Build-a-model)
+can be used to add variables, with calls to [`changeColCost`](@ref
+Build-a-model) used to define each objective coefficient.
+
+Addition of multiple variables and constraints can be achieved using
+[`addCols` and `addRows`](@ref Build-a-model). Alternatively,
+[`addVars`](@ref Build-a-model) can be used to add variables, with
+[`changeColsCost`](@ref Build-a-model) used to define objective
+coefficients. Note that defining multiple variables and constraints requires
+vectors of data and the specification of constraint coefficients as
+compressed
+[row-wise](https://en.wikipedia.org/wiki/Sparse_matrix#Compressed_sparse_row_(CSR,_CRS_or_Yale_format))
+or
+[column-wise](https://en.wikipedia.org/wiki/Sparse_matrix#Compressed_sparse_column_(CSC_or_CCS))
+matrices.
+
+### Passing a model
+
+If the entire definition of a model is known, then it can be passed to
+HiGHS via individual data arrays using the method [`passModel`](@ref
+Pass-a-model). In languages where HiGHS data structures can be used,
+an instance of the [`HighsLp`](@ref HighsLp) class can be populated
+with data and then passed.
+
+## Solving the model
+
+The incumbent model in HiGHS is solved by a call to the method
+[`run`](@ref Solve-the-model). By default, HiGHS minimizes the model's
+objective function, although this can be [changed](@ref
+Modifying-model-data). Where possible, HiGHS will reduce the solution
+time by using data obtained on previous runs, or supplied by the
+user. More information on this process of hot starting solvers is
+[available](@ref hot-start).
+
+## Extracting results
+
+After solving a model, it is important to know whether it has been
+solved to optimality, shown to be infeasible or unbounded, or why the
+solver may have terminated early. This model status is given by the
+value returned by the method [`getModelStatus`](@ref
+Extract-results). This value is of type [`HighsModelStatus`](@ref HighsModelStatus).
+Scalar information about a solved model is obtained using the method
+[`getInfo`](@ref Extract-results).  The solution and (any) basis are
+returned by the methods [`getSolution`](@ref Extract-results) and
+[`getBasis`](@ref Extract-results) respectively. HiGHS can also be used
+to write the solution to a file using the method [`writeSolution`](@ref
+Report-results).
+
+## Option values
+
+The option values that control HiGHS are of type `string`, `bool`,
+`int` and `double`. Options are referred to by a `string` identical to
+the name of their identifier. A full specification of the options is
+given in the [list of options](@ref option-definitions). An option
+value is changed by passing its name and value to the method
+[`setOptionValue`](@ref example-py-option-values).  The current value
+of an option is obtained by passing its name to the method
+[`getOptionValue`](@ref example-py-option-values).
+

data/ext/lpsolver-highs/docs/src/guide/further.md

@@ -0,0 +1,193 @@
+# [Further features](@id guide-further)
+
+## [Presolve](@id guide-presolve)
+
+HiGHS has a sophisticated presolve procedure for LPs and MIPs that
+aims to reduce the dimension of the model that must be solved. In most
+cases, the time saved by solving the reduced model is very much
+greater than the time taken to perform presolve. Once the presolved
+model is solved, a postsolve procedure (of minimal computational cost)
+deduces the optimal solution to the original model. Hence presolve is
+performed by default. The only exception occus when there is a valid
+basis for an LP and the simplex solver is used. In this case the
+original LP is solved, starting from this basis. In cases where the
+use of presolve is found not to be advantageous, its use can be
+switched off by setting the [presolve](@ref option-presolve) option to
+"off".
+
+HiGHS has a method [presolve](@ref Presolve/postsolve) that performs presolve on
+the incumbent model, allowing the presolved model to be extracted or
+written to a file. This is intended for users who have their own
+solution technique that they wish to test using models presolved by
+HiGHS. Note that this does not affect how the incumbent model is
+solved. There are two corresponding [postsolve](@ref Presolve/postsolve)
+methods, according to whether there are just solution values, or also
+a basis.
+
+## Model and solution management
+
+HiGHS has comprehensive tools for defining and extracting models. This can be
+done either to/from MPS or (CPLEX) format LP files, or via method calls. HiGHS
+also has methods that permit the incumbent model to be modified. Solutions can
+be supplied and extracted using either files or method calls.
+
+### Extracting model data
+
+The numbers of column, rows and nonzeros in the model are returned by the
+methods [`getNumCols`](@ref Get-model-data), [`getNumRows`](@ref Get-model-data),
+and [`getNumEntries`](@ref Get-model-data) respectively.
+
+Model data can be extracted for a single column or row by specifying the index
+of the column or row and calling the methods [`getCol`](@ref Get-model-data) and
+[`getRow`](@ref Get-model-data).
+
+As well as returning the value of the cost and bounds, these methods also return
+the number of nonzeros in the corresponding column or row of the constraint
+matrix. The indices and values of the nonzeros can be obtained using the methods
+[`getColEntries`](@ref Get-model-data) and [`getRowEntries`](@ref Get-model-data).
+
+For multiple columns and rows defined by a set of indices, the corresponding
+data can be extracted using the methods [`getCols`](@ref Get-model-data),
+[`getRows`](@ref Get-model-data), [`getColsEntries`](@ref Get-model-data) and
+[`getRowsEntries`](@ref Get-model-data).
+
+Specific matrix coefficients obtained using the method [`getCoeff`](@ref Get-model-data).
+
+## Modifying model data
+
+The most immediate model modification is to change the sense of the objective.
+By default, HiGHS minimizes the model's objective function. The objective sense
+can be set to minimize (maximize) using [changeObjectiveSense](@ref Modify-model-data).
+
+Model data for can be changed for one column or row by specifying the index of
+the column or row, together with the new scalar value for the cost or bounds,
+the specific methods being [changeColCost](@ref Modify-model-data),
+[changeColBounds](@ref Modify-model-data). The corresponding method for a row is
+[changeRowBounds](@ref Modify-model-data). Changes for multiple columns or rows
+are defined by supplying a list of indices, together with arrays of new values,
+using the methods [changeColsCost](@ref Modify-model-data),
+[changeColsBounds](@ref Modify-model-data). The corresponding method for a row
+is [changeRowsBounds](@ref Modify-model-data). An individual matrix coefficient
+is changed by passing its row index, column index and new value to
+[changeCoeff](@ref Modify-model-data).
+
+## [Hot start](@id hot-start)
+
+It may be possible for HiGHS to start solving a model using data
+obtained by solving a related model, or supplied by a user. Whether
+this is possible depends on the the class of model being solved, the
+solver to be used, and the modifications (if any) that have been to
+the incumbent model since it was last solved.
+
+This process is most efficient when solving a sequence of related LP
+problems and the optimal [basic solution](@ref term-basic-solution)
+for some problem earlier in the sequence is known. Only the
+[simplex](@ref solvers-simplex) solver can be hot-started in this
+way. Note that if LP modifications are made via HiGHS methods, any
+basis stored internally will be modified to allow the best possible
+hot start.
+
+### [LP](@id hot-start-lp)
+
+To run HiGHS from a user-defined solution or basis, this is passed to
+HiGHS using the methods [setSolution](@ref Set-solution) or
+[setBasis](@ref Set-basis). The basis passed to HiGHS need not be
+complete
+
+* There can be more basic variables then the number of rows in the
+  model. HiGHS will identify a set of basic variables of the correct
+  dimension by making some basic variables nonbasic
+
+* There can be fewer basic variables then the number of rows in the
+  model.  HiGHS will identify a set of basic variables of the correct
+  dimension by adding basic variables corresponding to slacks.
+
+* For nonbasic variables, it is unnecessary to specify whether they
+  are at their lower or upper bound unless they are "boxed" variables.
+
+If a basis is known, then the simplex solver is applied to the LP,
+starting from the known basis. Presolve is not performed because it is
+not currently possible to solve a presolved LP using a basis for the
+original problem. This default strategy is typically the most
+efficient. However, it may be more efficient to solve the LP from
+scratch using the IPM solver (following presolve) in the following
+circumstances
+
+* If the modifications are too great
+
+* If the LP can be reduced greatly via presolve
+
+To achieve this, any basis held internally must be cleared by calling
+`HighsLp::setBasis` with no argument.
+
+### MIP
+
+If a (partial) feasible assignment of the integer variables is known,
+this can be passed to HiGHS via [setSolution](@ref Set-solution). If
+integer variables are set to integer values, HiGHS will solve the LP
+with these integer variables fixed (or MIP if the assignment of the
+integer variables is not complete). If a feasible solution is
+obtained, it will be used to provide the MIP solver with an initial
+primal bound when it run to solve for all integer variables.
+
+## [Multi-objective optimization](@id guide-multi-objective-optimization)
+
+Users can specify multiple linear objectives with respect to which
+HiGHS will optimize by either blending them, or by performing
+lexicographic optimization according to the truth of the
+[blend\_multi\_objectives](@ref option-blend-multi-objectives) option. Each
+linear objective is represented by the following data, held in the
+[HighsLinearObjective](@ref HighsLinearObjective) structure
+
+- weight: Scalar of type double - The weight of this objective when blending 
+- offset: Scalar of type double - The offset of this objective
+- coefficients: Vector of type double - The coefficients of this objective
+- abs\_tolerance: Scalar of type double - The absolute tolerance on this objective when performing lexicographic optimization 
+- rel\_tolerance: Scalar of type double - The relative tolerance on this objective when performing lexicographic optimization 
+- priority: Scalar of type HighsInt - The priority of this objective when performing lexicographic optimization
+
+### Methods
+
+Multi-objective optimization in HiGHS is defined by the following methods
+
+- [addLinearObjective](@ref Multi-objective-optimization) - Add a single `HighsLinearObjective` instance to any already stored in HiGHS
+- [clearLinearObjectives](@ref Multi-objective-optimization) - Clears any linear objectives stored in HiGHS
+
+When there is at least one `HighsLinearObjective` instance in HiGHS,
+the `col_cost_` data in the incumbent model is ignored.
+
+### Blending multiple linear objectives
+
+When [blend\_multi\_objectives](@ref option-blend-multi-objectives) is `true`,
+as it is by default, any `HighsLinearObjective` instances will be
+combined according to the `weight` values, and the resulting objective
+will be minimized. Hence, any objectives that should be maximized
+within the combination must have a negative `weight` value.
+
+### Lexicographic optimization of multiple linear objectives
+
+When [blend\_multi\_objectives](@ref option-blend-multi-objectives) is `false`,
+HiGHS will optimize lexicographically with respect to any
+`HighsLinearObjective` instances. This is carried out as follows, according to the
+`priority` values in `HighsLinearObjective` instances. Note that _all
+priority values must be distinct_.
+
+* Minimize/maximize with respect to the linear objective of highest priority value, according to whether its `weight` is positive/negative
+
+* Add a constraint to the model so that the value of the linear objective of highest priority satsifies a bound given by the values of `abs_tolerance` and/or `rel_tolerance`.
+    + If the objective was minimized to a value ``f^*\ge0``, then the constraint ensures that the this objective value is no greater than ``\min(f^*+abs\_tolerance,~f^*\times[1+rel\_tolerance]).``
+
+    + If the objective was minimized to a value ``f^*<0``, then the constraint ensures that the this objective value is no greater than ``\min(f^*+abs\_tolerance,~f^*\times[1-rel\_tolerance]).``
+
+    + If the objective was maximized to a value ``f^*\ge0``, then the constraint ensures that the this objective value is no less than ``\max(f^*-abs\_tolerance,~f^*\times[1-rel\_tolerance]).``
+
+    + If the objective was maximized to a value ``f^*<0``, then the constraint ensures that the this objective value is no less than ``\max(f^*-abs\_tolerance,~f^*\times[1+rel\_tolerance]).``
+
+* Minimize/maximize with respect to the linear objective of next highest priority, and then add a corresponding objective constraint to the model, repeating until optimization with respect to the linear objective of lowest priority has taken place.
+
+Note
+
+* Negative values of `abs_tolerance` and `rel_tolerance` will be ignored. This is a convenient way of "switching off" a bounding technique that is not of interest.
+* When the model is continuous, no dual information will be returned if there is more than one linear objective.
+
+

data/ext/lpsolver-highs/docs/src/guide/gpu.md

@@ -0,0 +1,58 @@
+# [GPU acceleration](@id gpu)
+
+From HiGHS v1.10.0, its first order primal-dual LP (PDLP) solver
+[cuPDLP-C](https://github.com/COPT-Public/cuPDLP-C) can be run on an
+NVIDIA GPU under Linux and Windows. However, to achieve this, CUDA
+utilities must be installed and HiGHS must be built locally using
+CMake, as described below.
+
+### PDLP: A health warning
+
+First order solvers for LP are still very much "work in
+progress". Although impressive results have been reported, these are
+often to lower accuracy than is achieved by simplex and interior point
+solvers, have been obtained using top-of-the-range GPUs, and not
+achieved for all problem classes. Note that, due to PDLP using
+relative termination conditions, a solution deemed optimal by PDLP may
+not be accepted as optimal by HiGHS. The user should consider the
+infeasibility data returned by [HighsInfo](@ref HighsInfo) to decide
+whether the solution is acceptable to them.
+
+#### Termination criteria
+
+Although the PDLP solver may report that it has terminated with an
+optimal solution, HiGHS may identify that the solution returned by
+PDLP is not optimal. As discussed in [HiGHS feasibility and optimality
+tolerances](@ref kkt), this is due to PDLP using relative termination
+criteria and (unlike interior point solvers) not satisfying
+feasibility to high accuracy.
+
+If you use the HiGHS PDLP solver, in the first instance it is
+recommended that you increase the feasibility and optimality
+tolerances to `1e-4`, since this will result in the algorithm
+terminating much sooner. There are multiple feasibility and optimality
+tolerances, but all will be set to the value of the
+[`kkt_tolerance`](@ref option-kkt-tolerance) option (if it differs
+from its default value of `1e-4`) so this is recommended in the first
+instance.
+
+### Requirements
+
+CUDA Toolkit and CMake. 
+
+A [CUDA Toolkit](https://developer.nvidia.com/cuda-toolkit)
+installation is required, along with the matching NVIDIA
+driver. Please install both following the instructions on NVIDIA's
+website.
+
+HiGHS must be build locally with CMake. 
+
+Make sure the CUDA compiler `nvcc` is installed by running 
+
+```
+nvcc --version
+```
+
+### Build HiGHS with GPU support
+
+See [Building HiGHS with NVidia GPU support](@ref gpu-build).

data/ext/lpsolver-highs/docs/src/guide/index.md

@@ -0,0 +1,18 @@
+# [Introduction](@id guide-introduction)
+
+This guide describes the features of HiGHS that are available when it
+is called from [`Python`](@ref python-getting-started), [`C++`](@ref
+cpp-getting-started), [`C`](@ref c-api), [`C#`](@ref csharp)  and [`Fortran`](@ref
+fortran-api). It is written in three sections: [basic](@ref
+guide-basic), [further](@ref guide-further) and [advanced](@ref
+guide-advanced). 
+
+The [basic](@ref guide-basic) section will be sufficient for most
+users. This and the [further](@ref guide-further) section cover the
+`Python` interface `highspy`.  Although references to methods link to
+`Python` examples, the method names and functionality for other
+interfaces are as close as possible.
+
+The [advanced](@ref guide-advanced) section covers features in the
+[`C++`](@ref cpp-getting-started), [`C`](@ref c-api) and
+[`Fortran`](@ref fortran-api) that are not in `highspy`.

data/ext/lpsolver-highs/docs/src/guide/kkt.md

@@ -0,0 +1,219 @@
+# [Feasibility and optimality](@id kkt)
+
+Mathematically, continuous optimization problems have exact feasibility
+and optimality conditions. However, since solvers cannot always
+satisfy these conditions exactly when using floating-point arithmetic,
+they do so to within tolerances. As explored below, some solvers aim
+to satisfy those tolerances absolutely, and others aim to satisfy
+tolerances relative to problem data. When tolerances are satisfied
+relatively, they are generally not satisfied absolutely. The use of
+tolerances relative to problem data is not consistent across solvers,
+and can give a misleading claim of optimality. To achieve consistency,
+HiGHS reassesses the optimal solution claimed by such a solver in a
+reasonable and uniform manner.
+
+### Feasibility and optimality conditions
+
+To discuss tolerances and their use in different solvers, consider the
+standard form linear programming (LP) problem with ``n`` variables and
+``m`` equations (``n\ge m``).
+
+```math
+\begin{aligned}
+\textrm{minimize}   \quad & c^T\! x        \\
+\textrm{subject to} \quad & Ax = b  \\
+                          & x \ge 0,
+\end{aligned}
+```
+
+The feasibility and optimality conditions (KKT conditions) are that, at
+a point ``x``, there exist (row) dual values ``y`` and reduced costs
+(column dual values) ``s`` such that
+
+```math
+\begin{aligned}
+Ax=b&\qquad\textrm{Primal~equations}\\
+A^Ty+s=c&\qquad\textrm{Dual~equations}\\
+x\ge0&\qquad\textrm{Primal~feasibility}\\
+s\ge0&\qquad\textrm{Dual~feasibility}\\
+c^Tx-b^Ty=0&\qquad\textrm{Optimality}
+\end{aligned}
+```
+
+The optimality condition is equivalent to the complementarity
+condition that ``x^Ts=0``. Since any LP problem can be transformed
+into standard form, the following discussion loses no generality. This
+discussion also largely applies to quadratic programming (QP)
+problems, with the differences explored below.
+
+### The HiGHS feasibility and optimality tolerances
+
+HiGHS has separate tolerances for the following, listed with convenient mathematical notation
+
+- [Primal feasibility](@ref option-primal-feasibility-tolerance) (``\epsilon_P``)
+- [Dual feasibility](@ref option-dual-feasibility-tolerance) (``\epsilon_D``)
+- Residual errors in the [primal equations](@ref option-primal-residual-tolerance) (``\epsilon_R``)
+- Residual errors in the [dual equations](@ref option-dual-residual-tolerance) (``\epsilon_C``)
+- [Optimality](@ref option-optimality-tolerance) (``\epsilon_{O}``)
+
+All are set to the same default value of ``10^{-7}``. Although each
+can be set to different values by the user, if the user wishes to
+solve LPs to a general lower or higher tolerance, the value of the
+[KKT tolerance](@ref option-kkt-tolerance) can be changed from this
+default value.
+
+### When HiGHS yields an optimal solution
+
+When HiGHS returns a model status of optimal, the solution will
+satisfy feasibility and optimality tolerances absolutely or relatively
+according to whether the solver yields a basic solution.
+
+### Solutions with a corresponding basis
+
+The HiGHS simplex solvers and the interior point solver after
+crossover yield an optimal basic solution of the LP, consisting of
+``m`` basic variables and ``n-m`` nonbasic variables. At any basis,
+the nonbasic variables are zero, and values for the basic variables
+are given by solving a linear system of equations. Values for the row
+dual values (``y``) can be computed by solving a linear system of equations,
+and the column dual values are then given by ``s=c-A^Ty``. With exact
+arithmetic, the basic dual values are zero by construction.
+
+When primal and dual values are computed using floating-point
+arithmetic, the basic dual values are set to zero so the optimality
+condition holds by construction. However, the primal and dual
+equations may not be satisfied exactly, so have nonzero
+residuals. Fortunately, when solving a linear system of equations
+using a stable technique, any residuals are small relative to the RHS
+of the equations, whatever the condition of the matrix of
+coefficients. Hence HiGHS does not assess the primal residuals, or the
+dual residuals for basic variables. Thus optimality for a basic
+solution is assessed by HiGHS according to whether the following
+conditions hold
+
+```math
+\begin{aligned}
+x_i\ge-\epsilon_P&\qquad\forall i=1,\ldots,n\\
+s_i\ge-\epsilon_D&\qquad\forall i=1,\ldots,n.
+\end{aligned}
+```
+
+The HiGHS active set QP solver has an objective function ``(1/2)x^TQx + c^Tx``,
+and maintains the QP equivalent of a basis in which a subset
+of (up to ``n``) variables are zero. However, there are variables
+that are off their bounds whose reduced costs are not zero by
+construction. At an optimal solution they will only be less than a
+dual feasibility tolerance in magnitude, so the optimality condition
+will not be satisfied by construction. The primal and dual equations
+(where the latter is ``A^Ty+s=Qx+c``) will be satisfied with small
+residuals. Optimality is assessed by HiGHS according to whether primal
+and dual feasibility is satisfied to within the corresponding
+tolerance.
+
+
+### Solutions without a corresponding basis
+
+The HiGHS PDLP solver and the interior point solvers (HiPO and IPX)
+without crossover yield "optimal" primal and dual values that satisfy
+internal conditions for termination of the underlying algorithm. These
+conditions are discussed below, and are used for good reason. However,
+particularly in the case of PDLP, they can lead to a misleading claim
+of optimality.
+
+#### Interior point solutions
+
+The interior point algorithm uses a single feasibility tolerance
+``\epsilon=\min(\epsilon_P, \epsilon_D)``, and an independent
+[optimality tolerance](@ref option-ipm-optimality-tolerance)
+(``\epsilon_{IPM}``) that, by default, is (currently) ten times
+smaller than the other feasibility and optimality tolerances used by
+HiGHS. It terminates when
+
+```math
+\begin{aligned}
+\|Ax-b\|_\infty&\le(1+\|b\|_\infty)\epsilon_R\\
+\|c-A^Ty+s\|_\infty&\le(1+\|c\|_\infty)\epsilon_C\\
+-x_i&\le\epsilon\qquad\forall i=1,\ldots,n\\
+-s_i&\le		      \epsilon\qquad\forall i=1,\ldots,n\\
+|c^Tx-b^Ty|&\le(1+|c^Tx+b^Ty|/2)\epsilon_{IPM}.
+\end{aligned}
+```
+
+In practice, the feasibility tolerances are readily satisfied when
+using interior point solvers. Hence their termination generally
+depends on satisfying the optimality tolerance, with relative
+feasibility satisfied to a higher tolerance than required. Thus the
+solution obtained using interior point solvers typically has small
+absolute feasibility errors.
+
+#### PDLP solutions
+
+The PDLP algorithm uses an independent [optimality tolerance](@ref
+option-pdlp-optimality-tolerance) (``\epsilon_{PDLP}``) that is equal
+to the other feasibility and optimality tolerances used by HiGHS. It
+determines values of ``x\ge0`` and ``y``, and chooses ``s`` to be the
+non-negative values of ``c-A^Ty``. Hence it guarantees primal and dual
+feasibility by construction. It terminates when
+
+```math
+\begin{aligned}
+\|Ax-b\|_2&\le (1+\|b\|_2)\epsilon_P\\
+\|c-A^Ty-s\|_2&\le (1+\|c\|_2)\epsilon_D\\
+|c^Tx-b^Ty|&\le (1+|c^Tx|+|b^Ty|)\epsilon_{PDLP}.
+\end{aligned}
+```
+
+Unlike interior point solvers, PDLP does not readily satisfy the
+relative feasibility tolerances. Although they and the optimality
+tolerance are satisfied on successful termination, the solution
+obtained may have meaningful absolute feasibility errors.
+
+#### HiGHS solutions
+
+The relative measures used by HiPO, IPX and PDLP assume that all
+components of the cost and RHS vectors are relevant. When an LP
+problem is in standard form this is true for ``b``, but not
+necessarily for the cost vector ``c``. Consider a large component of
+``c`` for which the corresponding reduced cost value in ``s`` is also
+large, in which case the LP solution is insensitive to the cost. This
+component will contribute significantly to ``\|c\|`` and, hence, the
+RHS of the dual residual condition, allowing large values of
+``\|c-A^Ty-s\|`` to be accepted. However, this can lead to
+unacceptably large absolute residual errors and non-optimal solutions
+being deemed "optimal". When equations in ``Ax=b`` correspond to
+inequality constraints with large RHS values and a slack variable (so
+the constraint is redundant) the same issue occurs in the case of
+primal residual errors. The solution of the LP is not sensitive to
+this large RHS value, but its contribution to ``||b||`` can allow
+large absolute primal residual errors to be overlooked.
+
+To make an informed assessment of whether an "optimal" solution
+obtained by HiPO, IPX or PDLP is acceptable, HiGHS computes infinity norm
+measures of ``b`` and ``c`` corresponding to the components that
+define the optimal solution. For ``c`` these are the components
+corresponding to positive values of ``x`` and reduced costs that are
+close to zero. For ``b``, these are the components corresponding to
+constraints that are (close to being) satisfied exactly. The resulting
+measures are smaller than ``\|b\|`` or ``\|c\|``, and may lead to
+relative measures of primal/dual residual errors or infeasibilities
+not being satisfied, so the status of the solver's "optimal" solution
+may be reduced to "unknown". When this happens - and possibly if
+tolerances on relative measures _have_ been satisfied - users can
+consult the absolute and relative measures available via
+[HighsInfo](@ref info-num-primal-infeasibilities).
+
+### Discrete optimization problems
+
+Discrete optimization problems, such as the mixed-integer programming
+(MIP) problems solved by HiGHS, have no local optimality
+conditions. Variables required to take integer values will do so to
+within the `mip_feasibility_tolerance`. Since MIP sub-problems are
+solved with the simplex solver, the values of the variables and
+constraints will satisfy absolute feasibility tolerances. Within the
+MIP solver, the value of `mip_feasibility_tolerance` is used for
+`primal_feasibility_tolerance` when solving LP sub-problems, and one
+tenth of this value is used for `dual_feasibility_tolerance`. Hence
+any value of `primal_feasibility_tolerance` (or
+`dual_feasibility_tolerance`) set by the user has no effect of the MIP
+solver.
+

data/ext/lpsolver-highs/docs/src/guide/numerics.md

@@ -0,0 +1,55 @@
+# [Numerical considerations](@id numerics)
+
+Optimization solvers cannot be expected to find the exact solution of
+a problem, since it may not be possible to represent that solution
+using floating-point arithemtic. However, solvers will typically run
+faster and find more accurate solutions if the problem has good
+numerical properties. Ideally the optimal value of all primal
+variables (and dual variables when relevant) will be of order
+unity. This typically occurs if all objective and constraint matrix
+coefficients, as well as finite variable and constraint bounds, are of
+order unity. Whilst there may be some reasons why this ideal cannot be
+achieved in all models, there are many pitfalls to avoid. For an
+insight into reasons why a model may have bad numerical properties and
+how to avoid them, users are recommended to study this [JuMP
+tutorial](https://jump.dev/JuMP.jl/stable/tutorials/getting_started/tolerances/). Improving
+the numerical properties of a model will typically lead to it being
+solved faster and more accurately/reliably, so the investment should
+pay off!
+
+Internally, the HiGHS continuous optimization solvers scale the
+constraint matrix to improve the numerical properties of the problem,
+[feasibility and optimality tolerances](@ref kkt) are determined with
+respect to the original, unscaled problem. However, faced with a model
+with bad numerical properties, there is only so much that HiGHS can do
+to solve it efficiently and accurately.
+
+If the optimal values of many variables in a model are typically very
+large, this can correspond to very large values of the objective
+coefficients and finite variable and constraint bounds. Since most of
+the HiGHS solvers terminate according to small absolute [feasibility
+tolerances](@ref kkt), large objective coefficients and bounds force
+the solvers to achieve an accuracy that may be unrealsitic in the
+context of a model. As well as having an impact on efficiency, the
+solver may ultimately be unable to achieve the required accuracy and
+fail. Objective coefficients and bounds that are less than the
+feasibility and optimality tolerances can also be problematic,
+although this is less common and less serious.
+
+HiGHS offers a facility to enable users to assess the consequences of
+better problem scaling, in cases where some objective coefficients or
+bounds are large, or if all objective coefficients or bounds are
+small. By setting the options [__user\_objective\_scale__](@ref
+option-user-objective-scale) and/or [__user\_bound\_scale__](@ref
+option-user-bound-scale), HiGHS will solve the given model with
+uniform scaling of the objective coefficients or bounds. Note that
+these options define the exponent in power-of-two scaling factors so
+that model accuracy is not compromised. After solving the problem,
+feasibility and optimality will be assessed for the original model,
+with a warning given if the tolerances are not satisfied. Note that
+uniform scaling of bounds on discrete variables is not possible, and
+is achieved implicitly by scaling their cost and matrix
+coefficients. Also, when bounds on variables in a quadratic
+programming problem are scaled up (down), the values in the Hessian
+matrix must be scaled down (up) so that the overall scaling of the
+objective is uniform.