lpsolver 0.1.0 → 0.2.0

data/ext/lpsolver-highs/docs/src/solvers.md

@@ -0,0 +1,168 @@
+# [Solvers](@id solvers)
+
+## Introduction
+
+HiGHS has implementations of the three main solution techniques for LP
+(simplex, interior point and primal-dual hybrid gradient), two
+solution techniques for QP (active set and interior point), and one
+MIP solver. By default HiGHS will choose the most appropriate
+technique for a given problem, but this can be over-ridden by setting
+the option [__solver__](@ref option-solver).
+
+What follows below is an overview of all the solvers and key
+[options](@ref option-definitions) that define their algorithmic
+features. The relevant [__solver__](@ref option-solver) settings for
+each problem type, and their interpretation when incompatible with the
+problem type, are then [summarised](@ref solver-option).
+
+## LP
+
+#### [Simplex](@id solvers-simplex)
+
+HiGHS has efficient implementations of both the primal and dual
+simplex methods, although the dual simplex solver is likely to be
+faster and is more robust, so is used by default. Similarly, for
+reasons discussed in the [parallelism](@ref) section, the parallel
+dual simplex solver is unlikely to be worth using. The novel features
+of the dual simplex solver are described in
+
+_Parallelizing the dual revised simplex method_, Q. Huangfu and
+J. A. J. Hall, Mathematical Programming Computation, 10 (1), 119-142,
+2018 [DOI:
+10.1007/s12532-017-0130-5](https://link.springer.com/article/10.1007/s12532-017-0130-5).
+
+* Setting the option [__solver__](@ref option-solver) to "simplex" forces the simplex solver to be used
+* The option [__simplex\_strategy__](@ref option-simplex-strategy)
+  determines whether the primal solver or one of the parallel solvers is
+  to be used.
+
+#### [Interior point](@id solvers-lp-ipm)
+
+HiGHS has two interior point (IPM) solvers:
+
+* IPX is based on the preconditioned conjugate gradient method, as discussed in
+
+  _Implementation of an interior point method with basis
+  preconditioning_, Mathematical Programming Computation, 12, 603-635,
+  2020. [DOI:
+  10.1007/s12532-020-00181-8](https://link.springer.com/article/10.1007/s12532-020-00181-8).
+
+  This solver is serial.
+
+* HiPO is based on a direct factorisation, as discussed in 
+
+  _A factorisation-based regularised interior point method using the
+  augmented system_, F. Zanetti and J. Gondzio, 2025, [available on
+  arxiv](https://arxiv.org/abs/2508.04370)
+
+  This solver is parallel.
+
+  The [__hipo\_system__](@ref option-hipo-system) option can be used to
+  select the approach to use when solving the Newton systems within
+  the interior point solver: select "augmented" to force the solver to
+  use the augmented system, "normaleq" for normal equations, or
+  "choose" to leave the choice to the solver.
+
+  The option [__hipo\_ordering__](@ref option-hipo-ordering) can be used
+  to select the fill-reducing heuristic to use during the
+  factorisation:
+  
+  * Nested dissection, obtained setting the option
+    [__hipo\_ordering__](@ref option-hipo-ordering) to "metis".
+  
+  * Approximate minimum degree, obtained setting the option
+    [__hipo\_ordering__](@ref option-hipo-ordering) to "amd".
+  
+  * Reverse Cuthill-McKee, obtained setting the option
+    [__hipo\_ordering__](@ref option-hipo-ordering) to "rcm".
+
+For small LPs, IPX is often faster than HiPO. However, as problem size
+grows, HiPO becomes more efficient, and its advantage can be more
+than an order of magnitude.
+
+#### Primal-dual hybrid gradient method (PDLP)
+
+HiGHS includes the [
+cuPDLP-C](https://github.com/COPT-Public/cuPDLP-C) primal-dual hybrid
+gradient method for LP (PDLP), and also has a native PDLP solver,
+HiPDLP. On Linux and Windows, these solvers can be run on an NVIDIA
+[GPU](@ref gpu). On a CPU, they are unlikely to be competitive with
+the HiGHS interior point or simplex solvers.
+
+  * Setting the option [__solver__](@ref option-solver) to "pdlp" forces the cuPDLP-C solver to be used
+  * Setting the option [__solver__](@ref option-solver) to "hipdlp" forces the HiPDLP solver to be used
+
+### Basic solution
+
+The simplex solver always generates a [basic solution](@ref
+term-basic-solution). This is a solution at a vertex of the feasible
+region of the LP.
+
+By default, the IPM solvers also generate a basic solution by running
+a procedure known as "crossover". This can occasionally be very
+expensive so if users require only a solution to the LP, and not a
+basic solution, crossover can be suppressed. This is done by setting
+the [run\_crossover](@ref option-run-crossover) option to
+"off". However, if the IPM solver terminates without satsifying the
+[feasibility and optimality](@ref kkt) conditions, HiGHS will not
+claim optimality. Hence it is better to set the __run\_crossover__
+option to "choose", in which case crossover will be run if the IPM
+solver terminates without determining optimality.
+
+The PDLP solver does not generate a basic solution. Currently it has
+no crossover procedure to obtain one.
+
+When modifications have been made to an LP problem, the simplex solver
+(only) can solve the modified problem from the optimal basis of the
+original LP, a process known as ["hot starting"](@ref hot-start-lp).
+
+## QP
+
+HiGHS has two solvers for convex QP: a primal active set method, and
+an interior point method. The active set implementation uses a dense
+Cholesky factorization of the reduced Hessian, and the the limit on
+its dimension is determined by the option
+[__qp\_nullspace\_limit__](@ref option-qp-nullspace-limit). The
+interior point solver is HiPO, so see [above](@ref solvers-lp-ipm) for
+the key algorithmic options.
+
+## MIP
+
+MIPs are solved using a sophisticated branch-and-cut solver. This is
+largely single-threaded, although a prototype multithreaded solver was
+completed in February 2026, and is expected to be released by
+June. Users can choose the solver for LP sub-problems as follows
+
+* LPs where an advanced basis is not known. This is generally the case
+  at the root node of the branch-and-bound tree, but can occur at
+  other times in the MIP solution process. By default the simplex
+  solver is used, but the [__mip\_lp\_solver__](@ref
+  option-mip-lp-solver) option allows the user to determine whether
+  one of the IPM solvers is used.
+
+* LPs where an interior point solver must be used. This is generally
+  when computing the analytic centre of the constraints for the
+  centralised rounding heuristic. By default IPX is used, but the
+  [__mip\_ipm\_solver__](@ref option-mip-ipm-solver) option allows the
+  user to determine whether HiPO is used.
+
+Otherwise, for LPs where an advanced basis is known, only the simplex
+solver can be used.
+
+## [Summary](@id solver-option)
+
+The option [__solver__](@ref option-solver) can be set to:
+* "simplex", which selects the simplex solver.
+* "ipm", which selects the HiPO solver (or IPX if HiPO is not available in the build).
+* "ipx", which selects the IPX solver.
+* "hipo", which selects the HiPO solver, for both LP and QP.
+* "pdlp", which selects the cuPDLP-C solver.
+* "hipdlp", which selects the HiPDLP solver.
+* "qpasm", which selects the QP active-set method.
+* "choose", which selects the default solver for the given problem ("simplex" for LP, "qpasm" for QP).
+
+The option [__solver__](@ref option-solver) is ignored and the default solver is used if:
+* The problem is an LP and __solver__ is set to "qpasm".
+* The problem is a QP and __solver__ is set to "simplex", "ipx", "pdlp" or "hipdlp".
+* The problem is a MIP and __solver__ is not set to "choose".
+

data/ext/lpsolver-highs/docs/src/structures/classes/HighsHessian.md

@@ -0,0 +1,9 @@
+# HighsHessian
+
+A Hessian matrix is communicated via an instance of the HighsHessian class.
+
+- `dim_`: Scalar of type integer - Dimension of the Hessian
+- `format_`: Scalar of [HessianFormat](@ref) type - Format of the Hessian
+- `start_`: Vector of integer type - Start of each compressed column in the Hessian
+- `index_`: Vector of integer type - Indices of the nonzeros in the Hessian
+- `value_`: Vector of double type - Values of the nonzeros in the Hessian

data/ext/lpsolver-highs/docs/src/structures/classes/HighsIis.md

@@ -0,0 +1,16 @@
+# HighsIis
+
+Irreducible infeasibility system (IIS) data are communicated via an instance of the `HighsIis` class.
+
+- `valid_`: The data in the `HighsIis` instance is valid
+- `strategy_`: The IIS strategy used
+- `col_index_`: The indices of model columns in the IIS
+- `row_index_`: The indices of model rows in the IIS
+- `col_bound_`: The bounds on each column that define the IIS
+- `row_bound_`: The bounds on each row that define the IIS
+- `col_status_`: Indicates whether a column in the model is in an IIS, may be in an IIS, or is not in an IIS
+- `row_status_`: Indicates whether a row in the model is in an IIS, may be in an IIS, or is not in an IIS
+- `info_`: Data on the time and number of simplex iterations required to form the IIS
+- `model_`: A [HighsModel](@ref) consisting of the variables, constraints and bounds in the IIS. Currently only its [HighsLp](@ref) instance is relevant
+
+

data/ext/lpsolver-highs/docs/src/structures/classes/HighsLp.md

@@ -0,0 +1,19 @@
+# HighsLp
+
+An LP model is communicated via an instance of the `HighsLp` class
+
+- `num_col_`: Scalar of type integer - Number of columns in the model
+- `num_row_`: Scalar of type integer - Number of rows in the model
+- `col_cost_`: Vector of type double - Coefficients of the linear term in the objective function
+- `col_lower_`: Vector of type double - Lower bounds on the variables
+- `col_upper_`: Vector of type double - Upper bounds on the variables
+- `row_lower_`: Vector of type double - Lower bounds on the constraints
+- `row_upper_`: Vector of type double - Upper bounds on the constraints
+- `a_matrix_`: Instance of [HighsSparseMatrix](@ref) class - Constraint matrix
+- `sense_`: Scalar of type [ObjSense](@ref) - Optimization sense of the model
+- `offset_`: Scalar of type double - Constant term in the objective function
+- `model_name_`: Scalar of type string - Name of the model
+- `objective_name_`: Scalar of type string - Name of the objective function
+- `col_names_`: Vector of type string - Names of the variables
+- `row_names_`: Vector of type string - Names of the constraints
+- `integrality_`: Vector of type [HighsVarType](@ref) - Type of each variable

data/ext/lpsolver-highs/docs/src/structures/classes/HighsModel.md

@@ -0,0 +1,6 @@
+# HighsModel
+
+A QP model is communicated via an instance of the HighsModel class
+
+- `lp_`: Instance of [HighsLp](@ref) class - LP components of the model
+- `hessian_`: Instance of [HighsHessian](@ref) class - Hessian matrix

data/ext/lpsolver-highs/docs/src/structures/classes/HighsSparseMatrix.md

@@ -0,0 +1,10 @@
+# HighsSparseMatrix
+
+The constraint matrix of an LP model is communicated via an instance of the HighsSparseMatrix class
+
+- `format_`: Scalar of [MatrixFormat](@ref) type - Format of the matrix
+- `num_col_ `: Scalar of integer type - Number of columns in the matrix
+- `num_row_`: Scalar of integer type - Number of rows in the matrix
+- `start_`: Vector of integer type - Start of each compressed vector in the matrix
+- `index_`: Vector of integer type - Indices of the nonzeros in the matrix
+- `value_`: Vector of double type - Values of the nonzeros in the matrix

data/ext/lpsolver-highs/docs/src/structures/classes/index.md

@@ -0,0 +1,11 @@
+# [Overview](@id classes-overview)
+
+The data members of fundamental classes in HiGHS are defined in this section.
+
+ * [HighsSparseMatrix](@ref)
+ * [HighsLp](@ref)
+ * [HighsHessian](@ref)
+ * [HighsModel](@ref)
+ * [HighsIis](@ref)
+
+Class data members for internal use only are not documented.

data/ext/lpsolver-highs/docs/src/structures/enums.md

@@ -0,0 +1,114 @@
+# [Enums](@id structures-enums)
+
+The members of the fundamental HiGHS enums are defined below. If `Enum` refers
+to a particular enum, and `Member` to a particular member, the members are
+available as follows.
+
+ * Python: `highspy.Enum.Member`
+ * C++: `Enum::Member`
+
+Members for internal use only are not documented.
+
+## HighsStatus
+
+This is (part of) the return value of most HiGHS methods:
+
+ * `kError`: The method has exposed an error
+ * `kOk`: The method has completed successfully
+ * `kWarning`: The method has recovered from an unusual event, or has terminated
+  due to reaching a time or iteration limit
+
+## MatrixFormat
+
+This defines the format of a [HighsSparseMatrix](@ref):
+
+ * `kColwise`: The matrix is stored column-wise
+ * `kRowwise`: The matrix is stored row-wise
+
+## ObjSense
+
+This defines optimization sense of a [HighsLp](@ref):
+
+ * `kMinimize`: The objective is to be minimized
+ * `kMaximize`: The objective is to be maximized
+
+## HighsVarType
+
+This defines the feasible values of a variable within a model:
+
+ * `kContinuous`: The variable can take continuous values between its bounds
+ * `kInteger`: The variable must take integer values between its bounds
+ * `kSemiContinuous`: The variable must be zero or take continuous values between its bounds
+ * `kSemiInteger`: The variable must be zero or take integer values between its bounds
+
+## HessianFormat
+
+This defines the format of a [HighsHessian](@ref):
+
+ * `kTriangular`: The lower triangular component of the Hessian is stored column-wise or, equivalently, the upper triangular component is stored row-wise 
+ * `kSquare`: The whole Hessian ``Q`` is stored column-wise. This is for input only: internally the Hessian is stored in `kTriangular` format
+
+## SolutionStatus
+
+This defines the nature of any primal or dual solution information:
+
+ * `kSolutionStatusNone`: There is no solution information
+ * `kSolutionStatusInfeasible`: The solution is not feasible
+ * `kSolutionStatusFeasible`: The solution is feasible
+
+## BasisValidity
+
+This defines the nature of any basis information:
+
+ * `kBasisValidityInvalid`: There is no basisn information
+ * `kBasisValidityValid`: The basis information is valid
+
+## HighsModelStatus
+
+This defines the status of the model after a call to `run`
+
+ * `kNotset`: The model status has not been set
+ * `kModelError`: There is an error in the model
+ * `kSolveError`: There has been an error when solving the model
+ * `kModelEmpty`: The model is empty
+ * `kOptimal`: The model has been solved to optimality
+ * `kInfeasible`: The model is infeasible
+ * `kUnboundedOrInfeasible`: The model is unbounded or infeasible
+ * `kUnbounded`: The model is unbounded
+ * `kObjectiveBound`: The bound on the model objective value has been reached
+ * `kObjectiveTarget`: The target value for the model objective has been reached
+ * `kTimeLimit`: The run time limit has been reached
+ * `kIterationLimit`: The iteration limit has been reached
+ * `kSolutionLimit`: The MIP solver has reached the limit on the number of LPs solved
+ * `kInterrupt`: The solver has been interrupted by the user
+ * `kMemoryLimit`: The solver has been unable to allocate sufficient memory
+ * `kUnknown`: The model status is unknown
+
+## HighsBasisStatus
+
+This defines the status of a variable (or slack variable for a constraint) in a
+basis:
+
+ * `kLower`: The variable is nonbasic at its lower bound (or fixed value)
+ * `kBasic`: The variable is basic
+ * `kUpper`: The variable is at its upper bound
+ * `kZero`: A free variable is nonbasic and set to zero
+ * `kNonbasic`: The variable is nonbasic
+
+## HighsOptionType
+
+This defines the types of option values that control HiGHS:
+
+ * `kBool`: The option type is boolean
+ * `kInt`: The option type is integer
+ * `kDouble`: The option type is double
+ * `kString`: The option type is string
+
+## HighsInfoType
+
+This defines the types of (scalar) information available after a call to `run`:
+
+ * `kInt64`: The information type is 64-bit integer
+ * `kInt`: The information type is integer
+ * `kDouble`: The information type is double
+

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

@@ -0,0 +1,12 @@
+# [Introduction](@id structures-intro)
+
+There are several specialist data structures that can be used to
+interact with HiGHS when using [`C++`](@ref cpp-getting-started) and
+[`Python`](@ref python-getting-started), and they are defined in the
+sections on [enums](@ref structures-enums) and [classes](@ref
+classes-overview). The advantage using these classes is that many
+fewer parameters are needed when passing data to and from
+HiGHS. However, the use of classes is 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.
+

data/ext/lpsolver-highs/docs/src/structures/structs/HighsBasis.md

@@ -0,0 +1,8 @@
+# HighsBasis
+
+The basis of a model is communicated via an instance of the HighsBasis structure
+
+- valid: Scalar of type bool - Indicates whether the basis is valid
+- col\_status: Vector of type [HighsBasisStatus](@ref) - Comparison with [HighsBasisStatus](@ref) gives the basis status of a column
+- row\_status: Vector of type [HighsBasisStatus](@ref) - Comparison with [HighsBasisStatus](@ref) gives the basis status of a row
+

data/ext/lpsolver-highs/docs/src/structures/structs/HighsInfo.md

@@ -0,0 +1,148 @@
+# HighsInfo
+
+Scalar information about a solved model is communicated via an instance of the HighsInfo structure
+
+## valid
+- Indicates whether the values in a HighsInfo instance are valid
+- Type: bool
+
+## simplex\_iteration\_count
+- The number of simplex iterations performed
+- Type: integer
+
+## ipm\_iteration\_count
+- The number of interior point iterations performed
+- Type: integer
+
+## crossover\_iteration\_count
+- 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
+
+## primal\_solution\_status
+- Comparison with [SolutionStatus](@ref) gives the status of the [primal](@ref Primal-values) solution
+- Type: integer
+
+## dual\_solution\_status
+- Comparison with [SolutionStatus](@ref) gives the status of the [dual](@ref Dual-values) solution
+- Type: integer
+
+## basis\_validity
+- Comparison with [BasisValidity](@ref) gives the status of any basis information
+- Type: integer
+
+## objective\_function\_value
+- The optimal value of the objective function
+- Type: double
+
+## mip\_node\_count
+- The number of nodes generated by the MIP solver
+- Type: long integer
+
+## mip\_dual\_bound
+- The [dual bound](@ref terminology-mip) for the MIP solver
+- Type: double
+
+## mip\_gap
+- The absolute value of the gap between the primal and bounds, relative to the primal bound.
+- Type: double
+
+## max\_integrality\_violation
+- The maximum deviation from an integer value over all the discrete variables
+- Type: double
+
+## [num\_primal\_infeasibilities](@id info-num-primal-infeasibilities)
+- The number of variables violating a bound by more than the [primal feasibility tolerance](@ref option-primal-feasibility-tolerance).
+- Type: integer
+
+## max\_primal\_infeasibility
+- The maximum violation of a bound on a variable
+- Type: double
+
+## sum\_primal\_infeasibilities
+- The sum of violations of bounds by variables
+- Type: double
+
+## num\_dual\_infeasibilities
+- The number of variables violating dual feasibility by more than the [dual feasibility tolerance](@ref option-dual-feasibility-tolerance).
+- Type: integer
+
+## max\_dual\_infeasibility
+- The maximum violation of dual feasibility
+- Type: double
+
+## sum\_dual\_infeasibilities
+- 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 option-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 option-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 option-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 option-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 option-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 option-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
+- Type: double
+
+## primal\_dual\_integral
+- The primal-dual integral for MIPs
+- Type: double
+

data/ext/lpsolver-highs/docs/src/structures/structs/HighsLinearObjective.md

@@ -0,0 +1,11 @@
+# HighsLinearObjective
+
+A linear objective for a model is communicated via an instance of the 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
+

data/ext/lpsolver-highs/docs/src/structures/structs/HighsSolution.md

@@ -0,0 +1,10 @@
+# HighsSolution
+
+The solution of a model is communicated via an instance of the HighsSolution structure
+
+- value\_valid: Scalar of type bool - Indicates whether the column and row values are valid
+- dual\_valid: Scalar of type bool - Indicates whether the column and row [duals](@ref Dual-values) are valid
+- col\_value: Vector of type double - Values of the columns (variables)
+- col\_dual: Vector of type double - Duals of the columns (variables)
+- row\_value: Vector of type double - Values of the rows (constraints)
+- row\_dual: Vector of type double - Duals of the rows (constraints)

data/ext/lpsolver-highs/docs/src/structures/structs/index.md

@@ -0,0 +1,10 @@
+# [Overview](@id structs-overview)
+
+The data members of fundamental structs in HiGHS are defined in this section.
+
+ * [HighsSolution](@ref)
+ * [HighsBasis](@ref)
+ * [HighsInfo](@ref)
+ * [HighsLinearObjective](@ref)
+
+Structure data members for internal use only are not documented.