Getting started

Install

python -m pip install goal-based-allocation

The core runtime requires Python 3.10 or newer, NumPy, SciPy, and Matplotlib. The first-success workflow is offline: it needs no credentials, market data, display, or source checkout.

Run one balanced mandate

The authoritative script computes one balanced mandate and its exact buy-and-hold benchmark. It normally completes in under 15 seconds and writes no files.

examples/getting_started/quickstart.py

"""Deterministic first-success workflow for a balanced goal-based mandate."""

from goal_based_allocation import AdvisorSpec, compute_opportunity_point


def main() -> None:
    """Compute one analytical mandate and its exact buy-and-hold benchmark."""
    point = compute_opportunity_point(w_bd=0.35, spec=AdvisorSpec())
    if point is None:
        raise RuntimeError("balanced-mandate calibration did not converge")

    print("GoalBasedAllocation quickstart")
    print("horizon=10y, initial_wealth=100, rates=continuous annual")
    print(
        "mandate weights: "
        f"bonds={point['w_bd']:.1%}, equity={point['w_eq']:.1%}, "
        f"private_equity={point['w_pe']:.1%}"
    )
    print(
        "MV-optimal: "
        f"expected_wealth={point['E']:.3f}, std={point['Std']:.3f}, "
        f"survival={point['S']:.3%}"
    )
    print(f"floor_atom={point['F']:.3%}, jump_overshoot={point['O']:.3%}")
    print(
        "buy-and-hold: "
        f"expected_wealth={point['E_BH']:.3f}, std={point['Std_BH']:.3f}, "
        f"implied_return={point['r_impl_BH']:.3%}"
    )
    print(f"floor_protection_cost={point['floor_cost_pct']:.3%} of terminal value")


if __name__ == "__main__":
    main()

Expected output at version 0.3.1 (minor platform differences affect only trailing digits):

GoalBasedAllocation quickstart
horizon=10y, initial_wealth=100, rates=continuous annual
mandate weights: bonds=35.0%, equity=43.3%, private_equity=21.7%
MV-optimal: expected_wealth=139.040, std=46.087, survival=78.703%
floor_atom=13.431%, jump_overshoot=7.866%
buy-and-hold: expected_wealth=150.637, std=74.848, implied_return=4.097%
floor_protection_cost=7.699% of terminal value

The floor-protection cost is the relative difference between the terminal-value measures used by the analytical mandate and buy-and-hold benchmark. It is not a fee or guaranteed realised cost.

First parameters to change

• w_bd controls the bond share. The remaining risky share is split by AdvisorSpec.q.

• AdvisorSpec.omega_0 is the initial risky allocation target.

• AdvisorSpec.c is the continuous annual consumption rate.

• AdvisorSpec.q_dd scales the drawdown/floor tolerance.

The package-level opportunity-set workflow uses a 10-year horizon, initial wealth 100, and a 2% annual continuously compounded rate. These are model inputs, not forecasts or investment advice.

Next: mandates and opportunity sets.