CKO - ECBILT/CLIO Installation

Installing ECBILT/CLIO

In this document we describe how you can install the ECBILT/CLIO software on your computer. The installation process, which includes a demonstration run, consists of three steps

unpacking the software,
configuring the model, and
running the model.

Note that you need the Field, NetCDF, and udunits libraries in order to run the model. If this software is not available on your computer, you should install it first. You can obtain the source code distribution of these libraries via the tools page of the CKO website.

Unpacking the Software
To install the ECBILT/CLIO package, you should first create a directory named EMIC and change to this directory. Next, you should unpack the package using the commands

gunzip -c ../emic.tar.gz | tar xvf -

Now, the directory EMIC should have the following contents (dates and times may differ)

bgwd63 252% ll
total 320
-rw-r--r--    1 severijn ksoo          889 May 23 13:44 acconfig.h
-rw-r--r--    1 severijn ksoo        22125 May 23 13:03 aclocal.m4
drwxr-xr-x    5 severijn ksoo         4096 May 31 09:05 clio
drwxr-xr-x    2 severijn ksoo         4096 May 31 09:05 config
-rwxr-xr-x    1 severijn ksoo       186720 May 30 13:39 configure
-rw-r--r--    1 severijn ksoo        33071 May 30 13:39 configure.in
drwxr-xr-x    4 severijn ksoo         4096 May 31 09:05 doc
drwxr-xr-x    5 severijn ksoo         4096 May 31 09:05 ecbilt
drwxr-xr-x    4 severijn ksoo         4096 May 31 09:05 ecbilt_clio
drwxr-xr-x    4 severijn ksoo         4096 May 31 09:05 ecbilt_fixoc
drwxr-xr-x    4 severijn ksoo         4096 May 31 09:05 ecbilt_fom
drwxr-xr-x    4 severijn ksoo         4096 May 31 09:05 ecbilt_swamp
drwxr-xr-x    4 severijn ksoo         4096 May 31 09:05 fixoc
drwxr-xr-x    3 severijn ksoo         4096 May 31 09:05 fixtim
drwxr-xr-x    5 severijn ksoo         4096 May 31 09:05 fom
drwxr-xr-x    4 severijn ksoo         4096 May 31 09:05 lbm
drwxr-xr-x    4 severijn ksoo         4096 May 31 09:05 scenario
-rw-r--r--    1 severijn ksoo           10 May 31 09:01 stamp-h
drwxr-xr-x    4 severijn ksoo         4096 May 31 09:05 swamp
drwxr-xr-x    4 severijn ksoo         4096 May 31 09:05 tim
drwxr-xr-x    6 severijn ksoo         4096 May 31 09:05 wkdir

The file configure is a script that you will use to configure the ECBILT/CLIO model for your computer. Here is a description of the directories.

clio: This directory contains the sources and inputdata of the ocean-seaice model CLIO developed at the univeristy of Louvain La Neuve.
config: This directory contains files that are needed by the configuration program.
doc: This directory contains these installation instructions and documentation on the ECBILT and CLIO models.
ecbilt: This directory contains the sources, inputdata, and the default namelist of T21 quasi-geostrophic atmosphere model ECBILT developed at KNMI.
ecbilt_clio: This directory contains the sources and inputdata for a coupled model consisting of the ECBILT atmosphere model, the CLIO ocean-seaice model and the land model lbm.
ecbilt_fixoc: This directory contains the source code and inputdata for a coupled model consisting of the ECBILT atmosphere model, the fixed ocean model fixoc and the land model lbm.
ecbilt_swamp: This directory contians the source and inputdata for a coupled model consisting of the atmosphere model ECBILT, a mixed layer ocean swamp, the land model lbm and the seaice model tim.
ecbilt_fom: This directory contains the sources and inputdata of a coupled model consisting of the atmosphere model ECBILT, a flat-bottom ocean model fom, the seaice model tim, and the land model lbm.; This directory contains the source and inputdata of an ocean model with prescribed sea surface temperature and sea-ice climatology.
fixtim: This directory contains the source code, inputdata and the default namelist of a thermodynamic sea-ice model with prescribed thickness.
fom: This directory contains the sources, inputdata and the default namelist of a flat-bottom ocean model developed at KNMI.
lbm: This directory contains the sources, inputdata and the default namelist of the land-bucket model developed at KNMI.
scenario: This directory contains historical data and future scenario's of atmospheric composition and land cover (albedo and forest fraction).
swamp: This directory contains the source code, inputdata and the default namelist of a mixed-layer ocean model with prescribed heattransport.
tim: This directory contains the sources, inputdata and the default namelist of a thermodynamic sea-ice model.
wkdir: This directory contains the start data and specific namelist and parameter files for each of the coupled models.

The remaining files are used by the configuration script. Normally, you should not have to do anything with these files and it is best to just leave them where they are. The next step is to configure the software for your computer.

Configuration
You need to configure ECBILT/CLIO for two reasons: first, because of the differences between the computers on which ECBILT/CLIO can run. Second, because you need to adapt the model for your research topic. We describe how you can configure ECBILT/CLIO in these cases in the following sections.

Configuring for Your Computer
Most of the work related to configuring ECBILT/CLIO for you computer is handled by the script configure that you can find in the directory EMIC. This script will figure out where it can find all the tools and libraries that are needed to compile and run the model. The script accepts several command-line options. You can get a list of these options by entering

./configure --help

The last six options are the ones that control the configuration of the ECBILT/CLIO mode. Note that you can specify two or more of these options simultaneously. Also note that the script remembers the previous configuration options, so you only need to specify the options for things that you want to change.

You select the ocean model with the following option

./configure --with-ocean=ocean-model

The supported ocean models are clio, fom, swamp, and fixoc. If this option is not specified. the default ocean model CLIO is used. Note that the ocean model also determines which seaice model is used.

The ECBILT/CLIO model is compiled and run in a separate directory. The default directory is /tmp/$USER. You can change this directory with the following option

./configure --with-scratch=scratch_directory

You can start a demonstration run at the end of the configuration process with

./configure --with-run

On some computers, the configuration script is not able to find the Field, NetCDF and/or udunits library. In this case, you have to specify the location of this library with one or more of the command-line options --with-field, --with-netcdf, and --with-udunits. For example, you can determine the location of the NetCDF library by searching for the file netcdf.h. The path to this file will usually be something like /usr/local/include/netcdf.h. Everything upto (but not including) `include' is the directory you are looking for. Once you know where the NetCDF software is located, you can configure ECBILT for your computer by entering the command

./configure --with-netcdf=location-of-netcdf

in the directory EMIC. For example, if the file netcdf.h is located in the directory /usr/local/include then the configuration script is invoked as follows

./configure --with-netcdf=/usr/local

You can locate the Field and udunits library in a similar manner by searching for the files Contract.inc and udunits.h respectively.

During the configuration process a number of makefiles, scripts, and include files are created. When the configuration process is finished, the contents of the directory EMIC should be similar to this

bgwd63 254% ll
total 364
-rw-r--r--    1 severijn ksoo         1372 May 31 11:24 Makefile
-rw-r--r--    1 severijn ksoo          889 May 23 13:44 acconfig.h
-rw-r--r--    1 severijn ksoo        22125 May 23 13:03 aclocal.m4
drwxr-xr-x    2 severijn ksoo         4096 May 31 11:24 bin
drwxr-xr-x    5 severijn ksoo         4096 May 31 11:24 clio
drwxr-xr-x    2 severijn ksoo         4096 May 31 11:24 config
-rw-r--r--    1 severijn ksoo         3360 May 31 11:24 config.cache
-rw-r--r--    1 severijn ksoo         5680 May 31 11:24 config.log
-rwxr-xr-x    1 severijn ksoo        17363 May 31 11:24 config.status
-rwxr-xr-x    1 severijn ksoo       186720 May 31 11:07 configure
-rw-r--r--    1 severijn ksoo        33071 May 30 13:39 configure.in
drwxr-xr-x    9 severijn ksoo         4096 May 31 11:24 doc
drwxr-xr-x    5 severijn ksoo         4096 May 31 11:24 ecbilt
drwxr-xr-x    4 severijn ksoo         4096 May 31 11:24 ecbilt_clio
drwxr-xr-x    4 severijn ksoo         4096 May 31 11:24 ecbilt_fixoc
drwxr-xr-x    4 severijn ksoo         4096 May 31 11:24 ecbilt_fom
drwxr-xr-x    4 severijn ksoo         4096 May 31 11:24 ecbilt_swamp
drwxr-xr-x    4 severijn ksoo         4096 May 31 11:25 fixoc
drwxr-xr-x    3 severijn ksoo         4096 May 31 11:25 fixtim
drwxr-xr-x    5 severijn ksoo         4096 May 31 11:25 fom
drwxr-xr-x    2 severijn ksoo         4096 May 31 11:25 include
drwxr-xr-x    4 severijn ksoo         4096 May 31 11:25 lbm
drwxr-xr-x    4 severijn ksoo         4096 May 31 11:25 scenario
-rw-r--r--    1 severijn ksoo           10 May 31 11:25 stamp-h
drwxr-xr-x    4 severijn ksoo         4096 May 31 11:25 swamp
drwxr-xr-x    4 severijn ksoo         4096 May 31 11:25 tim
drwxr-xr-x    6 severijn ksoo         4096 May 31 11:25 wkdir

The configuration script creates a makefile and several directories

bin: This directory contains the script run-emic to build and run the coupled model.
include: This directory contains a header file that provides some information about your computer that is used at compile time. You should never have to modify this file.

Configuring the Model Physics and Output
You can define the physics and output data of each component of the coupled model by setting parameters in a number of parameter (for CLIO) and namelist (all other models) files. In order to run the demo you don't have to modify any of these. In this case you can continue with the section Running now.

You can change the run-time parameters of one of the component models ecbilt, fixtim, lbm, swamp, or tim by copying the file default-namelist from the corresponding subdirectory of the EMIC directory to the subdirectory of EMIC/wkdir and editing this copy. So if you want to change the configuration of the landmodel lbm of a ECBILT/CLIO coupled model, you use the following commands in the EMIC directory

cp lbm/default-namelist wkdir/ecbilt_clio_std/namelist-lbm
vi wkdir/ecbilt_clio_std/namelist-lbm

Information (little outdated) on the content of the namelist files is available in the EMIC/doc/ecbilt directory.

You can change the configuration of the CLIO ocean model by editing the *.param files in the directory EMIC/wkdir/ecbilt_clio_std. Be sure to make a backup copy before editing these files. Information about the content of the parameter files is available in files in EMIC/doc/clio.

Running
After the coupled model has been configured you can start the demonstration run by entering the command

make run

in the directory EMIC. This will invoke the script run-emic in the bin directory. You can also invoke this script directly. It takes the following command-line options

Option Default Description

-h Print a description of the command line options

-l run_label std The label identifying the run. This is the last part of the name the subdirectory of EMIC/wkdir.

-s start_year 1710 The year in which the model run starts.

-n number_of_years 1 The length of the model run in (model) years of 360 days.

-r restart_interval 1 The number of years between writing of a restart file.

If you want to run another configuration with the make run command, you can edit the Makefile in the EMIC directory and change the run_label argument to the -l option of the run-emic command. The demonstration runs with run label std take between 7 (fixoc & swamp) and 22 minutes (clio) to complete on a Linux PC with Pentium III processor at 733 MHz. The SGI Challenge ("broeikas") at the KNMI needs between 21 and 42 minutes, while the DEC Alpha ("ruunat") at the IMAU takes between 3 and 7 minutes to complete the runs.

Camiel Severijns

Last modified: Thu May 31 12:44:22 CEDT 2001

Option	Default	Description
`-h`		Print a description of the command line options
`-l` run_label	`std`	The label identifying the run. This is the last part of the name the subdirectory of `EMIC/wkdir`.
`-s` start_year	`1710`	The year in which the model run starts.
`-n` number_of_years	`1`	The length of the model run in (model) years of 360 days.
`-r` restart_interval	`1`	The number of years between writing of a restart file.