Commit 5a035026 authored by Gesa Meyer's avatar Gesa Meyer
Browse files

Merge branch 'preReleaseV2' into develop

parents 58d0a1b1 328ab729
Loading
Loading
Loading
Loading
+1 −1
Original line number Diff line number Diff line
@@ -759,7 +759,7 @@ WARN_LOGFILE =
# Note: If this tag is empty the current directory is searched.
# IT SEEMS THAT .F90 files are not found and it is easier to specify here!

INPUT                  = src/driver src/base documentation src/base/canopyWaterUpdate.F90  src/base/classicParams.F90  src/base/ctemDriver.F90  src/base/energBalNoVegSolve.F90  src/base/energBalVegSolve.F90  src/base/errorHandler.F90  src/base/mainCore.F90 src/driver/CLASSIC.F90 src/driver/fileIOModule.F90 tools/outputVariableEditor tools/metASCIILoader tools/initFileConverter tools/modifyRestartFile tools/convertOutputToCSV tools/ghgASCIILoader tools/regression_testing
INPUT                  = src/driver src/base documentation src/base/canopyWaterUpdate.F90  src/base/classicParams.F90  src/base/ctemDriver.F90  src/base/energBalNoVegSolve.F90  src/base/energBalVegSolve.F90  src/base/errorHandler.F90  src/base/mainCore.F90 src/driver/CLASSIC.F90 src/driver/fileIOModule.F90 tools/outputVariableEditor tools/metASCIILoader tools/modifyRestartFile tools/convertOutputToCSV tools/ghgASCIILoader tools/regression_testing

# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
+1 −1
Original line number Diff line number Diff line
@@ -72,7 +72,7 @@ OBJ = classicParams.o ctemStateVars.o classStateVars.o ctemOutputVars.o generalU
	soilHeatFluxCleanup.o waterBaseflow.o  balanceCarbon.o autotrophicRespiration.o phenology.o  \
	turnoverMod.o mortality.o fireenergycl.o disturbance.o competitionMod.o landuseChangeMod.o \
	allocateCarbon.o heterotrophicRespirationMod.o soilCProcesses.o \
	tracer.o readFromJobOptions.o outputManager.o modelStateDrivers.o dynamicTiling.o tiledDisturbance.o ctemDriver.o \
	tracer.o readFromJobOptions.o modelStateDrivers.o outputManager.o dynamicTiling.o tiledDisturbance.o ctemDriver.o \
	prepareOutputs.o metModule.o mainCore.o main.o xmlParser.o \
	xmlManager.o n_processes.o bnf.o nvolatil.o nitrification.o denitrification.o nleach.o \
	nuptake.o nallocate.o nlitter.o nhumific.o nMineralImm.o balnitro.o CLASSIC.o
+13 −9
Original line number Diff line number Diff line
@@ -2,14 +2,15 @@

1. @subpage modelParams
2. @subpage forcingData
3. @subpage vegetationData
3. @subpage geophysData
 - @subpage vegetationData
    - @subpage vegCLASSonly
    - @subpage vegCTEMtoo
4. @subpage soilData
5. @subpage initProgVar
 - @subpage soilData
4. @subpage initProgVar
  - @subpage initPhysProgVar
  - @subpage initCTEMProgVar
6. @subpage exModSets 
3. @subpage exModSets 

----

@@ -110,12 +111,15 @@ The length of the time step should be carefully considered in assembling the for

**Note** The meteorological forcing data can be either given to the model at the physics timestep (e.g. site-level forcing at 30 mins for a physics timestep of 30 mins), or at a coarser temporal resolution (e.g. 6 hourly for a physics timestep of 30 minutes). If the forcing is the same temporal resolution as the physics, then it is used as read-in. If it is coarser, CLASSIC will do disaggregation following the logic in @ref metModule.f90.

# Geophysical model input fields {#geophysData}

# Input Vegetation Data {#vegetationData}
CLASSIC has several mandatory input fields

## Input Vegetation Data {#vegetationData}

CLASSIC can be run with either dynamic vegetation (CTEM+CLASS) or a physics only simulation (CLASS). The model inputs differ between the two configurations with some input vegetation data for a CLASS-only run ignored when CTEM is turned on. As well CTEM requires some additional inputs not needed for CLASS-only runs as described below.

## Required vegetation data {#vegCLASSonly}
### Required vegetation data {#vegCLASSonly}

The typical main vegetation categories for the model physics (CLASS) are needleleaf trees, broadleaf trees, broadleaf shrubs, crops and grass (e.g. ican = 5). However this is adaptable and can include further PFTs depending on model configuration. There are checks in the model code that look for known PFTs (e.g. 'NdlTr', 'BdlTr', 'BdlSh', 'Crops', 'Grass'). If a PFT is introduced that is not known, the model will bail and let the user know where the PFT check failed. This is designed to prevent poorly considered additions and ensure developers are aware of where the different PFTs branch in the code. Urban areas are also treated as “vegetation” in the CLASS code, and have associated values for *FCAN*, *ALVC*, *ALIC* and *LNZ0* (see below). Thus these arrays have a larger dimension of `ican + 1` rather than `ican`.  

@@ -132,7 +136,7 @@ For each of the CLASS PFTs the following data are required for each mosaic tile
 8. **ROOT** Annual maximum rooting depth of vegetation category [m]


### Variables not presently read in
#### Variables not presently read in

These variables are not presently read-in by CLASSIC but could be if desired. Model code changes would be required.

@@ -167,7 +171,7 @@ For the non-required stomatal resistance parameters, typical values for the four
\end{array}
\f]

## Required vegetation data for a biogeochemical simulation (CLASS+CTEM) {#vegCTEMtoo}
### Required vegetation data for a biogeochemical simulation (CLASS+CTEM) {#vegCTEMtoo}

In addition to the CLASS variables described above, CTEM requires the following further information about the vegetation:

@@ -175,7 +179,7 @@ In addition to the CLASS variables described above, CTEM requires the following

If land use is being simulated this value will come from a land use change file (see @ref inputLUC) otherwise (if in the job options file: lnduseon = .false. and fixedYearLUC = -9999) it is taken from the model initialization file and kept constant thoughout a run (provided competition between PFTs is not turned on). 

# Input Soil Data {#soilData}
## Input Soil Data {#soilData}

All simulations require:

+82 −45
Original line number Diff line number Diff line
@@ -278,46 +278,101 @@
  language  = "en"
}

@ARTICLE{Wang2025-gx,
  title    = "Impact of topography and meteorological forcing on snow simulation
              in the Canadian Land Surface Scheme Including Biogeochemical
              Cycles ({CLASSIC})",
  author   = "Wang, Libo and Mudryk, Lawrence and Melton, Joe R and Mortimer,
              Colleen and Cole, Jason and Meyer, Gesa and Bartlett, Paul and
              Lalande, Micka{\"{e}}l",
  journal  = "EGUsphere",
  pages    = "1--37",
  abstract = "Abstract. Our study evaluates the impacts of an alternate snow
              cover fraction (SCF) parameterization on snow simulation in the
              Canadian Land Surface Scheme Including Biogeochemical Cycles
              (CLASSIC). Three reanalysis-based meteorological datasets are used
              to drive the model to account for uncertainties in the forcing
              data. While the default parameterization assumes a simple linear
              relationship between SCF and snow depth with no dependence on
              topography, the alternate parameterization accounts for the
              topographic effects of sub-grid terrain on SCF. We show that the
              alternate parameterization improves SCF simulated in CLASSIC
              during winter and spring in mountainous areas for all three
              choices of meteorological datasets. Annual mean bias, unbiased
              root mean squared area, and correlation improve by 75 \%, 32 \%,
              and 7 \% when evaluated with MODIS SCF observations over the
              Northern Hemisphere. We also demonstrate that the improvements to
              simulated SCF lead to further improvements in variables related to
              surface radiation, energy fluxes, and the water cycle. Finally, we
              link relative biases in the meteorological forcing data to
              differences in simulated snow water equivalent and SCF. Assessment
              of simulations with different combinations of SCF
              parameterizations and meteorological datasets reveals the large
              impact of meteorological forcing on snow simulation in CLASSIC.
              Two out of the three meteorological datasets were bias-adjusted
              using observation-based datasets. However, simulations forced by
              the dataset without bias correction outperform relative to
              simulations forced by datasets with bias correction, suggesting
              that there are large uncertainties in the observation-based
              datasets and/or methods used for bias correction. This study
              underscores the importance of accounting for topographic effects
              of sub-grid terrain and accurate meteorological forcing on snow
              simulation in land surface models.",
  month    =  mar,
  year     =  2025,
  doi      = "10.5194/egusphere-2025-1264",
  language = "en"
}


@ARTICLE{Gauthier2024-nx,
@ARTICLE{Gauthier2025-vw,
  title     = "Parameter optimization for global soil carbon simulations: Not a
               simple problem",
  author   = "Gauthier, Charles B and Melton, Joe R and Meyer, Gesa and S, Raj
              Deepak and Sonnentag, Oliver",
  journal  = "ESS Open Archive",
  abstract = "Accurate simulation of soil organic carbon (SOC) dynamics by
              terrestrial biosphere models is hampered by poorly constrained
  author    = "Gauthier, Charles B and Melton, Joe R and Meyer, Gesa and Raj
               Deepak, S N and Sonnentag, Oliver",
  journal   = "Journal of advances in modeling earth systems",
  publisher = "American Geophysical Union (AGU)",
  volume    =  17,
  number    =  8,
  pages     = "e2024MS004577",
  abstract  = "AbstractAccurate simulation of soil organic carbon (SOC) dynamics
               by terrestrial biosphere models is hampered by poorly constrained
               parameters and parameter equifinality, amongst other issues. To
               address this, we use Bayesian optimization to constrain the 16
               SOC-related parameters in the Canadian Land Surface Scheme
               Including biogeochemical Cycles (CLASSIC). We employed a global
              sensitivity analysis (Sobol') to develop four parameter sets based
              upon different sensitivity criteria. We then optimized each set
              against observed SOC (World Soil Information Service; WoSIS) and
              soil respiration (Soil Respiration Database; SRDB). Using two
               sensitivity analysis (Sobol') to develop four parameter sets
               based upon different sensitivity criteria. We then optimized each
               set against observed SOC (World Soil Information Service; WoSIS)
               and soil respiration (Soil Respiration Database; SRDB). Using two
               different loss functions; one focused on reproducing the
               observational mean value, and the other explicitly accounting for
               an estimated observational uncertainty. The best optimized
              parameter sets from each loss function had an average relative
              difference of 61\%. Thus the choice of loss function impacts what
              parameter values are deemed optimal and should be considered
              carefully. The final selected optimal parameter set saw a 12\%
              improvement against WoSIS and SRDB, had global SOC totals in line
              with literature estimates, and better simulated high-latitude SOC
              stocks evaluated against the Northern Circumpolar Soil Carbon
              Database (RMSD: 16.39 vs. 17.61; bias: -5.57 vs. -10.78 kg C m2)
              compared to the default CLASSIC parameters. However, some
              parameters were not well constrained, in particular those of
              needle-leaf deciduous trees which dominate Siberian boreal
              forests, a region relatively poorly observed in WoSIS and SRDB.
              Future work should apply further constraints on the optimization
              framework and address observational gaps.",
  month    =  jul,
  year     =  2024,
  doi      = "10.22541/essoar.172167442.20510812/v1"
               parameter sets for each loss function had an average relative
               difference of 61\%. Thus, the choice of loss function impacts
               what parameter values are deemed optimal and should be considered
               carefully. The final set of selected optimal parameters saw a
               12\% improvement against WoSIS and SRDB, had global SOC totals in
               line with literature estimates, and better simulated
               high-latitude SOC stocks evaluated against the Northern
               Circumpolar Soil Carbon Database (RMSD: 16.39 vs. 17.61; bias:
               -5.57 vs. -10.78 kg C ) compared to the default CLASSIC
               parameters. However, some parameters were not well constrained,
               in particular those of needle-leaf deciduous trees that dominate
               the Siberian boreal forests, a region relatively poorly observed
               in WoSIS and SRDB. Future work should apply further constraints
               on the optimization framework and address observational gaps.",
  month     =  aug,
  year      =  2025,
  keywords  = "soil organic carbon; land surface model; Bayesian optimization;
               sensitivity analysis; soil respiration; CLASSIC",
  doi       = "10.1029/2024ms004577",
  issn      = "1942-2466",
  language  = "en"
}



@ARTICLE{MacKay2022-do,
  title     = "On the Discretization of Richards Equation in Canadian Land
               Surface Models",
@@ -4500,24 +4555,6 @@
  doi      = "10.1029/2018MS001490"
}

@ARTICLE{cite Curasi2022-ss,
  title     = "Evaluating the performance of the Canadian Land Surface Scheme Including Biogeochemical Cycles (CLASSIC) tailored to the pan-Canadian domain",
  author    = "Curasi, S.R., Melton, J.R., Humphreys, E.R., Wang, L., Seiler, C., Cannon, A., Chan, E. and Qu, B.",
  abstract  = "Canada's boreal forests and tundra ecosystems are responding to unprecedented climate change with implications for the global carbon (C) cycle and 
  global climate. However, our ability to model the response of Canada's terrestrial ecosystems to climate change is limited and there has been no comprehensive,
   process-based assessment of Canada's terrestrial C cycle. We tailor the Canadian Land Surface Scheme Including Biogeochemical Cycles (CLASSIC) to Canada and evaluate 
   its C cycling performance against independent reference data. We utilize skill scores to assess model performance against reference data alongside benchmark scores that 
   quantify the level of agreement between the reference data sets to aid in interpretation. Our results demonstrate CLASSIC's sensitivity to prescribed vegetation cover. 
   They also show that the addition of five region-specific PFTs improves CLASSIC's skill at simulating the Canadian C cycle. CLASSIC performs well when tailored to Canada,
    falls within the range of the reference data sets, and meets or exceeds the benchmark scores for most C cycling processes. New region-specific land cover products, well-informed 
    plant functional type (PFT) parameterizations, and more detailed reference data sets will facilitate improvements to the representation of the terrestrial C cycle 
    in regional and global land surface models (LSMs). Incorporating a parameterization for boreal disturbance processes and explicitly representing peatlands and permafrost soils 
    will improve CLASSIC's future performance in Canada and other boreal regions. This is an important step toward a comprehensive process-based assessment of Canada's terrestrial 
    C cycle and evaluating Canada's net C balance under climate change.",
  journal   = "ESSOAr",
  year      =  2022,
  doi       = "https://doi.org/10.1002/essoar.10512727.1"
}

@ARTICLE{Canada_Fire_Danger_Group1992-bt,
  title   = "Development and structure of the Canadian forest fire behavior

documentation/cbc.md

0 → 100644
+3 −0
Original line number Diff line number Diff line
# Overview of the CLASSIC Benchmarking Collection {#cbc}

The CLASSIC Benchmarking Collection is...
 No newline at end of file
Loading