autoeq-optim 0.5.58

AutoEQ objectives, constraints, and optimizer backends
Documentation
use crate::de::{DEConfig, DEReport};
use std::sync::Arc;

pub(super) fn count_free_dimensions(lower_bounds: &[f64], upper_bounds: &[f64]) -> usize {
    lower_bounds
        .iter()
        .zip(upper_bounds.iter())
        .filter(|(lo, hi)| **hi > **lo)
        .count()
        .max(1)
}

/// Minimum number of DE generations to ensure adequate exploration when
/// the user's `maxeval` is large enough to afford it.
pub(super) const MIN_DE_GENERATIONS: usize = 5000;

pub(super) fn derive_de_budget(
    lower_bounds: &[f64],
    upper_bounds: &[f64],
    population: usize,
    maxeval: usize,
) -> (usize, usize, usize) {
    let n_free = count_free_dimensions(lower_bounds, upper_bounds);
    let desired_population = population.max(1).min(maxeval.max(1));
    let pop_multiplier = desired_population.div_ceil(n_free).max(4);
    let population_size = pop_multiplier * n_free;

    // B6 — respect the user's `maxeval` budget. The previous behaviour
    // was `(... / pop_size).max(MIN_DE_GENERATIONS)`, which silently
    // over-spent when `maxeval < MIN_DE_GENERATIONS * population_size`
    // (e.g. `maxeval=500 population=500` produced 5000 generations,
    // ~2.5 M evals — ten times the user-specified budget). We now
    // only apply the floor when the user's budget can actually afford
    // it; otherwise we run the computed number of generations and log
    // a warning so QA / benchmark runs can see the disagreement.
    let computed = maxeval.saturating_sub(population_size) / population_size;
    let budget_supports_floor = maxeval >= MIN_DE_GENERATIONS.saturating_mul(population_size);
    let max_iter = if budget_supports_floor {
        computed.max(MIN_DE_GENERATIONS)
    } else {
        // The `.max(1)` guarantees at least one generation runs so the
        // optimiser produces a result. A second cap by
        // `maxeval / population_size` prevents the total eval count
        // (initial population + N generations) from drifting past the
        // user's budget when `computed == 0` (i.e. maxeval ≤ pop_size).
        let budget_generations = maxeval / population_size.max(1);
        let capped = computed.max(1).min(budget_generations.max(1));
        log::warn!(
            "DE maxeval={} with population_size={} is below MIN_DE_GENERATIONS × pop = {}. \
             Running {} generations (≈{} evals) instead of the usual {} floor — expect \
             degraded convergence. Increase maxeval to {} or more to regain full exploration.",
            maxeval,
            population_size,
            MIN_DE_GENERATIONS.saturating_mul(population_size),
            capped,
            capped
                .saturating_mul(population_size)
                .saturating_add(population_size),
            MIN_DE_GENERATIONS,
            MIN_DE_GENERATIONS.saturating_mul(population_size),
        );
        capped
    };
    (pop_multiplier, population_size, max_iter)
}

/// Register a nonlinear inequality constraint with the DE config.
///
/// This helper reduces boilerplate when adding constraints to DE optimization.
/// The constraint is feasible when the constraint function returns <= 0.
///
/// # Type Parameters
/// * `T` - Constraint data type (must be Clone + Send + Sync + 'static)
/// * `F` - Constraint function type
pub(super) fn register_de_constraint<T, F>(config: &mut DEConfig, constraint_fn: F, data: T)
where
    T: Send + Sync + 'static,
    F: Fn(&[f64], Option<&mut [f64]>, &T) -> f64 + Send + Sync + 'static,
{
    config.penalty_ineq.push((
        Arc::new(move |x| {
            constraint_fn(
                x.as_slice().expect("DE candidates are contiguous"),
                None,
                &data,
            )
        }),
        1e3,
    ));
}

/// Process DE optimization results
///
/// Copies optimized parameters back to input array and formats status message.
///
/// # Arguments
/// * `x` - Mutable parameter array to update with optimized values
/// * `result` - DE optimization result containing optimal parameters and status
/// * `algo_name` - Algorithm name for status message formatting
///
/// # Returns
/// Result tuple with (status_message, objective_value)
pub fn process_de_results(
    x: &mut [f64],
    result: DEReport,
    algo_name: &str,
) -> Result<(String, f64), (String, f64)> {
    // Copy results back to input array
    if result.x.len() == x.len() {
        for (i, &value) in result.x.iter().enumerate() {
            x[i] = value;
        }
    }

    let status = if result.success {
        format!("AutoEQ {}: {}", algo_name, result.message)
    } else {
        format!("AutoEQ {}: {} (not converged)", algo_name, result.message)
    };

    Ok((status, result.fun))
}