From ab67c242417167dcd14b8c6a8003890de5767931 Mon Sep 17 00:00:00 2001 From: Henri Lefebvre Date: Fri, 21 Jun 2024 13:58:38 +0200 Subject: [PATCH] update doc, fix references --- docs/api/classes/branch-and-bound/BranchAndBound.rst | 2 +- docs/api/classes/branch-and-bound/BranchAndBoundCallback.rst | 2 ++ .../classes/column-generation/DantzigWolfeDecomposition.rst | 2 +- docs/api/classes/universal-callbacks/Callback.rst | 2 ++ docs/api/classes/universal-callbacks/LazyCutCallback.rst | 2 +- docs/api/constants/tolerances.rst | 2 +- docs/api/types/common/{CtrType => CtrType.rst} | 0 docs/api/types/universal-callbacks/CallbackEvent.rst | 2 ++ docs/developer_guide/build-the-doc.rst | 2 +- docs/examples/bilevel-problem.rst | 4 ++-- docs/examples/facility-location-problem.rst | 4 ++-- docs/examples/generalized-assignment-problem.rst | 4 ++-- docs/examples/knapsack-problem.rst | 4 ++-- docs/faq/mosek-and-eigen.rst | 2 ++ docs/index.rst | 2 +- .../mixed-integer-programming/dantzig-wolfe/index.rst | 2 ++ .../dantzig-wolfe/old/dantzig_wolfe.rst | 2 +- .../dantzig-wolfe/strong-branching.rst | 2 +- .../mixed-integer-programming/modeling/variables.rst | 2 +- .../optimizers/create-universal-callback.rst | 2 +- .../optimizers/universal-callbacks.rst | 2 +- lib/include/idol/modeling/constraints/TempCtr.h | 2 +- lib/include/idol/modeling/models/Model.h | 2 +- 23 files changed, 31 insertions(+), 21 deletions(-) rename docs/api/types/common/{CtrType => CtrType.rst} (100%) diff --git a/docs/api/classes/branch-and-bound/BranchAndBound.rst b/docs/api/classes/branch-and-bound/BranchAndBound.rst index b44abddf..1b7b3d75 100644 --- a/docs/api/classes/branch-and-bound/BranchAndBound.rst +++ b/docs/api/classes/branch-and-bound/BranchAndBound.rst @@ -8,7 +8,7 @@ It can be used to create customized branch-and-bound algorithms with a large deg .. seealso:: - If you are not familiar with optimizers and optimizer factories, please refer to :ref:`this page `. + If you are not familiar with optimizers and optimizer factories, please refer to :ref:`this page `. .. admonition:: Example diff --git a/docs/api/classes/branch-and-bound/BranchAndBoundCallback.rst b/docs/api/classes/branch-and-bound/BranchAndBoundCallback.rst index 52c6f174..5432eb88 100644 --- a/docs/api/classes/branch-and-bound/BranchAndBoundCallback.rst +++ b/docs/api/classes/branch-and-bound/BranchAndBoundCallback.rst @@ -1,3 +1,5 @@ +.. _api_BranchAndBoundCallback: + BranchAndBoundCallback ====================== diff --git a/docs/api/classes/column-generation/DantzigWolfeDecomposition.rst b/docs/api/classes/column-generation/DantzigWolfeDecomposition.rst index 918445ae..16710386 100644 --- a/docs/api/classes/column-generation/DantzigWolfeDecomposition.rst +++ b/docs/api/classes/column-generation/DantzigWolfeDecomposition.rst @@ -4,6 +4,6 @@ DantzigWolfeDecomposition .. hint:: This page documents on the `DantzigWolfeDecomposition` optimizer factory. Note that there are also - :ref:`Dantzig-Wolfe Decomposition tutorials `. + :ref:`Dantzig-Wolfe Decomposition tutorials `. .. doxygenclass:: idol::DantzigWolfeDecomposition diff --git a/docs/api/classes/universal-callbacks/Callback.rst b/docs/api/classes/universal-callbacks/Callback.rst index 7f3c2f3a..63c00d3a 100644 --- a/docs/api/classes/universal-callbacks/Callback.rst +++ b/docs/api/classes/universal-callbacks/Callback.rst @@ -1,3 +1,5 @@ +.. _api_Callback: + Callback ======== diff --git a/docs/api/classes/universal-callbacks/LazyCutCallback.rst b/docs/api/classes/universal-callbacks/LazyCutCallback.rst index 2197b5f0..ab484275 100644 --- a/docs/api/classes/universal-callbacks/LazyCutCallback.rst +++ b/docs/api/classes/universal-callbacks/LazyCutCallback.rst @@ -54,7 +54,7 @@ with :math:`\varepsilon` a given tolerance (by default, :code:`Tolerance::Feasib .. hint:: You may also be interested by a tutorial showing how you can implement a simple Benders Decomposition using lazy - cuts. :ref:`See Benders Decomposition tutorial `. + cuts. :ref:`See Benders Decomposition tutorial `. .. doxygenclass:: idol::LazyCutCallback \ No newline at end of file diff --git a/docs/api/constants/tolerances.rst b/docs/api/constants/tolerances.rst index 0fe7410d..d25b2cef 100644 --- a/docs/api/constants/tolerances.rst +++ b/docs/api/constants/tolerances.rst @@ -1,4 +1,4 @@ -.. _api_api_tolerances: +.. _api_tolerances: Tolerances and Numerics ======================= diff --git a/docs/api/types/common/CtrType b/docs/api/types/common/CtrType.rst similarity index 100% rename from docs/api/types/common/CtrType rename to docs/api/types/common/CtrType.rst diff --git a/docs/api/types/universal-callbacks/CallbackEvent.rst b/docs/api/types/universal-callbacks/CallbackEvent.rst index 0a4f03c0..823233be 100644 --- a/docs/api/types/universal-callbacks/CallbackEvent.rst +++ b/docs/api/types/universal-callbacks/CallbackEvent.rst @@ -1,3 +1,5 @@ +.. _api_CallbackEvent: + Events ====== diff --git a/docs/developer_guide/build-the-doc.rst b/docs/developer_guide/build-the-doc.rst index 186c3813..4d331aef 100644 --- a/docs/developer_guide/build-the-doc.rst +++ b/docs/developer_guide/build-the-doc.rst @@ -9,7 +9,7 @@ This page explains how to build the documentation on a local machine. Dependencies ------------ -LowerLevelDescription +Description ^^^^^^^^^^^ The documentation is built using `doxygen`_ and a bunch of other tools, in particular: diff --git a/docs/examples/bilevel-problem.rst b/docs/examples/bilevel-problem.rst index 2e65def7..0e7210c9 100644 --- a/docs/examples/bilevel-problem.rst +++ b/docs/examples/bilevel-problem.rst @@ -1,7 +1,7 @@ .. _example_mibs: -MILP-MILP Example with MibS -=========================== +Bilevel MILP-MILP (MibS) +======================== Problem Definition ------------------ diff --git a/docs/examples/facility-location-problem.rst b/docs/examples/facility-location-problem.rst index e4f3cd06..c81328bc 100644 --- a/docs/examples/facility-location-problem.rst +++ b/docs/examples/facility-location-problem.rst @@ -1,7 +1,7 @@ .. _example_flp: -Facility Location Problem -========================= +Facility Location Problem (Branch-and-Bound) +============================================ Problem Definition ------------------ diff --git a/docs/examples/generalized-assignment-problem.rst b/docs/examples/generalized-assignment-problem.rst index ff62c20e..a02a79f0 100644 --- a/docs/examples/generalized-assignment-problem.rst +++ b/docs/examples/generalized-assignment-problem.rst @@ -1,5 +1,5 @@ -Generalized Assignment Problem -============================== +Generalized Assignment Problem (Branch-and-Price) +================================================= Problem Definition ------------------ diff --git a/docs/examples/knapsack-problem.rst b/docs/examples/knapsack-problem.rst index c8dd6c3e..bc54d339 100644 --- a/docs/examples/knapsack-problem.rst +++ b/docs/examples/knapsack-problem.rst @@ -1,5 +1,5 @@ -Knapsack Problem -================ +Knapsack Problem (HiGHS) +========================= Problem Definition ------------------ diff --git a/docs/faq/mosek-and-eigen.rst b/docs/faq/mosek-and-eigen.rst index ec85705a..f54b1354 100644 --- a/docs/faq/mosek-and-eigen.rst +++ b/docs/faq/mosek-and-eigen.rst @@ -1,3 +1,5 @@ +.. _mosek_and_socp: + Why is Eigen necessary to solve QPs and QCQPs with Mosek? ========================================================= diff --git a/docs/index.rst b/docs/index.rst index 4c3112a2..d2ad161b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -38,7 +38,7 @@ combined to create a new algorithm, `branch_and_price`, which can be instantiate Getting Started With Idol ------------------------- -If you are new to idol, be sure to have a look at our :ref:`tutorials `. If you want to get a fast hands-on +If you are new to idol, be sure to have a look at our :ref:`tutorials `. If you want to get a fast hands-on start, have a look at our :ref:`local installation guideline `. It is the easiest installation process one could think of since it automatically downloads the latest version of idol, and installs it locally in a sub-folder. It's really a mater of seconds before you can start using idol. diff --git a/docs/tutorials/mixed-integer-programming/dantzig-wolfe/index.rst b/docs/tutorials/mixed-integer-programming/dantzig-wolfe/index.rst index 9f54893c..0aba8b1d 100644 --- a/docs/tutorials/mixed-integer-programming/dantzig-wolfe/index.rst +++ b/docs/tutorials/mixed-integer-programming/dantzig-wolfe/index.rst @@ -1,3 +1,5 @@ +.. _tutorial_DantzigWolfe: + Column Generation and Branch-and-Price Algorithm ================================================ diff --git a/docs/tutorials/mixed-integer-programming/dantzig-wolfe/old/dantzig_wolfe.rst b/docs/tutorials/mixed-integer-programming/dantzig-wolfe/old/dantzig_wolfe.rst index d5095acd..1e4264f7 100644 --- a/docs/tutorials/mixed-integer-programming/dantzig-wolfe/old/dantzig_wolfe.rst +++ b/docs/tutorials/mixed-integer-programming/dantzig-wolfe/old/dantzig_wolfe.rst @@ -90,7 +90,7 @@ Assuming that the instance file is named :code:`instance.txt`, it can be loaded const unsigned int n_agents = instance.n_agents(); const unsigned int n_jobs = instance.n_jobs(); -We are now ready to model our problem (for more details, refer to :ref:`this tutorial on modeling `) +We are now ready to model our problem (for more details, refer to :ref:`this tutorial on modeling `) .. code-block:: cpp diff --git a/docs/tutorials/mixed-integer-programming/dantzig-wolfe/strong-branching.rst b/docs/tutorials/mixed-integer-programming/dantzig-wolfe/strong-branching.rst index e0c3793e..cbd0bfd3 100644 --- a/docs/tutorials/mixed-integer-programming/dantzig-wolfe/strong-branching.rst +++ b/docs/tutorials/mixed-integer-programming/dantzig-wolfe/strong-branching.rst @@ -21,7 +21,7 @@ part is closest to `0.5`. Unfortunately, this rule performs badly in practice. M computationally hard, it makes sense to spend some time in carefully choosing the variable to branch on. This is typically the case when nodes are solved using Column Generation. -.. info:: +.. hint:: Clearly, Strong Branching is not only used in the context of column generation. It is a general technique that can be used in any context where solving a node is computationally expensive. Thus, this tutorial is not specific to the diff --git a/docs/tutorials/mixed-integer-programming/modeling/variables.rst b/docs/tutorials/mixed-integer-programming/modeling/variables.rst index 1f625947..edd3085f 100644 --- a/docs/tutorials/mixed-integer-programming/modeling/variables.rst +++ b/docs/tutorials/mixed-integer-programming/modeling/variables.rst @@ -72,7 +72,7 @@ parameters. For instance, the following code is equivalent to the previous one. Model model2(env); model2.add(x, TempVar(0, 10, Continuous)); -Here, we used the class :ref:`TempVar ` to create a temporary variable. A temporary variable is a variable +Here, we used the class :ref:`TempVar ` to create a temporary variable. A temporary variable is a variable which has not been instantiate yet. It is only a "template" of a variable specifying its bounds and type. Here, we therefore add the variable :math:`x` to the second model and directly set its attributes (bounds and type) accordingly. diff --git a/docs/tutorials/mixed-integer-programming/optimizers/create-universal-callback.rst b/docs/tutorials/mixed-integer-programming/optimizers/create-universal-callback.rst index 105d953e..e85540f7 100644 --- a/docs/tutorials/mixed-integer-programming/optimizers/create-universal-callback.rst +++ b/docs/tutorials/mixed-integer-programming/optimizers/create-universal-callback.rst @@ -66,7 +66,7 @@ The nested class :code:`Strategy` is the actual callback implementation. It is a overrides the :code:`operator()` method. In this example, the callback prints the value of the primal solution whenever the event triggering the callback is :code:`IncumbentSolution`. In other words, this callback will print out all incumbent solutions found by the solver. -As for the :ref:`UserCutCallback ` and :ref:`LazyConstraintCallback ` classes, +As for the :ref:`UserCutCallback ` and :ref:`LazyConstraintCallback ` classes, our new callback can be added to an optimizer as follows. .. code:: cpp diff --git a/docs/tutorials/mixed-integer-programming/optimizers/universal-callbacks.rst b/docs/tutorials/mixed-integer-programming/optimizers/universal-callbacks.rst index 6c0046a0..ccc6a329 100644 --- a/docs/tutorials/mixed-integer-programming/optimizers/universal-callbacks.rst +++ b/docs/tutorials/mixed-integer-programming/optimizers/universal-callbacks.rst @@ -252,7 +252,7 @@ We are now ready to create the callback factory and pass it to the optimizer. Th That's it! The optimizer will now call the callback function at each node of the branch-and-cut tree, and add the cuts to the master problem whenever a violated constraint is found. -.. info:: +.. hint:: Here, we added a call to :code:`Gurobi::with_lazy_cut`. This is because the Gurobi optimizer does not support lazy cuts by default and one needs to explicitly enable them. diff --git a/lib/include/idol/modeling/constraints/TempCtr.h b/lib/include/idol/modeling/constraints/TempCtr.h index 3a0b0515..e8f32c0a 100644 --- a/lib/include/idol/modeling/constraints/TempCtr.h +++ b/lib/include/idol/modeling/constraints/TempCtr.h @@ -24,7 +24,7 @@ namespace idol { * * This class represents a constraint which has not been built yet by a Model. * It contains all the arguments needed to create a real constraint - * as instantiated by the `Ctr` class. It is made of a row (see `Row`) and a type (see `CtrType.rst`). + * as instantiated by the `Ctr` class. It is made of a row (see `Row`) and a type (see `CtrType.rst.rst`). * * Typically, one creates a `TempCtr` by using the overloaded operators `<=`, `>=` and `==` between variable expressions (i.e., `Expr`) and * constant terms (i.e., `Constant`). diff --git a/lib/include/idol/modeling/models/Model.h b/lib/include/idol/modeling/models/Model.h index 17c3daf4..57698be9 100644 --- a/lib/include/idol/modeling/models/Model.h +++ b/lib/include/idol/modeling/models/Model.h @@ -837,7 +837,7 @@ class idol::Model : public Matrix { * * Example: * ```cpp - * CtrType.rst type = model.get_ctr_type(c1); + * CtrType.rst.rst type = model.get_ctr_type(c1); * * if (type == LessOrEqual) { * std::cout << "c1 is a <= constraint" << std::endl;