Reference

const METHODDISPATCH shows the mapping of method symbols to their corresponding update functions for the modelling-for-generating-alternatives problem. It is used to dynamically select the appropriate function based on the method specified in the `createalternativegeneratingproblem!` function.

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.

DWV_initial!(
    model::JuMP.Model,
    variables::AbstractArray{T,N},
    fixed_variables::Vector{VariableRef};
    weights::Vector{Float64} = zeros(length(variables)),
    metric::Distances.SemiMetric = SqEuclidean(),
    old_objective::AffExpr = JuMP.objective_function(model),
) where {T<:Union{VariableRef,AffExpr},N}

Initialize the objective of a JuMP model using the Directionally Weighted Variables method to generate alternative solutions. This function sets a new objective that minimizes the weighted sum of the decision variables, where weights are uniformly chosen between -1 and 1, based on the original objective function. Fixed variables are locked at their optimal values.

Arguments

• model::JuMP.Model: a solved JuMP model whose objective is to be redefined for alternative generation.
• variables::AbstractArray{T,N}: the variables involved in the objective, typically a vector or matrix of VariableRefs or AffExprs.
• fixed_variables::Vector{VariableRef}: variables to be fixed at their current values to avoid changes in alternatives.
• weights::Vector{Float64}: optional vector of weights for each variable; will be internally overwritten based on variable values.
• metric::Distances.SemiMetric: unused in this method (included for consistency with other alternative generation methods).
• old_objective::AffExpr: the original objective function of the model, used to determine variable weights.

Behavior

• Variables are randomly minimized or maximized, based on the original objective function.
• Fixed variables are frozen at their optimal values using fix(...).
• The objective is set to minimize the weighted sum of the variables, encouraging sparsity or deviation from the original.

DWV_update!(
    model::JuMP.Model,
    variables::AbstractArray{T,N},
    weights::Vector{Float64}
) where {T<:Union{VariableRef,AffExpr},N}

Dist_initial!(
    model::JuMP.Model,
    variables::AbstractArray{T,N},
    fixed_variables::Vector{VariableRef};
    weights::Vector{Float64} = zeros(length(variables)),
    metric::Distances.SemiMetric = SqEuclidean(),
) where {T<:Union{VariableRef,AffExpr},N}

Initialize a JuMP model's objective to maximize the distance between the current solution and a reference solution, based on a specified metric.

This function is typically used in the context of generating diverse solutions (alternatives) to an optimization problem by first defining a distance-based objective that measures how different a new solution is from an existing (optimal) one.

Arguments

• model::JuMP.Model: a JuMP model that has been previously solved.
• variables::AbstractArray{T,N}: the variables of the model to consider in the distance computation.
• fixed_variables::Vector{VariableRef}: a subset of all variables of model that are not allowed to be changed when seeking for alternatives.
• weights::Vector{Float64}: optional weights to influence the distance calculation (currently not used directly but reserved for extensions).
• metric::Distances.SemiMetric: the distance metric used to compute dissimilarity (default is squared Euclidean distance).

Behavior

• Extracts the current solution values of variables.
• Sets the model's objective to maximize the distance between the current variable values and the solution.
• Changes the model's objective sense to Max.

Dist_update!(
    model::JuMP.Model,
    variables::AbstractArray{T,N};
    weights::Vector{Float64} = zeros(length(variables)),
    metric::Distances.SemiMetric = Cityblock(),
) where {T<:Union{VariableRef,AffExpr},N}

Update a JuMP model's objective function to include an additional distance term for generating multiple diverse alternatives (as in Modeling to Generate Alternatives).

This function builds upon a previously defined objective by incrementally adding a distance term between the current solution and a new reference solution. It is typically used after Dist_initial! or a prior call to MGA_Dist_update!.

Arguments

• model::JuMP.Model: the JuMP model being updated to generate further alternatives.
• variables::AbstractArray{T,N}: the variables to consider in the distance computation.
• weights::Vector{Float64}: optional weights for the distance metric (currently not directly used).
• metric::Distances.SemiMetric: the distance metric used to compute dissimilarity (default is Cityblock distance).

Behavior

• Evaluates the current objective function to retrieve the cumulative distance so far.
• Computes the distance between the current variable values and their previous optimal values.
• Updates the objective function to maximize the sum of the cumulative and new distances.
• Resets the model's objective sense to Max.

HSJ_initial!(
    model::JuMP.Model,
    variables::AbstractArray{T,N},
    fixed_variables::Vector{VariableRef};
    weights::Vector{Float64} = zeros(length(variables)),
    metric::Distances.SemiMetric = SqEuclidean(),
) where {T<:Union{VariableRef,AffExpr}, N}

Initialize the objective of a JuMP model using the HSJ (Hop-Skip-Jump) method to generate alternative solutions.

This function sets a new objective that minimizes the weighted sum of the decision variables, where weights are based on the sign (non-zero value) of the original optimal solution. Fixed variables are locked at their optimal values.

Arguments

• model::JuMP.Model: a solved JuMP model whose objective is to be redefined for alternative generation.
• variables::AbstractArray{T,N}: the variables involved in the objective, typically a vector or matrix of VariableRefs or AffExprs.
• fixed_variables::Vector{VariableRef}: variables to be fixed at their current values to avoid changes in alternatives.
• weights::Vector{Float64}: optional vector of weights for each variable; will be internally overwritten based on variable values.
• metric::Distances.SemiMetric: unused in this method (included for consistency with other alternative generation methods).

Behavior

• Variables that are zero in the original solution receive weight 0; others receive weight 1.
• Fixed variables are frozen at their optimal values using fix(...).
• The objective is set to minimize the weighted sum of the variables, encouraging sparsity or deviation from the original.

HSJ_update!(
    model::JuMP.Model,
    variables::AbstractArray{T,N};
    weights::Vector{Float64} = zeros(length(variables)),
    metric::Distances.SemiMetric = SqEuclidean(),
) where {T<:Union{VariableRef,AffExpr}, N}

Update the objective of a JuMP model using the HSJ method to generate the next alternative solution.

This function redefines the objective based on the current optimal solution of the model, using weights determined by the sign of each variable's value (non-zero implies weight 1).

Arguments

• model::JuMP.Model: the JuMP model to be updated.
• variables::AbstractArray{T,N}: the decision variables involved in the updated objective.
• weights::Vector{Float64}: optional vector of weights; will be overwritten based on current variable values.
• metric::Distances.SemiMetric: unused in this method (included for interface consistency).

Behavior

• Variables with a zero value receive weight 0; all others receive weight 1.
• A new objective is set: minimize the weighted sum of the variables.
• This function does not re-fix any variables; it is typically called iteratively after HSJ_initial!.

Min_Max_Variables_initial!(
    model::JuMP.Model,
    variables::AbstractArray{T,N},
    fixed_variables::Vector{VariableRef};
    weights::Vector{Float64} = zeros(length(variables)),
    metric::Distances.SemiMetric = SqEuclidean(),
) where {T<:Union{VariableRef,AffExpr}, N}

Initialize the objective of a JuMP model using the Min/Max Variables method to generate alternative solutions. This function sets a new objective that minimizes the weighted sum of the decision variables, where weights are randomized between -1, 0 and 1. Fixed variables are locked at their optimal values.

Arguments

• model::JuMP.Model: a solved JuMP model whose objective is to be redefined for alternative generation.
• variables::AbstractArray{T,N}: the variables involved in the objective, typically a vector or matrix of VariableRefs or AffExprs.
• fixed_variables::Vector{VariableRef}: variables to be fixed at their current values to avoid changes in alternatives.
• weights::Vector{Float64}: optional vector of weights for each variable; will be internally overwritten based on variable values.
• metric::Distances.SemiMetric: unused in this method (included for consistency with other alternative generation methods).

Behavior

• Variables are randomly minimized or maximized.
• Fixed variables are frozen at their optimal values using fix(...).
• The objective is set to minimize the weighted sum of the variables, encouraging sparsity or deviation from the original.

Min_Max_Variables_update!(
    model::JuMP.Model,
    variables::AbstractArray{T,N};
    weights::Vector{Float64} = zeros(length(variables)),
    metric::Distances.SemiMetric = SqEuclidean(),
) where {T<:Union{VariableRef,AffExpr}, N}

Update the objective of a JuMP model using the Min/Max Variables method to generate the next alternative solution. Update the weights randomly between -1, 0 and 1.

Arguments

• model::JuMP.Model: the JuMP model to be updated.
• variables::AbstractArray{T,N}: the decision variables involved in the updated objective.
• weights::Vector{Float64}: optional vector of weights; will be overwritten based on current variable values.
• metric::Distances.SemiMetric: unused in this method (included for interface consistency).

Behavior

• Variables are randomly minimized or maximized.
• A new objective is set: minimize the weighted sum of the variables.
• This function does not re-fix any variables; it is typically called iteratively after Min_Max_Variables_initial!.

Random_Vector_initial!(
    model::JuMP.Model,
    variables::AbstractArray{T,N},
    fixed_variables::Vector{VariableRef};
    weights::Vector{Float64} = zeros(length(variables)),
    metric::Distances.SemiMetric = SqEuclidean(),
) where {T<:Union{VariableRef,AffExpr}, N}

Initialize the objective of a JuMP model using the Min/Max Variables method to generate alternative solutions. This function sets a new objective that minimizes the weighted sum of the decision variables, where weights are uniformly chosen between -1 and 1. Fixed variables are locked at their optimal values.

Arguments

• model::JuMP.Model: a solved JuMP model whose objective is to be redefined for alternative generation.
• variables::AbstractArray{T,N}: the variables involved in the objective, typically a vector or matrix of VariableRefs or AffExprs.
• fixed_variables::Vector{VariableRef}: variables to be fixed at their current values to avoid changes in alternatives.
• weights::Vector{Float64}: optional vector of weights for each variable; will be internally overwritten based on variable values.
• metric::Distances.SemiMetric: unused in this method (included for consistency with other alternative generation methods).

Behavior

• Variables are randomly minimized or maximized.
• Fixed variables are frozen at their optimal values using fix(...).
• The objective is set to minimize the weighted sum of the variables, encouraging sparsity or deviation from the original.

Random_Vector_update!(
    model::JuMP.Model,
    variables::AbstractArray{T,N};
    weights::Vector{Float64} = zeros(length(variables)),
    metric::Distances.SemiMetric = SqEuclidean(),
) where {T<:Union{VariableRef,AffExpr}, N}

Update the objective of a JuMP model using the Min/Max Variables method to generate the next alternative solution. Update the weights uniformly chosen between -1 and 1.

Arguments

• model::JuMP.Model: the JuMP model to be updated.
• variables::AbstractArray{T,N}: the decision variables involved in the updated objective.
• weights::Vector{Float64}: optional vector of weights; will be overwritten based on current variable values.
• metric::Distances.SemiMetric: unused in this method (included for interface consistency).

Behavior

• Variables are randomly minimized or maximized.
• A new objective is set: minimize the weighted sum of the variables.
• This function does not re-fix any variables; it is typically called iteratively after Random_Vector_initial!.

Spores_initial!(
    model::JuMP.Model,
    variables::AbstractArray{T,N},
    fixed_variables::Vector{VariableRef};
    weights::Vector{Float64} = zeros(length(variables)),
    metric::Distances.SemiMetric = SqEuclidean(),
) where {T<:Union{VariableRef,AffExpr}, N}

Initialize the objective of a JuMP model using the Spores method to generate alternative solutions. This function sets a new objective that minimizes the weighted sum of the decision variables, where weights are based on the variable value of the original optimal solution. Fixed variables are locked at their optimal values. For this method to work the upper bound of the variables must be set.

Arguments

• model::JuMP.Model: a solved JuMP model whose objective is to be redefined for alternative generation.
• variables::AbstractArray{T,N}: the variables involved in the objective, typically a vector or matrix of VariableRefs or AffExprs.
• fixed_variables::Vector{VariableRef}: variables to be fixed at their current values to avoid changes in alternatives.
• weights::Vector{Float64}: optional vector of weights for each variable; will be internally overwritten based on variable values.
• metric::Distances.SemiMetric: unused in this method (included for consistency with other alternative generation methods).

Behavior

• Variables are updated based on the potential value that they could have had.
• Fixed variables are frozen at their optimal values using fix(...).
• The objective is set to minimize the weighted sum of the variables, encouraging sparsity or deviation from the original.

Spores_update!(
    model::JuMP.Model,
    variables::AbstractArray{T,N};
    weights::Vector{Float64} = zeros(length(variables)),
    metric::Distances.SemiMetric = SqEuclidean(),
) where {T<:Union{VariableRef,AffExpr}, N}

Update the objective of a JuMP model using the Spores method to generate the next alternative solution. This function redefines the objective based on the current optimal solution of the model, updating the weights with respect to the current variable values.

Arguments

• model::JuMP.Model: the JuMP model to be updated.
• variables::AbstractArray{T,N}: the decision variables involved in the updated objective.
• weights::Vector{Float64}: optional vector of weights; will be overwritten based on current variable values.
• metric::Distances.SemiMetric: unused in this method (included for interface consistency).

Behavior

• Variables with are updated based on the previously optimal solution.
• A new objective is set: minimize the weighted sum of the variables.
• This function does not re-fix any variables; it is typically called iteratively after Spores_initial!.

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_generating_problem!(
  model::JuMP.Model,
  optimality_gap::Float64,
  fixed_variables::Vector{VariableRef},
  variables::AbstractArray{T,N},
  weights::Vector{Float64};
  method::Symbol = :HSJ,
  metric::Distances.SemiMetric = SqEuclidean(),
) where {T<:Union{VariableRef,AffExpr},N}

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.
• fixed_variables::Vector{VariableRef}=[]: a subset of all variables of model that are not allowed to be changed when seeking for alternatives.
• variables::AbstractArray{T,N}: the variables of model for which are considered when generating alternatives.
• weights::Vector{Float64}: a vector of weights used to update the objective function.
• method::Symbol = :HSJ: the method used to model the problem for generating alternatives.
• metric::Distances.SemiMetric = SqEuclidean(): the metric used to maximise the difference between alternatives and the optimal solution.

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.

results = generatealternatives!( model::JuMP.Model, optimalitygap::Float64, variables::AbstractArray{T,N}, nalternatives::Int64; modelingmethod::Symbol = :MaxDistance, metric::Distances.SemiMetric = SqEuclidean(), fixedvariables::Vector{VariableRef} = VariableRef[], ) where {T<:Union{VariableRef,AffExpr},N} 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.
• variables::AbstractArray{T,N}: the variables of model for which are considered when generating alternatives.
• n_alternatives: the number of alternative solutions sought.
• modeling_method::Symbol = :Max_Distance: the method used to model the problem for generating alternatives.
• 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_objective_function!(
    model::JuMP.Model,
    variables::AbstractArray{T,N};
    weights::Vector{Float64} = zeros(length(variables)),
    method::Symbol = :HSJ,
    metric::Distances.SemiMetric = SqEuclidean()) where {T<:Union{VariableRef,AffExpr},N}
)

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

Arguments

• model::JuMP.Model: a solved JuMP model for which alternatives are generated.
• variables::AbstractArray{T,N}: the variables of model for which are considered when generating alternatives.
• weights::Vector{Float64}: a vector of weights used to update the objective function.
• method::Symbol = :HSJ: the method used to model the problem for generating alternatives.
• metric::Distances.SemiMetric = SqEuclidean(): the metric used to maximise the difference between alternatives and the optimal solution.

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.