Skip to content

Architecture

Jump to bottom
Willian Nguyen edited this page Aug 4, 2025 · 9 revisions

Core Design Principles

1. Builder Pattern First

  • All actuarial functions use the builder pattern for parameter specification
  • Only required parameters need to be specified
  • Automatic parameter validation and cross-field validation
  • Type-safe construction prevents runtime errors

2. Zero-Cost Abstractions

  • Built on Rust's zero-cost abstractions
  • Compile-time optimizations eliminate runtime overhead
  • Memory-efficient operations with smart data reuse

3. Universal Data Input

  • Supports multiple data sources: DataFrames, XLSX/ODS, SOA XML, IFOA XLS
  • Automatic format detection (qx rates vs lx survivor functions)
  • Smart table recognition (ultimate vs select mortality tables)

Module Structure

rslife/
├── src/
│   ├── lib.rs                    # Main library entry point
│   ├── prelude.rs                # Re-exports for common usage
│   ├── mt_config.rs              # Mortality table configuration
│   ├── mt_data.rs                # Mortality data loading and processing
│   ├── params.rs                 # Parameter validation structs
│   ├── helpers.rs                # Utility functions
│   ├── xml.rs                    # SOA XML parsing
│   ├── int_rate_convert.rs       # Interest rate conversions
│   ├── annuities_certain.rs      # Certain annuities (no mortality)
│   ├── single_life/              # Single life actuarial functions
│   │   ├── annuities.rs          # Life annuity functions
│   │   ├── benefits.rs           # Life insurance benefit functions
│   │   ├── commutations.rs       # Commutation functions (Dx, Cx, Mx, Nx, Rx, Sx)
│   │   ├── survivals.rs          # Survival probability functions
│   │   └── ...                   # Other actuarial logic
│   └── ...                       # Additional modules as needed
├── data/                         # Example mortality tables and input data
├── diagrams/                     # Actuarial function diagrams and visualizations
├── docs/                         # Documentation (including ARCHITECTURE.md)
├── tests/                        # Integration and unit tests
└── examples/                     # Usage examples and demos

Data Flow Architecture

1. Data Loading Layer

MortData::from_soa_url_id(1704)     // SOA XML
MortData::from_ifo_url_id("AM92")   // IFOA XLS
MortData::from_xlsx("file.xlsx")    // Excel files
MortData::from_ods("file.ods")      // Excel files
MortData::from_df(dataframe)        // Polars DataFrame

MortData is constructed as a seperate layer to maximize its flexibility and capacity to handle multiple data sources.

There are also various other methods to help users to:

  • directly access data from SOA XML files (locally or via internet)
  • directly access data from IFOA xls files (locally or via internet)
  • other methods to handle their own custom data

More details on discussion to different ways to access data can be found at.

2. Configuration Layer

MortTableConfig::builder()
    .data(mort_data)
    .radix(100_000)                      // Using 100k instead of default 10k                   
    .pct(1.2)                           // Using 120% mortality instead of default 100%
    .assumption(AssumptionEnum::CFM)   // Using CFM instead of default UDD
    .build()
  • Central configuration object for all calculations
  • Holds mortality data, assumptions, and adjustments
  • Supports both ultimate and select mortality tables
  • Automatic validation of configuration parameters
  • Include methods to retrieve information from mortality table

3. Calculation Layer

Ax().mt(&config).i(0.04).x(35).call()?   // Life insurance

aax().mt(&config).i(0.04).x(65).call()?  // Annuities

tpx().mt(&config).x(35.0).t(5.0).call()? // Survival

Rx().mt(&config).i(0.06).x(27).call()? // Commutation

Parameter validation

  • SingleLifeParams: Validates parameters for life insurance and annuity calculations
  • SurvivalFunctionParams: Validates parameters for survival probability calculations
  • Cross-field validation ensures parameter combinations are valid
  • Early error detection prevents invalid calculations

Dependencies

Core Dependencies

  • Polars: DataFrame operations and data processing
  • bon: Builder pattern implementation
  • garde: Parameter validation
  • calamine: Excel file reading
  • roxmltree: XML parsing for SOA data
  • reqwest: HTTP requests for SOA data

Development Dependencies

  • approx: Floating-point comparisons in tests
  • Standard Rust testing framework

Future Architecture Considerations

Multi-Life Extensions

  • Joint life calculations
  • Survivor annuities
  • Last survivor benefits

Advanced Features

  • Stochastic mortality models
  • Economic scenario generation
  • Cash flow projections

Performance Enhancements

  • SIMD optimizations for bulk calculations
  • Parallel computation for independent calculations
  • GPU acceleration for large-scale computations
Clone this wiki locally