NOTES ON USING IAN'S NETCDF LPJ DRIVER -------------------------------------- written by Ian Ross and extended by Rita Wania BULDING THE DRIVER The driver is a single C++ file, lpjio.cpp, along with a makefile to compile and link this with the main LPJ module. When building the driver, you need to make sure that the parameters passed to the outannual routine from lpjmain.f match the definitions of those functions in lpjio.cpp. See below in CHANGING THE VARIABLE LIST for more about this. CONFIGURATION FILE All of the configuration information for LPJ goes in a single configuration file called lpj.cfg, each line of which is of the form : . There's an example configuration file at the bottom of this document. The keys are taken from this table: +-------------------+-----------------------------------------------------+ | IN_DATA_DIR | Input data directory: you can just make this | | | . to refer to the current directory (that's the | | | default if you don't set it). | +-------------------+-----------------------------------------------------+ | TEMP | Monthly temperature input: the first one is the | | TEMP_VAR | filename and the second the netCDF variable name | | | (which defaults to tas if you don't set it). | +-------------------+-----------------------------------------------------+ | PREC | Monthly precipitation input: the first one is the | | PREC_VAR | filename and the second the netCDF variable name | | | (which defaults to pr if you don't set it). | +-------------------+-----------------------------------------------------+ | WETDAYS | Monthly wet days count input: the first one is the | | WETDAYS_VAR | filename and the second the netCDF variable name | | | (which defaults to wetdays if you don't set it). ** | +-------------------+-----------------------------------------------------+ | SUN | Monthly sunshine input: the first one is the | | SUN_VAR | filename, the second the netCDF variable name | | SUN_IS_CLOUD | (which defaults to clt if you don't set it), and | | | the last one is a true/false flag saying that the | | | "sun" is actually cloudiness (default TRUE). | +-------------------+-----------------------------------------------------+ | MET_DATA_TYPE | Type of met data input: Either "MONTHLY" which are | | | usual monthly data, "PAR", which uses monthly data | | | but replaces the sun shine data by PAR data or | | | "DAILY" for daily input data. | +-------------------+-----------------------------------------------------+ | MASK | Land/sea mask input: the first one is the filename, | | MASK_VAR | the second is the netCDF mask variable (defaults | | MASK_TYPE | to mask if you don't set it), and the last one is | | | the mask type (BOOLEAN or PERCENT_LAND, with the | | | default being BOOLEAN). | +-------------------+-----------------------------------------------------+ | SOIL_TYPE | Soil type input: the first one can either be a | | SOIL_TYPE_VAR | filename or a fixed numerical value (which is used | | | as the LPJ soilcode for all points); if the first | | | one is a filename, then the second is used to | | | specify the soil type variable (which defaults to | | | soiltype if you don't set it). If you don't set | | | any of these, the default is a fixed soilcode of 2. | +-------------------+-----------------------------------------------------+ | SPINUP_YEARS | Run length control: the first one gives the number | | RUN_YEARS | of years of spin-up to do, and the second gives | | | the number of transient years to do (which is used | | | as the averaging period for output data | | | collection). If RUN_YEARS is unset or set to zero, | | | a single pass is made through the input climate | | | data. (SPINUP_YEARS defaults to 1000.) | +-------------------+-----------------------------------------------------+ | SPINUP_DATA_YEARS | Controls the use of the input data during spin-up. | | | If unset or set to zero, all of the available | | | climate data is use repeatedly during the spin-up. | | | If set to some non-zero value, just that number of | | | years of climate data from the beginning of the | | | dataset are used repeatedly for spin-up. | +-------------------+-----------------------------------------------------+ | SPINUP_OUT_FREQ | Output frequency control. The first one controls | | RUN_OUT_FREQ | the output of data during spin-up: if set to zero, | | | there is no output during spin-up. The second | | | controls output during the main part of the run. | | | If this is unset or set to zero, only one output | | | file is written, averaged over the whole of the | | | main part of the run. If it's a non-zero value, | | | output files are averaged and written every | | | RUN_OUT_FREQ years during the main part of the run. | +-------------------+-----------------------------------------------------+ | RUN_OUT_YEARS_ON | If TRUE, then annual output is written to files. | | RUN_OUT_YEARS | The number given to RUN_OUT_YEARS tells lpj how | | | many years should be put out, starting from the | | | last year, counting backwards. E.g. if RUN_YEARS is | | | 102 and RUN_OUT_YEARS is 10, then the years 93-102 | | | will be written to files. | +-------------------+-----------------------------------------------------+ | CO2_CONC | Ambient CO2 concentration in ppmv. This can either | | | be a single value or the name of the file from which| | | to read annual CO2 data. The CO2 file must contain | | | the same number of years as the climate data. | +-------------------+-----------------------------------------------------+ | OUTPUT_FILE | The leading part of the output filename. Output | | | files are named -.nc. | +-------------------+-----------------------------------------------------+ | OUTPUT_VAR | Output variable definitions. There should be one | | | of these for each required output variable. Each | | | line can either be a simple variable name on its | | | own, or a variable name followed by a list of | | | collection types in square brackets. The available | | | variable collection types are MEAN, SDEV, MIN and | | | MAX. For instance, collecting mean and standard | | | deviation FPC values is done with an entry like | | | "fpc_grid [MEAN,SDEV]". If no OUTPUT_VAR entries | | | are provided, a small default set of variables is | | | collected. | +-------------------+-----------------------------------------------------+ ** Comment: Even when using the time-series data for temperature, precipitation and cloud cover, still use the climatology data for wetdays. The lpj driver is set up, so that it uses only the 102-year averages of wetdays. Some tests have shown that it doesn't make a big difference when using the climatology instead of time-series wetdays data. INPUT DATA The driver needs four climate inputs (temperature, precipitation, wet day counts and sunshine) and two static inputs (a land/sea mask and, if you're using one, a soil type map). All of these files are netCDF files, and they all have some common features: - They're all on common latitude/longitude grids with the dimensions and coordinate variables called "lat" and "lon". (The driver will quit with an error message if they're not on common grids.) - The record dimension in the climate inputs is called "time". You should provide a monthly time-series with a whole number of years for temperature, precipitation and sunshine and a seasonal cycle (i.e. 12 months) for the wet day counts. - The climate input variables are all defined as "float var(time, lat, lon)". - The land mask variable is defined as "int var(lat, lon)" (for BOOLEAN masks) or "float var(lat, lon)" (for PERCENT_LAND masks). - The soil type variable is defined as "int var(lat, lon)". You can put the climate input all into one file, or have separate files for temperature, precipitation and sunshine as you wish. We used the CRU mean climatology (CL 1.0) and the time-series (TS 2.1) data on 0.5 and 1.0 degree grids. We do not have permission to redistribute those data sets, but they can be downloaded from the CRU website (http://www.cru.uea.ac.uk/cru/data/hrg.htm). However, we provide an example data set over a few grid cells in Scandinavia. OUTPUT DATA The output files are in netCDF format, with all the output variables defined on the same latitude/longitude grid that the input variables were. The latitude and longitude dimensions and coordinate variables are the same as in the input files. Extra dimensions and coordinate variables are defined as needed for PFT number (pft), month of year (month), day of year (day) and trace gas index (trace). Variables are defined as follows: +--------------------------+-----------------------------------+ | Annual single values | float var(lat, lon) | +--------------------------+-----------------------------------+ | Monthly single values | float var(month, lat, lon) | +--------------------------+-----------------------------------+ | Daily single values | float var(day, lat, lon) | +--------------------------+-----------------------------------+ | Per-PFT values | float var(pft, lat, lon) | +--------------------------+-----------------------------------+ | Monthly per-PFT values | float var(month, pft, lat, lon) | +--------------------------+-----------------------------------+ | Daily per-PFT values | float var(day, pft, lat, lon) | +--------------------------+-----------------------------------+ | Trace gas values | float var(trace, lat, lon) | +--------------------------+-----------------------------------+ | Monthly trace gas values | float var(month, trace, lat, lon) | +--------------------------+-----------------------------------+ | Daily per-layer values | float var(day, layer, lat, lon) | +--------------------------+-----------------------------------+ Variable names are either the base LPJ variable name (for mean values) or the base LPJ name with _SDEV, _MIN or _MAX appended as appropriate. CHANGING THE VARIABLE LIST If you look in lpjio.cpp, you'll see that the variables passed from the main LPJ program to the driver are listed in three places: - In the LPJ_VARIABLES array (starting at or around line 260): this is where the names and types (simple annual, simple monthly, simple daily, per-PFT annual, per-PFT monthly, per-PFT daily, per-layer daily, trace gas annual, trace gas monthly) of variables are defined. - In the header of the outannual function (at or around line 1152), which receives the values from the main LPJ program. - Within the outannual function (at or around line 1211), there are lots of calls to a function called handle_output_record, one per variable. This is where data is collected for averaging before output. The lists in all of these places should be consistent! The only place where ordering is important is in the header of the outannual function. Everywhere else, you can put things in any order. So, with that in mind, here's the procedure for adding a new variable to the set of variables that the driver can output: 1. Change the call to outannual in lpjmain.f to pass the new variable to the driver. 2. Change the header for the outannual function in lpjio.cpp to match the call in the main program. Make sure you call the variables in the same order as in lpjmain.f. 3. Add an entry to the LPJ_VARIABLES array for your new variable, selecting the appropriate type (make sure you get it right - the driver will almost certainly crash or do weird things if it's wrong). 4. Add a new call to handle_output_record in the appropriate place in the outannual function. That's it! Once you've done this and rebuilt LPJ, you'll be able to specify your new variable in the lpj.cfg file and have it output as and when you want it. EXAMPLE CONFIGURATION FILE Here's an example configuration file that does a 1100 year run (1000 years of spin-up, followed by 100 years of data collection). The output is constrained to the last 15 years of the 100 years of data collection though via the RUN_OUT_YEARS line. ---------------------------------------------------------------------- IN_DATA_DIR: . TEMP: tas.nc PREC: pr.nc SUN: wetdays.nc SUN: clt.nc SUN_IS_CLOUD: TRUE MET_DATA_TYPE: MONTHLY MASK: lpj_land_mask.nc MASK_VAR: mask MASK_TYPE: BOOLEAN SOIL_TYPE: lpj_soil_type.nc SOIL_TYPE_VAR: soiltype SPINUP_YEARS: 1000 RUN_YEARS: 100 RUN_OUT_YEARS: 15 RUN_OUT_YEARS_ON: TRUE CO2_CONC: 280 OUTPUT_FILE: out_280 OUTPUT_VAR: fpc_grid [MEAN,SDEV] OUTPUT_VAR: nind [MEAN,SDEV] OUTPUT_VAR: lm_ind [MEAN,SDEV] OUTPUT_VAR: sm_ind [MEAN,SDEV] OUTPUT_VAR: hm_ind [MEAN,SDEV] OUTPUT_VAR: rm_ind [MEAN,SDEV] OUTPUT_VAR: anpp [MEAN,SDEV] OUTPUT_VAR: litter_ag [MEAN,SDEV] OUTPUT_VAR: litter_bg [MEAN,SDEV] OUTPUT_VAR: afire_frac [MEAN,SDEV] OUTPUT_VAR: acflux_fire [MEAN,SDEV] OUTPUT_VAR: gdd [MEAN,SDEV] OUTPUT_VAR: height [MEAN,SDEV] OUTPUT_VAR: mw1 [MEAN,SDEV] ----------------------------------------------------------------------