Add new attribute NodeLimit (#2552)

Author: matbesancon

docs/src/manual/models.md

@@ -105,4 +105,5 @@ The following attributes are available:
  * [`TimeLimitSec`](@ref)
  * [`ObjectiveLimit`](@ref)
  * [`SolutionLimit`](@ref)
+ * [`NodeLimit`](@ref)
  * [`AutomaticDifferentiationBackend`](@ref)

docs/src/reference/models.md

@@ -81,6 +81,7 @@ Silent
 TimeLimitSec
 ObjectiveLimit
 SolutionLimit
+NodeLimit
 RawOptimizerAttribute
 NumberOfThreads
 RawSolver

docs/src/tutorials/implementing.md

@@ -335,6 +335,7 @@ method for each attribute.
 | [`TimeLimitSec`](@ref) | Yes           | Yes           | Yes                |
 | [`ObjectiveLimit`](@ref) | Yes         | Yes           | Yes                |
 | [`SolutionLimit`](@ref) | Yes          | Yes           | Yes                |
+| [`NodeLimit`](@ref)     | Yes          | Yes           | Yes                |
 | [`RawOptimizerAttribute`](@ref) | Yes  | Yes           | Yes                |
 | [`NumberOfThreads`](@ref) | Yes        | Yes           | Yes                |
 | [`AbsoluteGapTolerance`](@ref) | Yes   | Yes           | Yes                |

src/Test/test_attribute.jl

@@ -252,6 +252,32 @@ function setup_test(
     return
 end
 
+function test_attribute_NodeLimit(model::MOI.AbstractOptimizer, ::Config)
+    @requires MOI.supports(model, MOI.NodeLimit())
+    # Get the current value to restore it at the end of the test
+    value = MOI.get(model, MOI.NodeLimit())
+    MOI.set(model, MOI.NodeLimit(), 3)
+    @test MOI.get(model, MOI.NodeLimit()) == 3
+    MOI.set(model, MOI.NodeLimit(), nothing)
+    @test MOI.get(model, MOI.NodeLimit()) === nothing
+    MOI.set(model, MOI.NodeLimit(), 1)
+    @test MOI.get(model, MOI.NodeLimit()) == 1
+    MOI.set(model, MOI.NodeLimit(), value)
+    _test_attribute_value_type(model, MOI.NodeLimit())
+    return
+end
+
+test_attribute_NodeLimit(::MOI.ModelLike, ::Config) = nothing
+
+function setup_test(
+    ::typeof(test_attribute_NodeLimit),
+    model::MOIU.MockOptimizer,
+    ::Config,
+)
+    MOI.set(model, MOI.NodeLimit(), nothing)
+    return
+end
+
 """
     test_attribute_AbsoluteGapTolerance(model::MOI.AbstractOptimizer, config::Config)
 

src/attributes.jl

@@ -899,6 +899,30 @@ struct SolutionLimit <: AbstractOptimizerAttribute end
 
 attribute_value_type(::SolutionLimit) = Union{Nothing,Int}
 
+"""
+    NodeLimit()
+
+An optimizer attribute for setting a limit on the number of branch-and-bound
+nodes explored by a mixed-integer program (MIP) solver.
+
+## Default values
+
+The provided limit must be a `Union{Nothing,Int}`.
+
+When `set` to `nothing`, the limit reverts to the solver's default.
+
+The default value is `nothing`.
+
+## Termination criteria
+
+The solver may stop when the [`NodeCount`](@ref) is larger than or equal to
+the `NodeLimit`. If stopped because of this attribute, the
+[`TerminationStatus`](@ref) must be `NODE_LIMIT`.
+"""
+struct NodeLimit <: AbstractOptimizerAttribute end
+
+attribute_value_type(::NodeLimit) = Union{Nothing,Int}
+
 """
     RawOptimizerAttribute(name::String)