MatrixOfConstraints

docs/src/submodules/Utilities/overview.md

@@ -11,6 +11,7 @@ DocTestFilters = [r"MathOptInterface|MOI"]
 
 The Utilities submodule provides a variety of functionality for managing
 `MOI.ModelLike` objects.
+
 ## Utilities.Model
 
 [`Utilities.Model`](@ref) provides an implementation of a [`ModelLike`](@ref)
@@ -382,6 +383,93 @@ See [`Utilities.supports_allocate_load`](@ref) for more details.
 !!! warning
     The Allocate-Load API should **not** be used outside [`copy_to`](@ref).
 
+## Utilities.MatrixOfConstraints
+
+The constraints of [`Utilities.Model`](@ref) are stored as a vector of tuples
+of function and set in a `Utilities.VectorOfConstraints`. Other representations
+can be used by parametrizing the type [`Utilities.GenericModel`](@ref)
+(resp. [`Utilities.GenericOptimizer`](@ref)). For instance, if all
+non-`SingleVariable` constraints are affine, the coefficients of all the
+constraints can be stored in a single sparse matrix using
+[`Utilities.MatrixOfConstraints`](@ref). The constraints storage can even be
+customized up to a point where it exactly matches the storage of the solver of
+interest, in which case [`copy_to`](@ref) can be implemented for the solver by
+calling [`copy_to`](@ref) to this custom model.
+
+For instance, [Clp](https://github.com/jump-dev/Clp.jl) defines the following
+model
+```julia
+MOI.Utilities.@product_of_scalar_sets(LP, MOI.EqualTo{T}, MOI.LessThan{T}, MOI.GreaterThan{T})
+const Model = MOI.Utilities.GenericModel{
+    Float64,
+    MOI.Utilities.MatrixOfConstraints{
+        Float64,
+        MOI.Utilities.MutableSparseMatrixCSC{Float64,Cint,MOI.Utilities.ZeroBasedIndexing},
+        MOI.Utilities.Box{Float64},
+        LP{Float64},
+    },
+}
+```
+
+The [`copy_to`](@ref) operation can now be implemented as follows (assuming that
+the `Model` definition above is in the `Clp` module so that it can be referred
+to as `Model`, to be distinguished with [`Utilities.Model`](@ref)):
+```julia
+function _copy_to(
+    dest::Optimizer,
+    src::Model
+)
+    @assert MOI.is_empty(dest)
+    A = src.constraints.coefficients
+    row_bounds = src.constraints.constants
+    Clp_loadProblem(
+        dest,
+        A.n,
+        A.m,
+        A.colptr,
+        A.rowval,
+        A.nzval,
+        src.lower_bound,
+        src.upper_bound,
+        # (...) objective vector (omitted),
+        row_bounds.lower,
+        row_bounds.upper,
+    )
+    # Set objective sense and constant (omitted)
+    return
+end
+
+function MOI.copy_to(
+    dest::Optimizer,
+    src::Model;
+    copy_names::Bool = false
+)
+    _copy_to(dest, src)
+    return MOI.Utilities.identity_index_map(src)
+end
+
+function MOI.copy_to(
+    dest::Optimizer,
+    src::MOI.Utilities.UniversalFallback{Model};
+    copy_names::Bool = false
+)
+    # Copy attributes from `src` to `dest` and error in case any unsupported
+    # constraints or attributes are set in `UniversalFallback`.
+    return MOI.copy_to(dest, src.model)
+end
+
+function MOI.copy_to(
+    dest::Optimizer,
+    src::MOI.ModelLike;
+    copy_names::Bool = false
+)
+    model = Model()
+    index_map = MOI.copy_to(model, src)
+    _copy_to(dest, model)
+    return index_map
+end
+```
+
 ## Fallbacks
 
 The value of some attributes can be inferred from the value of other

docs/src/submodules/Utilities/reference.md

@@ -79,6 +79,47 @@ Utilities.load
 Utilities.load_constraint
 ```
 
+## Utilities.MatrixOfConstraints
+
+```@docs
+Utilities.MatrixOfConstraints
+Utilities.rows
+```
+
+### Constants
+
+```@docs
+Utilities.Box
+Utilities.load_constants
+```
+
+### Mutable sparse matrix
+
+```@docs
+Utilities.MutableSparseMatrixCSC
+Utilities.AbstractIndexing
+Utilities.ZeroBasedIndexing
+Utilities.OneBasedIndexing
+Utilities.add_column
+Utilities.allocate_terms
+Utilities.set_number_of_rows
+Utilities.load_terms
+Utilities.final_touch
+```
+
+### Product of sets
+
+```@docs
+Utilities.ProductOfSets
+Utilities.set_index
+Utilities.set_types
+Utilities.add_set
+Utilities.indices
+Utilities.MixOfScalarSets
+Utilities.OrderedProductOfSets
+Utilities.OrderedProductOfScalarSets
+```
+
 ## Fallbacks
 
 ```@docs

src/Bridges/bridge_optimizer.jl

@@ -395,6 +395,9 @@ function MOI.supports_incremental_interface(
 )
     return MOI.supports_incremental_interface(b.model, copy_names)
 end
+function MOIU.final_touch(uf::AbstractBridgeOptimizer, index_map)
+    return MOIU.final_touch(uf.model, index_map)
+end
 
 # References
 function MOI.is_valid(b::AbstractBridgeOptimizer, vi::MOI.VariableIndex)

src/Utilities/Utilities.jl

@@ -60,6 +60,9 @@ include("variables.jl")
 include("vector_of_constraints.jl")
 include("struct_of_constraints.jl")
 include("model.jl")
+include("sparse_matrix.jl")
+include("product_of_sets.jl")
+include("matrix_of_constraints.jl")
 include("parser.jl")
 include("mockoptimizer.jl")
 include("cachingoptimizer.jl")

src/Utilities/cachingoptimizer.jl

@@ -232,6 +232,27 @@ end
 
 _standardize(d::IndexMap) = d
 
+function pass_nonvariable_constraints(
+    dest::CachingOptimizer,
+    src::MOI.ModelLike,
+    idxmap::IndexMap,
+    constraint_types,
+    pass_cons;
+    filter_constraints::Union{Nothing,Function} = nothing,
+)
+    dest.state == ATTACHED_OPTIMIZER && reset_optimizer(dest)
+    return pass_nonvariable_constraints(
+        dest.model_cache,
+        src,
+        idxmap,
+        constraint_types,
+        pass_cons;
+        filter_constraints = filter_constraints,
+    )
+end
+function final_touch(m::CachingOptimizer, index_map)
+    return final_touch(m.model_cache, index_map)
+end
 function MOI.copy_to(m::CachingOptimizer, src::MOI.ModelLike; kws...)
     if m.state == ATTACHED_OPTIMIZER
         reset_optimizer(m)

src/Utilities/copy.jl

@@ -569,6 +569,15 @@ function try_constrain_variables_on_creation(
     single_variable_not_added
 end
 
+"""
+    function final_touch(model::MOI.ModelLike, idxmap) end
+
+This is called at the end of [`default_copy_to`](@ref) to inform the model that
+the copy is finished. This allows `model` to perform thats that should be done
+only once all the model information is gathered.
+"""
+function final_touch(::MOI.ModelLike, idxmap) end
+
 """
     default_copy_to(
         dest::MOI.ModelLike,
@@ -649,6 +658,8 @@ function default_copy_to(
         filter_constraints = filter_constraints,
     )
 
+    final_touch(dest, idxmap)
+
     return idxmap
 end