From scratch

JULES From Scratch is an alternative how-to for those who don't work on a system where Cylc, Rose and FCM have already been installed and/or can't use the Met Office Virtual Machine (e.g. for security reasons). I (Toby Marthews) wrote the first version of it in 2017. I'm also assuming little or no familiarity with any recent version of JULES.

I've been using JULES since 2008 when I was involved with a carbon cycle project at Univ. Oxford (which led to Marthews et al. 2012). During the first half of 2017 (now working at UKCEH) I rewrote and reorganised the JULES website (i.e. this website you are reading). As part of this, I created new pages there for all the JULES tutorials I could find (under Training) and a complete set of pages about how to get started using the model (under Getting Started).

JULES From Scratch is my tutorial for JULES. In order to follow it and get JULES running, you will need quite a few things in place on your system first (please check through this list of necessities). If you have all those in place, you just need to install a few programs on your Linux/UNIX system (see below) and you'll be good to go. Keep this window open, and then open the slides and/or the video below:


Click here for slides: PDF icon 20210716_JULES From Scratch.pdf

Click here for a video version (n.b. with subtitles if you click on the "CC" button).


Install Cylc, Rose and FCM and cache your MOSRS password

You need to have three programs installed on your system: Cylc, Rose and FCM. All three of these are necessary for running JULES and I've done a page about installing each with all the steps required (linked here below).

Ideally, these three will be installed globally by your system administrator, but if that isn't possible (or you are the system administrator) then you will need to go through some/all of these steps for a local installation. First check what is on your system by putting these commands into a UNIX shell:

cd ~
echo $SHELL
     #You need to be in a bash shell, so if this returns anything except "/bin/bash" ask your system administrator how you can get into bash
xmessage -center hello!
     #You need to have X11 forwarding activated. If this opens a little window to say Hello then you are OK, but if it says "Can't open display" then check (i) you did use "-X" in the options to log in on your ssh command and (ii) your terminal program (e.g. MobaXTerm, XQuartz) has been set up to accept X11 Forwarding.
cat ~/.bashrc
     #Check your .bashrc file and make sure that it has been set up correctly. For example, on JASMIN you need to have a PATH= command in there (described here) to get Cylc, Rose and FCM working.
cylc check-software
     #If Cylc is installed, this will give you a message saying "Core requirements: OK" (you don't need "Full-functionality": partial functionality is fine (e.g. you might be missing the PyGraphviz, Sphinx or PyGTK libraries, but this is OK); it'll also warn you if you are missing Python itself (you need vn>=2.6))
rose --version
     #Just check you don't get "command not found"
fcm --version
     #Just check you don't get "command not found" (it's OK if the locale is not set properly, e.g. "Setting locale failed")

EVEN IF ALL SEEM TO BE INSTALLED OK, your personal profile settings may not be correct for using JULES so please do anyway go through the installation links below to make sure your environment setup is OK and your MOSRS password has been correctly cached.

  • Install Cylc from GitHub following these steps
  • Install Rose from GitHub following these steps (inc. what goes in your ~/.metomi/rose.conf file, which each user needs to set up separately)
  • Install FCM from GitHub following these steps (includes caching your MOSRS password *** which is compulsory for all users before using JULES *** and what goes in your ~/.subversion/servers and ~/.metomi/fcm/keyword.cfg files, which each user needs to set up separately)
  • Install JULES itself following these steps (this includes the download command for getting hold of a particular version of JULES).


Once you have all of that installed, you're ready to actually use the model (!). Most likely you will wish to run JULES for a particular site or region. As explained here, this will involve assembling control files, driving data and ancillary data, which collectively are called a configuration for the run.

I should stress at this point that I'm not an Iris user, but the majority of JULES users are (for Iris see here and here). I have used Python a lot, but I prefer using NCO tools and R as much as possible and this (obviously) influences what tools I find useful below. I prefer R to Python because I find the graphics options much more advanced than Python (e.g. lattice plots, ggplot2) and I prefer NCO tools because, although the syntax is pretty horrible until you get used to it, they allow you to manipulate NetCDF files in single commands with no memory restrictions on large files as you have doing it in Python or R (or any other script language).

Finally, take a note of the following Rose suite codes that are examples I maintain for 'easy' runs of JULES (that is 'easy' in the sense of 'not very easy, but easier than most other options'!) and see here for code release details. Good luck!


 Point run Loobos on JASMIN

Global run at 0.5° resolution (WFDEI data in 1D land-axis format) on the UKCEH linux box platform wllf00x

n.b. these suites require this dump file to run

Global run at 0.25° resolution (eartH2Observe data on 2D grid) on JASMIN
JULESvn5.1 u-bp696 
JULESvn5.2 u-am539 
JULESvn5.3 u-bf460 
JULESvn5.4 u-bp697 
JULESvn5.5 u-bp698 


(n.b. up to vn5.6 there was a bug in JULES: selecting output frac_fplain_lp with overbank inundation OFF caused a seg fault)



n.b. Loobos is an EXAMPLE, not a RECOMMENDED set of parameters for a JULES point run (see Example configurations here): for a best point run for a particular location, you need to modify the soil and other ancillary data appropriately.


** Apologies: this doesn't quite work yet (July 2021) **


** needs to run with Toby's branch vn6.0_hj and requires access to the LSPCEH workspace on JASMIN **

  • Now return to the PDF linked above for the next steps.