cal-model 0.1.2

A2L calibration data model and session layer: characteristic binding, COMPU_METHOD conversions, limit validation, curve calibration
Documentation
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
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
//! Calibration fitting: monotone piecewise-linear curves and bounded
//! working-point optimisation.
//!
//! These are the two computations a calibration engineer reaches for when
//! the ECU will not tell them the answer — a measured set of points that
//! must become a curve the ECU can interpolate, and a set of adjustable
//! parameters whose best combination has to be found inside their limits.
//!
//! # Curve nodes are parameter *intervals*
//!
//! A [`CalParameter`] is one node of a curve under construction: `value` is
//! the ordinate (the calibrated output at that node) and `lower`/`upper`
//! are the abscissa bounds of the operating condition it was measured at —
//! "`idle` between 700 and 900 rpm". The node's abscissa is the interval's
//! midpoint, which is what makes the fit reproducible from the measurement
//! record rather than from an implicit index order. Nodes are sorted by
//! abscissa before the fit, so the caller may pass them in any order.
//!
//! # Monotonicity is enforced, not assumed
//!
//! A calibration curve whose ordinates change direction makes the ECU's
//! interpolation physically wrong at the turn, so [`calibrate_curve`]
//! rejects it with [`CalError::NonMonotone`] rather than fitting a curve
//! that lies. Both directions are accepted — a gain that falls with
//! temperature is as legitimate as one that rises with load.
//!
//! # The optimiser is deterministic
//!
//! [`optimize_working_point`] is bounded coordinate descent from a fixed
//! set of starting points (each parameter's midpoint and the box corners),
//! halving the step on every sweep without improvement. Same inputs, same
//! answer, every run — which is the only acceptable behaviour for something
//! that ends up in an ECU's flash. A non-finite objective is reported as
//! [`CalError::Convergence`] carrying the iteration count, never silently
//! returning a number from a diverged search.

use crate::error::CalError;
use std::cmp::Ordering;
use std::fmt;

/// Sweep budget for coordinate descent before the optimiser gives up.
const MAX_SWEEPS: u32 = 400;

/// Relative step below which a sweep counts as converged.
const STEP_TOLERANCE: f64 = 1e-9;

/// One node of a curve under construction, or one adjustable of an
/// optimisation.
#[derive(Debug, Clone, PartialEq)]
pub struct CalParameter {
    /// What this node is — the operating condition or the parameter name.
    pub name: String,
    /// For a curve node, the ordinate (the calibrated value). For an
    /// adjustable, the starting point.
    pub value: f64,
    /// Lower bound: the abscissa interval's start (a curve node) or the
    /// parameter's calibration limit.
    pub lower: f64,
    /// Upper bound: the abscissa interval's end (a curve node) or the
    /// parameter's calibration limit.
    pub upper: f64,
}

impl CalParameter {
    /// A parameter with a name, a value, and bounds.
    #[must_use]
    pub fn new(name: impl Into<String>, value: f64, lower: f64, upper: f64) -> Self {
        Self {
            name: name.into(),
            value,
            lower,
            upper,
        }
    }

    /// The abscissa of a curve node: the midpoint of its interval.
    #[must_use]
    pub fn midpoint(&self) -> f64 {
        // f64::midpoint rather than (lower + upper) / 2.0: it cannot
        // overflow on two finite bounds, which (a + b) cannot promise.
        self.lower.midpoint(self.upper)
    }

    /// Clamp `x` into this parameter's bounds.
    #[must_use]
    pub fn clamp(&self, x: f64) -> f64 {
        if x < self.lower {
            self.lower
        } else if x > self.upper {
            self.upper
        } else {
            x
        }
    }
}

impl fmt::Display for CalParameter {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "{} = {:.6} in [{:.6}, {:.6}]",
            self.name, self.value, self.lower, self.upper
        )
    }
}

/// A monotone piecewise-linear calibration curve.
#[derive(Debug, Clone, PartialEq)]
pub struct Curve {
    points: Vec<(f64, f64)>,
}

impl Curve {
    /// Build a curve from `(abscissa, ordinate)` points.
    ///
    /// # Errors
    ///
    /// [`CalError::Unsupported`] when fewer than two points are given, when
    /// the abscissae are not strictly ascending, or when any point is
    /// non-finite.
    pub fn new(points: Vec<(f64, f64)>) -> Result<Self, CalError> {
        if points.len() < 2 {
            return Err(CalError::Unsupported {
                subject: "calibration curve".to_string(),
                reason: format!("{} point(s) given, at least 2 are required", points.len()),
            });
        }
        if points
            .iter()
            .any(|&(x, y)| !x.is_finite() || !y.is_finite())
        {
            return Err(CalError::Unsupported {
                subject: "calibration curve".to_string(),
                reason: "points must be finite".to_string(),
            });
        }
        // Ascending and strictly increasing: `partial_cmp` rather than a
        // negated `<`, so a NaN abscissa is visibly incomparable rather than
        // silently "not ascending".
        if points.windows(2).any(|pair| match pair {
            [first, second] => !matches!(first.0.partial_cmp(&second.0), Some(Ordering::Less)),
            _ => true,
        }) {
            return Err(CalError::Unsupported {
                subject: "calibration curve".to_string(),
                reason: "abscissae must be strictly ascending".to_string(),
            });
        }
        Ok(Self { points })
    }

    /// The fitted points, ascending by abscissa.
    #[must_use]
    pub fn points(&self) -> &[(f64, f64)] {
        &self.points
    }

    /// Number of nodes.
    #[must_use]
    pub fn len(&self) -> usize {
        self.points.len()
    }

    /// `true` when the curve carries no nodes (never true for a curve built
    /// through [`Curve::new`]).
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.points.is_empty()
    }

    /// `true` when the ordinates never change direction.
    #[must_use]
    pub fn is_monotone(&self) -> bool {
        let mut rising = false;
        let mut falling = false;
        for pair in self.points.windows(2) {
            let [first, second] = pair else { continue };
            if second.1 > first.1 {
                rising = true;
            } else if second.1 < first.1 {
                falling = true;
            }
        }
        !(rising && falling)
    }

    /// Evaluate the curve at `x`: linear interpolation between the
    /// bracketing nodes, clamped to the end nodes outside the domain (the
    /// ASAP2 `TAB_INTP` convention).
    #[must_use]
    pub fn eval(&self, x: f64) -> f64 {
        let Some(&(first_x, first_y)) = self.points.first() else {
            return f64::NAN;
        };
        if x <= first_x {
            return first_y;
        }
        let Some(&(last_x, last_y)) = self.points.last() else {
            return f64::NAN;
        };
        if x >= last_x {
            return last_y;
        }
        for pair in self.points.windows(2) {
            let [first, second] = pair else { continue };
            let (x0, y0) = *first;
            let (x1, y1) = *second;
            if x >= x0 && x <= x1 {
                let span = x1 - x0;
                if span == 0.0 {
                    return y0;
                }
                return y0 + (y1 - y0) * (x - x0) / span;
            }
        }
        last_y
    }
}

impl fmt::Display for Curve {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        writeln!(f, "calibration curve ({} points):", self.points.len())?;
        for &(x, y) in &self.points {
            writeln!(f, "  x = {x:>12.4}   y = {y:>12.6}")?;
        }
        Ok(())
    }
}

/// Fit a monotone piecewise-linear curve through the given nodes.
///
/// Nodes are ordered by their abscissa (the midpoint of `lower..upper`) and
/// the ordinates must not change direction. The fit reproduces every node
/// exactly and interpolates linearly between them — which is precisely what
/// an ECU's `TAB_INTP` conversion does, so what this returns is what the ECU
/// will compute.
///
/// # Errors
///
/// [`CalError::Unsupported`] for fewer than two nodes, non-finite bounds, or
/// two nodes sharing an abscissa; [`CalError::OutOfBounds`] when a node's
/// `lower` exceeds its `upper`; [`CalError::NonMonotone`] when the ordinates
/// change direction.
pub fn calibrate_curve(params: &[CalParameter]) -> Result<Curve, CalError> {
    let mut nodes: Vec<(f64, &CalParameter)> = Vec::with_capacity(params.len());
    for param in params {
        validate_bounds(param)?;
        nodes.push((param.midpoint(), param));
    }
    nodes.sort_by(|a, b| {
        a.0.partial_cmp(&b.0)
            .unwrap_or(std::cmp::Ordering::Equal)
            .then_with(|| a.1.name.cmp(&b.1.name))
    });
    for pair in nodes.windows(2) {
        let [first, second] = pair else { continue };
        if first.0 == second.0 {
            return Err(CalError::Unsupported {
                subject: "calibration curve".to_string(),
                reason: format!(
                    "nodes `{}` and `{}` share the abscissa {}",
                    first.1.name, second.1.name, first.0
                ),
            });
        }
    }
    let mut points: Vec<(f64, f64)> = Vec::with_capacity(nodes.len());
    let mut direction = 0_i8;
    for (abscissa, param) in &nodes {
        if let Some(&(_, previous)) = points.last() {
            if param.value > previous && direction < 0 {
                return Err(CalError::NonMonotone {
                    name: param.name.clone(),
                    value: param.value,
                    previous,
                });
            }
            if param.value < previous && direction > 0 {
                return Err(CalError::NonMonotone {
                    name: param.name.clone(),
                    value: param.value,
                    previous,
                });
            }
            if param.value > previous {
                direction = 1;
            } else if param.value < previous {
                direction = -1;
            }
        }
        points.push((*abscissa, param.value));
    }
    Curve::new(points)
}

/// Check a parameter's bounds are usable.
fn validate_bounds(param: &CalParameter) -> Result<(), CalError> {
    if !param.lower.is_finite() || !param.upper.is_finite() || !param.value.is_finite() {
        return Err(CalError::Unsupported {
            subject: format!("parameter `{}`", param.name),
            reason: "value and bounds must be finite".to_string(),
        });
    }
    if param.lower > param.upper {
        return Err(CalError::OutOfBounds {
            name: param.name.clone(),
            value: param.lower,
            lower: param.lower,
            upper: param.upper,
        });
    }
    Ok(())
}

/// Maximise `objective` over the box defined by `params`, returning the
/// point and its value.
///
/// Coordinate descent from each parameter's midpoint and from the box
/// corners, halving the step after every sweep without improvement, until
/// the step falls below [`STEP_TOLERANCE`] or [`MAX_SWEEPS`] sweeps pass.
/// The returned point is always inside the box.
///
/// # Errors
///
/// [`CalError::OutOfBounds`] for an empty parameter set or a degenerate
/// bound, [`CalError::Unsupported`] for non-finite bounds,
/// [`CalError::Convergence`] when the objective never yields a finite value.
pub fn optimal_point(
    params: &[CalParameter],
    objective: &dyn Fn(&[f64]) -> f64,
) -> Result<(Vec<f64>, f64), CalError> {
    if params.is_empty() {
        return Err(CalError::Unsupported {
            subject: "optimiser".to_string(),
            reason: "no parameters to optimise".to_string(),
        });
    }
    for param in params {
        validate_bounds(param)?;
    }
    let n = params.len();
    let widths: Vec<f64> = params.iter().map(|p| p.upper - p.lower).collect();

    // Deterministic multi-start: the midpoint, then every corner of the box
    // for small problems, so a descent that would otherwise stall in a
    // corner's basin starts from that corner too.
    let mut starts: Vec<Vec<f64>> = vec![params.iter().map(CalParameter::midpoint).collect()];
    if n <= 8 {
        for corner in 0..n {
            for high_corner in [true, false] {
                let mut point: Vec<f64> = params
                    .iter()
                    .map(|p| if high_corner { p.lower } else { p.upper })
                    .collect();
                let Some(param) = params.get(corner) else {
                    continue;
                };
                let opposite = if high_corner {
                    param.upper
                } else {
                    param.lower
                };
                if let Some(slot) = point.get_mut(corner) {
                    *slot = opposite;
                }
                starts.push(point);
            }
        }
    }

    let mut best: Option<(Vec<f64>, f64)> = None;
    let mut worst_sweeps = 0_u32;
    for start in starts {
        match descend(params, &widths, objective, start) {
            Ok(found) => {
                let replace = best.as_ref().is_none_or(|(_, value)| found.1 > *value);
                if replace {
                    best = Some(found);
                }
            }
            Err(sweeps) => worst_sweeps = worst_sweeps.max(sweeps),
        }
    }
    best.ok_or(CalError::Convergence {
        iterations: worst_sweeps.max(1),
    })
}

/// One coordinate-descent run from `start`.
///
/// `Ok` carries the point and its value; `Err` carries the number of sweeps
/// the run consumed before giving up.
fn descend(
    params: &[CalParameter],
    widths: &[f64],
    objective: &dyn Fn(&[f64]) -> f64,
    mut point: Vec<f64>,
) -> Result<(Vec<f64>, f64), u32> {
    for (index, param) in params.iter().enumerate() {
        if let Some(slot) = point.get_mut(index) {
            *slot = param.clamp(*slot);
        }
    }
    // A non-finite start is still worth walking away from (the box corners
    // may well be finite), but a run that never sees a finite value reports
    // failure rather than returning -inf as an answer.
    let initial = objective(&point);
    let mut value = if initial.is_finite() {
        initial
    } else {
        f64::NEG_INFINITY
    };
    let mut steps: Vec<f64> = widths.iter().map(|w| 0.5 * w).collect();
    let mut sweep = 0_u32;
    loop {
        if sweep >= MAX_SWEEPS {
            return Err(MAX_SWEEPS);
        }
        sweep += 1;
        let mut improved = false;
        let mut attempted = false;
        let mut finite_trial = false;
        for index in 0..point.len() {
            for direction in [1.0_f64, -1.0_f64] {
                let step = steps.get(index).copied().unwrap_or(0.0);
                let current = point.get(index).copied().unwrap_or(0.0);
                let Some(param) = params.get(index) else {
                    continue;
                };
                let trial = param.clamp(current + direction * step);
                if trial == current {
                    continue;
                }
                attempted = true;
                let mut candidate = point.clone();
                if let Some(slot) = candidate.get_mut(index) {
                    *slot = trial;
                }
                let score = objective(&candidate);
                if !score.is_finite() {
                    continue;
                }
                finite_trial = true;
                if score > value {
                    value = score;
                    point = candidate;
                    improved = true;
                    break;
                }
            }
        }
        if improved {
            continue;
        }
        if !finite_trial {
            // No trial moved the needle. Either every trial was rejected as
            // non-finite (a diverged objective — report it), or the box has
            // collapsed to a point (there is nowhere left to search, which is
            // a converged answer, not a failure).
            return if attempted {
                Err(sweep)
            } else {
                Ok((point, value))
            };
        }
        let mut moving = false;
        for step in &mut steps {
            *step *= 0.5;
            if *step > STEP_TOLERANCE {
                moving = true;
            }
        }
        if !moving {
            return Ok((point, value));
        }
    }
}

/// Maximise `objective` over the box defined by `params` and return the best
/// value found.
///
/// See [`optimal_point`] for the search itself and its guarantees; this is
/// the value-only form calibration tools usually want.
///
/// # Errors
///
/// As [`optimal_point`].
pub fn optimize_working_point(
    params: &[CalParameter],
    objective: &dyn Fn(&[f64]) -> f64,
) -> Result<f64, CalError> {
    optimal_point(params, objective).map(|(_, value)| value)
}