Balance Classes

Base Class

class elm_diagnostics.balances.base.Balance(run, year=None, by=None, config=None, analysis_year_min=None, analysis_year_max=None)[source]

Bases: ABC

Abstract base for water, carbon, and energy budget balances.

Subclasses define which YAML config section to read and how to assemble the balance equation.

Parameters:

run (Run)
year (int | None)
by (SubgridLevel | None)
config (Config | str | Path | None)
analysis_year_min (int | None)
analysis_year_max (int | None)

property frame: str

components()[source]

Return cached unit-normalized, time-aligned balance components.

Return type:: dict[str, DataArray]

residual()[source]

Return the cached closure residual.

Return type:: DataArray

abstractmethod plot()[source]

Generate balance plots.

Returns a tuple of figures for this balance type.

Return type:: tuple[Figure, ...]

to_netcdf(path)[source]

Save balance components to NetCDF.

Return type:: None
Parameters:: path (str | Path)

plot_all_years()[source]: Iterate over all available years, yielding plot tuples.

Water Balance

class elm_diagnostics.balances.water.WaterBalance(run, year=None, by=None, config=None, analysis_year_min=None, analysis_year_max=None)[source]

Bases: Balance

Column water balance: dS/dt = P - ET - R.

Default equation (from ELM BalanceCheckMod.F90):: residual = cumul(inputs) - cumul(outputs) - dS

where:

inputs = RAIN + SNOW
outputs = QFLX_EVAP_TOT + QOVER + QDRAI + QDRAI_PERCH (QFLX_EVAP_TOT = QSOIL + QVEGE + QVEGT if not available)
dS = change in (SOILLIQ + SOILICE + H2OSNO + H2OCAN + H2OSFC) (SOILLIQ and SOILICE are summed over vertical levels)

Parameters:

run (Run)
year (int | None)
by (SubgridLevel | None)
config (Config | str | Path | None)
analysis_year_min (int | None)
analysis_year_max (int | None)

cumulative()[source]

Return cumulative balance components as a Dataset.

Return type:: Dataset

plot()[source]

Generate water balance plots.

If by parameter is set, creates faceted plots with one panel per sub-gridcell unit.

Returns:

fig_storage_decomposition): fig_cumulative: cumulative inputs, outputs, dS, and residual fig_output_decomposition: breakdown of output components fig_input_decomposition: breakdown of input components fig_storage_decomposition: breakdown of storage-change components

Return type:

tuple[Figure, Figure, Figure, Figure]

Carbon Balance

class elm_diagnostics.balances.carbon.CarbonBalance(run, year=None, by=None, config=None, analysis_year_min=None, analysis_year_max=None)[source]

Bases: Balance

Ecosystem carbon balance.

For BGC mode:: dTOTECOSYSC/dt = GPP - ER - TOTFIRE - WOOD_HARVESTC NEE = ER - GPP (positive = source to atmosphere)
For SP mode (satellite phenology):: Carbon pools are not prognostic. Raises an informative error.

Parameters:

run (Run)
year (int | None)
by (SubgridLevel | None)
config (Config | str | Path | None)
analysis_year_min (int | None)
analysis_year_max (int | None)

plot()[source]

Generate carbon balance plots.

Returns:: fig_cumulative: cumulative fluxes and storage change fig_pools: carbon pool time series
Return type:: tuple[Figure, Figure]

Energy Balance

class elm_diagnostics.balances.energy.EnergyBalance(run, year=None, by=None, config=None, analysis_year_min=None, analysis_year_max=None)[source]

Bases: Balance

Surface energy balance: Rnet - FSH - EFLX_LH_TOT - FGR ~ 0.

All quantities are instantaneous fluxes (W/m2). No cumulative integration is performed (per user specification).

Rnet = FSA - FIRA = (FSDS - FSR) + (FLDS - FIRE) Closure = Rnet - FSH - EFLX_LH_TOT - FGR

Parameters:

run (Run)
year (int | None)
by (SubgridLevel | None)
config (Config | str | Path | None)
analysis_year_min (int | None)
analysis_year_max (int | None)

plot()[source]

Generate energy balance plots.

Returns:: fig_fluxes: radiation components and turbulent/ground fluxes fig_closure: residual time series
Return type:: tuple[Figure, Figure]