ProbabilityEngine

A comprehensive Swift library for probability theory, statistics, and Bayesian inference.

ProbabilityEngine provides a type-safe, modular framework for performing probability calculations, statistical analysis, and Monte Carlo simulations on Apple platforms.

---

Features

• Combinatorics — Factorials, permutations, combinations (with/without repetition), and multinomial coefficients with overflow-safe arithmetic
• Statistical Distributions — Discrete (Binomial, Poisson, Geometric) and continuous (Normal, Exponential) distributions with PDF, CDF, quantiles, and moment calculations
• Event Operations — Set-theory operations including complement, union, intersection, and conditional probability
• Bayesian Inference — Simple posterior calculation, binary hypothesis testing, multi-hypothesis inference, and sequential Bayesian updating
• Monte Carlo Simulations — Actor-based async simulator with progress tracking, cancellation support, and Accelerate-optimized performance
• Educational Explanations — Step-by-step explanations for all major calculations in plain text or Markdown format
• Type-Safe Design — Probability wrapper type guarantees valid values in [0, 1], with Result-based error handling throughout

---

Technologies Used

Category	Technology
Language	Swift 6.0
Build System	Swift Package Manager
Concurrency	Swift async/await, Actors
Performance	Apple Accelerate (vDSP)
Precision	Foundation Decimal

No external dependencies — pure Swift implementation using only system frameworks.

---

Requirements

• macOS 13.0+ / iOS 16.0+ / watchOS 9.0+ / tvOS 16.0+
• Xcode 16.0+
• Swift 6.0+

---

Installation

Swift Package Manager

Add ProbabilityEngine to your Package.swift:

dependencies: [
    .package(url: "https://github.com/your-username/ProbabilityEngine.git", from: "1.0.0")
]

Then add the dependency to your target:

.target(
    name: "YourTarget",
    dependencies: ["ProbabilityEngine"]
)

You can import the umbrella module or individual modules as needed:

import ProbabilityEngine    // All modules
import Combinatorics        // Just combinatorics
import Statistics           // Just distributions
import Bayesian             // Just Bayesian inference

---

Usage

Combinatorics

let calc = CombinatoricsCalculator()

// Combinations: C(52, 5) - poker hands
let result = calc.combinations(n: 52, k: 5)
if case .success(let value) = result {
    print("Poker hands: \(value)")  // 2,598,960
}

// Permutations with repetition
let pins = calc.permutationsWithRepetition(n: 10, k: 4)  // 10,000

Statistical Distributions

// Normal distribution
let normal = NormalDistribution(mean: 100, stdDev: 15)
let probability = normal.cdf(115)           // P(X <= 115)
let zScore = normal.zScore(for: 130)        // 2.0
let quantile = normal.quantile(0.95)        // 95th percentile

// Binomial distribution
let binomial = BinomialDistribution(n: 10, p: 0.5)!
let exactProb = binomial.pmf(5)             // P(X = 5)

Bayesian Inference

let bayes = BayesianCalculator()

// Medical test: 1% disease prevalence, 95% sensitivity, 5% false positive
let result = bayes.binaryPosterior(
    priorH: 0.01,
    sensitivityEGivenH: 0.95,
    falsePositiveEGivenNotH: 0.05
)

if case .success(let posterior) = result {
    print("P(disease|positive test): \(posterior)")  // ~0.16
}

Monte Carlo Simulation

let simulator = MonteCarloSimulator()

// Estimate probability with progress tracking
let result = try await simulator.estimateProbability(
    config: SimulationConfig(iterations: 100_000)
) { rng in
    // Birthday paradox: 23 people, any shared birthday?
    var birthdays = Set<Int>()
    for _ in 0..<23 {
        let day = rng.nextInt(in: 0..<365)
        if birthdays.contains(day) { return true }
        birthdays.insert(day)
    }
    return false
}

print("Probability: \(result.successRate)")  // ~0.507

Explanations

let engine = ExplanationEngine()

if let explanation = engine.explainCombinations(n: 5, k: 2) {
    print(explanation.plainText)
    // Outputs step-by-step calculation with formulas
}

---

Architecture

ProbabilityEngine follows a modular architecture with seven specialized modules:

ProbabilityEngine (umbrella)
├── Shared          — Foundation types, protocols, error handling
├── Combinatorics   — Factorial, permutation, combination calculations
├── Statistics      — Probability distributions and special functions
├── Events          — Event operations and conditional probability
├── Bayesian        — Bayes' theorem implementations
├── MonteCarlo      — Actor-based simulation engine
└── Explanations    — Educational step-by-step explanations

Key Design Patterns:

• Protocol-Oriented — Calculator, Distribution, Simulatable protocols enable polymorphism
• Result-Based Error Handling — All calculations return Result<T, CalculationError>
• Type-Safe Wrappers — Probability struct guarantees valid probability values
• Actor Isolation — MonteCarloSimulator uses Swift actors for thread safety