Restarting transient year simulations and Changing a parameter value

Here we are going to walk through how to restart an ELM run so that you can simulate a new transient period. This is useful for assessing the impact a change to parameter values will have on the current (transient) year model output.

Step 1: Setting up a workspace volume named "elmwork"

• Make a workspace volume by running the following code in a terminal window

docker volume create elmwork

Step 2: restarting an ELM simulation to produce one year of new transient phase data

• Run the following code in the terminal window

docker run -t -i --hostname=docker --user=modeluser -v elmdata:/inputdata/ -v elmoutput:/output/ -v elmwork:/tmp/ serbinsh/ngeearctic_elm_containers:elm_v2-for-ngee_multiarch /bin/bash /tools/OLMT/examples/site_fullrun_docker_transient_nyears.sh --transient_years=1

• below this code is broken down by color to tell you what it is doing and some of the settings you can adjust if you want to:
  
  

INSTRUCTION for other sites, or if you'd like try your own spinup phases first

The above command is to run for one of four sites, Kougarok. The command for other sites, are as follows.
NOTE: you have to run a quick run as shown in Option 1. quick run.
PLEASE note that 2 extra options appending: --site_name=* --init_ncfile=/output/cime_run_dirs/quick_run_AK-*_ICB1850CNPRDCTCBC.elm.r.????-01-01-00000.nc. You must be sure site_name is consistent with init_ncfile which MUST be existed. Also --case_prefix=quick_run for spinup stages while --case_prefix=Myrun for later transient stage, which can be edited as your own.

Site beo:

docker run -t -i --hostname=docker --user=modeluser -v elmdata:/inputdata/ -v elmoutput:/output/ -v elmwork:/tmp/ serbinsh/ngeearctic_elm_containers:elm_v2-for-ngee_multiarch /bin/bash /tools/OLMT/examples/site_fullrun_docker_transient_nyears.sh --transient_years=1 --case_prefix=Myrun --site_name=beo --init_ncfile=/output/cime_run_dirs/quick_run_AK-BEOG_ICB1850CNPRDCTCBC.elm.r.0041-01-01-00000.nc

Site teller:

MUST do a quick run first:

docker run -t -i --hostname=docker --user modeluser -v elmdata:/inputdata -v elmoutput:/output serbinsh/ngeearctic_elm_containers:elm_v2-for-ngee_multiarch /scripts/OLMT_docker_example.sh --site_name=teller --ad_spinup_years=20 --final_spinup_years=30 --transient_years=5 --case_prefix=quick_run

THEN,

docker run -t -i --hostname=docker --user=modeluser -v elmdata:/inputdata/ -v elmoutput:/output/ -v elmwork:/tmp/ serbinsh/ngeearctic_elm_containers:elm_v2-for-ngee_multiarch /bin/bash /tools/OLMT/examples/site_fullrun_docker_transient_nyears.sh --transient_years=1 --case_prefix=Myrun --site_name=teller --init_ncfile=/output/cime_run_dirs/quick_run_AK-TLG_ICB1850CNPRDCTCBC.elm.r.0041-01-01-00000.nc

Site council:

MUST do a quick run first:

docker run -t -i --hostname=docker --user modeluser -v elmdata:/inputdata -v elmoutput:/output serbinsh/ngeearctic_elm_containers:elm_v2-for-ngee_multiarch /scripts/OLMT_docker_example.sh --site_name=council --ad_spinup_years=20 --final_spinup_years=30 --transient_years=5 --case_prefix=quick_run

THEN,

docker run -t -i --hostname=docker --user=modeluser -v elmdata:/inputdata/ -v elmoutput:/output/ -v elmwork:/tmp/ serbinsh/ngeearctic_elm_containers:elm_v2-for-ngee_multiarch /bin/bash /tools/OLMT/examples/site_fullrun_docker_transient_nyears.sh --transient_years=1 --case_prefix=Myrun --site_name=council --init_ncfile=/output/cime_run_dirs/quick_run_AK-CLG_ICB1850CNPRDCTCBC.elm.r.0041-01-01-00000.nc

Site kougarok:

If you want to try your own for this site, then do a quick run first:

docker run -t -i --hostname=docker --user modeluser -v elmdata:/inputdata -v elmoutput:/output serbinsh/ngeearctic_elm_containers:elm_v2-for-ngee_multiarch /scripts/OLMT_docker_example.sh --site_name=kougarok --ad_spinup_years=20 --final_spinup_years=30 --transient_years=5 --case_prefix=quick_run

THEN,

docker run -t -i --hostname=docker --user=modeluser -v elmdata:/inputdata/ -v elmoutput:/output/ -v elmwork:/tmp/ serbinsh/ngeearctic_elm_containers:elm_v2-for-ngee_multiarch /bin/bash /tools/OLMT/examples/site_fullrun_docker_transient_nyears.sh --transient_years=1 --case_prefix=Myrun --site_name=kougarok --init_ncfile=/output/cime_run_dirs/quick_run_AK-K64G_ICB1850CNPRDCTCBC.elm.r.0041-01-01-00000.nc

Step 3: Examining new transient year data in Jupyter notebook

• In a NEW terminal window, copy, paste, and run the following command to start communication between Docker and JupyterLab notebook
  

docker run -t -i  -v elmdata:/home/jovyan/inputdata -v elmoutput:/home/jovyan/output/ -v elmwork:/home/jovyan/work/ -p 8888:8888 serbinsh/ngeearctic_elm_containers:elmlab_3.3.2

• When this code has run successfully, the terminal window will provide two URLs, either of which can be copied and pasted into a browser window to open the JupyterLab notebook.
  
• In the JupyterLab notebook, navigate to the scripts folder in the left-hand menu
  
• Double-click to open the notebook "plot_ELM_variable_2D.ipynb." Remember that you might have to expand the width of the left-hand menu in order to read the full names of all the notebooks there
  
• In the main JupyterLab workspace, you should see a document titled "An example of reading in and plotting one variable from ELM output" that has the NGEE Arctic logo. From here, you will follow the tutorial instructions in the JupyterLab notebook to plot a selected variable from the 1-year transient run. Note that there are a few dropdown menus in the JupyterLab notebook that allow you to select output from different simulation runs, look at data for all PFTs combined or individually, and choose specific years of transient data as well as specific output variables here.
  

Step 4: Changing parameter value

Provided steps 1-3 went well, you should have two terminal windows open: one that restarted the ELM transient year run and one that connected to the Jupyter Lab notebook to explore the data from that restarted transient year. You should also have a JupyterLab environment open in a browser window.

• In the JupyterLab environment, click the home folder icon at the top of the left-hand menu so that the subfolders inputdata, output scripts, and work are visible
  

• Open the work folder
  

• Open the Kougarok subfolder and double-click on the "clm_params.txt" to open it. The workspace on the right should look like this:
  
  

• In the clm_params.txt file, scroll down to lines 170-173. These have the header "slatop" and are highlighted purple in the image below. This is where the parameter is described (long name), units are given, and the group to which this parameter is applied are given (coordinates, in this case pftname)
  
  

• Scroll to lines 1104-1129. This is where you can what the pftname coordinate options are. There are 25 pft names given. For arctic simulations, we will be considering broadleaf_deciduous_boreal_shrub (#12 in the list) and c3_arctic_grass (#13 in the list).
  

• Now scroll to lines 1327-1329. You will see a list of 25 values for slatop, one for each pft name

• We are going to modify the the 13th value in this list from a value of 0.03 m2 gC leaf-1 to 0.0165 m2 gC leaf-1. Do this by double clicking the value and edit the text directly. This edit means this parameter is changed for all c3_arctic_grass in future simulations. Note that this is a made-up value for illustrating the process of changing a parameter. In reality, changing a parameter would be based on established values in literature or field/lab observations.
  
  

• JupyterLab will automatically save this modified version of clm_params.text. To be safe, though, you can also go to File and select "save text."
  

• The modified modified clm_params.txt will be used to overwrite clm_params.nc when you next run OLMT (OLMT requires .nc files)
  

Step 5: Rerunning one-year transient simulation with new parameter value

• Now that the parameter value for slatop has been modified, we want to rerun the one-year transient simulation with this new parameter in the mix. To do this, locate the terminal window where you ran the last transient restart in step 2. The last message in the terminal should read "DONE docker ELM runs !")
  
• Copy and paste the following command to restart the simulation using the site_fullrun_docker_transient_nyears.sh command. Note that this time we are restarting the simulation, we are specifying a new prefix to be assigned to the output ("MySLA") so this run can be differentiated from the earlier run that used the default prefix ("My").

docker run -t -i --hostname=docker --user=modeluser -v elmdata:/inputdata/ -v elmoutput:/output/ -v elmwork:/tmp/ serbinsh/ngeearctic_elm_containers:elm_v2-for-ngee_multiarch /bin/bash /tools/OLMT/examples/site_fullrun_docker_transient_nyears.sh --transient_years=1 --case_prefix=MySLA

Step 6: Visualizing newly simulated ELM output variables

• In the browser window that has the JupyterLab environment open, go to the notebook "Plot_ELM_variable_2D.ipynb" again.
• Click the circular arrow button near the run button to restart the kernel. This will allow the notebook to restart communication with docker and access the new simulation data you just produced.
• This time around in the notebook, you will want to select the output data from the simulation we just ran with a new slatop parameter value. Remember that this will have the prefix "MySLA" since we specified that in the transient restart command.
• Click around and explore some of the output variables to see how they were impacted by this change by alternating between the output from the original 1 year transient simulation and the new SLA transient run simulation. Make sure that whenever you change a dropdown menu option or a radio button, you do so when the blue progress bar was ABOVE the section of code you are choosing a new option for. If you hit run, the blue sidebar moves down, and the "old" section for the dropdown menu or the radio button shows up again then the code did not run with your new selection in place. Reselect and hit run again. If your run button disappears in the JupyterLab notebook (an annoying bug that we have noticed occasionally creeps in) then you should go to the menu button and select "run selected cells" or "run selected cell and all cells below" depending on whether you want to progress forward by one step or move through to the end of the notebook.
  
• The default output variable to look at is GPP but another interesting one to explore is TLAI (total projected leaf area index).
  
• If we put these graphs side by side, we can see how what differed between the two simulations.
  GPP of C3 arctic grasses (green line) was slightly higher with the SLA parameter value change:
  
  TLAI of C3 arctic grasses (green line again) was much lower following the SLA parameter value change:
  
  

Step 6: Save the modified parameter file so you know what you changed!

• Back in Docker Desktop, navigate to the Volumes tab in the left-hand menu
  
• Open elmwork folder
• In the list of containers listed under "In Use" one should have a green container symbol, indicating that it is active
  
• Select the "data" tab at the top of the container list. This should give you a folder named Kougarok that you can click to open. You should see a list of files that look like this:
  
  
• Click on the file named clm_params.txt and three dots should show up on the far right (past the filesize)
• Click the three dots and select "Save as..."
• Choose an appropriate location and filename to keep track of your work. You can see how tracking changes to the model and simulation output is an important part of keeping a clean and productive workflow going... the model output is only valuable as long as you know how it was produced!

Return to Home