lpsolver 0.1.0 → 0.2.1

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

@@ -0,0 +1,86 @@
+# HiGHS - High Performance Optimization Software
+
+!!! warning
+    This HiGHS documentation is a work in progress.
+
+HiGHS is software for the definition, modification and solution of large scale
+sparse linear optimization models.
+
+HiGHS is freely available from [GitHub](https://github.com/ERGO-Code/HiGHS)
+under the MIT licence and has no third-party dependencies.
+
+## Specification
+
+HiGHS can solve linear programming (LP) models of the form:
+```math
+\begin{aligned}
+\min                \quad & c^T\! x        \\
+\textrm{subject to} \quad & L \le Ax \le U  \\
+                          & l \le x \le u,
+\end{aligned}
+```
+as well as mixed integer linear programming (MILP) models of the same form, for
+which some of the variables must take integer values.
+
+HiGHS also solves quadratic programming (QP) models, which contain an additional
+objective term ``\frac{1}{2}x^T\! Q x``, where the Hessian matrix ``Q`` is
+positive semi-definite. HiGHS cannot solve QP models where some of the variables
+must take integer values.
+
+Read the [Terminology](@ref) section for more details.
+
+## Using HiGHS
+
+HiGHS can be used as a stand-alone executable on Windows, Linux and MacOS. There
+is also a C++11 library that can be used within a C++ project or, via its C, C#,
+FORTRAN, Julia, Python and Rust interfaces.
+
+Get started by following [Install HiGHS](@ref).
+
+## Overview
+
+The stand-alone [executable](@ref executable) allows models to be solved from
+[MPS](https://en.wikipedia.org/wiki/MPS_(format)) or (CPLEX)
+[LP](https://web.mit.edu/lpsolve/doc/CPLEX-format.htm) files, with full control
+of the HiGHS run-time options, and the solution can be written to files in human
+and computer-readable formats.
+
+The HiGHS shared library allows models to be loaded, built and modified. It can
+also be used to extract solution data and perform other operations relating to
+the incumbent model. The basic functionality is introduced via a [`Guide`](@ref guide-basic),
+with links to examples of its use in the `Python` interface `highspy`. This makes use of the C++
+structures and enums, and is as close as possible to the native C++ library
+calls. These can be studied via the [C++ header file](https://github.com/ERGO-Code/HiGHS/blob/master/highs/Highs.h).
+
+The C interface cannot make use of the C++ structures and enums, and its methods are documented [explicitly](@ref c-api).
+
+## Solvers
+
+For LPs, HiGHS has implementations of the revised simplex method,
+interior point method, and PDLP first order method. MIPs are solved by
+branch-and-cut, and QPs by active set. More information on the HiGHS
+solvers is [available](@ref solvers).
+
+## Citing HiGHS
+
+If you use HiGHS in an academic context, please cite the following article:
+
+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)
+
+## Performance benchmarks
+
+The performance of HiGHS relative to some commercial and open-source simplex
+solvers may be assessed via the Mittlemann benchmarks:
+
+ * [LP (find primal-dual feasible point)](http://plato.asu.edu/ftp/lpfeas.html)
+ * [LP (find optimal basic solution)](http://plato.asu.edu/ftp/lpopt.html)
+ * [MILP benchmarks](http://plato.asu.edu/ftp/milp.html).
+
+## Feedback
+
+Your comments or specific questions on HiGHS would be greatly appreciated, so
+please send an email to `highsopt@gmail.com` to get in touch with the
+development team.

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

@@ -0,0 +1,130 @@
+# Install HiGHS
+
+## Compile from source
+
+HiGHS uses CMake as build system, and requires at least version
+3.15. Details about building from source using CMake can be found in `HiGHS/cmake/README.md`.
+
+## HiGHS with HiPO
+
+HiGHS does not have any external dependencies, however, the new interior point solver HiPO uses BLAS. At the moment HiPO is optional and can be enabled via CMake.
+
+### External ordering heuristics
+
+HiPO also relies on a fill-reducing ordering heuristic. HiGHS includes the source code of Metis, AMD and RCM, three open-source ordering heuristics. Their source code is already part of the HiGHS library, so there is no need to link them. In particular, there is no need to have Metis installed separately, as in previous versions of HiPO. These source codes can be found in extern/metis, extern/amd, extern/rcm, together with the respective license files. Notice that the HiGHS source code is MIT licensed. However, if you build HiGHS with HiPO support, then libhighs and the HiGHS executables are licensed Apache 2.0, due to the presence of Metis and AMD.
+
+### BLAS
+
+On MacOS no BLAS installation is required because HiPO uses [Apple Accelerate](https://developer.apple.com/accelerate/) by default.
+
+On Windows and Linux, you can either compile OpenBLAS at configure time using the option `-DBUILD_OPENBLAS=ON` (`OFF` by default) or compile BLAS using the instructions below.
+
+#### MacOS
+
+To build HiPO on MacOS, run
+```
+cmake -S. -B build -DHIPO=ON
+```
+
+#### Linux and Windows: Compile OpenBLAS at configure time
+
+```
+cmake -S. -B build -DHIPO=ON -DBUILD_OPENBLAS=ON
+```
+
+#### Linux and Windows: Link with BLAS installatied on your machine
+
+On Linux, libblas and libopenblas are supported. We recommend libopenblas for its better performance, and it is found by default if available on the system. Install with
+
+```
+sudo apt update
+sudo apt install libopenblas-dev
+```
+
+To build HiPO, run
+```
+cmake -S. -B build -DHIPO=ON
+```
+
+On Windows, OpenBLAS is required. It could be installed via [vcpkg](https://learn.microsoft.com/en-us/vcpkg/get_started/overview) with
+
+```
+vcpkg install openblas[threads]
+```
+
+Note, that `[threads]` is required for HiPO.
+
+On Windows, you also need to specify the path to OpenBLAS. If it was installed with vcpkg as suggested above, add the path to `vcpkg.cmake` to the CMake flags, e.g.
+```
+cmake -S. -B build -DHIPO=ON -DCMAKE_TOOLCHAIN_FILE="C:/vcpkg/scripts/buildsystems/vcpkg.cmake"
+```
+
+##### Path to BLAS
+
+To specify explicitly which BLAS vendor to look for, `BLA_VENDOR` coud be set in CMake, e.g. `-DBLA_VENDOR=Apple` or `-DBLA_VENDOR=OpenBLAS`. Alternatively, to specify which BLAS library to use, set `BLAS_LIBRARIES` to the full path of the library e.g. `-DBLAS_LIBRARIES=/path_to/libopenblas.so`.
+
+
+## Bazel build
+
+Alternatively, building with Bazel is supported for Bazel-based projects. To build HiGHS, from the root directory, run
+
+```
+bazel build //...
+```
+
+## Install via a package manager
+
+HiGHS can be installed using a package manager in the cases of
+[`Julia`](@ref HiGHS.jl), [`Python`](@ref python-getting-started), [`CSharp`](@ref nuget) and [`Rust`](@ref Rust).
+
+## Precompiled Binaries
+
+Precompiled static binaries are available at https://github.com/ERGO-Code/HiGHS/releases.
+
+Additionally, there is one package containing shared libraries for Windows x64.
+
+The `*-mit` binary packages contain HiGHS and are MIT-licenced.
+The `*-apache` binary packages contain HiGHS with HiPO and are Apache-licenced, due to the licensing of the dependencies of HiPO. For more information, see [THIRD_PARTY_NOTICES.md](https://github.com/ERGO-Code/HiGHS/blob/master/THIRD_PARTY_NOTICES.md).
+
+If you have any questions or requests for more platforms and binaries, please get in touch with us at hello@highs.dev.
+
+To install a precompiled binary, download and extract the archive corresponding to your Operating System and architecture, the executable is located at `/bin/highs`.
+
+## [Building HiGHS with NVidia GPU support](@id gpu-build)
+
+HiGHS must be built, from the root directory, with
+
+```
+cmake -S. -Bbuild -DCUPDLP_GPU=ON
+cmake --build build --parallel
+```
+
+This uses [FindCUDAToolkit](https://cmake.org/cmake/help/latest/module/FindCUDAToolkit.html) to find a CUDA installation locally. For more details on HiGHS with CMake, see `HiGHS/cmake/README.md`.
+
+
+#### Find CUDA
+
+If CUDA is not found automatically, there is an extra option `-DCUPDLP_FIND_CUDA=ON`, to be used with `-DCUPDLP_GPU=ON`, which instead uses `cuPDLP-C`'s `FindCUDAConf.cmake`.
+
+This requires the environment variable `CUDA_HOME` to be set to the directory with the CUDA installation. Having set this, run
+
+```
+cmake -S. -Bbuild -DCUPDLP_GPU=ON -DCUPDLP_FIND_CUDA=ON
+cmake --build build --parallel
+```
+
+to build HiGHS.
+
+### Bazel build with Cuda
+
+Alternatively, for Bazel run
+
+```
+bazel build //... --//:cupdlp_gpu
+```
+
+It may be necessary to also specify the architecture, e.g.
+
+```
+bazel build //... --//:cupdlp_gpu --@rules_cuda//cuda:archs=sm_89
+```

data/ext/lpsolver-highs/docs/src/interfaces/c_api.md

@@ -0,0 +1,6 @@
+# [C](@id c-api)
+
+```@autodocs
+Modules = [Main]
+Filter = t -> startswith("$t", "Highs")
+```

data/ext/lpsolver-highs/docs/src/interfaces/cpp/examples.md

@@ -0,0 +1 @@
+Example programs calling HiGHS from C, C++, C#, Fortran and Python are in [`HiGHS/examples`](https://github.com/ERGO-Code/HiGHS/tree/master/examples).

data/ext/lpsolver-highs/docs/src/interfaces/cpp/index.md

@@ -0,0 +1,29 @@
+# [Getting started](@id cpp-getting-started)
+
+HiGHS can be cloned from [GitHub](https://github.com/ERGO-Code/HiGHS) with the command
+
+``` bash
+git clone https://github.com/ERGO-Code/HiGHS.git
+```
+
+### Building HiGHS from source code
+
+
+HiGHS uses CMake (minimum version 3.15) as a build system, and can use the following compilers
+
+- Clang ` clang `
+- GNU ` g++ `
+- Intel ` icc `
+- Microsoft ` MSVC `
+
+Instructions for building HiGHS from source code are in `HiGHS/cmake/README.md`.
+
+The simplest setup is to build HiGHS in a build directory within the root directory. The
+name of the build folder is arbitrary but, assuming it is `build`,
+the sequence of commands is as follows
+
+``` bash
+cd HiGHS
+cmake -S. -B build 
+cmake --build build --parallel
+```

data/ext/lpsolver-highs/docs/src/interfaces/cpp/library.md

@@ -0,0 +1,107 @@
+The HiGHS library is defined in the [`highs/Highs.h`](https://github.com/ERGO-Code/HiGHS/blob/master/highs/Highs.h) header file. It contains the definition of the methods and members of the class. 
+
+## Define model
+
+Models in HiGHS are defined as an instance of the `HighsModel` class. This consists of one instance of the `HighsLp` class, and one instance of the `HighsHessian` class. Communication of models to and from HiGHS is possible via instances of the `HighsLp` or `HighsModel` class. In the C and other interfaces, communication of models is via scalar values and addresses of arrays.
+
+In C++, the neatest way of passing a model to HiGHS is to create an instance of the `HighsModel` class, populate its data, and call
+``` cpp
+Highs::passModel(const HighsModel& model)
+```
+
+or create and populate an instance of the `HighsLp` class, and call
+``` cpp
+Highs::passModel(const HighsLp& lp)
+```
+
+For reading models from a file, use
+``` cpp
+Highs::readModel(const std::string& filename)
+```
+
+Below is an example of building a `HighsModel`
+``` cpp
+  // Create and populate a HighsModel instance for the LP
+  
+  // Min    f  =  x_0 +  x_1 + 3
+  // s.t.                x_1 <= 7
+  //        5 <=  x_0 + 2x_1 <= 15
+  //        6 <= 3x_0 + 2x_1
+  // 0 <= x_0 <= 4; 1 <= x_1
+  
+  // Although the first constraint could be expressed as an upper
+  // bound on x_1, it serves to illustrate a non-trivial packed
+  // column-wise matrix.
+  
+  HighsModel model;
+  model.lp_.num_col_ = 2;
+  model.lp_.num_row_ = 3;
+  model.lp_.sense_ = ObjSense::kMinimize;
+  model.lp_.offset_ = 3;
+  model.lp_.col_cost_ = {1.0, 1.0};
+  model.lp_.col_lower_ = {0.0, 1.0};
+  model.lp_.col_upper_ = {4.0, 1.0e30};
+  model.lp_.row_lower_ = {-1.0e30, 5.0, 6.0};
+  model.lp_.row_upper_ = {7.0, 15.0, 1.0e30};
+  
+  // Here the orientation of the matrix is column-wise
+  model.lp_.a_matrix_.format_ = MatrixFormat::kColwise;
+  // a_start_ has num_col_+1 entries, and the last entry is the number
+  // of nonzeros in A, allowing the number of nonzeros in the last
+  // column to be defined
+  model.lp_.a_matrix_.start_ = {0, 2, 5};
+  model.lp_.a_matrix_.index_ = {1, 2, 0, 1, 2};
+  model.lp_.a_matrix_.value_ = {1.0, 3.0, 1.0, 2.0, 2.0};
+```
+
+## Solve model
+
+``` cpp
+  // Create a Highs instance
+  Highs highs;
+  HighsStatus return_status;
+  
+  // Pass the model to HiGHS
+  return_status = highs.passModel(model);
+  assert(return_status==HighsStatus::kOk);
+  
+  // Get a const reference to the LP data in HiGHS
+  const HighsLp& lp = highs.getLp();
+  
+  // Solve the model
+  return_status = highs.run();
+  assert(return_status==HighsStatus::kOk);
+  
+  // Get the model status
+  const HighsModelStatus& model_status = highs.getModelStatus();
+  assert(model_status==HighsModelStatus::kOptimal);
+```
+
+Solution information:
+
+``` cpp
+  const HighsInfo& info = highs.getInfo();
+  cout << "Simplex iteration count: " << info.simplex_iteration_count << endl;
+  cout << "Objective function value: " << info.objective_function_value << endl;
+  cout << "Primal  solution status: " << highs.solutionStatusToString(info.primal_solution_status) << endl;
+  cout << "Dual    solution status: " << highs.solutionStatusToString(info.dual_solution_status) << endl;
+  cout << "Basis: " << highs.basisValidityToString(info.basis_validity) << endl;
+```
+
+## Integrality variables
+
+To indicate that variables must take integer values use the `HighsLp::integrality` vector.
+``` cpp
+  model.lp_.integrality_.resize(lp.num_col_);
+  for (int col=0; col < lp.num_col_; col++)
+    model.lp_.integrality_[col] = HighsVarType::kInteger;
+
+  highs.passModel(model);
+```
+
+## Clearing the basis
+
+To clear any internal basis, call `HighsLp::setBasis` with no argument.
+
+
+

data/ext/lpsolver-highs/docs/src/interfaces/csharp.md

@@ -0,0 +1,55 @@
+#### [CSharp](@id csharp)
+
+#### Build from source
+
+There is a C# example code in `examples/call_highs_from_csharp.cs`. From the HiGHS root directory, run
+
+``` bash
+cmake -S. -Bbuild -DCSHARP=ON
+```
+
+If a CSharp compiler is available, this builds the example using CMake and generates a binary in the build directory (`build/bin/csharpexample`).
+
+#### [NuGet](@id nuget)
+
+The nuget package Highs.Native is on https://www.nuget.org, at https://www.nuget.org/packages/Highs.Native/.
+
+It can be added to your C# project with `dotnet`
+
+```shell
+dotnet add package Highs.Native --version 1.14.0
+```
+
+The nuget package contains runtime libraries for
+
+* `win-x64`
+* `win-x32`
+* `linux-x64`
+* `linux-arm64`
+* `macos-x64`
+* `macos-arm64`
+
+Details for building locally can be found in `nuget/README.md`. Many thanks to Markus-Ludwig Wermer and the team at MENTZ GmbH for the NuGet packaging support!
+
+#### C# API
+
+The C# API can be called directly. Here are observations on calling the HiGHS C# API from C#:
+
+ * The file `HiGHS/highs/interfaces/highs_csharp_api.cs` contains all the PInvoke you need.
+ * Make sure, that the native HiGHS library (`highs.dll`, `libhighs.dll`,
+   `libhighs.so`, ... depending on your platform) can be found at runtime. How
+   to do this is platform dependent, copying it next to your C# executable
+   should work in most cases. You can use msbuild for that. On linux, installing
+   HiGHS system wide should work.
+ * Make sure that all dependencies of the HiGHS library can be found, too. For
+   example, if HiGHS was build using `Visual C++` make sure that the
+   `MSVCRuntime` is installed on the machine you want to run your application
+   on.
+ * Depending on the name of your HiGHS library, it might be necessary to change
+   the constant "highslibname". See [document](https://learn.microsoft.com/en-us/dotnet/standard/native-interop/cross-platform)
+   on writing cross platform P/Invoke code if necessary.
+ * Call the Methods in `highs_csharp_api.cs` and have fun with HiGHS.
+
+This is the normal way to call plain old C from C# with the great simplification
+that you don't have to write the PInvoke declarations yourself.
+

data/ext/lpsolver-highs/docs/src/interfaces/fortran.md

@@ -0,0 +1,11 @@
+
+#### [Fortran](@id fortran-api)
+
+The interface is in
+`HiGHS/highs/interfaces/highs_fortran_api.f90`. Its
+methods are simply bindings to the [`C` API](@ref c-api)
+
+To include in the build, switch the Fortran CMake parameter on:
+``` bash
+cmake -DFORTRAN=ON ..
+```

data/ext/lpsolver-highs/docs/src/interfaces/julia/index.md

@@ -0,0 +1,130 @@
+# HiGHS.jl
+
+[HiGHS.jl](https://github.com/jump-dev/HiGHS.jl) is a Julia package that
+interfaces with HiGHS.
+
+HiGHS.jl has two components:
+
+ - a thin wrapper around the complete C API
+ - an interface to [MathOptInterface](https://github.com/jump-dev/MathOptInterface.jl)
+
+The C API can be accessed via `HiGHS.Highs_xxx` functions, where the names and
+arguments are identical to the C API.
+
+## Installation
+
+Install HiGHS as follows:
+```julia
+import Pkg
+Pkg.add("HiGHS")
+```
+
+In addition to installing the HiGHS.jl package, this command will also download
+and install the HiGHS binaries. (You do not need to install or compile HiGHS
+separately.)
+
+To use a custom binary, read the [Custom solver binaries](https://jump.dev/JuMP.jl/stable/developers/custom_solver_binaries/)
+section of the JuMP documentation.
+
+## Use with JuMP
+
+Pass `HiGHS.Optimizer` to `JuMP.Model` to create a JuMP model with HiGHS as the
+optimizer. Set options using `set_optimizer_attribute`.
+
+```julia
+using JuMP
+import HiGHS
+model = Model(HiGHS.Optimizer)
+set_optimizer_attribute(model, "presolve", "on")
+set_optimizer_attribute(model, "time_limit", 60.0)
+```
+
+For more details, including a range of tutorials and examples using HiGHS, see
+the [JuMP documentation](https://jump.dev/JuMP.jl/stable/).
+
+## Issues and feedback
+
+HiGHS.jl is maintained by the JuMP community and is not officially maintained
+or supported by the HiGHS developers.
+
+To report a problem (e.g., incorrect results, or a crash of the solver),
+or make a suggestion for how to improve HiGHS.jl, please
+[file a GitHub issue at HiGHS.jl](https://github.com/jump-dev/HiGHS.jl).
+
+If you use HiGHS from JuMP, use `JuMP.write_to_file(model, "filename.mps")`
+to write your model an MPS file, then upload the MPS file to [https://gist.github.com](https://gist.github.com)
+and provide a link to the gist in the GitHub issue.
+
+## C API
+
+HiGHS.jl is a thin wrapper around the complete [HiGHS C API](@ref c-api).
+
+As a basic example, we solve the model:
+
+```math
+\begin{aligned}
+\min                \quad & x + y \\
+\textrm{subject to} \quad & 5 \le x + 2y \le 15   \\
+                          & 6 \le 3x + 2y         \\
+                          & 0 \le x \le 4         \\
+                          & 1 \le y               \\
+                          & y \in \mathbb{Z}.
+
+\end{aligned}
+```
+
+Here is the corresponding Julia code:
+
+```julia
+julia> using HiGHS
+
+julia> highs = Highs_create()
+Ptr{Nothing} @0x00007fc4557d3200
+
+julia> ret = Highs_setBoolOptionValue(highs, "log_to_console", false)
+0
+
+julia> @assert ret == 0  # If ret != 0, something went wrong
+
+julia> Highs_addCol(highs, 1.0, 0.0, 4.0, 0, C_NULL, C_NULL)   # x is column 0
+0
+
+julia> Highs_addCol(highs, 1.0, 1.0, Inf, 0, C_NULL, C_NULL)   # y is column 1
+0
+
+julia> Highs_changeColIntegrality(highs, 1, kHighsVarTypeInteger)
+0
+
+julia> Highs_changeObjectiveSense(highs, kHighsObjSenseMinimize)
+0
+
+julia> senseP = Ref{Cint}(0)  # Instead of passing `&sense`, pass a Julia `Ref`
+Base.RefValue{Int32}(0)
+
+julia> Highs_getObjectiveSense(model, senseP)
+0
+
+julia> senseP[] == kHighsObjSenseMinimize  # Dereference with senseP[]
+true
+
+julia> Highs_addRow(highs, 5.0, 15.0, 2, Cint[0, 1], [1.0, 2.0])
+0
+
+julia> Highs_addRow(highs, 6.0, Inf, 2, Cint[0, 1], [3.0, 2.0])
+0
+
+julia> Highs_run(highs)
+0
+
+julia> col_value = zeros(Cdouble, 2);
+
+julia> Highs_getSolution(highs, col_value, C_NULL, C_NULL, C_NULL)
+0
+
+julia> col_value
+2-element Vector{Float64}:
+ 1.0
+ 2.0
+
+julia> Highs_destroy(highs)
+```

data/ext/lpsolver-highs/docs/src/interfaces/other.md

@@ -0,0 +1,41 @@
+# Other Interfaces
+
+!!! note
+    Some of the interfaces listed on this page are not officially supported by
+    the HiGHS development team and are contributed by the community.
+
+## AMPL
+
+HiGHS can be used via AMPL, see the [AMPL Documentation](https://dev.ampl.com/solvers/highs/index.html).
+
+
+## GAMS
+
+The interface is available at [GAMSlinks](https://github.com/coin-or/GAMSlinks/),
+including [pre-build libraries](https://github.com/coin-or/GAMSlinks/releases).
+
+## Javascript
+
+ * HiGHS can be used from Javascript directly inside a web browser thanks to
+   [highs-js](https://github.com/lovasoa/highs-js). See the [demo](https://lovasoa.github.io/highs-js/)
+   and the [npm package](https://www.npmjs.com/package/highs).
+ * Alternatively, HiGHS also has a [native Node.js](https://www.npmjs.com/package/highs-solver)
+   interface.
+
+## MATLAB
+
+* [HiGHSMEX](https://github.com/savyasachi/HiGHSMEX) is a MATLAB interface that provides all the functionality of HiGHS, except the following: Reading problem data from a model file; Setting names for the rows and columns of the model, or setting name for the objective; Advanced features such as solution of systems using the current basis matrix.
+
+  The interface is avalailable for Windows, MacOS and Linux, and has been tested on Windows and MacOS. Pre-built binaries (mex files) for Windows and MacOS are available in the repository, which also includes instructions for building from source in [README.md](https://github.com/savyasachi/HiGHSMEX/blob/main/README.md).
+
+* The HiGHS MIP and dual simplex LP solvers have been used _within_ MATLAB (so for all architectures) by default since release 2024a.
+
+## R
+
+ * An R interface is available through the [`highs` R package](https://cran.r-project.org/web/packages/highs/index.html).
+
+## Rust
+
+ * HiGHS can be used from rust through the [`highs` crate](https://crates.io/crates/highs).
+   The rust linear programming modeler [**good_lp**](https://crates.io/crates/good_lp)
+   supports HiGHS.