Financial formulas

This pack provides reusable financial calculations for model inputs, cashflows, calculations and metrics. It uses ordinary DECCF callbacks and metric declarations; it adds no engine concepts. The Calculator lists it as Financial formulas.

const { formulas } = modules["financial-formulas"];
const { savingsPlan } = modules.savings;

const periodRate = formulas.rates.period({ annualRate, convention: "effective" });
const goalContribution = formulas.savings.requiredContribution({
  openingBalance,
  target,
  periodRate,
  periods: (ctx) => ctx.time.index + 1,
});
const fund = savingsPlan({
  openingBalance,
  annualRate,
  contribution: monthlyContribution,
  contributionPlacement: "end",
});

Formula factories accept numbers, declared inputs or compatible callbacks and return functions that receive the current model context. Input references nested inside another formula are carried as preconditions; arbitrary callbacks must still be declared in the surrounding model. Invoke a configured formula with the current context, for example payment(ctx). The two composite packs also use these formulas internally: selecting loans or savings selects this pack automatically.

amount.during and snapshots.atPeriod take an integer literal or a fixed input.integer for their period bounds. For phase limits that change with other inputs, use an ordinary model callback with explicit preconditions or a savings/loan plan callback.

Formula groups

• amount: shareOf, sparse atPeriods, and half-open during profiles.
• rates: nominal, effective or explicitly compounded annual-to-period rates.
• growth: compound growth, annual step growth and degradation for fixed assumptions. A dynamic period index is allowed; a changing rate should be modeled period by period with a savings or loan plan.
• savings: future value and the contribution needed to reach a target, for end- or start-of-period deposits.
• valuation: real value and present value.
• financing: interest on opening balance, annuity payment and capped principal from a remaining balance.
• usage: convert mileage/intensity to consumption and consumption to cost without implicit unit conversion.
• business: operating result, break-even units, static cash runway and ratios. Undefined metrics stay undefined when the margin or denominator does not support a result.
• workingCapital: cash-conversion days, signed net working capital, funding cost, unpaid share and signed VAT net.
• accounting: opening debit and credit balances from an account's prior balance.
• dates.shiftMonth: shift a YYYY-MM date across year boundaries.
• metrics: cumulative selected flows and discounted NPV/payback for selected flows with explicit placements.
• snapshots.atPeriod: preserve a calculation at a selected model period with existing field and metric declarations.

Money inputs are read as numeric amounts and compatible money currencies are checked when the formula or composition runs. No exchange rate is inferred and no cents rounding is hidden. Annual rates use the model's periods per year; nominal rates divide by that count unless a capitalization frequency is supplied. metrics.discountedCashflows requires the declared cashflow placement to match the selected placement.

See Reusable financial formulas for migration examples and period conventions.