DALEC-BETHY (D&B) – The Inversion Lab / TCCAS dalecbethy/std

Description

Plugin for the DALEC-BETHY (D&B) terrestrial carbon model.

D&B couples the BETHY (BiosphEric Terrestrial rHYlogic) canopy/soil photosynthesis and energy-balance scheme with the DALEC (Data Assimilation Linked Ecosystem Carbon) carbon-pool/allocation model. It is developed and maintained by The Inversion Lab (Vossbeck, Knorr, Kaminski) as part of the Terrestrial Carbon Community Assimilation System (TCCAS), and is delivered with hand-written tangent-linear and adjoint code (src/cost_fw.f90 / src/cost_bw.f90), plus an internal L-BFGS-B minimiser (mini/) for site-level parameter assimilation experiments run outside of pyCIF (make xassi).

D&B simulates, at hourly resolution, canopy photosynthesis (GPP), plant and soil respiration, and the resulting net ecosystem exchange (NEE) of CO2, on a set of “sample points” (nsp = a spatial grid cell / PFT combination) aggregated from a smaller set of grid cells (ng). It can also simulate ancillary satellite-observable quantities (SIF, L-band VOD, surface soil moisture, ASCAT backscatter slope, FAPAR) used to constrain its own parameters in stand-alone assimilation runs.

For a CIF (Community Inversion Framework) integration, D&B is expected to be used as a bottom-up terrestrial CO2 flux model: it is run forward (possibly in tangent-linear/adjoint mode, since the Fortran adjoint already exists) to produce a NEE flux field that CIF can then use/optimise jointly with an atmospheric transport model, in the same spirit as the satwetch4 plugin provides a bottom-up CH4 wetland flux.

Model sources (excluding all input/forcing/observation data, which are not tracked in the CIF repository) are mirrored, unmodified, under model_sources/dalecbethy for reference by compile(). The original code lives at /home/chimereges/aberchet/DB/model/sites and must not be edited from here; only this pyCIF plugin (pure Python) is developed in this branch.

Note

Unlike most pyCIF models, compile() is not exposed at the package level here, so the generic run_model transform (see pycif/plugins/transforms/system/run_model/__init__.py) does not auto-call it at plugin-initialisation time. D&B’s build regenerates src/dimensions.f90 from the actual forcing NetCDF files for domain_name (see the Makefile rule for src/dimensions.f90), so compiling before pyCIF has staged input/{static,dyn}forcing.nc (see native2inputs()) would break outside of the normal, input-agnostic compile stage most models rely on. Instead, run() lazily triggers compilation itself, the first time it is called (i.e. once the D&B input data is known).

Warning

This is a work-in-progress skeleton, not a working plugin yet. It follows the same structure as pycif/plugins/models/template and reuses ideas from pycif/plugins/models/satwetch4 (in particular for the shape of a bottom-up flux-model mapper), but several structural choices below are explicitly marked TODO and need validation by a D&B/CIF developer before the model can actually run inside pyCIF:

• whether the D&B parameters (core/sif/lvod/slope-params.csv, i.e. the model’s own control vector, see src/prior.f90) should be exposed to pyCIF as an optimisable input component (à la satwetch4’s model_param_k/model_param_q10), or handled entirely internally to D&B;

• both the dynamic meteorological forcing (input/dynforcing.nc) and the time-invariant static forcing (input/staticforcing.nc) are now supplied by CIF meteo/static components (see the requirements dict below and pycif.plugins.datastreams.fluxes.dalecbethy), rewritten per sub-simulation by make_meteo()/ make_static() instead of being linked from the reference, pre-processed site/global files.

Key reference

• D&B / TCCAS: Vossbeck, Knorr, Kaminski (The Inversion Lab) – full citation TBD.

YAML arguments

The following arguments are used to configure the plugin. pyCIF will return an exception at the initialization if mandatory arguments are not specified, or if any argument does not fit accepted values or type:

Mandatory arguments

parameters_dir : str, mandatory

Directory holding D&B’s prior parameter CSV files (‘<domain_name>-{core,sif,lvod,slope}-params.csv’, D&B Makefile ‘parameters/’ directory).

Optional arguments

autoflush : bool, optional, default False

Cleans big temporary files when the simulation is done. Triggers the function flushrun of the model if available

ensrf_restart_file : str, optional

Use in EnSRF mode to point at relevant restart file

ensrf_datei : str, optional

New start date to use in EnSRF

ensrf_same_restart : bool, optional

Use in EnSRF mode to check if same restart

dir_sources : str, optional, default “”

Path to the D&B sources (e.g. ‘model_sources/dalecbethy’). Overwrites ‘direxec’ if specified.

direxec : str, optional, default “”

Path to a pre-built D&B checkout/executable to re-use instead of recompiling.

domain_name : str, optional, default “global”

D&B site/domain identifier, as used for the Makefile ‘DOMAIN’ macro and to select the ‘<domain_name>-{core,sif,lvod,slope}-params.csv’ prior parameter files (e.g. ‘FI-Sod’, ‘ES-LM1’, or ‘global’).

forcing_source : str, optional, default “era5”

Dynamic meteorological forcing to use: ‘era5’ or ‘insitu’ (site configurations only; ‘global’ only has ‘era5’-like reanalysis forcing). See the Makefile ‘FORCE_SELECT’ macro.

calendar_type : str, optional, default “gregorian”

Calendar used by D&B: ‘gregorian’ or ‘365_days’ (see src/dimensions.f90).

force-recompile : bool, optional, default False

Force recompilation of D&B even if an executable is already available in ‘direxec’.

auto-recompile : bool, optional, default True

Automatically (re-)compile D&B if no executable is found.

output_resolution : str, optional, default “daily”

Which D&B output NetCDF stream to read back into pyCIF: ‘hourly’ or ‘daily’ (see ‘diagout/dalec-bethy_{hourly,daily}-output_*.nc’).

Requirements

The current plugin requires the present plugins to run properly:

Requirement name	Requirement type	Explicit definition	Any valid	Default name	Default version
domain	Domain	False	True	dalecbethy	std
meteo	DataStream	True	False	dalecbethy	std
static	DataStream	True	False	dalecbethy	std

YAML template

Please find below a template for a YAML configuration:

model:
  plugin:
    name: dalecbethy
    version: std
    type: model

  # Mandatory arguments
  parameters_dir: XXXXX  # str

  # Optional arguments
  autoflush: XXXXX  # bool
  ensrf_restart_file: XXXXX  # str
  ensrf_datei: XXXXX  # str
  ensrf_same_restart: XXXXX  # bool
  dir_sources: XXXXX  # str
  direxec: XXXXX  # str
  domain_name: XXXXX  # str
  forcing_source: XXXXX  # str
  calendar_type: XXXXX  # str
  force-recompile: XXXXX  # bool
  auto-recompile: XXXXX  # bool
  output_resolution: XXXXX  # str

See also

API reference (functions & code)