FVSCHEDULE

What it does

FVSCHEDULE(principal, schedule)

FVSCHEDULE(principal, schedule) returns the future value of a principal after applying a series of compound interest rates, one per period:

FVSCHEDULE  =  principal × Π_{i=1}^{m} (1 + r_i)

where r_1 … r_m are the entries of schedule in order. That is the entire definition: a running product of growth factors.

Its place in the family is defined by what it is not. FV assumes one constant rate and adds a payment stream; FVSCHEDULE allows the rate to vary and has no payment stream at all. When the rate changes over the life of the investment — a floating-rate note, a forecast path of short rates, a scenario ladder — FV is structurally the wrong function and FVSCHEDULE is the right one.

The relation to FV is exact in the degenerate case: a schedule of n identical rates r gives principal × (1 + r)^n, which is −FV(r, n, 0, −principal).

Two mathematical properties are worth stating because they are easy to assume wrongly:

1. Order does not matter. Multiplication is commutative, so shuffling the schedule leaves the answer unchanged in exact arithmetic. (In binary64 it changes the last bits — see Numerical notes — but never the value in any meaningful sense.) Contrast NPV or IRR, where order is meaning.
2. The average that reproduces the answer is geometric, not arithmetic. The single equivalent constant rate is (Π(1 + r_i))^(1/m) − 1, which is at or below the arithmetic mean of the r_i by the AM–GM inequality, with equality only when all rates are equal. Substituting the mean rate into FV therefore overstates the result, always. That gap is the whole reason volatility drags on compound returns, and FVSCHEDULE is the function that shows it.

Range: the product is positive whenever every 1 + r_i > 0. A rate of exactly −1 in any period annihilates the whole thing to zero; a rate below −1 flips the sign, which is arithmetically consistent and financially meaningless.

Arguments

• The rates are per period, expressed as decimal fractions, and the period is implicit: it is however long each schedule entry represents. There is no period-length argument and no unit checking.
• The number of periods is the length of the schedule. There is no separate nper, which removes one whole class of mismatch error that the FV-family functions are prone to.
• schedule must be an array or reference of numbers. Microsoft documents that non-numeric values in the schedule produce #VALUE!, and that empty cells are treated as zero — no interest.

Try it

Quirks

Result and edge cases

Returns Number — a value in the same units as principal.

• A rate of exactly −1 produces zero, and every subsequent rate is irrelevant. The reference engine applies no guard here — no #NUM!, no #DIV/0! — it simply multiplies by zero.
• A rate below −1 flips the sign of the result. Two such rates flip it back. This is arithmetic behaving correctly on input that has no financial reading, and no function in Excel will warn you.
• Negative principal carries through; the family sign convention is not enforced here, because there is no equation to balance — FVSCHEDULE is a product, not a solved equation, and it returns the same sign it was given.
• Numeric text in the schedule is coerced; non-numeric text produces #VALUE!.
• Empty, missing and error arguments follow the shared call model; see The value universe and Coercion and lifting.

Errors

How to implement

Numerical notes

FVSCHEDULE is a product of m factors and its error analysis is the classical one for repeated multiplication.

Error accumulates linearly, and there is no cancellation. Each multiplication introduces at most half an ULP of relative error, and the errors compound multiplicatively — so after m steps the relative error is bounded by roughly m·u/(1 − m·u) with u the unit roundoff. For any schedule a spreadsheet would realistically hold, that is a handful of ULPs at worst. There is no subtraction anywhere in the computation, and therefore no cancellation and no ill-conditioning. Compared with almost everything else in this family, FVSCHEDULE is benign.

Order changes the last bits. Floating-point multiplication is commutative but not associative, so the product of the same factors in a different order can differ by an ULP or two. The reference engine multiplies strictly left to right in schedule order. An implementation that sorted the factors, or that used pairwise multiplication for parallelism, would return slightly different bits for the same schedule — which is worth knowing before treating a last-digit disagreement as a bug.

The 1 + r_i addition is the accuracy floor. For a small rate — a daily rate of 1e-5, say — forming 1 + r discards the low bits of r before any multiplication happens, and no amount of care in the product recovers them. A schedule of many small rates therefore loses more precision in its additions than in its multiplications. The accurate alternative accumulates Σ log1p(r_i) and exponentiates once:

FVSCHEDULE  =  principal × exp( Σ log1p(r_i) )

Rust code

11 fvschedule_fn "FVSCHEDULE" (2, 2) [V "principal", R "schedule"] |s, a, sv| {
    let principal = num(s, a, 0)?;
    let rates = schedule(s, a, 1, sv)?;
    tv_out(s, tv::fvschedule(principal, &rates))
}

/// FVSCHEDULE's schedule: numbers, a blank cell as 0, any other held value #VALUE!; a direct
/// value through number coercion.
fn schedule(site: &Site<'_>, a: &[CalcValue], index: usize, sv: &mut EvalServices<'_>) -> Step<Vec<f64>> {
    let g = grid(site, a, index, sv)?;
    if !g.held {
        return Ok(vec![num(site, a, index)?]);
    }
    let mut rates = Vec::with_capacity(g.cells.len());
    for cell in &g.cells {
        match cell.core_ref() {
            CoreRef::Number(n) => rates.push(n),
            CoreRef::Empty => rates.push(0.0),
            CoreRef::Error(code) => return fail(code),
            _ => return fail(W::Value),
        }
    }
    Ok(rates)
}

pub fn fvschedule(principal: f64, schedule: &[f64]) -> Result<f64, FinancialError> {
    validate_finite(&[principal])?;
    validate_finite(schedule)?;
    let mut result = principal;
    for rate in schedule {
        result *= 1.0 + rate;
    }
    if result.is_finite() {
        Ok(result)
    } else {
        Err(FinancialError::Num)
    }
}

No implementation has been published with a Handbook test suite for this function.

Version differences

No comparison between specific Excel builds is recorded here yet. This does not establish that all builds behave alike.

Alternatives

Relationships

• FV — the constant-rate, payment-bearing sibling. FVSCHEDULE(P, {r,r,…,r}) and −FV(r, n, 0, −P) compute the same quantity by different routes and are a good cross-check.
• PV — there is no PVSCHEDULE. To discount through a varying rate path you divide, or you build the reciprocal schedule by hand. The asymmetry is a real gap in the function set.
• RRI — the equivalent constant rate: RRI(m, principal, FVSCHEDULE(principal, schedule)) returns the geometric mean growth rate of the schedule. This pair is the cleanest way to express the AM–GM point above.
• PRODUCT — what FVSCHEDULE does, one step removed. principal * PRODUCT(1 + schedule) as an array formula is the hand-built equivalent, and it is worth knowing because it makes the treatment of blanks and text explicit rather than implicit.
• GEOMEAN — the geometric mean, on 1 + r values, which relates directly to the equivalent constant rate.
• EFFECT — a within-year compounding conversion at a single rate, not a path of rates. Different question.
• Confused with: applying an average rate. See the AM–GM note; the arithmetic mean always overstates.

Named variants

No named variants are recorded yet.