autoeq-optim 0.5.58

AutoEQ objectives, constraints, and optimizer backends
Documentation
use super::compute::compute_epa;
use super::compute::compute_epa_multichannel_normalized;
use super::compute::compute_epa_normalized;
use super::epa::epa_flatness;
use super::epa::epa_loss;
use super::epa::epa_loss_normalized;
use super::epa_config::EpaConfig;
use super::temporal::temporal_ir_masking_metrics;
use super::temporal::temporal_masking_penalty;
use super::temporal_masking_config::TemporalMaskingConfig;
use super::types::EpaChannelRole;
use super::types::TemporalMaskingMode;
use super::types::TemporalMaskingProfile;
use super::types::infer_epa_channel_role;

fn make_flat_response(level_db: f64) -> (Vec<f64>, Vec<f64>) {
    let n = 1000;
    let freqs: Vec<f64> = (0..n)
        .map(|i| 20.0 + (16000.0 - 20.0) * i as f64 / n as f64)
        .collect();
    let spl = vec![level_db; n];
    (freqs, spl)
}

fn make_harsh_response() -> (Vec<f64>, Vec<f64>) {
    let n = 1000;
    let freqs: Vec<f64> = (0..n)
        .map(|i| 20.0 + (16000.0 - 20.0) * i as f64 / n as f64)
        .collect();
    let spl: Vec<f64> = freqs
        .iter()
        .map(|&f| if f > 5000.0 { 85.0 } else { 75.0 })
        .collect();
    (freqs, spl)
}

fn make_peaked_response() -> (Vec<f64>, Vec<f64>) {
    let n = 1000;
    let freqs: Vec<f64> = (0..n)
        .map(|i| 20.0 + (16000.0 - 20.0) * i as f64 / n as f64)
        .collect();
    let mut spl: Vec<f64> = vec![70.0; n];
    // Add multiple prominent peaks that create roughness and imbalance.
    // Wide enough windows (~20 Hz) to hit multiple bins at ~32 Hz spacing.
    // Peaks at various frequencies including high-freq to raise sharpness.
    for (i, &f) in freqs.iter().enumerate() {
        if (f - 300.0).abs() < 20.0
            || (f - 370.0).abs() < 20.0
            || (f - 5000.0).abs() < 100.0
            || (f - 8000.0).abs() < 100.0
        {
            spl[i] = 90.0; // 20 dB peaks
        }
    }
    (freqs, spl)
}

#[test]
fn test_epa_score_flat_response() {
    let (freqs, spl) = make_flat_response(75.0);
    let config = EpaConfig::default();
    let score = compute_epa(&freqs, &spl, &config);

    assert!(
        score.evaluation > 6.0,
        "Flat response should have high evaluation, got {}",
        score.evaluation
    );
    assert!(
        score.activity < 2.0,
        "Flat response should have low activity, got {}",
        score.activity
    );
}

#[test]
fn test_epa_score_harsh_response() {
    let (freqs_flat, spl_flat) = make_flat_response(75.0);
    let (freqs_harsh, spl_harsh) = make_harsh_response();
    let config = EpaConfig::default();

    let flat_score = compute_epa(&freqs_flat, &spl_flat, &config);
    let harsh_score = compute_epa(&freqs_harsh, &spl_harsh, &config);

    assert!(
        harsh_score.evaluation < flat_score.evaluation,
        "Harsh response (eval={}) should have lower evaluation than flat (eval={})",
        harsh_score.evaluation,
        flat_score.evaluation
    );
    assert!(
        harsh_score.sharpness_acum > flat_score.sharpness_acum,
        "Harsh response (sharp={}) should have higher sharpness than flat (sharp={})",
        harsh_score.sharpness_acum,
        flat_score.sharpness_acum
    );
}

#[test]
fn test_epa_loss_flat_is_low() {
    let (freqs, spl) = make_flat_response(75.0);
    let config = EpaConfig::default();
    let loss = epa_loss(&freqs, &spl, &config, 0.0);
    assert!(
        loss < 2.0,
        "Flat response with zero flatness loss should have low EPA loss, got {loss}"
    );
}

#[test]
fn test_epa_transfer_descriptors_do_not_change_optimizer_loss() {
    let (freqs_flat, spl_flat) = make_flat_response(75.0);
    let (freqs_peaked, spl_peaked) = make_peaked_response();
    let config = EpaConfig::default();

    let flat_loss = epa_loss(&freqs_flat, &spl_flat, &config, 0.0);
    let peaked_loss = epa_loss(&freqs_peaked, &spl_peaked, &config, 0.0);

    assert_eq!(peaked_loss, flat_loss);
}

#[test]
fn test_epa_config_default() {
    let config = EpaConfig::default();
    assert_eq!(config.listening_level_phon, 75.0);
    assert_eq!(config.target_sharpness, 1.2);
    assert_eq!(config.max_roughness, 0.5);
    assert_eq!(config.evaluation_weight, 0.6);
    assert_eq!(config.potency_weight, 0.2);
    assert_eq!(config.activity_weight, 0.2);
    // Weights should sum to 1.0
    let total = config.evaluation_weight + config.potency_weight + config.activity_weight;
    assert!(
        (total - 1.0).abs() < 1e-10,
        "EPA weights should sum to 1.0, got {total}"
    );
}

#[test]
fn test_compute_epa_normalized_matches_absolute_equivalent() {
    // A curve normalized around 0 dB plus a 75 phon listening level should
    // produce the same EpaScore as the equivalent absolute 75 dB SPL curve.
    let (freqs, spl_abs) = make_flat_response(75.0);
    let spl_rel: Vec<f64> = spl_abs.iter().map(|v| v - 75.0).collect();

    let config = EpaConfig {
        listening_level_phon: 75.0,
        ..EpaConfig::default()
    };

    let score_abs = compute_epa(&freqs, &spl_abs, &config);
    let score_rel = compute_epa_normalized(&freqs, &spl_rel, &config);

    assert!(
        (score_abs.total_loudness_sone - score_rel.total_loudness_sone).abs() < 1e-9,
        "normalized path should match absolute path, got abs={} rel={}",
        score_abs.total_loudness_sone,
        score_rel.total_loudness_sone
    );
    assert!((score_abs.sharpness_acum - score_rel.sharpness_acum).abs() < 1e-9);
    assert!((score_abs.roughness - score_rel.roughness).abs() < 1e-9);
    assert!((score_abs.loudness_balance - score_rel.loudness_balance).abs() < 1e-9);
}

#[test]
fn test_normalized_calibration_prevents_silent_floor() {
    // A level-relative flat curve (~0 dB everywhere) only represents
    // near-silence when calibrated at 0 phon. The `_normalized` variant
    // denormalizes against `listening_level_phon` and must produce a
    // non-trivial total loudness at the configured listening level.
    let (freqs, _) = make_flat_response(0.0);
    let spl_rel = vec![0.0_f64; freqs.len()];

    let config = EpaConfig {
        listening_level_phon: 75.0,
        ..EpaConfig::default()
    };

    let silent_floor_config = EpaConfig {
        listening_level_phon: 0.0,
        ..config.clone()
    };

    let raw_score = compute_epa(&freqs, &spl_rel, &silent_floor_config);
    let calibrated_score = compute_epa_normalized(&freqs, &spl_rel, &config);

    // Zero-level calibration should be at or near the silent floor.
    assert!(
        raw_score.total_loudness_sone < 0.5,
        "0 phon normalized input should be near-silent, got {}",
        raw_score.total_loudness_sone
    );
    // Calibrated path should show meaningful loudness (flat 75 dB ≈ 30+ sone).
    assert!(
        calibrated_score.total_loudness_sone > 5.0,
        "calibrated 75 phon flat curve should have meaningful loudness, got {}",
        calibrated_score.total_loudness_sone
    );
}

#[test]
fn test_epa_loss_normalized_matches_absolute_equivalent() {
    // Same invariant as the compute_epa test: normalized path with the
    // listening-level offset should match the absolute path exactly.
    let (freqs, spl_abs) = make_flat_response(75.0);
    let spl_rel: Vec<f64> = spl_abs.iter().map(|v| v - 75.0).collect();

    let config = EpaConfig {
        listening_level_phon: 75.0,
        ..EpaConfig::default()
    };

    let loss_abs = epa_loss(&freqs, &spl_abs, &config, 0.25);
    let loss_rel = epa_loss_normalized(&freqs, &spl_rel, &config, 0.25);
    assert!(
        (loss_abs - loss_rel).abs() < 1e-12,
        "epa_loss_normalized should match epa_loss on denormalized input, got abs={} rel={}",
        loss_abs,
        loss_rel
    );
}

#[test]
fn temporal_masking_penalty_rewards_cutting_audible_modes() {
    let freqs = vec![50.0, 100.0, 200.0];
    let modes = vec![TemporalMaskingMode {
        frequency: 100.0,
        q: 30.0,
        prominence_db: 9.0,
        temporal_severity_db: 6.0,
    }];
    let cfg = TemporalMaskingConfig::default();

    let no_eq = vec![0.0, 0.0, 0.0];
    let cut = vec![0.0, -6.0, 0.0];
    let boost = vec![0.0, 3.0, 0.0];

    let no_eq_penalty = temporal_masking_penalty(&freqs, &no_eq, &modes, &cfg);
    let cut_penalty = temporal_masking_penalty(&freqs, &cut, &modes, &cfg);
    let boost_penalty = temporal_masking_penalty(&freqs, &boost, &modes, &cfg);

    assert!(cut_penalty < no_eq_penalty);
    assert!(boost_penalty > no_eq_penalty);
}

#[test]
fn temporal_masking_profile_changes_audibility() {
    let freqs = vec![50.0, 100.0, 200.0];
    let peq = vec![0.0, 0.0, 0.0];
    let modes = vec![TemporalMaskingMode {
        frequency: 100.0,
        q: 30.0,
        prominence_db: 9.0,
        temporal_severity_db: 6.0,
    }];
    let transient = TemporalMaskingConfig {
        profile: TemporalMaskingProfile::Transient,
        ..Default::default()
    };
    let sustained = TemporalMaskingConfig {
        profile: TemporalMaskingProfile::Sustained,
        ..Default::default()
    };

    assert!(
        temporal_masking_penalty(&freqs, &peq, &modes, &transient)
            > temporal_masking_penalty(&freqs, &peq, &modes, &sustained)
    );
}

#[test]
fn temporal_ir_masking_detects_pre_ringing() {
    let cfg = TemporalMaskingConfig {
        pre_mask_ms: 0.0,
        post_mask_ms: 0.0,
        ..Default::default()
    };
    let clean = vec![0.0, 0.0, 1.0, 0.0, 0.0];
    let ringing = vec![0.35, 0.0, 1.0, 0.0, 0.0];

    let clean_metrics = temporal_ir_masking_metrics(&clean, 1000.0, &cfg).unwrap();
    let ringing_metrics = temporal_ir_masking_metrics(&ringing, 1000.0, &cfg).unwrap();

    assert!(clean_metrics.penalty <= 1e-12);
    assert!(ringing_metrics.pre_ringing_audible_db > -10.0);
    assert!(ringing_metrics.penalty > clean_metrics.penalty);
}

#[test]
fn temporal_ir_masking_applies_near_transient_pre_masking() {
    let cfg = TemporalMaskingConfig {
        pre_mask_ms: 3.0,
        post_mask_ms: 0.0,
        ..Default::default()
    };
    let near = vec![0.0, 0.3, 1.0, 0.0, 0.0, 0.0, 0.0];
    let far = vec![0.3, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0];

    let near_metrics = temporal_ir_masking_metrics(&near, 1000.0, &cfg).unwrap();
    let far_metrics = temporal_ir_masking_metrics(&far, 1000.0, &cfg).unwrap();

    assert!(far_metrics.pre_ringing_audible_db > near_metrics.pre_ringing_audible_db);
}

#[test]
fn multichannel_epa_increases_loudness_for_stereo_programme() {
    let (freqs, spl_rel) = make_flat_response(0.0);
    let config = EpaConfig::default();
    let mono =
        compute_epa_multichannel_normalized(&freqs, &[(&spl_rel, EpaChannelRole::Main)], &config)
            .unwrap();
    let stereo = compute_epa_multichannel_normalized(
        &freqs,
        &[
            (&spl_rel, EpaChannelRole::Main),
            (&spl_rel, EpaChannelRole::Main),
        ],
        &config,
    )
    .unwrap();

    assert!(
        stereo.total_loudness_sone > mono.total_loudness_sone,
        "two equal programme channels should be louder than one"
    );
}

#[test]
fn multichannel_epa_excludes_lfe_role() {
    let (freqs, spl_rel) = make_flat_response(0.0);
    let config = EpaConfig::default();
    let main =
        compute_epa_multichannel_normalized(&freqs, &[(&spl_rel, EpaChannelRole::Main)], &config)
            .unwrap();
    let with_lfe = compute_epa_multichannel_normalized(
        &freqs,
        &[
            (&spl_rel, EpaChannelRole::Main),
            (&spl_rel, EpaChannelRole::Lfe),
        ],
        &config,
    )
    .unwrap();

    assert!(
        (main.total_loudness_sone - with_lfe.total_loudness_sone).abs() < 1e-9,
        "LFE should not contribute to BS.1770-style aggregate EPA loudness"
    );
}

#[test]
fn channel_role_inference_covers_common_surround_and_lfe_names() {
    assert_eq!(infer_epa_channel_role("left"), EpaChannelRole::Main);
    assert_eq!(
        infer_epa_channel_role("surround_left"),
        EpaChannelRole::Surround
    );
    assert_eq!(infer_epa_channel_role("Ls"), EpaChannelRole::Surround);
    assert_eq!(infer_epa_channel_role("LFE"), EpaChannelRole::Lfe);
    assert_eq!(infer_epa_channel_role("subwoofer"), EpaChannelRole::Lfe);
}

#[test]
fn epa_flatness_uses_config_blend() {
    // At the extremes of the blend, `epa_flatness` should equal the
    // pure `erb_weighted_loss` / `band_weighted_loss` helpers.
    use crate::loss::enhanced_weights::{band_weighted_loss, erb_weighted_loss};
    let freqs = ndarray::Array1::from(vec![100.0, 1000.0, 5000.0, 10000.0]);
    let err = ndarray::Array1::from(vec![1.0, 1.0, 1.0, 1.0]);

    let mut cfg = EpaConfig {
        flatness_erb_weight: 1.0,
        flatness_band_weight: 0.0,
        ..Default::default()
    };
    let got_erb = epa_flatness(&freqs, &err, 20.0, 20000.0, &cfg);
    let expected_erb = erb_weighted_loss(&freqs, &err);
    assert!(
        (got_erb - expected_erb).abs() < 1e-9,
        "pure ERB blend should equal erb_weighted_loss, got {got_erb} vs {expected_erb}"
    );

    cfg.flatness_erb_weight = 0.0;
    cfg.flatness_band_weight = 1.0;
    let got_band = epa_flatness(&freqs, &err, 20.0, 20000.0, &cfg);
    let expected_band = band_weighted_loss(&freqs, &err, &cfg.flatness_band_weights);
    assert!(
        (got_band - expected_band).abs() < 1e-9,
        "pure band blend should equal band_weighted_loss, got {got_band} vs {expected_band}"
    );
}

#[test]
fn epa_flatness_empty_range_returns_infinity() {
    let freqs = ndarray::Array1::from(vec![100.0, 200.0, 500.0]);
    let err = ndarray::Array1::from(vec![1.0, 1.0, 1.0]);
    let cfg = EpaConfig::default();
    assert!(epa_flatness(&freqs, &err, 5000.0, 10000.0, &cfg).is_infinite());
}