Getting started

Here's how to get started as a JULES user:

• Get started
• Email/support lists
• Other files you need (configuration files):
  • Driving data
  • Ancillary data
  • Control files
• Analysis tools

Get started

• The first step is to request access to the code here. Registration is free and open to all for non-commercial use (registration is required just to keep track of who is using JULES, not to restrict usage). When you register, you will automatically be set up with a Met Office Science Repository Service (MOSRS) login (may take a few days), which will allow you to access the JULES TRAC.
• Next, bookmark the main JULES manual pages and also the namelist pages (which you'll need because of the excellent search box through which you can look up what particular model variables mean).
• Now do at least one of the tutorials on our training page, for example Toby's JULES From Scratch.

Email and support lists

• To subscribe, first follow this link and register yourself. After that, wait up to 10 minutes for the email confirming the registration, and then follow these links to subscribe to the jules and jules-users lists (managed by NCAS at Univ. Reading): 
•           JULES general interest: https://maillists.reading.ac.uk/scripts/wa-READING.exe?SUBED1=JULES (i.e. jules*A*T*maillists.reading.ac.uk)
            JULES users: https://maillists.reading.ac.uk/scripts/wa-READING.exe?SUBED1=JULES-USERS (i.e. jules-users*A*T*maillists.reading.ac.uk)
• If you want to unsubscribe from either list, you can go to the same subscription link. *** pls note you need to unsubscribe from BOTH lists to stop getting JULES mailings ***
• There is a JULES GitHub platform is now available for all to use for questions, support and discussions. For this, you will need a GitHub account you are prepared to use for work purposes.
• JULES is technically supported for running at the UK Met Office and on the JASMIN super data cluster. For all technical issues with JULES, Rose, Cylc or FCM, please check the documentation and tutorials on the JULES TRAC and JULES manual pages before emailing a support request.
•      JULES technical support for non-UK Met Office staff if using the JASMIN super data cluster is provided by Computational Modelling Services (CMS). *** n.b. change of system as of 1-JUl-21 ***: the NCAS-CMS Modelling Helpdesk is moving to a new Discourse Forum available at https://cms-helpdesk.ncas.ac.uk . To raise a new query, you will need to sign up for an account at https://cms-helpdesk.ncas.ac.uk. Please read the Welcome post for further information.
•           All non-JULES-related enquiries related to JASMIN services should be sent to JASMIN user support (provided by CEDA) support*A*T*jasmin.ac.uk (the email address support*A*T*ceda.ac.uk is now dedicated to support CEDA Archive and data service related issues only, e.g. data access).
•           Before submitting any query to CMS or JASMIN, however, please check the comprehensive documentation pages CEDA Help and JASMIN Help. Please note also that on JASMIN-related websites, there is a help beacon (shown by an orange question mark in the bottom right corner) which can be used to search help documents and also to submit helpdesk queries.
•      JULES technical support for UK Met Office staff (only!): jules-support*A*T*metoffice.gov.uk
• For JULES science support, see the configurations pages for details about the particular model configuration you are using. Use the MOSRS contact list if you need to contact someone specific.

Other files you need (configuration files)

When you start on a new project that uses Land Surface Model (LSM) simulation, you need to allocate a substantial amount of time to get the model running. LSMs are not 'plug in and play' systems: they need setting up and they need certain datafiles to be assembled before they can be run.

In common with all land surface models, JULES needs three elements to perform a simulation: driving data, ancillary/prescribed data and control files (together these are called the 'model configuration'). Here is a list of standard configurations for JULES.

Users are encouraged as far as possible to work from one of the CORE CONFIGURATIONS, although there are also non-core configurations in use for research and other purposes. The idea is that, as much as you can, you DON'T assemble your own configuration from scratch, but rather choose one of the pre-assembled configurations that is similar to what you want to do, download it (this is free) and modify its options and settings appropriately for use in your particular application on your particular system. Ideally, if your configuration gives good results and you've published it, please then contact us about it (see email address below) and we can add your configuration to the list for others to use.

Here are some links to help you select the most appropriate configuration components for your project:

1. Driving data (a.k.a. forcing data)

(WATCH decided to define "driving data" differently from "forcing data", but usually they are synonymous terms). These are meteorological / climate data that can either be obtained from standard open-access datasets (see table below; usually in NetCDF format) or from a met. station (as in e.g. the Loobos example or studies like Marthews et al. 2012) or directly from National Meteorological & Hydrological Services (NMHSs). Basically, JULES requires data on:

        Radiation (downward SW and LW),

        Precipitation (rainfall and snowfall),

        Temperature (approx. 2 m above canopy height),

        Surface pressure,

        Specific humidity and

        Wind speed

(i.e., the variables listed here). These variables must be available for every timestep, although JULES can do some interpolation/disaggregation automatically if the simulation timestep differs from the driving data timestep (e.g. 3 hourly data to half hourly or daily data to hourly). JULES-appropriate sources for driving data include:

(n.b. there are many other data products and alternative sources, e.g. see NCAR/UCAR's Precipitation Data Sets Overview & Comparison table and/or ISIMIP's page here and/or the links here). If you have not been provided with driving data for your project, by far the best initial source is to consult the (uncoupled versions of) standard JULES configurations and see what they use.

2. Ancillary data

Spatial datasets, e.g. soil properties (hydraulic and thermal parameter values), land-cover (frac; vegetation and non-vegetation) and DEM-derived gridded flow-directions and accumulated areas. If these have been provided as time-varying ancillaries then they are called prescribed data by JULES (other ancillary data are constant). For non-point runs, usually all in NetCDF format. JULES runs require these (non-time-varying) ancillary fields and these (time-varying) prescribed data fields, usually at the same resolution as your driving data (see above):

n.b. there are MANY other sources: these are just some starter suggestions. Use Google!

• If you are doing a gridded run using driving data from one of the sources above, contact your source to see whether they can also supply you with ancillary data on the same grid.

• If you have not been provided with ancillary data for your project, by far the best initial source is to consult the standard JULES configurations (e.g. on Rosie Go - see below), see what ancillary data they use and request permission to use it too.

• The UK Met Office ANcillary Tools and Suites (ANTS) system: This system can create ancillary data files on appropriate grids (see here (requires password) and/or the how-to for ANTS on Jasmin by P. McGuire at Univ. Reading). However, n.b. it says here that ANTS is only at the test release stage and "you should not expect a fully functioning set of software and tools", so I would currently NOT advise using it at the moment unless you have expertise in this area.

3. Control files

Currently JULES's control files must be in the form of either (i) a set of Fortran namelist files (model parameter input .nml files) or (ii) a Rose suite (a suite is effectively a bundle of control files, including the same namelists as used for (i) ).

• ROSE SUITES: There are two ways to get hold of Rose suites:

1. Through downloading a standard JULES configuration, or
2. Through the Rose Suite Discovery Engine Rosie Go (part of your Rose installation; see here for how to do this). This is equivalent to searching the online repository, e.g. searching for u-am539 here leads you to this page here.

           *** An important note about the Rosie Go database: pretty much EVERY suite in use or in development across the JULES community is on there. That's fantastic from the point of view that you can find everything that has been committed to the system BUT it's bad because on there are also suites that don't work (e.g. someone tried a few changes and has not yet completed the work), suites that only work with particular branches of JULES (and generally nothing in the .info file will tell you which because it's in the author's personal notes) and many suites that use a coupled model environment using other ESM models that are not JULES (for which the Rose Suite Editor windows will look unfamiliar). BEWARE !!! ***

• NAMELIST FILES: Sets of namelists are not usually distributed around the JULES community any more (except as part of Rose suites), but if you are working from a set of these supplied from elsewhere, then you can either run JULES directly from the namelists or use create_rose_app to convert them into a Rose suite and then use that to run JULES (see here for details of both options).

The namelists JULES requires for (i) are described on the JULES Manuals pages (select your version of JULES and find section "The JULES namelist files") and this is the best source for details of both these kinds of control files (both the Rose suite and the namelist files are composed of the same set of namelists).

One final document about control file settings (for people with a little more experience of using JULES): it's known in the JULES community that certain parameter combinations are inadvisable and there is a useful list of these that you can find here appended to Ticket #592.

Analysis tools for JULES output data

Gridded runs from Land Surface Models (LSMs) in general can output data in 2D or 1D NetCDF files and you usually need to use different software to visualise/analyse these two types of gridded output. However, please be aware that JULES will (almost) always give you 1D output from gridded runs, whether the driving data are 1D or 2D (only in a few specific cases will the output be 2D: details are in the documentation section for model_grid.nml). This means that you either need to use analysis software that can deal with 1D files or you need to anticipate a post-processing step to convert your 1D JULES outputs into 2D files.

• For converting 1D JULES output to 2D, see here.
• For JASMIN users, be aware of the jasmin-sci software environment.
• Finally, see here for evaluation / benchmarking.