Review NorESM spin-up routine and adapt it to our needs
Opened this issue · 6 comments
The description in the NorESM docu is comprehensible and comprehensive.
It addresses:
- Creation of atmospheric forcing (for spin-up) from coupled NorESM runs
- Accelerated decomposition (duration and meaning)
- Normal decomposition (duration)
It targets:
- global coupled model simulations
- biogeochemistry (bgc) simulations with active crop module
What should our own documentation address?
-> The target audience is new group members getting started.
Answers to FAQ:
- Why do we do a spin-up? (purpose)
- Which variables are important to check? #Carbon pools, leaf area index,...
- When is a spin-up needed/when not?
- How long should a spin-up be? # Rules of thumb (global/single-site -> the longer, the higher the latitude)
- How to perform a spin-up (with bgc, fates, ...)? #Could be linked to NorESM/CESM documentation?
- What is accelerated decomposition?
Issues:
We might create duplications with existing documentation.
But we should aim for a concise summary of the important steps for a typical user.
We should link to the NorESM/CESM documentation for further details (see link above for NorESM).
@kjetilaas Please check and refine what I have written!
Fig.1 Example spin-up for single cell case Brazil
- Why do we do a spin-up?
The idea behind doing a so-called spin-up is to reach an equilibrium state in your model. Typically any perturbation (e.g. 2x CO2) experiment starts from such a state. Running our perturbed system into equilibrium again will give you the maximum impact of the perturbation. - Which variables are important to check?
Since we are interested in the equilibrium state of our system, the "slowest" variables matter the most (e.g. terrestrial soil carbon). If you are running in BioGeoChemistry (BGC) mode, it is important to check the "health" of your vegetation. The variable directly associated with the health is Total Leaf Area Index (TLAI). If this is 0 your vegetation is dead and something went really wrong. - How long should a spin-up be?
The overall duration (years before an equilibrium state is reached) varies. As mentioned above, the variables with the slowest turnover rate will define the time you'd need to spend for your spin-up. The rule of thumb for single-cell simulation is the higher the latitude the longer the spin-up. E.g. spinning up a single cell case in the Tropics will approximately take 2x100 years after which the terrestrial carbon pools are in equilibrium. In the polar regions, it will take a couple of 1000 years! - What does equilibrium mean?
Typically you'd cycle through a range of given meteorological years - referred to as time-slice (e.g. 1990-2000). After an initial rapid increase in your variables, you will start to see the interannual variability of the chosen time slice (wiggling). Equilibrium is reached as soon as consecutive time slices differ by less than a threshold that you have to choose (< 0.1-1%). - How to perform a spin-up?
Usually, we do a two-staged spin-up. See the necessary XML change commands below.
- Accalorated decomposition (reduced size of carbon pools)
./xmlchange CLM_NML_USE_CASE="2000_control"
./xmlchange DATM_CLMNCEP_YR_START="1991"
./xmlchange DATM_CLMNCEP_YR_END="2010"
./xmlchange DATM_PRESAERO="clim_2000"
./xmlchange CCSM_CO2_PPMV="369."
./xmlchange STOP_OPTION="nyears"
./xmlchange RUN_REFDATE="0001-01-01"
./xmlchange RUN_STARTDATE="0001-01-01"
#Additional xml changes for AD mode
./xmlchange CLM_ACCELERATED_SPINUP="on"
#Number of years for spin-up
#For Tropics only STOP_N=100 is needed!
./xmlchange STOP_N=100
#Frequency of restart files (1/4 of STOP_N)
./xmlchange REST_N=25
#Setting wall clock time (on saga 5 years / 30 min)
#./xmlchange --subgroup case.st_archive JOB_WALLCLOCK_TIME=36:00:00
./xmlchange JOB_WALLCLOCK_TIME=36:00:00
./case.setup
./preview_namelists
- Normal spin-up (original size of carbon pools)
./xmlchange CLM_FORCE_COLDSTART="off"
./xmlchange CONTINUE_RUN="FALSE"
#Re-use directory but re-define reference time
./xmlchange RUN_REFDATE="0401-01-01"
./xmlchange RUN_STARTDATE="0401-01-01"
#Additional xml changes for AD mode
./xmlchange CLM_ACCELERATED_SPINUP="off"
./xmlchange STOP_N=100
#Frequency of restart files (1/4 of STOP_N)
./xmlchange REST_N=25
#Setting wall clock time
#./xmlchange --subgroup case.st_archive JOB_WALLCLOCK_TIME=36:00:00
./xmlchange JOB_WALLCLOCK_TIME=36:00:00
./case.setup
#Point to restart file (IMPORTANT: Do not forget the single-quotationmarks '<path to restart file>')
echo "finidat = '${restart_file}'" >> user_nl_clm
echo "Restart file: ${restart_file}"
I'm moving to a better repo name and template now. Could @kjetilaas please review the suggested changes of @ziu1986?
I think this looks good. I would only add a link to the escomp documentation on this, and a short comment on how this is different/complements that:
https://escomp.github.io/ctsm-docs/versions/master/html/users_guide/running-special-cases/Spinning-up-the-biogeochemistry-BGC-spinup.html
Also, the figure seemed to be missing on the rtd page.
Thank you for your comments @kjetilaas !
Could you please add your suggested change as a pull request in this repo? The changes made by @ziu1986 you can find here.
I will make sure that the figure comes a long in the new doc-page so no need to worry about that in the review.