diff --git a/0.2/_sources/jump-tutorials/getting-started.ipynb.txt b/0.2/_sources/jump-tutorials/getting-started.ipynb.txt index dc717b8..a023994 100644 --- a/0.2/_sources/jump-tutorials/getting-started.ipynb.txt +++ b/0.2/_sources/jump-tutorials/getting-started.ipynb.txt @@ -2,7 +2,7 @@ "cells": [ { "cell_type": "markdown", - "id": "c5a596fb", + "id": "546635ee", "metadata": {}, "source": [ "# Getting started with MIPLearn\n", @@ -19,8 +19,7 @@ "
\n", "Note\n", " \n", - "We use SCIP in this tutorial because it is a fast and widely available noncommercial MIP solver. All the steps shown here also work for Gurobi, CPLEX and XPRESS, although the performance impact might be different.\n", - " \n", + "In this tutorial, we use SCIP because it is more widely available than commercial MIP solvers. However, all the steps below should work for Gurobi, CPLEX or XPRESS, as long as you have a license for these solvers. The performance impact of MIPLearn may also change for different solvers.\n", "
\n", "\n", "
\n", @@ -33,10 +32,10 @@ }, { "cell_type": "markdown", - "id": "1f59417f", + "id": "8b97258c", "metadata": {}, "source": [ - "## Installing MIPLearn\n", + "## Installation\n", "\n", "MIPLearn is available in two versions:\n", "\n", @@ -49,14 +48,16 @@ { "cell_type": "code", "execution_count": 1, - "id": "1ddeeb8e", + "id": "2dbeacbc", "metadata": {}, "outputs": [ { "name": "stderr", "output_type": "stream", "text": [ - "Path `/home/axavier/Packages/MIPLearn.jl/dev` exists and looks like the correct package. Using existing path.\n", + "\u001b[32m\u001b[1m Updating\u001b[22m\u001b[39m git-repo `https://github.com/ANL-CEEESA/MIPLearn.jl.git`\n", + "\u001b[32m\u001b[1m Updating\u001b[22m\u001b[39m registry at `~/.julia/registries/General`\n", + "\u001b[32m\u001b[1m Updating\u001b[22m\u001b[39m git-repo `https://github.com/JuliaRegistries/General.git`\n", "\u001b[32m\u001b[1m Resolving\u001b[22m\u001b[39m package versions...\n", "\u001b[32m\u001b[1m No Changes\u001b[22m\u001b[39m to `~/Packages/MIPLearn/dev/docs/jump-tutorials/Project.toml`\n", "\u001b[32m\u001b[1m No Changes\u001b[22m\u001b[39m to `~/Packages/MIPLearn/dev/docs/jump-tutorials/Manifest.toml`\n" @@ -65,40 +66,35 @@ ], "source": [ "using Pkg\n", - "Pkg.develop(PackageSpec(path=\"/home/axavier/Packages/MIPLearn.jl/dev\"))" + "Pkg.add(PackageSpec(url=\"https://github.com/ANL-CEEESA/MIPLearn.jl.git\"))" ] }, { "cell_type": "markdown", - "id": "de7ab489", + "id": "b2f449e7", "metadata": {}, "source": [ "In addition to MIPLearn itself, we will also install a few other packages that are required for this tutorial:\n", "\n", - "- `SCIP`, a non-commercial mixed-integer programming solver\n", - "- `JuMP`, an open-source modeling language for Julia\n", - "- `Distributions`, a statistics package that we will use to generate random inputs\n", - "- `Glob`, a package that retrieves all files in a directory matching a certain pattern" + "- [**SCIP**](https://www.scipopt.org/), one of the fastest non-commercial MIP solvers currently available\n", + "- [**JuMP**](https://jump.dev/), an open source modeling language for Julia\n", + "- [**Distributions.jl**](https://github.com/JuliaStats/Distributions.jl), a statistics package that we will use to generate random inputs\n", + "- [**Glob.jl**](https://github.com/vtjnash/Glob.jl), a package that retrieves all files in a directory matching a certain pattern" ] }, { "cell_type": "code", "execution_count": 2, - "id": "29d29925", + "id": "68f99568", "metadata": {}, "outputs": [ { "name": "stderr", "output_type": "stream", "text": [ - "\u001b[32m\u001b[1m Updating\u001b[22m\u001b[39m registry at `~/.julia/registries/General`\n", - "\u001b[32m\u001b[1m Updating\u001b[22m\u001b[39m git-repo `https://github.com/JuliaRegistries/General.git`\n", "\u001b[32m\u001b[1m Resolving\u001b[22m\u001b[39m package versions...\n", "\u001b[32m\u001b[1m No Changes\u001b[22m\u001b[39m to `~/Packages/MIPLearn/dev/docs/jump-tutorials/Project.toml`\n", - "\u001b[32m\u001b[1m No Changes\u001b[22m\u001b[39m to `~/Packages/MIPLearn/dev/docs/jump-tutorials/Manifest.toml`\n", - "\u001b[32m\u001b[1mPrecompiling\u001b[22m\u001b[39m project...\n", - "\u001b[32m ✓ \u001b[39mMIPLearn\n", - "1 dependency successfully precompiled in 10 seconds (96 already precompiled)\n" + "\u001b[32m\u001b[1m No Changes\u001b[22m\u001b[39m to `~/Packages/MIPLearn/dev/docs/jump-tutorials/Manifest.toml`\n" ] } ], @@ -109,13 +105,12 @@ " PackageSpec(name=\"JuMP\", version=\"0.21\"),\n", " PackageSpec(name=\"Distributions\", version=\"0.25\"),\n", " PackageSpec(name=\"Glob\", version=\"1\"),\n", - "])\n", - "using Revise" + "])" ] }, { "cell_type": "markdown", - "id": "88074d87", + "id": "51e09fc9", "metadata": {}, "source": [ "
\n", @@ -129,16 +124,16 @@ }, { "cell_type": "markdown", - "id": "78482747", + "id": "18c300c4", "metadata": {}, "source": [ "## Modeling a simple optimization problem\n", "\n", "To illustrate how can MIPLearn be used, we will model and solve a small optimization problem related to power systems optimization. The problem we discuss below is a simplification of the **unit commitment problem,** a practical optimization problem solved daily by electric grid operators around the world. \n", "\n", - "Suppose that you work at a utility company, and that it is your job to decide which electrical generators should be online at a certain hour of the day, and how much power should each generator produce. More specifically, assume that your company owns $n$ generators, denoted by $g_1, \\ldots, g_n$. Each generator can either be online or offline. An online generator $g_i$ can produce between $p^\\text{min}_i$ to $p^\\text{max}_i$ megawatts of power, and it costs your company $c^\\text{fixed}_i + c^\\text{var}_i y_i$, where $y_i$ is the amount of power produced. An offline generator produces nothing, and costs nothing. You also know that the total amount of power to be produced needs to be exactly equal to the total demand $d$ (in megawatts). To minimize the costs to your company, which generators should be online, and how much power should they produce?\n", + "Suppose that you work at a utility company, and that it is your job to decide which electrical generators should be online at a certain hour of the day, as well as how much power should each generator produce. More specifically, assume that your company owns $n$ generators, denoted by $g_1, \\ldots, g_n$. Each generator can either be online or offline. An online generator $g_i$ can produce between $p^\\text{min}_i$ to $p^\\text{max}_i$ megawatts of power, and it costs your company $c^\\text{fix}_i + c^\\text{var}_i y_i$, where $y_i$ is the amount of power produced. An offline generator produces nothing and costs nothing. You also know that the total amount of power to be produced needs to be exactly equal to the total demand $d$ (in megawatts). To minimize the costs to your company, which generators should be online, and how much power should they produce?\n", "\n", - "This simple problem be modeled as a *mixed-integer linear optimization* problem as follows. For each generator $g_i$, let $x_i \\in \\{0,1\\}$ be a decision variable indicating whether $g_i$ is online, and let $y_i \\geq 0$ be a decision variable indicating how much power does $g_i$ produce. The problem we need to solve is given by:\n", + "This simple problem can be modeled as a *mixed-integer linear optimization* problem as follows. For each generator $g_i$, let $x_i \\in \\{0,1\\}$ be a decision variable indicating whether $g_i$ is online, and let $y_i \\geq 0$ be a decision variable indicating how much power does $g_i$ produce. The problem is then given by:\n", "\n", "$$\n", "\\begin{align}\n", @@ -155,17 +150,17 @@ " \n", "Note\n", " \n", - "We use a simplified version of the unit commitment problem in this tutorial just to make it easier to follow. MIPLearn can also handle realistic, large-scale versions of this problem. See the benchmark sections for more details.\n", + "We use a simplified version of the unit commitment problem in this tutorial just to make it easier to follow. MIPLearn can also handle realistic, large-scale versions of this problem. See benchmarks for more details.\n", " \n", "
\n", "\n", - "Next, let us convert this abstract mathematical formulation into a concrete optimization model, using the Julia and the JuMP modeling language. We start by defining a data structure that holds all input data:" + "Next, let us convert this abstract mathematical formulation into a concrete optimization model, using Julia and JuMP. We start by defining a data structure that holds all the input data." ] }, { "cell_type": "code", "execution_count": 3, - "id": "ec7dbab4", + "id": "b12d6483", "metadata": {}, "outputs": [], "source": [ @@ -180,16 +175,16 @@ }, { "cell_type": "markdown", - "id": "c8f6a5b8", + "id": "55cdb64b", "metadata": {}, "source": [ - "Next, we create a function that converts this data into a concrete JuMP model:" + "Next, we create a function that converts this data structure into a concrete JuMP model. For more details on the JuMP syntax, see [the official JuMP documentation](https://jump.dev/JuMP.jl/stable/)." ] }, { "cell_type": "code", "execution_count": 4, - "id": "14e84c92", + "id": "1e38a266", "metadata": {}, "outputs": [], "source": [ @@ -218,7 +213,7 @@ }, { "cell_type": "markdown", - "id": "f647734f", + "id": "d28c4d5a", "metadata": {}, "source": [ "At this point, we can already use JuMP and any mixed-integer linear programming solver to find optimal solutions to any instance of this problem. To illustrate this, let us solve a small instance with three generators, using SCIP:" @@ -227,7 +222,7 @@ { "cell_type": "code", "execution_count": 5, - "id": "b2abe5e2", + "id": "9ff9f05c", "metadata": {}, "outputs": [ { @@ -242,7 +237,6 @@ ], "source": [ "using SCIP\n", - "using Printf\n", "\n", "model = build_uc_model(\n", " UnitCommitmentData(\n", @@ -266,7 +260,7 @@ }, { "cell_type": "markdown", - "id": "5be976f5", + "id": "345de591", "metadata": {}, "source": [ "Running the code above, we found that the optimal solution for our small problem instance costs \\$1320. It is achieve by keeping generators 2 and 3 online and producing, respectively, 60 MW and 40 MW of power." @@ -274,7 +268,7 @@ }, { "cell_type": "markdown", - "id": "96a1f952", + "id": "eb8904ef", "metadata": {}, "source": [ "## Generating training data\n", @@ -289,7 +283,7 @@ { "cell_type": "code", "execution_count": 6, - "id": "353e6199", + "id": "7298bb0d", "metadata": {}, "outputs": [], "source": [ @@ -317,7 +311,7 @@ }, { "cell_type": "markdown", - "id": "2140968d", + "id": "c1feed43", "metadata": {}, "source": [ "In this example, for simplicity, only the demands change from one instance to the next. We could also have made the prices and the production limits random. The more randomization we have in the training data, however, the more challenging it is for the machine learning models to learn solution patterns.\n", @@ -328,7 +322,7 @@ { "cell_type": "code", "execution_count": 7, - "id": "1bb24909", + "id": "61d43994", "metadata": {}, "outputs": [], "source": [ @@ -339,34 +333,33 @@ }, { "cell_type": "markdown", - "id": "96bc0e42", + "id": "3fdeb8cd", "metadata": {}, "source": [ - "Next, we will write these data structures to individual files. MIPLearn uses files during the training process because, for large-scale optimization problems, it is often impractical to hold the entire training data, as well as the concrete JuMP models, in memory. Files also make it much easier to solve multiple instances simultaneously, potentially even on multiple machines. We will cover parallel and distributed computing in a future tutorial.\n", + "Next, we write these data structures to individual files. MIPLearn uses files during the training process because, for large-scale optimization problems, it is often impractical to hold the entire training data, as well as the concrete JuMP models, in memory. Files also make it much easier to solve multiple instances simultaneously, potentially even on multiple machines. We will cover parallel and distributed computing in a future tutorial.\n", "\n", - "The code below generates the files `uc/train/000001.jld2`, `uc/train/000002.jld2`, etc." + "The code below generates the files `uc/train/000001.jld2`, `uc/train/000002.jld2`, etc., which contain the input data in [JLD2 format](https://github.com/JuliaIO/JLD2.jl)." ] }, { "cell_type": "code", "execution_count": 8, - "id": "8ec476b1", + "id": "31b48701", "metadata": {}, "outputs": [], "source": [ "using MIPLearn\n", - "using Glob\n", - "\n", "MIPLearn.save(data[1:90], \"uc/train/\")\n", "MIPLearn.save(data[91:100], \"uc/test/\")\n", "\n", + "using Glob\n", "train_files = glob(\"uc/train/*.jld2\")\n", "test_files = glob(\"uc/test/*.jld2\");" ] }, { "cell_type": "markdown", - "id": "5d53a783", + "id": "5cecea59", "metadata": {}, "source": [ "Finally, we use `MIPLearn.LearningSolver` and `MIPLearn.solve!` to solve all the training instances. `LearningSolver` is the main component provided by MIPLearn, which integrates MIP solvers and ML. The `solve!` function can be used to solve either one or multiple instances, and requires: (i) the list of files containing the training data; and (ii) the function that converts the data structure into a concrete JuMP model:" @@ -375,14 +368,14 @@ { "cell_type": "code", "execution_count": 9, - "id": "514a3b3a", + "id": "60732af0", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ - "101.279699 seconds (93.52 M allocations: 3.599 GiB, 1.23% gc time, 0.52% compilation time)\n" + "103.808547 seconds (93.52 M allocations: 3.604 GiB, 1.19% gc time, 0.52% compilation time)\n" ] }, { @@ -401,33 +394,33 @@ }, { "cell_type": "markdown", - "id": "72eb09f4", + "id": "bbc7ad82", "metadata": {}, "source": [ - "The macro `@time` shows us how long did the code take to run. We can see that SCIP was able to solve all training instances in about 2 minutes. The solutions, and other useful training data, is stored by MIPLearn in `.h5` files, stored side-by-side with the original `.jld2` files." + "The macro `@time` shows us how long did the code take to run. We can see that SCIP was able to solve all training instances in about 2 minutes. The solutions, and other useful training data, are stored by MIPLearn in `.h5` files, stored side-by-side with the original `.jld2` files." ] }, { "cell_type": "markdown", - "id": "90406b90", + "id": "73379180", "metadata": {}, "source": [ "## Solving new instances\n", "\n", - "Now that we have training data, we can fit the ML models using `MIPLearn.fit!`, then solve the test instances with `MIPLearn.solve!`, as shown below:" + "With training data in hand, we can now fit the ML models using `MIPLearn.fit!`, then solve the test instances with `MIPLearn.solve!`, as shown below:" ] }, { "cell_type": "code", "execution_count": 10, - "id": "e4de94db", + "id": "e045d644", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ - " 5.693951 seconds (9.33 M allocations: 334.689 MiB, 1.62% gc time)\n" + " 5.951264 seconds (9.33 M allocations: 334.657 MiB, 1.51% gc time)\n" ] } ], @@ -439,23 +432,23 @@ }, { "cell_type": "markdown", - "id": "247c1087", + "id": "d8de7b26", "metadata": {}, "source": [ - "The trained MIP solver was able to solve all test instances in about 5 seconds. To see that ML is being helpful here, let us repeat the code above, but remove the `fit!` line:" + "The trained MIP solver was able to solve all test instances in about 6 seconds. To see that ML is being helpful here, let us repeat the code above, but remove the `fit!` line:" ] }, { "cell_type": "code", "execution_count": 11, - "id": "62061b12", + "id": "cf2a989e", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ - " 9.829350 seconds (8.17 M allocations: 278.008 MiB, 0.47% gc time)\n" + " 10.390325 seconds (8.17 M allocations: 278.042 MiB, 0.89% gc time)\n" ] } ], @@ -466,10 +459,10 @@ }, { "cell_type": "markdown", - "id": "8ea5c423", + "id": "e100b25d", "metadata": {}, "source": [ - "Without the help of the ML models, SCIP took around 10 seconds to solve the same test instances, or about twice as long.\n", + "Without the help of the ML models, SCIP took around 10 seconds to solve the same test instances.\n", "\n", "
\n", "Note\n", @@ -480,18 +473,18 @@ }, { "cell_type": "markdown", - "id": "569f7c7a", + "id": "af451e87", "metadata": {}, "source": [ "## Understanding the acceleration\n", "\n", - "Let us know go a bit deeper and try to understand how exactly did MIPLearn accelerate SCIP's performance. First, we are going to solve one of the training instances again, using the trained solver, but this time using the `tee=true` parameter, so that we can see SCIP's log:" + "Let us go a bit deeper and try to understand how exactly did MIPLearn accelerate SCIP's performance. First, we are going to solve one of the test instances again, using the trained solver, but this time using the `tee=true` parameter, so that we can see SCIP's log:" ] }, { "cell_type": "code", "execution_count": 12, - "id": "46739739", + "id": "0c675452", "metadata": {}, "outputs": [ { @@ -538,7 +531,7 @@ "presolved problem has 2000 variables (1000 bin, 0 int, 0 impl, 1000 cont) and 2001 constraints\n", " 2000 constraints of type \n", " 1 constraints of type \n", - "Presolving Time: 0.10\n", + "Presolving Time: 0.11\n", "transformed 1/1 original solutions to the transformed problem space\n", "\n", " time | node | left |LP iter|LP it/n|mem/heur|mdpt |vars |cons |rows |cuts |sepa|confs|strbr| dualbound | primalbound | gap | compl. \n", @@ -560,18 +553,18 @@ }, { "cell_type": "markdown", - "id": "9cdc02d0", + "id": "ff0b6858", "metadata": {}, "source": [ - "The log above is quite complicated if you have never seen it before, but the important line in the one starting with `feasible solution found [...] objective value 1.705169e+07`. This line indicates that MIPLearn was able to construct a warm start with value `1.705169e+07`. Using this warm start, SCIP then proceeded with the branch-and-cut process to either prove its optimality or find an even better solution. Very quickly, however, SCIP proved that the solution produced by MIPLearn was indeed optimal and terminated. It was able to do this without generating a single cutting plane or running any other heuristics; it could tell the optimality by the root LP relaxation alone, which was very fast. \n", + "The log above is quite complicated if you have never seen it before, but the important line is the one starting with `feasible solution found [...] objective value 1.705169e+07`. This line indicates that MIPLearn was able to construct a warm start with value `1.705169e+07`. Using this warm start, SCIP then used the branch-and-cut method to either prove its optimality or to find an even better solution. Very quickly, however, SCIP proved that the solution produced by MIPLearn was indeed optimal. It was able to do this without generating a single cutting plane or running any other heuristics; it could tell the optimality by the root LP relaxation alone, which was very fast. \n", "\n", - "Let us now do the same thing again, but using the untrained solver this time:" + "Let us now repeat the process, but using the untrained solver this time:" ] }, { "cell_type": "code", "execution_count": 13, - "id": "555af477", + "id": "1aa9230e", "metadata": {}, "outputs": [ { @@ -642,7 +635,7 @@ "L 0.7s| 1 | 0 | 1707 | - | alns| 0 |2000 |2001 |2015 | 14 | 11 | 0 | 0 | 1.705038e+07 | 1.705178e+07 | 0.01%| unknown\n", "\n", "SCIP Status : solving was interrupted [gap limit reached]\n", - "Solving Time (sec) : 0.67\n", + "Solving Time (sec) : 0.68\n", "Solving Nodes : 1\n", "Primal Bound : +1.70517823853380e+07 (13 solutions)\n", "Dual Bound : +1.70503798271962e+07\n", @@ -657,15 +650,17 @@ }, { "cell_type": "markdown", - "id": "72a52d26", + "id": "9417bb85", "metadata": {}, "source": [ - "In this log file, notice how the line we saw before is now missing; SCIP needs to find an initial solution using its own internal heuristics. The solution SCIP initially found has value `2.335200e+07`, which is significantly worse than the one MIPLearn constructed before. SCIP then proceeds to improve this solution by generating a number of cutting planes and repeatedly running primal heuristics. In the end, it is able to find the optimal solution, as expected, but it takes longer." + "In this log file, notice how the previous line about warm starts is missing. Since no warm starts were provided, SCIP had to find an initial solution using its own internal heuristics, which are not specifically tailored for this problem. The initial solution found by SCIP's heuristics has value `2.335200e+07`, which is significantly worse than the one constructed by MIPLearn. SCIP then proceeded to improve this solution, by generating cutting planes and repeatedly running additional primal heuristics. In the end, it was able to find the optimal solution, as expected, but it took longer.\n", + "\n", + "In summary, MIPLearn accelerated the solution process by constructing a high-quality initial solution. In the following tutorials, we will see other strategies that MIPLearn can use to accelerate MIP performance, besides warm starts." ] }, { "cell_type": "markdown", - "id": "36fb5f02", + "id": "ab9c1ff4", "metadata": {}, "source": [ "## Accessing the solution\n", @@ -678,7 +673,7 @@ { "cell_type": "code", "execution_count": 14, - "id": "f62f28b4", + "id": "79759e87", "metadata": {}, "outputs": [ { @@ -710,7 +705,7 @@ }, { "cell_type": "markdown", - "id": "d5722dcf", + "id": "b096dcf9", "metadata": {}, "source": [ "We can then solve this model as before, with `MIPLearn.solve!`:" @@ -719,7 +714,7 @@ { "cell_type": "code", "execution_count": 15, - "id": "e49f9e60", + "id": "1b668c12", "metadata": {}, "outputs": [ { diff --git a/0.2/jump-tutorials/getting-started.ipynb b/0.2/jump-tutorials/getting-started.ipynb index dc717b8..a023994 100644 --- a/0.2/jump-tutorials/getting-started.ipynb +++ b/0.2/jump-tutorials/getting-started.ipynb @@ -2,7 +2,7 @@ "cells": [ { "cell_type": "markdown", - "id": "c5a596fb", + "id": "546635ee", "metadata": {}, "source": [ "# Getting started with MIPLearn\n", @@ -19,8 +19,7 @@ "
\n", "Note\n", " \n", - "We use SCIP in this tutorial because it is a fast and widely available noncommercial MIP solver. All the steps shown here also work for Gurobi, CPLEX and XPRESS, although the performance impact might be different.\n", - " \n", + "In this tutorial, we use SCIP because it is more widely available than commercial MIP solvers. However, all the steps below should work for Gurobi, CPLEX or XPRESS, as long as you have a license for these solvers. The performance impact of MIPLearn may also change for different solvers.\n", "
\n", "\n", "
\n", @@ -33,10 +32,10 @@ }, { "cell_type": "markdown", - "id": "1f59417f", + "id": "8b97258c", "metadata": {}, "source": [ - "## Installing MIPLearn\n", + "## Installation\n", "\n", "MIPLearn is available in two versions:\n", "\n", @@ -49,14 +48,16 @@ { "cell_type": "code", "execution_count": 1, - "id": "1ddeeb8e", + "id": "2dbeacbc", "metadata": {}, "outputs": [ { "name": "stderr", "output_type": "stream", "text": [ - "Path `/home/axavier/Packages/MIPLearn.jl/dev` exists and looks like the correct package. Using existing path.\n", + "\u001b[32m\u001b[1m Updating\u001b[22m\u001b[39m git-repo `https://github.com/ANL-CEEESA/MIPLearn.jl.git`\n", + "\u001b[32m\u001b[1m Updating\u001b[22m\u001b[39m registry at `~/.julia/registries/General`\n", + "\u001b[32m\u001b[1m Updating\u001b[22m\u001b[39m git-repo `https://github.com/JuliaRegistries/General.git`\n", "\u001b[32m\u001b[1m Resolving\u001b[22m\u001b[39m package versions...\n", "\u001b[32m\u001b[1m No Changes\u001b[22m\u001b[39m to `~/Packages/MIPLearn/dev/docs/jump-tutorials/Project.toml`\n", "\u001b[32m\u001b[1m No Changes\u001b[22m\u001b[39m to `~/Packages/MIPLearn/dev/docs/jump-tutorials/Manifest.toml`\n" @@ -65,40 +66,35 @@ ], "source": [ "using Pkg\n", - "Pkg.develop(PackageSpec(path=\"/home/axavier/Packages/MIPLearn.jl/dev\"))" + "Pkg.add(PackageSpec(url=\"https://github.com/ANL-CEEESA/MIPLearn.jl.git\"))" ] }, { "cell_type": "markdown", - "id": "de7ab489", + "id": "b2f449e7", "metadata": {}, "source": [ "In addition to MIPLearn itself, we will also install a few other packages that are required for this tutorial:\n", "\n", - "- `SCIP`, a non-commercial mixed-integer programming solver\n", - "- `JuMP`, an open-source modeling language for Julia\n", - "- `Distributions`, a statistics package that we will use to generate random inputs\n", - "- `Glob`, a package that retrieves all files in a directory matching a certain pattern" + "- [**SCIP**](https://www.scipopt.org/), one of the fastest non-commercial MIP solvers currently available\n", + "- [**JuMP**](https://jump.dev/), an open source modeling language for Julia\n", + "- [**Distributions.jl**](https://github.com/JuliaStats/Distributions.jl), a statistics package that we will use to generate random inputs\n", + "- [**Glob.jl**](https://github.com/vtjnash/Glob.jl), a package that retrieves all files in a directory matching a certain pattern" ] }, { "cell_type": "code", "execution_count": 2, - "id": "29d29925", + "id": "68f99568", "metadata": {}, "outputs": [ { "name": "stderr", "output_type": "stream", "text": [ - "\u001b[32m\u001b[1m Updating\u001b[22m\u001b[39m registry at `~/.julia/registries/General`\n", - "\u001b[32m\u001b[1m Updating\u001b[22m\u001b[39m git-repo `https://github.com/JuliaRegistries/General.git`\n", "\u001b[32m\u001b[1m Resolving\u001b[22m\u001b[39m package versions...\n", "\u001b[32m\u001b[1m No Changes\u001b[22m\u001b[39m to `~/Packages/MIPLearn/dev/docs/jump-tutorials/Project.toml`\n", - "\u001b[32m\u001b[1m No Changes\u001b[22m\u001b[39m to `~/Packages/MIPLearn/dev/docs/jump-tutorials/Manifest.toml`\n", - "\u001b[32m\u001b[1mPrecompiling\u001b[22m\u001b[39m project...\n", - "\u001b[32m ✓ \u001b[39mMIPLearn\n", - "1 dependency successfully precompiled in 10 seconds (96 already precompiled)\n" + "\u001b[32m\u001b[1m No Changes\u001b[22m\u001b[39m to `~/Packages/MIPLearn/dev/docs/jump-tutorials/Manifest.toml`\n" ] } ], @@ -109,13 +105,12 @@ " PackageSpec(name=\"JuMP\", version=\"0.21\"),\n", " PackageSpec(name=\"Distributions\", version=\"0.25\"),\n", " PackageSpec(name=\"Glob\", version=\"1\"),\n", - "])\n", - "using Revise" + "])" ] }, { "cell_type": "markdown", - "id": "88074d87", + "id": "51e09fc9", "metadata": {}, "source": [ "
\n", @@ -129,16 +124,16 @@ }, { "cell_type": "markdown", - "id": "78482747", + "id": "18c300c4", "metadata": {}, "source": [ "## Modeling a simple optimization problem\n", "\n", "To illustrate how can MIPLearn be used, we will model and solve a small optimization problem related to power systems optimization. The problem we discuss below is a simplification of the **unit commitment problem,** a practical optimization problem solved daily by electric grid operators around the world. \n", "\n", - "Suppose that you work at a utility company, and that it is your job to decide which electrical generators should be online at a certain hour of the day, and how much power should each generator produce. More specifically, assume that your company owns $n$ generators, denoted by $g_1, \\ldots, g_n$. Each generator can either be online or offline. An online generator $g_i$ can produce between $p^\\text{min}_i$ to $p^\\text{max}_i$ megawatts of power, and it costs your company $c^\\text{fixed}_i + c^\\text{var}_i y_i$, where $y_i$ is the amount of power produced. An offline generator produces nothing, and costs nothing. You also know that the total amount of power to be produced needs to be exactly equal to the total demand $d$ (in megawatts). To minimize the costs to your company, which generators should be online, and how much power should they produce?\n", + "Suppose that you work at a utility company, and that it is your job to decide which electrical generators should be online at a certain hour of the day, as well as how much power should each generator produce. More specifically, assume that your company owns $n$ generators, denoted by $g_1, \\ldots, g_n$. Each generator can either be online or offline. An online generator $g_i$ can produce between $p^\\text{min}_i$ to $p^\\text{max}_i$ megawatts of power, and it costs your company $c^\\text{fix}_i + c^\\text{var}_i y_i$, where $y_i$ is the amount of power produced. An offline generator produces nothing and costs nothing. You also know that the total amount of power to be produced needs to be exactly equal to the total demand $d$ (in megawatts). To minimize the costs to your company, which generators should be online, and how much power should they produce?\n", "\n", - "This simple problem be modeled as a *mixed-integer linear optimization* problem as follows. For each generator $g_i$, let $x_i \\in \\{0,1\\}$ be a decision variable indicating whether $g_i$ is online, and let $y_i \\geq 0$ be a decision variable indicating how much power does $g_i$ produce. The problem we need to solve is given by:\n", + "This simple problem can be modeled as a *mixed-integer linear optimization* problem as follows. For each generator $g_i$, let $x_i \\in \\{0,1\\}$ be a decision variable indicating whether $g_i$ is online, and let $y_i \\geq 0$ be a decision variable indicating how much power does $g_i$ produce. The problem is then given by:\n", "\n", "$$\n", "\\begin{align}\n", @@ -155,17 +150,17 @@ " \n", "Note\n", " \n", - "We use a simplified version of the unit commitment problem in this tutorial just to make it easier to follow. MIPLearn can also handle realistic, large-scale versions of this problem. See the benchmark sections for more details.\n", + "We use a simplified version of the unit commitment problem in this tutorial just to make it easier to follow. MIPLearn can also handle realistic, large-scale versions of this problem. See benchmarks for more details.\n", " \n", "
\n", "\n", - "Next, let us convert this abstract mathematical formulation into a concrete optimization model, using the Julia and the JuMP modeling language. We start by defining a data structure that holds all input data:" + "Next, let us convert this abstract mathematical formulation into a concrete optimization model, using Julia and JuMP. We start by defining a data structure that holds all the input data." ] }, { "cell_type": "code", "execution_count": 3, - "id": "ec7dbab4", + "id": "b12d6483", "metadata": {}, "outputs": [], "source": [ @@ -180,16 +175,16 @@ }, { "cell_type": "markdown", - "id": "c8f6a5b8", + "id": "55cdb64b", "metadata": {}, "source": [ - "Next, we create a function that converts this data into a concrete JuMP model:" + "Next, we create a function that converts this data structure into a concrete JuMP model. For more details on the JuMP syntax, see [the official JuMP documentation](https://jump.dev/JuMP.jl/stable/)." ] }, { "cell_type": "code", "execution_count": 4, - "id": "14e84c92", + "id": "1e38a266", "metadata": {}, "outputs": [], "source": [ @@ -218,7 +213,7 @@ }, { "cell_type": "markdown", - "id": "f647734f", + "id": "d28c4d5a", "metadata": {}, "source": [ "At this point, we can already use JuMP and any mixed-integer linear programming solver to find optimal solutions to any instance of this problem. To illustrate this, let us solve a small instance with three generators, using SCIP:" @@ -227,7 +222,7 @@ { "cell_type": "code", "execution_count": 5, - "id": "b2abe5e2", + "id": "9ff9f05c", "metadata": {}, "outputs": [ { @@ -242,7 +237,6 @@ ], "source": [ "using SCIP\n", - "using Printf\n", "\n", "model = build_uc_model(\n", " UnitCommitmentData(\n", @@ -266,7 +260,7 @@ }, { "cell_type": "markdown", - "id": "5be976f5", + "id": "345de591", "metadata": {}, "source": [ "Running the code above, we found that the optimal solution for our small problem instance costs \\$1320. It is achieve by keeping generators 2 and 3 online and producing, respectively, 60 MW and 40 MW of power." @@ -274,7 +268,7 @@ }, { "cell_type": "markdown", - "id": "96a1f952", + "id": "eb8904ef", "metadata": {}, "source": [ "## Generating training data\n", @@ -289,7 +283,7 @@ { "cell_type": "code", "execution_count": 6, - "id": "353e6199", + "id": "7298bb0d", "metadata": {}, "outputs": [], "source": [ @@ -317,7 +311,7 @@ }, { "cell_type": "markdown", - "id": "2140968d", + "id": "c1feed43", "metadata": {}, "source": [ "In this example, for simplicity, only the demands change from one instance to the next. We could also have made the prices and the production limits random. The more randomization we have in the training data, however, the more challenging it is for the machine learning models to learn solution patterns.\n", @@ -328,7 +322,7 @@ { "cell_type": "code", "execution_count": 7, - "id": "1bb24909", + "id": "61d43994", "metadata": {}, "outputs": [], "source": [ @@ -339,34 +333,33 @@ }, { "cell_type": "markdown", - "id": "96bc0e42", + "id": "3fdeb8cd", "metadata": {}, "source": [ - "Next, we will write these data structures to individual files. MIPLearn uses files during the training process because, for large-scale optimization problems, it is often impractical to hold the entire training data, as well as the concrete JuMP models, in memory. Files also make it much easier to solve multiple instances simultaneously, potentially even on multiple machines. We will cover parallel and distributed computing in a future tutorial.\n", + "Next, we write these data structures to individual files. MIPLearn uses files during the training process because, for large-scale optimization problems, it is often impractical to hold the entire training data, as well as the concrete JuMP models, in memory. Files also make it much easier to solve multiple instances simultaneously, potentially even on multiple machines. We will cover parallel and distributed computing in a future tutorial.\n", "\n", - "The code below generates the files `uc/train/000001.jld2`, `uc/train/000002.jld2`, etc." + "The code below generates the files `uc/train/000001.jld2`, `uc/train/000002.jld2`, etc., which contain the input data in [JLD2 format](https://github.com/JuliaIO/JLD2.jl)." ] }, { "cell_type": "code", "execution_count": 8, - "id": "8ec476b1", + "id": "31b48701", "metadata": {}, "outputs": [], "source": [ "using MIPLearn\n", - "using Glob\n", - "\n", "MIPLearn.save(data[1:90], \"uc/train/\")\n", "MIPLearn.save(data[91:100], \"uc/test/\")\n", "\n", + "using Glob\n", "train_files = glob(\"uc/train/*.jld2\")\n", "test_files = glob(\"uc/test/*.jld2\");" ] }, { "cell_type": "markdown", - "id": "5d53a783", + "id": "5cecea59", "metadata": {}, "source": [ "Finally, we use `MIPLearn.LearningSolver` and `MIPLearn.solve!` to solve all the training instances. `LearningSolver` is the main component provided by MIPLearn, which integrates MIP solvers and ML. The `solve!` function can be used to solve either one or multiple instances, and requires: (i) the list of files containing the training data; and (ii) the function that converts the data structure into a concrete JuMP model:" @@ -375,14 +368,14 @@ { "cell_type": "code", "execution_count": 9, - "id": "514a3b3a", + "id": "60732af0", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ - "101.279699 seconds (93.52 M allocations: 3.599 GiB, 1.23% gc time, 0.52% compilation time)\n" + "103.808547 seconds (93.52 M allocations: 3.604 GiB, 1.19% gc time, 0.52% compilation time)\n" ] }, { @@ -401,33 +394,33 @@ }, { "cell_type": "markdown", - "id": "72eb09f4", + "id": "bbc7ad82", "metadata": {}, "source": [ - "The macro `@time` shows us how long did the code take to run. We can see that SCIP was able to solve all training instances in about 2 minutes. The solutions, and other useful training data, is stored by MIPLearn in `.h5` files, stored side-by-side with the original `.jld2` files." + "The macro `@time` shows us how long did the code take to run. We can see that SCIP was able to solve all training instances in about 2 minutes. The solutions, and other useful training data, are stored by MIPLearn in `.h5` files, stored side-by-side with the original `.jld2` files." ] }, { "cell_type": "markdown", - "id": "90406b90", + "id": "73379180", "metadata": {}, "source": [ "## Solving new instances\n", "\n", - "Now that we have training data, we can fit the ML models using `MIPLearn.fit!`, then solve the test instances with `MIPLearn.solve!`, as shown below:" + "With training data in hand, we can now fit the ML models using `MIPLearn.fit!`, then solve the test instances with `MIPLearn.solve!`, as shown below:" ] }, { "cell_type": "code", "execution_count": 10, - "id": "e4de94db", + "id": "e045d644", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ - " 5.693951 seconds (9.33 M allocations: 334.689 MiB, 1.62% gc time)\n" + " 5.951264 seconds (9.33 M allocations: 334.657 MiB, 1.51% gc time)\n" ] } ], @@ -439,23 +432,23 @@ }, { "cell_type": "markdown", - "id": "247c1087", + "id": "d8de7b26", "metadata": {}, "source": [ - "The trained MIP solver was able to solve all test instances in about 5 seconds. To see that ML is being helpful here, let us repeat the code above, but remove the `fit!` line:" + "The trained MIP solver was able to solve all test instances in about 6 seconds. To see that ML is being helpful here, let us repeat the code above, but remove the `fit!` line:" ] }, { "cell_type": "code", "execution_count": 11, - "id": "62061b12", + "id": "cf2a989e", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ - " 9.829350 seconds (8.17 M allocations: 278.008 MiB, 0.47% gc time)\n" + " 10.390325 seconds (8.17 M allocations: 278.042 MiB, 0.89% gc time)\n" ] } ], @@ -466,10 +459,10 @@ }, { "cell_type": "markdown", - "id": "8ea5c423", + "id": "e100b25d", "metadata": {}, "source": [ - "Without the help of the ML models, SCIP took around 10 seconds to solve the same test instances, or about twice as long.\n", + "Without the help of the ML models, SCIP took around 10 seconds to solve the same test instances.\n", "\n", "
\n", "Note\n", @@ -480,18 +473,18 @@ }, { "cell_type": "markdown", - "id": "569f7c7a", + "id": "af451e87", "metadata": {}, "source": [ "## Understanding the acceleration\n", "\n", - "Let us know go a bit deeper and try to understand how exactly did MIPLearn accelerate SCIP's performance. First, we are going to solve one of the training instances again, using the trained solver, but this time using the `tee=true` parameter, so that we can see SCIP's log:" + "Let us go a bit deeper and try to understand how exactly did MIPLearn accelerate SCIP's performance. First, we are going to solve one of the test instances again, using the trained solver, but this time using the `tee=true` parameter, so that we can see SCIP's log:" ] }, { "cell_type": "code", "execution_count": 12, - "id": "46739739", + "id": "0c675452", "metadata": {}, "outputs": [ { @@ -538,7 +531,7 @@ "presolved problem has 2000 variables (1000 bin, 0 int, 0 impl, 1000 cont) and 2001 constraints\n", " 2000 constraints of type \n", " 1 constraints of type \n", - "Presolving Time: 0.10\n", + "Presolving Time: 0.11\n", "transformed 1/1 original solutions to the transformed problem space\n", "\n", " time | node | left |LP iter|LP it/n|mem/heur|mdpt |vars |cons |rows |cuts |sepa|confs|strbr| dualbound | primalbound | gap | compl. \n", @@ -560,18 +553,18 @@ }, { "cell_type": "markdown", - "id": "9cdc02d0", + "id": "ff0b6858", "metadata": {}, "source": [ - "The log above is quite complicated if you have never seen it before, but the important line in the one starting with `feasible solution found [...] objective value 1.705169e+07`. This line indicates that MIPLearn was able to construct a warm start with value `1.705169e+07`. Using this warm start, SCIP then proceeded with the branch-and-cut process to either prove its optimality or find an even better solution. Very quickly, however, SCIP proved that the solution produced by MIPLearn was indeed optimal and terminated. It was able to do this without generating a single cutting plane or running any other heuristics; it could tell the optimality by the root LP relaxation alone, which was very fast. \n", + "The log above is quite complicated if you have never seen it before, but the important line is the one starting with `feasible solution found [...] objective value 1.705169e+07`. This line indicates that MIPLearn was able to construct a warm start with value `1.705169e+07`. Using this warm start, SCIP then used the branch-and-cut method to either prove its optimality or to find an even better solution. Very quickly, however, SCIP proved that the solution produced by MIPLearn was indeed optimal. It was able to do this without generating a single cutting plane or running any other heuristics; it could tell the optimality by the root LP relaxation alone, which was very fast. \n", "\n", - "Let us now do the same thing again, but using the untrained solver this time:" + "Let us now repeat the process, but using the untrained solver this time:" ] }, { "cell_type": "code", "execution_count": 13, - "id": "555af477", + "id": "1aa9230e", "metadata": {}, "outputs": [ { @@ -642,7 +635,7 @@ "L 0.7s| 1 | 0 | 1707 | - | alns| 0 |2000 |2001 |2015 | 14 | 11 | 0 | 0 | 1.705038e+07 | 1.705178e+07 | 0.01%| unknown\n", "\n", "SCIP Status : solving was interrupted [gap limit reached]\n", - "Solving Time (sec) : 0.67\n", + "Solving Time (sec) : 0.68\n", "Solving Nodes : 1\n", "Primal Bound : +1.70517823853380e+07 (13 solutions)\n", "Dual Bound : +1.70503798271962e+07\n", @@ -657,15 +650,17 @@ }, { "cell_type": "markdown", - "id": "72a52d26", + "id": "9417bb85", "metadata": {}, "source": [ - "In this log file, notice how the line we saw before is now missing; SCIP needs to find an initial solution using its own internal heuristics. The solution SCIP initially found has value `2.335200e+07`, which is significantly worse than the one MIPLearn constructed before. SCIP then proceeds to improve this solution by generating a number of cutting planes and repeatedly running primal heuristics. In the end, it is able to find the optimal solution, as expected, but it takes longer." + "In this log file, notice how the previous line about warm starts is missing. Since no warm starts were provided, SCIP had to find an initial solution using its own internal heuristics, which are not specifically tailored for this problem. The initial solution found by SCIP's heuristics has value `2.335200e+07`, which is significantly worse than the one constructed by MIPLearn. SCIP then proceeded to improve this solution, by generating cutting planes and repeatedly running additional primal heuristics. In the end, it was able to find the optimal solution, as expected, but it took longer.\n", + "\n", + "In summary, MIPLearn accelerated the solution process by constructing a high-quality initial solution. In the following tutorials, we will see other strategies that MIPLearn can use to accelerate MIP performance, besides warm starts." ] }, { "cell_type": "markdown", - "id": "36fb5f02", + "id": "ab9c1ff4", "metadata": {}, "source": [ "## Accessing the solution\n", @@ -678,7 +673,7 @@ { "cell_type": "code", "execution_count": 14, - "id": "f62f28b4", + "id": "79759e87", "metadata": {}, "outputs": [ { @@ -710,7 +705,7 @@ }, { "cell_type": "markdown", - "id": "d5722dcf", + "id": "b096dcf9", "metadata": {}, "source": [ "We can then solve this model as before, with `MIPLearn.solve!`:" @@ -719,7 +714,7 @@ { "cell_type": "code", "execution_count": 15, - "id": "e49f9e60", + "id": "1b668c12", "metadata": {}, "outputs": [ { diff --git a/0.2/jump-tutorials/getting-started/index.html b/0.2/jump-tutorials/getting-started/index.html index 8b44297..97e03ae 100644 --- a/0.2/jump-tutorials/getting-started/index.html +++ b/0.2/jump-tutorials/getting-started/index.html @@ -178,8 +178,8 @@
  • - - 1.2. Installing MIPLearn + + 1.2. Installation
  • @@ -479,15 +479,15 @@ div.rendered_html tbody tr:hover {

    Note

    -

    We use SCIP in this tutorial because it is a fast and widely available noncommercial MIP solver. All the steps shown here also work for Gurobi, CPLEX and XPRESS, although the performance impact might be different.

    +

    In this tutorial, we use SCIP because it is more widely available than commercial MIP solvers. However, all the steps below should work for Gurobi, CPLEX or XPRESS, as long as you have a license for these solvers. The performance impact of MIPLearn may also change for different solvers.

    Warning

    MIPLearn is still in early development stage. If run into any bugs or issues, please submit a bug report in our GitHub repository. Comments, suggestions and pull requests are also very welcome!

    • -
    -

    1.2. Installing MIPLearn

    +
    +

    1.2. Installation

    MIPLearn is available in two versions:

    • Python version, compatible with the Pyomo modeling language,

      • @@ -500,7 +500,7 @@ div.rendered_html tbody tr:hover { 
     using Pkg
-Pkg.develop(PackageSpec(path="/home/axavier/Packages/MIPLearn.jl/dev"))
+Pkg.add(PackageSpec(url="https://github.com/ANL-CEEESA/MIPLearn.jl.git"))
    @@ -509,7 +509,9 @@ div.rendered_html tbody tr:hover { 
    -Path `/home/axavier/Packages/MIPLearn.jl/dev` exists and looks like the correct package. Using existing path.
+    Updating git-repo `https://github.com/ANL-CEEESA/MIPLearn.jl.git`
+    Updating registry at `~/.julia/registries/General`
+    Updating git-repo `https://github.com/JuliaRegistries/General.git`
    Resolving package versions...
   No Changes to `~/Packages/MIPLearn/dev/docs/jump-tutorials/Project.toml`
   No Changes to `~/Packages/MIPLearn/dev/docs/jump-tutorials/Manifest.toml`
@@ -517,10 +519,10 @@ Path `/home/axavier/Packages/MIPLearn.jl/dev` exists and looks like the correct

    In addition to MIPLearn itself, we will also install a few other packages that are required for this tutorial:

      -

    • SCIP, a non-commercial mixed-integer programming solver

      • -

    • JuMP, an open-source modeling language for Julia

      • -

    • Distributions, a statistics package that we will use to generate random inputs

      • -

    • Glob, a package that retrieves all files in a directory matching a certain pattern

      • +

    • SCIP, one of the fastest non-commercial MIP solvers currently available

      • +

    • JuMP, an open source modeling language for Julia

      • +

    • Distributions.jl, a statistics package that we will use to generate random inputs

      • +

    • Glob.jl, a package that retrieves all files in a directory matching a certain pattern

    [2]:
@@ -534,7 +536,6 @@ Path `/home/axavier/Packages/MIPLearn.jl/dev` exists and looks like the correct
     PackageSpec(name="Distributions", version="0.25"),
     PackageSpec(name="Glob", version="1"),
 ])
-using Revise
    @@ -543,14 +544,9 @@ Path `/home/axavier/Packages/MIPLearn.jl/dev` exists and looks like the correct 
    -    Updating registry at `~/.julia/registries/General`
-    Updating git-repo `https://github.com/JuliaRegistries/General.git`
    Resolving package versions...
   No Changes to `~/Packages/MIPLearn/dev/docs/jump-tutorials/Project.toml`
   No Changes to `~/Packages/MIPLearn/dev/docs/jump-tutorials/Manifest.toml`
-Precompiling project...
-  ✓ MIPLearn
-1 dependency successfully precompiled in 10 seconds (96 already precompiled)
    @@ -561,9 +557,9 @@ Path `/home/axavier/Packages/MIPLearn.jl/dev` exists and looks like the correct

    1.3. Modeling a simple optimization problem

    To illustrate how can MIPLearn be used, we will model and solve a small optimization problem related to power systems optimization. The problem we discuss below is a simplification of the unit commitment problem, a practical optimization problem solved daily by electric grid operators around the world.

    -

    Suppose that you work at a utility company, and that it is your job to decide which electrical generators should be online at a certain hour of the day, and how much power should each generator produce. More specifically, assume that your company owns \(n\) generators, denoted by \(g_1, \ldots, g_n\). Each generator can either be online or offline. An online generator \(g_i\) can produce between \(p^\text{min}_i\) to \(p^\text{max}_i\) megawatts of power, and it costs your -company \(c^\text{fixed}_i + c^\text{var}_i y_i\), where \(y_i\) is the amount of power produced. An offline generator produces nothing, and costs nothing. You also know that the total amount of power to be produced needs to be exactly equal to the total demand \(d\) (in megawatts). To minimize the costs to your company, which generators should be online, and how much power should they produce?

    -

    This simple problem be modeled as a mixed-integer linear optimization problem as follows. For each generator \(g_i\), let \(x_i \in \{0,1\}\) be a decision variable indicating whether \(g_i\) is online, and let \(y_i \geq 0\) be a decision variable indicating how much power does \(g_i\) produce. The problem we need to solve is given by:

    +

    Suppose that you work at a utility company, and that it is your job to decide which electrical generators should be online at a certain hour of the day, as well as how much power should each generator produce. More specifically, assume that your company owns \(n\) generators, denoted by \(g_1, \ldots, g_n\). Each generator can either be online or offline. An online generator \(g_i\) can produce between \(p^\text{min}_i\) to \(p^\text{max}_i\) megawatts of power, and it costs +your company \(c^\text{fix}_i + c^\text{var}_i y_i\), where \(y_i\) is the amount of power produced. An offline generator produces nothing and costs nothing. You also know that the total amount of power to be produced needs to be exactly equal to the total demand \(d\) (in megawatts). To minimize the costs to your company, which generators should be online, and how much power should they produce?

    +

    This simple problem can be modeled as a mixed-integer linear optimization problem as follows. For each generator \(g_i\), let \(x_i \in \{0,1\}\) be a decision variable indicating whether \(g_i\) is online, and let \(y_i \geq 0\) be a decision variable indicating how much power does \(g_i\) produce. The problem is then given by:

    \[\begin{split}\begin{align} \text{minimize } \quad & \sum_{i=1}^n \left( c^\text{fix}_i x_i + c^\text{var}_i y_i \right) \\ @@ -575,9 +571,9 @@ company \(c^\text{fixed}_i + c^\text{ \end{align}\end{split}\]

    Note

    -

    We use a simplified version of the unit commitment problem in this tutorial just to make it easier to follow. MIPLearn can also handle realistic, large-scale versions of this problem. See the benchmark sections for more details.

    +

    We use a simplified version of the unit commitment problem in this tutorial just to make it easier to follow. MIPLearn can also handle realistic, large-scale versions of this problem. See benchmarks for more details.

    -

    Next, let us convert this abstract mathematical formulation into a concrete optimization model, using the Julia and the JuMP modeling language. We start by defining a data structure that holds all input data:

    +

    Next, let us convert this abstract mathematical formulation into a concrete optimization model, using Julia and JuMP. We start by defining a data structure that holds all the input data.

    [3]:
    @@ -593,7 +589,7 @@ company \(c^\text{fixed}_i + c^\text{
    -

    Next, we create a function that converts this data into a concrete JuMP model:

    +

    Next, we create a function that converts this data structure into a concrete JuMP model. For more details on the JuMP syntax, see the official JuMP documentation.

    [4]:
    @@ -630,7 +626,6 @@ company \(c^\text{fixed}_i + c^\text{ 
     using SCIP
-using Printf
 
 model = build_uc_model(
     UnitCommitmentData(
@@ -711,19 +706,18 @@ obj = 1320.0
    -

    Next, we will write these data structures to individual files. MIPLearn uses files during the training process because, for large-scale optimization problems, it is often impractical to hold the entire training data, as well as the concrete JuMP models, in memory. Files also make it much easier to solve multiple instances simultaneously, potentially even on multiple machines. We will cover parallel and distributed computing in a future tutorial.

    -

    The code below generates the files uc/train/000001.jld2, uc/train/000002.jld2, etc.

    +

    Next, we write these data structures to individual files. MIPLearn uses files during the training process because, for large-scale optimization problems, it is often impractical to hold the entire training data, as well as the concrete JuMP models, in memory. Files also make it much easier to solve multiple instances simultaneously, potentially even on multiple machines. We will cover parallel and distributed computing in a future tutorial.

    +

    The code below generates the files uc/train/000001.jld2, uc/train/000002.jld2, etc., which contain the input data in JLD2 format.

    [8]:
 
     using MIPLearn
-using Glob
-
 MIPLearn.save(data[1:90], "uc/train/")
 MIPLearn.save(data[91:100], "uc/test/")
 
+using Glob
 train_files = glob("uc/train/*.jld2")
 test_files = glob("uc/test/*.jld2");
    @@ -746,7 +740,7 @@ obj = 1320.0 
    -101.279699 seconds (93.52 M allocations: 3.599 GiB, 1.23% gc time, 0.52% compilation time)
+103.808547 seconds (93.52 M allocations: 3.604 GiB, 1.19% gc time, 0.52% compilation time)
    @@ -757,11 +751,11 @@ obj = 1320.0 WARNING: Dual bound 1.98665e+07 is larger than the objective of the primal solution 1.98665e+07. The solution might not be optimal.
    -

    The macro @time shows us how long did the code take to run. We can see that SCIP was able to solve all training instances in about 2 minutes. The solutions, and other useful training data, is stored by MIPLearn in .h5 files, stored side-by-side with the original .jld2 files.

    +

    The macro @time shows us how long did the code take to run. We can see that SCIP was able to solve all training instances in about 2 minutes. The solutions, and other useful training data, are stored by MIPLearn in .h5 files, stored side-by-side with the original .jld2 files.

    1.5. Solving new instances

    -

    Now that we have training data, we can fit the ML models using MIPLearn.fit!, then solve the test instances with MIPLearn.solve!, as shown below:

    +

    With training data in hand, we can now fit the ML models using MIPLearn.fit!, then solve the test instances with MIPLearn.solve!, as shown below:

    [10]:
    @@ -778,10 +772,10 @@ WARNING: Dual bound 1.98665e+07 is larger than the objective of the primal solut 
    -  5.693951 seconds (9.33 M allocations: 334.689 MiB, 1.62% gc time)
+  5.951264 seconds (9.33 M allocations: 334.657 MiB, 1.51% gc time)
    -

    The trained MIP solver was able to solve all test instances in about 5 seconds. To see that ML is being helpful here, let us repeat the code above, but remove the fit! line:

    +

    The trained MIP solver was able to solve all test instances in about 6 seconds. To see that ML is being helpful here, let us repeat the code above, but remove the fit! line:

    [11]:
    @@ -797,10 +791,10 @@ WARNING: Dual bound 1.98665e+07 is larger than the objective of the primal solut 
    -  9.829350 seconds (8.17 M allocations: 278.008 MiB, 0.47% gc time)
+ 10.390325 seconds (8.17 M allocations: 278.042 MiB, 0.89% gc time)
    -

    Without the help of the ML models, SCIP took around 10 seconds to solve the same test instances, or about twice as long.

    +

    Without the help of the ML models, SCIP took around 10 seconds to solve the same test instances.

    Note

    Note that is is not necessary to specify what ML models to use. MIPLearn, by default, will try a number of classical ML models and will choose the one that performs the best, based on k-fold cross validation. MIPLearn is also able to automatically collect features based on the MIP formulation of the problem and the solution to the LP relaxation, among other things, so it does not require handcrafted features. If you do want to customize the models and features, however, that is also possible, as @@ -809,7 +803,7 @@ we will see in a later tutorial.

    1.6. Understanding the acceleration

    -

    Let us know go a bit deeper and try to understand how exactly did MIPLearn accelerate SCIP’s performance. First, we are going to solve one of the training instances again, using the trained solver, but this time using the tee=true parameter, so that we can see SCIP’s log:

    +

    Let us go a bit deeper and try to understand how exactly did MIPLearn accelerate SCIP’s performance. First, we are going to solve one of the test instances again, using the trained solver, but this time using the tee=true parameter, so that we can see SCIP’s log:

    [12]:
    @@ -864,7 +858,7 @@ presolving (4 rounds: 4 fast, 3 medium, 3 exhaustive): presolved problem has 2000 variables (1000 bin, 0 int, 0 impl, 1000 cont) and 2001 constraints 2000 constraints of type <varbound> 1 constraints of type <linear> -Presolving Time: 0.10 +Presolving Time: 0.11 transformed 1/1 original solutions to the transformed problem space time | node | left |LP iter|LP it/n|mem/heur|mdpt |vars |cons |rows |cuts |sepa|confs|strbr| dualbound | primalbound | gap | compl. @@ -879,9 +873,9 @@ Gap : 0.01 %
    -

    The log above is quite complicated if you have never seen it before, but the important line in the one starting with feasible solution found [...] objective value 1.705169e+07. This line indicates that MIPLearn was able to construct a warm start with value 1.705169e+07. Using this warm start, SCIP then proceeded with the branch-and-cut process to either prove its optimality or find an even better solution. Very quickly, however, SCIP proved that the solution produced by MIPLearn was -indeed optimal and terminated. It was able to do this without generating a single cutting plane or running any other heuristics; it could tell the optimality by the root LP relaxation alone, which was very fast.

    -

    Let us now do the same thing again, but using the untrained solver this time:

    +

    The log above is quite complicated if you have never seen it before, but the important line is the one starting with feasible solution found [...] objective value 1.705169e+07. This line indicates that MIPLearn was able to construct a warm start with value 1.705169e+07. Using this warm start, SCIP then used the branch-and-cut method to either prove its optimality or to find an even better solution. Very quickly, however, SCIP proved that the solution produced by MIPLearn was indeed +optimal. It was able to do this without generating a single cutting plane or running any other heuristics; it could tell the optimality by the root LP relaxation alone, which was very fast.

    +

    Let us now repeat the process, but using the untrained solver this time:

    [13]:
    @@ -960,7 +954,7 @@ L 0.6s| 1 | 0 | 1707 | - | rens| 0 |2000 |2001 |2015 | 14 | 1 L 0.7s| 1 | 0 | 1707 | - | alns| 0 |2000 |2001 |2015 | 14 | 11 | 0 | 0 | 1.705038e+07 | 1.705178e+07 | 0.01%| unknown SCIP Status : solving was interrupted [gap limit reached] -Solving Time (sec) : 0.67 +Solving Time (sec) : 0.68 Solving Nodes : 1 Primal Bound : +1.70517823853380e+07 (13 solutions) Dual Bound : +1.70503798271962e+07 @@ -968,7 +962,9 @@ Gap : 0.01 %
    -

    In this log file, notice how the line we saw before is now missing; SCIP needs to find an initial solution using its own internal heuristics. The solution SCIP initially found has value 2.335200e+07, which is significantly worse than the one MIPLearn constructed before. SCIP then proceeds to improve this solution by generating a number of cutting planes and repeatedly running primal heuristics. In the end, it is able to find the optimal solution, as expected, but it takes longer.

    +

    In this log file, notice how the previous line about warm starts is missing. Since no warm starts were provided, SCIP had to find an initial solution using its own internal heuristics, which are not specifically tailored for this problem. The initial solution found by SCIP’s heuristics has value 2.335200e+07, which is significantly worse than the one constructed by MIPLearn. SCIP then proceeded to improve this solution, by generating cutting planes and repeatedly running additional primal +heuristics. In the end, it was able to find the optimal solution, as expected, but it took longer.

    +

    In summary, MIPLearn accelerated the solution process by constructing a high-quality initial solution. In the following tutorials, we will see other strategies that MIPLearn can use to accelerate MIP performance, besides warm starts.

    1.7. Accessing the solution

    diff --git a/0.2/objects.inv b/0.2/objects.inv index b5ad601..d2d30aa 100644 Binary files a/0.2/objects.inv and b/0.2/objects.inv differ diff --git a/0.2/searchindex.js b/0.2/searchindex.js index 9c9a485..2e596ce 100644 --- a/0.2/searchindex.js +++ b/0.2/searchindex.js @@ -1 +1 @@ -Search.setIndex({docnames:["benchmarks/facility","benchmarks/knapsack","benchmarks/preliminaries","benchmarks/stab","benchmarks/tsp","benchmarks/uc","index","internals/abstract-component","internals/data-collection","internals/dynamic-lazy","internals/primal","internals/solver-interfaces","internals/static-lazy","jump-tutorials/customizing-ml","jump-tutorials/getting-started","jump-tutorials/lazy-constraints","jump-tutorials/user-cuts"],envversion:{"sphinx.domains.c":2,"sphinx.domains.changeset":1,"sphinx.domains.citation":1,"sphinx.domains.cpp":3,"sphinx.domains.index":1,"sphinx.domains.javascript":2,"sphinx.domains.math":2,"sphinx.domains.python":2,"sphinx.domains.rst":2,"sphinx.domains.std":2,nbsphinx:3,sphinx:56},filenames:["benchmarks/facility.ipynb","benchmarks/knapsack.ipynb","benchmarks/preliminaries.ipynb","benchmarks/stab.ipynb","benchmarks/tsp.ipynb","benchmarks/uc.ipynb","index.md","internals/abstract-component.ipynb","internals/data-collection.ipynb","internals/dynamic-lazy.ipynb","internals/primal.ipynb","internals/solver-interfaces.ipynb","internals/static-lazy.ipynb","jump-tutorials/customizing-ml.ipynb","jump-tutorials/getting-started.ipynb","jump-tutorials/lazy-constraints.ipynb","jump-tutorials/user-cuts.ipynb"],objects:{},objnames:{},objtypes:{},terms:{"000":14,"000000e":14,"000001":14,"000002":14,"008":14,"06ch11357":6,"0976":6,"100":[3,14],"1000":[1,4,14],"101":14,"1103":14,"1138":14,"1150":14,"1201":14,"1204":14,"1207":14,"1209":14,"1210":14,"1211":14,"1212":14,"1214":14,"1216":14,"1220":14,"1223":14,"1229":14,"125":14,"1287":6,"1320":14,"1403":14,"150":3,"155":1,"1707":14,"1722":14,"189":1,"1994":1,"200":3,"2000":14,"2001":14,"2002":14,"2003":14,"2004":[1,14],"2005":14,"2006":14,"2007":14,"2009":14,"201":3,"2011":14,"2014":14,"2015":14,"2020":6,"2021":6,"203":14,"20m":14,"212":1,"22m":14,"230":14,"23m":14,"24m":14,"250":1,"251":1,"256":2,"25m":14,"26m":14,"278":14,"279":14,"279699":14,"2933":2,"3000":14,"334":14,"335200e":14,"338047247943162":14,"350":4,"351":4,"365":14,"4287567":6,"500":[1,3,4,14],"5281":6,"599":14,"600":14,"6230":2,"646":14,"689":14,"693951":14,"700":14,"70503465600130e":14,"70503465600131e":14,"705035e":14,"705036e":14,"70503798271962e":14,"705037e":14,"705038e":14,"7051217395548128e7":14,"70516871251443e":14,"705169e":14,"70517823853380e":14,"705178e":14,"705332e":14,"705687e":14,"706228e":14,"706492e":14,"711399e":14,"767":14,"7aa79aaa":14,"829350":14,"839873e":14,"861":14,"862":14,"8950k":14,"98665e":14,"abstract":14,"case":14,"class":[1,3,4],"default":[1,2,4,14],"erd\u0151":3,"final":14,"fr\u00e9vill":1,"function":14,"g\u00e9rard":1,"import":14,"int":14,"long":[1,14],"new":3,"r\u00e9nyi":3,"return":[4,14],"true":[1,3,4,6,14],"try":14,"var":14,"while":3,AND:6,ARE:6,BUT:6,FOR:6,For:[2,4,14],LTS:2,NOT:6,SUCH:6,THE:6,The:[1,2,3,4,6,14],USE:6,Use:14,Using:14,abl:[6,14],abort:14,about:14,abov:[1,2,6,14],ac02:6,acceler:6,achiev:14,across:1,actual:2,add:14,added:14,addit:14,adjac:3,advanc:6,advantag:6,advis:6,affexpr:14,after:14,again:14,aggreg:14,ahm:6,align:[1,14],alinson:6,all:[1,2,4,6,14],alloc:14,aln:14,alon:14,alpha:1,alpha_i:1,alreadi:14,also:[1,2,4,6,14],although:[1,14],among:14,amount:14,ani:[6,14],anl:6,appli:1,argonn:6,argument:1,aris:6,arnaud:1,around:14,art:[2,6],ask:4,assum:[6,14],attach:14,automat:[6,14],avail:[1,14],averag:[1,2],axavi:[6,14],b_i:1,base:[6,14],becaus:14,befor:[2,14],begin:[1,14],being:14,below:[6,14],benchmark:14,benefit:2,best:14,better:14,between:[4,14],bin:14,binari:6,bit:14,both:14,bound:14,branch:14,bug:14,build_uc_model:14,busi:6,cachingoptim:14,calcul:1,call:1,can:[1,3,4,6,14],candid:14,capac:1,caus:6,cbc:14,ceeesa:6,certain:[6,14],cfix:14,challeng:14,chang:14,chg:14,choos:14,cite:6,citi:4,classic:14,cliqu:14,clq:14,code:14,coeff:14,coeffici:[1,14],collect:14,com:[6,14],combin:[1,6],come:2,command:14,comment:14,commerci:14,commit:[6,14],compani:14,compar:2,compat:14,compil:14,compl:14,complet:[1,3,4],completesol:14,complex:14,complic:14,compon:14,comput:[2,6,14],con:14,concret:14,condit:[6,14],conf:14,consequenti:6,consol:14,conss:14,constant:1,constraint:[1,6,14],construct:14,constructor:3,consum:1,cont:14,contain:14,contract:6,contributor:6,conveni:14,convent:[2,6],convert:14,copyright:6,core:2,correct:14,correl:1,cost:[1,14],could:14,cover:14,cplex:[6,14],creat:[4,14],cross:14,custom:14,cut:14,cvar:14,dai:14,daili:14,damag:6,data:6,ddr4:2,decid:14,decis:14,deeper:14,defin:14,del:14,delet:14,demand:14,demonstr:14,denot:14,depart:6,depend:14,deriv:[1,6],detail:[2,14],dev:14,develop:[6,14],did:14,differ:[4,14],digit:14,direct:6,director:6,directori:14,disabl:[1,4],disclaim:6,discret:[1,6],discuss:14,distanc:4,distinct:2,distribut:[1,3,4,6,14],doc:14,document:6,doe:14,doi:6,download:14,dual:14,dualbound:14,dure:[3,14],each:[1,2,3,4,14],earli:14,easier:[2,14],effici:1,either:14,electr:14,end:[1,14],endors:6,energi:6,enhanc:[2,6],ensur:14,entir:[2,14],eq_demand:14,eq_max_pow:14,eq_min_pow:14,equal:14,equalto:14,etc:14,european:1,evalu:[2,14],even:[6,14],event:6,exact:2,exactli:[1,4,14],exampl:14,exemplari:6,exhaust:14,exist:14,expect:[2,14],experi:2,express:6,extens:6,fals:[1,3,4],famili:6,fast:14,faster:14,feasibl:[6,14],featur:14,feng:6,few:14,field:6,file:14,find:[1,3,6,14],first:[2,4,6,14],fit:[6,14],fix:[1,3,4,14],fix_citi:4,fix_graph:3,fix_w:1,float64:14,fold:14,folder:14,follow:[6,14],foral:1,form:6,formul:14,found:14,fqiu:6,frac:1,fraction:14,framework:[6,14],frequent:14,frevil:1,from:[1,2,3,4,6,14],full:6,fund:6,futur:14,g_1:14,g_i:14,g_n:14,gamma:[1,4],gamma_:[1,4],gap:14,gener:[2,6],geq:14,get:6,gib:14,git:14,github:[6,14],given:[1,3,4,14],glob:14,going:14,gold:2,good:6,gov:6,gradual:2,grant:6,graph:3,greaterthan:14,grid:[6,14],gurobi:[2,6,14],hamiltonian:4,handcraft:14,handl:14,happen:6,harder:2,has:14,have:14,help:14,here:[2,14],heur:14,heurist:[2,14],high:[1,3,4,6],histor:14,hold:14,holder:6,hole:14,home:14,hour:14,how:[2,14],howev:[6,14],http:[6,14],ident:1,identifi:6,ijoc:6,illustr:[2,14],impact:14,impl:14,implement:6,impli:[1,6],implic:14,impract:14,improv:14,incident:6,includ:6,incompat:14,inde:14,independ:[1,3,4],indic:14,indirect:6,individu:14,inf:14,infeas:14,inform:6,initi:[4,14],input:14,instanc:[2,4,6],instead:1,instruct:14,integ:[1,4,6,14],integr:14,intel:2,interest:2,intern:[2,14],interrupt:[6,14],intshift:14,issu:14,item:1,iter:14,its:[6,14],itself:14,jld2:14,job:14,journal:[1,6],julia:14,juliaregistri:14,jump:14,just:14,karp:[3,4],keep:14,kept:[1,4],kindli:6,knapsack:6,know:14,kwdef:14,laboratori:6,languag:14,larg:[6,14],larger:14,later:[2,14],launch:14,ldot:[1,4,14],ldrd:6,learn:[2,6,14],learningsolv:[2,14],left:14,length:14,leq:[1,14],lessthan:14,let:14,liabil:6,liabl:6,like:14,limit:[2,6,14],line:14,linear:[6,14],linearli:1,linux:2,list:[4,6,14],llc:6,load:14,loc:[1,3,4],lock:14,log:14,longer:14,look:14,loss:6,low:[1,3,4],machin:[6,14],macro:14,made:14,mai:[1,6,14],mailto:6,main:[6,14],make:[1,2,14],manifest:14,match:14,materi:6,math:3,mathbb:[3,4],mathemat:[1,14],mathoptinterfac:14,max:14,maxim:[1,3],maximum:6,maxweightstablesetgener:3,mdpt:14,measur:2,medium:14,megawatt:14,mem:14,memori:14,merchant:6,met:6,method:[6,14],mhz:2,mib:14,might:14,min:14,minim:14,minut:14,mip:[2,6,14],miplearn:2,miplib:2,miss:14,mix:[6,14],mode:[2,14],model:6,modif:6,more:[1,2,14],much:14,multidimension:6,multiknapsackgener:1,multipl:14,multipli:1,must:6,name:[6,14],nation:6,nearest:[1,4],necessari:[2,14],need:14,neglig:6,neither:6,never:14,newer:14,newli:2,next:14,no_optim:14,node:14,non:14,noncommerci:14,nor:6,note:14,noth:14,notic:[6,14],now:14,number:[1,14],obj:14,object:14,objective_valu:14,observ:6,obtain:14,oe0000875:6,offic:6,offici:14,offlin:14,often:14,onc:4,one:[3,4,14],ones:14,onli:[6,14],onlin:14,open:14,oper:[1,14],optim:[2,6],optimizer_with_attribut:14,origin:14,other:[4,6,14],otherwis:6,our:14,out:6,overview:1,own:14,p_j:1,packag:[6,14],packagespec:14,page:2,pair:4,parallel:14,paramet:[2,3,14],particular:[6,14],path:[4,14],pattern:[6,14],perfom:2,perform:[2,6,14],permiss:6,permit:6,perturb:1,pkg:14,plane:14,plateau:1,pleas:14,pmax:14,pmin:14,point:14,possibl:[6,14],potenti:14,power:[6,14],practic:14,precis:1,precompil:14,predict:14,preliminari:6,preprocess:1,present:[2,14],presolv:14,previous:6,price:[1,14],primal:14,primalbound:14,printf:14,println:14,prior:6,probabl:[1,3,4,14],probe:14,problem:[2,6],proce:14,procedur:1,proceed:14,process:14,processor:2,procur:6,produc:14,product:[6,14],profit:[1,6],program:[6,14],project:14,promot:6,propos:2,prove:[6,14],provid:[1,3,4,6,14],pull:14,pure:6,purpos:6,pyomo:14,python:14,qiu:6,quad:14,qualiti:[2,6],quickli:14,quit:14,ram:2,rand:14,randint:[1,3,4],random:14,random_uc_data:14,ratio:1,reach:14,read:14,real:14,realist:14,recal:3,recommend:14,redistribut:6,redund:6,refer:[1,2],regist:14,registri:14,regular:14,relat:14,relax:14,releas:14,remain:[3,14],remov:14,ren:14,repeat:14,repeatedli:14,repo:14,report:14,repositori:14,reproduc:6,request:[6,14],requir:14,research:[1,6],reserv:6,resolv:14,resourc:1,respect:14,restrict:2,retain:6,retriev:14,rev:14,revis:14,right:[6,14],root:14,roughli:1,round:[1,4,14],rout:4,row:14,run:[2,14],salesman:6,same:[1,2,3,4,14],sampl:[1,3,4,14],save:14,saw:14,scale:[1,3,4,6,14],scienc:6,scip:14,scipopt:14,sec:14,second:14,section:14,see:[2,14],seed:14,seen:14,sens:[2,14],sepa:14,server:2,servic:6,set:[1,2,4,6,14],set_optim:14,set_sil:14,shabbir:6,shall:6,shift:14,shortest:4,should:[2,14],show:14,shown:14,side:14,significantli:14,sim:[1,3,4],similar:[2,14],simpl:3,simplic:14,simplif:14,simplifi:14,simultan:[2,14],singl:14,situat:14,slower:14,small:[2,14],softwar:6,solut:[2,6],solv:[2,6],solver:[2,6,14],solver_baselin:14,solver_ml:14,some:14,sourc:14,space:14,special:6,specif:[1,6,14],specifi:[2,3,14],speed:2,spend:14,sqrt:4,squar:4,stabl:6,stage:14,start:[4,6],state:[2,6,14],statist:14,statu:14,step:14,still:[1,4,14],storag:14,store:14,strbr:14,strict:6,stronger:2,struct:14,structur:14,studi:2,subject:[1,14],submit:14,subset:[1,3],subseteq:3,substitut:6,success:14,successfulli:14,suggest:14,sum:[3,14],sum_:[1,14],support:6,suppos:14,symmetri:14,system:[6,14],take:[2,6,14],techniqu:[2,6],tee:14,tell:14,termin:14,test:[1,2,3,4,14],test_data:14,test_fil:14,text:[1,14],than:[1,14],thei:14,them:[4,14],theori:6,therefor:[2,4],theses:14,thi:[1,2,3,4,6,14],thing:14,thread:2,three:[2,14],tight:1,tighten:14,time:[2,14],todo:[0,5,7,8,9,10,11,12,13,15,16],togeth:14,toml:14,took:14,tort:6,total:[2,14],train:[1,2,3,4],train_data:14,train_fil:14,transform:14,travel:6,travelingsalesmangener:4,tsplib:2,tutori:14,twice:14,two:[3,14],type:[1,14],typic:[2,6],u_j:1,ubuntu:2,uchicago:6,under:6,undirect:3,uniform:[1,3,4,14],unit:[6,14],unitcommitmentdata:14,unknown:14,unlik:6,untrain:14,updat:14,upfront:14,upgd:14,upon:6,url:14,use:[2,6,14],used:[1,2,3,4,6,14],useful:14,useless:14,user:[1,3],uses:[6,14],using:[1,2,6,14],usual:14,util:14,valid:14,valu:[4,6,14],varbound:14,variabl:[1,6,14],variableref:14,vbound:14,vector:14,veri:[2,6,14],version:14,vertex:3,vertic:3,violat:14,visit:4,w_jitter:1,w_v:3,wai:[3,6],want:14,warm:14,warn:14,warranti:6,weight:[1,6],welcom:14,well:14,were:[2,6,14],what:[2,14],when:[1,2,3,14],where:[1,3,4,14],whether:[6,14],which:[2,6,14],wide:14,without:[1,6,14],work:[6,14],world:14,wors:14,would:2,write:14,written:6,x_1:4,x_i:[4,14],x_j:[1,4],x_n:4,xavier:6,xeon:2,xpress:[6,14],y_1:4,y_i:[4,14],y_j:4,y_n:4,you:[6,14],your:[6,14],zenodo:6,zeroon:14},titles:["Facility Location","3. Multidimensional Knapsack","1. Preliminaries","2. Maximum Weight Stable Set","4. Traveling Salesman","Unit Commitment","MIPLearn","Abstract component","Training data collection","Dynamic lazy constraints & user cuts","Primal solutions","Solver interfaces","Static lazy constraints","Customizing the ML models","1. Getting started with MIPLearn","Modeling lazy constraints","Modeling user cuts"],titleterms:{"abstract":7,"new":14,"static":12,acceler:14,access:14,acknowledg:6,author:6,baselin:2,benchmark:[2,6],challeng:[1,2,3,4],code:6,collect:8,commit:5,compon:7,constraint:[9,12,15],content:6,custom:13,cut:[9,16],data:[8,14],definit:[1,3,4],dynam:9,facil:0,gener:[1,3,4,14],get:14,instal:14,instanc:[1,3,14],interfac:11,introduct:14,julia:6,knapsack:1,lazi:[9,12,15],licens:6,locat:0,maximum:3,miplearn:[6,14],model:[13,14,15,16],multidimension:1,optim:14,preliminari:2,primal:10,problem:[1,3,4,14],random:[1,3,4],refer:6,result:2,salesman:4,set:3,simpl:14,solut:[10,14],solv:14,solver:11,sourc:6,stabl:3,start:14,tabl:6,train:[8,14],travel:4,tutori:6,understand:14,unit:5,user:[9,16],weight:3}}) \ No newline at end of file +Search.setIndex({docnames:["benchmarks/facility","benchmarks/knapsack","benchmarks/preliminaries","benchmarks/stab","benchmarks/tsp","benchmarks/uc","index","internals/abstract-component","internals/data-collection","internals/dynamic-lazy","internals/primal","internals/solver-interfaces","internals/static-lazy","jump-tutorials/customizing-ml","jump-tutorials/getting-started","jump-tutorials/lazy-constraints","jump-tutorials/user-cuts"],envversion:{"sphinx.domains.c":2,"sphinx.domains.changeset":1,"sphinx.domains.citation":1,"sphinx.domains.cpp":3,"sphinx.domains.index":1,"sphinx.domains.javascript":2,"sphinx.domains.math":2,"sphinx.domains.python":2,"sphinx.domains.rst":2,"sphinx.domains.std":2,nbsphinx:3,sphinx:56},filenames:["benchmarks/facility.ipynb","benchmarks/knapsack.ipynb","benchmarks/preliminaries.ipynb","benchmarks/stab.ipynb","benchmarks/tsp.ipynb","benchmarks/uc.ipynb","index.md","internals/abstract-component.ipynb","internals/data-collection.ipynb","internals/dynamic-lazy.ipynb","internals/primal.ipynb","internals/solver-interfaces.ipynb","internals/static-lazy.ipynb","jump-tutorials/customizing-ml.ipynb","jump-tutorials/getting-started.ipynb","jump-tutorials/lazy-constraints.ipynb","jump-tutorials/user-cuts.ipynb"],objects:{},objnames:{},objtypes:{},terms:{"000":14,"000000e":14,"000001":14,"000002":14,"042":14,"06ch11357":6,"0976":6,"100":[3,14],"1000":[1,4,14],"103":14,"1103":14,"1138":14,"1150":14,"1201":14,"1204":14,"1207":14,"1209":14,"1210":14,"1211":14,"1212":14,"1214":14,"1216":14,"1220":14,"1223":14,"1229":14,"125":14,"1287":6,"1320":14,"1403":14,"150":3,"155":1,"1707":14,"1722":14,"189":1,"1994":1,"200":3,"2000":14,"2001":14,"2002":14,"2003":14,"2004":[1,14],"2005":14,"2006":14,"2007":14,"2009":14,"201":3,"2011":14,"2014":14,"2015":14,"2020":6,"2021":6,"203":14,"20m":14,"212":1,"22m":14,"230":14,"23m":14,"24m":14,"250":1,"251":1,"256":2,"25m":14,"26m":14,"278":14,"279":14,"2933":2,"3000":14,"334":14,"335200e":14,"338047247943162":14,"350":4,"351":4,"365":14,"390325":14,"4287567":6,"500":[1,3,4,14],"5281":6,"600":14,"604":14,"6230":2,"646":14,"657":14,"700":14,"70503465600130e":14,"70503465600131e":14,"705035e":14,"705036e":14,"70503798271962e":14,"705037e":14,"705038e":14,"7051217395548128e7":14,"70516871251443e":14,"705169e":14,"70517823853380e":14,"705178e":14,"705332e":14,"705687e":14,"706228e":14,"706492e":14,"711399e":14,"767":14,"7aa79aaa":14,"808547":14,"839873e":14,"861":14,"862":14,"8950k":14,"951264":14,"98665e":14,"abstract":14,"case":14,"class":[1,3,4],"default":[1,2,4,14],"erd\u0151":3,"final":14,"fr\u00e9vill":1,"function":14,"g\u00e9rard":1,"import":14,"int":14,"long":[1,14],"new":3,"r\u00e9nyi":3,"return":[4,14],"true":[1,3,4,6,14],"try":14,"var":14,"while":3,AND:6,ARE:6,BUT:6,FOR:6,For:[2,4,14],LTS:2,NOT:6,SUCH:6,THE:6,The:[1,2,3,4,6,14],USE:6,Use:14,Using:14,With:14,abl:[6,14],abort:14,about:14,abov:[1,2,6,14],ac02:6,acceler:6,achiev:14,across:1,actual:2,add:14,added:14,addit:14,adjac:3,advanc:6,advantag:6,advis:6,affexpr:14,after:14,again:14,aggreg:14,ahm:6,align:[1,14],alinson:6,all:[1,2,4,6,14],alloc:14,aln:14,alon:14,alpha:1,alpha_i:1,alreadi:14,also:[1,2,4,6,14],although:[1,14],among:14,amount:14,ani:[6,14],anl:[6,14],appli:1,argonn:6,argument:1,aris:6,arnaud:1,around:14,art:[2,6],ask:4,assum:[6,14],attach:14,automat:[6,14],avail:[1,14],averag:[1,2],axavi:6,b_i:1,base:[6,14],becaus:14,befor:[2,14],begin:[1,14],being:14,below:[6,14],benchmark:14,benefit:2,besid:14,best:14,better:14,between:[4,14],bin:14,binari:6,bit:14,both:14,bound:14,branch:14,bug:14,build_uc_model:14,busi:6,cachingoptim:14,calcul:1,call:1,can:[1,3,4,6,14],candid:14,capac:1,caus:6,cbc:14,ceeesa:[6,14],certain:[6,14],cfix:14,challeng:14,chang:14,chg:14,choos:14,cite:6,citi:4,classic:14,cliqu:14,clq:14,code:14,coeff:14,coeffici:[1,14],collect:14,com:[6,14],combin:[1,6],come:2,command:14,comment:14,commerci:14,commit:[6,14],compani:14,compar:2,compat:14,compil:14,compl:14,complet:[1,3,4],completesol:14,complex:14,complic:14,compon:14,comput:[2,6,14],con:14,concret:14,condit:[6,14],conf:14,consequenti:6,consol:14,conss:14,constant:1,constraint:[1,6,14],construct:14,constructor:3,consum:1,cont:14,contain:14,contract:6,contributor:6,conveni:14,convent:[2,6],convert:14,copyright:6,core:2,correl:1,cost:[1,14],could:14,cover:14,cplex:[6,14],creat:[4,14],cross:14,current:14,custom:14,cut:14,cvar:14,dai:14,daili:14,damag:6,data:6,ddr4:2,decid:14,decis:14,deeper:14,defin:14,del:14,delet:14,demand:14,demonstr:14,denot:14,depart:6,deriv:[1,6],detail:[2,14],dev:14,develop:[6,14],did:14,differ:[4,14],digit:14,direct:6,director:6,directori:14,disabl:[1,4],disclaim:6,discret:[1,6],discuss:14,distanc:4,distinct:2,distribut:[1,3,4,6,14],doc:14,document:[6,14],doe:14,doi:6,download:14,dual:14,dualbound:14,dure:[3,14],each:[1,2,3,4,14],earli:14,easier:[2,14],effici:1,either:14,electr:14,end:[1,14],endors:6,energi:6,enhanc:[2,6],ensur:14,entir:[2,14],eq_demand:14,eq_max_pow:14,eq_min_pow:14,equal:14,equalto:14,etc:14,european:1,evalu:[2,14],even:[6,14],event:6,exact:2,exactli:[1,4,14],exampl:14,exemplari:6,exhaust:14,expect:[2,14],experi:2,express:6,extens:6,fals:[1,3,4],famili:6,fast:14,faster:14,fastest:14,feasibl:[6,14],featur:14,feng:6,few:14,field:6,file:14,find:[1,3,6,14],first:[2,4,6,14],fit:[6,14],fix:[1,3,4,14],fix_citi:4,fix_graph:3,fix_w:1,float64:14,fold:14,folder:14,follow:[6,14],foral:1,form:6,format:14,formul:14,found:14,fqiu:6,frac:1,fraction:14,framework:[6,14],frequent:14,frevil:1,from:[1,2,3,4,6,14],full:6,fund:6,futur:14,g_1:14,g_i:14,g_n:14,gamma:[1,4],gamma_:[1,4],gap:14,gener:[2,6],geq:14,get:6,gib:14,git:14,github:[6,14],given:[1,3,4,14],glob:14,going:14,gold:2,good:6,gov:6,gradual:2,grant:6,graph:3,greaterthan:14,grid:[6,14],gurobi:[2,6,14],had:14,hamiltonian:4,hand:14,handcraft:14,handl:14,happen:6,harder:2,has:14,have:14,help:14,here:[2,14],heur:14,heurist:[2,14],high:[1,3,4,6,14],histor:14,hold:14,holder:6,hole:14,hour:14,how:[2,14],howev:[6,14],http:[6,14],ident:1,identifi:6,ijoc:6,illustr:[2,14],impact:14,impl:14,implement:6,impli:[1,6],implic:14,impract:14,improv:14,incident:6,includ:6,incompat:14,inde:14,independ:[1,3,4],indic:14,indirect:6,individu:14,inf:14,infeas:14,inform:6,initi:[4,14],input:14,instanc:[2,4,6],instead:1,instruct:14,integ:[1,4,6,14],integr:14,intel:2,interest:2,intern:[2,14],interrupt:[6,14],intshift:14,issu:14,item:1,iter:14,its:[6,14],itself:14,jld2:14,job:14,journal:[1,6],julia:14,juliaregistri:14,jump:14,just:14,karp:[3,4],keep:14,kept:[1,4],kindli:6,knapsack:6,know:14,kwdef:14,laboratori:6,languag:14,larg:[6,14],larger:14,later:[2,14],launch:14,ldot:[1,4,14],ldrd:6,learn:[2,6,14],learningsolv:[2,14],left:14,length:14,leq:[1,14],lessthan:14,let:14,liabil:6,liabl:6,licens:14,limit:[2,6,14],line:14,linear:[6,14],linearli:1,linux:2,list:[4,6,14],llc:6,load:14,loc:[1,3,4],lock:14,log:14,longer:14,loss:6,low:[1,3,4],machin:[6,14],macro:14,made:14,mai:[1,6,14],mailto:6,main:[6,14],make:[1,2,14],manifest:14,match:14,materi:6,math:3,mathbb:[3,4],mathemat:[1,14],mathoptinterfac:14,max:14,maxim:[1,3],maximum:6,maxweightstablesetgener:3,mdpt:14,measur:2,medium:14,megawatt:14,mem:14,memori:14,merchant:6,met:6,method:[6,14],mhz:2,mib:14,might:14,min:14,minim:14,minut:14,mip:[2,6,14],miplearn:2,miplib:2,miss:14,mix:[6,14],mode:[2,14],model:6,modif:6,more:[1,2,14],much:14,multidimension:6,multiknapsackgener:1,multipl:14,multipli:1,must:6,name:[6,14],nation:6,nearest:[1,4],necessari:[2,14],need:14,neglig:6,neither:6,never:14,newer:14,newli:2,next:14,no_optim:14,node:14,non:14,nor:6,note:14,noth:14,notic:[6,14],now:14,number:[1,14],obj:14,object:14,objective_valu:14,observ:6,obtain:14,oe0000875:6,offic:6,offici:14,offlin:14,often:14,onc:4,one:[3,4,14],ones:14,onli:[6,14],onlin:14,open:14,oper:[1,14],optim:[2,6],optimizer_with_attribut:14,origin:14,other:[4,6,14],otherwis:6,our:14,out:6,overview:1,own:14,p_j:1,packag:[6,14],packagespec:14,page:2,pair:4,parallel:14,paramet:[2,3,14],particular:[6,14],path:4,pattern:[6,14],perfom:2,perform:[2,6,14],permiss:6,permit:6,perturb:1,pkg:14,plane:14,plateau:1,pleas:14,pmax:14,pmin:14,point:14,possibl:[6,14],potenti:14,power:[6,14],practic:14,precis:1,predict:14,preliminari:6,preprocess:1,present:[2,14],presolv:14,previou:14,previous:6,price:[1,14],primal:14,primalbound:14,println:14,prior:6,probabl:[1,3,4,14],probe:14,problem:[2,6],procedur:1,proceed:14,process:14,processor:2,procur:6,produc:14,product:[6,14],profit:[1,6],program:[6,14],project:14,promot:6,propos:2,prove:[6,14],provid:[1,3,4,6,14],pull:14,pure:6,purpos:6,pyomo:14,python:14,qiu:6,quad:14,qualiti:[2,6,14],quickli:14,quit:14,ram:2,rand:14,randint:[1,3,4],random:14,random_uc_data:14,ratio:1,reach:14,read:14,real:14,realist:14,recal:3,recommend:14,redistribut:6,redund:6,refer:[1,2],regist:14,registri:14,regular:14,relat:14,relax:14,releas:14,remain:[3,14],remov:14,ren:14,repeat:14,repeatedli:14,repo:14,report:14,repositori:14,reproduc:6,request:[6,14],requir:14,research:[1,6],reserv:6,resolv:14,resourc:1,respect:14,restrict:2,retain:6,retriev:14,rev:14,right:[6,14],root:14,roughli:1,round:[1,4,14],rout:4,row:14,run:[2,14],salesman:6,same:[1,2,3,4,14],sampl:[1,3,4,14],save:14,scale:[1,3,4,6,14],scienc:6,scip:14,scipopt:14,sec:14,second:14,section:14,see:[2,14],seed:14,seen:14,sens:[2,14],sepa:14,server:2,servic:6,set:[1,2,4,6,14],set_optim:14,set_sil:14,shabbir:6,shall:6,shift:14,shortest:4,should:[2,14],show:14,shown:14,side:14,significantli:14,sim:[1,3,4],similar:[2,14],simpl:3,simplic:14,simplif:14,simplifi:14,simultan:[2,14],sinc:14,singl:14,situat:14,slower:14,small:[2,14],softwar:6,solut:[2,6],solv:[2,6],solver:[2,6,14],solver_baselin:14,solver_ml:14,some:14,sourc:14,space:14,special:6,specif:[1,6,14],specifi:[2,3,14],speed:2,spend:14,sqrt:4,squar:4,stabl:6,stage:14,start:[4,6],state:[2,6,14],statist:14,statu:14,step:14,still:[1,4,14],storag:14,store:14,strategi:14,strbr:14,strict:6,stronger:2,struct:14,structur:14,studi:2,subject:[1,14],submit:14,subset:[1,3],subseteq:3,substitut:6,success:14,suggest:14,sum:[3,14],sum_:[1,14],summari:14,support:6,suppos:14,symmetri:14,syntax:14,system:[6,14],tailor:14,take:[2,6,14],techniqu:[2,6],tee:14,tell:14,test:[1,2,3,4,14],test_data:14,test_fil:14,text:[1,14],than:[1,14],thei:14,them:[4,14],theori:6,therefor:[2,4],theses:14,thi:[1,2,3,4,6,14],thing:14,thread:2,three:[2,14],tight:1,tighten:14,time:[2,14],todo:[0,5,7,8,9,10,11,12,13,15,16],togeth:14,toml:14,took:14,tort:6,total:[2,14],train:[1,2,3,4],train_data:14,train_fil:14,transform:14,travel:6,travelingsalesmangener:4,tsplib:2,tutori:14,two:[3,14],type:[1,14],typic:[2,6],u_j:1,ubuntu:2,uchicago:6,under:6,undirect:3,uniform:[1,3,4,14],unit:[6,14],unitcommitmentdata:14,unknown:14,unlik:6,untrain:14,updat:14,upfront:14,upgd:14,upon:6,url:14,use:[2,6,14],used:[1,2,3,4,6,14],useful:14,useless:14,user:[1,3],uses:[6,14],using:[1,2,6,14],usual:14,util:14,valid:14,valu:[4,6,14],varbound:14,variabl:[1,6,14],variableref:14,vbound:14,vector:14,veri:[2,6,14],version:14,vertex:3,vertic:3,violat:14,visit:4,w_jitter:1,w_v:3,wai:[3,6],want:14,warm:14,warn:14,warranti:6,weight:[1,6],welcom:14,well:14,were:[2,6,14],what:[2,14],when:[1,2,3,14],where:[1,3,4,14],whether:[6,14],which:[2,6,14],wide:14,without:[1,6,14],work:[6,14],world:14,wors:14,would:2,write:14,written:6,x_1:4,x_i:[4,14],x_j:[1,4],x_n:4,xavier:6,xeon:2,xpress:[6,14],y_1:4,y_i:[4,14],y_j:4,y_n:4,you:[6,14],your:[6,14],zenodo:6,zeroon:14},titles:["Facility Location","3. Multidimensional Knapsack","1. Preliminaries","2. Maximum Weight Stable Set","4. Traveling Salesman","Unit Commitment","MIPLearn","Abstract component","Training data collection","Dynamic lazy constraints & user cuts","Primal solutions","Solver interfaces","Static lazy constraints","Customizing the ML models","1. Getting started with MIPLearn","Modeling lazy constraints","Modeling user cuts"],titleterms:{"abstract":7,"new":14,"static":12,acceler:14,access:14,acknowledg:6,author:6,baselin:2,benchmark:[2,6],challeng:[1,2,3,4],code:6,collect:8,commit:5,compon:7,constraint:[9,12,15],content:6,custom:13,cut:[9,16],data:[8,14],definit:[1,3,4],dynam:9,facil:0,gener:[1,3,4,14],get:14,instal:14,instanc:[1,3,14],interfac:11,introduct:14,julia:6,knapsack:1,lazi:[9,12,15],licens:6,locat:0,maximum:3,miplearn:[6,14],model:[13,14,15,16],multidimension:1,optim:14,preliminari:2,primal:10,problem:[1,3,4,14],random:[1,3,4],refer:6,result:2,salesman:4,set:3,simpl:14,solut:[10,14],solv:14,solver:11,sourc:6,stabl:3,start:14,tabl:6,train:[8,14],travel:4,tutori:6,understand:14,unit:5,user:[9,16],weight:3}}) \ No newline at end of file