Hforecast
Documentation menu

Documentation

Granularity

The -g/--granularity flag sets how long each simulation step is: day, month (the default), or annual. Every plan runs the same sequence of phases each step — granularity only changes how often the clock ticks and how finely events are placed in time.

hforecast -g annual -c plan.yaml -o hforecast.journal

The three settings

Setting Step Best for Cost
annual one year Long-range projections (decades to retirement and beyond) Fastest, coarsest
month one month Most personal-finance scenarios (the default) Moderate
day one day Short-range, high-fidelity runs; exact action dates Slowest, finest

What changes with granularity

  • Timing of events. Recurring income and expenses are applied once per step (a monthly step applies a month’s worth; an annual step, a year’s). Investment growth, dividends, and interest accrue once per step at that period’s rate.
  • Where actions land. An action posts on the start date of the period it falls in — the exact date in daily mode, the 1st of the month in monthly mode, and January 1 in annual mode. In annual mode, several actions in the same year all post on January 1, in date order. If an action’s exact date matters (a purchase on a specific day), use a finer granularity.
  • Run time. Finer granularity means more steps. A 60-year plan is ~60 annual steps, ~720 monthly steps, or ~22,000 daily steps — and a complex plan with many holdings and lots can take tens of seconds at monthly granularity over a long horizon. For a first pass over a decades-long plan, -g annual is dramatically faster and usually accurate enough; drop to month or day when you need the detail.

Daily mode and tax tags

Annual and monthly modes create their own tagged transactions, so the tax engine has everything it needs. Daily mode is different: it runs off an existing journal’s real transactions, and the tax engine reads gross income and deductions from posting tags — so those postings need tags such as ; earnings:income and ; deductions:pre-tax. Without them, daily-mode taxes will be wrong. See Tagging for the full set.

Choosing

  • Start with the default month for most plans.
  • Use annual for quick, long-range projections, or when a monthly run is too slow.
  • Use day only when you need exact action dates or are driving the simulation from a real journal at daily fidelity.

Note that different granularities can produce slightly different totals — coarser steps average growth and timing over the period. That’s expected; the output is a rough projection, not an exact schedule.

See also