xbudget.nodes

Typed expression tree for xbudget recipes.

An xbudget recipe (the nested recipe dict loaded from YAML) describes how to build each budget term from raw model diagnostics. These dataclasses give the recipe an explicit, immutable shape so the parser, evaluator, and query helpers can dispatch on node type instead of probing dict keys.

The grammar (mirrors the YAML, see recipes/*.yaml):

Budget        := name, metadata, {side: Term}          # side in {lhs, rhs}
Term          := name, path, explicit_var?, [Operation]
Operation     := Sum | Product | Difference
Sum/Product   := [(operand_name, Operand)]
Difference    := source variable name (differenced across a grid axis)
Operand       := Constant | VarRef | Term

A Term may carry more than one Operation (e.g. a bulk Product and an equivalent finer Sum decomposition of the same quantity); each operation yields its own output variable when evaluated.

Classes

Budget(name, metadata, sides)	A named budget (e.g. heat) with lhs/rhs term trees and metadata.
Constant(value)	A scalar factor/addend in a sum or product (e.g. a density, a sign).
Difference(operand)	Finite-difference a staggered quantity across its grid axis.
LateralDivergence(fx, fy)	Horizontal flux divergence div(Fx, Fy) of two flux sub-terms.
Product(terms)	Multiply named operands together.
Reciprocal(source)	Safe reciprocal (1/x with zeros mapped to infinity) of a variable.
Sum(terms)	Add named operands together.
Term(name, path, operations[, explicit_var, ...])	A node in a budget tree: a named quantity defined by its operations.
VarRef(name)	A reference to a raw diagnostic variable expected in the dataset.