libitofin 0.52.1

//! Default-probability term structure.
//!
//! Port of `ql/termstructures/defaulttermstructure.{hpp,cpp}`: the
//! [`DefaultProbabilityTermStructure`] trait extends [`TermStructure`] with
//! the survival-probability, default-probability, default-density and
//! hazard-rate algebra. Two hooks are required
//! ([`survival_probability_impl`](DefaultProbabilityTermStructure::survival_probability_impl)
//! and
//! [`default_density_impl`](DefaultProbabilityTermStructure::default_density_impl),
//! `defaulttermstructure.hpp:158-160`); the third
//! ([`hazard_rate_impl`](DefaultProbabilityTermStructure::hazard_rate_impl),
//! `defaulttermstructure.hpp:162`) carries C++'s default implementation and is
//! overridden by curves that quote the hazard rate directly.
//!
//! ## Divergences from QuantLib
//!
//! - Jump quotes and dates are held by [`DefaultProbabilityJumps`]. Curves opt
//!   in through [`DefaultProbabilityTermStructure::jumps`]. As in QuantLib,
//!   automatic year-end dates are generated once; moving reference dates
//!   change jump times, not the generated dates. Times are calculated on demand
//!   rather than cached by `setJumps()` (`defaulttermstructure.cpp:64-79`).
//! - C++ overloads on `Date`/`Time` become distinct method names: the plain
//!   name takes times and the `_date` / `_dates` suffix takes dates, so the
//!   two-argument `defaultProbability` overloads are
//!   [`default_probability_between`](DefaultProbabilityTermStructure::default_probability_between)
//!   (times) and
//!   [`default_probability_between_dates`](DefaultProbabilityTermStructure::default_probability_between_dates)
//!   (dates).
//! - The C++ `QL_REQUIRE` on reversed arguments
//!   (`defaulttermstructure.cpp:107-109`, `120-122`) returns an `Err` here
//!   rather than throwing.

use crate::errors::QlResult;
use crate::handle::Handle;
use crate::patterns::observable::Observer;
use crate::quotes::Quote;
use crate::shared::SharedMut;
use crate::termstructures::{TermStructure, TermStructureBase};
use crate::time::date::{Date, Month};
use crate::types::{Probability, Rate, Real, Time};
use crate::{fail, require};

/// Observable multiplicative survival jumps shared by credit curves.
///
/// This implements `defaulttermstructure.cpp:64-103` (v1.44). Quote validation
/// is lazy: every jump whose time is strictly inside `(0, t)` is read, in input
/// order, so jumps on or before the reference date never apply.
/// The owning curve must expose this state through its `jumps()` hook.
pub struct DefaultProbabilityJumps {
    quotes: Vec<Handle<dyn Quote>>,
    dates: Vec<Date>,
}

impl DefaultProbabilityJumps {
    /// Registers jump quotes with the curve's updater and resolves dates.
    ///
    /// Empty dates select December 31 of the initial reference year and each
    /// subsequent year. Explicit dates must have one entry per quote.
    ///
    /// # Errors
    /// Returns an error for mismatched lengths, null dates, an unavailable
    /// reference date, or automatic dates beyond the supported date range.
    pub fn new(
        base: &TermStructureBase,
        quotes: Vec<Handle<dyn Quote>>,
        dates: Vec<Date>,
    ) -> QlResult<Self> {
        Self::with_observer(base, &base.updater(), quotes, dates)
    }

    /// As [`new`](Self::new), registering the jump quotes with `observer`
    /// instead of the base updater: a bootstrapped curve passes the private
    /// updater that invalidates its cache.
    ///
    /// # Errors
    /// Returns the [`new`](Self::new) errors.
    pub fn with_observer(
        base: &TermStructureBase,
        observer: &SharedMut<dyn Observer>,
        quotes: Vec<Handle<dyn Quote>>,
        mut dates: Vec<Date>,
    ) -> QlResult<Self> {
        if dates.is_empty() && !quotes.is_empty() {
            let year = base.reference_date()?.year();
            require!(
                quotes.len() <= (Date::max_date().year() - year + 1) as usize,
                "automatic jump dates exceed the maximum supported date"
            );
            dates = (0..quotes.len())
                .map(|i| Date::new(31, Month::December, year + i as i32))
                .collect();
        }
        require!(
            quotes.len() == dates.len(),
            "mismatch between number of jumps ({}) and jump dates ({})",
            quotes.len(),
            dates.len()
        );
        require!(
            dates.iter().all(|date| *date != Date::null()),
            "null jump date"
        );
        let jumps = Self { quotes, dates };
        jumps.register_observer(observer);
        Ok(jumps)
    }

    /// The immutable jump dates, including any generated year-end dates.
    pub fn dates(&self) -> &[Date] {
        &self.dates
    }

    /// Registers `observer` with every jump quote.
    pub fn register_observer(&self, observer: &SharedMut<dyn Observer>) {
        for quote in &self.quotes {
            quote.register_observer(observer);
        }
    }

    fn factor<T: TermStructure + ?Sized>(&self, curve: &T, t: Time) -> QlResult<Probability> {
        let mut factor = 1.0;
        for (date, handle) in self.dates.iter().zip(&self.quotes) {
            let jump_time = curve.time_from_reference(*date)?;
            if jump_time > 0.0 && jump_time < t {
                let quote = handle.current_link()?;
                require!(quote.is_valid(), "invalid jump quote");
                let value = quote.value()?;
                require!(value > 0.0 && value <= 1.0, "invalid jump value: {value}");
                factor *= value;
            }
        }
        Ok(factor)
    }
}

/// Default-probability term structure.
///
/// Mirrors QuantLib's `DefaultProbabilityTermStructure`: concrete credit
/// curves implement
/// [`survival_probability_impl`](Self::survival_probability_impl) and
/// [`default_density_impl`](Self::default_density_impl) (both called after
/// range checking, so they must assume extrapolation is required) and inherit
/// the rest.
pub trait DefaultProbabilityTermStructure: TermStructure {
    /// Survival-probability calculation, implemented by concrete curves.
    fn survival_probability_impl(&self, t: Time) -> QlResult<Probability>;

    /// Default-density calculation, implemented by concrete curves.
    fn default_density_impl(&self, t: Time) -> QlResult<Real>;

    /// The curve as [`Any`](std::any::Any), for the callers that must recover
    /// its concrete type from a `dyn DefaultProbabilityTermStructure`.
    ///
    /// The credit-side twin of
    /// [`YieldTermStructure::as_any`](crate::termstructures::yieldtermstructure::YieldTermStructure::as_any);
    /// see that method for why the seam exists and what the default `None`
    /// means.
    fn as_any(&self) -> Option<&dyn std::any::Any> {
        None
    }

    /// Optional observable jump state; existing curves default to no jumps.
    fn jumps(&self) -> Option<&DefaultProbabilityJumps> {
        None
    }

    /// Jump dates in constructor order.
    fn jump_dates(&self) -> &[Date] {
        self.jumps().map_or(&[], DefaultProbabilityJumps::dates)
    }

    /// Jump times recalculated against the current reference date.
    fn jump_times(&self) -> QlResult<Vec<Time>> {
        self.jump_dates()
            .iter()
            .map(|date| self.time_from_reference(*date))
            .collect()
    }

    /// Hazard-rate calculation, derived from the density and the survival
    /// probability; curves quoting the hazard rate override it with a more
    /// efficient implementation.
    ///
    /// A zero survival probability yields a zero hazard rate rather than a
    /// division by zero (`defaulttermstructure.hpp:220-223`).
    fn hazard_rate_impl(&self, t: Time) -> QlResult<Rate> {
        let survival = self.survival_probability(t, true)?;
        if survival == 0.0 {
            return Ok(0.0);
        }
        Ok(self.default_density(t, true)? / survival)
    }

    /// The survival probability from the reference date to time `t`.
    ///
    /// The time must be calculated with the same day-counting rule used by
    /// the term structure.
    fn survival_probability(&self, t: Time, extrapolate: bool) -> QlResult<Probability> {
        self.check_range_time(t, extrapolate)?;
        let factor = match self.jumps() {
            Some(jumps) => jumps.factor(self, t)?,
            None => 1.0,
        };
        Ok(factor * self.survival_probability_impl(t)?)
    }

    /// The survival probability from the reference date to `date`.
    fn survival_probability_date(&self, date: Date, extrapolate: bool) -> QlResult<Probability> {
        self.survival_probability(self.time_from_reference(date)?, extrapolate)
    }

    /// The default probability from the reference date to time `t`.
    ///
    /// The time must be calculated with the same day-counting rule used by
    /// the term structure.
    fn default_probability(&self, t: Time, extrapolate: bool) -> QlResult<Probability> {
        Ok(1.0 - self.survival_probability(t, extrapolate)?)
    }

    /// The default probability from the reference date to `date`.
    fn default_probability_date(&self, date: Date, extrapolate: bool) -> QlResult<Probability> {
        Ok(1.0 - self.survival_probability_date(date, extrapolate)?)
    }

    /// The probability of default between times `t1` and `t2`.
    ///
    /// Times before the reference date contribute nothing, so a negative `t1`
    /// is clamped to a zero default probability
    /// (`defaulttermstructure.cpp:123`).
    fn default_probability_between(
        &self,
        t1: Time,
        t2: Time,
        extrapolate: bool,
    ) -> QlResult<Probability> {
        if t1.is_nan() || t2.is_nan() || t1 > t2 {
            fail!("initial time ({t1}) later than final time ({t2})");
        }
        let p1 = if t1 < 0.0 {
            0.0
        } else {
            self.default_probability(t1, extrapolate)?
        };
        let p2 = self.default_probability(t2, extrapolate)?;
        Ok(p2 - p1)
    }

    /// The probability of default between `d1` and `d2`.
    ///
    /// Dates before the reference date contribute nothing, so a `d1` that
    /// precedes it is clamped to a zero default probability
    /// (`defaulttermstructure.cpp:110-111`).
    fn default_probability_between_dates(
        &self,
        d1: Date,
        d2: Date,
        extrapolate: bool,
    ) -> QlResult<Probability> {
        require!(d1 <= d2, "initial date ({d1}) later than final date ({d2})");
        let p1 = if d1 < self.reference_date()? {
            0.0
        } else {
            self.default_probability_date(d1, extrapolate)?
        };
        let p2 = self.default_probability_date(d2, extrapolate)?;
        Ok(p2 - p1)
    }

    /// The default density at time `t`.
    ///
    /// The time must be calculated with the same day-counting rule used by
    /// the term structure.
    fn default_density(&self, t: Time, extrapolate: bool) -> QlResult<Real> {
        self.check_range_time(t, extrapolate)?;
        self.default_density_impl(t)
    }

    /// The default density at `date`.
    fn default_density_date(&self, date: Date, extrapolate: bool) -> QlResult<Real> {
        self.default_density(self.time_from_reference(date)?, extrapolate)
    }

    /// The hazard rate at time `t`, with annual frequency and continuous
    /// compounding.
    ///
    /// The time must be calculated with the same day-counting rule used by
    /// the term structure.
    fn hazard_rate(&self, t: Time, extrapolate: bool) -> QlResult<Rate> {
        self.check_range_time(t, extrapolate)?;
        self.hazard_rate_impl(t)
    }

    /// The hazard rate at `date`, with annual frequency and continuous
    /// compounding.
    fn hazard_rate_date(&self, date: Date, extrapolate: bool) -> QlResult<Rate> {
        self.hazard_rate(self.time_from_reference(date)?, extrapolate)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::patterns::observable::{AsObservable, Observable};
    use crate::termstructures::TermStructureBase;
    use crate::time::date::Month;
    use crate::time::daycounters::actual360::Actual360;

    const INTENSITY: Real = 0.04;

    struct ExponentialCurve {
        base: TermStructureBase,
        max: Date,
    }

    impl ExponentialCurve {
        fn new(reference: Date) -> ExponentialCurve {
            ExponentialCurve {
                base: TermStructureBase::with_reference_date(
                    reference,
                    None,
                    Some(Actual360::new()),
                ),
                max: reference + 360,
            }
        }
    }

    impl AsObservable for ExponentialCurve {
        fn observable(&self) -> &Observable {
            self.base.observable()
        }
    }

    impl TermStructure for ExponentialCurve {
        fn base(&self) -> &TermStructureBase {
            &self.base
        }

        fn max_date(&self) -> Date {
            self.max
        }
    }

    impl DefaultProbabilityTermStructure for ExponentialCurve {
        fn survival_probability_impl(&self, t: Time) -> QlResult<Probability> {
            Ok((-INTENSITY * t).exp())
        }

        fn default_density_impl(&self, t: Time) -> QlResult<Real> {
            Ok(INTENSITY * (-INTENSITY * t).exp())
        }
    }

    fn curve() -> ExponentialCurve {
        ExponentialCurve::new(Date::new(15, Month::June, 2026))
    }

    fn survival(t: Time) -> Probability {
        (-INTENSITY * t).exp()
    }

    #[test]
    fn survival_probability_checks_range_then_delegates() {
        let curve = curve();
        assert!((curve.survival_probability(0.5, false).unwrap() - survival(0.5)).abs() < 1.0e-15);
        assert_eq!(curve.survival_probability(0.0, false).unwrap(), 1.0);
        assert!(curve.survival_probability(-0.5, false).is_err());
        assert!(curve.survival_probability(2.0, false).is_err());
        assert!((curve.survival_probability(2.0, true).unwrap() - survival(2.0)).abs() < 1.0e-15);
    }

    #[test]
    fn date_variants_convert_through_the_day_counter() {
        let curve = curve();
        let date = curve.reference_date().unwrap() + 180;
        assert!(
            (curve.survival_probability_date(date, false).unwrap() - survival(0.5)).abs() < 1.0e-15
        );
        assert!(
            (curve.default_density_date(date, false).unwrap() - INTENSITY * survival(0.5)).abs()
                < 1.0e-15
        );
        assert!((curve.hazard_rate_date(date, false).unwrap() - INTENSITY).abs() < 1.0e-15);
        assert!(curve.default_density(-0.5, false).is_err());
        assert!(curve.default_density(2.0, false).is_err());
    }

    #[test]
    fn default_probability_is_one_minus_survival() {
        let curve = curve();
        let date = curve.reference_date().unwrap() + 180;
        assert!(
            (curve.default_probability(0.5, false).unwrap() - (1.0 - survival(0.5))).abs()
                < 1.0e-15
        );
        assert!(
            (curve.default_probability_date(date, false).unwrap() - (1.0 - survival(0.5))).abs()
                < 1.0e-15
        );
        assert_eq!(curve.default_probability(0.0, false).unwrap(), 0.0);
        assert!(curve.default_probability(-0.5, false).is_err());
    }

    #[test]
    fn hazard_rate_recovers_the_constant_intensity() {
        let curve = curve();
        assert!((curve.hazard_rate(0.5, false).unwrap() - INTENSITY).abs() < 1.0e-15);
        assert!((curve.hazard_rate(2.0, true).unwrap() - INTENSITY).abs() < 1.0e-15);
        assert!(curve.hazard_rate(2.0, false).is_err());
        assert!(curve.hazard_rate(-0.5, false).is_err());
    }

    #[test]
    fn default_probability_between_times_clamps_and_orders() {
        let curve = curve();
        let between = curve
            .default_probability_between(0.25, 0.75, false)
            .unwrap();
        assert!((between - (survival(0.25) - survival(0.75))).abs() < 1.0e-15);

        let clamped = curve.default_probability_between(-1.0, 0.5, false).unwrap();
        assert!((clamped - (1.0 - survival(0.5))).abs() < 1.0e-15);

        assert!(
            curve
                .default_probability_between(0.75, 0.25, false)
                .is_err()
        );
    }

    #[test]
    fn default_probability_between_dates_clamps_before_the_reference() {
        let curve = curve();
        let reference = curve.reference_date().unwrap();
        let between = curve
            .default_probability_between_dates(reference + 90, reference + 270, false)
            .unwrap();
        assert!((between - (survival(0.25) - survival(0.75))).abs() < 1.0e-15);

        let clamped = curve
            .default_probability_between_dates(reference - 1, reference + 180, false)
            .unwrap();
        assert!((clamped - (1.0 - survival(0.5))).abs() < 1.0e-15);

        assert!(
            curve
                .default_probability_between_dates(reference + 270, reference + 90, false)
                .is_err()
        );
    }

    #[test]
    fn zero_survival_probability_yields_a_zero_hazard_rate() {
        struct DefaultedCurve {
            base: TermStructureBase,
        }

        impl AsObservable for DefaultedCurve {
            fn observable(&self) -> &Observable {
                self.base.observable()
            }
        }

        impl TermStructure for DefaultedCurve {
            fn base(&self) -> &TermStructureBase {
                &self.base
            }

            fn max_date(&self) -> Date {
                Date::max_date()
            }
        }

        impl DefaultProbabilityTermStructure for DefaultedCurve {
            fn survival_probability_impl(&self, _t: Time) -> QlResult<Probability> {
                Ok(0.0)
            }

            fn default_density_impl(&self, _t: Time) -> QlResult<Real> {
                Ok(1.0)
            }
        }

        let curve = DefaultedCurve {
            base: TermStructureBase::with_reference_date(
                Date::new(15, Month::June, 2026),
                None,
                Some(Actual360::new()),
            ),
        };
        assert_eq!(curve.hazard_rate(0.5, false).unwrap(), 0.0);
        assert_eq!(curve.default_probability(0.5, false).unwrap(), 1.0);
    }
}