goal-based-allocation 0.2.0__tar.gz → 0.3.0__tar.gz

{goal_based_allocation-0.2.0/goal_based_allocation.egg-info → goal_based_allocation-0.3.0}/PKG-INFO

@@ -1,17 +1,19 @@
 Metadata-Version: 2.4
 Name: goal-based-allocation
-Version: 0.2.0
-Summary: Dynamic Mean-Variance Portfolio Allocation under Regime-Switching Jump-Diffusions with Absorbing Barriers and Distribution Matching
+Version: 0.3.0
+Summary: Analytical dynamic mean-variance allocation and terminal-wealth risk under regime-switching jump-diffusions
 Author: Artur Sepp
-License: MIT
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/ArturSepp/GoalBasedAllocation
 Project-URL: Repository, https://github.com/ArturSepp/GoalBasedAllocation
 Project-URL: Issues, https://github.com/ArturSepp/GoalBasedAllocation/issues
-Keywords: portfolio-optimization,mean-variance,regime-switching,jump-diffusion,goal-based-investing,laplace-transform,option-pricing,quantitative-finance
+Project-URL: Documentation, https://artursepp.github.io/GoalBasedAllocation/
+Project-URL: Changelog, https://github.com/ArturSepp/GoalBasedAllocation/blob/main/CHANGELOG.md
+Project-URL: Paper, https://papers.ssrn.com/sol3/papers.cfm?abstract_id=6534579
+Keywords: portfolio-optimization,mean-variance,regime-switching,jump-diffusion,goal-based-investing,laplace-transform,option-pricing,quantitative-finance,asset-allocation,wealth-management,absorbing-barrier
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Financial and Insurance Industry
 Classifier: Intended Audience :: Science/Research
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
@@ -28,37 +30,30 @@ Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: black; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7; extra == "docs"
+Requires-Dist: myst-parser>=2; extra == "docs"
+Requires-Dist: sphinx-sitemap>=2; extra == "docs"
 Dynamic: license-file
 
-# GoalBasedAllocation
+# GoalBasedAllocation (`goal-based-allocation`)
 
-<p align="center">
-  <em>Dynamic Mean-Variance Portfolio Allocation under Regime-Switching Jump-Diffusions<br>with Absorbing Barriers and Distribution Matching</em>
-</p>
+Analytical dynamic mean-variance allocation and terminal-wealth risk under
+regime-switching jump-diffusions in Python for quantitative researchers and
+wealth-management model developers.
 
-<p align="center">
-  <a href="https://github.com/ArturSepp/GoalBasedAllocation/actions/workflows/tests.yml">
-    <img src="https://github.com/ArturSepp/GoalBasedAllocation/actions/workflows/tests.yml/badge.svg" alt="Tests">
-  </a>
-  <a href="https://github.com/ArturSepp/GoalBasedAllocation/blob/main/LICENSE">
-    <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT">
-  </a>
-  <a href="https://pypi.org/project/goal-based-allocation/">
-    <img src="https://img.shields.io/pypi/v/goal-based-allocation.svg" alt="PyPI">
-  </a>
-  <a href="https://pypi.org/project/goal-based-allocation/">
-    <img src="https://img.shields.io/pypi/pyversions/goal-based-allocation.svg" alt="Python">
-  </a>
-  <a href="https://pepy.tech/project/goal-based-allocation">
-    <img src="https://pepy.tech/badge/goal-based-allocation" alt="Downloads">
-  </a>
-</p>
+[![PyPI](https://img.shields.io/pypi/v/goal-based-allocation?style=flat-square)](https://pypi.org/project/goal-based-allocation/)
+[![Python](https://img.shields.io/pypi/pyversions/goal-based-allocation?style=flat-square)](https://pypi.org/project/goal-based-allocation/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Tests](https://github.com/ArturSepp/GoalBasedAllocation/actions/workflows/tests.yml/badge.svg)](https://github.com/ArturSepp/GoalBasedAllocation/actions/workflows/tests.yml)
+[![Downloads](https://static.pepy.tech/badge/goal-based-allocation)](https://pepy.tech/project/goal-based-allocation)
+[![Monthly](https://static.pepy.tech/badge/goal-based-allocation/month)](https://pepy.tech/project/goal-based-allocation)
+
+**Documentation:** [artursepp.github.io/GoalBasedAllocation](https://artursepp.github.io/GoalBasedAllocation/)
 
-Companion code to:
+**Paper:** companion code to Sepp, A. (2026), *Dynamic Mean-Variance Portfolio Allocation under Regime-Switching Jump-Diffusions with Absorbing Barriers and Distribution Matching* — [SSRN 6534579](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=6534579). See [Citation](#citation) for BibTeX.
 
-> **Sepp, A. (2026). Dynamic Mean-Variance Portfolio Allocation under Regime-Switching
-> Jump-Diffusions with Absorbing Barriers and Distribution Matching.**
-> [SSRN: https://papers.ssrn.com/sol3/papers.cfm?abstract_id=6534579](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=6534579)
+---
 
 ## Overview
 
@@ -66,12 +61,18 @@ This package provides a **fully analytical Laplace-transform framework** for dyn
 mean-variance (MV) portfolio allocation under a two-state regime-switching model
 with exponential jumps at regime transitions and an absorbing wealth floor.
 
+It models two regimes and multi-asset mandates aggregated to one effective risky
+asset. It is not a discrete constrained multi-asset optimiser, trading engine, or
+production portfolio-management system; use
+[`optimalportfolios`](https://github.com/ArturSepp/OptimalPortfolios) for rolling
+multi-asset construction, constraints, transaction costs, and backtesting.
+
 The MV-optimal strategy takes the form
 
-$$\omega^*(t) = |\omega^*_a| \cdot \left(\frac{\Pi^*(t)}{\Pi_t} - 1\right)$$
+$$\omega^{\ast}(t) = |\omega^{\ast}_a| \cdot \left(\frac{\Pi^{\ast}(t)}{\Pi_t} - 1\right)$$
 
-where $\Pi^*(t)$ is the target wealth trajectory derived from the Riccati ODE system,
-and $|\omega^*_a|$ is the regime-dependent allocation intensity. This produces an
+where $\Pi^{\ast}(t)$ is the target wealth trajectory derived from the Riccati ODE system,
+and $|\omega^{\ast}_a|$ is the regime-dependent allocation intensity. This produces an
 **endogenous de-risking glide path**: early in the horizon the funding gap is large
 and allocation is aggressive; as the portfolio approaches the target, allocation
 moderates automatically.
@@ -101,6 +102,12 @@ simulation is needed for pricing; MC is used only for validation.
 - Monte Carlo simulator for validation of all analytical results
 - Integration tests and all paper figures reproducible from a single command
 
+## When to use it — and when not
+
+Use `goal-based-allocation` to design goal-based mandates under regime switching: survival and shortfall probabilities against a wealth floor, MV-optimal allocation intensities and glide paths, terminal wealth distributions, investment opportunity sets for client advice, and regime-switching vanilla option pricing on the same Laplace engine — all analytically, with Monte Carlo reserved for validation.
+
+The model is deliberately parsimonious: two regimes, exponential jumps at transitions, and multi-asset mandates reduced to a single effective asset via portfolio aggregation. For discrete rolling multi-asset optimisation with weight constraints and transaction costs, use [`optimalportfolios`](https://github.com/ArturSepp/OptimalPortfolios).
+
 ## Model
 
 The portfolio wealth $\Pi_t$ follows a regime-switching jump-diffusion
@@ -114,7 +121,7 @@ with two states: **growth** ($i=1$) and **stress** ($i=2$).
 | $\mu^{[i]} = \bar{\mu}^{[i]} - \lambda \alpha^{[i]}$ | Diffusion drift | `mu_bar` |
 | $r_h = \max(r, c)$ | Hurdle rate | `r_h` |
 | $r_c = r_h - c = \max(0, r-c)$ | Net floor growth rate | `r_c` |
-| $\omega^*_a = -\tilde{a}^{[i]}/\Sigma^{[i]}$ | Risky allocation coefficient | `w_a` |
+| $\omega^{\ast}_a = -\tilde{a}^{[i]}/\Sigma^{[i]}$ | Risky allocation coefficient | `w_a` |
 
 ### Process specification
 
@@ -123,7 +130,7 @@ with two states: **growth** ($i=1$) and **stress** ($i=2$).
 | Diffusion | Regime-dependent drift $\mu^{[i]}$ and volatility $\sigma^{[i]}$ |
 | Jumps | Exponential crash at growth→stress ($\eta^{[1]}$), exponential recovery at stress→growth ($\eta^{[2]}$) |
 | Regime switching | Poisson rates $\lambda^{[12]}$ (crash) and $\lambda^{[21]}$ (recovery) |
-| MV-optimal control | $\omega^*(t) = \|\omega_a^*\| \cdot (\Pi^*(t)/\Pi_t - 1)$, from Riccati system |
+| MV-optimal control | $\omega^{\ast}(t) = \|\omega_a^{\ast}\| \cdot (\Pi^{\ast}(t)/\Pi_t - 1)$, from Riccati system |
 | Absorbing floor | Wealth stopped at $L_t = L_0 \cdot e^{r_c t}$, converting to cash |
 
 ### Asset class parameters
@@ -148,9 +155,9 @@ $w_{\text{eq}} = g(1-w)$, $w_{\text{pe}} = (1-g)(1-w)$.
 | Balanced | 35/43/22 | 11.1 / 16.7% | 4.34 / 0.70% | 0.233 |
 | Growth | 0/67/33 | 15.8 / 23.8% | 5.33 / 0.00% | 0.334 |
 
-### MV-optimal results ($c=0\%$, $\omega^*(0)=1$, $q_{dd}=2$)
+### MV-optimal results ($c=0\%$, $\omega^{\ast}(0)=1$, $q_{dd}=2$)
 
-| Mandate | $r_{\text{impl}}$ | $\Pi^*_T$ | $\mathbb{E}[\Pi_T]$ | Std | Survival | $r^{\text{BH}}_{\text{impl}}$ | $\text{Std}^{\text{BH}}$ |
+| Mandate | $r_{\text{impl}}$ | $\Pi^{\ast}_T$ | $\mathbb{E}[\Pi_T]$ | Std | Survival | $r^{\text{BH}}_{\text{impl}}$ | $\text{Std}^{\text{BH}}$ |
 |---|---|---|---|---|---|---|---|
 | Income | 2.39% | 240 | 127 | 24.7 | 85.5% | 2.46% | 30.4 |
 | Conservative | 2.92% | 200 | 134 | 33.7 | 83.2% | 3.33% | 48.3 |
@@ -181,20 +188,21 @@ Requires Python >= 3.10 with NumPy >= 1.24, SciPy >= 1.10, and Matplotlib >= 3.7
 
 ```
 GoalBasedAllocation/
-├── goal_based_allocation/          # Core library
-│   ├── regime_switch_paper.py      # Laplace framework: density, survival, overshoot, BH moments
-│   ├── riccati_solver.py           # Riccati ODE system + MC simulator
-│   ├── laplace_inversion.py        # Abate-Whitt & Stehfest numerical inversion
-│   ├── client_solver.py            # Effective asset construction, portfolio eta quadrature
-│   ├── mandate_utils.py            # Portfolio mandate construction from assets
-│   ├── opportunity_set.py          # Investment opportunity set & advisor framework
-│   └── vanilla_option_pricer.py    # Laplace-transform vanilla option pricing (regime switching)
+├── src/
+│   └── goal_based_allocation/      # Core library
+│       ├── regime_switch_paper.py  # Density, survival, overshoot, BH moments
+│       ├── riccati_solver.py       # Riccati ODE system + MC simulator
+│       ├── laplace_inversion.py    # Abate-Whitt & Stehfest numerical inversion
+│       ├── client_solver.py        # Effective asset construction, portfolio eta quadrature
+│       ├── mandate_utils.py        # Portfolio mandate construction from assets
+│       ├── opportunity_set.py      # Investment opportunity set & advisor framework
+│       └── vanilla_option_pricer.py # Regime-switching vanilla option pricing
 ├── examples/                       # Minimal, self-contained illustrations
 │   ├── wealth_process_simulation.py
 │   ├── terminal_wealth_distribution.py
 │   ├── investment_opportunity_set.py
 │   └── regime_switch_smile.py      # Vol smile + Fourier/MC reference pricers
-├── paper_code/
+├── papers/
 │   └── goal_based_allocation_2026/ # Self-contained paper: LaTeX, PDF, figures
 │       ├── goal_based_allocation_2026.tex
 │       ├── generate_paper_figures.py   # All 10 figures + integration tests
@@ -333,13 +341,17 @@ Fourier and Monte Carlo cross-checks.
 
 ## Reproducing Paper Results
 
-All figures and integration tests can be reproduced with a single command:
+The `papers/` projects are available from a GitHub clone and are intentionally not
+included in PyPI distributions. From a clone, the main paper's integration tests and
+figures can be reproduced with the commands below. The current `--test` mode runs the
+tests and then generates all figures; use `--outdir` to keep verification output away
+from tracked figures.
 
 ```bash
-cd paper_code/goal_based_allocation_2026
+cd papers/goal_based_allocation_2026
 
-# Run integration tests (9 assertions)
-python generate_paper_figures.py --test
+# Run 9 integration assertions, then generate figures into a temporary directory
+python generate_paper_figures.py --test --outdir my_verification_figures/
 
 # Generate all figures only (writes to ./figures/)
 python generate_paper_figures.py
@@ -383,8 +395,8 @@ The `--test` flag runs 7 tests with 9 assertions covering:
 ### Selected figures
 
 <p align="center">
-  <img src="paper_code/goal_based_allocation_2026/figures/mandate_density_overlay_c0.png" width="48%" />
-  <img src="paper_code/goal_based_allocation_2026/figures/mandate_comparison.png" width="48%" />
+  <img src="papers/goal_based_allocation_2026/figures/mandate_density_overlay_c0.png" width="48%" />
+  <img src="papers/goal_based_allocation_2026/figures/mandate_comparison.png" width="48%" />
 </p>
 
 <p align="center">
@@ -393,8 +405,8 @@ The `--test` flag runs 7 tests with 9 assertions covering:
 </p>
 
 <p align="center">
-  <img src="paper_code/goal_based_allocation_2026/figures/path_dynamics_balanced.png" width="48%" />
-  <img src="paper_code/goal_based_allocation_2026/figures/opportunity_set_c0.png" width="48%" />
+  <img src="papers/goal_based_allocation_2026/figures/path_dynamics_balanced.png" width="48%" />
+  <img src="papers/goal_based_allocation_2026/figures/opportunity_set_c0.png" width="48%" />
 </p>
 
 <p align="center">
@@ -409,7 +421,7 @@ The analytical framework proceeds in three steps:
 **Step 1: Riccati ODE system.** The pre-commitment MV problem reduces to a
 system of coupled Riccati ODEs for the value function coefficients
 in each regime. The solution yields the optimal allocation
-intensity $|\omega^*_a|$ and the target wealth trajectory $\Pi^*(t)$.
+intensity $|\omega^{\ast}_a|$ and the target wealth trajectory $\Pi^{\ast}(t)$.
 
 **Step 2: Gap process.** Under the optimal policy, the log-cushion ratio
 $X_t = \ln(B_t/Z_t)$ is a regime-switching jump-diffusion with an absorbing
@@ -426,16 +438,22 @@ jump sizes via deterministic numerical integration (`portfolio_eta_quadrature`).
 Buy-and-hold benchmark moments are computed exactly via the 2×2 matrix exponential
 of Proposition B.7.
 
-## Related Packages
+## Ecosystem
 
-| Package | Description |
+This package is part of an open-source Python stack for quantitative finance — full catalogue at [github.com/ArturSepp](https://github.com/ArturSepp):
+
+| Package | Purpose |
 |---|---|
-| [OptimalPortfolios](https://github.com/ArturSepp/OptimalPortfolios) | Optimal portfolio construction and backtesting |
-| [StochVolModels](https://github.com/ArturSepp/StochVolModels) | Stochastic volatility models for options pricing |
-| [QuantInvestStrats](https://github.com/ArturSepp/QuantInvestStrats) | Quantitative investment strategies and analytics |
-| [BloombergFetch](https://github.com/ArturSepp/BloombergFetch) | Bloomberg data API wrapper |
-| [VanillaOptionPricers](https://github.com/ArturSepp/VanillaOptionPricers) | Vanilla option pricing models |
-| [factorlasso](https://github.com/ArturSepp/factorlasso) | Factor model estimation with LASSO |
+| [`qis`](https://github.com/ArturSepp/QuantInvestStrats) | Performance analytics, factsheets, and visualisation |
+| [`optimalportfolios`](https://github.com/ArturSepp/OptimalPortfolios) | Portfolio construction and backtesting |
+| [`factorlasso`](https://github.com/ArturSepp/factorlasso) | Sparse factor models and factor covariance estimation |
+| [`bbg-fetch`](https://github.com/ArturSepp/BloombergFetch) | Bloomberg data fetching |
+| [`trendfollowing`](https://github.com/ArturSepp/TrendFollowingSystems) | Trend-following systems: closed-form theory and replication |
+| [`goal-based-allocation`](https://github.com/ArturSepp/GoalBasedAllocation) *(this package)* | Dynamic MV allocation under regime-switching jump-diffusions |
+| [`stochvolmodels`](https://github.com/ArturSepp/StochVolModels) | Stochastic volatility pricing analytics |
+| [`vanilla-option-pricers`](https://github.com/ArturSepp/VanillaOptionPricers) | Vectorised vanilla option pricers and implied volatility fitters |
+
+Dependency links within the stack: `optimalportfolios` builds on `qis` and `factorlasso`; `trendfollowing` builds on `qis`.
 
 ## Citation
 
@@ -461,7 +479,7 @@ If you use this work in your research, please cite both the paper and the softwa
   title        = {{GoalBasedAllocation}: A {Python} package for dynamic mean-variance
                   portfolio allocation under regime-switching jump-diffusions},
   year         = {2026},
-  note         = {Version 0.2.0},
+  note         = {Version 0.3.0},
   howpublished = {\url{https://github.com/ArturSepp/GoalBasedAllocation}}
 }
 ```