g_math 0.7.0

Deterministic fixed-point arithmetic, every format a type: correctly rounded transcendentals, decimal and symbolic domains, linear algebra, Lie groups, manifolds, ODE solvers, certified intervals. Pure Rust, zero-float
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

//! Canonical FASC Entry Point
//!
//! **THIS IS THE PRIMARY API FOR gMath.**
//!
//! All arithmetic flows through:
//! `gmath("value") → LazyExpr → StackEvaluator → StackValue → Domain dispatch`
//!
//! ## Quick Start
//!
//! ```rust
//! use g_math::canonical::{gmath, evaluate, LazyExpr};
//! use g_math::fixed_point::Q64_64;
//!
//! // Build expressions (zero allocation, deferred evaluation)
//! let result = gmath("1.5") + gmath("2.5");
//!
//! // Evaluate in a format (the thread-local evaluator for that format)
//! let value = evaluate::<Q64_64>(&result).unwrap();
//! println!("{}", value);  // "4.0000000000000000000"
//! ```
//!
//! ## Chaining Results (Compound Interest Example)
//!
//! ```rust
//! use g_math::canonical::{gmath, evaluate, LazyExpr};
//! use g_math::fixed_point::Q64_64;
//!
//! let rate = gmath::<Q64_64>("1.05"); // 5% annual rate
//! let mut balance = evaluate::<Q64_64>(&gmath("1000.00")).unwrap();
//!
//! for year in 1..=5 {
//!     // Feed previous result back in: full precision + shadow preserved
//!     balance = evaluate(&(LazyExpr::from(balance) * gmath("1.05"))).unwrap();
//!     println!("Year {}: {:.2}", year, balance);
//! }
//! ```
//!
//! ## Transcendentals
//!
//! ```rust
//! use g_math::canonical::{gmath, evaluate};
//! use g_math::fixed_point::Q64_64;
//!
//! let e = evaluate::<Q64_64>(&gmath("1.0").exp()).unwrap();     // e^1 = 2.718...
//! let ln2 = evaluate::<Q64_64>(&gmath("2.0").ln()).unwrap();    // ln(2) = 0.693...
//! let root = evaluate::<Q64_64>(&gmath("2.0").sqrt()).unwrap();  // sqrt(2) = 1.414...
//! println!("{}", e);    // "2.7182818284590452353"
//! ```
//!
//! ## Runtime Strings
//!
//! ```rust
//! use g_math::canonical::{gmath_parse, evaluate, LazyExpr};
//!
//! let user_input = String::from("3.14");
//! let parsed = gmath_parse::<g_math::fixed_point::Q64_64>(&user_input).unwrap();
//! let result = evaluate(&parsed.sin()).unwrap();
//! ```
//!
//! ## Architecture
//!
//! - **LazyExpr**: Expression tree builder with operator overloading
//! - **StackEvaluator**: Thread-local evaluator with fixed-size workspace
//! - **StackValue**: Domain-tagged result (Binary | Decimal | Ternary | Symbolic)
//! - **gmath()**: Entry point for static strings: zero-cost, deferred parsing
//! - **gmath_parse()**: Entry point for runtime strings: eager parsing
//! - **LazyExpr::from(StackValue)**: Chain results into new expressions (zero precision loss)

// Re-export the complete FASC API
pub use super::universal::fasc::{
    LazyExpr,
    LazyMatrixExpr,
    DomainMatrix,
    gmath,
    gmath_parse,
    ConstantId,
    StackEvaluator,
    StackValue,
    evaluate,
    evaluate_matrix,
    evaluate_sincos,
    evaluate_sinhcosh,
    with_evaluator,
    FascFormat,
    GmathMode,
    ComputeMode,
    OutputMode,
};

// Re-export shadow types for public API
pub use super::universal::tier_types::{CompactShadow, ShadowConstantId};

/// Set compute:output mode. Examples: "binary:ternary", "auto:auto", "decimal:binary"
pub fn set_gmath_mode(mode_str: &str) -> Result<(), &'static str> {
    let mode = GmathMode::from_str(mode_str)?;
    super::universal::fasc::mode::set_mode(mode);
    Ok(())
}

/// Reset to default Auto:Auto mode
pub fn reset_gmath_mode() {
    super::universal::fasc::mode::reset_mode();
}

// ============================================================================
// PRE-PARSED CONSTRUCTORS (called by gmath!() proc-macro)
// ============================================================================

/// Construct a pre-parsed Decimal LazyExpr. Called by `gmath!("0.1")` expansion.
///
/// Skips runtime string parsing: dp, scaled value, and shadow are computed
/// at compile time by the proc-macro. ~60 ns faster than `gmath("0.1")`.
#[doc(hidden)]
pub fn __pre_decimal<T: FascFormat>(dp: u8, scaled: i128, shadow_num: i128, shadow_den: u128) -> LazyExpr<T> {
    use super::domains::symbolic::rational::RationalNumber;
    let shadow = CompactShadow::from_rational(shadow_num, shadow_den);
    match T::try_to_binary_storage(scaled) {
        Ok(storage) => LazyExpr::Value(Box::new(StackValue::Decimal(dp, storage, shadow))),
        // beyond the format's decimal storage: the exact rational, as the
        // runtime parser does (this narrowed with a wrapping cast)
        Err(_) => LazyExpr::Value(Box::new(StackValue::Symbolic(
            RationalNumber::new(scaled, 10u128.pow(dp as u32)),
        ))),
    }
}

/// Construct a pre-parsed Binary integer LazyExpr. Called by `gmath!("255")` expansion.
#[doc(hidden)]
pub fn __pre_integer<T: FascFormat>(value: i128) -> LazyExpr<T> {
    use super::domains::symbolic::rational::RationalNumber;
    let shadow = CompactShadow::from_rational(value, 1);
    match T::integer_value(value) {
        Some(storage) => LazyExpr::Value(Box::new(StackValue::Binary(T::MAX_BINARY_TIER, storage, shadow))),
        // beyond the integer range of the storage word: the exact rational,
        // as the runtime parser does (this shifted with a wrapping cast)
        None => LazyExpr::Value(Box::new(StackValue::Symbolic(RationalNumber::from_ratio(value, 1)))),
    }
}