How to run ADEL simulations

1. initial setup

First, make a new directory somewhere on the geography system, e.g. test. Change directory there, then put this file in that directory. Then untar it ...

machine% wget http://www2.geog.ucl.ac.uk/~plewis/ADEL/adel.tar.Z
machine% tar xvzf adel.tar.Z

If 'tar' doesnt work, try gtar (it means theres an old version of tar).

You should now have angles.raw, machines.ssh.dat, machines.sun4u.dat, makefile, and setup.dat.

2. Edit your configuration

The main control you have over the canopy simulations is via the file setup.dat. You can use this to change the plant density, axis density, thermal time interval etc.

3. Generate the plants

To generate the plants, type:

machine% make wheat

(or make jwheat to use different configuration files). Note that this makes a call to graphtal that is only availavble on the sun4u machines, so you have to run this part on a sun4u (everything else you can run anywhere).

This will create a directory called wheat that is a sort of database for these plants and the simulations. Within this is a directory called wheat/data that is really the root directory for your simulations.

If you get anything wrong at this stage or want to delete everything in the wheat directory and start again, type:

machine% make clean

When you type 'make wheat', the script runs another script called ${ROOTDIR}/growWheat -file ${SETUP}, where ${ROOTDIR} is /home/plewis/ESA/shiva/wheat/csh and ${SETUP} is the file setup.dat. Thus all of the information in setup.dat is passed through to this script.

If you type 'make jwheat', then the flag -jillian is passed through to growWheat. This uses a different density setup (Jilliandensity.par, rather than the default density.par), and a different version of the file physio.h (Jillianphysio.h rather than physio.h).

Running ${ROOTDIR}/growWheat copies some control files to $SIMULATIONS (wheat/data). These are: sol.can, colors.def, density.par or Jilliandensity.par, plante.lsys, field.lsys, field.h, geom.h, and physio.h or Jillianphysio.h.

If these files already exist in $SIMULATIONS (wheat/data) they will not be over-written. Thus, you can modify them after they are copied over for the first time.

You can then use 'make wheat' again to generate the new simulations with your modifications.

The resultant plant files are generated in the directory $outputRoot.$AXISDENSITY.$DENSITY where these terms are defined in setup.dat. The default will be $outputRoot = models, AXISDENSITY = 694, DENSITY = 200, so the files will then be in wheat/data/models.694.200.

There should be a set of files im*.can (e.g. im0.can) that are expressions of the plants in 'can' format. There should also be directories wheat/data/models.694.200/axiom and wheat/data/models.694.200/stats. The 'axiom' directory contains an L-systems description of the plants (that is translated into the can format), e.g. axiom.0.dat. The 'stats' directory should only contain a file thermalTime.dat that gives a translation between the model instance number (0-10 here) and the thermal time for that plant.

There will also be a file wheat/data/angles.dat that is derived from angles.raw. This is used for radiometric simulations later. So if you want a different angle set for the simulations, change the angles.raw file before you run 'make wheat'.

4. Generate the wavefront object files

The next stage is to translate the .can files to .obj files, and generate 'fields' of plants, since this is what all further simulations require.

This is achieved by typing:

machine% make obj

Note that this can be run on any computer (e.g. polybotes).

The translation includes organising the plants into bounding boxes (for efficient ray tracing) so can be a little slow if you run on a slow machine.

Typing 'make obj' runs the script ${ROOTDIR}/objWheat -file ${SETUP}, which in turn calls ${ROOTDIR}/makeObjFromCan -here $HERE/$SIMULATIONS -file $HERE/$file -d $DENSITY -can $output/im$j.can -opRoot $output/im$j for each set of plants at each thermal time instance. The main 'control' here is $DENSITY ... the plant number density, but $FieldSize, $rowDirection, $interRowSpacing also play a role in defining the field. These are all defined in setup.dat.

The resultant plant files will be in wheat/data/models.694.200. There are a number of file types, including: im0.include.obj (defines the soil and the particular plant objects to use); im0.plant_2.obj (defines the detailed geometry for plant 0 ...plant_4 == plant number 1 etc.); im0.obj (the field of plants); im0.leafLAD.dat (the leaf angle distribution); im0.stemLAD.dat (the stem objects LAD).

5. Calculate statistics

The next stage is to calculate some canopy statistics:

machine% make stats

This writes results to wheat/data/models.694.200/stats. This directory contains a number of statistics, including height, leaf angle distribution per time instance, some general plant iinformation etc.

6. Calculate canopy cover

The next stage is to calculate canopy cover:

machine% make cover

This calls ${ROOTDIR}/getCover -file ${SETUP}. It generates a series of gif images and puts the results in the file cover.dat.


7. Make some movies

The next stage is to make some movies:

machine% make movie

This calls quickViewPlant -movie -file ${SETUP}.


Or the individual files:



8. Reporting

The next stage is to make some reporting web pages:

machine% make html

This calls makeHTMLReport -file ${SETUP}. It generates a reporting structure and gives you easy access to processed information on the plants.

The html file is in wheat/data/models.694.200/index.html.

9. BRDF simulations

machine% make brdf

This calls BRDFWheatControl -file ${SETUP}

It is mainly controlled by the angles specified in angles.raw, which are columns of VZA, VAA, SZA, SAA (all in degrees). This gets translated to a file wheat/data/angles.dat where this information is made more explicit. This translation is done in setup.dat (so change angles.raw if you want to do some different angles).

The other relevant information is in setup.dat. This includes: rowDirection (obvious ... degrees), and other information just after '# setup for BRDF simulations' in the file. Increase sizer to use more samples (image linear dimensions in pixels). Increase rpp to get a better quality 'image' (if thats what you want, but 25 is plenty really). Change nrows to see a different number of crop rows (but make sure this is consistent with interRowSpacing and FieldSize).

Lots can go wrong with the radiometric simulations (especially when they are run in parallel over lots of machines). There is a utility to track and kill radiometric simulations:

To run it just on the local machine:

machine% ~plewis/public_html/ADEL/bin/csh/killBRDF

You might want to run it a few times, just to make sure.

The simulations write to, e.g. wheat/data/models.694.200/im0. Within here is a sub-directory set, controlled by the line 'set RT = (0.25 0.50 0.75)' in setup.dat. This gives a range of leaf reflectance to transmittance ratios for the simulations. You may just wish to set this to 0.5 (equal leaf reflectance and transmittance assumed in sampling).

The simulation data then are in directories such as wheat/data/models.694.200/im0leaf_rt0.50. This contains the assumed leaf, soil etc. reflectance data, the wavebands used in the simulations, and a set of files for each angular scenario (defined in angles.raw).

Once you are happy that 'make brdf' is giving the right sort of results ... you can consider parallelisation ...

To do this, edit the files machines.ssh.dat and machines.sun4u.dat to contain the machine names that you want to run on (multiple times if you want ... but don't overload the machines).

To just run on the machines in the machines.ssh.dat file, you can do:

machine% make brdf-parallel-ssh

Similarly for rsh (brdf-parallel-rsh is for machines that won't accept ssh ... but there shouldn't be any of these now'days).

If you have messed up at this point (which is not impossible) and you want to kill the jobs, try:

machine% ~plewis/public_html/ADEL/bin/csh/killBRDF -machines machines.ssh.dat

If thats not working, log on to each machine in machines.ssh.dat and run killBRDF separately.

The radiometric simulation results will be in files such as wheat/data/models.694.200/im10/leaf_rt0.50/brdf.-15.000000.90.000000.0.000000.0.000000.0.direct_contributions.