calminer-docs/specifications/financial_metrics.md

Financial Metrics Specification

1. Purpose

Define the standard methodology CalMiner uses to compute discounted-cash-flow profitability metrics, including Net Present Value (NPV), Internal Rate of Return (IRR), and Payback Period. These calculations underpin scenario evaluation, reporting, and investment decision support within the platform.

2. Scope

• Applies to scenario-level profitability analysis using cash flows stored in the application database.
• Covers deterministic cash-flow evaluation; stochastic extensions (e.g., Monte Carlo) may overlay these metrics but should reference this specification.
• Documents the assumptions implemented in services/financial.py and the related pytest coverage in tests/test_financial.py.

3. Inputs and Definitions

Symbol	Name	Description	Units / Domain	Notes
CF_t	Cash flow at period t	Currency amount (positive or negative)	Scenario currency	Negative values typically represent investments/outflows.
t	Period index	Fractional period (0 = anchor)	Real number	Derived from explicit index or calendar date.
r	Discount rate	Decimal representation of the annual rate	r > -1	Scenario configuration provides default rate.
m	Compounds per year	Compounding frequency	Positive integer	Defaults to 1 (annual).
RV	Residual value	Terminal value realised after final period	Scenario currency	Optional.
t_{RV}	Residual periods	Timing of residual value relative to anchor	Real number	Defaults to last period + 1.

Period Anchoring and Timing

Cash flows can be supplied with either:

1. period_index — explicit integers/floats overriding all other timing.
2. date — calendar dates. The earliest dated flow anchors the timeline and subsequent dates convert the day difference into fractional periods using a 365-day year divided by compounds_per_year.
3. Neither — flows default to sequential periods based on input order.

This aligns with normalize_cash_flows in services/financial.py, ensuring all calculations receive (amount, periods) tuples.

4. Net Present Value (NPV)

Formula

For a set of cash flows CF_t with discount rate r and compounding frequency m:

\text{NPV} = \sum_{t=0}^{n} \frac{CF_t}{\left(1 + \frac{r}{m}\right)^{t}} +
\begin{cases}
\dfrac{RV}{\left(1 + \frac{r}{m}\right)^{t_{RV}}} & \text{if residual value present} \\
0 & \text{otherwise}
\end{cases}

Implementation Notes

• discount_factor computes $(1 + r/m)^{-t}; NPV iterates over the normalised flows and sums amount * factor`.
• Residual values default to one period after the final cash flow when residual_periods is omitted.
• Empty cash-flow sequences return 0 unless a residual value is supplied.

5. Internal Rate of Return (IRR)

Definition

IRR is the discount rate r for which NPV equals zero:

0 = \sum_{t=0}^{n} \frac{CF_t}{\left(1 + \frac{r}{m}\right)^{t}}

Solver Behaviour

• Newton–Raphson iteration starts from guess (default 10%).
• Derivative instability or non-finite values trigger a fallback to a bracketed bisection search between:
  • Lower bound: -0.99 \times m
  • Upper bound: 10.0 (doubles until the root is bracketed or attempts exceed 12)
• Raises ConvergenceError when no sign change is found or the bisection fails within the iteration budget (max_iterations default 100; bisection uses double this limit).
• Validates that the cash-flow series includes at least one negative and one positive value; otherwise IRR is undefined and a ValueError is raised.

Caveats

• Multiple sign changes may yield multiple IRRs. The solver returns the root it finds within the configured bounds; scenarios must interpret the result in context.
• Rates less than -1 * m imply nonphysical periodic rates and are excluded.

6. Payback Period

Definition

The payback period is the earliest period t where cumulative cash flows become non-negative. With fractional interpolation (default behaviour), the period is calculated as:

\text{Payback} = t_{prev} + \left(\frac{-\text{Cumulative}_{prev}}{CF_t}\right)
\times (t - t_{prev})

where t_{prev} is the previous period with negative cumulative cash flow.

Implementation Notes

• Cash flows are sorted by period to ensure chronological accumulation.
• When allow_fractional is False, the function returns the first period with non-negative cumulative total without interpolation.
• PaybackNotReachedError is raised if the cumulative total never becomes non-negative.

7. Examples

Example 1: Baseline Project

• Initial investment: -1,000,000 at period 0.
• Annual inflows: 300k, 320k, 340k, 360k, 450k (periods 1-5).
• Discount rate: 8% annual, compounds_per_year = 1.

Period	Cash Flow (currency)
0	-1,000,000
1	300,000
2	320,000
3	340,000
4	360,000
5	450,000

• net_present_value ≈ 205,759
• internal_rate_of_return ≈ 0.158
• payback_period ≈ 4.13 periods

Example 2: Residual Value with Irregular Timing

• Investment: -500,000 on 2024-01-01
• Cash inflows on irregular dates (2024-07-01: 180k, 2025-01-01: 200k, 2025-11-01: 260k)
• Residual value 150k realised two years after final inflow
• Discount rate: 10%, compounds_per_year = 4

NPV discounts each cash flow by converting day deltas to quarterly periods. The residual is discounted at t_{RV} = last_period + 2 (because the override is supplied).

8. Testing Strategy

tests/test_financial.py exercises:

• normalize_cash_flows with date-based, index-based, and sequential cash-flow inputs.
• NPV calculations with and without residual values, including discount-rate sensitivity checks.
• IRR convergence success cases, invalid inputs, and non-converging scenarios.
• Payback period exact, fractional, and never-payback cases.

Developers extending the financial metrics should add regression tests covering new assumptions or solver behaviour.

9. Integration Notes

• Scenario evaluation services should pass cash flows as CashFlow instances to reuse the shared normalisation logic.
• UI and reporting layers should display rates as percentages but supply them as decimals to the service layer.
• Future Monte Carlo or sensitivity analyses can reuse the same helpers to evaluate each simulated cash-flow path.

10. References

• Internal implementation: calminer/services/financial.py
• Tests: calminer/tests/test_financial.py
• Related specification: calminer-docs/specifications/price_calculation.md
• Architecture context: calminer-docs/architecture/08_concepts/02_data_model.md