Skip to content

Home

Jump to bottom
Martin-Daniel Lacasse edited this page Mar 12, 2026 · 2 revisions

Welcome to Owl – Optimal Wealth Lab

Owl is an open-source retirement-planning tool built with linear programming. It helps you explore and optimize long-term financial strategies—withdrawals, contributions, Roth conversions, and legacy planning—under various market assumptions.

  • Use historical return data to back-test strategies.
  • Run Monte Carlo simulations with stochastic models (bootstrap, VAR, lognormal, etc.) to evaluate sequence-of-returns risk.
  • Build scenarios using fixed or custom return assumptions, inflation, and tax rules.
  • Optimize for maximum net spending or after-tax bequest, depending on your goals.
  • Incorporate tax-sensitive behavior: Roth conversions, IRMAA (Medicare), RMDs, LTCG and NIIT (with optional exact MIP formulations), ACA marketplace (pre-65), and federal income tax.
  • Fully customize inputs: taxable, tax-deferred, Roth, and HSA accounts; spending paths; pensions and Social Security; debts and fixed assets; time-series data via the Household Financial Profile (HFP).

Quick Start

  1. Launch Owl

  2. Set up your profile

    • Enter age, retirement horizon, and financial accounts (taxable, traditional, Roth, HSA).
    • Add income sources (salary, Social Security, pension) and optional debts or fixed assets.
    • Upload or create a Household Financial Profile (HFP) for wages, contributions, and big-ticket items.

  3. Choose assumptions

    • Select a return model: historical, stochastic, bootstrap SOR, VAR, or fixed.
    • Set inflation and spending approach (constant, smile curve, etc.).

  4. Pick your optimization goal

    • Maximize lifetime spending, or
    • Maximize after-tax bequest while maintaining desired spending.
    • Optionally cap Roth conversions, set Medicare/ACA/LTCG to “optimize” (expert), and choose MIP decomposition (sequential or Benders) when using multiple optimize flags.

  5. Run the optimization

    • Owl computes optimal withdrawals, conversions, and contribution paths.
    • Review results: spending plan, account balances, tax projections, and exports.

  6. Simulate (optional)

    • Use Monte Carlo or historical-range stress tests to check robustness.
    • Iterate on assumptions and export results for comparison.

Documentation

Document Description
INSTALL.md Installation, Python environment, and developer build
USER_GUIDE.md Python API usage, Jupyter examples, scripts
PARAMETERS.md Full reference for TOML case file parameters
RATE_MODELS.md Rate models: historical, stochastic, bootstrap, VAR, etc.
docs/modeling-capabilities.md Modeled components, assumptions, and limitations
papers/owl.tex Mathematical foundations (LaTeX/PDF)

UI documentation is available inside the Streamlit app.

Command-line interface (owlcli)

  • List cases: owlcli list examples/
  • Run a case: owlcli run examples/Case_jack+jill.toml
  • Override solver options: owlcli run examples/Case.toml --solver HiGHS --solver-opt withMedicare=optimize --solver-opt withDecomposition=sequential
  • Solver options help: owlcli run --help-solver-options

Key capabilities (highlights)

  • Accounts: Taxable, tax-deferred, Roth, and HSA; RMDs; Roth conversion optimization with 5-year maturation; safety-net minimum balances.
  • Taxes: Federal brackets (OBBBA 2026), LTCG (0%/15%/20%), NIIT (3.8%), SS taxability (provisional income), standard deduction.
  • Medicare & ACA: IRMAA (Part B) from MAGI lookback; optional MIP “optimize” for exact bracket choice; ACA marketplace (pre-65) with SLCSP and premium tax credit.
  • Income & outflows: Social Security (PIA, FRA, spousal/survivor), pensions (joint-and-survivor), wages and contributions via HFP, debts and fixed assets.
  • MIP decomposition: When several “optimize” options are on (Medicare, ACA, LTCG, NIIT, SS taxability), use sequential (relax-and-fix heuristic) or Benders (certified optimum) to keep solve times tractable; LTCG binaries are handled in the subproblem for robustness.
  • Solvers: HiGHS (default, free) or MOSEK (optional, commercial).

Credits and support

  • Credits: See CREDITS.md.
  • Bugs and feature requests: GitHub Issues or email.
  • Privacy: The app does not store or forward your data; all inputs stay in your session and can be downloaded to your computer.

Copyright © 2024–2026 Martin-D. Lacasse. For educational use only; not financial advice.

Clone this wiki locally