Modify suite

If you don't know what a JULES Rose suite is, please see these FAQs.

OK: so you've got hold of a JULES Rose suite from a colleague or elsewhere, and you're hoping to you use it on your UNIX system (platform) to replicate your colleague's JULES run as closely as possible. However, you are using a different version of JULES from the one the suite was written for, and you are also on a different platform from your colleague.

Unfortunately, there's no automatic conversion/upgrade command (at least, not yet!), but going through the steps below should see you right. In the following, wherever you see "vnZ.Z" please substitute the version of JULES you are wanting to convert the suite to (usually the latest released version) and wherever you see "vnY.Y" that's the version your suite is at before the upgrade.

If you want to follow this with a specific example Rose suite, try this one, which is a suite for JULESvn5.2 (it's a slightly modified version of the original Loobos example widely used by the JULES community):
          Loobos example filesPackage icon
Download this and put it in ~/roses/ before following the steps below to make it work on your system.


STEP 0: Before you do anything else, please read all the JULES release notes between vnY.Y and vnZ.Z, accessible here. Please don't skip this, for example if you read the vn5.5 release notes you will discover that the deposition routines are not fully functioning in that version of JULES, so if you find a Rose suite on Rosie Go which has the deposition namelists in it, you know that that suite must be for a developmental branch of JULESvn5.5 and you won't waste time trying to use it (as I did!).


STEP 1: First, set up some environment variables to point to the JULES installation you want to convert the suite to ($JULES_ROOT ; note that you will need to have downloaded a copy of this version of JULES, e.g. see here), the location you have saved the Rose suite ($RSUITE, most usually in directory ~/roses/) and the location you want to use for JULES output ($OUTPUT). Here are some example paths (but they may be different for your system):
   export JULES_ROOT=$HOME/MODELS/jules-vnZ.Z
   export RSUITE=$HOME/roses/u-am539 (just for example: your suite will have a different name from "u-am539")
   export OUTPUT=$HOME/output (or wherever you usually put your output)
Immediately check that the output location exists:
   ls $OUTPUT
(create it if it doesn't exist, using mkdir -p $OUTPUT)


STEP 2: If you know your suite is from an older version of JULES, use rose app-upgrade (as described here). These commands can't deal with all the differences between versions (e.g. for versions older than vn3.4), but they can often get you most of the way there, so they are worth trying out.

First, find out what version your suite is at before upgrading (i.e. vnY.Y), which you get by opening it in Rose Editor
   rose edit -C $RSUITE &
and looking at the end of the 'meta' entry in fcm_make (or there are other ways: see Q3 here). If any ‘Error’ pop-ups appeared along with Rose Edit saying “Could not find metadata for ...” (they may be behind another window), then you need also to change BOTH metadata paths in fcm_make and jules to point to $JULES_ROOT (i.e. change the fcm_make metadata to point to [full path of $JULES_ROOT]/rose-meta/jules-fcm-make/vnY.Y and the jules metadata to point to [full path of $JULES_ROOT]/rose-meta/jules-standalone/vnY.Y, respectively - e.g. to convert from vn5.2 to vn5.5 I should have ".../MODELS/jules-vn5.5/rose-meta/jules-fcm-make/vn5.2" in the first of these). Next, do:
   rose app-upgrade -M $JULES_ROOT/rose-meta -C $RSUITE/app/fcm_make --all-versions
(if you need to see what upgrades are possible), then:
   rose app-upgrade -M $JULES_ROOT/rose-meta -C $RSUITE/app/fcm_make vnZ.Z
   rose macro --fix -C $RSUITE/app/fcm_make
   rose app-upgrade -M $JULES_ROOT/rose-meta -C $RSUITE/app/jules vnZ.Z
   rose macro --fix -C $RSUITE/app/jules


STEP 3: Check the metadata (if rose app-upgrade worked, nothing should be required here, but if it didn't work you'll need to correct these errors manually). Open Rose Edit using:
   rose edit -C $RSUITE &
If two ‘Error’ pop-ups appear saying “Could not find metadata for jules-fcm-make/vnZ.Z” and “Could not find metadata for jules-standalone/vnZ.Z” (they may be behind another window) then you'll need to make the following two changes (click OK to get rid of the windows).

  • Click on fcm_make in the Rose Edit window: In "meta", change it to say “[full path of $JULES_ROOT]/rose-meta/jules-fcm-make/vnZ.Z” (unfortunately, you can’t use environment variables like $JULES_ROOT here: it has to be the full absolute path written out, which you can get from echo $JULES_ROOT). When you click “Apply” the ‘env’ below this tab should change into a ‘Build configuration’ tab.
  • Click on the jules tab: In "meta", change it to say “[full path of $JULES_ROOT]/rose-meta/jules-standalone/vnZ.Z”. When you click “Apply” the ‘command’ below this tab should change into an ‘Execution command’ tab.


STEP 4: With Rose Edit still open, make the following changes (n.b. these changes are what I need for the CEH platform: if these changes don't work for you, please contact your System Administrator to find out what you need to have here or, possibly, look inside your $JULES_ROOT/etc/fcm-make/make.cfg or $JULES_ROOT/etc/fcm-make/platform/*.cfg files because the paths you need may already be there from other users):

  • Click on fcm_make → Build configuration. If 'platform options' are available, select the appropriate platform from the drop down box, otherwise:
    • Check “Path to JULES source” is pointing correctly at “[full path of $JULES_ROOT]”
    • IF YOU ARE WORKING AT AN OFFICIAL JULES 'SITE': Check that platform is set correctly for your site using the drop-down menu (e.g. I need to put "ceh") (if your SITE is missing from the drop-down, you need to update line 13 of $RSUITE/app/fcm_make/rose-app.conf directly, e.g. to "JULES_PLATFORM=ceh", even though this will produce red triangle/cog errors). See Step 4 here for more details.
    • IF YOU ARE NOT WORKING AT AN OFFICIAL JULES 'SITE': Check platform is “custom” and then check 'Build with NetCDF' is on "yes", then, if they are missing, right-click on it and add two latent variables for the NetCDF include files and the NetCDF library files (remove "Path to NetCDF installation" by clicking on its cog). For CEH I then need to put /usr/lib64/gfortran/modules for the include files and /usr/lib64 for the library files: you'll need to find out from your System Administrator what the correct paths are for your system.
  • Click on jules → Namelist configuration → Output and check output_dir is “[full path of $OUTPUT]".
  • You may well find that there are several red warning triangles in some of the namelists indicating that something isn't right. Check them all one-by-one and right-click on the red crosses for 'auto-fix' options.
  • Click on File → Check and Save, and close the editor.

From my experience, I've found that Rose Edit is clever enough to help with most things, but major 'framework' changes like having a new namelist it often can't do completely (e.g. changing vn5.1 → vn5.2 required two new namelists and I found the Editor couldn't auto-fix that). For these, you will have to (i) search on Rosie Go for a suite that has already been updated (there will always be one), (ii) check it out, (iii) Compare the rose-app.conf files and work out what it is you're missing, then copy it in (but note my warning in STEP 0 above!).


*** Warning: if you are using a nonstandard platform file (i.e. not registered properly as an option for JULES_PLATFORM) then all should still be fine, but your Build Configuration page will have red warning triangles and red cogs in Rose Edit. Workaround: change line 22 of $JULES_ROOT/etc/fcm-make/make.cfg to "$JULES_PLATFORM{?} = custom" and then in $JULES_ROOT/etc/fcm-make/platform/custom.cfg insert these lines at the top (just above "# Load the remote machine settings") but putting in the correct INC and LIB paths for your system:

$JULES_COMPILER = gfortran
$JULES_MPI = nompi
$JULES_NETCDF = netcdf
$JULES_NETCDF_INC_PATH = /usr/lib64/gfortran/modules

(i.e. what's in $JULES_ROOT/etc/fcm-make/platform/ceh.cfg with the addition of $JULES_NETCDF = netcdf) ***


STEP 5: DRIVING AND ANCILLARY FILES: Apart from very tiny suites, suites do NOT contain the driving and ancillary files they need to run (they just point to them). You can list the files the suite needs like this:
   grep -ir "file='" $RSUITE
   grep -ir "/" $RSUITE/suite.rc
and you will need to check each of these paths individually and, if they refer to files you don't have, you will have to download them separately (by which I mean email your colleague and ask for copies). You can alternatively edit these file paths in Rose Edit (e.g. in jules → Namelist configuration → Driving data → file and jules → Namelist configuration → Ancillary data → ... , however there are usually file paths at quite a lot of the namelists and you end up checking down through each one, which can be time-consuming). In Loobos_orig, for example, I need to make sure the paths to tile_fractions.dat, Loobos_1997.dat and initial_conditions.dat are all [full path of $RSUITE]/file/ which can be done most easily by search-replacing in the $RSUITE/app/jules/rose-app.conf textfile.

*** Useful commands ***: search all files in the Rose suite for a particular path (e.g. "/users/global") and replace it with "/home/users":
   grep -r "/users/global" $RSUITE
   find $RSUITE/* -name "*.conf" -print0 | xargs -0 sed -s -i s#/users/global#/home/users#g
(you can check by repeating the grep command that they have all been correctly replaced).


STEP 6: Open the $RSUITE/suite.rc file. If you're in luck, you won't need to change anything here, but there may be complications. You can try simply replacing the suite.rc with a more basic, platform-independent one (like this one Package icon, but if that doesn't work you need to delve into this more deeply: see the suite.rc links at the end of this page.

All done: this suite should now work on your platform with JULESvnZ.Z.