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.
• maximum_archive_size::Integer = 1000: hard cap on archive size; if exceeded after pruning, only the best-ranked solutions are kept.
• parallel_evaluation::Bool = false: use threaded Pareto ranking. Requires Julia started with multiple threads (julia -t N).

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,
    maximum_archive_size=500
)

See also rank_function.

estimate_ensemble_parallel(objective_function, neighbor_function, acceptance_probability_function, cooling_function, initial_states; kwargs...)

Run multiple independent Pareto simulated annealing chains in parallel, then merge their archives.

Each element of initial_states seeds one chain that runs estimate_ensemble on its own thread. Results are merged into a single archive and re-ranked. This gives near-linear speedup with thread count and better Pareto front coverage from diverse starting points.

Requires Julia started with multiple threads (julia -t N).

Arguments

• objective_function, neighbor_function, acceptance_probability_function, cooling_function: same as estimate_ensemble.
• initial_states::AbstractVector{<:AbstractVector{<:Real}}: one starting parameter vector per chain.

Keyword Arguments

All keyword arguments from estimate_ensemble are supported and forwarded to each chain. The rng kwarg is ignored; each chain gets its own deterministic RNG seeded from rng_seed and the chain index.

• rng_seed::Integer = 42: base seed for per-chain RNG generation.

Returns

Same as estimate_ensemble: (error_cache, parameter_cache, pareto_rank_array) for the merged archive.

Example

starts = [[2.5, 1.5], [1.0, 2.0], [3.0, 1.0], [4.0, 0.5]]
(EC, PC, RA) = estimate_ensemble_parallel(
    obj_fn, neighbor_fn, accept_fn, cool_fn, starts;
    rank_cutoff=4.0, maximum_number_of_iterations=40
)

See also estimate_ensemble.

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.