Build financial models with declarations
Combine inputs, expressions, and named calculations to describe a cashflow model. The same building blocks work for households, companies, investments, and other payment plans. You choose the model inputs and presentation pages; calculation packs do not require a shared form.
Expressions can be used directly in calculations and as metric values. For example:
const opening = calculation({
name:"opening", calculate:expr.subtract(capital, purchaseCosts),
});
const bank = account({ owner, type:"asset", initial:opening });
const reserve = metric({ value:opening, label:"Starting cash" });Here, capital and purchaseCosts are money inputs. An account's initial value can be an input field, an expression, or a calculation that can be resolved from inputs at the start. The opening value must be available before the period's payments begin. Register the references in the model's ordinary input, account, and calculation declarations.
expr.add, subtract, multiply, divide, min, max, and sum combine values. expr.eq and expr.when express conditions; only the selected branch is evaluated. expr.amount reads the numeric amount from a Money value. expr.money turns a number into Money in the model currency. Money values must use compatible currencies; expressions do not convert currencies.
A metric's value can refer to an input field, a calculation result, or an expression. Select a named field from a structured result with result.project("field"). Use valueType:"text" for text, such as a status message. A metric uses either value or its own calculate function.
Loan plans and financial formulas can also read calculations, projections, and expressions directly. Declared references make dependencies visible and let the same result be reused in payments and reports. Loan terms must be available before the period's payments.
With Financial formulas, time series can be accumulated as a sum or tracked as a minimum and maximum:
const cash = formulas.series.running({
name:"cash", source:expr.netCash(owner), operation:"sum", initial:opening,
});
const minimum = formulas.series.running({
name:"minimum", source:cash, operation:"min", initial:opening,
});running creates a calculation for each period. sum accumulates from the opening value; min and max compare each value with it. Without an opening value, the series starts with the first period's observation. This is useful for catching a weak month that a strong ending value would hide.
formulas.series.rateScenario combines base, a list of changes:[{fromPeriod,change}], an optional shock, and an optional floor. Period indexes start at zero. A distribution used as shock is drawn once per Monte Carlo trial and spread across the periods. An ordinary calculation uses the distribution's center.
Goal seeking uses formulas.solve.variable("name") and formulas.solve.bisect({variable,expression,target,lower,upper}). Use a continuous, monotonic formula and bounds whose endpoints enclose the target. The Find a loan amount from a monthly payment example searches for the loan amount that produces the desired annuity payment. It changes the named unknown in the formula; it does not change user inputs or rerun a whole cashflow model at each search step.
The result contains value, converged, iterations, residual, and reason. Publish the calculated amount with, for example, metric({value:expr.money(goal.project("value"))}), and the reason with metric({value:goal.project("reason"),valueType:"text"}).
reason | Meaning |
|---|---|
converged | The formula reaches the target within tolerance. |
target-outside-bounds | The bounds do not enclose the target. The endpoint whose formula value is closest to the target is returned. |
iteration-limit | The search reached its iteration limit; the result is not yet within tolerance. |
residual is the formula value minus the target. tolerance applies to this difference, not to the unknown. In the payment example, 0.01 means a difference of at most one Swedish öre (SEK 0.01) in the monthly payment. Always use the reason together with the calculated value. A goal-seeked annuity describes the payment formula; the household budget, credit policy, and actual account flows need their own declarations.