[breaking] Rename MOIU.supports_default_copy_to to MOI.supports_incremental_interface

docs/src/manual/implementing.md

@@ -453,25 +453,23 @@ MOI.supports_add_constrained_variables(::Optimizer, ::Type{Reals}) = false
 ### Incremental and `copy_to`
 
 If you implement the incremental interface, you have the option of also
-implementing [`copy_to`](@ref). If you don't want to implement
-[`copy_to`](@ref), e.g., because the solver has no API for building the problem
-in a single function call, define the following fallback:
+implementing [`copy_to`](@ref).
+
+If you don't want to implement [`copy_to`](@ref), e.g., because the solver has
+no API for building the problem in a single function call, define the following
+fallback:
 ```julia
+# If you support VariableName and ConstraintName...
+MOI.supports_incremental_interface(::Optimizer, copy_names::Bool) = true
+# Otherwise...
+MOI.supports_incremental_interface(::Optimizer, copy_names::Bool) = !copy_names
+
 function MOI.copy_to(dest::Optimizer, src::MOI.ModelLike; kwargs...)
     return MOI.Utilities.automatic_copy_to(dest, src; kwargs...)
 end
-
-function MOI.Utilities.supports_default_copy_to(
-    model::Optimizer,
-    copy_names::Bool,
-)
-    # If you support names...
-    return true
-    # Otherwise...
-    return !copy_names
-end
 ```
-See [`Utilities.supports_default_copy_to`](@ref) for more details.
+See [`supports_incremental_interface`](@ref) for more details on whether to
+implement the `true` or `!copy_names` version.
 
 ## [Names](@id implement_names)
 

docs/src/reference/models.md

@@ -28,6 +28,7 @@ is_empty
 empty!
 write_to_file
 read_from_file
+supports_incremental_interface
 copy_to
 ```
 

docs/src/submodules/Test/overview.md

@@ -22,7 +22,7 @@ so that all solvers can benefit.
 The skeleton below can be used for the wrapper test file of a solver named
 `FooBar`. Remove unnecessary tests as appropriate, for example tests for
 features that the solver does not support (tests are not skipped depending
-on the value of `supports`). 
+on the value of `supports`).
 
 ```julia
 # ============================ /test/MOI_wrapper.jl ============================
@@ -61,10 +61,10 @@ function test_SolverName()
     @test MOI.get(OPTIMIZER, MOI.SolverName()) == "FooBar"
 end
 
-function test_supports_default_copy_to()
-    @test MOI.Utilities.supports_default_copy_to(OPTIMIZER, false)
+function test_supports_incremental_interface()
+    @test MOI.supports_incremental_interface(OPTIMIZER, false)
     # Use `@test !...` if names are not supported
-    @test MOI.Utilities.supports_default_copy_to(OPTIMIZER, true)
+    @test MOI.supports_incremental_interface(OPTIMIZER, true)
 end
 
 function test_unittest()

docs/src/submodules/Utilities/reference.md

@@ -58,7 +58,6 @@ Utilities.latex_formulation
 ```@docs
 Utilities.automatic_copy_to
 Utilities.default_copy_to
-Utilities.supports_default_copy_to
 ```
 
 ### [Allocate-Load API](@id allocate_load_api_ref)

src/Bridges/bridge_optimizer.jl

@@ -358,11 +358,11 @@ end
 function MOI.copy_to(mock::AbstractBridgeOptimizer, src::MOI.ModelLike; kws...)
     return MOIU.automatic_copy_to(mock, src; kws...)
 end
-function MOIU.supports_default_copy_to(
+function MOI.supports_incremental_interface(
     b::AbstractBridgeOptimizer,
     copy_names::Bool,
 )
-    return MOIU.supports_default_copy_to(b.model, copy_names)
+    return MOI.supports_incremental_interface(b.model, copy_names)
 end
 
 # References

src/MathOptInterface.jl

@@ -94,6 +94,35 @@ Empty the model, that is, remove all variables, constraints and model attributes
 """
 function empty! end
 
+"""
+    supports_incremental_interface(model::ModelLike, copy_names::Bool)
+
+Return a `Bool` indicating whether `model` supports building incrementally via
+[`add_variable`](@ref) and [`add_constraint`](@ref).
+
+`copy_names` is a `Bool` indicating whether the user wishes to set
+[`VariableName`](@ref) and [`ConstraintName`](@ref) attributes.
+If `model` supports the incremental interface but does not support name
+attributes, define
+```julia
+supports_incremental_interface(::MyNewModel, copy_names::Bool) = !copy_names
+```
+
+The main purpose of this function is to determine whether a model can be loaded
+into `model` incrementally or whether it should be cached and copied at once
+instead.
+
+This is used in two places to determine whether to add a cache:
+1. A first cache can be used to store the model as entered by the user as well
+   as the names of variables and constraints. This cache is created if this
+   function returns `false` when `copy_names` is `true`.
+2. If bridges are used, then a second cache can be used to store the bridged
+   model with unnamed variables and constraints. This cache is created if this
+   function returns `false` when `copy_names` is `false`.
+```
+"""
+supports_incremental_interface(::ModelLike, ::Bool) = false
+
 """
     copy_to(dest::ModelLike, src::ModelLike; copy_names=true, warn_attributes=true)