Partial implementation of parallel_solve

Project.toml

@@ -5,6 +5,7 @@ version = "0.2.0"
 
 [deps]
 Conda = "8f4d0f93-b110-5947-807f-2305c1781a2d"
+Distributed = "8ba89e20-285c-5b6f-9357-94700520ee1b"
 JLD2 = "033835bb-8acc-5ee8-8aae-3f567f8a3819"
 JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
 Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"

README.md

@@ -108,12 +108,12 @@ end
 fit!(solver, training_instances)
 
 # Save trained solver to disk
-save("solver.mls", solver)
+save("solver.bin", solver)
 
 # Application restarts...
 
 # Load trained solver from disk
-solver = load("solver.mls")
+solver = load_solver("solver.bin")
 
 # Solve additional instances
 test_instances = [...]
@@ -123,46 +123,43 @@ end
 
 ```
 
-### 1.5 Solving training instances in parallel
-```julia
-using MIPLearn
-using Cbc
+### 1.5 Solving instances from disk
 
-# Solve training instances in parallel
-training_instances = [...]
-solver = LearningSolver(Cbc.Optimizer)
-parallel_solve!(solver, training_instances, n_jobs=4)
-fit!(solver, training_instances)
+In all examples above, we have assumed that instances are available as `JuMPInstance` objects, stored in memory. When problem instances are very large, or when there is a large number of problem instances, this approach may require an excessive amount of memory. To reduce memory requirements, MIPLearn.jl can also operate on instances that are stored on disk, through the `FileInstance` class, as the next example illustrates.
 
-# Solve test instances in parallel
-test_instances = [...]
-parallel_solve!(solver, test_instances)
-```
-
-### 1.6 Solving instances from disk
 
 ```julia
 using MIPLearn
 using JuMP
 using Cbc
 
-# Create 600 problem instances and save them to files
+# Create a large number of problem instances
 for i in 1:600
-    m = Model()
-    @variable(m, x, Bin)
-    @objective(m, Min, x)
-    @feature(x, [1.0])
 
+    # Build JuMP model
+    model = Model()
+    @variable(...)
+    @objective(...)
+    @constraint(...)
+
+    # Add ML features and categories
+    @feature(...)
+    @category(...)
+    
+    # Save instances to a file
     instance = JuMPInstance(m)
     save("instance-$i.bin", instance)
 end
 
-# Initialize instances and solver
+# Initialize training and test instances
 training_instances = [FileInstance("instance-$i.bin") for i in 1:500]
 test_instances = [FileInstance("instance-$i.bin") for i in 501:600]
+
+# Initialize solver
 solver = LearningSolver(Cbc.Optimizer)
 
-# Solve training instances
+# Solve training instances. Files are modified in-place, and at most one
+# file is loaded to memory at a time.
 for instance in training_instances
     solve!(solver, instance)
 end
@@ -176,6 +173,39 @@ for instance in test_instances
 end
 ```
 
+### 1.6 Solving training instances in parallel
+
+In many situations, instances can be solved in parallel to accelerate the training process. MIPLearn.jl provides the method `parallel_solve!(solver, instances)` to easily achieve this.
+
+First, launch Julia in multi-process mode:
+```
+julia --procs 4
+```
+Then run the following script:
+
+```julia
+@everywhere using MIPLearn
+@everywhere using Cbc
+
+# Initialize training and test instances
+training_instances = [...]
+test_instances = [...]
+
+# Initialize the solver
+solver = LearningSolver(Cbc.Optimizer)
+
+# Solve training instances in parallel. The number of instances solved
+# simultaneously is the same as the `--procs` specified when running Julia.
+parallel_solve!(solver, training_instances)
+
+# Train machine learning models
+fit!(solver, training_instances)
+
+# Solve test instances in parallel
+parallel_solve!(solver, test_instances)
+```
+
+
 ## 2. Customization
 
 ### 2.1 Selecting solver components

src/MIPLearn.jl

@@ -6,20 +6,16 @@ __precompile__(false)
 module MIPLearn
 
 using PyCall
-
-export JuMPInstance
-export LearningSolver
-export @feature
-export @category
-
-miplearn = pyimport("miplearn")
+global miplearn = pyimport("miplearn")
+global traceback = pyimport("traceback")
 
 include("utils/log.jl")
 include("utils/exceptions.jl")
+include("instance/abstract.jl")
+include("instance/jump.jl")
+include("instance/file.jl")
 include("solvers/jump.jl")
 include("solvers/learning.jl")
 include("solvers/macros.jl")
-include("instance/jump.jl")
-include("instance/file.jl")
 
 end # module

src/instance/abstract.jl

@@ -0,0 +1,8 @@
+#  MIPLearn: Extensible Framework for Learning-Enhanced Mixed-Integer Optimization
+#  Copyright (C) 2020-2021, UChicago Argonne, LLC. All rights reserved.
+#  Released under the modified BSD license. See COPYING.md for more details.
+
+abstract type Instance
+end
+
+

src/instance/file.jl

@@ -55,12 +55,16 @@ end
 
 struct FileInstance <: Instance
     py::PyCall.PyObject
+    filename::AbstractString
 end
 
 
 function FileInstance(filename)::FileInstance
     filename isa AbstractString || error("filename should be a string. Found $(typeof(filename)) instead.")
-    return FileInstance(PyFileInstance(filename))
+    return FileInstance(
+        PyFileInstance(filename),
+        filename,
+    )
 end
 
 

src/solvers/learning.jl

@@ -2,18 +2,21 @@
 #  Copyright (C) 2020-2021, UChicago Argonne, LLC. All rights reserved.
 #  Released under the modified BSD license. See COPYING.md for more details.
 
+using Distributed
+
+
 struct LearningSolver
     py::PyCall.PyObject
-end
-
-
-abstract type Instance
+    optimizer_factory
 end
 
 
 function LearningSolver(optimizer_factory)::LearningSolver
     py = miplearn.LearningSolver(solver=JuMPSolver(optimizer_factory))
-    return LearningSolver(py)
+    return LearningSolver(
+        py,
+        optimizer_factory,
+    )
 end
 
 
@@ -31,7 +34,19 @@ function fit!(solver::LearningSolver, instances::Vector{<:Instance})
 end
 
 
+function parallel_solve!(solver::LearningSolver, instances::Vector{FileInstance})
+    filenames = [instance.filename for instance in instances]
+    optimizer_factory = solver.optimizer_factory
+    @sync @distributed for filename in filenames
+        s = LearningSolver(optimizer_factory)
+        solve!(s, FileInstance(filename))
+        nothing
+    end
+end
+
+
 export Instance,
        LearningSolver,
        solve!,
-       fit!
+       fit!,
+       parallel_solve!

src/solvers/macros.jl

@@ -62,3 +62,7 @@ macro category(obj, category)
         set_category!($(esc(obj)), $(esc(category)))
     end
 end
+
+
+export @feature,
+       @category

src/utils/exceptions.jl

@@ -3,7 +3,6 @@
 #  Released under the modified BSD license. See COPYING.md for more details.
 
 using PyCall
-traceback = pyimport("traceback")
 
 
 macro python_call(expr)

test/solvers/learning_test.jl

@@ -7,7 +7,7 @@ using MIPLearn
 using Gurobi
 
 @testset "LearningSolver" begin
-    @testset "model with annotations" begin
+    @testset "Model with annotations" begin
         # Create standard JuMP model
         weights = [1.0, 2.0, 3.0]
         prices = [5.0, 6.0, 7.0]
@@ -48,7 +48,7 @@ using Gurobi
         solve!(solver, instance)
     end
 
-    @testset "model without annotations" begin
+    @testset "Model without annotations" begin
         model = Model()
         @variable(model, x, Bin)
         @variable(model, y, Bin)
@@ -57,5 +57,4 @@ using Gurobi
         instance = JuMPInstance(model)
         stats = solve!(solver, instance)
     end
-
 end