Skip to content

Commit a4f7cc2

Browse files
committed
Merge branch 'latest' into version-bump-111
2 parents 9c9193a + dacd4ca commit a4f7cc2

26 files changed

+453
-185
lines changed

FEATURES.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ Add missing include to zstr needed for gcc v15 and clang v19 [#2313](https://git
88

99
Updates for intel llvm compiler on linux [#2257](https://github.com/ERGO-Code/HiGHS/pull/2257)
1010

11+
Build directory for Windows MSVC now `Release/bin` replacing `bin/Release` [#2376](https://github.com/ERGO-Code/HiGHS/pull/2376)
12+
1113
## Code changes
1214

1315
Fixed incorrect assertion in `HighsMipSolver::solutionFeasible()` (fixing [#2204](https://github.com/ERGO-Code/HiGHS/issues/2204))
@@ -22,6 +24,8 @@ By setting non-empty values of options `read_solution_file`, `read_basis_file`,
2224

2325
Bug [#2273](https://github.com/ERGO-Code/HiGHS/issues/2273) fixed
2426

27+
Added the feasibility jump heuristic as per [#1423](https://github.com/ERGO-Code/HiGHS/issues/1423). This is on by default, but using the option `mip_heuristic_run_feasibility_jump=false` switches it off.
28+
2529
ZI rounding and shifting MIP primal heuristics have been added (see [#2287](https://github.com/ERGO-Code/HiGHS/pull/2287)). They are off by default, but can be activated by setting the options `mip_heuristic_run_zi_round` and `mip_heuristic_run_shifting` to be true. Options `mip_heuristic_run_rins`, `mip_heuristic_run_rens` and `mip_heuristic_run_root_reduced_cost` to run the RINS, RENS and rootReducedCost heuristics have been added. These are true by default, but setting them to be false can accelerate the MIP solver on easy problems.
2630

2731
Added `Highs_changeRowsBoundsByRange` to C API, fixing [#2296](https://github.com/ERGO-Code/HiGHS/issues/2296)
@@ -52,3 +56,6 @@ Added a max scale factor (+1024) when scaling up coefficients in `preprocessBase
5256

5357
Renamed `HighsOptions::pdlp_d_gap_tol` to `HighsOptions::pdlp_optimality_tolerance` for consistency with IPM
5458

59+
Renamed `HighsOptions::complementarity_tolerance` to `HighsOptions::optimality_tolerance` for consistency with IPM and PDLP
60+
61+

app/RunHighs.cpp

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,7 @@ int main(int argc, char** argv) {
7575
// call this first so that printHighsVersionCopyright uses reporting
7676
// settings defined in any options file.
7777
highs.passOptions(loaded_options);
78+
// Log changes from the default option settings
7879
highs.writeOptions("", true);
7980

8081
// Lines to write out documentation of HighsOptions and HighsInfo

check/TestQpSolver.cpp

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -40,9 +40,9 @@ void testPrimalDualObjective(Highs& h,
4040
required_objective_function_value));
4141
REQUIRE(okValueDifference(alt_objective_function_value,
4242
required_objective_function_value));
43-
double complementarity_tolerance;
44-
h.getOptionValue("complementarity_tolerance", complementarity_tolerance);
45-
REQUIRE(fabs(info.primal_dual_objective_error) < complementarity_tolerance);
43+
double optimality_tolerance;
44+
h.getOptionValue("optimality_tolerance", optimality_tolerance);
45+
REQUIRE(fabs(info.primal_dual_objective_error) < optimality_tolerance);
4646
}
4747

4848
TEST_CASE("qp-unbounded", "[qpsolver]") {

docs/make.jl

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,11 +39,13 @@ Documenter.makedocs(
3939
strict = !("strict=false" in ARGS),
4040
doctest = ("doctest=only" in ARGS) ? :only : true,
4141
repo = "https://github.com/ERGO-Code/HiGHS/tree/latest{path}",
42-
linkcheck = true,
42+
linkcheck = false,
4343
linkcheck_ignore = [
4444
"https://crates.io/crates/highs",
4545
"https://crates.io/crates/good_lp",
4646
"https://link.springer.com/article/10.1007/s12532-017-0130-5",
47+
"https://link.springer.com/article/10.1007/s12532-020-00181-8",
48+
"https://github.com/ERGO-Code/HiGHS/blob/master/highs/Highs.h"
4749
],
4850
pages = [
4951
"About" => "index.md",
@@ -54,7 +56,8 @@ Documenter.makedocs(
5456
"guide/basic.md",
5557
"guide/further.md",
5658
"guide/advanced.md",
57-
"guide/highs-gpu.md"
59+
"guide/gpu.md",
60+
"guide/kkt.md"
5861
],
5962
"Data structures" => Any[
6063
"structures/index.md",

docs/src/executable.md

Lines changed: 21 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,12 @@
11
# [Executable](@id executable)
22

3-
HiGHS can run as a standalone program with a command-line interface. It solves an optimization problem provided by a model file. HiGHS supports the following model file formats:
4-
5-
- [MPS file format](https://en.wikipedia.org/wiki/MPS_(format))
6-
- (CPLEX) [LP file format](https://docs.mosek.com/latest/capi/lp-format.html)
3+
HiGHS can run as a stand-alone program with a command-line
4+
interface. It solves an optimization problem provided by either an
5+
[MPS](https://docs.gurobi.com/projects/optimizer/en/current/reference/fileformats/modelformats.html#mps-format)
6+
file, or
7+
[LP](https://docs.gurobi.com/projects/optimizer/en/current/reference/fileformats/modelformats.html#lp-format)
8+
file. Note that HiGHS cannot read the [lpsolve LP file
9+
format](https://lpsolve.sourceforge.net/5.5/lp-format.htm).
710

811
### Running the executable
912

@@ -19,9 +22,10 @@ path name can be given.
1922

2023
### Command line options
2124

22-
When HiGHS is run from the command line, some fundamental option values may be
23-
specified directly. Many more may be specified via a file. Formally, the usage
24-
is:
25+
HiGHS is controlled by [option](@ref options-intro) values. When it is
26+
run from the command line, some fundamental option values may be
27+
specified directly. Many more may be specified via a file containing
28+
HiGHS options settings. Formally, the usage is:
2529

2630
```shell
2731
$ bin/highs --help
@@ -64,7 +68,16 @@ options:
6468
```
6569

6670
The [list of options](@ref option-definitions) section gives a full
67-
list of options, and the format in which they are specified.
71+
list of options, and their default values. In a file containing HiGHS
72+
options they are specified as `name = value`, with one per line, and
73+
any line beginning with `#` treated as a comment. For example, the
74+
primal-dual hybrid gradient method for LP (PDLP) is used with all
75+
feasibility and optimality tolerances set to `1e-4` if HiGHS reads the
76+
following in its options file.
77+
```shell
78+
solver = pdlp
79+
kkt_tolerance = 1e-4
80+
```
6881

6982
### Return code values
7083

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,16 @@
1-
# [HiGHS on a GPU](@id highs-gpu)
1+
# [GPU acceleration](@id gpu)
22

33
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.
44

55
### PDLP: A health warning
66

77
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.
88

9-
If you use the HiGHS PDLP solver, in the first instance it is recommended that you increase the primal and dual feasibility tolerances to `1e-4`, since these are the default values used natively by cuPDLP-C, and will result in the algorithm terminating much sooner.
9+
#### Termination criteria
10+
11+
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 feasibilty and optimality tolerances](@ref kkt), this is due to PDLP using relative termination criteria.
12+
13+
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.
1014

1115
### Requirements
1216

docs/src/guide/kkt.md

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
# [Feasibilty and optimality](@id kkt)
2+
3+
Mathematically, continuous optimization problems have exact feasibilty
4+
and optimality conditions. However, since solvers cannot always
5+
satisfy these conditions exactly when using floating-point arithmetic,
6+
they do so to within tolerances. As explored below, some solvers aim
7+
to satisfy those tolerances absolutely, and others aim to satisfy
8+
tolerances relative to problem data. When tolerances are satisfied
9+
relatively, they are generally not satisfied absolutely. The use of
10+
tolerances relative to problem data is not consistent across solvers,
11+
and can give a misleading claim of optimality. To achieve consistency,
12+
HiGHS reassesses the optimal solution claimed by such a solver in a
13+
reasonable and uniform manner.
14+
15+
### Feasibilty and optimality conditions
16+
17+
To discuss tolerances and their use in different solvers, consider the
18+
standard form linear programming (LP) problem with ``n`` variables and
19+
``m`` equations (``n\ge m``).
20+
21+
```math
22+
\begin{aligned}
23+
\textrm{minimize} \quad & c^T\! x \\
24+
\textrm{subject to} \quad & Ax = b \\
25+
& x \ge 0,
26+
\end{aligned}
27+
```
28+
29+
The feasibilty and optimality conditions (KKT conditions) are that, at
30+
a point ``x``, there exist (row) dual values ``y`` and reduced costs
31+
(column dual values) ``s`` such that
32+
33+
```math
34+
\begin{aligned}
35+
Ax=b&\qquad\textrm{Primal~equations}\\
36+
A^Ty+s=c&\qquad\textrm{Dual~equations}\\
37+
x\ge0&\qquad\textrm{Primal~feasibility}\\
38+
s\ge0&\qquad\textrm{Dual~feasibility}\\
39+
c^Tx-b^Ty=0&\qquad\textrm{Optimality}
40+
\end{aligned}
41+
```
42+
43+
The optimality condition is equivalent to the complementarity
44+
condition that ``x^Ts=0``. Since any LP problem can be transformed
45+
into standard form, the following discussion loses no generality. This
46+
discussion also largely applies to quadratic programming (QP)
47+
problems, with the differences explored below.
48+
49+
### The HiGHS feasibility and optimality tolerances
50+
51+
HiGHS has separate tolerances for the following, listed with convenient mathematical notation
52+
53+
- [Primal feasibility](@ref option-primal-feasibility-tolerance) (``\epsilon_P``)
54+
- [Dual feasibility](@ref option-dual-feasibility-tolerance) (``\epsilon_D``)
55+
- Residual errors in the [primal equations](@ref option-primal-residual-tolerance) (``\epsilon_R``)
56+
- Residual errors in the [dual equations](@ref option-dual-residual-tolerance) (``\epsilon_C``)
57+
- [Optimality](@ref option-optimality-tolerance) (``\epsilon_{O}``)
58+
59+
All are set to the same default value of ``10^{-7}``. Although each
60+
can be set to different values by the user, if the user wishes to
61+
solve LPs to a general lower or higher tolerance, the value of the
62+
[KKT tolerance](@ref option-kkt-tolerance) can be changed from this
63+
default value.
64+
65+
### When HiGHS yields an optimal solution
66+
67+
When HiGHS returns a model status of optimal, the solution will
68+
satisfy feasibility and optimality tolerances absolutely or relatively
69+
according to whether the solver yields a basic solution.
70+
71+
### Solutions with a corresponding basis
72+
73+
The HiGHS simplex solvers and the interior point solver after
74+
crossover yield an optimal basic solution of the LP, consisting of
75+
``m`` basic variables and ``n-m`` nonbasic variables. At any basis,
76+
the nonbasic variables are zero, and values for the basic variables
77+
are given by solving a linear system of equations. Values for the row
78+
dual values (``y``) can be computed by solving a linear system of equations,
79+
and the column dual values are then given by ``s=c-A^Ty``. With exact
80+
arithmetic, the basic dual values are zero by construction.
81+
82+
When primal and dual values are computed using floating-point
83+
arithmetic, the basic dual values are set to zero so the optimality
84+
condition holds by construction. However, the primal and dual
85+
equations may not be satisfied exactly, so have nonzero
86+
residuals. Fortunately, when solving a linear system of equations
87+
using a stable technique, any residuals are small relative to the RHS
88+
of the equations, whatever the condition of the matrix of
89+
coefficients. Hence HiGHS does not assess the primal residuals, or the
90+
dual residuals for basic variables. Thus optimality for a basic
91+
solution is assessed by HiGHS according to whether the following
92+
conditions hold
93+
94+
```math
95+
\begin{aligned}
96+
x_i\ge-\epsilon_P&\qquad\forall i=1,\ldots,n\\
97+
s_i\ge-\epsilon_D&\qquad\forall i=1,\ldots,n.
98+
\end{aligned}
99+
```
100+
101+
The HiGHS active set QP solver has an objective function ``(1/2)x^TQx + c^Tx``,
102+
and maintains the QP equivalent of a basis in which a subset
103+
of (up to ``n``) variables are zero. However, there are variables
104+
that are off their bounds whose reduced costs are not zero by
105+
construction. At an optimal solution they will only be less than a
106+
dual feasibility tolerance in magnitude, so the optimality condition
107+
will not be satisfied by construction. The primal and dual equations
108+
(where the latter is ``A^Ty+s=Qx+c``) will be satisfied with small
109+
residuals. Optimality is assessed by HiGHS according to whether primal
110+
and dual feasibility is satisfied to within the corresponding
111+
tolerance.
112+
113+
114+
### Solutions without a corresponding basis
115+
116+
The HiGHS PDLP solver and the interior point solver without crossover
117+
(IPX) yield "optimal" primal and dual values that satisfy internal
118+
conditions for termination of the underlying algorithm. These
119+
conditions are discussed below, and are used for good reason. However
120+
they can lead to a misleading claim of optimality.
121+
122+
#### Interior point solutions
123+
124+
The interior point algorithm uses a single feasibility tolerance
125+
``\epsilon=\min(\epsilon_P, \epsilon_D)``, and an independent
126+
[optimality tolerance](@ref option-ipm-optimality-tolerance)
127+
(``\epsilon_{IPM}``) that, by default, is (currently) ten times
128+
smaller than the other feasibility and optimality tolerances used by
129+
HiGHS. It terminates when
130+
131+
```math
132+
\begin{aligned}
133+
\|Ax-b\|_\infty&\le(1+\|b\|_\infty)\epsilon_R\\
134+
\|c-A^Ty+s\|_\infty&\le(1+\|c\|_\infty)\epsilon_C\\
135+
-x_i&\le\epsilon\qquad\forall i=1,\ldots,n\\
136+
-s_i&\le \epsilon\qquad\forall i=1,\ldots,n\\
137+
|c^Tx-b^Ty|&\le(1+|c^Tx+b^Ty|/2)\epsilon_{IPM}.
138+
\end{aligned}
139+
```
140+
141+
#### PDLP solutions
142+
143+
The PDLP algorithm uses an independent [optimality tolerance](@ref
144+
option-pdlp-optimality-tolerance) (``\epsilon_{PDLP}``) that is equal
145+
to the other feasibility and optimality tolerances used by HiGHS. It
146+
determines values of ``x\ge0`` and ``y``, and chooses ``s`` to be the
147+
non-negative values of ``c-A^Ty``. Hence it guarantees primal and dual
148+
feasibility by construction. It terminates when
149+
150+
```math
151+
\begin{aligned}
152+
\|Ax-b\|_2&\le (1+\|b\|_2)\epsilon_P\\
153+
\|c-A^Ty-s\|_2&\le (1+\|c\|_2)\epsilon_D\\
154+
|c^Tx-b^Ty|&\le (1+|c^Tx|+|b^Ty|)\epsilon_{PDLP}.
155+
\end{aligned}
156+
```
157+
158+
#### HiGHS solutions
159+
160+
The relative measures used by PDLP and IPX assume that all components
161+
of the cost and RHS vectors are relevant. When an LP problem is in
162+
standard form this is true for ``b``, but not necessarily for the cost
163+
vector ``c``. Consider a large component of ``c`` for which the
164+
corresponding reduced cost value in ``s`` is also large, in which case
165+
the LP solution is insensitive to the cost. This component will
166+
contribute significantly to ``\|c\|`` and, hence, the RHS of the dual
167+
residual condition, allowing large values of ``\|c-A^Ty-s\|`` to be
168+
accepted. However, this can lead to unacceptably large absolute
169+
residual errors and non-optimal solutions being deemed "optimal". When
170+
equations in ``Ax=b`` correspond to inequality constraints with large
171+
RHS values and a slack variable (so the constraint is redundant) the
172+
same issue occurs in the case of primal residual errors. The solution
173+
of the LP is not sensitive to this large RHS value, but its
174+
contribution to ``||b||`` can allow large absolute primal residual
175+
errors to be overlooked.
176+
177+
To make an informed assessment of whether an "optimal" solution
178+
obtained by IPX or PDLP is acceptable, HiGHS computes infinity norm
179+
measures of ``b`` and ``c`` corresponding to the components that
180+
define the optimal solution. For ``c`` these are the components
181+
corresponding to positive values of ``x`` and reduced costs that are
182+
close to zero. For ``b``, these are the components corresponding to
183+
constraints that are (close to being) satisfied exactly. The resulting
184+
measures are smaller than ``\|b\|`` or ``\|c\|``, and may lead to
185+
relative measures of primal/dual residual errors or infeasibilities
186+
not being satisfied, so the status of the solver's "optimal" solution
187+
may be reduced to "unknown". When this happens - and possibly if
188+
tolerances on relative measures _have_ been satisfied - users can
189+
consult the absolute and relative measures available via
190+
[HighsInfo](@ref info-num-primal-infeasibilities).
191+
192+
### Discrete optimization problems
193+
194+
Discrete optimization problems, such as the mixed-integer programming
195+
(MIP) problems solved by HiGHS, have no local optimality
196+
conditions. Variables required to take integer values will do so to
197+
within the `mip_feasibility_tolerance`. Since MIP sub-problems are
198+
solved with the simplex solver, the values of the variables and
199+
constraints will satisfy absolute feasibility tolerances. Within the
200+
MIP solver, the value of `mip_feasibility_tolerance` is used for
201+
`primal_feasibility_tolerance` when solving LP sub-problems, and one
202+
tenth of this value is used for `dual_feasibility_tolerance`. Hence
203+
any value of `primal_feasibility_tolerance` (or
204+
`dual_feasibility_tolerance`) set by the user has no effect of the MIP
205+
solver.
206+

docs/src/index.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -31,15 +31,15 @@ Read the [Terminology](@ref) section for more details.
3131

3232
## Using HiGHS
3333

34-
HiGHS can be used as a standalone executable on Windows, Linux and MacOS. There
34+
HiGHS can be used as a stand-alone executable on Windows, Linux and MacOS. There
3535
is also a C++11 library that can be used within a C++ project or, via its C, C#,
36-
FORTRAN, Julia, and Python interfaces.
36+
FORTRAN, Julia, Python and Rust interfaces.
3737

3838
Get started by following [Install HiGHS](@ref).
3939

4040
## Overview
4141

42-
The standalone [executable](@ref executable) allows models to be solved from
42+
The stand-alone [executable](@ref executable) allows models to be solved from
4343
[MPS](https://en.wikipedia.org/wiki/MPS_(format)) or (CPLEX)
4444
[LP](https://web.mit.edu/lpsolve/doc/CPLEX-format.htm) files, with full control
4545
of the HiGHS run-time options, and the solution can be written to files in human

docs/src/installation.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
## Compile from source
44

55
HiGHS uses CMake as build system, and requires at least version
6-
3.15. Details about building from source using cmake can be found in `HiGHS/cmake/README.md`.
6+
3.15. Details about building from source using CMake can be found in `HiGHS/cmake/README.md`.
77

88
## Install via a package manager
99

@@ -21,7 +21,7 @@ Precompiled static executables are available for a variety of platforms at
2121
* [https://github.com/JuliaBinaryWrappers/HiGHSstatic_jll.jl/releases](https://github.com/JuliaBinaryWrappers/HiGHSstatic_jll.jl/releases)
2222

2323
Multiple versions are available. Each version has the form `vX.Y.Z`. In
24-
general, you should choose the most recent versinon.
24+
general, you should choose the most recent version.
2525

2626
To install a precompiled binary, download the appropriate `HiGHSstatic.vX.Y.Z.[platform-string].tar.gz`
2727
file and extract the executable located at `/bin/highs`.

docs/src/interfaces/cpp/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ HiGHS uses CMake (minimum version 3.15) as a build system, and can use the follo
1818

1919
Instructions for building HiGHS from source code are in `HiGHS/cmake/README.md`.
2020

21-
The simplest setup is to build HiGHS in a build directory within the root direcory. The
21+
The simplest setup is to build HiGHS in a build directory within the root directory. The
2222
name of the build folder is arbitrary but, assuming it is `build`,
2323
the sequence of commands is as follows
2424

0 commit comments

Comments
 (0)