Updated docs/src/guide/kkt.md and added qpsolver/README.md and lp_data/UserScale.md

Author: jajhall

docs/README.md

@@ -113,11 +113,12 @@ tolerance.
 
 ### Solutions without a corresponding basis
 
-The HiGHS PDLP solver and the interior point solver without crossover
-(IPX) 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
-they can lead to a misleading claim of optimality.
+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
 
@@ -138,6 +139,13 @@ HiGHS. It terminates when
 \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
@@ -155,27 +163,32 @@ feasibility by construction. It terminates when
 \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 PDLP and IPX 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.
+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 IPX or PDLP is acceptable, HiGHS computes infinity norm
+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

docs/src/guide/kkt.md

@@ -0,0 +1,116 @@
+# HiGHS - User bound and cost scaling
+
+User bound and cost scaling have been introduced to assess solver
+performance if a user's model were better scaled. It is achieved using
+the integer `HighsOptions::user_bound_scale` and
+`HighsOptions::user_cost_scale` options, where the scaling factor
+itself is two to the power of the option value. For simplicity, the
+scaling is applied to the incumbent model - as if the model had been
+well scaled by the user.
+
+Scaling of costs is simple, since all costs are scaled. Scaling of LPs
+is also simple since all finite column and row bounds are scaled, so
+the constraint matrix is unchanged. However, nonzero (finite) bounds
+on non-continuous variables cannot be scaled, since it would change
+the number of feasible values. For a non-continuous variable, its
+contributions to the objective and constraint activites are scaled by
+scaling the cost coefficient and matrix values.
+
+In summary, the incumbent data affected by user bound and cost scaling
+are as follows
+
+- User bound scaling affects
+  - Costs of non-continuous variables — using `userScaleCosts`
+  - Matrix coefficients of non-continuous variables — using `userScaleMatrix`
+  - Bounds of continuous variables — using `userScaleColBounds`
+  - All row bounds — using `userScaleRowBounds`
+- User cost scaling affects
+  - All column costs — using `userScaleCosts`
+
+The only exception is the case of changes driven by a
+`HighsIndexCollection`, where scaling is performed on individual
+entries
+
+## Where user scaling takes place
+
+User scaling typically takes place when a model has been passed to
+HiGHS and the values of `user_bound_scale` or `user_cost_scale` are
+nonzero, or when the values of `user_bound_scale` or `user_cost_scale`
+are changed after a model has been passed to HiGHS. However, for
+consistency, when the incumbent model has been scaled that must be
+maintained when other operations take place.
+
+Although scaling is more likely to be done to reduce the magnitude of
+bounds and costs, extreme scaling up can make increase the magnitude
+of bounds and costs beyond the value at which HiGHS considers them to
+be infinite. This (arguably) changes the model fundamentally. Hence,
+whenever user scaling is applied, an initial pass is made to determine
+whether it generates infinite bounds or costs or large matrix values,
+returning an error if this occurs. If they only create small matrix
+values, then a warning is issued.
+
+### `Highs::passModel`
+
+When a model is passed to HiGHS, if `user_bound_scale` or
+`user_cost_scale` are nonzero then their use is considered. If they
+create no infinte bounds or costs, or large matrix values, then the
+user scaling is applied, otherwise an error is returned. If they only
+create small matrix values, then the user scaling is applied, and a
+warning is issued.
+
+### `Highs::addColsInterface`
+
+When new columns are added to a model, they have no integrality, so
+the scaling of their bounds and costs is simple. Hence,
+`user_bound_scale` is applied uniformly to the (local) lower and upper
+bounds of the new columns, and `user_cost_scale` is applied uniformly
+to the (local) costs of the new columns.
+
+### `Highs::addRowsInterface`
+
+When new rows are added to a model, any column integrality must be
+respected. Hence `user_bound_scale` must be applied to the columns of
+non-continuous variables in the (local) matrix, and must be applied
+uniformly to the lower and upper bounds of the new rows
+
+### `Highs::changeIntegralityInterface`
+
+When integrality changes, the simplest thing to do is first remove any
+scaling specific to non-continuous variables — by using the negation
+of `user_bound_scale` to scale the costs and matrix coefficient for
+non-continuous variables. Then, after updating the integrality, use
+`user_bound_scale` to scale the costs and matrix coefficient for
+non-continuous variables.
+
+### `Highs::changeCostsInterface`
+
+When costs change, `user_bound_scale` must be applied to the changed
+costs of non-continuous variables, and `user_cost_scale` must be
+applied uniformly.
+
+### `Highs::changeColBoundsInterface`
+
+When column bounds change, `user_bound_scale` must be applied to the
+changed bounds of continuous variables
+
+### `Highs::changeRowBoundsInterface`
+
+When row bounds change, `user_bound_scale` must be applied uniformly
+to the changed bounds
+
+### `Highs::changeCoefficientInterface
+
+The coefficient is scaled using `user_bound_scale` if is corresponds
+to a non-continuous variable
+
+### `Highs::optionChangeAction`
+
+When `user_bound_scale` or `user_cost_scale` change (the difference
+in) this value must be applied as for a whole model. Since this is
+typically the first application of user scaling, there is a check for
+infinte bounds or costs, and whichever of `user_bound_scale` and
+`user_cost_scale` causes then is rejected with an error return.
+
+### `Highs::passModel`
+
+