API Reference

estimate_ensemble(objective_function, neighbor_function, acceptance_probability_function, cooling_function, initial_state; kwargs...)

Estimate a Pareto optimal ensemble of solutions using simulated annealing with Pareto ranking.

The algorithm iteratively generates candidate solutions via neighbor_function, evaluates them with objective_function, and accepts or rejects them based on Pareto rank and a temperature-dependent acceptance probability. Solutions with rank below rank_cutoff are retained in the archive.

Arguments

• objective_function::Function: evaluates a parameter vector and returns an n_objectives × 1 error array.
• neighbor_function::Function: generates a new candidate parameter vector from the current best.
• acceptance_probability_function::Function: (rank_array, temperature) -> Float64 probability of accepting.
• cooling_function::Function: (temperature) -> new_temperature for the annealing schedule.
• initial_state::AbstractVector{<:Real}: starting parameter vector.

Keyword Arguments

• maximum_number_of_iterations::Integer = 20: iterations per temperature level.
• rank_cutoff::Real = 5.0: solutions with Pareto rank ≥ rank_cutoff are pruned from the archive.
• temperature_min::Real = 0.0001: annealing stops when temperature falls below this value.
• show_trace::Bool = true: print iteration and temperature at each accepted step.
• rng::AbstractRNG = Random.default_rng(): random number generator for reproducibility.

Returns

A tuple (error_cache, parameter_cache, pareto_rank_array) where:

• error_cache::Matrix{Float64}: objective values for retained solutions (n_objectives × n_solutions).
• parameter_cache::Matrix{Float64}: parameter vectors for retained solutions (n_params × n_solutions).
• pareto_rank_array::Vector{Float64}: Pareto rank of each retained solution (0 = Pareto optimal).

Example

using Random
rng = MersenneTwister(42)  # for reproducibility
(EC, PC, RA) = estimate_ensemble(
    obj_fn, neighbor_fn, accept_fn, cool_fn, x0;
    rank_cutoff=4.0, maximum_number_of_iterations=40, rng=rng
)

See also rank_function.

rank_function(error_cache) -> Vector{Float64}

Compute the Pareto rank for each solution (column) in error_cache.

The Pareto rank of a solution is the number of other solutions in the archive that dominate it (i.e., are better or equal in all objectives and strictly better in at least one). A rank of 0 means the solution lies on the Pareto front.

Arguments

• error_cache::AbstractMatrix: an n_objectives × n_solutions matrix of objective values (lower is better).

Returns

• rank_array::Vector{Float64}: Pareto rank for each solution.

Example

errors = [1.0 2.0 1.5; 2.0 1.0 1.5]
ranks = rank_function(errors)  # [0.0, 0.0, 1.0]

See also estimate_ensemble.