<h1 align="center">
<a href="https://crates.io/crates/rslife">
<picture>
<source srcset="https://raw.githubusercontent.com/hnlearndev/static/refs/heads/main/rslife/banner/banner_dark.svg" media="(prefers-color-scheme: dark)">
<img src="https://raw.githubusercontent.com/hnlearndev/static/refs/heads/main/rslife/banner/banner_light.svg" alt="RSLife logo">
</picture>
</a>
</h1>
<div align="center">
[](https://crates.io/crates/rslife)
[](https://docs.rs/rslife/latest/rslife/)
[](https://app.codecov.io/gh/hnlearndev/rslife)
| **MSRV** | [](https://github.com/hnlearndev/rslife/actions/workflows/rust-1.90.0.yml) | [](https://github.com/hnlearndev/rslife/actions/workflows/rust-1.90.0.yml) |
| **Stable** | [](https://github.com/hnlearndev/rslife/actions/workflows/rust-stable.yml) | [](https://github.com/hnlearndev/rslife/actions/workflows/rust-stable.yml) |
| **Nightly** | [](https://github.com/hnlearndev/rslife/actions/workflows/rust-nightly.yml) | — |
</div>
---
A comprehensive Rust library for actuarial mortality table calculations and life insurance mathematics, featuring an elegant **builder pattern** that makes complex actuarial calculations intuitive and type-safe.
## Why RSLife?
**🚀 Performance & Memory Efficiency:**
- Leveraging Rust's zero-cost abstractions for maximum performance
- Polars integration for efficient DataFrame operations with zero-copy optimization
- Minimal memory allocation with smart data reuse and lazy evaluation
- Compile-time optimizations eliminate runtime overhead
**🎯 Developer Experience:**
- **Intuitive Builder Pattern**: Only specify parameters you need, no confusing parameter lists. RSLife ensures that the low level interfaces are even more approachable than the high level ones.
- **Type Safety**: Compile-time validation prevents common actuarial calculation errors
- **Auto-Completion**: IDEs provide intelligent suggestions for all parameters
- **Self-Documenting**: Parameter names make code intent crystal clear
- **Cross-Field Validation**: Parameter combinations validated automatically
**📊 Intelligent Data Processing:**
- **Universal Input**: DataFrames, XLSX/ODS files, and loading directly from Society of Actuary (US) and Institute and Faculty of Actuaries (UK) Mortality Database with automatic format detection
- **Format Agnostic**: Seamlessly detects `qx` rates or `lx` survivor functions without manual specification
- **Smart Table Recognition**: Automatically determines ultimate vs select mortality tables
- **Validation Built-In**: Comprehensive data integrity checks prevent runtime errors before calculations
- **Select & Ultimate**: Full support for both table types with automatic recognition
**🔧 Production Ready:**
- **Complete Actuarial Coverage**: Life insurance, annuities,survival functions and commutations with standard notation
- **Multiple Assumptions**: Uniform Death Distribution (UDD), Constant Force of Mortality (CFM), and Hyperbolic (HPB) methods for fractional age calculations
- **Multiple Parametric Life Table Models**: Constant Force Law, Gompertz, and Makeham, Weibull etc...
- **Consistent API**: All functions use the same parameter structure with builder pattern
- **Battle-Tested**: Validated against standard actuarial references from SOA and IFOA most trusted materials.
- **Error Handling**: Clear, actionable error messages for debugging
## Quick Start
Add the crate dependency
```bash
cargo add rslife
```
Or add this to your `Cargo.toml`:
```toml
[dependencies]
rslife = "0.2.13"
```
The crate is designed with three main layers to make actuarial computations convenient (more on [architecture from Wiki](https://github.com/hnlearndev/rslife/wiki/Architecture)), as illustrated below:
```rust
use rslife::prelude::*;
fn main() -> RSLifeResult<()> {
// ========= FIRST LAYER - MORTALILITY DATA LOAD=========
// Load mortality data
// This seperation layer consists of multiple methods with flexibility at user hand to formulate the mortality or morbidity data
let data = MortData::from_builtin("AM92")?;
// ========= SECOND LAYER - MORTALILITY TABLE CONFIGURATION =========
// Construct Mortality Table Config
// This layer is more rigid but still allows some configuration to mortality table
let mt = MortTableConfig::builder()
.data(data)
.radix(100_000) // Radix of 100k instead of default 10k
.pct(1.5) // 150% mortality rate instead of default 100%
.assumption(AssumptionEnum::CFM) // CFM assumption instead of default UDD assumtpion
.build()?;
// ========= THIRD LAYER - CALCULATIONS =========
// New builder pattern for actuarial calculations!
// This is the layer to perform calculation. Variables are only declared when needed - Consistent with actuarial notation principle.
let fractional_age_time_survival_rate = tpx()
.mt(&mt)
.x(35.5)
.t(5.8)
.entry_age(33)
.call()?;
let life_annuity = aax()
.mt(&mt)
.i(0.03)
.x(65.0)
.m(12) // monthly payable m=12
.call()?;
let deferred_term = Ax1n()
.mt(&mt)
.i(0.03)
.x(35.0)
.n(15.0)
.entry_age(34) // Entry age for selected effect - duration
.t(5.0) // Deferred 5 years
.call()?;
Ok(())
}
```
## Data sources - Layer 1 in zoom
RSLife supports flexible mortality data input with automatic `qx`/`lx` detection.
Detail guide can be found on project [wiki](https://github.com/hnlearndev/rslife/wiki)
An example of parametric life table model
```rust
// Parametric life table model
let makeham_model_data = MortData::from_Makeham_law()
.A(0.00022)
.B(2.7e-6)
.C(1.124)
.start_age(20)
.call()?;
```
Life table can also be formulated from dataframe
```rust
// DataFrames - mortality rates or survivor functions
// qx data
let df_qx = df! {
"age" => [25_u32, 26, 27],
"qx" => [0.001_f64, 0.0012, 0.0015],
}?;
let data_from_df_with_qx = MortData::from_df(df_qx)?;
// lx data
let df_lx = df! {
"age" => [25_u32, 26.0, 27.0],
"lx" => [100000.0_f64, 99900.0, 99780.0],
}?;
let data_from_df_with_lx = MortData::from_df(df_lx)?;
// Macro to directly form MortData
// This is equivalent to forming dataframe then using from_df method
let data_from_macro = mddf! {
"age" => [25_u32, 26, 27],
"qx" => [0.001_f64, 0.0012, 0.0015],
}
```
There are various other methods to formulate life table. For examples, from spreadsheets
```rust
// Custom data from spreadsheet XLSX
let data_from_xlsx = MortData::from_xlsx("data/mortality.xlsx", "select")?;
// Custom data from spreadsheet ODS
let data_from_ods = MortData::from_ods("data/mortality.ods", "select")?;
```
Direct ingestion from SOA, IFOA and Australian Government Actuary mortality and morbidity database
More direct API are coming in the next releases. Please feel free to suggest your favorite database.
```rust
// ELT No.15 Female
let data_from_soa = MortData::from_soa_url_id(1704)?;
// AM92 Selected Mortality Table
let data_from_ifoa = MortData::from_ifoa_url_id("AM92")?;
// Male mortality rate in 2020-2022
let data_from_aga = MortData::from_aus_gov_act("Male", "2020-22")?;
```
### Built-in Tables
For frequently used tables, RSLife provides a preloaded cache via `MortData::from_builtin(id)`. The tables are loaded once on first access and shared across all subsequent calls — avoiding repeated I/O or network overhead.
```rust
// IFOA tables
let am92 = MortData::from_builtin("AM92")?;
let af92 = MortData::from_builtin("AF92")?;
let pfa92 = MortData::from_builtin("PFA92")?;
let pma92 = MortData::from_builtin("PMA92")?;
// IFOA projected tables (C10 / C20)
let pfa92c10 = MortData::from_builtin("PFA92C10")?;
let pma92c10 = MortData::from_builtin("PMA92C10")?;
let pfa92c20 = MortData::from_builtin("PFA92C20")?;
let pma92c20 = MortData::from_builtin("PMA92C20")?;
// SOA tables
let elt15_f = MortData::from_builtin("ELT15_F")?;
let elt15_m = MortData::from_builtin("ELT15_M")?;
let sult = MortData::from_builtin("SULT")?;
```
| `AM92` | IFOA | Male Assured Lives, 1991–94 experience |
| `AF92` | IFOA | Female Assured Lives, 1991–94 experience |
| `PFA92` | IFOA | Female Pensioners, 1991–94 experience |
| `PMA92` | IFOA | Male Pensioners, 1991–94 experience |
| `PFA92C10` | IFOA | Female Pensioners, projected to year 2010 |
| `PMA92C10` | IFOA | Male Pensioners, projected to year 2010 |
| `PFA92C20` | IFOA | Female Pensioners, projected to year 2020 |
| `PMA92C20` | IFOA | Male Pensioners, projected to year 2020 |
| `ELT15_F` | SOA | English Life Table No. 15, Female |
| `ELT15_M` | SOA | English Life Table No. 15, Male |
| `SULT` | SOA | Standard Ultimate Life Table |
## The Builder Pattern Advantage - IMMERSE in C4 principles
RSLife with its builder pattern, founded on 💥<span style="color: #FF0000; font-weight: bold">C4</span>💥 pillars - _Clear_, _Concise_, _Coherent_ and _Comprehensive_, enhances actuarial developer experience (DX), letting you 🌊<span style="color: #27ae60; font-weight: bold">IMMERSE</span>🌊 yourselves in what truly matters for the core actuarial computation.
- **🎯 <span style="color: #27ae60; font-weight: bold">I</span>ntentional**: Only specify parameters that matter for each calculation
- **🗒️ <span style="color: #27ae60; font-weight: bold">M</span>anageable**: Avoid clutter from declaring all parameters
- **🔧 <span style="color: #27ae60; font-weight: bold">M</span>aintainable**: Adding new parameters doesn't break existing code
- **⚡ <span style="color: #27ae60; font-weight: bold">E</span>fficient**: Automatic cross-field validation catches errors early
- **📖 <span style="color: #27ae60; font-weight: bold">R</span>eadable**: Self-documenting code that's easy to understand
- **🔒 <span style="color: #27ae60; font-weight: bold">S</span>afe**: Compile-time validation prevents parameter mistakes
- **🧁 <span style="color: #27ae60; font-weight: bold">E</span>ffortless**: Capable to construct complex calculations with minial code
**vs. Traditional Approaches:**
```rust
// ❌ Other libraries: **verbose** structs, need to declare all parameters, easy to mess up order
let params = ComplexConfig {
mt: config,
i: 0.03,
x: 35,
n: None,
t: 10,
m: 1,
moment: 1,
entry_age: None,
};
// ❌ What does this even mean? Not intuitive but a common practise
let result = some_function(&config, 35, 0.03, 1, 0, 1, 1, Some(30))?;
// ✅ RSLife: crystal clear, only specify what matters
let result = Ax()
.mt(&config)
.i(0.03)
.x(35.0)
.entry_age(34)
.call()?;
```
## Actuarial Functions & Naming Convention
### Function Structure
**Systematic Modifiers**:
- **Immediate / In arrears**: Single letter → `Ax`, `Axn` (payments at end of year)
- **Due / In advance**: Double letter → `aax`, `aaxn` (payments at start of year)
- **Increasing**: `I` prefix → `IAx`, `Iaax` (arithmetic growth)
- **Decreasing**: `D` prefix → `DAx1n`, `Daaxn` (arithmetic decrease)
- **Geometric**: `g` prefix → `gAx`, `gaax` (geometric growth)
These modifiers are applicable to most but not all functions. (eg: There is no modified version for Exn/Axn1 - pure endowment function)
All functions now use the builder pattern with `SingleLifeParams` and `SurvivalFunctionParams` for consistent parameter passing and automatic validation.
### Full list of actuarial functions available via `rslife::prelude::*`
**Cetain annuities:**
Present value and future value
- `aan`, `an`, `ssn`,`sn`
- `Iaan`, `Ian`, `Issn`, `Isn`,
- `Daan`, `Dan`, `Dssn`, `Dsn`,
**Annuities:**
Due/In-advance version:
- `aax`, `aaxn`
- `Iaax`, `Iaaxn`
- `Daaxn`
- `gaax`, `gaaxn`
Immediate/In-arrears version:
- `ax`, `axn`
- `Iax`, `Iaxn`
- `Daxn`
- `gax`, `gaxn`
**Benefits and Life Insurance:**
- `Ax`, `Ax1n`, `Exn` or `Axn1`, `Axn`
- `IAx`, `IAx1n`, `IAxn`
- `DAx1n`, `DAxn`
- `gAx`, `gAx1n`, `gExn`, `gAxn`
**Survival Probabilities:**
- `tpx`, `tqx`, `lx`, `dx`
**Commutation:**
- `Cx`, `Dx`, `Mx`, `Nx`, `Rx`, `Sx`
All functions are developed following Test-Driven Development principles, using the most trusted reference materials from SOA and IFOA.
The package is also routinely re-tested by solving the latest actuarial examination problems.
## Examples
Check out the `examples/` directory for comprehensive examples:
- **`basic_usage.rs`** - Demonstrates basic usage of the package.
- **`cm1_april_2025.rs`** - Using RSLife package to provide solution for [CM1 exam from IFOA](https://actuaries.org.uk/qualify/curriculum/actuarial-mathematics/).
These examples will be updated when CM1 papers and examiners' report are published.
Not all the questions are part of the demonstration unless they are relevant to acturial computation features of the package.
SOA examination materials are also under consideration to be added as a re-testing medium in the near future.
```bash
# Basic usage example
cargo run --example basic_usage
# CM1 exams solution using RSLife
cargo run --example cm1_apr_2025
cargo run --example cm1_sep_2025
```
## Contributing
Regardless of technical background, if you have a domain knowledge on actuarial computation, you are more than welcomed! Please feel free to submit a Pull Request.
For major changes, please open an issue first to discuss what you would like to change.
## License
This project is dual-licensed under the Apache License, Version 2.0 and the MIT License.
You may choose either license when using this code.
See [](./LICENSE-APACHE) and [](./LICENSE-MIT) for details.
## Contact
**Willian Nguyen** - [hieunt(dot)hello(at)gmail(dot)com](mailto:)
**Project link** - [https://github.com/hnlearndev/rslife](https://github.com/hnlearndev/rslife)
## References
- [Actuarial Mathematics for Life Contingent Risks](https://www.goodreads.com/book/show/58306503-actuarial-mathematics-for-life-contingent-risks)
- [Actuarial Mathematics](https://www.goodreads.com/book/show/1715653.Actuarial_Mathematics)
- [Society of Actuaries Mortality and Morbidity Tables](https://mort.soa.org)
- [Institute and Faculty of Actuaries Mortality and Morbidity Tables](https://www.actuaries.org.uk/learn-and-develop/continuous-mortality-investigation/cmi-mortality-and-morbidity-tables)
- [Australian Government Actuary](https://aga.gov.au)
- Standard actuarial notation and practices
## Similar Projects
**Python:**
- [pyliferisk](https://github.com/franciscogarate/pyliferisk) - Python library for actuarial calculations and life insurance mathematics
- [pymort](https://github.com/actuarialopensource/pymort) - Python mortality table library with XML parsing capabilities
**R:**
- [lifecontingencies](https://github.com/spedygiorgio/lifecontingencies) - R package for actuarial life contingencies calculations
- [MortalityTables](https://github.com/kainhofer/r-mortality-tables) - R package for working with life and pension tables
- [demography](https://github.com/robjhyndman/demography) - R package for demographic analysis and mortality forecasting
**Julia:**
- [MortalityTables.jl](https://github.com/JuliaActuary/MortalityTables.jl) - Julia package for mortality table calculations and life contingencies
- [ActuaryUtilities.jl](https://github.com/JuliaActuary/ActuaryUtilities.jl) - Julia utilities for actuarial modeling and analysisk.
## Enjoy?
Let me know that you find the crate helpful. Thank you :D
[](https://github.com/sponsors/hnlearndev)
[](https://www.buymeacoffee.com/hnlearndev)