xbudget.evaluate.evaluate_budgets

xbudget.evaluate.evaluate_budgets(data, budgets, allow_rechunk=True, on_missing='warn')[source]

Evaluate parsed budgets into data; return records.

Parameters:

  • data (xgcm.Grid or xr.Dataset) – The dataset (or grid) to read diagnostics from and write derived variables into. Modified in place.

  • budgets (dict of str -> Budget) – Parsed budgets, from xbudget.parse.parse_budgets().

  • allow_rechunk (bool, default True) – Temporarily rechunk staggered variables for difference operations.

  • on_missing ({"warn", "raise", "ignore"}, default "warn") – How to handle a required diagnostic that is absent from data. "warn" emits one end-of-run summary UserWarning; "raise" raises MissingDiagnosticError; "ignore" is silent. In every case the affected variables are stamped with xbudget_incomplete / xbudget_missing attributes, and terms declared optional in the recipe are exempt.

Returns:

records – New variable name -> metadata ({"path": [...], "op": kind}).

Return type:

dict

Examples

Parse a recipe to a typed tree, then evaluate it into a grid (or dataset). The derived variables are written into data in place; records maps each new name to its structural identity:

>>> budgets = xbudget.parse_budgets(recipe)
>>> records = xbudget.evaluate_budgets(grid, budgets)
>>> records["heat_rhs"]
{'path': ['heat', 'rhs'], 'op': 'sum'}
>>> grid._ds["heat_rhs"]           # the derived variable now lives in the data
<xarray.DataArray 'heat_rhs' ...>

collect_budgets is the usual one-call entry point (it parses and evaluates); call evaluate_budgets directly when you already hold a parsed tree or want to control the two steps separately.