Parameter files

(and how to hack them)

Before reading this, you should know the basics of what a parameter file is, as well as how to read XML. You can look at more information about parameter files in the user parameter file topic, the Model I/O topic, or look at an XML tutorial at http://www.w3schools.com/xml/default.asp.

In this document:

A parameter file is not formatted for easy reading by humans. The text is written in one continuous stream, without tabs, spaces, or new line characters. There's a good reason for this. Formatting characters make it harder to correctly parse the file to get the data out of it.

If you want to look at a parameter file, I recommend a browser such as Internet Explorer. A browser will format the XML for you in a way that makes it easy to read.

To directly edit a parameter file, all you need is some kind of a text editor. If you have an XML or HTML editor that will color-code the text for you, that's helpful for avoiding mistakes. You can put newlines and tabs into the text by hand if it helps you edit it. You can even leave them in when you use the file. If the parser has trouble, you can try taking them out then.

The biggest reason to understand parameter files intimately is for testing. If you write an automated test, you might start by writing code that generates a parameter file and feeds it to the model. You have to know how to write this file correctly.

Additionally, there are a few reasons when you might need to edit parameter files by hand. For instance, perhaps you have put a new behavior into the core model that isn't yet in the GUI. To test it, you would need to add its parameters by hand to a parameter file. There are a few test behaviors that you can't add through the GUI, and must add by hand instead. Also, there are some parameter file formats that make perfectly legitimate runs that the GUI won't allow you to do; for instance, putting seed dispersal behaviors at the beginning of a timestep.

When an XML file is well-formed, it means that the XML syntax is correct: opening elements and closing elements are correctly paired, attributes have quotation marks in the right place, etc. An XML file MUST be well-formed to be used.

Once you've edited your parameter file, you have to make sure it's well-formed. There are online well-formedness checkers, or you can open it in a browser. If you can see the whole file all the way to the bottom, it's well-formed. If it's not well-formed, the browser will stop displaying text at some point and display an error.

On a large scale, the order that the elements go in is important to the GUI (less so to the core model). The order of individual elements don't matter but the large scale groupings should be the same. Follow the order set in a file created by the GUI.

You may look at a parameter file and need some help knowing what an XML tag represents. The help file for a behavior should help you begin to puzzle it out. Looking at the actual Java code should resolve all doubt.

There are two formats that almost all parameters follow. The first is the single piece of data, like this:

< li_julianDayGrowthStarts> 120< /li_julianDayGrowthStarts>

This particular parameter is the first day of the growing season, for light behaviors.

The second format is for species-specific parameters, like this:

< tr_canopyRadiusExponent>
< tr_creVal species="ACRU"> 1.0< /tr_creVal>
< tr_creVal species="ACSA"> 1.0< /tr_creVal>
< tr_creVal species="BEAL"> 1.0< /tr_creVal>
< /tr_canopyRadiusExponent>

This parameter is an equation exponent for tree allometry for each species.

Parameter names sometimes change as behaviors change. Often, an XML tag will be left with the old name so old files will still work.

Here is a sample parameter file that we will look at piece by piece. (This file doesn't make a very good simulation; I edited it to make it shorter.)

The root tag of the parameter file contains a file code which identifies it as a parameter file for a certain version of SORTIE-ND. For an explanation of the different elements of the file code, see the Model I/O topic.

Plot parameters are required and are always present. They must always come first. There are optional additional parameters in plot depending on the needs of the behaviors.

The tree parameters are always present. They must always come before the behavior list. In addition to the parameters shown above, the < tree> tag may also contain a tree map. If you want to remove a tree map from a parameter file, it is sometimes easier to do it by hand if the map is large.

The behavior list specifies the behaviors for this simulation in the order in which they will be called each timestep. Each behavior gets a version number and the trees to which it is applied.

You can change around the order of behaviors, but be sure you know what you are doing. In the list above, switching the first two behaviors would cause a fatal error. You can always switch behaviors of the same type, such as growth behaviors or mortality behaviors (but this is something you can do easily in the GUI as well). The list positions must match later parameter groupings.

In the C++ code documentation, each behavior class should tell you in the class documentation what string you use to call it from the parameter file. It should also tell you its version number (if it doesn't, it's probably version 1.0).

Not all behaviors are applied to trees. If they are, they may interpret the list in different ways. Again, class documentation should tell you if the behavior will do something unusual with the list of trees to which it is applied.

Tree allometry parameters are required and always present. They always come after the behavior list.

The parameters for one behavior are grouped together. There may be multiple copies of a single behavior. They can be distinguished by the number at the end of the behavior name tag, which matches their list position.

Only the parameters actually required by the behaviors in the behavior list must be present. If a behavior has optional parameters, the GUI usually writes them out even if they aren't needed.

The parameter groups usually go in the same order as the behaviors themselves in the behavior list, but they don't have to. If you changed the parameter groups around the file would still work fine.