goal-based-allocation 0.4.0__tar.gz → 0.4.2__tar.gz

{goal_based_allocation-0.4.0 → goal_based_allocation-0.4.2}/MANIFEST.in

@@ -1 +1,3 @@
 prune src/goal_based_allocation/run
+prune papers
+prune agents

{goal_based_allocation-0.4.0/src/goal_based_allocation.egg-info → goal_based_allocation-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: goal-based-allocation
-Version: 0.4.0
+Version: 0.4.2
 Summary: Semi-analytical dynamic mean-variance allocation and terminal-wealth risk under regime-switching jump-diffusions
 Author: Artur Sepp
 License-Expression: MIT
@@ -173,7 +173,7 @@ $w_{\text{eq}} = g(1-w)$, $w_{\text{pe}} = (1-g)(1-w)$.
 | Growth | 3.68% | 254 | 144 | 61.9 | 73.8% | 5.01% | 117.6 |
 
 Floor protection cost ranges from 6bp (income) to 117bp (growth). BH moments
-are exact under the RS-JD model via 2×2 matrix exponential (Proposition B.7).
+are exact under the RS-JD model via 2×2 matrix exponential (Proposition A.1).
 
 ## Installation
 
@@ -212,10 +212,10 @@ GoalBasedAllocation/
 │   ├── investment_opportunity_set.py
 │   └── regime_switch_smile.py      # Vol smile + Fourier/MC reference pricers
 ├── 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
-│       └── figures/
+│   └── goal_based_allocation_2026/
+│       ├── paper/                    # Current LaTeX, PDF and approved figures
+│       ├── replication/              # Producer, static inputs and paper tests
+│       └── drafts/, presentations/, private/, agents/  # Local sections
 ├── pyproject.toml
 ├── LICENSE
 └── README.md
@@ -273,12 +273,13 @@ assets = create_paper_assets()
 eq = assets['equity']
 T = 10.0
 
-# Solve Riccati ODE for target return of 4%
+# Solve the Riccati system. target_return fixes the present value of the target,
+# Pi*(0) = Pi0 * exp(0.04 * T); it is not the expected terminal wealth (see below).
 ell, ric = find_ell(eq, T, target_return=0.04, r=0.02, c=0.02)
 gap = gap_process_asset(ric)
 
 # Terminal targets
-PiT = ric.derived_at_tau(0)['Pi_star'][0]   # target wealth at T
+PiT = ric.derived_at_tau(0)['Pi_star'][0]   # target wealth at T, equal to ell / 2
 L_T = eq.pi_floor                            # floor at T (with r=c)
 B_T = PiT - L_T                              # buffer
 
@@ -298,6 +299,14 @@ print(f"Overshoot mass = {np.trapezoid(f_ov, d_ov):.4f}")
 print(f"Floor atom = {1 - S - np.trapezoid(f_ov, d_ov):.4f}")
 ```
 
+`find_ell` matches `target_return` to $-b(T)/(2a(T))$, the present value of the policy's target,
+$\Pi^{\ast}(0) = \Pi_0 e^{\rho T}$, not to the expected terminal wealth. Here $c = r$, so the target
+grows at $r_c = 0$ and equals $100 e^{0.4} \approx 149.2$ at both ends of the horizon, while the
+expected terminal wealth of the floor-protected strategy is about 106.4. The chapter *The MV-optimal
+policy and the Riccati system* of the [handbook](https://goalbasedallocation.readthedocs.io/en/latest/)
+gives the expected terminal wealth in closed form and the multiplier `ell` for an expected-wealth
+target.
+
 ### 3. Compare MV-optimal vs buy-and-hold
 
 ```python
@@ -310,7 +319,7 @@ from goal_based_allocation.riccati_solver import find_ell, gap_process_asset
 eff = build_effective_asset(w_eq=0.43, w_pe=0.22, k=3.0)
 T, PI0 = 10.0, 100.0
 
-# MV-optimal survival (analytical via Laplace)
+# MV-optimal survival (analytical via Laplace); target_return sets Pi*(0), as above
 ell, ric = find_ell(eff, T, target_return=0.04, r=0.02, c=0.0)
 gap = gap_process_asset(ric)
 S = compute_survival(T, gap.x0, gap)
@@ -368,20 +377,17 @@ tests and then generates all figures; use `--outdir` to keep verification output
 from tracked figures.
 
 ```bash
-cd papers/goal_based_allocation_2026
-
-# 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
+# Run from the repository root; output defaults to the external local runtime.
+python papers/goal_based_allocation_2026/replication/generate_paper_figures.py --test
+python papers/goal_based_allocation_2026/replication/generate_paper_figures.py
+python papers/goal_based_allocation_2026/replication/generate_paper_figures.py --figure 10
+```
 
-# Generate a single figure
-python generate_paper_figures.py --figure 10
+The main manuscript, PDF and approved figures now live in `paper/`; research code
+and static inputs live in `replication/`. See the [paper index](papers/README.md).
+An optional `--outdir` must be absolute and outside the checkout and OneDrive;
+it applies to both normal generation and `--test`.
 
-# Custom output directory
-python generate_paper_figures.py --outdir my_figures/
-```
 
 ### Integration tests
 
@@ -415,8 +421,8 @@ The `--test` flag runs 7 tests with 9 assertions covering:
 ### Selected figures
 
 <p align="center">
-  <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%" />
+  <img src="papers/goal_based_allocation_2026/paper/figures/mandate_density_overlay_c0.png" width="48%" />
+  <img src="papers/goal_based_allocation_2026/paper/figures/mandate_comparison.png" width="48%" />
 </p>
 
 <p align="center">
@@ -425,8 +431,8 @@ The `--test` flag runs 7 tests with 9 assertions covering:
 </p>
 
 <p align="center">
-  <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%" />
+  <img src="papers/goal_based_allocation_2026/paper/figures/path_dynamics_balanced.png" width="48%" />
+  <img src="papers/goal_based_allocation_2026/paper/figures/opportunity_set_c0.png" width="48%" />
 </p>
 
 <p align="center">
@@ -456,7 +462,7 @@ and inverted numerically using the Abate-Whitt (1995) Euler acceleration algorit
 asset using portfolio volatility with full correlation structure, and portfolio
 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.
+of Proposition A.1.
 
 ## Key References
 
@@ -470,7 +476,7 @@ of Proposition B.7.
 - Sepp, A. (2006). Extended CreditGrades model with stochastic volatility and jumps.
   *Wilmott Magazine*, September, 50-62.
 - Lipton, A. (2001). *Mathematical Methods for Foreign Exchange*. World Scientific.
-- Lipton, A. (2001). Assets with jumps. *Risk*, 14(9), 149-153.
+- Lipton, A. (2002). Assets with jumps. *Risk*, 15(9), 149-153.
 - Cont, R. and Tankov, P. (2009). Constant proportion portfolio insurance in the presence
   of jumps in asset prices. *Mathematical Finance*, 19(3), 379-401.
 - Abate, J. and Whitt, W. (1995). Numerical inversion of Laplace transforms of probability
@@ -528,7 +534,7 @@ metadata is available in [`CITATION.cff`](CITATION.cff).
   title        = {goal-based-allocation: A {Python} package for dynamic mean-variance
                   portfolio allocation under regime-switching jump-diffusions},
   year         = {2026},
-  version      = {0.4.0},
+  version      = {0.4.2},
   howpublished = {\url{https://github.com/ArturSepp/GoalBasedAllocation}}
 }
 ```

{goal_based_allocation-0.4.0 → goal_based_allocation-0.4.2}/README.md

@@ -136,7 +136,7 @@ $w_{\text{eq}} = g(1-w)$, $w_{\text{pe}} = (1-g)(1-w)$.
 | Growth | 3.68% | 254 | 144 | 61.9 | 73.8% | 5.01% | 117.6 |
 
 Floor protection cost ranges from 6bp (income) to 117bp (growth). BH moments
-are exact under the RS-JD model via 2×2 matrix exponential (Proposition B.7).
+are exact under the RS-JD model via 2×2 matrix exponential (Proposition A.1).
 
 ## Installation
 
@@ -175,10 +175,10 @@ GoalBasedAllocation/
 │   ├── investment_opportunity_set.py
 │   └── regime_switch_smile.py      # Vol smile + Fourier/MC reference pricers
 ├── 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
-│       └── figures/
+│   └── goal_based_allocation_2026/
+│       ├── paper/                    # Current LaTeX, PDF and approved figures
+│       ├── replication/              # Producer, static inputs and paper tests
+│       └── drafts/, presentations/, private/, agents/  # Local sections
 ├── pyproject.toml
 ├── LICENSE
 └── README.md
@@ -236,12 +236,13 @@ assets = create_paper_assets()
 eq = assets['equity']
 T = 10.0
 
-# Solve Riccati ODE for target return of 4%
+# Solve the Riccati system. target_return fixes the present value of the target,
+# Pi*(0) = Pi0 * exp(0.04 * T); it is not the expected terminal wealth (see below).
 ell, ric = find_ell(eq, T, target_return=0.04, r=0.02, c=0.02)
 gap = gap_process_asset(ric)
 
 # Terminal targets
-PiT = ric.derived_at_tau(0)['Pi_star'][0]   # target wealth at T
+PiT = ric.derived_at_tau(0)['Pi_star'][0]   # target wealth at T, equal to ell / 2
 L_T = eq.pi_floor                            # floor at T (with r=c)
 B_T = PiT - L_T                              # buffer
 
@@ -261,6 +262,14 @@ print(f"Overshoot mass = {np.trapezoid(f_ov, d_ov):.4f}")
 print(f"Floor atom = {1 - S - np.trapezoid(f_ov, d_ov):.4f}")
 ```
 
+`find_ell` matches `target_return` to $-b(T)/(2a(T))$, the present value of the policy's target,
+$\Pi^{\ast}(0) = \Pi_0 e^{\rho T}$, not to the expected terminal wealth. Here $c = r$, so the target
+grows at $r_c = 0$ and equals $100 e^{0.4} \approx 149.2$ at both ends of the horizon, while the
+expected terminal wealth of the floor-protected strategy is about 106.4. The chapter *The MV-optimal
+policy and the Riccati system* of the [handbook](https://goalbasedallocation.readthedocs.io/en/latest/)
+gives the expected terminal wealth in closed form and the multiplier `ell` for an expected-wealth
+target.
+
 ### 3. Compare MV-optimal vs buy-and-hold
 
 ```python
@@ -273,7 +282,7 @@ from goal_based_allocation.riccati_solver import find_ell, gap_process_asset
 eff = build_effective_asset(w_eq=0.43, w_pe=0.22, k=3.0)
 T, PI0 = 10.0, 100.0
 
-# MV-optimal survival (analytical via Laplace)
+# MV-optimal survival (analytical via Laplace); target_return sets Pi*(0), as above
 ell, ric = find_ell(eff, T, target_return=0.04, r=0.02, c=0.0)
 gap = gap_process_asset(ric)
 S = compute_survival(T, gap.x0, gap)
@@ -331,20 +340,17 @@ tests and then generates all figures; use `--outdir` to keep verification output
 from tracked figures.
 
 ```bash
-cd papers/goal_based_allocation_2026
-
-# 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
+# Run from the repository root; output defaults to the external local runtime.
+python papers/goal_based_allocation_2026/replication/generate_paper_figures.py --test
+python papers/goal_based_allocation_2026/replication/generate_paper_figures.py
+python papers/goal_based_allocation_2026/replication/generate_paper_figures.py --figure 10
+```
 
-# Generate a single figure
-python generate_paper_figures.py --figure 10
+The main manuscript, PDF and approved figures now live in `paper/`; research code
+and static inputs live in `replication/`. See the [paper index](papers/README.md).
+An optional `--outdir` must be absolute and outside the checkout and OneDrive;
+it applies to both normal generation and `--test`.
 
-# Custom output directory
-python generate_paper_figures.py --outdir my_figures/
-```
 
 ### Integration tests
 
@@ -378,8 +384,8 @@ The `--test` flag runs 7 tests with 9 assertions covering:
 ### Selected figures
 
 <p align="center">
-  <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%" />
+  <img src="papers/goal_based_allocation_2026/paper/figures/mandate_density_overlay_c0.png" width="48%" />
+  <img src="papers/goal_based_allocation_2026/paper/figures/mandate_comparison.png" width="48%" />
 </p>
 
 <p align="center">
@@ -388,8 +394,8 @@ The `--test` flag runs 7 tests with 9 assertions covering:
 </p>
 
 <p align="center">
-  <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%" />
+  <img src="papers/goal_based_allocation_2026/paper/figures/path_dynamics_balanced.png" width="48%" />
+  <img src="papers/goal_based_allocation_2026/paper/figures/opportunity_set_c0.png" width="48%" />
 </p>
 
 <p align="center">
@@ -419,7 +425,7 @@ and inverted numerically using the Abate-Whitt (1995) Euler acceleration algorit
 asset using portfolio volatility with full correlation structure, and portfolio
 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.
+of Proposition A.1.
 
 ## Key References
 
@@ -433,7 +439,7 @@ of Proposition B.7.
 - Sepp, A. (2006). Extended CreditGrades model with stochastic volatility and jumps.
   *Wilmott Magazine*, September, 50-62.
 - Lipton, A. (2001). *Mathematical Methods for Foreign Exchange*. World Scientific.
-- Lipton, A. (2001). Assets with jumps. *Risk*, 14(9), 149-153.
+- Lipton, A. (2002). Assets with jumps. *Risk*, 15(9), 149-153.
 - Cont, R. and Tankov, P. (2009). Constant proportion portfolio insurance in the presence
   of jumps in asset prices. *Mathematical Finance*, 19(3), 379-401.
 - Abate, J. and Whitt, W. (1995). Numerical inversion of Laplace transforms of probability
@@ -491,7 +497,7 @@ metadata is available in [`CITATION.cff`](CITATION.cff).
   title        = {goal-based-allocation: A {Python} package for dynamic mean-variance
                   portfolio allocation under regime-switching jump-diffusions},
   year         = {2026},
-  version      = {0.4.0},
+  version      = {0.4.2},
   howpublished = {\url{https://github.com/ArturSepp/GoalBasedAllocation}}
 }
 ```

{goal_based_allocation-0.4.0 → goal_based_allocation-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "goal-based-allocation"
-version = "0.4.0"
+version = "0.4.2"
 description = "Semi-analytical dynamic mean-variance allocation and terminal-wealth risk under regime-switching jump-diffusions"
 readme = "README.md"
 license = "MIT"
@@ -50,7 +50,8 @@ docs = ["furo>=2024.8.6", "sphinx>=7", "myst-parser>=2", "sphinx-sitemap>=2"]
 
 [dependency-groups]
 test = ["pytest>=7.0"]
-lint = ["black", "ruff==0.16.2"]
+lint = ["black", "ruff==0.16.10"]
+audit = ["pip-audit==2.10.1"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
@@ -74,7 +75,7 @@ where = ["src"]
 include = ["goal_based_allocation*"]
 exclude = ["goal_based_allocation.run*"]
 
-# `papers/` reproduces published code and is left exactly as-is.
+# Historical paper numerical style stays outside package lint; workspace policy is checked separately.
 [tool.ruff]
 line-length = 100
 exclude = ["papers"]

{goal_based_allocation-0.4.0 → goal_based_allocation-0.4.2}/src/goal_based_allocation/__init__.py

@@ -53,4 +53,4 @@ from .variance_swap import (
     skew_overidentification_test,
 )
 
-__version__ = "0.4.0"
+__version__ = "0.4.2"

{goal_based_allocation-0.4.0 → goal_based_allocation-0.4.2/src/goal_based_allocation.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: goal-based-allocation
-Version: 0.4.0
+Version: 0.4.2
 Summary: Semi-analytical dynamic mean-variance allocation and terminal-wealth risk under regime-switching jump-diffusions
 Author: Artur Sepp
 License-Expression: MIT
@@ -173,7 +173,7 @@ $w_{\text{eq}} = g(1-w)$, $w_{\text{pe}} = (1-g)(1-w)$.
 | Growth | 3.68% | 254 | 144 | 61.9 | 73.8% | 5.01% | 117.6 |
 
 Floor protection cost ranges from 6bp (income) to 117bp (growth). BH moments
-are exact under the RS-JD model via 2×2 matrix exponential (Proposition B.7).
+are exact under the RS-JD model via 2×2 matrix exponential (Proposition A.1).
 
 ## Installation
 
@@ -212,10 +212,10 @@ GoalBasedAllocation/
 │   ├── investment_opportunity_set.py
 │   └── regime_switch_smile.py      # Vol smile + Fourier/MC reference pricers
 ├── 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
-│       └── figures/
+│   └── goal_based_allocation_2026/
+│       ├── paper/                    # Current LaTeX, PDF and approved figures
+│       ├── replication/              # Producer, static inputs and paper tests
+│       └── drafts/, presentations/, private/, agents/  # Local sections
 ├── pyproject.toml
 ├── LICENSE
 └── README.md
@@ -273,12 +273,13 @@ assets = create_paper_assets()
 eq = assets['equity']
 T = 10.0
 
-# Solve Riccati ODE for target return of 4%
+# Solve the Riccati system. target_return fixes the present value of the target,
+# Pi*(0) = Pi0 * exp(0.04 * T); it is not the expected terminal wealth (see below).
 ell, ric = find_ell(eq, T, target_return=0.04, r=0.02, c=0.02)
 gap = gap_process_asset(ric)
 
 # Terminal targets
-PiT = ric.derived_at_tau(0)['Pi_star'][0]   # target wealth at T
+PiT = ric.derived_at_tau(0)['Pi_star'][0]   # target wealth at T, equal to ell / 2
 L_T = eq.pi_floor                            # floor at T (with r=c)
 B_T = PiT - L_T                              # buffer
 
@@ -298,6 +299,14 @@ print(f"Overshoot mass = {np.trapezoid(f_ov, d_ov):.4f}")
 print(f"Floor atom = {1 - S - np.trapezoid(f_ov, d_ov):.4f}")
 ```
 
+`find_ell` matches `target_return` to $-b(T)/(2a(T))$, the present value of the policy's target,
+$\Pi^{\ast}(0) = \Pi_0 e^{\rho T}$, not to the expected terminal wealth. Here $c = r$, so the target
+grows at $r_c = 0$ and equals $100 e^{0.4} \approx 149.2$ at both ends of the horizon, while the
+expected terminal wealth of the floor-protected strategy is about 106.4. The chapter *The MV-optimal
+policy and the Riccati system* of the [handbook](https://goalbasedallocation.readthedocs.io/en/latest/)
+gives the expected terminal wealth in closed form and the multiplier `ell` for an expected-wealth
+target.
+
 ### 3. Compare MV-optimal vs buy-and-hold
 
 ```python
@@ -310,7 +319,7 @@ from goal_based_allocation.riccati_solver import find_ell, gap_process_asset
 eff = build_effective_asset(w_eq=0.43, w_pe=0.22, k=3.0)
 T, PI0 = 10.0, 100.0
 
-# MV-optimal survival (analytical via Laplace)
+# MV-optimal survival (analytical via Laplace); target_return sets Pi*(0), as above
 ell, ric = find_ell(eff, T, target_return=0.04, r=0.02, c=0.0)
 gap = gap_process_asset(ric)
 S = compute_survival(T, gap.x0, gap)
@@ -368,20 +377,17 @@ tests and then generates all figures; use `--outdir` to keep verification output
 from tracked figures.
 
 ```bash
-cd papers/goal_based_allocation_2026
-
-# 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
+# Run from the repository root; output defaults to the external local runtime.
+python papers/goal_based_allocation_2026/replication/generate_paper_figures.py --test
+python papers/goal_based_allocation_2026/replication/generate_paper_figures.py
+python papers/goal_based_allocation_2026/replication/generate_paper_figures.py --figure 10
+```
 
-# Generate a single figure
-python generate_paper_figures.py --figure 10
+The main manuscript, PDF and approved figures now live in `paper/`; research code
+and static inputs live in `replication/`. See the [paper index](papers/README.md).
+An optional `--outdir` must be absolute and outside the checkout and OneDrive;
+it applies to both normal generation and `--test`.
 
-# Custom output directory
-python generate_paper_figures.py --outdir my_figures/
-```
 
 ### Integration tests
 
@@ -415,8 +421,8 @@ The `--test` flag runs 7 tests with 9 assertions covering:
 ### Selected figures
 
 <p align="center">
-  <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%" />
+  <img src="papers/goal_based_allocation_2026/paper/figures/mandate_density_overlay_c0.png" width="48%" />
+  <img src="papers/goal_based_allocation_2026/paper/figures/mandate_comparison.png" width="48%" />
 </p>
 
 <p align="center">
@@ -425,8 +431,8 @@ The `--test` flag runs 7 tests with 9 assertions covering:
 </p>
 
 <p align="center">
-  <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%" />
+  <img src="papers/goal_based_allocation_2026/paper/figures/path_dynamics_balanced.png" width="48%" />
+  <img src="papers/goal_based_allocation_2026/paper/figures/opportunity_set_c0.png" width="48%" />
 </p>
 
 <p align="center">
@@ -456,7 +462,7 @@ and inverted numerically using the Abate-Whitt (1995) Euler acceleration algorit
 asset using portfolio volatility with full correlation structure, and portfolio
 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.
+of Proposition A.1.
 
 ## Key References
 
@@ -470,7 +476,7 @@ of Proposition B.7.
 - Sepp, A. (2006). Extended CreditGrades model with stochastic volatility and jumps.
   *Wilmott Magazine*, September, 50-62.
 - Lipton, A. (2001). *Mathematical Methods for Foreign Exchange*. World Scientific.
-- Lipton, A. (2001). Assets with jumps. *Risk*, 14(9), 149-153.
+- Lipton, A. (2002). Assets with jumps. *Risk*, 15(9), 149-153.
 - Cont, R. and Tankov, P. (2009). Constant proportion portfolio insurance in the presence
   of jumps in asset prices. *Mathematical Finance*, 19(3), 379-401.
 - Abate, J. and Whitt, W. (1995). Numerical inversion of Laplace transforms of probability
@@ -528,7 +534,7 @@ metadata is available in [`CITATION.cff`](CITATION.cff).
   title        = {goal-based-allocation: A {Python} package for dynamic mean-variance
                   portfolio allocation under regime-switching jump-diffusions},
   year         = {2026},
-  version      = {0.4.0},
+  version      = {0.4.2},
   howpublished = {\url{https://github.com/ArturSepp/GoalBasedAllocation}}
 }
 ```

{goal_based_allocation-0.4.0 → goal_based_allocation-0.4.2}/src/goal_based_allocation.egg-info/SOURCES.txt

@@ -17,6 +17,7 @@ src/goal_based_allocation.egg-info/dependency_links.txt
 src/goal_based_allocation.egg-info/requires.txt
 src/goal_based_allocation.egg-info/top_level.txt
 tests/test_docs.py
+tests/test_documentation_examples.py
 tests/test_framework.py
 tests/test_metadata.py
 tests/test_module_layout.py

goal_based_allocation-0.4.2/tests/test_docs.py

@@ -0,0 +1,350 @@
+"""Documentation structure, bibliography and public-name coverage tests.
+
+The handbook conventions are recorded in ``docs/documentation_standard.md``; this module enforces
+the mechanical ones: page metadata and attribution, the eight sections and the convention card of a
+methodology chapter, the callout labels, the single bibliography, the API page and the coverage of
+every public export by a chapter. A small Sphinx build checks the page titles, robots tags and
+sitemap that the site configuration produces.
+"""
+
+import importlib
+import inspect
+import re
+import runpy
+import subprocess
+import sys
+from html.parser import HTMLParser
+from pathlib import Path
+
+import pytest
+
+import goal_based_allocation
+
+REPOSITORY_ROOT = Path(__file__).resolve().parents[1]
+DOCS = REPOSITORY_ROOT / "docs"
+
+METHODOLOGY_CHAPTERS = (
+    "regime_switching_model.md",
+    "buy_and_hold_moments.md",
+    "mv_optimal_policy.md",
+    "wealth_floor_gap_process.md",
+    "laplace_inversion.md",
+    "laplace_barrier_framework.md",
+    "terminal_wealth_distribution.md",
+    "mandate_aggregation.md",
+    "investment_opportunity_set.md",
+    "european_options.md",
+    "variance_swaps.md",
+)
+UTILITY_PAGES = (
+    "index.md",
+    "getting-started.md",
+    "conventions.md",
+    "model-boundaries.md",
+    "validation.md",
+    "papers.md",
+    "comparison.md",
+    "bibliography.md",
+    "documentation_standard.md",
+    "api/index.md",
+)
+# published addresses of the former user guide, kept as redirects to their chapters
+LEGACY_REDIRECTS = {
+    "user-guide/mv-optimal-policy.md": "mv_optimal_policy",
+    "user-guide/terminal-wealth-floor.md": "terminal_wealth_distribution",
+    "user-guide/mandates-opportunity-set.md": "investment_opportunity_set",
+    "user-guide/option-pricing.md": "european_options",
+}
+SECTIONS = (
+    "Overview",
+    "Inputs, notation, and assumptions",
+    "Methodology",
+    "Worked example",
+    "Implementation in goal_based_allocation",
+    "Interpretation and limitations",
+    "See also",
+    "References",
+)
+CARD_ROWS = (
+    "Time and rates",
+    "Regimes",
+    "Jump sizes",
+    "Wealth coordinate",
+    "Measure",
+    "Numerical method",
+    "Package default",
+)
+BYLINE = "*Author: [Artur Sepp](https://github.com/ArturSepp)"
+CITATION = ("Software citation: "
+            "[CITATION.cff](https://github.com/ArturSepp/GoalBasedAllocation/blob/main/CITATION.cff).")
+PENDING_MARK = " [pending publisher check]"
+SOFTWARE_ENTRY = (
+    "Sepp, A. goal-based-allocation: Semi-analytical dynamic mean-variance allocation and "
+    "terminal-wealth risk under regime-switching jump-diffusions. [Software citation metadata]"
+    "(https://github.com/ArturSepp/GoalBasedAllocation/blob/main/CITATION.cff)."
+)
+
+
+def read(relative: str) -> str:
+    """Return a documentation source."""
+    return (DOCS / relative).read_text(encoding="utf-8")
+
+
+def without_code(text: str) -> str:
+    """Remove fenced code blocks, keeping line structure."""
+    return re.sub(r"```.*?```", lambda match: "\n" * match.group(0).count("\n"), text, flags=re.DOTALL)
+
+
+def normalise(text: str) -> str:
+    """Collapse whitespace so that line wrapping does not change an entry."""
+    return re.sub(r"\s+", " ", text).strip()
+
+
+def list_items(text: str, marker: str) -> list:
+    """Items of the Markdown lists in ``text`` whose bullets match ``marker``, continuations joined."""
+    items, current = [], None
+    for line in text.splitlines():
+        match = re.match(rf"^(?:{marker})\s+(.*)$", line)
+        if match:
+            if current is not None:
+                items.append(normalise(current))
+            current = match[1]
+        elif current is not None and line.startswith(" ") and line.strip():
+            current += " " + line.strip()
+        elif current is not None:
+            items.append(normalise(current))
+            current = None
+    if current is not None:
+        items.append(normalise(current))
+    return items
+
+
+def bibliography_entries() -> list:
+    """The canonical entries, without their pending-verification mark."""
+    body = read("bibliography.md").split("\n## ", 1)[1]
+    return [item[:-len(PENDING_MARK)] if item.endswith(PENDING_MARK) else item
+            for item in list_items(body, "-")]
+
+
+def public_names() -> list:
+    """Names exported by the package root, excluding submodules."""
+    return sorted(name for name in dir(goal_based_allocation)
+                  if not name.startswith("_")
+                  and not inspect.ismodule(getattr(goal_based_allocation, name)))
+
+
+def test_navigation_targets_exist():
+    for relative in METHODOLOGY_CHAPTERS + UTILITY_PAGES + tuple(LEGACY_REDIRECTS):
+        assert (DOCS / relative).is_file(), relative
+
+
+def test_pages_have_description_title_byline_and_citation():
+    for relative in METHODOLOGY_CHAPTERS + UTILITY_PAGES:
+        text = read(relative)
+        assert text.startswith("---\nmyst:\n  html_meta:\n    description: >-\n"), relative
+        body = without_code(text.split("\n---\n", 1)[1])
+        titles = re.findall(r"^# .+$", body, flags=re.MULTILINE)
+        assert len(titles) == 1, relative
+        after_title = body.split(titles[0], 1)[1].lstrip("\n")
+        assert after_title.startswith(BYLINE), relative
+        assert CITATION in body, relative
+
+
+def test_methodology_chapters_have_the_eight_sections_in_order():
+    for chapter in METHODOLOGY_CHAPTERS:
+        headings = re.findall(r"^## (.+)$", without_code(read(chapter)), flags=re.MULTILINE)
+        assert tuple(headings) == SECTIONS, chapter
+        assert re.search(r"^Implemented in \[GoalBasedAllocation\]", read(chapter), flags=re.MULTILINE)
+
+
+def test_methodology_chapters_open_with_the_convention_card():
+    for chapter in METHODOLOGY_CHAPTERS:
+        section = read(chapter).split("## Inputs, notation, and assumptions\n", 1)[1]
+        table = []
+        for line in section.lstrip("\n").splitlines():
+            if not line.startswith("|"):
+                break
+            table.append(line)
+        assert table[0] == "| Convention | This article |", chapter
+        assert table[1] == "|---|---|", chapter
+        rows = tuple(line.split("|")[1].strip() for line in table[2:])
+        assert rows == CARD_ROWS, chapter
+
+
+def test_methodology_chapters_are_in_the_handbook_toctree():
+    toctree = "\n".join(re.findall(r"```\{toctree\}(.*?)```", read("index.md"), flags=re.DOTALL))
+    for chapter in METHODOLOGY_CHAPTERS:
+        assert re.search(rf"^{chapter[:-3]}$", toctree, flags=re.MULTILINE), chapter
+
+
+def test_callouts_use_the_two_labels():
+    for chapter in METHODOLOGY_CHAPTERS:
+        for line in without_code(read(chapter)).splitlines():
+            if line.startswith("> **") and not line.startswith(">  "):
+                assert line.startswith(("> **Insight.**", "> **Pitfall.**")), (chapter, line)
+
+
+def test_bibliography_has_unique_entries():
+    entries = bibliography_entries()
+    assert len(entries) == len(set(entries))
+    assert SOFTWARE_ENTRY in entries
+
+
+def test_references_are_verbatim_bibliography_entries():
+    entries = bibliography_entries()
+    cited = set()
+    for chapter in METHODOLOGY_CHAPTERS:
+        references = read(chapter).split("\n## References\n", 1)[1]
+        items = list_items(references, r"\d+\.")
+        assert items, chapter
+        for item in items:
+            matches = [entry for entry in entries if item.startswith(entry)]
+            assert matches, (chapter, item[:80])
+            cited.update(matches)
+        assert any(item.startswith(SOFTWARE_ENTRY) for item in items), chapter
+    assert cited == set(entries), sorted(set(entries) - cited)
+
+
+def test_api_page_lists_every_export_exactly_once():
+    page = read("api/index.md")
+    listed = re.findall(r"^   goal_based_allocation\.([A-Za-z_][A-Za-z0-9_.]*)$", page, flags=re.MULTILINE)
+    root = [name for name in listed if "." not in name]
+    assert sorted(root) == public_names()
+    assert len(root) == len(set(root))
+    for dotted in (name for name in listed if "." in name):
+        module_name, attribute = dotted.rsplit(".", 1)
+        module = importlib.import_module(f"goal_based_allocation.{module_name}")
+        assert hasattr(module, attribute), dotted
+
+
+def test_every_export_is_named_by_a_chapter():
+    chapters = "\n".join(read(chapter) for chapter in METHODOLOGY_CHAPTERS)
+    spans = re.findall(r"`([^`\n]+)`", chapters)
+    for name in public_names():
+        assert any(re.search(rf"\b{name}\b", span) for span in spans), name
+
+
+def test_chapter_mathematics_avoids_github_escapes():
+    for chapter in METHODOLOGY_CHAPTERS + ("conventions.md",):
+        prose = without_code(read(chapter))
+        assert "\\," not in prose, chapter
+        assert "}_" not in prose, chapter
+
+
+def test_legacy_user_guide_pages_redirect_to_chapters():
+    for relative, target in LEGACY_REDIRECTS.items():
+        text = read(relative)
+        assert text.startswith("---\norphan: true\n"), relative
+        assert f'"http-equiv=refresh": "0; url=../{target}.html"' in text, relative
+        assert (DOCS / f"{target}.md").is_file(), target
+
+
+@pytest.mark.parametrize(
+    ("service_url", "canonical_url"),
+    [
+        # stable and latest serve the same pages, so both name latest as canonical
+        (
+            "https://goalbasedallocation.readthedocs.io/en/stable/",
+            "https://goalbasedallocation.readthedocs.io/en/latest/",
+        ),
+        (
+            "https://goalbasedallocation.readthedocs.io/en/latest/",
+            "https://goalbasedallocation.readthedocs.io/en/latest/",
+        ),
+        (
+            "https://goalbasedallocation.readthedocs.io/en/0.4.1/",
+            "https://goalbasedallocation.readthedocs.io/en/0.4.1/",
+        ),
+    ],
+)
+def test_stable_builds_name_latest_as_canonical(monkeypatch, service_url, canonical_url):
+    pytest.importorskip("tomllib", reason="docs/conf.py reads pyproject.toml with tomllib")
+    monkeypatch.setenv("READTHEDOCS_CANONICAL_URL", service_url)
+    assert runpy.run_path(str(DOCS / "conf.py"))["html_baseurl"] == canonical_url
+
+
+def test_site_build_shortens_titles_and_keeps_redirect_stubs_out_of_the_index(
+    monkeypatch, tmp_path
+):
+    # Furo would end every title with the full html_title, and the redirect stubs, the noindex
+    # search page and the general index would be offered to search engines in the sitemap.
+    for module in ("sphinx", "furo", "myst_parser", "sphinx_sitemap"):
+        pytest.importorskip(module)
+    monkeypatch.delenv("READTHEDOCS_CANONICAL_URL", raising=False)
+    source = tmp_path / "source"
+    (source / "user-guide").mkdir(parents=True)
+    (source / "conf.py").write_text(
+        "import runpy\n"
+        f"_site = runpy.run_path({str(DOCS / 'conf.py')!r})\n"
+        "extensions = ['myst_parser', 'sphinx.ext.autodoc', 'sphinx_sitemap']\n"
+        "html_theme = 'furo'\n"
+        f"templates_path = [{str(DOCS / '_templates')!r}]\n"
+        "for _key in ('project', 'html_title', 'html_baseurl', 'sitemap_url_scheme',\n"
+        "             'sitemap_excludes'):\n"
+        "    if _key in _site:\n"
+        "        globals()[_key] = _site[_key]\n"
+        "setup = _site['setup']\n",
+        encoding="utf-8",
+    )
+    front_matter = "---\nmyst:\n  html_meta:\n    description: {}\n---\n\n"
+    (source / "index.md").write_text(
+        front_matter.format("The handbook.") + "# Home\n\n```{toctree}\nchapter\n```\n",
+        encoding="utf-8",
+    )
+    (source / "chapter.md").write_text(
+        front_matter.format("A chapter.") + "# The regime-switching jump-diffusion\n\nText.\n",
+        encoding="utf-8",
+    )
+    (source / "user-guide" / "old.md").write_text(
+        "---\norphan: true\nmyst:\n  html_meta:\n    description: A moved page.\n"
+        '    "http-equiv=refresh": "0; url=../chapter.html"\n---\n\n# A moved page\n\nMoved.\n',
+        encoding="utf-8",
+    )
+    output = tmp_path / "html"
+    result = subprocess.run(
+        [sys.executable, "-m", "sphinx", "-W", "-q", "-b", "html", str(source), str(output)],
+        capture_output=True,
+        text=True,
+        timeout=120,
+    )
+    assert result.returncode == 0, result.stdout + result.stderr
+
+    class Head(HTMLParser):
+        """Collect the title text and the robots and description tags of a page head."""
+
+        def __init__(self):
+            super().__init__()
+            self.robots, self.descriptions = [], []
+
+        def handle_starttag(self, tag, attrs):
+            attrs = dict(attrs)
+            if tag == "meta" and attrs.get("name") == "robots":
+                self.robots.append(attrs["content"])
+            if tag == "meta" and attrs.get("name") == "description":
+                self.descriptions.append(attrs["content"])
+
+    def head(name):
+        """Parse the head of a built page and return its titles and tag collector."""
+        html = (output / f"{name}.html").read_text(encoding="utf-8").split("</head>")[0]
+        parser = Head()
+        parser.feed(html)
+        return re.findall(r"<title>(.*?)</title>", html), parser
+
+    project = "goal-based-allocation"
+    titles, index = head("index")
+    assert titles == ["goal-based-allocation - goal-based allocation under regime-switching "
+                      "jump-diffusions"]
+    assert index.robots == []
+    titles, chapter = head("chapter")
+    assert titles == [f"The regime-switching jump-diffusion - {project}"]
+    assert chapter.robots == []
+    titles, stub = head("user-guide/old")
+    assert titles == [f"A moved page - {project}"]
+    assert stub.robots == ["noindex, follow"]
+    assert stub.descriptions == ["A moved page."]
+    sitemap = (output / "sitemap.xml").read_text(encoding="utf-8")
+    base = "https://goalbasedallocation.readthedocs.io/en/latest/"
+    assert sorted(re.findall(r"<loc>(.*?)</loc>", sitemap)) == [
+        f"{base}chapter.html",
+        f"{base}index.html",
+    ]

goal_based_allocation-0.4.2/tests/test_documentation_examples.py

@@ -0,0 +1,64 @@
+"""Execute the worked examples of every handbook chapter.
+
+Each methodology chapter under ``docs/`` shows its worked example as fenced ``python`` blocks whose
+assertions check every number the chapter quotes against an independent computation. The blocks of
+one chapter run in order in one namespace, offline, from a temporary working directory, so a chapter
+reads like a script. A block that is a schematic fragment carries the comment
+``<!-- docs-test: skip -->`` on the line before its fence. Chapters whose examples run Monte Carlo
+or calibrate a mandate are marked ``slow``.
+"""
+
+import re
+from pathlib import Path
+
+import pytest
+
+DOCS = Path(__file__).resolve().parents[1] / "docs"
+
+FENCE = re.compile(r"(?P<skip><!-- docs-test: skip -->\s*\n)?```python\n(?P<code>.*?)\n```", re.DOTALL)
+
+# chapter basename -> whether its examples are slow
+CHAPTERS = {
+    "regime_switching_model": False,
+    "buy_and_hold_moments": False,
+    "mv_optimal_policy": True,
+    "wealth_floor_gap_process": True,
+    "laplace_inversion": False,
+    "laplace_barrier_framework": False,
+    "terminal_wealth_distribution": True,
+    "mandate_aggregation": True,
+    "investment_opportunity_set": True,
+    "european_options": False,
+    "variance_swaps": False,
+}
+
+
+def chapter_blocks(name: str) -> list:
+    """Return the executable python blocks of a chapter, in page order.
+
+    Args:
+        name: chapter basename under ``docs/``.
+
+    Returns:
+        Source strings of the blocks that are not marked as skipped.
+    """
+    text = (DOCS / f"{name}.md").read_text(encoding="utf-8")
+    return [match["code"] for match in FENCE.finditer(text) if not match["skip"]]
+
+
+def test_every_methodology_chapter_has_examples():
+    for name in CHAPTERS:
+        assert chapter_blocks(name), f"{name}.md has no executable python block"
+
+
+@pytest.mark.parametrize(
+    "name",
+    [pytest.param(name, marks=pytest.mark.slow) if slow else name
+     for name, slow in CHAPTERS.items()],
+)
+def test_chapter_examples_run(name, tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setenv("MPLBACKEND", "Agg")
+    namespace = {"__name__": f"docs_{name}"}
+    for index, code in enumerate(chapter_blocks(name)):
+        exec(compile(code, f"docs/{name}.md[block {index}]", "exec"), namespace)

{goal_based_allocation-0.4.0 → goal_based_allocation-0.4.2}/tests/test_module_layout.py

@@ -8,6 +8,7 @@ from pathlib import Path
 REPOSITORY_ROOT = Path(__file__).resolve().parents[1]
 PACKAGE_ROOT = REPOSITORY_ROOT / "src" / "goal_based_allocation"
 TESTS_ROOT = REPOSITORY_ROOT / "tests"
+REPOSITORY_RUNNER_ROOTS = (REPOSITORY_ROOT / "examples", REPOSITORY_ROOT / "papers")
 EXPECTED_RUNNERS = {
     "run/client_solver_local.py",
     "run/laplace_inversion_local.py",
@@ -179,6 +180,47 @@ def test_production_modules_do_not_own_development_dispatchers() -> None:
     assert not failures, failures
 
 
+def test_repository_dispatchers_use_current_names() -> None:
+    """Enum-dispatched examples and paper analyses use ``Locals`` and ``run_local``."""
+    dispatcher_modules = []
+    failures = []
+    for root in REPOSITORY_RUNNER_ROOTS:
+        for path in sorted(root.rglob("*.py")):
+            tree = _tree(path)
+            definitions = {
+                node.name: node
+                for node in tree.body
+                if isinstance(node, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef))
+            }
+            names = {node.id for node in ast.walk(tree) if isinstance(node, ast.Name)}
+            legacy_names = sorted(LEGACY_DISPATCHERS & (definitions.keys() | names))
+            if not (legacy_names or {"Locals", "run_local"} & definitions.keys()):
+                continue
+            relative = path.relative_to(REPOSITORY_ROOT).as_posix()
+            dispatcher_modules.append(relative)
+            if legacy_names:
+                failures.append(f"{relative}: retains {', '.join(legacy_names)}")
+                continue
+            if not {"Locals", "run_local"} <= definitions.keys():
+                failures.append(f"{relative}: expected Locals plus run_local")
+                continue
+            dispatcher = definitions["run_local"]
+            args = dispatcher.args.args
+            annotation = args[0].annotation if args else None
+            if (
+                not args
+                or args[0].arg != "local"
+                or not isinstance(annotation, ast.Name)
+                or annotation.id != "Locals"
+            ):
+                failures.append(f"{relative}: expected run_local(local: Locals)")
+            if not _main_calls_run_local_directly(path):
+                failures.append(f"{relative}: main guard must contain only run_local(local=Locals.*)")
+
+    assert len(dispatcher_modules) == 2
+    assert not failures, failures
+
+
 def test_development_runners_are_excluded_from_distributions() -> None:
     """Setuptools, the source manifest, and artifact checker exclude source runners."""
     pyproject = (REPOSITORY_ROOT / "pyproject.toml").read_text(encoding="utf-8")

{goal_based_allocation-0.4.0 → goal_based_allocation-0.4.2}/tests/test_repository_layout.py

@@ -29,8 +29,8 @@ def test_research_projects_use_papers_root():
     papers = REPOSITORY_ROOT / "papers"
 
     assert not (REPOSITORY_ROOT / "paper_code").exists()
-    assert (papers / "goal_based_allocation_2026" / "generate_paper_figures.py").is_file()
-    assert (papers / "kospi_volatility_fit_jun2026" / "run_analysis.py").is_file()
+    assert (papers / "goal_based_allocation_2026" / "replication" / "generate_paper_figures.py").is_file()
+    assert (papers / "kospi_volatility_fit_jun2026" / "replication" / "run_analysis.py").is_file()
 
 
 def test_public_path_references_use_papers_root():

goal_based_allocation-0.4.0/tests/test_docs.py

@@ -1,37 +0,0 @@
-"""Documentation structure and public-name coverage tests."""
-
-import re
-from pathlib import Path
-
-import goal_based_allocation
-
-REPOSITORY_ROOT = Path(__file__).resolve().parents[1]
-
-
-def test_api_catalogue_names_exist():
-    api_page = (REPOSITORY_ROOT / "docs" / "api" / "index.md").read_text(encoding="utf-8")
-    names = set(re.findall(r"^\| `([A-Za-z][A-Za-z0-9_]*)` \|", api_page, flags=re.MULTILINE))
-
-    assert len(names) >= 30
-    missing = sorted(name for name in names if not hasattr(goal_based_allocation, name))
-    assert missing == []
-
-
-def test_docs_navigation_targets_exist():
-    expected = (
-        "getting-started.md",
-        "conventions.md",
-        "model-boundaries.md",
-        "validation.md",
-        "papers.md",
-        "comparison.md",
-        "api/index.md",
-        "user-guide/mv-optimal-policy.md",
-        "user-guide/terminal-wealth-floor.md",
-        "user-guide/mandates-opportunity-set.md",
-        "user-guide/option-pricing.md",
-    )
-    docs = REPOSITORY_ROOT / "docs"
-
-    for relative_path in expected:
-        assert (docs / relative_path).is_file(), relative_path