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:

Editing parameter files
Why edit parameter files?
Validating parameter files
Figuring out parameters
Sample parameter file
Parameter file tag
Plot parameters
Tree parameters
Behavior list
Behavior parameters

Editing parameter files

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.

Why edit parameter files?

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.

Validating parameter files

XML files can be well-formed and valid. These are two different things. Well-formed 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.

An XML file is valid if it has been validated against its data definition (in our case, our DTDs). This means that all expected data is present, in the right format, and in the right order. SORTIE-ND does not actually validate parameter files against the DTDs, and you don't need to either. However, the DTDs still serve as the place where we define how parameters are written. Both the GUI and the core model use and expect this standard when parsing the XML files. If the file you've edited doesn't conform to the DTDs, it is likely to be rejected. The only place where you really have latitude to ignore the DTDs is in the order of elements.

Figuring out parameters

You may look at a parameter file and need some help knowing what an XML tag represents. Start by looking at the DTD for that section of the parameter file. It should have comments for each tag. For a parameter, the comment should allow you to identify the parameter in the user documentation and get what it's for and what units its in.

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. The comments in the DTD should reflect this fact.

Sample parameter file

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.)

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<paramFile fileCode="06010101">
<plot>
<timesteps>400</timesteps>
<randomSeed>0</randomSeed>
<yearsPerTimestep>5.0</yearsPerTimestep>
<plot_lenX>500.0</plot_lenX>
<plot_lenY>500.0</plot_lenY>
<plot_latitude>41.92</plot_latitude>
<plot_title>Default parameter file-use for testing only</plot_title>
</plot>
<trees>
<tr_speciesList>
<tr_species speciesName="ACRU" />
<tr_species speciesName="ACSA" />
<tr_species speciesName="BEAL" />
</tr_speciesList>
<tr_seedDiam10Cm>0.2</tr_seedDiam10Cm>
<tr_canopyHeight>
<tr_chVal species="ACRU">30.0</tr_chVal>
<tr_chVal species="ACSA">30.0</tr_chVal>
<tr_chVal species="BEAL">30.0</tr_chVal>
</tr_canopyHeight>
<tr_canopyRadiusToDBH>
<tr_crtdVal species="ACRU">0.108</tr_crtdVal>
<tr_crtdVal species="ACSA">0.107</tr_crtdVal>
<tr_crtdVal species="BEAL">0.109</tr_crtdVal>
</tr_canopyRadiusToDBH>
<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>
<tr_conversionDiam10ToDBH>
<tr_cdtdVal species="ACRU">0.75</tr_cdtdVal>
<tr_cdtdVal species="ACSA">0.75</tr_cdtdVal>
<tr_cdtdVal species="BEAL">0.75</tr_cdtdVal>
</tr_conversionDiam10ToDBH>
<tr_fractOfHeightInCanopy>
<tr_fohicVal species="ACRU">0.49</tr_fohicVal>
<tr_fohicVal species="ACSA">0.58</tr_fohicVal>
<tr_fohicVal species="BEAL">0.54</tr_fohicVal>
</tr_fractOfHeightInCanopy>
<tr_canopyDepthExponent>
<tr_cdeVal species="ACRU">1.0</tr_cdeVal>
<tr_cdeVal species="ACSA">1.0</tr_cdeVal>
<tr_cdeVal species="BEAL">1.0</tr_cdeVal>
</tr_canopyDepthExponent>
<tr_slopeOfHeight-Diam10>
<tr_sohdVal species="ACRU">0.03</tr_sohdVal>
<tr_sohdVal species="ACSA">0.03</tr_sohdVal>
<tr_sohdVal species="BEAL">0.03</tr_sohdVal>
</tr_slopeOfHeight-Diam10>
<tr_minAdultDBH>
<tr_madVal species="ACRU">10.0</tr_madVal>
<tr_madVal species="ACSA">10.0</tr_madVal>
<tr_madVal species="BEAL">10.0</tr_madVal>
</tr_minAdultDBH>
<tr_slopeOfAsymHeight>
<tr_soahVal species="ACRU">0.063</tr_soahVal>
<tr_soahVal species="ACSA">0.062333334</tr_soahVal>
<tr_soahVal species="BEAL">0.063</tr_soahVal>
</tr_slopeOfAsymHeight>
</trees>
<behaviorList>
<behavior>
<behaviorName>glilight</behaviorName>
<version>1.0</version>
<applyTo species="ACRU" type="Seedling" />
<applyTo species="ACSA" type="Seedling" />
<applyTo species="BEAL" type="Seedling" />
<applyTo species="ACRU" type="Sapling" />
<applyTo species="ACSA" type="Sapling" />
<applyTo species="BEAL" type="Sapling" />
<applyTo species="ACRU" type="Adult" />
<applyTo species="ACSA" type="Adult" />
<applyTo species="BEAL" type="Adult" />
</behavior>
<behavior>
<behaviorName>relunlimgrowth</behaviorName>
<version>1.0</version>
<applyTo species="ACRU" type="Seedling" />
<applyTo species="ACSA" type="Seedling" />
<applyTo species="BEAL" type="Seedling" />
<applyTo species="ACRU" type="Sapling" />
<applyTo species="ACSA" type="Sapling" />
<applyTo species="BEAL" type="Sapling" />
<applyTo species="ACRU" type="Adult" />
<applyTo species="ACSA" type="Adult" />
<applyTo species="BEAL" type="Adult" />
</behavior>
<behavior>
<behaviorName>adultstochasticmort</behaviorName>
<version>1.0</version>
<applyTo species="ACRU" type="Seedling" />
<applyTo species="ACSA" type="Seedling" />
<applyTo species="BEAL" type="Seedling" />
<applyTo species="ACRU" type="Sapling" />
<applyTo species="ACSA" type="Sapling" />
<applyTo species="BEAL" type="Sapling" />
<applyTo species="ACRU" type="Adult" />
<applyTo species="ACSA" type="Adult" />
<applyTo species="BEAL" type="Adult" />
</behavior>
<behavior>
<behaviorName>removedead</behaviorName>
<version>2.0</version>
<applyTo species="ACRU" type="Adult" />
<applyTo species="ACRU" type="Sapling" />
<applyTo species="ACRU" type="Seedling" />
<applyTo species="ACSA" type="Adult" />
<applyTo species="ACSA" type="Sapling" />
<applyTo species="ACSA" type="Seedling" />
<applyTo species="BEAL" type="Adult" />
<applyTo species="BEAL" type="Sapling" />
<applyTo species="BEAL" type="Seedling" />
</behavior>
</behaviorList>
<gliLight>
<li_heightOfFishEyePhoto>0</li_heightOfFishEyePhoto>
<li_beamFractGlobalRad>0.5</li_beamFractGlobalRad>
<li_clearSkyTransCoeff>0.65</li_clearSkyTransCoeff>
<li_julianDayGrowthStarts>120</li_julianDayGrowthStarts>
<li_julianDayGrowthEnds>270</li_julianDayGrowthEnds>
<li_minSunAngle>0.779</li_minSunAngle>
<li_numAltGrids>12</li_numAltGrids>
<li_numAziGrids>18</li_numAziGrids>
<li_lightExtinctionCoefficient>
<li_lecVal species="ACRU">0.399</li_lecVal>
<li_lecVal species="ACSA">0.399</li_lecVal>
<li_lecVal species="BEAL">0.399</li_lecVal>
</li_lightExtinctionCoefficient>
</gliLight>
<growth>
<gr_asympDiameterGrowth>
<gr_adgVal species="ACRU">0.167</gr_adgVal>
<gr_adgVal species="ACSA">0.125</gr_adgVal>
<gr_adgVal species="BEAL">0.169</gr_adgVal>
</gr_asympDiameterGrowth>
<gr_slopeGrowthResponse>
<gr_sgrVal species="ACRU">0.027</gr_sgrVal>
<gr_sgrVal species="ACSA">0.159</gr_sgrVal>
<gr_sgrVal species="BEAL">0.137</gr_sgrVal>
</gr_slopeGrowthResponse>
</growth>
<mortality>
<mo_nonSizeDepMort>
<mo_nsdmVal species="ACRU">0.01</mo_nsdmVal>
<mo_nsdmVal species="ACSA">0.01</mo_nsdmVal>
<mo_nsdmVal species="BEAL">0.01</mo_nsdmVal>
</mo_nonSizeDepMort>
</mortality>
</paramFile>

Parameter file tag

<paramFile fileCode="06010101">

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

<plot>
<timesteps>400</timesteps>
<randomSeed>0</randomSeed>
<yearsPerTimestep>5.0</yearsPerTimestep>
<plot_lenX>500.0</plot_lenX>
<plot_lenY>500.0</plot_lenY>
<plot_latitude>41.92</plot_latitude>
<plot_title>Default parameter file-use for testing only</plot_title>
</plot>

These parameters are all required and are always present. They are defined in "Plot.dtd". They must always come first.

Tree parameters

<trees>
<tr_speciesList>
<tr_species speciesName="ACRU" />
<tr_species speciesName="ACSA" />
<tr_species speciesName="BEAL" />
</tr_speciesList>
<tr_seedDiam10Cm>0.2</tr_seedDiam10Cm>
<tr_canopyHeight>
<tr_chVal species="ACRU">30.0</tr_chVal>
<tr_chVal species="ACSA">30.0</tr_chVal>
<tr_chVal species="BEAL">30.0</tr_chVal>
</tr_canopyHeight>
<tr_canopyRadiusToDBH>
<tr_crtdVal species="ACRU">0.108</tr_crtdVal>
<tr_crtdVal species="ACSA">0.107</tr_crtdVal>
<tr_crtdVal species="BEAL">0.109</tr_crtdVal>
</tr_canopyRadiusToDBH>
<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>
<tr_conversionDiam10ToDBH>
<tr_cdtdVal species="ACRU">0.75</tr_cdtdVal>
<tr_cdtdVal species="ACSA">0.75</tr_cdtdVal>
<tr_cdtdVal species="BEAL">0.75</tr_cdtdVal>
</tr_conversionDiam10ToDBH>
<tr_fractOfHeightInCanopy>
<tr_fohicVal species="ACRU">0.49</tr_fohicVal>
<tr_fohicVal species="ACSA">0.58</tr_fohicVal>
<tr_fohicVal species="BEAL">0.54</tr_fohicVal>
</tr_fractOfHeightInCanopy>
<tr_canopyDepthExponent>
<tr_cdeVal species="ACRU">1.0</tr_cdeVal>
<tr_cdeVal species="ACSA">1.0</tr_cdeVal>
<tr_cdeVal species="BEAL">1.0</tr_cdeVal>
</tr_canopyDepthExponent>
<tr_slopeOfHeight-Diam10>
<tr_sohdVal species="ACRU">0.03</tr_sohdVal>
<tr_sohdVal species="ACSA">0.03</tr_sohdVal>
<tr_sohdVal species="BEAL">0.03</tr_sohdVal>
</tr_slopeOfHeight-Diam10>
<tr_minAdultDBH>
<tr_madVal species="ACRU">10.0</tr_madVal>
<tr_madVal species="ACSA">10.0</tr_madVal>
<tr_madVal species="BEAL">10.0</tr_madVal>
</tr_minAdultDBH>
<tr_slopeOfAsymHeight>
<tr_soahVal species="ACRU">0.063</tr_soahVal>
<tr_soahVal species="ACSA">0.062333334</tr_soahVal>
<tr_soahVal species="BEAL">0.063</tr_soahVal>
</tr_slopeOfAsymHeight>
</trees>

The tree parameters are always present. They are defined in "Trees.dtd". 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.

Behavior list

<behaviorList>
<behavior>
<behaviorName>glilight</behaviorName>
<version>1.0</version>
<applyTo species="ACRU" type="Seedling" />
<applyTo species="ACSA" type="Seedling" />
<applyTo species="BEAL" type="Seedling" />
<applyTo species="ACRU" type="Sapling" />
<applyTo species="ACSA" type="Sapling" />
<applyTo species="BEAL" type="Sapling" />
<applyTo species="ACRU" type="Adult" />
<applyTo species="ACSA" type="Adult" />
<applyTo species="BEAL" type="Adult" />
</behavior>
<behavior>
<behaviorName>relunlimgrowth</behaviorName>
<version>1.0</version>
<applyTo species="ACRU" type="Seedling" />
<applyTo species="ACSA" type="Seedling" />
<applyTo species="BEAL" type="Seedling" />
<applyTo species="ACRU" type="Sapling" />
<applyTo species="ACSA" type="Sapling" />
<applyTo species="BEAL" type="Sapling" />
<applyTo species="ACRU" type="Adult" />
<applyTo species="ACSA" type="Adult" />
<applyTo species="BEAL" type="Adult" />
</behavior>
<behavior>
<behaviorName>adultstochasticmorty</behaviorName>
<version>1.0</version>
<applyTo species="ACRU" type="Seedling" />
<applyTo species="ACSA" type="Seedling" />
<applyTo species="BEAL" type="Seedling" />
<applyTo species="ACRU" type="Sapling" />
<applyTo species="ACSA" type="Sapling" />
<applyTo species="BEAL" type="Sapling" />
<applyTo species="ACRU" type="Adult" />
<applyTo species="ACSA" type="Adult" />
<applyTo species="BEAL" type="Adult" />
</behavior>
<behavior>
<behaviorName>removedead</behaviorName>
<version>2.0</version>
<applyTo species="ACRU" type="Adult" />
<applyTo species="ACRU" type="Sapling" />
<applyTo species="ACRU" type="Seedling" />
<applyTo species="ACSA" type="Adult" />
<applyTo species="ACSA" type="Sapling" />
<applyTo species="ACSA" type="Seedling" />
<applyTo species="BEAL" type="Adult" />
<applyTo species="BEAL" type="Sapling" />
<applyTo species="BEAL" type="Seedling" />
</behavior>
</behaviorList>

The behavior list specifies the behaviors for this simulation in the order in which they will be called each timestep. The tags are defined in "ParamFile.dtd". 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).

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.

Behavior parameters

<gliLight>
<li_heightOfFishEyePhoto>0</li_heightOfFishEyePhoto>
<li_beamFractGlobalRad>0.5</li_beamFractGlobalRad>
<li_clearSkyTransCoeff>0.65</li_clearSkyTransCoeff>
<li_julianDayGrowthStarts>120</li_julianDayGrowthStarts>
<li_julianDayGrowthEnds>270</li_julianDayGrowthEnds>
<li_minSunAngle>0.779</li_minSunAngle>
<li_numAltGrids>12</li_numAltGrids>
<li_numAziGrids>18</li_numAziGrids>
<li_lightExtinctionCoefficient>
<li_lecVal species="ACRU">0.399</li_lecVal>
<li_lecVal species="ACSA">0.399</li_lecVal>
<li_lecVal species="BEAL">0.399</li_lecVal>
</li_lightExtinctionCoefficient>
</gliLight>
<growth>
<gr_asympDiameterGrowth>
<gr_adgVal species="ACRU">0.167</gr_adgVal>
<gr_adgVal species="ACSA">0.125</gr_adgVal>
<gr_adgVal species="BEAL">0.169</gr_adgVal>
</gr_asympDiameterGrowth>
<gr_slopeGrowthResponse>
<gr_sgrVal species="ACRU">0.027</gr_sgrVal>
<gr_sgrVal species="ACSA">0.159</gr_sgrVal>
<gr_sgrVal species="BEAL">0.137</gr_sgrVal>
</gr_slopeGrowthResponse>
</growth>
<mortality>
<mo_nonSizeDepMort>
<mo_nsdmVal species="ACRU">0.01</mo_nsdmVal>
<mo_nsdmVal species="ACSA">0.01</mo_nsdmVal>
<mo_nsdmVal species="BEAL">0.01</mo_nsdmVal>
</mo_nonSizeDepMort>
</mortality>
</paramFile>

In general, all the parameters for one type of behavior are grouped together. For instance, the tag <mortality> encloses all parameters for all mortality behaviors. This is because one parameter may apply to multiple behaviors of the same type, and this way the parameter does not have to be repeated.

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 because it's easier than doing all the necessary checks in the GUI code.

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.


16-Feb-2005 10:08 AM