Training - Video tutorial

Tutorial 1 – Check out and go

Objective – [Duplicate and] check out an existing suite and modify for your computer system

1. Cache met office repository password
2. Checkout JULES at version 5.2 release to an appropriate location
   • fcm checkout fcm:jules.x_tr@vn5.2 $HOME/JULES/vn5.2
   • [If you don't have the fcm keywords set up use: fcm checkout https://code.metoffice.gov.uk/svn/jules/main/trunk@12251 $HOME/JULES/vn5.2]
3. Start rosie using: “rosie go”
4. Search for and copy suite number: u-bb219
   • Right click on the suite and select copy. This will create your own suite, with aunique ID, that you are free to edit and commit to the repository to save any changes you make.
   • (Please note, I do not do this step in the video below.)
5. Open your newly created suite, this will trigger a couple of warning messages regarding your meta data, hence the first task:
6. Update the fcm-make and jules metadata paths to your JULES version 5.2 release location
   1. Click on the fcm-make tab in the left hand column, and replace the dummy path with ~/JULES/vn5.2/rose-meta/jules-fcm-make/HEAD
   2. Click on the jules tab in the left hand column, and replace the dummy path with ~/JULES/vn5.2/rose-meta/jules-standalone/HEAD
   • Your suite now knows how to treat all the options you want to provide
7. Configure the fcm-make options:
   1. Click on the fcm make -> Build Configuration tab.
   2. If you are using a platform known by jules, select the appropriate platform from the drop down box.
   3. If not you need to know your fortran compiler and the location of your netCDF libraries. You do not need to include the OMP or MPI parallesation options for this suite.
8. Configure the JULES configuration:
   • Choose an appropriate output location (I recommend '$HOME/JULES_Tutorial/output' for compatibility with my plotting script)
   • ensure you create this output directory: mkdir -p '$HOME/JULES_Tutorial/output'
9. Check and Save the suite (the "ABC" button), then Run the suite (the play button)
   • This will open a gui control window which informs you of the status of your "job".
   • There are 2 stages for this job, fcm_make and jules.
10. When the job has succeeded open up the suite location from the "Tools" drop down menu.
11. You can plot the output using JT_plot_output.py from this terminal:
    • ./JT_plot_output.py [-data_dir /your/output/directory]
12. If all this has worked you can commit your changes to your repository using the "fcm commit" commandfrom the terminal
    • This opens your terminal defaul text editor, usually vi. Enter here a message you want to accompany your suite revision, e.g. "my first successful jules run".
      • To start typing in vi press the "i" key, when  you have finished typing press "Esc", to save and close type ":wq" then hit return.
    • After you close you the text editor confirm that you want to commit the changes.
    • (Please note, this step is not included in the video tutorial)

(Please note, the above instructions have been updated following a JULES training course, hence the video below follows a slightly different sequence)

Tutorial 2 – Spin me round

Objective – Familiarise yourself with run options in the rose/cylc environment by Investigating the effect of model spin up.

1. Continue from Tutorial 1
2. Go to the spin up tab in the rose suite
3. Set up and run a simulation with no spin up and output the data with an appropriate run_id (e.g. spinup_0).
4. Set up and run simulations with 1, 5 and 10 year spin up durations and output with appropriate run-ids (e.g. spinup_1, spinup_5 and spinup_10).
   • Note here you will have to wait until the previous simulation has completed until you can start the next simulation
5. When all are complete open up the terminal using Tools -> "Launch Terminal" and plot the output using JT_plot_output_multi.py, i.e. if the recommend run_ids were used:
   • ./JT_plot_output_multi.py -run_ids spinup_0,spinup_1,spinup_5,spinup_10
6. If all this has worked you can commit your changes to your repository using the "fcm commit" command from the terminal.
   • This opens your terminal defaul text editor, usually vi. Enter here a message you want to accompany your suite revision, e.g. "my first successful jules run".
     • To start typing in vi press the "i" key, when  you have finished typing press "Esc", to save and close type ":wq" then hit return.
   • After you close you the text editor confirm that you want to commit the changes.
   • (Please note, this step is not included in the video tutorial)

Tutorial 3 – Go green

Objective - Familiarise yourself with science options in the rose/cylc environment by investigating various vegetation options.

1. Continue from Tutorial 2
2. Head to the science settings -> vegetation tab. Nothing is set to true, in particular the l_phenol and l_triffid options. This means we are using static vegetation (constant lai and canopy height), which will be our first simulation.
3. Whilst we are here, lets activate the various _fix options, set l_trait_phys=True, can_model=4 and can_rad_mod=6 which will make our simulation a little more up-to-date. To see the documentation regarding these options please refer to the JULES user guide.
4. Head back to the output tab and change the run_id to something relevant, e.g. Static_Vegetation.
5. Head to the output -> profiles -> (1) tab and add gpp_gb to the output variables (for a  full list of output variables refer to the JULES user guide)
6. Save and Run the simulation.
7. For our next run we are going to activate leaf phenology, head to the science options -> vegetation tab and set l_phenol to True…. Various warning messages have popped up, address all these issues:
   • phenol_period = 1
   • add lai to the initial conditions with a constant value of 3
8. Head back to the output tab and change the run_id to something relevant, e.g. Phenol_Vegetation.
9. Save and Run the simulation.
10. For our next run we are going to activate leaf phenology, head to the science options -> vegetation tab and set l_triffid to True…. Various warning messages have popped up, address all these issues:
    • triffid_period = 1
    • soil biogeochemistry model = RothC
    • add canht to the initial conditions with a constant value of 3
11. Head back to the output tab and change the run_id to something relevant, e.g. TRIFFID_Vegetation.
12. Save and run the simulation
13. When all are complete open up the terminal using Tools -> "Launch Terminal" and plot the output using JT_plot_output_multi.py, i.e. if the recommend run_ids were used:
    • ./JT_plot_output_multi.py -run_ids Static_Vegetation,Phenol_Vegetation,TRIFFID_Vegetation

14. If all this has worked you can commit your changes to your repository using the "fcm commit" command from the terminal.

    • This opens your terminal defaul text editor, usually vi. Enter here a message you want to accompany your suite revision, e.g. "my first successful jules run".

    • To start typing in vi press the "i" key, when  you have finished typing press "Esc", to save and close type ":wq" then hit return.

    • After you close you the text editor confirm that you want to commit the changes.

    • (Please note, this step is not included in the video tutorial)

Tutorial 4 – All square

Objective - Set up and run global gridded simulation and plot the output. This tutorial is based on the practical example made by Toby Marthews'.

1. Download the ancillary and met driving data from Toby Marthews' website and extract the files to somewhere sensible.
   • https://www.tobymarthews.com/jules-short-course-2016.html
   • For consistency with the commands given in this tutorial I recommend extracting all the zipfiles to "$HOME/JULES_Tutorial/gridded/data"
2. Check out the version 5.2 release of JULES (Tutorial 1, step 2)
3. Copy and check out the suite u-am539 from the rose repository. Open the rose gui for your newly created suite.
4. Update the metadata paths in the suite (Tutorial 1, step 6)
5. Check the fcm build configuration matches your machine (Tutorial 1, step 7)
6. Update the paths of the ancilary files and driving data in the rose suite.
   • Edit the "Driving Data" and "Ancillary Data" tabs in left hand column to point to your data directory ("$HOME/JULES_Tutorial/gridded/data").
   • It is possible possible to make this change by editting the configuration file with a text editor as is sown in video. The configuration file is saved in your rose suite directory: $HOME/roses/[SUITE-ID]/app/jules.rose-app.conf. i.e. Search and replace:
     • "/users/global/tobmar/MODELS/iofiles/io_wetlands/ancils/" -> to your ancillary data directory ("$HOME/JULES_Tutorial/gridded/data")
     • "/prj/nceo/wfdei" -> to your driving data directory ("$HOME/JULES_Tutorial/gridded/data")
7. Change the duration of the run to the first 15 days of June by editting the Timestepping namelist.
8. Change the output directory (output_dir) to something sensible:
   • output_dir = $HOME/JULES_Tutorial/gridded/output
   • You could also change the run_id to something descriptive, $ROSE_TASK_NAME is a rose environment variable which in this case would take the value "jules".
9. You can now run the suite using the play button.
   • It is also possible to run a suite from the command line by executing "rose suite-run" from the suite directory ($HOME/roses/[SUITE-ID]
10. When the simulation has complete navigate to the output direcotry to look at the data using ncdump:
    • cd $HOME/JULES_Tutorial/gridded/output
    • ncdump -h jules.Base.nc
    • This shows us all the data stored in our output file.
    • To save space JULES stores all output on 1 dimensional land vectors.
11. To plot the data in 2D we will use a simple script (plot_JULES_2D_output.py) I created and I have stored on the JULES repository,
    • To export the script from the command line using fcm:
      • fcm export https://code.metoffice.gov.uk/svn/jules/main/branches/pkg/edwardcomynplatt/r13496_python_packages_ECP/share/plot_JULES_2D_output.py
    • to execute the script to plot the mean grid box skin temperature:
      • python2.7 plot_JULES_2D_output.py jules.Base.nc tstar_gb mean None