User Guide

This guide covers all aspects of using Lactuca for actuarial calculations in Python.

Getting started

• Getting Started
  • Installation
  • Activation
  • Bundled tables (one-time setup)
  • Quick example
  • How Lactuca is organised
  • Actuarial table types
  • Loading a table
  • Survival and mortality probabilities
  • Life expectancy
  • Commutation functions
  • Interest rates
  • Growth rates
  • Configuration
  • Life annuities
  • Life insurances
  • Disability tables
  • Exit tables
  • Functional API
  • Time shift (ts) for off-anniversary reserves
  • Next steps
  • Support

Working with AI assistants

Use Lactuca with Cursor, Copilot, ChatGPT, and other assistants — context files and workflows.

• Working with AI assistants
  • Professional responsibility
  • Verifying AI-generated code
  • What these files are / are not
  • Download the context pack
  • Match docs to your installed version
  • Quick start
  • Cursor
  • VS Code + GitHub Copilot
  • ChatGPT / Claude / Gemini
  • Prompt templates
  • Portfolio and batch work
  • Updating context when you upgrade Lactuca
  • Further reading

Foundations

• Notation and Glossary
  • Life table symbols
  • Decrements
  • Interest rate symbols
  • Multi-scenario rate containers
  • Commutation functions
  • Life annuity symbols
  • Life insurance symbols
  • Calculation parameters
  • Calculation modes
  • Force of mortality methods
  • Other terms
• lx Interpolation
  • Interpolation assumptions
  • Configuration in Lactuca
  • Fractional survival probabilities
  • Example: monthly survival
  • Example: fractional starting age
  • Continuous calculations
  • Scope of effect
  • Numerical comparison: UDD vs CFM
  • Integer commutations vs fractional survival
  • See also

Configuration

• Configuration
  • Mental model
  • Accessing the singleton
  • Reading configuration values
  • Updating values
  • Decimal settings via decimals proxy
  • Persistence methods (TOML)
  • Reset methods and singleton lifecycle
  • Recommended usage patterns
  • Settings reference
  • TOML file layout
  • See also

Tables

How to work with actuarial tables in Lactuca.

• Table Taxonomy
  • Aggregate – Static
  • Aggregate – Generational
  • Select-Ultimate tables: actuarial context
  • Select-Ultimate — duration indexing
  • Select-Ultimate – Static
  • Select-Ultimate – Generational
  • How each table maps to this taxonomy
  • See also
• Bundled Actuarial Tables
  • Managing bundled tables
  • Need a table that is not listed here?
  • Table reference
  • See also
• Using Actuarial Tables
  • Quick recap: the three table classes
  • Default interest rate
  • Vectorial creation
  • Bulk portfolio calculations
  • Deferred construction: pending, configure, and TableRegistry
  • Decimal precision
  • Table properties
  • See also
• Building Custom Table Files (.ltk)
  • Column names and input formats
  • Common construction parameters
  • Single-rate and sex-independent tables
  • Aggregate – Static tables
  • Aggregate – Generational tables
  • Select-Ultimate – Static tables
  • Select-Ultimate – Generational tables
  • Inspecting a TableBuilder
  • Loading, round-tripping and cloning
  • TableBuilder parameter reference
  • See also
• Mortality Improvement (MI)
  • What is mortality improvement?
  • Projection formulas
  • Constant vs. year-indexed MI factors
  • Improvement in practice
  • MI and the select-ultimate structure
  • Processing multiple cohort groups with configure()
  • See also
• Modifying Decrements
  • Method names per table type
  • Core semantics
  • State and lifecycle
  • Available modification keys
  • Combining modifications
  • Precision
  • See also

Core calculations

Life annuities, life insurances, commutation functions, and related topics.

• Interest Rates
  • Creating an InterestRate
  • Discount factors
  • Annuities on InterestRate
  • Querying individual rates
  • Effective rate over an interval
  • Force of interest
  • Accumulation factor
  • Calculation mode (Config is the source of truth)
  • Using with table methods
  • Nominal rates
  • Piecewise term structure — discount formula
  • Calendar conventions and days_per_year
  • EIOPA risk-free rate curve (Solvency II)
  • Curve diagnostics (curve_analysis / validate)
  • See also
• Life Annuities
  • Annuity-due and annuity-immediate
  • The annuity formula
  • Core parameters
  • Equivalence with life insurances
  • Commutation function connection
  • Actuarial contexts
  • Code examples
  • See also
• Life Insurances
  • Types
  • The insurance formula
  • Core parameters
  • Mortality placement and payment timing
  • Equivalence with life annuities
  • Commutation function connection
  • Pure endowment
  • Code examples
  • See also
• Prospective Reserves and the ts Parameter
  • How ts transforms the calculation
  • Basic usage
  • ts vs d — key distinction
  • Integer-only mode (force_integer_ts)
  • Piecewise interest rate with ts
  • Growth rates and ts
  • Mode compatibility
  • Portfolio reserves
  • Net premium and prospective reserve — worked example
  • Methods that support ts
  • See also
• Commutation Functions
  • Integer-age requirement
  • Independence from calculation settings
  • Dependency chain
  • ex — complete expectation (not curtate)
  • Why \(\ddot{a}_x = N_x/D_x\)
  • Definitions
  • Continuous variants for fractional ages
  • Using commutation functions in Lactuca
  • Commutation formulas vs. direct engine methods
  • Key actuarial formulas using commutation functions
  • Notes
  • See also
• Deferred Life Contingencies
  • The deferment parameter
  • Standard formulas
  • API examples
  • Joint-life deferred contingencies
  • Financial annuities without mortality
  • Deferment and benefit growth
  • Interaction with pure endowments
  • Calculation modes
  • See also
• Growth Rates
  • Creating a GrowthRate
  • Computing growth factors
  • Using with table methods
  • Anniversary convention
  • Piecewise schedules and shifted()
  • Combining growth and interest
  • Inspecting a GrowthRate
  • Mutating rates and terms
  • Querying rates and segment metadata
  • Validation reports
  • Curve analysis
  • Exporting
  • Generating cashflow amounts
  • See also
• Joint-Life Calculations
  • Independence assumption
  • Status types
  • Joint annuities
  • Joint pure endowment
  • First-death insurance
  • Functional API
  • Derivable formulas
  • Parameter reference
  • Batch joint-life calculations
  • Inspecting flows (return_flows)
  • See also
• Calculation Modes
  • Actuarial coherence across modes
  • What the mode controls
  • Mode comparison
  • Mode descriptions
  • Setting the mode
  • Payment frequencies
  • Two independent mortality settings
  • Insurance: mortality placement
  • Accuracy comparison
  • Classical identity \(1 = d\,\ddot{a}_x + A_x\)
  • Regulatory reporting scope
  • See also
• Decimal Precision and Rounding
  • Default precision strategy
  • Viewing current settings
  • Changing settings
  • TOML configuration file
  • Full list of decimal settings
  • Available properties by table type
  • Rounding implementation
  • See also
• Numerical Precision
  • Precision strategy overview
  • float64 throughout
  • Dual survivor store
  • Log-domain joint-life products
  • Integer and fractional age detection
  • Why rounding only at output
  • Summation for commutation chains
  • Actuarial invariants
  • See also

Productionizing / advanced

• Functional API
  • OOP style vs functional style
  • Common parameters
  • Controlling output precision
  • Probability functions
  • Life expectancy (LifeTable only)
  • Person-years functions (LifeTable only)
  • Life annuities (LifeTable only)
  • Life insurances (LifeTable only)
  • Commutation functions (LifeTable only)
  • Multi-life functions (LifeTable only)
  • Inspecting payment flows (return_flows)
  • Batch with multiple tables
  • Full function list
  • Global calculation mode (config.calculation_mode)
  • See also
• Batch Calculations
  • Batch methods covered
  • When to use batch mode
  • Parameter compatibility reference
  • Return-type rules
  • Pending tables in batch mode
  • Error handling in batch mode
  • Single-table batch
  • Multi-table batch (functional API)
  • Joint-life batch
  • Aggregate portfolio flows
  • Cohort and duration: instance-level properties
  • Pure financial annuities (ir.a(), ir.ä())
  • Performance notes
  • DataFrame workflow
  • See also
• Probable Flows and Portfolio Reserves
  • Theory: from individual APV to portfolio expected flows
  • What return_flows=True returns in batch mode
  • IFRS 17 Best Estimate Liability
  • Solvency II SCR — life underwriting risk module
  • IAS 19 Present Value of the Defined Benefit Obligation
  • Sensitivity analysis
  • Performance notes
• Growth Rate Conventions
  • Anniversary index definition
  • Net effective interest rate
  • Bibliographic reference
  • Piecewise growth rates and fractional ts
  • Policy on fractional ts
• Irregular Cashflows
  • Parameters
  • How it works
  • Restrictions
  • Use cases
  • Design note: why due annuities exclude cashflow_times
  • Interaction with m and n
  • Inspecting the cashflows
  • Performance notes
  • Custom per-payment amounts on a uniform schedule
  • Generating payment schedules with payment_times
  • Life insurances with irregular cashflows
  • See also
• Inspecting Cash Flows
  • Annuity cash-flow keys (discrete_precision)
  • Insurance cash-flow keys (discrete_precision)
  • Pure-endowment cash-flow keys
  • Scalar–batch key mapping (discrete_precision)
  • Continuous mode keys
  • Simplified modes — nested structure
  • Decomposing and verifying a present value
  • summary() — audit snapshots
  • See also
• Force of Mortality Methods
  • Available methods
  • Mortality placement
  • Choosing a method
  • See also
• Last Payment Adjustment
  • Annuity-due versus annuity-immediate
  • The fractional weight
  • Annuity adjustment
  • Insurance adjustment
  • Irregular cashflows
  • See also
• Date Utilities Guide
  • Accepted date formats (DateLike)
  • Date construction and manipulation
  • Date components
  • Date formatting
  • Duration calculations
  • Actuarial age
  • Anniversary generation
  • Calendar utilities
  • Vectorized usage
  • Configuration
  • See also

Architecture / internals

• qx Derivation Flow
  • The decrement array: where it all begins
  • Building the survival function
  • Integer-age annual probability
  • Sub-annual and fractional-age probabilities
  • Interpolating lx at fractional ages
  • Multi-year survival and mortality
  • Deaths column
  • Boundary at the terminal age
  • Rounding boundaries
  • See also