lpsolver 0.1.0 → 0.2.1

data/ext/lpsolver-highs/docs/src/interfaces/python/example-py.md

@@ -0,0 +1,275 @@
+# [Examples](@id example-py)
+
+## Initialize HiGHS
+
+HiGHS must be initialized before making calls to the HiGHS Python
+library, and the examples below assume that it has been done
+
+```python
+import highspy
+import numpy as np
+h = highspy.Highs()
+```
+
+## Read a model
+
+To read a model into HiGHS from a MPS files and (CPLEX) LP files pass the file name to `readModel`. 
+
+```python
+# Read a model from MPS file model.mps
+filename = 'model.mps'
+status = h.readModel(filename)
+print('Reading model file ', filename, ' returns a status of ', status)
+filename = 'model.dat'
+status = h.readModel(filename)
+print('Reading model file ', filename, ' returns a status of ', status)
+```
+
+## Build a model
+
+Build the model
+
+```raw
+minimize    f  =  x0 +  x1
+subject to              x1 <= 7
+            5 <=  x0 + 2x1 <= 15
+            6 <= 3x0 + 2x1
+            0 <= x0 <= 4; 1 <= x1
+```
+
+Using the simplified interface, the model can be built as follows:
+
+```python
+x0 = h.addVariable(lb = 0, ub = 4)
+x1 = h.addVariable(lb = 1, ub = 7)
+
+h.addConstr(5 <=   x0 + 2*x1 <= 15)
+h.addConstr(6 <= 3*x0 + 2*x1)
+
+h.minimize(x0 + x1)
+```
+
+Alternatively, the model can be built using the more general interface, which allows the user to specify the model in a more flexible way.
+
+Firstly, one variable at a time, via a sequence of calls to `addVar` and `addRow`:s
+```python
+inf = highspy.kHighsInf
+# Define two variables, first using identifiers for the bound values,
+# and then using constants
+lower = 0
+upper = 4
+h.addVar(lower, upper)
+h.addVar(1, inf)
+
+# Define the objective coefficients (costs) of the two variables,
+# identifying the variable by index, and changing its cost from the
+# default value of zero
+cost = 1
+h.changeColCost(0, cost)
+h.changeColCost(1, 1)
+
+# Define constraints for the model
+#
+# The first constraint (x1<=7) has only one nonzero coefficient,
+# identified by variable index 1 and value 1
+num_nz = 1
+index = 1
+value = 1
+h.addRow(-inf, 7, num_nz, index, value)
+
+# The second constraint (5 <= x0 + 2x1 <= 15) has two nonzero
+# coefficients, so arrays of indices and values are required
+num_nz = 2
+index = np.array([0, 1])
+value = np.array([1, 2])
+h.addRow(5, 15, num_nz, index, value)
+
+# The final constraint (6 <= 3x0 + 2x1) has the same indices but
+# different values
+num_nz = 2
+value = np.array([3, 2])
+h.addRow(6, inf, num_nz, index, value)
+
+# Access LP
+lp = h.getLp()
+num_nz = h.getNumNz()
+print('LP has ', lp.num_col_, ' columns', lp.num_row_, ' rows and ', num_nz, ' nonzeros')
+```
+
+Alternatively, via calls to `addCols` and `addRows`.
+
+```python
+inf = highspy.kHighsInf
+# The constraint matrix is defined with the rows below, but parameters
+# for an empty (column-wise) matrix must be passed
+cost = np.array([1, 1], dtype=np.double)
+lower = np.array([0, 1], dtype=np.double)
+upper = np.array([4, inf], dtype=np.double)
+num_nz = 0
+start = 0
+index = 0
+value = 0
+h.addCols(2, cost, lower, upper, num_nz, start, index, value)
+# Add the rows, with the constraint matrix row-wise
+lower = np.array([-inf, 5, 6], dtype=np.double)
+upper = np.array([7, 15, inf], dtype=np.double)
+num_nz = 5
+start = np.array([0, 1, 3])
+index = np.array([1, 0, 1, 0, 1])
+value = np.array([1, 1, 2, 3, 2], dtype=np.double)
+h.addRows(3, lower, upper, num_nz, start, index, value)
+```
+
+ * `passColName`
+ * `passRowName`
+
+## Pass a model
+
+Pass a model from a HighsLp instance
+```python
+inf = highspy.kHighsInf
+# Define a HighsLp instance
+lp = highspy.HighsLp()
+lp.num_col_ = 2;
+lp.num_row_ = 3;
+lp.col_cost_ = np.array([1, 1], dtype=np.double)
+lp.col_lower_ = np.array([0, 1], dtype=np.double)
+lp.col_upper_ = np.array([4, inf], dtype=np.double)
+lp.row_lower_ = np.array([-inf, 5, 6], dtype=np.double)
+lp.row_upper_ = np.array([7, 15, inf], dtype=np.double)
+# In a HighsLp instance, the number of nonzeros is given by a fictitious final start
+lp.a_matrix_.start_ = np.array([0, 2, 5])
+lp.a_matrix_.index_ = np.array([1, 2, 0, 1, 2])
+lp.a_matrix_.value_ = np.array([1, 3, 1, 2, 2], dtype=np.double)
+h.passModel(lp)
+```
+
+## Solve the model
+
+The incumbent model in HiGHS is solved by calling
+```python
+h.run()
+```
+
+## Print solution information
+
+```python
+solution = h.getSolution()
+basis = h.getBasis()
+info = h.getInfo()
+model_status = h.getModelStatus()
+print('Model status = ', h.modelStatusToString(model_status))
+print()
+print('Optimal objective = ', info.objective_function_value)
+print('Iteration count = ', info.simplex_iteration_count)
+print('Primal solution status = ', h.solutionStatusToString(info.primal_solution_status))
+print('Dual solution status = ', h.solutionStatusToString(info.dual_solution_status))
+print('Basis validity = ', h.basisValidityToString(info.basis_validity))
+```
+!!! warning
+    The following are markers for documentation that has yet to be added
+
+## Extract results
+
+ * `getModelStatus`
+ * `getInfo`
+ * `getSolution`
+ * `getBasis`
+ * `getObjectiveValue`
+ * `getDualObjectiveValue`
+
+## Report results
+
+ * `writeSolution`
+
+## [Option values](@id example-py-option-values)
+
+ * `setOptionValue`
+ * `getOptionValue`
+
+## Get model data
+
+ * `getNumCol`
+ * `getNumRow`
+ * `getNumNz`
+ * `getCol`
+ * `getRow`
+ * `getColEntries`
+ * `getRowEntries`
+ * `getCols`
+ * `getRows`
+ * `getColsEntries`
+ * `getRowsEntries`
+ * `getColName`
+ * `getColByName`
+ * `getRowName`
+ * `getRowByName`
+ * `getCoeff`
+
+## Modify model data
+
+ * `EnsureColwise`
+ * `EnsureRowwise`
+ * `changeObjectiveSense`
+ * `changeColCost`
+ * `changeColBounds`
+ * `changeRowBounds`
+ * `changeColsCost`
+ * `changeColsBounds`
+ * `changeRowsBounds`
+ * `changeCoeff`
+
+## Set solution
+
+ * `setSolution`
+
+## Set basis
+
+ * `setBasis`
+
+## Presolve/postsolve
+
+ * `presolve`
+ * `getPresolvedLp`
+ * `getPresolvedModel`
+ * `getPresolveLog`
+ * `getPresolveOrigColsIndex`
+ * `getPresolveOrigRowsIndex`
+ * `getModelPresolveStatus`
+ * `writePresolvedModel`
+ * `presolveStatusToString`
+ * `presolveRuleTypeToString`
+ * `postsolve`
+
+## Basis solves and tableau calculation
+ * `getBasicVariables`
+ * `getBasisInverseRow`
+ * `getBasisInverseRowSparse`
+ * `getBasisInverseCol`
+ * `getBasisInverseColSparse`
+ * `getBasisSolve`
+ * `getBasisSolveSparse`
+ * `getBasisTransposeSolve`
+ * `getBasisTransposeSolveSparse`
+ * `getReducedRow`
+ * `getReducedRowSparse`
+ * `getReducedColumn`
+ * `getReducedColumnSparse`
+
+## Rays and unboundedness
+
+ * `getDualRayExist`
+ * `getDualRay`
+ * `getDualUnboundednessDirectionExist`
+ * `getDualUnboundednessDirection`
+ * `getPrimalRayExist`
+ * `getPrimalRay`
+ 
+## Multi-objective optimization
+
+* `addLinearObjective`
+* `clearLinearObjectives`
+
+
+
+

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

@@ -0,0 +1,91 @@
+# [Getting started](@id python-getting-started)
+
+## Install
+
+HiGHS is available as `highspy` on [PyPi](https://pypi.org/project/highspy/).
+
+If `highspy` is not already installed, run:
+
+```shell
+$ pip install highspy
+```
+
+## Import
+
+To use `highspy` within a Python program, it must be imported
+
+```python
+import highspy
+```
+
+## Initialize
+
+HiGHS must be initialized before making calls to the HiGHS Python library:
+
+```python
+h = highspy.Highs()
+```
+
+## Logging
+
+When called from C++, or via the C API, console logging is duplicated
+to a file that, by default, is `Highs.log`. However, to channel
+logging to a file from `highspy`, the name of the file needs to be
+specified explicitly via a call to `setOptionValue('log_file',
+'foo.bar')`.
+
+## Methods
+
+Detailed documentation of the methods and structures is given in the
+[examples section](@ref example-py).
+
+## Return status
+
+Unless a method just returns data from HiGHS, so is guaranteed to run
+successfully, each method returns a status to indicate whether it has run
+successfully. This value is an instance of the enum [HighsStatus](@ref), and in
+the [examples section](@ref example-py), it is referred to as `status`.
+
+## First example
+
+The following Python code reads a model from the file `model.mps`, and then
+solves it.
+
+```python
+import highspy
+
+h = highspy.Highs()
+filename = 'model.mps'
+h.readModel(filename)
+h.run()
+print('Model ', filename, ' has status ', h.getModelStatus())
+```
+
+## Extracting values efficiently
+
+When arrays of values are returned by `highspy`, accessing them
+entry-by-entry can be very slow. Such arrays should first be converted
+into lists. The following example illustrates how the method
+`getSolution()` is used to obtain the solution of a model.
+
+```python
+import highspy
+
+h = highspy.Highs()
+h.readModel('model.mps')
+h.run()
+
+solution = h.getSolution()
+num_vars = len(solution.col_value)
+
+value = [solution.col_value[icol]
+         for icol in range(num_vars)]
+
+col_value = list(solution.col_value)
+value = [col_value[icol]
+         for icol in range(num_vars)]
+```
+
+For an example LP that is solved in 0.025s, accessing the values
+directly from `solution.col_value` takes 0.04s. Forming the list
+`col_value` and accessing the values directly from it takes 0.0001s.

data/ext/lpsolver-highs/docs/src/interfaces/python/model-py.md

@@ -0,0 +1,90 @@
+# [Modelling](@id model-py)
+
+HiGHS has a rudimentry modelling language that allows models to be built and run using `highspy`. 
+
+Below is an example of building a mathematical LP. The functions used are documented in detail below
+```
+# model and solve the LP
+#
+# maximize 10 x1 + 25x2
+# s. t.       x1 +  2x2 <=  80
+#             x1 +  4x2 <= 120
+#             x1 >= 0; x2 >= 0
+import highspy
+
+h = highspy.Highs()
+
+x1 = h.addVariable()
+x2 = h.addVariable()
+
+h.addConstr(x1 + 2*x2 <=  80)
+h.addConstr(x1 + 4*x2 <= 120)
+
+h.maximize(10*x1 + 25*x2)
+
+print("x1 = ", h.val(x1))
+print("x2 = ", h.val(x2))
+```
+
+## addVariable
+
+Adds a variable to the model. By default it is continuous,
+non-negative, with zero objective coefficient, and has no name
+associated with it.
+
+```
+addVariable(lb = 0, ub = kHighsInf, obj = 0, type=HighsVarType.kContinuous, name = None)
+```
+
+## addConstr
+
+Adds a constraint to the model. It must be defined in terms of a
+linear function, with `*` used when there are non-unit
+coefficients. By default it has a lower bound of -infinity, an upper
+bound of +infinity, and no name associated with it.
+
+```
+addConstr(cons, name = None)
+```
+
+## maximize
+
+Calls HiGHS to maximize the objective. By default it uses the
+objective coefficients defined when the variables were added to the
+model. However, a linear function can be passed as an argument.
+
+```
+maximize(obj=None)
+```
+
+## minimize
+
+Calls HiGHS to minimize the objective. By default it uses the
+objective coefficients defined when the variables were added to the
+model. However, a linear function can be passed as an argument.
+
+```
+minimize(obj=None)
+```
+
+## val
+
+Extracts the current value of a particular variable
+
+```
+val(var)
+```
+
+## vals
+
+Extracts the current values of a particular set of variables
+
+```
+vals(vars)
+```
+
+## MIP Example
+
+
+
+