1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
use super::super::loss::{
AsymmetricLossConfig, DriversLossData, HeadphoneLossData, LossType, SpeakerLossData,
};
use super::super::x2peq::x2spl;
use super::de::optimize_filters_autoeq_with_callback;
use super::loss::{
AsymmetricStrategy, DriversMode, DriversStrategy, EpaStrategy, FlatStrategy,
HeadphoneScoreStrategy, Objective, ObjectiveContext, SpeakerScoreStrategy,
};
use super::penalty_mode::PenaltyMode;
use super::smoothness_penalty_config::SmoothnessPenaltyConfig;
use super::types::MultiObjectiveData;
use super::types::OptimProgressCallback;
use crate::Curve;
use crate::PeqModel;
use ndarray::Array1;
use std::sync::{Arc, OnceLock};
/// Data structure for holding objective function parameters
///
/// This struct contains all the data needed to compute the objective function
/// for filter optimization.
#[derive(Clone)]
pub struct ObjectiveData {
/// Lazily prepared fixed-grid loss kernel shared by all clones.
///
/// This is public only to preserve construction through historical struct
/// literals. Callers should initialize it with `Default::default()` and
/// otherwise treat it as an implementation detail.
#[doc(hidden)]
pub prepared: Arc<OnceLock<super::prepared_objective::PreparedObjective>>,
/// Frequency points for evaluation
pub freqs: Arc<Array1<f64>>,
/// Target spl
pub target: Arc<Array1<f64>>,
/// Target error values
pub deviation: Arc<Array1<f64>>,
/// Sample rate in Hz
pub srate: f64,
#[allow(dead_code)]
/// Minimum spacing between filters in octaves
pub min_spacing_oct: f64,
/// Weight for spacing penalty term
pub spacing_weight: f64,
/// Maximum allowed dB level
pub max_db: f64,
/// Minimum absolute gain for filters
pub min_db: f64,
/// Minimum frequency in Hz for loss function evaluation
pub min_freq: f64,
/// Maximum frequency in Hz for loss function evaluation
pub max_freq: f64,
/// PEQ model that defines the filter structure
pub peq_model: PeqModel,
/// Type of loss function to use
pub loss_type: LossType,
/// Cached strategy object used to evaluate this objective.
///
/// When `None`, [`ObjectiveData::build_objective`] is used as a fallback.
/// Setup code should populate this field so the strategy is built once.
#[allow(dead_code)]
pub objective: Option<Arc<dyn Objective>>,
/// Optional score data for SpeakerScore loss type
pub speaker_score_data: Option<SpeakerLossData>,
/// Optional score data for HeadphoneScore loss type
pub headphone_score_data: Option<HeadphoneLossData>,
/// Input curve for headphone loss (optional)
pub input_curve: Option<Curve>,
/// Optional data for multi-driver crossover optimization
pub drivers_data: Option<DriversLossData>,
/// Fixed crossover frequencies (when not optimizing frequencies)
pub fixed_crossover_freqs: Option<Vec<f64>>,
/// Penalty weights used when the optimizer does not support nonlinear constraints
/// If zero, penalties are disabled and true constraints (if any) are used.
/// Penalty for ceiling constraint
pub penalty_w_ceiling: f64,
/// Penalty for spacing constraint
pub penalty_w_spacing: f64,
/// Penalty for min gain constraint
pub penalty_w_mingain: f64,
/// Integrality constraints - true for integer parameters, false for continuous
pub integrality: Option<Vec<bool>>,
/// Multi-objective data for multi-measurement optimization.
/// When `Some`, `compute_base_fitness` delegates to `compute_multi_objective_fitness`.
pub multi_objective: Option<MultiObjectiveData>,
/// Whether to smooth the error before computing the loss
pub smooth: bool,
/// Smoothing resolution as 1/N octave
pub smooth_n: usize,
/// Frequency-dependent maximum boost envelope for per-filter gain clamping.
/// Each entry is (frequency_hz, max_boost_db). Interpolated in log-frequency.
/// When Some, positive filter gains are clamped before loss evaluation.
pub max_boost_envelope: Option<Vec<(f64, f64)>>,
/// Optional minimum-cut safety envelope.
/// Each entry is (frequency_hz, max_cut_db), where max_cut_db is negative.
/// When Some, negative filter gains are clamped before loss evaluation.
pub min_cut_envelope: Option<Vec<(f64, f64)>>,
/// Experimental EPA diagnostics and active spectral-flatness blend.
///
/// Used only when `loss_type == LossType::Epa`. When `None`, the
/// optimizer falls back to `EpaConfig::default()`.
pub epa_config: Option<crate::loss::epa::score::EpaConfig>,
/// Detected modal ringing data retained for EPA diagnostic compatibility.
///
/// It does not steer optimizer fitness.
pub temporal_masking_modes: Vec<crate::loss::epa::score::TemporalMaskingMode>,
/// Pre-detected frequency problems (usually SSIR / decomposed-correction
/// room modes) to seed the DE optimizer's smart initial-guess
/// generator with.
///
/// Each entry is `(frequency_hz, q, suggested_gain_db)` — the sign of
/// the gain says whether the seed should cut (negative) or boost
/// (positive) the problem. When this list is non-empty,
/// `initial_guess::create_smart_initial_guesses` will use it instead
/// of running its own naive `find_peaks` over the smoothed deviation.
/// Order should be "most important first" (i.e. sorted by
/// `|gain_db|` descending) so that if there are fewer filters than
/// problems the most prominent ones are the ones kept.
///
/// Defaults to empty, which preserves the old behaviour
/// (auto-detected peaks/dips).
pub detected_problems: Vec<(f64, f64, f64)>,
/// Per-frequency dip-suppression mask for
/// [`LossType::SpeakerFlatAsymmetric`].
///
/// `Some(mask)` scales the dip branch of the asymmetric loss toward
/// zero inside detected narrow nulls (see
/// [`crate::roomeq::impulse_analysis::build_null_suppression_mask`]).
/// `None` disables suppression — dips are weighted with the
/// full `bass_dip_weight` / `dip_weight` of the asymmetric config.
/// Must have the same length as `freqs` when provided.
pub null_suppression: Option<Arc<Array1<f64>>>,
/// Peak/dip weights for [`LossType::SpeakerFlatAsymmetric`].
pub asymmetric_loss_config: AsymmetricLossConfig,
/// Optional smoothness regularizer on the correction curve.
/// `None` disables the penalty.
pub smoothness_penalty: Option<SmoothnessPenaltyConfig>,
/// Optional audibility/JND deadband applied to residual errors before
/// spectral objective scoring.
pub audibility_deadband: Option<crate::roomeq::AudibilityDeadbandConfig>,
}
impl ObjectiveData {
pub(crate) fn prepared(&self) -> &super::prepared_objective::PreparedObjective {
self.prepared
.get_or_init(|| super::prepared_objective::PreparedObjective::new(self))
}
/// Build the [`Objective`] strategy that corresponds to the configured
/// [`LossType`] and payload fields.
pub fn build_objective(&self) -> Arc<dyn Objective> {
match self.loss_type {
LossType::SpeakerFlat | LossType::HeadphoneFlat => Arc::new(FlatStrategy),
LossType::SpeakerFlatAsymmetric => Arc::new(AsymmetricStrategy {
config: self.asymmetric_loss_config,
null_suppression: self.null_suppression.clone(),
}),
LossType::SpeakerScore => {
if let Some(ref sd) = self.speaker_score_data {
Arc::new(SpeakerScoreStrategy {
score_data: sd.clone(),
})
} else {
log::error!("speaker score loss requested but score data is missing");
Arc::new(MissingDataStrategy)
}
}
LossType::HeadphoneScore => {
if let Some(ref hd) = self.headphone_score_data {
Arc::new(HeadphoneScoreStrategy { data: hd.clone() })
} else {
log::error!("headphone score loss requested but headphone data is missing");
Arc::new(MissingDataStrategy)
}
}
LossType::DriversFlat => {
if let Some(ref dd) = self.drivers_data {
Arc::new(DriversStrategy {
data: dd.clone(),
mode: DriversMode::Flat,
fixed_crossover_freqs: self.fixed_crossover_freqs.clone(),
})
} else {
log::error!("drivers-flat loss requested but driver data is missing");
Arc::new(MissingDataStrategy)
}
}
LossType::MultiSubFlat => {
if let Some(ref dd) = self.drivers_data {
Arc::new(DriversStrategy {
data: dd.clone(),
mode: DriversMode::MultiSub,
fixed_crossover_freqs: None,
})
} else {
log::error!("multi-sub-flat loss requested but driver data is missing");
Arc::new(MissingDataStrategy)
}
}
LossType::Epa => Arc::new(EpaStrategy {
config: self.epa_config.clone().unwrap_or_default(),
temporal_masking_modes: self.temporal_masking_modes.clone(),
}),
}
}
/// Configure penalty weights based on the optimizer's requirements.
///
/// Call this before optimization to set appropriate penalty weights.
/// Use `PenaltyMode::Disabled` when the optimizer supports native constraints.
pub fn configure_penalties(&mut self, mode: PenaltyMode) {
self.penalty_w_ceiling = mode.ceiling_weight();
self.penalty_w_mingain = mode.mingain_weight();
// Spacing weight is computed from spacing_weight config, scaled by mode
let spacing_scale = match mode {
PenaltyMode::Disabled => 0.0,
PenaltyMode::Standard => 1e3,
PenaltyMode::Pso => 5e2,
};
self.penalty_w_spacing = self.spacing_weight.max(0.0) * spacing_scale;
}
}
/// Placeholder strategy used when a loss type is selected but its required
/// payload data is missing. Returning infinity keeps the optimizer from
/// selecting the invalid candidate.
struct MissingDataStrategy;
impl Objective for MissingDataStrategy {
fn compute(&self, _x: &[f64], _ctx: &ObjectiveContext) -> f64 {
f64::INFINITY
}
}
impl std::fmt::Debug for ObjectiveData {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("ObjectiveData")
.field("freqs", &self.freqs)
.field("target", &self.target)
.field("deviation", &self.deviation)
.field("srate", &self.srate)
.field("min_spacing_oct", &self.min_spacing_oct)
.field("spacing_weight", &self.spacing_weight)
.field("max_db", &self.max_db)
.field("min_db", &self.min_db)
.field("min_freq", &self.min_freq)
.field("max_freq", &self.max_freq)
.field("peq_model", &self.peq_model)
.field("loss_type", &self.loss_type)
.field("objective", &self.objective.as_ref().map(|_| "<Objective>"))
.field("speaker_score_data", &self.speaker_score_data)
.field("headphone_score_data", &self.headphone_score_data)
.field("input_curve", &self.input_curve)
.field("drivers_data", &self.drivers_data)
.field("fixed_crossover_freqs", &self.fixed_crossover_freqs)
.field("penalty_w_ceiling", &self.penalty_w_ceiling)
.field("penalty_w_spacing", &self.penalty_w_spacing)
.field("penalty_w_mingain", &self.penalty_w_mingain)
.field("integrality", &self.integrality)
.field("multi_objective", &self.multi_objective)
.field("smooth", &self.smooth)
.field("smooth_n", &self.smooth_n)
.field("max_boost_envelope", &self.max_boost_envelope)
.field("min_cut_envelope", &self.min_cut_envelope)
.field("epa_config", &self.epa_config)
.field("temporal_masking_modes", &self.temporal_masking_modes)
.field("detected_problems", &self.detected_problems)
.field("null_suppression", &self.null_suppression)
.field("asymmetric_loss_config", &self.asymmetric_loss_config)
.field("smoothness_penalty", &self.smoothness_penalty)
.field("audibility_deadband", &self.audibility_deadband)
.finish()
}
}
/// Run the AutoEQ DE backend with an EPA-aware per-iteration callback.
///
/// EPA preference is recomputed every [`EPA_INTERVAL`] generations from the
/// current best parameter vector. This matches the previous behaviour in
/// `optimize_filters_with_callback`'s `AlgorithmCategory::AutoEQ` arm.
pub(super) fn run_autoeq_de_with_epa_callback(
x: &mut [f64],
lower_bounds: &[f64],
upper_bounds: &[f64],
objective_data: ObjectiveData,
params: &crate::OptimParams,
autoeq_name: &str,
mut callback: OptimProgressCallback,
) -> Result<(String, f64), (String, f64)> {
const EPA_INTERVAL: usize = 10;
let epa_config = objective_data.epa_config.clone();
let epa_freqs =
ndarray::Array1::from(objective_data.freqs.iter().copied().collect::<Vec<f64>>());
// Reconstruct the normalised measurement: target − deviation.
let epa_normalized: Vec<f64> = objective_data
.target
.iter()
.zip(objective_data.deviation.iter())
.map(|(&t, &d)| t - d)
.collect();
let epa_srate = objective_data.srate;
let epa_model = objective_data.peq_model;
let mut epa_gen_counter: usize = 0;
let de_cb: Box<dyn FnMut(&crate::de::DEIntermediate) -> crate::de::CallbackAction + Send> =
Box::new(move |intermediate| {
epa_gen_counter += 1;
let epa = if epa_gen_counter.is_multiple_of(EPA_INTERVAL) {
let peq_spl = x2spl(
&epa_freqs,
intermediate.x.as_slice().unwrap(),
epa_srate,
epa_model,
);
let corrected: Vec<f64> = epa_normalized
.iter()
.enumerate()
.map(|(i, &n)| n + peq_spl[i])
.collect();
let cfg = epa_config.clone().unwrap_or_default();
let score = crate::loss::epa::score::compute_epa_normalized(
epa_freqs.as_slice().unwrap(),
&corrected,
&cfg,
);
Some(score.preference)
} else {
None
};
callback(intermediate.iter, intermediate.fun, epa)
});
optimize_filters_autoeq_with_callback(
x,
lower_bounds,
upper_bounds,
objective_data,
autoeq_name,
params,
de_cb,
)
}