Understanding the interpreter: scan order and time-dependent operability
Shedding light on a commonly-made coding error

Applies to: Spatial Woodstock, all versions
Date:  3/26/2008

The Woodstock interpreter is a space-delimited, top-down scan order parser. It matches development types with other model components (e.g., yield tables, action operability, transition targets, and so on) by scanning from the top of the section until it finds a matching declaration. The purpose of this tech tip is to make you aware of this scan order and how it affects coding, and to highlight a commonly-made, scan-order coding error.

It is important to be aware of Woodstock’s top-down scan order to ensure that you order development type masks properly. If you are using non-basic development type masks in declarations (i.e., the mask contains one or more question mark characters or aggregate attributes), you must be conscious of the order of the masks within the section to avoid potential mismatches. Moreover, Woodstock is unable to detect a mask mismatch, and so it is up to you to check for them.

One commonly-made ordering error is in action operability declarations that employ time-dependency (i.e., whose operability terms include the _CP keyword within the conditional statement). Consider the action declaration below.

*ACTION aClearcut Y
  *OPERALBLE aClearcut
     ? ? ?  _AGE >= 25 and _CP = 1
     ? ? ?  _AGE >= 20 and _CP >= 2

The first operability declaration states that in the first period the minimum harvest age is 25; in periods two and higher, the minimum harvest age is 20. The problem is that all development types will match on the first declaration because it contains a global mask; the second operability rule is effectively rendered ineffectual. This ‘error’ would have been obvious in the resulting schedule — there would be no clearcuts after the first period, or the model would likely be infeasible.

The proper way to declare the time-dependent operability rules above is as follows:

*ACTION aClearcut Y
  *OPERALBLE aClearcut _CP 1
     ? ? ?  _AGE >= 25
  *OPERALBLE aClearcut _CP 2.._LENGTH
     ? ? ?  _AGE >= 20

This declaration completely avoids the ordering trap.

As you can see, some care is required when making declarations that use non-basic masks. Any ‘mistakes’ such as these are usually apparent in the results.