[[TOC]]

There are three different types of output files:

• annual outputs, one value per pixel or CFT/PFT specific (61 files)
• monthly outputs (54 files)
• daily outputs (43 files)

You find information in

• source:trunk/include/conf.h listing the variables
• source:trunk/par/outputvars.par giving the variables, units and description

file name	data type[size]	content	data unit[scaled]	dimension	comment
general
grid.bin	short [2 bytes]	coordinates	deg*100	2(lon,lat)*grid cells
vegc.bin	float [4 bytes]	vegetation carbon pool	gC/m²	c(grid cells, nyears)
litc.bin	float [4 bytes]	litter carbon pool	gC/m²	c(grid cells, nyears)
soilc.bin	float [4 bytes]	soil carbon pool	gC/m²	c(grid cells, nyears)
firec.bin	float [4 bytes]	carbon released by fire	gC/m²	c(grid cells, nyears)
mprec.bin	float [4 bytes]	monthly precipitation	mm	c(grid cells, 12, nyears)	valid for all output files starting with “m”
mnpp.bin	float [4 bytes]	monthly net primary production	gC/m²	c(grid cells, 12, nyears)
mrh.bin	float [4 bytes]	monthly respiration	gC/m²	c(grid cells, 12, nyears)
natural vegetation
fpc.bin	float [4 bytes]	foliage projected cover of natural vegetation in grid cell	%	c(ncell, ncft*2+9	1.band in (npft+1): total fraction of natural vegetation, 2. to last band: pfts follow in the order they occur in pft.par
firef.bin (?)	float [4 bytes]	fire return interval	1/fraction of grid cell burned this year
agricultural vegetation
sdates.bin	short [2 bytes]	sowing date	dayofyear [1:365]	c(grid cells, 24, nyears)	12 crops irrigated/rainfed
hdates.bin	short [2 bytes]	harvest date	dayofyear [1:365]	c(grid cells, 24, nyears)	12 crops irrigated/rainfed
growing_period.bin	float [4 bytes]	length of growing period	length of growing period in days	c(grid cells, 28, nyears)	(12 ncfts + grass) *2
pft_harvest.pft.bin	float [4 bytes]	crop yield	gC/m²	c(ncell, [[Crops	ncft]]*2 , nyears)
pft_rharvest.pft.bin	float [4 bytes]	crop residue yield	gC/m²	c(ncell, ncft*2, nyears)	cfts: rainfed/irrigated
pft_npp.bin	float [4 bytes]		gC/m²	c(ncell, ncft*2+9, nyears)	cfts: rainfed/irrigated

all output files in plain binary (BSQ)

Some PFT/CFT-specific outputs (see list below for examples) are available as output per grid cell (grid-based) or per pft (pft-based). The grid-based output is internally multiplied with the stand fraction in a grid cell and will be generated if WITH_GRIDBASED is defined in lpjml.conf. If this line is not enabled (the default setting) the output will be pft_based. To convert back, multiply with stand_frac and cellarea.

• pft_harvest
• pft_npp
• cft_nir
• cft_airrig
• cft_consump_water_g

a) if lpj has been run in distributed mode, use output_bsq.ksh to join the output parts to one file
all following steps will be the same
b) creating a rectangular binary image from the output
use the program grd2bsq (call it with [-h] to get help)
don’t forget to use the output grid, not input grid … ;-)
c) see next point on how to read binary data

- quite simple with any programming language, once you know how the data is stored (as described under point 8b, but see below for byte order issues)

- most image processing programs have an option to import binary data (but they usually need it in a rectangular grid, see point 9 b)

- R can read binary data. We now offer the lpjmlkit R package to help with reading both LPJmL input and output files. If you want to use lpjmlkit consider changing the output format from RAW to CLM in lpjml.conf/lpjml.js so that the necessary metadata about number of cells, number of bands etc. are included in files.

- ArcView / ArcGIS: they DO read binary input data, but the online help system will not tell you … You need to specify a header with data type, coordinates etc, there should be information on the web about the specifications for the version you are using. It seems to cause problems to read negative values, though.
- if you have problems importing binary data to the software you are using for analysis, you might need to write a program that converts the output data to ASCII (or use the respective function of a different software package)

If you get strange errors (such as really unsensible values for your output data) when reading binary data, one reason might be that the data has been written on a different system architecture than the one you are using for reading it, and that those systems - just bad luck - store data internally in a different byte order. You might use the functions in src/tools/swap.c to change the byte order if you are programming in C, and there are many examples in other languages on the web. Those functions should work fine for all integer data types (i.e. short/int/long in C/C), and you don’t need to think about char data, as it is one byte only. Things get more complicated if you look at floating point data types: additionally to byte order issues the internal representation of the number might be different. You are on the safe side if you avoid reading binary floating point data from a different architecture. However, most systems seem to follow the IEEE floating point standard, so you might be lucky using the integer byte swapping functions.

In order to add new outputs, you’ll have to take care of several things. There are in principle 4 different output types available.

• annual outputs per pixel
• annual outputs per PFT/CFT
• monthly outputs per pixel
• daily outputs per pixel for 1 single CFT

There are currently 158 different outputs defined in LPJmL, see include/conf.h. Additional output — even if not written away during the run, will increase the memory requirements of the model. Please consider this, when adding new outputs. You can search the code for existing outputs (e.g. ‘MIRRIG’ AND ‘mirrig’) and use this as a guideline. Unless you plan to implement a new type of output, you can copy/paste existing structures and functions.

• Create a unique identifier in include/conf.h
  (!) Daily outputs need to be IN BETWEEN D_LAI and D_PET. Keep order as in include/output.h

• Increment NOUT in include/conf.h by the number of new outputs created

• Define units, scale, description of new output in outputvars.par

• Add new elements to the structure Output in include/output.h
  (!) Monthly outputs need to be added to the structure Output and also to the structure Outputmonth.
  (!) Daily outputs have to be added to the structure Daily_outputs only, they need to be IN BETWEEN D_LAI and D_PET
  (!) Daily outputs should be in the order of daily output identifiers in include/conf.h

• Add output variable (including: id, name, variable(NetCDF), description, unit, scale) to list of files in par/outputvars.par
  (!) Daily outputs should be in the same order as in include/conf.h and include/output.h.

• For PFT/CFT-specific outputs: allocate memory to element in src/lpj/initoutput.c

• For PFT/CFT-specific outputs: free memory of element in src/lpj/freeoutput.c

• Initialize new output elements in corresponding init function (e.g. initoutput_monthly.c)

• MONTHLY outputs only: Add output identifier to function that checks type of output (i.e. src/lpj/ismonthlyoutput.c)

• MONTHLY outputs only: Add new output structure element(s) to function that allocates memory: src/lpj/newoutputmonthly.c

• Add output identifier to src/lpj/outputbuffersize.c (mind the correct position!)

• Write away output in corresponding fwriteoutput_* function (e.g. fwriteoutput_monthly.c & fwriteoutput_monthly2.c)
  (!) There are 2 functions for monthly and daily outputs, both are needed (one for with river routing, the other for without)

• Fill output structure with values wanted at the appropriate place in the code. Pay attention to the difference between + and += and that the output works for all options (e.g. with and without river routing) and land use types.

• MONTHLY outputs only: add new output to src/lpj/update_outputmonthly.c and free output memory after it is written to file at end of year in src/lpj/freeoutputmonthly.c

• Finally, call new output variable in lpjml.conf in order to write it to file