Add warmstart_backend_start_values

Author: pulsipher

docs/src/develop/extensions.md

@@ -779,6 +779,7 @@ extended using the following steps:
 8. As appropriate and if NOT a `JuMPBackend`, extend the following:
     - The remaining result related attributes listed in [`JuMP.get_attribute`](@ref JuMP.get_attribute(::AbstractTransformationBackend, ::Any))
     - [`JuMP.lp_sensitivity_report`](@ref JuMP.lp_sensitivity_report(::AbstractTransformationBackend))
+    - [`InfiniteOpt.warmstart_backend_start_values`](@ref) to enable automated warmstarts
 9. If Step 6 was skipped and/or the backend is NOT a `JuMPBackend` then extend the following:
     - [`InfiniteOpt.map_value`](@ref) (enables `JuMP.value`)
     - [`InfiniteOpt.map_infinite_parameter_value`](@ref) (enables `JuMP.value` for infinite parameters)

docs/src/guide/optimize.md

@@ -63,6 +63,18 @@ via [`set_optimizer`](@ref):
 julia> set_optimizer(model, Ipopt.Optimizer)
 ```
 
+!!! note
+    For effective resolves, 
+    [`warmstart_backend_start_values`](@ref warmstart_backend_start_values(::InfiniteModel))
+    provides a convenient and efficient way to update the start values used by
+    the backend using a previous solution stored in the backend.
+    ```julia
+    optimize!(model)
+    warmstart_backend_start_values(model)
+    set_parameter_value(p, 42)
+    optimize!(model)
+    ```
+
 A number of methods also exist to adjust the optimizer settings such as 
 suppressing output. This is explained below in the 
 [Optimizer Settings](@ref opt_settings) section.

docs/src/guide/variable.md

@@ -890,6 +890,18 @@ julia> start_value(z)
 0.0
 ```
 
+!!! note
+    For effective resolves, 
+    [`warmstart_backend_start_values`](@ref warmstart_backend_start_values(::InfiniteModel))
+    provides a convenient and efficient way to update the start values used by
+    the backend using a previous solution stored in the backend.
+    ```julia
+    optimize!(model)
+    warmstart_backend_start_values(model)
+    set_parameter_value(p, 42)
+    optimize!(model)
+    ```
+
 For infinite variables, this should be done using 
 [`set_start_value_function`](@ref). FOr example:
 ```jldoctest var_macro
@@ -903,4 +915,4 @@ arguments that exactly match the format of the infinite parameters given in
 `Infinite(params...)`.
 
 A number of other techniques exist for the various variable types can be found in 
-the manual below.
+the manual.

docs/src/manual/backend.md

@@ -73,4 +73,5 @@ constraint_supports(::InfOptConstraintRef, ::AbstractTransformationBackend)
 transformation_backend_ready
 set_transformation_backend_ready
 update_parameter_value(::AbstractTransformationBackend, ::Any, ::Any)
+warmstart_backend_start_values(::AbstractTransformationBackend)
 ```

docs/src/manual/result.md

@@ -56,6 +56,11 @@ JuMP.lp_sensitivity_report(::InfiniteModel)
 InfOptSensitivityReport 
 ```
 
+## Warmstarts
+```@docs
+warmstart_backend_start_values(::InfiniteModel)
+```
+
 ## Transformation Backend Extension API
 ```@docs
 map_value(::Any, ::AbstractTransformationBackend)

src/backends.jl

@@ -339,6 +339,48 @@ function build_transformation_backend!(model::InfiniteModel; kwargs...)
     return
 end
 
+"""
+    warmstart_backend_start_values(
+        backend::AbstractTransformationBackend; 
+        [kwargs...]
+    )::Nothing
+
+Use the previous solution values stored in `backend` to warmstart the start values
+to be used for the next [`optimize!`](@ref) call. This serves as an extension point 
+for new backend types.
+"""
+function warmstart_backend_start_values(
+    backend::AbstractTransformationBackend; 
+    kwargs...
+    )
+    error("`warmstart_backend_start_values` not implemented for transformation backends " * 
+          "of type `$(typeof(backend))`.")
+end
+
+"""
+    warmstart_backend_start_values(model::InfiniteModel; [kwargs...])
+
+Use the previous solution values (primals and duals) stored in the transformation 
+backend of `model` to warmstart the start values to be used for the next 
+[`optimize!`](@ref) call. For `JuMPBackend`s (like `TranscriptionBackend`) this calls 
+`JuMP.set_start_values` on the underlying JuMP model. Note that only start values in
+the backend model are updated, the start values stored in `model` remain unchanged.
+
+**Example*
+```julia-repl
+julia> optimize!(model)
+
+julia> warmstart_backend_start_values(model) # call before making model updates
+
+julia> set_parameter_value(p, 42)
+
+julia> optimize!(model)
+```
+"""
+function warmstart_backend_start_values(model::InfiniteModel; kwargs...)
+    return warmstart_backend_start_values(model.backend; kwargs...)
+end
+
 """
     JuMP.set_optimize_hook(
         model::InfiniteModel, 
@@ -696,6 +738,19 @@ end
 function JuMP.optimize!(backend::JuMPBackend)
     return JuMP.optimize!(backend.model)
 end
+function warmstart_backend_start_values(backend::JuMPBackend; kwargs...)
+    jump_model = transformation_model(backend)
+    if JuMP.has_values(jump_model)
+        JuMP.set_start_values(
+            jump_model;
+            nonlinear_dual_start = nothing, 
+            kwargs...
+        )
+    else
+        @warn("No previous solution values found to warmstart the backend.")
+    end
+    return
+end
 
 ################################################################################
 #                             VARIABLE MAPPING API

test/extensions.jl

@@ -262,6 +262,10 @@ end
 
     # prepare for result queries
     mockoptimizer = JuMP.backend(m).optimizer.model
+    for v in all_variables(m.backend.model)
+        MOI.set(mockoptimizer, MOI.VariablePrimal(),
+                JuMP.optimizer_index(v), 1.0)
+    end
     MOI.set(mockoptimizer, MOI.TerminationStatus(), MOI.OPTIMAL)
     MOI.set(mockoptimizer, MOI.RawStatusString(), "solver specific string")
     MOI.set(mockoptimizer, MOI.ResultCount(), 2)
@@ -315,6 +319,8 @@ end
     @test dual(c2) == [0., -1.]
     @test dual(c3) == [0., -1.]
     @test is_solved_and_feasible(m)
+    @test warmstart_backend_start_values(m) isa Nothing
+    @test start_value(transformation_variable(y)) == 1
 #     @test optimizer_index(x) == optimizer_index.(transformation_variable(x))
 #     @test optimizer_index(x0) == optimizer_index(transformation_variable(x0))
 #     @test optimizer_index(y) == optimizer_index(transformation_variable(y))

test/extensions/backend.jl

@@ -405,3 +405,17 @@ function InfiniteOpt.update_parameter_value(
     end
     return true
 end
+
+# Extend `warmstart_backend_start_values` to support warmstarting
+function InfiniteOpt.warmstart_backend_start_values(
+    backend::NewReformBackend;
+    my_kwarg = true # EXTRA CAN BE PASSED ON TO THE MAPPING
+    )
+    # REPLACE BELOW WITH ACTUAL WARMSTARTING OPERATION
+    if my_kwarg
+        JuMP.set_start_values(transformation_model(backend))
+    else
+        @warn("Unable to warmstart backend.")
+    end
+    return
+end

test/results.jl

@@ -203,6 +203,9 @@ end
             MOI.set(mockoptimizer, MOI.ConstraintDual(), JuMP.optimizer_index(c), -12.0)
         end
     end
+    for v in all_variables(tb.model)
+        MOI.set(mockoptimizer, MOI.VariablePrimal(1), JuMP.optimizer_index(v), 1.0)
+    end
     # MOI.set(mockoptimizer, MOI.ConstraintDual(), JuMP.optimizer_index(creft), 7.0)
     MOI.set(mockoptimizer, MOI.VariablePrimal(1), JuMP.optimizer_index(gt), 1.0)
     MOI.set(mockoptimizer, MOI.VariablePrimal(1), JuMP.optimizer_index(inft[1]), 2.0)
@@ -270,6 +273,11 @@ end
         @test isa(optimizer_index(inf, label = InternalLabel), Vector{MOI.VariableIndex})
         @test isa(optimizer_index(rv), Vector{MOI.VariableIndex})
     end
+    # test warmstart_backend_start_values
+    @testset "warmstart_backend_start_values" begin
+        @test warmstart_backend_start_values(m) isa Nothing
+        @test start_value(gt) == 1
+    end
     # test dual
     @testset "JuMP.dual" begin
         @test_throws ErrorException dual(g)
@@ -436,12 +444,21 @@ end
         @test shadow_price(c4) == [-2, -3]
         @test_throws ErrorException InfiniteOpt.map_shadow_price(c1, TestBackend())
     end
+    # test warmstart_backend_start_values
+    @testset "warmstart_backend_start_values" begin
+        @test warmstart_backend_start_values(m) isa Nothing
+        @test start_value(c1t) == 1
+        @test dual_start_value(c1t) == -1
+        @test_throws ErrorException warmstart_backend_start_values(TestBackend())
+    end
     # test model not up to date
     set_objective_sense(m, MOI.MAX_SENSE)
     @testset "Not up-to-date" begin 
         @test_throws ErrorException dual(c1)
         @test_throws ErrorException shadow_price(c1)
         @test_throws ErrorException optimizer_index(c1)
+        str = "No previous solution values found to warmstart the backend."
+        @test_logs (:warn, str) warmstart_backend_start_values(m)
     end
 end