Planner Context

FinZot exposes a set of named values, called the “context”, that any formula can reference. Think of them as always-available named cells. As the simulation advances through time, from 2025 to 2026 and onward, these values update automatically to reflect the current state of the plan. You never define them yourself. You just reference them by name.

For example, instead of a static travel budget, spend 1% of net worth on travel: net_worth * 0.01.

These variables are available in user-defined formulas across the plan: income and expense sizing, milestone triggers, contributions, Roth conversions and withdrawals, and extra cash entries.

How planner fields behave

• Names ignore capitalization. age, AGE, and Age_primary all resolve to the same field.
• Trend helpers look back at any expression over these fields. LAG, PCT_CHANGE, and the ROLLING_* functions accept net_worth - total_debt as readily as net_worth. Only a named formula cannot appear inside them. The formula language page owns the rules.
• A sizing formula reads the year as it stands. When FinZot sizes an entry, balances already carry this year’s investment return, and flow fields such as total_income hold what the year has booked so far. A milestone trigger reads last year’s close instead (milestones and timing).
• A QCD formula sees balances only. Qualified Charitable Distributions are sized first in the year, before any income or spending is booked, so total_income, consumption, and the other flow fields are $0 there. Size a gift from traditional_balance or BALANCE(); a gift sized from a flow gives $0 every year (charitable giving).
• A look back reads a year-end close. LAG, PCT_CHANGE, and the ROLLING_* functions read one history per field, recorded after each year settles. That history is the same number wherever the formula sits. So a lagged read and a plain read of the same field measure two different moments. Subtracting one from the other does not give a year-over-year change.
• Debt fields depend on where the formula sits. total_debt, mortgage_balance, and debt_free report the balance left after every payment the year has made so far. The year makes its debt payments in step 2, so an income sized in step 1 still reads the old balance, and everything sized after that reads the new one (how a year works). In the year a loan is paid off, an income formula reads debt_free as FALSE and an expense formula reads it as TRUE.
• A sizing formula floors at zero. When a formula that sizes an income, expense, contribution, withdrawal, or gift evaluates below $0, that year’s amount is $0. The entry does not become a loss or a refund, and an income stream cannot carry a loss.

Numeric variables

Variable	Aliases	What it represents
age_primary	age	Current age of the primary person, in whole years.
age_spouse		Current age of the spouse, in whole years. 0 if single.
calendar_year		Calendar year of the plan, such as 2035.
year_index		Year offset in the projection, starting at 0 for the first year.
years_remaining		Years left in the plan, counting the current one. Never below 1, so it is always safe to divide by. The final year of the plan reads 1. This is the same horizon the amortized budget spreads wealth over.
invested_assets		Total cash and securities. This is net worth excluding real estate and debt.
net_worth		Total household net worth.
total_debt		Outstanding debt balance across all loans.
mortgage_balance		Outstanding mortgage debt across all properties.
real_estate_equity		Total equity across every property in the plan.
taxable_balance		Combined taxable brokerage balance.
roth_balance		Total Roth account balance.
traditional_balance		Total traditional (pre-tax) retirement balance.
hsa_balance		Total HSA account balance.
edu_529_balance		Total 529 education savings balance.
withdrawal_amount		Net withdrawal from investment accounts for the year: security sales plus dividend and interest income, minus purchases. Reinvested dividends net to zero.
consumption		Total annual consumption: regular expenses, personal property expenses, and debt interest. Excludes rental property costs, taxes, and debt principal.
total_income		Total gross income: earned, Social Security, pension, other, tax-free, and rental. Excludes employer contributions.
earned_income		W-2 earned income only.
social_security_income		Social Security benefit income for the year.
pension_income		Defined benefit pension payout income for the year.
portfolio_return		Value-weighted portfolio return for the year, as a decimal. 0.07 means 7%. Weighted by beginning-of-year market value per asset. Uses pure asset class returns, unaffected by withdrawals or contributions.
real_portfolio_return	real_return	portfolio_return deflated by the year’s inflation: (1 + portfolio_return) / (1 + inflation_rate) - 1. Use this rather than portfolio_return - inflation_rate, which overstates the real return in volatile years.
equity_allocation		Fraction of invested assets in equities, from 0.0 to 1.0, by beginning-of-year market value. Equity classes are Domestic, International, Global, and Sector Stock.
inflation_rate		Annual inflation rate FinZot uses for the current year.

Boolean variables

Variable	What it represents
debt_free	TRUE once the plan has paid off every modeled debt.

Helper functions

These wrap planner calculations. Use them like any spreadsheet function.

Function	Use it to
FUTURE_DOLLARS(amount)	Inflate today’s dollars into the current plan year using FinZot’s inflation table.
BALANCE("account_id")	Read the current balance of a specific account, looked up by its internal account ID.

Both helpers keep a history, so they work inside the time-series functions. LAG(BALANCE("account_id"), 1) is the account’s closing balance at the end of last year, and LAG(FUTURE_DOLLARS(1000), 1) inflates to last year’s dollars.

A milestone is checked at the turn of the year against the closing balances, so inside a milestone FUTURE_DOLLARS inflates to prices at that year’s close. invested_assets > FUTURE_DOLLARS(2_000_000) then fires when the portfolio is worth $2 million in today’s dollars.

See also

• Formula Language — The spreadsheet-style syntax, operators, and functions used to customize FinZot’s calculations.
• How a Year Works — The order FinZot processes each projection year. Income, expenses, and required payments first, then each list of actions you control, ending in Roth Conversions and Withdrawals. This order is also what a formula reads: it decides which of the year’s flows have happened by the time an entry is sized. Also the three stages that cover a shortfall and the default account that absorbs surplus.