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 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 that works 100% in all cases (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.
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 idx code 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 the fcm_make and jules apps (e.g. using:
geany $RSUITE/app/fcm_make/rose-app.conf $RSUITE/app/jules/rose-app.conf &
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 JRPATH/rose-meta/jules-fcm-make/vnY.Y and the jules metadata to point to JRPATH/rose-meta/jules-standalone/vnY.Y, respectively, where for JRPATH put the full path of $JULES_ROOT (i.e. no "~" shorthands). For example, e.g. to convert from vn5.2 to vn5.5 (i.e. Y.Y is 5.2 and Z.Z is 5.5) you will need JRPATH/rose-meta/jules-fcm-make/vn5.2 in the first of these).
Next, do the commands described here:
rose app-upgrade -C $RSUITE/app/fcm_make --all-versions
rose app-upgrade -C $RSUITE/app/jules --all-versions
...to see what upgrades are possible (n.b. the -M option on rose app-upgrade doesn't do anything: it looks at the first lines of the respective rose-app.conf files to get the meta path, i.e. you need those JRPATHs to be right before you can use rose app-upgrade), and then:
rose app-upgrade -C $RSUITE/app/fcm_make vnZ.Z
rose app-upgrade -C $RSUITE/app/jules vnZ.Z
rose macro --fix -C $RSUITE/app/fcm_make
rose macro --fix -C $RSUITE/app/jules
STEP 3: Check the metadata (if STEP 2 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). A very good tip at this point is to fish out one of the rose-app.conf files used for Rose Stem testing (e.g. $JULES_ROOT/rose-stem/app/eraint_rfm_2ddata/rose-app.conf). Carefully compare this line by line with what you have (e.g. using xxdiff) and you should be able to see what is incorrect.
If those Rose Stem testing suites are insufficient for this, 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 PLEASE 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_REMOTE = local
$JULES_COMPILER = gfortran
$JULES_MPI = nompi
$JULES_NETCDF = netcdf
$JULES_NETCDF_INC_PATH = /usr/lib64/gfortran/modules
$JULES_NETCDF_LIB_PATH = /usr/lib64
(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), 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.