Mathematical Correctness

Topic: contributing.correctness

Mathematical correctness is Priority Level 1. Nothing else matters if the math is wrong. Covers validation, edge cases, symbol assumptions, numerical precision, and domain restrictions.

Mathematical Correctness

Mathematical correctness is Priority Level 1. Nothing else matters if the math is wrong.

Why This Is Non-Negotiable

MathHook is used by:

• Students learning mathematics
• Engineers making calculations
• Researchers validating results

A wrong answer doesn't just fail—it actively harms users who trust it.

If sin(π) returns 1.2246e-16 instead of 0:

• A student learns wrong
• An engineer's calculation is off
• A researcher's proof is invalid

There is no acceptable rate of mathematical errors. Zero is the only target.

Core Principles

1. Never ship incorrect math to fix a bug elsewhere
2. Never sacrifice correctness for performance
3. Never assume—verify against SymPy
4. Test edge cases obsessively
5. Domain errors must be caught, not silently wrong

Validation Process

Before Implementation

# Verify against SymPy
python3 -c "
from sympy import *
x = Symbol('x')
print(simplify(sin(x)**2 + cos(x)**2))
"

After Implementation

./scripts/validate.sh           # All validations
./scripts/validate.sh simplify  # Specific module

Edge Cases (ALWAYS Test)

Symbol Assumptions

Symbols carry assumptions that affect correctness:

#![allow(unused)]
fn main() {
// sqrt(x^2) depends on assumptions about x
let x = symbol!(x);  // Unknown sign

// sqrt(x^2) = |x|, not x (unless x is positive)
let x_positive = symbol!(x).with_assumption(Assumption::Positive);
// Now sqrt(x^2) = x is correct
}

Assumption Categories

Numerical Precision

Float Comparison

#![allow(unused)]
fn main() {
// ❌ NEVER - Floating point equality is unreliable
if result == 0.0 { ... }

// ✅ ALWAYS - Use epsilon comparison
const EPSILON: f64 = 1e-10;
if result.abs() < EPSILON { ... }
}

Exact vs Approximate

#![allow(unused)]
fn main() {
// Symbolic π must give exact results
sin(Expression::pi())  // Must return exactly 0, not 1.2246e-16

// Only use floats for numerical approximation
expr!(3.14159)  // Approximate - loses exactness
Expression::pi()  // Symbolic - maintains exactness
}

Complex Numbers

Branch Cuts

Default Behavior

#![allow(unused)]
fn main() {
// Complex-safe by default
sqrt(&expr!(-1))  // Returns i, not NaN or error
}

Domain Restrictions

Error Handling for Domain Violations

#![allow(unused)]
fn main() {
pub fn log(arg: &Expression) -> Result<Expression, MathError> {
    // Check for zero
    if arg.is_zero() {
        return Err(MathError::DomainError {
            operation: "log".into(),
            value: arg.clone(),
            reason: "logarithm of zero is undefined".into(),
        });
    }

    // Check for negative (if real mode)
    if arg.is_negative_real() {
        return Err(MathError::DomainError {
            operation: "log".into(),
            value: arg.clone(),
            reason: "logarithm of negative real requires complex mode".into(),
        });
    }

    // Continue with evaluation...
}
}

Simplification Rules

Order of Operations

1. Canonicalize - Flatten, sort, remove identity elements
2. Apply identities - Combine like terms, power rules, trig
3. Numerical evaluation - Only if explicitly requested

Idempotence Requirement

#![allow(unused)]
fn main() {
// Simplification must be idempotent
let once = simplify(&expr);
let twice = simplify(&once);
assert_eq!(once, twice);  // Must be equal
}

Canonical Forms

Common Errors to Avoid

Reference Materials

For complex cases, consult:

1. Abramowitz & Stegun - Handbook of Mathematical Functions
2. DLMF - Digital Library of Mathematical Functions
3. SymPy source - For implementation details

Examples

API Reference

• Rust: ``
• Python: ``
• JavaScript: ``

See Also

• contributing.testing

• contributing.development

• contributing.architecture-reference