lpsolver 0.1.0 → 0.2.0

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

@@ -0,0 +1,163 @@
+# Terminology
+
+Any linear optimization model will have __decision variables__, a
+linear or quadratic __objective function__, and linear __constraints__
+and __bounds__ on the values of the decision variables. A
+__mixed-integer__ optimization model will require some or all of the
+decision variables to take integer values. The model may require the
+objective function to be maximized or minimized whilst satisfying the
+constraints and bounds. By default, HiGHS minimizes the objective
+function.
+
+## Bounds and the objective function
+
+The bounds on a decision variable are the least and greatest values
+that it may take, and infinite bounds can be specified. A linear
+objective function is given by a set of coefficients, one for each
+decision variable, and its value is the sum of products of
+coefficients and values of decision variables. The objective
+coefficients are often referred to as __costs__, and some may be
+zero. When a model has been solved, the optimal values of the
+decision variables are referred to as the __(primal) solution__.
+
+## Constraints and the feasible region
+
+Linear constraints require linear functions of decision variables to
+lie between bounds, and infinite bounds can be specified. If the
+bounds are equal, then the constraint is an __equation__. If the
+bounds are both finite, then the constraint is said to be __boxed__ or
+__two-sided__. The set of points satisfying linear constraints and
+bounds is known as the __feasible region__. Geometrically, this is a
+multi-dimensional convex polyhedron, whose extreme points are referred
+to as __vertices__.
+
+## The constraint matrix
+
+The coefficients of the linear constraints are naturally viewed as
+rows of a __matrix__. The constraint coefficients associated with a
+particular decision variable form a column of the constraint
+matrix. Hence constraints are sometimes referred to as __rows__, and
+decision variables as __columns__. Constraint matrix coefficients may
+be zero. Indeed, for large practical models it is typical for most
+of the coefficients to be zero. When this property can be exploited to
+computational advantage, the matrix is said to be __sparse__. When the
+constraint matrix is not sparse, the solution of large models is
+normally intractable computationally.
+
+## Optimization outcomes
+
+It is possible to define a set of constraints and bounds that cannot
+be satisfied, in which case the model is said to be
+__infeasible__. Conversely, it is possible that the value of the
+objective function can be improved without bound whilst satisfying the
+constraints and bounds, in which case the model is said to be
+__unbounded__. If a model is neither infeasible, nor unbounded, it
+has an __optimal solution__. The optimal objective function value for
+a linear optimization model may be achieved at more than point, in
+which case the optimal solution is said to be __non-unique__.
+
+## Primal values
+
+The values of the decision variables are referred to as __primal__ values to distingush them from __dual__ values.
+
+## Dual values
+
+When none of the decision variables is required to take integer
+values, the model is said to be __continuous__. For
+continuous models, each variable and constraint has an
+associated __dual variable__. The values of the dual
+variables constitute the __dual solution__, and it is for
+this reason that the term __primal solution__ is used to
+distinguish the optimal values of the decision variables. At the
+optimal solution of a continuous model, some of the decision
+variables and values of constraint functions will be equal to their
+lower or upper bounds. Such a bound is said to
+be __active__. If a variable or constraint is at a bound,
+its corresponding dual solution value will generally be non-zero: when
+at a lower bound the dual value will be non-negative; when at an upper
+bound the dual value will be non-positive. When maximizing the
+objective the required signs of the dual values are reversed. Due to
+their economic interpretation, the dual values associated with
+constraints are often referred to as __shadow prices__
+or __fair prices__. Mathematically, the dual values
+associated with variables are often referred to as __reduced
+costs__, and the dual values associated with constraints are
+often referred to as __Lagrange multipliers__.
+
+## [Basic solution](@id term-basic-solution)
+
+An LP model that is neither infeasible, nor unbounded, has an optimal
+solution at a vertex of the feasible region. At a vertex, the decision
+variables (original variables and slack variables for constraints) can
+be partitioned into as many __basic variables__ as there are
+constraints, and __nonbasic variables__. Such a solution is known as a
+__basic solution__, and the partition referred to as a __basis__.
+
+The value of a nonbasic variable is equal to its lower or upper
+bound. The values of the basic variables are obtained by solving a
+linear system of equations. Their values lie between the lower and
+upper bounds (to within the [primal feasibility tolerance](@ref
+option-primal-feasibility-tolerance)), but may be equal to a lower or
+upper bound, a situation known as __degeneracy__.
+
+When a basic solution is known, the values of the dual variables yield
+sensitivity information for the solution, a property that can be very
+valuable both to users and when the LP is solved as a sub-problem when
+solving mixed-integer programming problems.
+
+When modifications have been made to an LP problem, the simplex solver
+(only) can solve the modified LP from the optimal basis of the
+original LP. Such "hot starting" is typically the most efficient means
+of solving the modified LP, and is essential to the efficient solution
+of mixed-integer programming problems. However, if the modifications
+are too great, it may be more efficient to solve the LP from scratch
+using the IPM solver.
+
+## Sensitivity
+
+Analysis of the change in optimal objective value of a continuous
+linear optimization model as the cost coefficients and bounds are
+changed is referred to in HiGHS as __ranging__. For an
+active bound, the corresponding dual value gives the change in the
+objective if that bound is increased or decreased. This level of
+analysis is often referred to as __sensitivity__. In
+general, the change in the objective is only known for a limited range
+of values for the active bound. HiGHS will return the limits of
+these __bound ranges__ ranges, the objective value at
+both limits and the index of a variable or constraint that will
+acquire an active bound at both limits. For each variable with an
+active bound, the solution will remain optimal for a range of values
+of its cost coefficient. HiGHS will return the values of
+these __cost ranges__. For a variable or constraint whose
+value is not at a bound, HiGHS will return the range of values that
+the variable or constraint can take, the objective values at the
+limits of the range, and the index of a variable or constraint with a
+bound that will become in active at both limits.
+
+## [MIP](@id terminology-mip)
+
+When solving a MIP, some or all the variables must take discrete values. In HiGHS there are three types of discrete variables.
+
+- Integer: those that must take integer values between their bounds
+- Semi-continuous: those that must be zero or take continuous values between their bounds
+- Semi-integer: those that must be zero or take integer values between their bounds
+
+In the following discussion, for ease of reference to relative
+objective values, it is assumed that the objective is being minimized
+
+Any point for which the discrete variables satisfy their requirements,
+is said to be __integer feasible__. The objective value at such a
+point is an upper bound on the optimal objective value. The least such
+bound is known as the __primal bound__. The MIP solver generates a
+sequence of LPs, each of which has bounds on the variables that are
+tighter than those of the original model. When unsolved, there is a
+bound on the optimal objective value for each such LP and, the
+greatest such bound is known as the __dual bound__. The optimal
+objective value of the MIP cannot be less than the dual bound. Hence
+the gap between the primal and dual bounds is a measure of progress of
+the MIP solver. Although the absolute gap is of some interest, the gap
+relative to the primal bound is a better measure. When the gap reaches
+zero then the MIP is solved to optimality. However, it is often
+preferable to stop the MIP solver when the relative gap is below a
+specified tolerance.
+

data/ext/lpsolver-highs/examples/CMakeLists.txt

@@ -0,0 +1,26 @@
+if(NOT BUILD_EXAMPLES)
+  return()
+endif()
+
+if(BUILD_CXX_EXAMPLE)
+  file(GLOB CXX_SRCS "*.cpp")
+  foreach(FILE_NAME IN LISTS CXX_SRCS)
+    highs_cxx_test(${FILE_NAME})
+  endforeach()
+endif()
+
+# if(BUILD_PYTHON_EXAMPLE)
+#   file(GLOB PYTHON_SRCS "*.py")
+#   foreach(FILE_NAME IN LISTS PYTHON_SRCS)
+#     add_python_example(${FILE_NAME})
+#   endforeach()
+# endif()
+
+if(BUILD_CXX_EXAMPLE)
+  file(GLOB C_SRCS "*_minimal.c")
+  # set(C_SRCS "call_highs_from_c_minimal.c")
+  foreach(FILE_NAME IN LISTS C_SRCS)
+    message(${FILE_NAME})
+    highs_c_test(${FILE_NAME})
+  endforeach()
+endif()

data/ext/lpsolver-highs/examples/Docs.py

@@ -0,0 +1,104 @@
+import highspy
+import numpy as np
+
+# minimize    f  =  x0 +  x1
+# subject to              x1 <= 7
+#             5 <=  x0 + 2x1 <= 15
+#             6 <= 3x0 + 2x1
+#             0 <= x0 <= 4; 1 <= x1
+# Highs h
+h = highspy.Highs()
+inf = highspy.kHighsInf
+
+# Load a model from MPS file model.mps
+print("\nLoading the model from an MPS file")
+filename = 'model.mps'
+h.readModel(filename)
+h.run()
+
+print("\nBuilding a model using single variables and constraints")
+# Build a model with single variables and constraints
+h.clear()
+# 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 defining its cost
+cost = 1
+h.changeColCost(0, cost)
+h.changeColCost(1, 1)
+# Define constraints for the model
+#
+# The first constraint (x_1<=7) has only one nonzero coefficient,
+# identified by variable index 1 and value 1
+lower = -inf
+upper = 7
+num_nz = 1
+index = 1
+value = 1
+h.addRow(lower, upper, num_nz, index, value)
+# The second constraint (5 <= x_0 + 2x_1 <= 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], dtype=np.double)
+h.addRow(5, 15, num_nz, index, value)
+# The final constraint (6 <= 3x_0 + 2x_1) has the same indices but different values
+num_nz = 2
+value = np.array([3, 2], dtype=np.double)
+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')
+
+#h.writeModel("")
+
+# Build a model with multiple columns and rows
+h.clear()
+print("\nBuilding a model using multiple variables and constraints")
+# 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)
+
+h.writeModel("")
+h.run()
+
+# Pass the following model from a HighsLp instance
+h.clear()
+print("Passing the model via HighsLp")
+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 instsance, 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)
+h.writeModel("")
+h.run()
+