LULUC design document

[marcadella]

About

This issue gathers design notes around the implementation of LULUC (luluc branch). Because of the complexity of the task, a baby-step approach is taken, where naive implementation is used first, and complexified bit by bit to reach the end goal. The content of this issue should reflect, at any time, what is implemented on luluc (checked items), and what is planned to be implemented (unchecked items).
All items marked with [first approximation] are simplifications used as first approximation. These will be refined in a later stage.

Terminology

• The world is discretized in grid cells.
• Biomee works with one grid cell only, whose area is arbitrary (Biomee works exclusively by unit of area). Therefore, it belongs to the responsibility of the user code to scale Biomee outputs using the grid cell area for converting stocks (resp. fluxes) in kg (resp. kg m-2). In the example of LUH2, the scaling factor would be carea*10^6 (where carea varies with latitude).
• The grid cell is composed of non-overlapping land units (LU), each having a state (or land use):
  • Managed: with sub categories such as:
    • cropland
    • pasture
    • urban
  • Unmanaged: the type of vegetation is then defined as the potential natural vegetation cover of the grid cell.
    • Primary: never been managed
    • Secondary: has been managed at some point
• Each LU's size is defined by a fraction of the total area occupied by the grid cell. This fraction can be 0.
• The sum of all fractions is typically 1, but may be less due to a 'hidden' fraction (ex: LUH2's ice-water fraction icwtr). Biomee is agnostic to the exact meaning of the fractions, their scale (ex: percents vs weights) or their cumulative sum.
• The evolution of the fractional LUs is governed by a transitions matrices provided by the user (forcing). Typically, the time series of one grid cell from LUH2 dataset.

Specification

Interface LUH2

The states and transition names appearing in this section are taken from LUH2.

• R function to extract starting states and transitions for one location, start time and end time.
• Merge states to get only: [first approximation]
  • unmanaged primary (primf, primn)
  • unmanaged secondary (secdf, secnf)
  • managed crop (c3ann, c4ann, c3per, c3per, c3nfx)
  • managed pasture (pastr, range)
  • managed urban (urban)

Note:

• primf_harv is primf to secd
• primn_harv is primn to secdf
• secmf_harv is secdf to itself (self-transition)
• secyf_harv is secdf to itself (self-transition)
• secnf_harv is secdn to itself (self-transition)

Input (in R)

• Take in init_lu (array):
  • LU name name
  • managed flag
  • Special flux configs (when these are implemented)
  • Initial fraction
  • multiplicity: use for creating multiple LU (of which only the first one us initialized, the others have 0 area).
• Take in luc_forcing: square matrix n times.
• Make sure the standard Biomee model still works (appropriate inputs/config may be provided by the R wrapper)
• Add lu to init_cohort to tell which LU this cohort initialization belongs to (if not present, the first LU is used).

Spin-up

• State at year 1 is used (i.e. implicit 0 transitions).

Default transitions

Default transitions are used if the number of transient years is greater than the number of transitions provided.

• Implicit 0 (i.e. the last state is maintained).

Multi LU support

• Multiple LU with fraction.
• Constant number of LUs (with potentially null fraction) [first approximation]

LU merging

Land units need to be merged to avoid an exponential growth of the number of LU. LU with the same state may be merged, but the merging criteria remains to be decided (cf #271 pt 6).

• No merging as we work (for now) with one LU per state. [first approximation]

Note for later: merging should be done to maintain multiplicity of each LU. Merge oldest tiles first.

Land use fluxes

Land use fluxes refer to the fluxes resulting from the usage of the land in a specific state. For instance, crop harvesting will export a fraction of the above ground biomass yearly.

• unmanaged: standard biomee fluxes
• managed: standard biomee fluxes [first approximation]
• urban: no fluxes (i.e. we freeze all the pools) [first approximation]

Redistribution

Redistribution of the different pools when a fraction of a LU is affected by a transition.

All transitions (including self-transitions): [first approximation]

• All above ground C and N is released into the atmosphere (burnt)
• All other pools are distributed to maintain mass balance

Multi LU output

• With only one LU (default), the output stays the same (data)
• With multiple LUs:
  • data is replaced with combined LUs (which aggregates all LUs)
  • Followed by one column for each LU (the name of the column is the name of the LU). Each column contains the three usual vectors (annual, daily and cohorts) + output_annual_land_use.
  • LUs with multiplicity > 1 are aggregated in the output.

External interface and doc

• Implement interface change to runread_ and drivers
• Add LULUC vignette

[marcadella]

Above is what I am planning to implement regarding LULUC. I'll keep the plan updated with current progress and remarks. Any comment is welcome. @stineb @fabern

[stineb]

Great. This makes sense. There are baby steps that you can take before implementing transitions:

• Introduce lu (land unit = tile) dimension to the objects that contain state variables (with memory between time steps - all mass pools). Baby-step is to have the length = 1 initially for this new dimension .
• Specify a temporally constant land use distribution (specifying forest, crop, and urban) through the forcing. Pools and fluxes written to output should be per unit ground area. Additionally write gridcell area fraction occupied by each land unit (tile) to output.
• Implement net land use change by considering only information about states and determine land use change as the difference of the states between years.
• (going towards transitions, as you outline above).

Did you consider these?

[fabern]

Great writeup. Thanks.

I agree with Beni to make first a code working with no change (temporally constant, and even forest-only) and then gradually complexify. Keeping the current BiomeE simulations as a special case, thereby ensuring each structural code change is backwards compatible. I.e. regarding lu-dimension: simulate first grid cell with a single land-unit only. And regarding transition forcings: implement forcing that specifies no changes. Etc.

Regarding the plans then to implement the transitions.
Lacking the background in that field, I need a few clarifications regarding:

• LUH2 interface:
  • are you suggesting the three tile types forest, crop, urban ?
  • how do we evaluate model output? I.e. will we similarly aggregate any observational data to which we want to calibrate. Or will we need to translate back to LUH2 types for evaluation?
• Initial state: How are initial states derived from LUH2 and the input init_cohort related?
• Spin-up: unclear what you mean with s1, s2, and icwtr. Can you modify your initial post?
• In- and output: once they are ready, could you include in above post specific examples of the input and output data structures? I believe focussing on the interface can make the discussion more specific and help in development.

[marcadella]

@stineb

• This is what I meant with 'Make sure the standard biomee model still works': 1 forested LU.
• Yes, Biomee only works per unit land area anyways. The addition of LULUC will not change that. The addition of 'gridcell area fraction occupied by each land unit (tile) to output' won't be necessary because this is already given as an input.
• LUH2 provides both states (net) and transitions (gross) for each year. Knowing the first state and the full transition matrix is enough to reconstruct each state, so it is redundant information. But the plan is to start with the net transitions to start with (i.e. one LU per state).

@fabern

• Regarding your initial comment, same answer as to Beni's first point. If you want to know everything about LUH2, have fun.
• No need to translate back to LUH2 states. Actually, although my implementation will heavily use the concepts taken from LUH2, Biomee will happily work with other land use data. All the user needs to do is to map the states from the data source to the states supported by Biomee. Initially, these states will be forest, crop and urban.
• init_cohort contains the information about which PFT is present in the cohorts, i.e. which PFT grows on the tile.

[fabern]

@marcadella
Point 2/6: I believe adding the 'gridcell area fraction occupied by each land unit (tile) to output' still would make sense for two reasons linked to clarity, robustness and convenience for the user.

a) to make calculations of fluxes for the planet, we'd need the fluxes either as flux per gridcell area or then as flux per tile area + the tile area/fraction. Most convenient is if the area or fraction is reported in the output too. This further allows to easily also plot the evolution of land use types in terms of surface area.

b) Secondly, the evolution of the area might be more or less explicit in the input specification. This depends we specify the input (e.g. if we just specify which fraction of land transitions then we'd need to make an additional calculation to know how much there is at each point in time). The least error prone again is to add it as a state variable to the output.

EDIT: only reading now your third point addressed at stineb. So even if the state is provided by LUH2. Is it already clear if we add this to the input to BiomeE? Or will we only include the transitions? Regardless, better make it explicit in the output, too.

@marcadella
Point 6/6: Yes. My question was intended to understand whether there is some globally available data in LUH2 that can be used to define the PFTs present.

[marcadella]

@fabern
Point 6/6: LUH2 tells us only broad crop types (C3/4 annual/perennial and C3 N fixator), and gives an indication on the potential natural vegetation cover Beni talked about (forested vs non-forested). Nothing more.