From e2d56dc431c8ab03df880af1e86997c9765d51b0 Mon Sep 17 00:00:00 2001 From: JAJHall Date: Wed, 22 Mar 2023 23:57:38 +0000 Subject: [PATCH] Guide now in three sections --- docs/make.jl | 2 ++ docs/src/guide/advanced.md | 2 +- docs/src/guide/basic.md | 54 ++++++++++++----------------- docs/src/guide/further.md | 14 ++++++++ docs/src/guide/index.md | 18 ++++++++++ docs/src/index.md | 2 +- docs/src/interfaces/julia/index.md | 2 +- docs/src/interfaces/python/index.md | 2 +- docs/src/parallel.md | 2 +- docs/src/terminology.md | 8 ++--- 10 files changed, 65 insertions(+), 41 deletions(-) create mode 100644 docs/src/guide/further.md create mode 100644 docs/src/guide/index.md diff --git a/docs/make.jl b/docs/make.jl index b3cc6cf167..0ce9881a56 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -49,7 +49,9 @@ Documenter.makedocs( "installation.md", "Executable" => "executable.md", "Guide" => Any[ + "guide/index.md", "guide/basic.md", + "guide/further.md", "guide/advanced.md" ], "Data structures" => Any[ diff --git a/docs/src/guide/advanced.md b/docs/src/guide/advanced.md index ba2f42983f..5c637ec005 100644 --- a/docs/src/guide/advanced.md +++ b/docs/src/guide/advanced.md @@ -1,4 +1,4 @@ -# Advanced features +# [Advanced features](@id guide-advanced) ## Simplex tableau data diff --git a/docs/src/guide/basic.md b/docs/src/guide/basic.md index 2a938f6c5a..dd45427b19 100644 --- a/docs/src/guide/basic.md +++ b/docs/src/guide/basic.md @@ -1,16 +1,4 @@ -# Basic features - -This guide describes the basic features of HiGHS that are available -when it is called from [`Python`](@ref python-getting-started), -[`C++`](@ref cpp-getting-started), [`C`](@ref c-api) and -[`Fortran`](@ref fortran-api). Although references to methods link to -`Python` examples, the method names and functionality for other -interfaces are as close as possible. - -This basic guide will be sufficient for most users, and covers all the -methods in the `Python` interface `highspy`. A guide to more advanced -methods available via other interfaces is [available](@ref -Advanced-features). +# [Basic features](@id guide-basic) The minimal use of HiGHS has the following three stages. @@ -18,7 +6,8 @@ The minimal use of HiGHS has the following three stages. * [Solve the model](@ref Solving-the-model) * [Extract results](@ref Extracting-results) -Although its default actions will be sufficient for most users, HiGHS can be controlled by setting [Option values](@ref Option-values). +Although its default actions will be sufficient for most users, HiGHS +can be controlled by setting [Option values](@ref Option-values). _Intro to other basic features_ @@ -47,19 +36,21 @@ the method [`readModel`](@ref Read-a-model). HiGHS infers the file type by the e * `.mps`: for an MPS file * `.lp`: for a CPLEX LP file -HiGHS can read compressed files that end in the `.gz` extension. +HiGHS can read compressed files that end in the `.gz` extension, but +not (yet) files that end in the `.zip` extension. ### Building a model The model in HiGHS can be built using a sequence of calls to add variables and constraints. This is most easily done one-by-one using -the methods [`addCol` and `addRow`](@ref Build-a-model). Alterntively, -[`addVar` and `addRow`](@ref Build-a-model) can be used, with -[`changeColCost`](@ref Build-a-model) used to define each objective -coefficient. +the methods [`addCol` and `addRow`](@ref +Build-a-model). Alternatively, calls to [`addVar`](@ref Build-a-model) +can be used to add variables, with calls to [`changeColCost`](@ref +Build-a-model) used to define each objective coefficient. Addition of multiple variables and constraints can be achieved using -[`addVars` and `addRows`](@ref Build-a-model), with +[`addCols` and `addRows`](@ref Build-a-model). Alternatively, +[`addVars`](@ref Build-a-model) can be used to add variables, with [`changeColsCost`](@ref Build-a-model) used to define objective coefficients. Note that defining the model in this way requires vectors of data and the specification of constraint coefficients as @@ -71,17 +62,21 @@ matrices. ### Passing a model -If the entire definition of a model is known, then is can be passed to +If the entire definition of a model is known, then it can be passed to HiGHS via individual data arrays using the method [`passModel`](@ref Pass-a-model). In languages where HiGHS data structures can be used, -an instance of the [`HighsLp`](@ref HighsLp) class can be passed. +an instance of the [`HighsLp`](@ref HighsLp) class can be populated +with data and then passed. ## Solving the model -The incumbent model in HiGHS is solved by a call to the method [run](@ref Solve-the-model). -By default, HiGHS minimizes the model's objective function. Where possible, -HiGHS will hot start the solver using solution information obtained on previous -runs, or supplied by the user. +The incumbent model in HiGHS is solved by a call to the method +[run](@ref Solve-the-model). By default, HiGHS minimizes the model's +objective function, although this can be [changed](@ref +Modifying-model-data). Where possible, HiGHS will reduce the solution +time by using data obtained on previous runs, or supplied by the +user. More information on this process of hot starting solvers is +given [below](@ref hot-start). ## Extracting results @@ -133,7 +128,7 @@ data can be extracted using the methods [getCols](@ref Get-model-data), Specific matrix coefficients obtained using the method [getCoeff](@ref Get-model-data). -### Modifying model data +## Modifying model data The most immediate model modification is to change the sense of the objective. By default, HiGHS minimizes the model's objective function. The objective sense @@ -150,8 +145,3 @@ using the methods [changeColsCost](@ref Modify-model-data), is [changeRowsBounds](@ref Modify-model-data). An individual matrix coefficient is changed by passing its row index, column index and new value to [changeCoeff](@ref Modify-model-data). - -### Other operations - -To run HiGHS from a user-defined solution or basis, this is passed to HiGHS -using the methods [setSolution](@ref Set-solution) or [setBasis](@ref Set-basis). diff --git a/docs/src/guide/further.md b/docs/src/guide/further.md new file mode 100644 index 0000000000..69f1e493e2 --- /dev/null +++ b/docs/src/guide/further.md @@ -0,0 +1,14 @@ +# [Further features](@id guide-further) + +### [Hot start](@id hot-start) + +It may be possible for HiGHS to start solving a model using data +obtained by solving a related model, or supplied by a user. Whether +this is possible depends on the the class of model being solved, the +solver to be used, and the modifications (if any) that have been to +the incumbent model since it was last solved. + +#### LP + +To run HiGHS from a user-defined solution or basis, this is passed to HiGHS +using the methods [setSolution](@ref Set-solution) or [setBasis](@ref Set-basis). diff --git a/docs/src/guide/index.md b/docs/src/guide/index.md new file mode 100644 index 0000000000..99c09d9a22 --- /dev/null +++ b/docs/src/guide/index.md @@ -0,0 +1,18 @@ +# [Introduction](@id guide-introduction) + +This guide describes the features of HiGHS that are available when it +is called from [`Python`](@ref python-getting-started), [`C++`](@ref +cpp-getting-started), [`C`](@ref c-api) and [`Fortran`](@ref +fortran-api). It is written in three sections: [basic](@ref +guide-basic), [further](@ref guide-further) and [advanced](@ref +guide-advanced). + +The [basic](@ref guide-basic) section will be sufficient for most +users. This and the [further](@ref guide-further) section cover the +`Python` interface `highspy`. Although references to methods link to +`Python` examples, the method names and functionality for other +interfaces are as close as possible. + +The [advanced](@ref guide-advanced) section covers features in the +[`C++`](@ref cpp-getting-started), [`C`](@ref c-api) and +[`Fortran`](@ref fortran-api) that are not in highspy`. \ No newline at end of file diff --git a/docs/src/index.md b/docs/src/index.md index 0713d71f1e..bdd9c798b1 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -49,7 +49,7 @@ 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 Basic-features), +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/src/Highs.h). diff --git a/docs/src/interfaces/julia/index.md b/docs/src/interfaces/julia/index.md index 9c877a091c..26165acf00 100644 --- a/docs/src/interfaces/julia/index.md +++ b/docs/src/interfaces/julia/index.md @@ -59,7 +59,7 @@ and provide a link to the gist in the GitHub issue. HiGHS.jl is a thin wrapper around the complete [HiGHS C API](@ref c-api). -As a basic example, we solve the problem: +As a basic example, we solve the model: ```math \begin{aligned} diff --git a/docs/src/interfaces/python/index.md b/docs/src/interfaces/python/index.md index 629f0a883f..ae9c3fc7e3 100644 --- a/docs/src/interfaces/python/index.md +++ b/docs/src/interfaces/python/index.md @@ -47,7 +47,7 @@ the [examples section](@ref example-py), it is referred to as `status`. ## First example -The following Python code reads a problem from the file `model.mps`, and then +The following Python code reads a model from the file `model.mps`, and then solves it. ```python diff --git a/docs/src/parallel.md b/docs/src/parallel.md index 3322fb7fc7..b14defc01e 100644 --- a/docs/src/parallel.md +++ b/docs/src/parallel.md @@ -42,7 +42,7 @@ parallel dual simplex solver is unlikely to be worth using. ## MIP The only parallel computation currently implemented in the MIP solver -occurs when performing symmetry detection on the problem, and when +occurs when performing symmetry detection on the model, and when querying clique tables. This parallelism is always advantageous, so is performed regardless of the value of the [parallel](@ref) option. diff --git a/docs/src/terminology.md b/docs/src/terminology.md index e34829c08b..fba4e7849c 100644 --- a/docs/src/terminology.md +++ b/docs/src/terminology.md @@ -128,10 +128,10 @@ 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 LP problems, each of which has bounds on the variables -that are tighter than those of the original problem. 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 +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