From 73e2de3a077f125f7396dbfc001c56f72a0064a1 Mon Sep 17 00:00:00 2001 From: odow Date: Wed, 13 Mar 2024 15:24:44 +1300 Subject: [PATCH] [docs] improve docstrings in objective.jl --- src/objective.jl | 203 +++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 187 insertions(+), 16 deletions(-) diff --git a/src/objective.jl b/src/objective.jl index 27d5ec9a201..2992557d81f 100644 --- a/src/objective.jl +++ b/src/objective.jl @@ -7,14 +7,35 @@ # An algebraic modeling language for Julia # See https://github.com/jump-dev/JuMP.jl ############################################################################# -# This file contains objective-related functions """ relative_gap(model::GenericModel) Return the final relative optimality gap after a call to `optimize!(model)`. -Exact value depends upon implementation of MathOptInterface.RelativeGap() -by the particular solver used for optimization. + +Exact value depends upon implementation of [`MOI.RelativeGap`](@ref) by the +particular solver used for optimization. + +This function is equivalent to querying the [`MOI.RelativeGap`](@ref) attribute. + +## Example + +```jldoctest +julia> import HiGHS + +julia> model = Model(HiGHS.Optimizer); + +julia> set_silent(model) + +julia> @variable(model, x >= 1, Int); + +julia> @objective(model, Min, 2 * x + 1); + +julia> optimize!(model) + +julia> relative_gap(model) +0.0 +``` """ function relative_gap(model::GenericModel{T})::T where {T} return MOI.get(model, MOI.RelativeGap()) @@ -31,6 +52,27 @@ vector-valued objectives, it returns a `Vector{Float64}`. In the case of a vector-valued objective, this returns the _ideal point_, that is, the point obtained if each objective was optimized independently. + +This function is equivalent to querying the [`MOI.ObjectiveBound`](@ref) attribute. + +## Example + +```jldoctest +julia> import HiGHS + +julia> model = Model(HiGHS.Optimizer); + +julia> set_silent(model) + +julia> @variable(model, x >= 1, Int); + +julia> @objective(model, Min, 2 * x + 1); + +julia> optimize!(model) + +julia> objective_bound(model) +3.0 +``` """ function objective_bound(model::GenericModel{T})::Union{T,Vector{T}} where {T} return MOI.get(model, MOI.ObjectiveBound()) @@ -45,7 +87,33 @@ most-recent solution returned by the solver. For scalar-valued objectives, this function returns a `Float64`. For vector-valued objectives, it returns a `Vector{Float64}`. +This function is equivalent to querying the [`MOI.ObjectiveValue`](@ref) attribute. + See also: [`result_count`](@ref). + +## Example + +```jldoctest +julia> import HiGHS + +julia> model = Model(HiGHS.Optimizer); + +julia> set_silent(model) + +julia> @variable(model, x >= 1); + +julia> @objective(model, Min, 2 * x + 1); + +julia> optimize!(model) + +julia> objective_value(model) +3.0 + +julia> objective_value(model; result = 2) +ERROR: Result index of attribute MathOptInterface.ObjectiveValue(2) out of bounds. There are currently 1 solution(s) in the model. +Stacktrace: +[...] +``` """ function objective_value( model::GenericModel{T}; @@ -63,7 +131,34 @@ index `result` of the most-recent solution returned by the solver. Throws `MOI.UnsupportedAttribute{MOI.DualObjectiveValue}` if the solver does not support this attribute. +This function is equivalent to querying the [`MOI.DualObjectiveValue`](@ref) +attribute. + See also: [`result_count`](@ref). + +## Example + +```jldoctest +julia> import HiGHS + +julia> model = Model(HiGHS.Optimizer); + +julia> set_silent(model) + +julia> @variable(model, x >= 1); + +julia> @objective(model, Min, 2 * x + 1); + +julia> optimize!(model) + +julia> dual_objective_value(model) +3.0 + +julia> dual_objective_value(model; result = 2) +ERROR: Result index of attribute MathOptInterface.DualObjectiveValue(2) out of bounds. There are currently 1 solution(s) in the model. +Stacktrace: +[...] +``` """ function dual_objective_value( model::GenericModel{T}; @@ -76,6 +171,25 @@ end objective_sense(model::GenericModel)::MOI.OptimizationSense Return the objective sense. + +This function is equivalent to querying the [`MOI.ObjectiveSense`](@ref) attribute. + +## Example + +```jldoctest +julia> model = Model(); + +julia> objective_sense(model) +FEASIBILITY_SENSE::OptimizationSense = 2 + +julia> @variable(model, x); + +julia> @objective(model, Max, x) +x + +julia> objective_sense(model) +MAX_SENSE::OptimizationSense = 1 +``` """ function objective_sense(model::GenericModel) return MOI.get(model, MOI.ObjectiveSense())::MOI.OptimizationSense @@ -84,10 +198,26 @@ end """ set_objective_sense(model::GenericModel, sense::MOI.OptimizationSense) -Sets the objective sense of the model to the given sense. See -[`set_objective_function`](@ref) to set the objective function. These are -low-level functions; the recommended way to set the objective is with the -[`@objective`](@ref) macro. +Sets the objective sense of the model to the given sense. + +See [`set_objective_function`](@ref) to set the objective function. + +These are low-level functions; the recommended way to set the objective is with +the [`@objective`](@ref) macro. + +## Example + +```jldoctest +julia> model = Model(); + +julia> objective_sense(model) +FEASIBILITY_SENSE::OptimizationSense = 2 + +julia> set_objective_sense(model, MOI.MAX_SENSE) + +julia> objective_sense(model) +MAX_SENSE::OptimizationSense = 1 +``` """ function set_objective_sense(model::GenericModel, sense::MOI.OptimizationSense) return MOI.set(model, MOI.ObjectiveSense(), sense) @@ -99,10 +229,30 @@ end set_objective_function(model::GenericModel, func::Real) set_objective_function(model::GenericModel, func::Vector{<:AbstractJuMPScalar}) -Sets the objective function of the model to the given function. See -[`set_objective_sense`](@ref) to set the objective sense. These are low-level -functions; the recommended way to set the objective is with the -[`@objective`](@ref) macro. +Sets the objective function of the model to the given function. + +See [`set_objective_sense`](@ref) to set the objective sense. + +These are low-level functions; the recommended way to set the objective is with +the [`@objective`](@ref) macro. + +## Example + +```jldoctest +julia> model = Model(); + +julia> @variable(model, x); + +julia> @objective(model, Min, x); + +julia> objective_function(model) +x + +julia> set_objective_function(model, 2 * x + 1) + +julia> objective_function(model) +2 x + 1 +``` """ function set_objective_function end @@ -180,6 +330,22 @@ end objective_function_type(model::GenericModel)::AbstractJuMPScalar Return the type of the objective function. + +This function is equivalent to querying the [`MOI.ObjectiveFunctionType`](@ref) +attribute. + +## Example + +```jldoctest +julia> model = Model(); + +julia> @variable(model, x); + +julia> @objective(model, Min, 2 * x + 1); + +julia> objective_function_type(model) +AffExpr (alias for GenericAffExpr{Float64, GenericVariableRef{Float64}}) +``` """ function objective_function_type(model::GenericModel) return jump_function_type( @@ -191,12 +357,15 @@ end """ objective_function( model::GenericModel, - T::Type = objective_function_type(model), - ) + ::Type{F} = objective_function_type(model), + ) where {F} -Return an object of type `T` representing the objective function. +Return an object of type `F` representing the objective function. -Error if the objective is not convertible to type `T`. +Errors if the objective is not convertible to type `F`. + +This function is equivalent to querying the [`MOI.ObjectiveFunction{F}`](@ref) +attribute. ## Example @@ -218,11 +387,13 @@ julia> objective_function(model, QuadExpr) julia> typeof(objective_function(model, QuadExpr)) QuadExpr (alias for GenericQuadExpr{Float64, GenericVariableRef{Float64}}) ``` + We see with the last two commands that even if the objective function is affine, as it is convertible to a quadratic function, it can be queried as a quadratic function and the result is quadratic. -However, it is not convertible to a variable. +However, it is not convertible to a variable: + ```jldoctest objective_function; filter = r"MathOptInterface\\."s julia> objective_function(model, VariableRef) ERROR: InexactError: convert(MathOptInterface.VariableIndex, 1.0 + 2.0 MOI.VariableIndex(1))