Add documentation

Author: odow

docs/src/manual/objective.md

@@ -157,3 +157,80 @@ julia> @objective(model, Min, 2x)
 julia> @objective(model, Max, objective_function(model))
 2 x
 ```
+
+## Set a vector-valued objective
+
+Define a multi-objective optimization problem by passing a vector of objectives:
+
+```jldoctest; setup = :(model=Model())
+julia> @variable(model, x[1:2]);
+
+julia> @objective(model, Min, [1 + x[1], 2 * x[2]])
+2-element Vector{AffExpr}:
+ x[1] + 1
+ 2 x[2]
+
+julia> f = objective_function(model)
+2-element Vector{AffExpr}:
+ x[1] + 1
+ 2 x[2]
+```
+
+In most cases, multi-objective optimization solvers will return multiple
+solutions, corresponding to points on the Pareto frontier. See [Multiple solutions](@ref)
+for information on how to query and work with multiple solutions.
+
+Note that you can must set a single objective sense, that is, you cannot have
+both minimization and maximization objectives. Work around this limitation by
+choosing `Min` and negating any objectives you want to maximize:
+
+```jldoctest; setup = :(model=Model())
+julia> @variable(model, x[1:2]);
+
+julia> @expression(model, obj1, 1 + x[1])
+x[1] + 1
+
+julia> @expression(model, obj2, 2 * x[1])
+2 x[1]
+
+julia> @objective(model, Min, [obj1, -obj2])
+2-element Vector{AffExpr}:
+ x[1] + 1
+ -2 x[1]
+```
+
+Defining your objectives as expressions allows flexibility in how you can solve
+variations of the same problem, with some objectives removed and constrained to
+be no worse that a fixed value.
+
+```jldoctest; setup = :(model=Model())
+julia> @variable(model, x[1:2]);
+
+julia> @expression(model, obj1, 1 + x[1])
+x[1] + 1
+
+julia> @expression(model, obj2, 2 * x[1])
+2 x[1]
+
+julia> @expression(model, obj3, x[1] + x[2])
+x[1] + x[2]
+
+julia> @objective(model, Min, [obj1, obj2, obj3])  # Three-objective problem
+3-element Vector{AffExpr}:
+ x[1] + 1
+ 2 x[1]
+ x[1] + x[2]
+
+julia> # optimize!(model), look at the solution, talk to stakeholders, then
+       # decide you want to solve a new problem where the third objective is
+       # removed and constrained to be better than 2.0.
+       nothing
+
+julia> @objective(model, Min, [obj1, obj2])   # Two-objective problem
+2-element Vector{AffExpr}:
+ x[1] + 1
+ 2 x[1]
+
+julia> @constraint(model, obj3 <= 2.0)
+x[1] + x[2] ≤ 2.0
+```

src/objective.jl

@@ -25,6 +25,9 @@ end
 
 Return the best known bound on the optimal objective value after a call to
 `optimize!(model)`.
+
+In the case of a vector-valued objective, this returns the nadir point, that is,
+the point obtained if each objective was optimized independently.
 """
 function objective_bound(model::Model)::Union{Float64,Vector{Float64}}
     return MOI.get(model, MOI.ObjectiveBound())
@@ -36,6 +39,9 @@ end
 Return the objective value associated with result index `result` of the
 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}`.
+
 See also: [`result_count`](@ref).
 """
 function objective_value(