optionstratlib-core 0.23.0

Core domain model of OptionStratLib: options, positions, legs, trades, checked Decimal helpers and their errors. Re-exported by the optionstratlib facade on every feature set.
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

/******************************************************************************
   Author: Joaquín Béjar García
   Email: jb@taunais.com
   Date: 11/8/24
******************************************************************************/
use positive::Positive;

/// Days in a year, as `positive` defines it (365). Re-exported so that
/// components reach it through core rather than by depending on `positive`
/// directly (ADR-0001 D8).
pub use positive::constants::DAYS_IN_A_YEAR;
use rust_decimal::Decimal;
use rust_decimal_macros::dec;
use std::sync::LazyLock;

/// Mathematical constant representing π (pi) with high precision using Decimal type.
/// Used for circular calculations, angle conversions, and geometric computations.
pub const PI: Decimal = dec!(3.1415926535897932384626433832);

/// Represents zero as a 64-bit floating point number.
/// Used as a baseline value for numerical comparisons and calculations.
pub const ZERO: f64 = 0.0;

/// Small decimal value used as a threshold for convergence tests and equality comparisons.
/// Represents a general tolerance level for numerical algorithms.
#[allow(dead_code)]
pub const TOLERANCE: Decimal = dec!(1e-8);

/// Extremely small decimal value used for high-precision calculations.
/// Represents the smallest meaningful difference in numerical computations.
pub const EPSILON: Decimal = dec!(1e-16);

/// Minimum allowed volatility value as a `Positive` decimal.
///
/// Prevents numerical issues in financial calculations with near-zero volatility.
/// Initialized once via `LazyLock`, like the six cells below it.
///
/// # Why the `Err` arm cannot fire
///
/// Each of these initialisers is a closure over nothing: its only input is a
/// `dec!(…)` literal, expanded to a fixed mantissa and scale at compile time.
/// [`Positive::new_decimal`] rejects exactly one thing, a value below the
/// lower bound — zero without the `non-zero` feature, which this crate does
/// not enable — and every literal here is strictly positive. There is no
/// runtime value that reaches the `Err` arm, and no `Positive` constant to
/// return in its place: `positive` keeps `from_decimal_const` crate-private,
/// so a `const` alternative does not exist for values outside its own
/// constant ladder. The alternative to aborting would be a stand-in like
/// `Positive::ZERO`, which would silently make every annualisation divide by
/// zero — worse than the abort it replaced.
pub static MIN_VOLATILITY: LazyLock<Positive> = LazyLock::new(|| {
    Positive::new_decimal(dec!(1e-16))
        .unwrap_or_else(|e| unreachable!("MIN_VOLATILITY literal is positive and finite: {e}")) // scan-banned: allow -- `dec!()` literal, `Err` arm has no reachable input; see MIN_VOLATILITY
});

/// Maximum allowed volatility value as a `Positive` decimal (100%).
///
/// Sets an upper bound for volatility inputs in financial models.
pub const MAX_VOLATILITY: Positive = Positive::HUNDRED;

/// Multiplier defining the lower bound for strike price ranges (98% of reference price).
/// Used to establish the minimum strike price in option chains or pricing models.
pub const STRIKE_PRICE_LOWER_BOUND_MULTIPLIER: f64 = 0.98;

/// Multiplier defining the upper bound for strike price ranges (102% of reference price).
/// Used to establish the maximum strike price in option chains or pricing models.
pub const STRIKE_PRICE_UPPER_BOUND_MULTIPLIER: f64 = 1.02;

/// Standard number of trading days in a year as a `Positive` decimal.
///
/// Used for business day-based financial calculations. See `MIN_VOLATILITY`
/// for the `LazyLock` rationale.
pub static TRADING_DAYS: LazyLock<Positive> = LazyLock::new(|| {
    Positive::new_decimal(dec!(252.0))
        .unwrap_or_else(|e| unreachable!("TRADING_DAYS literal is positive and finite: {e}")) // scan-banned: allow -- `dec!()` literal, `Err` arm has no reachable input; see MIN_VOLATILITY
});

/// Standard number of trading hours in a market day as a `Positive` decimal.
///
/// Typically represents a standard U.S. market session (9:30 AM to 4:00 PM).
pub static TRADING_HOURS: LazyLock<Positive> = LazyLock::new(|| {
    Positive::new_decimal(dec!(6.5))
        .unwrap_or_else(|e| unreachable!("TRADING_HOURS literal is positive and finite: {e}")) // scan-banned: allow -- `dec!()` literal, `Err` arm has no reachable input; see MIN_VOLATILITY
});

/// Number of seconds in an hour as a `Positive` decimal value.
///
/// Used for time-based conversions and calculations.
pub static SECONDS_PER_HOUR: LazyLock<Positive> = LazyLock::new(|| {
    Positive::new_decimal(dec!(3600.0))
        .unwrap_or_else(|e| unreachable!("SECONDS_PER_HOUR literal is positive and finite: {e}")) // scan-banned: allow -- `dec!()` literal, `Err` arm has no reachable input; see MIN_VOLATILITY
});

/// Number of minutes in an hour as a `Positive` decimal value.
///
/// Aliased to `positive::constants::SIXTY`, which already exists upstream —
/// no runtime initialization required.
pub const MINUTES_PER_HOUR: Positive = positive::constants::SIXTY;

/// Number of milliseconds in a second as a `Positive` decimal value.
///
/// Aliased to `positive::constants::THOUSAND`, which already exists upstream.
pub const MILLISECONDS_PER_SECOND: Positive = positive::constants::THOUSAND;

/// Number of microseconds in a second as a `Positive` decimal value.
///
/// No matching `positive::constants::*` entry for `1_000_000`, so the value
/// is built once via `LazyLock`.
pub static MICROSECONDS_PER_SECOND: LazyLock<Positive> = LazyLock::new(|| {
    Positive::new_decimal(dec!(1_000_000.0)).unwrap_or_else(|e| {
        unreachable!("MICROSECONDS_PER_SECOND literal is positive and finite: {e}") // scan-banned: allow -- `dec!()` literal, `Err` arm has no reachable input; see MIN_VOLATILITY
    })
});

/// Standard number of weeks in a year as a `Positive` decimal value.
///
/// Used for time-based financial calculations and annualization.
pub static WEEKS_PER_YEAR: LazyLock<Positive> = LazyLock::new(|| {
    Positive::new_decimal(dec!(52.0))
        .unwrap_or_else(|e| unreachable!("WEEKS_PER_YEAR literal is positive and finite: {e}")) // scan-banned: allow -- `dec!()` literal, `Err` arm has no reachable input; see MIN_VOLATILITY
});

/// Number of months in a year as a `Positive` decimal value.
///
/// Upstream `positive::constants` skips 11/12 in its integer ladder, so the
/// value is built once via `LazyLock`.
pub static MONTHS_PER_YEAR: LazyLock<Positive> = LazyLock::new(|| {
    Positive::new_decimal(dec!(12.0))
        .unwrap_or_else(|e| unreachable!("MONTHS_PER_YEAR literal is positive and finite: {e}")) // scan-banned: allow -- `dec!()` literal, `Err` arm has no reachable input; see MIN_VOLATILITY
});

/// Number of quarters in a year as a `Positive` decimal value.
///
/// Aliased to `positive::constants::FOUR`, which already exists upstream.
pub const QUARTERS_PER_YEAR: Positive = positive::constants::FOUR;

#[cfg(test)]
mod tests {
    use super::*;

    /// Forces every `LazyLock` in this file.
    ///
    /// The `unreachable!` arms above are justified by the literals beside
    /// them being strictly positive and finite, which is true of the literals
    /// as written and of nothing else: `LazyLock` initialises at first
    /// access, at run time, so an edit that makes one of these literals zero
    /// or negative compiles cleanly and aborts on whichever request touches
    /// it first. Unlike a `const` item, the compiler does not check
    /// the premise.
    ///
    /// Dereferencing each one here moves that failure into the test suite,
    /// where a bad literal is a red run rather than a dead worker. It is what
    /// makes the markers honest rather than merely reviewed.
    #[test]
    fn test_every_lazy_constant_initialises() {
        for (name, value) in [
            ("MIN_VOLATILITY", *MIN_VOLATILITY),
            ("TRADING_DAYS", *TRADING_DAYS),
            ("TRADING_HOURS", *TRADING_HOURS),
            ("SECONDS_PER_HOUR", *SECONDS_PER_HOUR),
            ("MICROSECONDS_PER_SECOND", *MICROSECONDS_PER_SECOND),
            ("WEEKS_PER_YEAR", *WEEKS_PER_YEAR),
            ("MONTHS_PER_YEAR", *MONTHS_PER_YEAR),
        ] {
            assert!(
                value > Positive::ZERO,
                "{name} must be strictly positive, or its unreachable arm is reachable"
            );
        }
    }
}