pub const TRANSITION: f64 = 4.0;
#[inline]
#[must_use]
fn softplus(u: f64) -> f64 {
u.max(0.0) + (-u.abs()).exp().ln_1p()
}
#[inline]
#[must_use]
pub fn sigmoid(z: f64) -> f64 {
if z >= 0.0 {
1.0 / (1.0 + (-z).exp())
} else {
let e = z.exp();
e / (1.0 + e)
}
}
#[inline]
#[must_use]
pub fn logit(p: f64) -> f64 {
let p = p.clamp(1e-9, 1.0 - 1e-9);
(p / (1.0 - p)).ln()
}
#[inline]
#[must_use]
pub fn density_from(
d_min: f64,
d_max: f64,
gamma: f64,
log_e0: f64,
toe_transition: f64,
shoulder_transition: f64,
log_e: f64,
) -> f64 {
let span = d_max - d_min;
let gamma = gamma.max(1e-9);
let half = 0.5 * span.abs() / gamma;
let toe_slope = toe_transition.max(1e-3);
let shoulder_slope = shoulder_transition.max(1e-3);
let direction = if span < 0.0 { -1.0 } else { 1.0 };
let toe = softplus(toe_slope * (log_e - (log_e0 - half))) / toe_slope;
let shoulder = softplus(shoulder_slope * (log_e - (log_e0 + half))) / shoulder_slope;
let travel = (gamma * (toe - shoulder)).clamp(0.0, span.abs());
d_min + direction * travel
}
#[inline]
#[must_use]
pub fn slope_from(
d_min: f64,
d_max: f64,
gamma: f64,
log_e0: f64,
toe_transition: f64,
shoulder_transition: f64,
log_e: f64,
) -> f64 {
let span = d_max - d_min;
let gamma = gamma.max(1e-9);
let half = 0.5 * span.abs() / gamma;
let toe_slope = toe_transition.max(1e-3);
let shoulder_slope = shoulder_transition.max(1e-3);
let direction = if span < 0.0 { -1.0 } else { 1.0 };
let travel = gamma
* (softplus(toe_slope * (log_e - (log_e0 - half))) / toe_slope
- softplus(shoulder_slope * (log_e - (log_e0 + half))) / shoulder_slope);
if travel <= 0.0 || travel >= span.abs() {
return 0.0;
}
direction
* gamma
* (sigmoid(toe_slope * (log_e - (log_e0 - half)))
- sigmoid(shoulder_slope * (log_e - (log_e0 + half))))
}
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct CharacteristicCurve {
pub d_min: f64,
pub d_max: f64,
pub gamma: f64,
pub log_e0: f64,
pub toe_transition: f64,
pub shoulder_transition: f64,
}
impl CharacteristicCurve {
#[must_use]
pub const fn new(d_min: f64, d_max: f64, gamma: f64, log_e0: f64) -> Self {
Self {
d_min,
d_max,
gamma,
log_e0,
toe_transition: TRANSITION,
shoulder_transition: TRANSITION,
}
}
#[must_use]
pub const fn with_transition(self, transition: f64) -> Self {
Self {
toe_transition: transition,
shoulder_transition: transition,
..self
}
}
#[must_use]
pub const fn with_corners(self, toe: f64, shoulder: f64) -> Self {
Self {
toe_transition: toe,
shoulder_transition: shoulder,
..self
}
}
#[must_use]
pub fn span(&self) -> f64 {
self.d_max - self.d_min
}
#[must_use]
pub fn amplitude(&self) -> f64 {
self.span().abs().max(1e-9)
}
#[must_use]
pub fn rises(&self) -> bool {
self.span() >= 0.0
}
#[must_use]
pub fn slope_factor(&self) -> f64 {
self.gamma
}
#[must_use]
pub fn density(&self, log_e: f64) -> f64 {
density_from(
self.d_min,
self.d_max,
self.gamma,
self.log_e0,
self.toe_transition,
self.shoulder_transition,
log_e,
)
}
#[must_use]
pub fn slope_at(&self, log_e: f64) -> f64 {
slope_from(
self.d_min,
self.d_max,
self.gamma,
self.log_e0,
self.toe_transition,
self.shoulder_transition,
log_e,
)
}
#[must_use]
pub fn log_exposure_at(&self, density: f64) -> f64 {
let span = self.span();
let half = 0.5 * span.abs() / self.gamma.max(1e-9);
let target = (density - self.d_min) / span;
let direction = if span < 0.0 { -1.0 } else { 1.0 };
if target <= 1e-12 {
return self.log_e0 - direction * (half + 10.0);
}
if target >= 1.0 - 1e-12 {
return self.log_e0 + direction * (half + 10.0);
}
let mut low = self.log_e0 - half - 10.0;
let mut high = self.log_e0 + half + 10.0;
for _ in 0..200 {
let middle = 0.5 * (low + high);
let below = if direction > 0.0 {
self.density(middle) < density
} else {
self.density(middle) > density
};
if below {
low = middle;
} else {
high = middle;
}
if high - low < 1e-12 {
break;
}
}
0.5 * (low + high)
}
#[must_use]
pub fn shifted(&self, delta_log_e: f64, delta_d_min: f64) -> Self {
Self {
d_min: self.d_min + delta_d_min,
log_e0: self.log_e0 + delta_log_e,
..*self
}
}
}
#[cfg(test)]
mod tests {
use super::*;
fn curve() -> CharacteristicCurve {
CharacteristicCurve::new(0.2, 2.2, 0.6, -0.75)
}
#[test]
fn is_monotonic_and_bounded() {
let c = curve();
let mut previous = f64::NEG_INFINITY;
for i in -800..800 {
let d = c.density(f64::from(i) / 100.0);
assert!(d > previous, "density must increase with exposure");
assert!(
(c.d_min - 1e-6..=c.d_max + 1e-6).contains(&d),
"escaped the curve at {d}"
);
previous = d;
}
}
#[test]
fn a_reversal_falls_instead_of_rising() {
let reversal = CharacteristicCurve::new(3.4, 0.0, 1.9, -0.4).with_transition(8.0);
assert!(!reversal.rises());
assert!((reversal.span() + 3.4).abs() < 1e-12);
assert!((reversal.amplitude() - 3.4).abs() < 1e-12);
let mut previous = f64::INFINITY;
for i in -900..900 {
let log_e = f64::from(i) / 100.0;
let d = reversal.density(log_e);
assert!(d <= previous + 1e-12, "a reversal's density must not rise");
assert!(
(-1e-6..=3.4 + 1e-6).contains(&d),
"escaped the curve at {d}"
);
previous = d;
}
assert!(reversal.density(-2.0) - reversal.density(2.0) > 2.5);
let middle = reversal.slope_at(reversal.log_e0);
assert!(
(middle + 1.9).abs() < 0.02 * 1.9,
"centre slope {middle} vs -gamma"
);
for density in [3.2, 2.0, 1.0, 0.2] {
let back = reversal.density(reversal.log_exposure_at(density));
assert!((back - density).abs() < 1e-6, "{density} came back {back}");
}
}
#[test]
fn the_straight_line_has_constant_slope() {
let c = curve();
let half = 0.5 * c.span() / c.gamma;
let centre = c.slope_at(c.log_e0);
assert!(
(centre - c.gamma).abs() < 0.005 * c.gamma,
"centre slope {centre} vs gamma {}",
c.gamma
);
for offset in [-0.5 * half, 0.5 * half] {
let slope = c.slope_at(c.log_e0 + offset);
assert!(
(slope - c.gamma).abs() < 0.05 * c.gamma,
"slope {slope} at {offset}"
);
}
}
#[test]
fn one_rate_is_the_old_curve() {
for (d_min, d_max, gamma, log_e0, rate) in [
(0.2, 2.2, 0.6, -0.75, 4.0),
(3.35, 0.18, 2.22, -1.19, 6.0),
(0.0964, 2.5358, 3.7821, -1.4125, 7.0),
] {
let curve = CharacteristicCurve::new(d_min, d_max, gamma, log_e0).with_transition(rate);
let span = d_max - d_min;
let half = 0.5 * span.abs() / gamma;
let direction = if span < 0.0 { -1.0 } else { 1.0 };
for i in -40..=40 {
let log_e = log_e0 + f64::from(i) / 8.0;
let old = d_min
+ direction
* (gamma / rate)
* (softplus(rate * (log_e - (log_e0 - half)))
- softplus(rate * (log_e - (log_e0 + half))));
let new = curve.density(log_e);
assert!((old - new).abs() < 1e-12, "{log_e}: {old} against {new}");
}
}
}
#[test]
fn two_rates_keep_the_plateaus_and_the_line() {
let base = CharacteristicCurve::new(3.35, 0.18, 2.22, -1.19);
for (toe, shoulder) in [(5.0, 2.0), (2.0, 5.0), (8.0, 1.5), (4.0, 4.0)] {
let curve = base.with_corners(toe, shoulder);
let high = curve.density(curve.log_e0 - 6.0);
let low = curve.density(curve.log_e0 + 6.0);
assert!(
(high - 3.35).abs() < 1e-3,
"{toe}/{shoulder}: unexposed at {high}"
);
assert!(
(low - 0.18).abs() < 1e-3,
"{toe}/{shoulder}: clear at {low}"
);
let mut steepest = 0.0_f64;
let mut previous = f64::INFINITY;
for i in -300..300 {
let log_e = curve.log_e0 + f64::from(i) / 40.0;
steepest = steepest.max(curve.slope_at(log_e).abs());
let d = curve.density(log_e);
assert!(d <= previous + 1e-12, "{toe}/{shoulder} rose at {log_e}");
previous = d;
}
assert!(
steepest > 0.5 * 2.22 && steepest < 1.5 * 2.22,
"{toe}/{shoulder}: steepest slope {steepest} against gamma 2.22"
);
for density in [3.2, 2.2, 1.2, 0.3] {
let back = curve.density(curve.log_exposure_at(density));
assert!((back - density).abs() < 1e-6, "{density} came back {back}");
}
}
}
#[test]
fn a_different_toe_changes_the_middle_of_the_curve() {
let at_four =
CharacteristicCurve::new(3.3476, 0.1816, 2.2233, -1.1944).with_transition(4.0);
let split = at_four.with_corners(5.0, 2.0);
let mut moved = 0.0_f64;
for i in 0..=80 {
let log_e = at_four.log_e0 - 2.0 + 0.05 * f64::from(i);
moved = moved.max((split.density(log_e) - at_four.density(log_e)).abs());
}
assert!(moved > 0.02, "the two shapes differ by only {moved}");
assert!(moved < 0.6, "the two shapes differ by {moved}");
}
#[test]
fn the_ends_are_flat() {
let c = curve();
let half = 0.5 * c.span() / c.gamma;
assert!(c.slope_at(c.log_e0 - half - 2.0) < 1e-3);
assert!(c.slope_at(c.log_e0 + half + 2.0) < 1e-3);
}
#[test]
fn the_maximum_slope_is_reached_over_a_plateau() {
let c = curve();
let half = 0.5 * c.span() / c.gamma;
let mut on_plateau = 0;
for i in 0..400 {
let x = c.log_e0 - half + (i as f64) / 400.0 * 2.0 * half;
if c.slope_at(x) > 0.9 * c.gamma {
on_plateau += 1;
}
}
assert!(
on_plateau > 200,
"only {on_plateau}/400 samples within 10 % of gamma"
);
}
#[test]
fn the_transition_decides_how_much_of_gamma_the_curve_reaches() {
fn peak(curve: CharacteristicCurve) -> f64 {
(0..400)
.map(|i| curve.slope_at(curve.log_e0 - 1.0 + f64::from(i) / 200.0))
.fold(f64::NEG_INFINITY, f64::max)
}
let paper = CharacteristicCurve::new(0.2078, 2.7739, 5.24, -1.1750);
let sharp = peak(paper.with_transition(10.0));
let soft = peak(paper.with_transition(TRANSITION));
assert!(
(sharp - 4.4).abs() < 0.2,
"at the paper's transition the slope peaks at {sharp}, not near the 4.8 the sheet draws"
);
assert!(
soft < 0.6 * sharp,
"the negative's transition still reached {soft} of {sharp}"
);
let negative = CharacteristicCurve::new(0.0, 1.6818, 0.4745, -0.7582);
assert!(
(peak(negative) - negative.gamma).abs() < 0.01 * negative.gamma,
"the negative peaked at {} against gamma {}",
peak(negative),
negative.gamma
);
}
#[test]
fn inverse_agrees_with_forward() {
let c = curve();
for i in 1..10 {
let d = c.d_min + c.span() * f64::from(i) / 10.0;
let x = c.log_exposure_at(d);
assert!(
(c.density(x) - d).abs() < 1e-6,
"{d} -> {x} -> {}",
c.density(x)
);
}
}
#[test]
fn the_inverse_is_monotonic() {
let c = curve();
let mut previous = f64::NEG_INFINITY;
for i in 1..200 {
let d = c.d_min + c.span() * f64::from(i) / 200.0;
let x = c.log_exposure_at(d);
assert!(x > previous, "not monotonic at {d}");
previous = x;
}
}
}