Reference

Structure holding the solutions for the near-optimal alternatives.

Structure representing a problem that can be solved by Metaheuristics.jl and the algorithm to solve it.

add_solution!(
    model::JuMP.Model,
    metric::Distances.Metric
)

Add a previously found solution to a modelling-for-generating-alternatives problem. Used for iteratively finding multiple alternative solutions.

add_solution!(
    problem::MetaheuristicProblem,
    result::Metaheuristics.State,
    metric::Distances.SemiMetric
)

Modify a Metaheuristic problem representing the alternative generating problem for the original LP using a newly found alternative solution. This function can be used when one wants to iteratively run a metaheuristic to find alternative solutions one by one.

Arguments:

• problem::MetaheuristicProblem: problem to be modified by adding a solution.
• result::Metaheuristics.State: result containing the optimal solution to add to the objective function.
• metric::Distances.SemiMetric: metric used to evaluate distance between alternatives.

create_alternative_problem(
    model::JuMP.Model,
    optimality_gap::Float64,
    metric::Distances.Metric,
    [selected_variables::Vector{VariableRef}]
)

Transform a JuMP model into a model solving its corresponding modelling-for-generating-alternatives problem.

Arguments

• model::JuMP.Model: a solved JuMP model for which alternatives are generated.
• optimality_gap::Float64: the maximum percentage deviation (>= 0) an alternative may have compared to the optimal solution.
• metric::Distances.Metric=SqEuclidean(): the metric used to maximise the difference between alternatives and the optimal solution.
• fixed_variables::Vector{VariableRef}=[]: a subset of all variables of model that are not allowed to be changed when seeking for alternatives.

problem = create_alternative_generating_problem(
    model::JuMP.Model,
    algorithm::Metaheuristics.Algorithm,
    initial_solution::OrderedDict{VariableRef, Float64},
    optimality_gap::Float64,
    metric::Distances.SemiMetric,
    fixed_variables::Dict{VariableRef, Float64}
)

Create the Metaheuristic problem representing the alternative generating problem for the original LP.

Arguments:

• model::JuMP.Model: JuMP model representing the original LP.
• algorithm::Metaheuristics.Algorithm: Metaheuristic algorithm to solve the alternative generating problem.
• initial_solution::OrderedDict{VariableRef, Float64}: (near-)optimal solution to model, for which alternatives are sought.
• optimality_gap::Float64: maximum gap in objective value between initial_solution and alternative solutions.
• metric::Distances.SemiMetric: distance metric used to compute distance between alternative solutions and initial_solution.
• fixed_variables::Dict{MOI.VariableIndex, Float64}: solution values for fixed variables of the original problem.

objective = create_objective(
    model::JuMP.Model,
    solution::OrderedDict{JuMP.VariableRef, Float64},
    optimality_gap::Float64,
    metric::Distances.SemiMetric,
    index_map::Dict{Int64, Int64},
    fixed_variables::Dict{VariableRef, Float64}
)

Create an objective function supported by Metaheuristics.jl for the alternative generating problem.

Arguments

• model::JuMP.Model: solved JuMP model of the original lp problem.
• solution::OrderedDict{JuMP.VariableRef, Float64}: solution value of the original lp problem excluding fixed variables.
• optimality_gap::Float64: maximum difference between objective value of optimal solution and alternative solutions.
• metric::Distances.SemiMetric: distance metric used to measure distance between solutions.
• index_map::Dict{Int64, Int64}: dictionary mapping indices in the JuMP/MathOptInterface model to indices of x.
• fixed_variables::Dict{VariableRef, Float64}: dictionary containing the values of the fixed variables.

bounds = extract_bounds(
    model::JuMP.Model,
    index_map::Dict{Int64, Int64}
)

Transform the bounds from a JuMP Model into a matrix of bounds readable by Metaheuristics.jl.

Arguments

• model::JuMP.Model: solved JuMP model of the original lp problem.
• index_map::Dict{Int64, Int64}: dictionary mapping indices in the JuMP/MathOptInterface model to indices of x.

constraint = extract_constraint(
    constraint::MOI.ConstraintFunction,
    x::Vector{Float64},
    index_map::Dict{Int64, Int64},
    fixed_variables::Dict{MOI.VariableIndex, Float64}
)

Convert a constraint from a MathOptInterface function into a julia function of x. Supports only ScalarAffineFunction and VariableIndex constraints.

Arguments

• constraint::MOI.ConstraintFunction: constraint transform into a julia function.
• x::Vector{Float64}: a vector representing an individual in the metaheuristic population.
• index_map::Dict{Int64, Int64}: a dictionary mapping indices in the MathOptInterface model to indices of x.
• fixed_variables::Dict{MOI.VariableIndex, Float64}: a dictionary containing the values of the fixed variables.

objective = extract_objective(
    objective::JuMP.AffExpr,
    x::Vector{Float64},
    index_map::Dict{Int64, Int64},
    fixed_variables::Dict{MOI.VariableIndex, Float64}
)

Convert the objective from a MathOptInterface function into a julia function of x. Supports only linear single-objective functions.

Arguments

• objective::JuMP.AffExpr: the objective function to transform into a julia function.
• x::Vector{Float64}: a vector representing an individual in the metaheuristic population.
• index_map::Dict{Int64, Int64}: a dictionary mapping indices in the MathOptInterface model to indices of x.
• fixed_variables::Dict{MOI.VariableIndex, Float64}: a dictionary containing the values of the fixed variables.

extract_variables(model::JuMP.Model)

Retrieve the variables and their solution values from a JuMP model.

result = generate_alternatives!(
  model::JuMP.Model,
  optimality_gap::Float64,
  n_alternatives::Int64;
  metric::Distances.Metric = SqEuclidean(),
  selected_variables::Vector{VariableRef} = []
)

Generate n_alternatives solutions to model which are as distant from the optimum and each other, but with a maximum optimality_gap, using optimisation.

Arguments

• model::JuMP.Model: a solved JuMP model for which alternatives are generated.
• optimality_gap::Float64: the maximum percentage deviation (>=0) an alternative may have compared to the optimal solution.
• n_alternatives: the number of alternative solutions sought.
• metric::Distances.Metric=SqEuclidean(): the metric used to maximise the difference between alternatives and the optimal solution.
• fixed_variables::Vector{VariableRef}=[]: a subset of all variables of model that are not allowed to be changed when seeking for alternatives.

result = generate_alternatives(
  model::JuMP.Model,
  optimality_gap::Float64,
  n_alternatives::Int64,
  metaheuristic_algorithm::Metaheuristics.Algorithm;
  metric::Distances.Metric = SqEuclidean(),
  selected_variables::Vector{VariableRef} = []
)

Generate n_alternatives solutions to model which are as distant from the optimum and each other, but with a maximum optimality_gap, using a metaheuristic algorithm.

Arguments

• model::JuMP.Model: a solved JuMP model for which alternatives are generated.
• optimality_gap::Float64: the maximum percentage deviation (>=0) an alternative may have compared to the optimal solution.
• n_alternatives: the number of alternative solutions sought.
• metaheuristic_algorithm::Metaheuristics.Algorithm: algorithm used to search for alternative solutions.
• metric::Distances.Metric=SqEuclidean(): the metric used to maximise the difference between alternatives and the optimal solution.
• fixed_variables::Vector{VariableRef}=[]: a subset of all variables of model that are not allowed to be changed when seeking for alternatives.

result = run_alternative_generating_problem!(
    problem::MetaheuristicProblem
)

Optimise the problem using the specified metaheuristic algorithm and return the result.

update_solutions!(results::AlternativeSolutions, model::JuMP.Model)

Update the set of results AlternativeSolutions with the variable values obtained when solving the JuMP model model.

update_solutions!(results::AlternativeSolutions, model::JuMP.Model)

Update the set of results AlternativeSolutions with the variable values obtained when solving using Metaheuristics.

Arguments

• results::AlternativeSolutions: set of solutions to add a new solution to.
• state::Metaheuristics.State: contains results to metaheuristic solve.
• initial:solution::OrderedDict{VariableRef, Float64}: used to identify the indices of the metaheuristic solution in the JuMP model.
• fixed_variables::Dict{MOI.VariableIndex, Float64}: set of fixed variables and their solution values.
• model::JuMP.Model: original model for which alternative solutions are found.