calculate_discounted_payback_period
Calculate the discounted payback period: how many years until the DISCOUNTED cumulative cash flows recover the initial investment, incorporating the time value of money. Formula: Discounted payback = the year t where cumulative discounted cash flow turns positive. WHEN TO USE: Use when you want a payback-style risk screen that still respects the cost of capital — a project can pay back nominally but never on a discounted basis. WHEN NOT TO USE: Do NOT use for the final go/no-go decision (it still ignores flows after payback); use calculate_npv for value creation and calculate_irr for return. BEHAVIOUR: If discounted cumulative cash flow never turns positive, an explicit error is returned rather than a number. RETURNS: JSON object { discounted_payback_period_years: number (e.g. 4.2), inputs }. If the discounted flows never recover the investment, returns an explicit error stating no payback occurs. PARAMETERS: cash_flows (required): Ordered cash flows starting at time 0 (first element is the initial investment, typically negative), e.g. [-250000, 50000, 75000, 100000, 125000]. The time-0 flow is not discounted. rate (required): Discount rate as a decimal, e.g. 0.10 = 10% (never pass percentage points). Must be >= 0.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| rate | Yes | Discount rate as a decimal, e.g. 0.10 = 10% (never pass percentage points). Must be >= 0. | |
| cash_flows | Yes | Ordered cash flows starting at time 0 (first element is the initial investment, typically negative), e.g. [-250000, 50000, 75000, 100000, 125000]. The time-0 flow is not discounted. |