Additive Equation
Purpose
To calculate a value as a function of several other values by means of an additive equation
Type Name
‘additive_equation’
Definition Syntax
Without a transform of equation result:
[term1] + [term2] + [term3] + etc.
With a transform of equation result:
transform([term1] + [term2] + [term3] + etc.)
where:
- ‘term1’, ‘term2’ are equation terms (see below)
- ‘transform’ is an optional transform (see below)
Note that equation terms must always be separated by a PLUS. To apply a minus, you need to use a negative constant at the start of the term, or else pre-calculate the term and then use it in your equation.
Definition Syntax for single Equation Term
[k1] * transform(k2) ^ k3
where: - ‘k1’ is either a constant (e.g. -1.2) or else the name of a key in the varlue dictionary - ‘transform’ is an optional transform such as ln(), log10(), etc. - ‘k2’ is an optional exponent
For both the definition of the additive equation term as well as the additive equation you can leave spaces before and after the ‘+’, ‘*’ and ‘^’ symbols. This is not mandatory but often makes your equations easier to read and check.
Example 1:
‘3.4 + 0.03 * par_rut ^ 1.2’
This equation extracts the value for key ‘par_rut’ from the value dictionary, then applies the power 1.2 to it. The result is then multiplied by 0.03 and added to 3.4.
Example 2:
‘3.4 + -0.03*par_rut^1.2’
This equation extracts the value for key ‘par_rut’ from the value dictionary, then applies the power 1.2 to it. The result is then multiplied by 0.03 and subtracted from 3.4.
Example 3:
‘f_k1_rut + f_k2_rut * par_rut ^ f_k3_rut’
This equation extracts the value for key ‘par_rut’ from the value dictionary, then applies the power of the value held for key ‘f_k3_rut’ to it. The result is then multiplied by the value held for key ‘f_k2_rut’ and added to the value held for key ‘f_k1_rut’. If the value dictionary holds the values 3.4, 0.03, and 1.2 for keys ‘f_k1_rut’, ‘f_k2_rut’ and ‘f_k3_rut’, respectively, then the value from example 3 will match that for example 1.
Example 4:
‘f_k1_rut + f_k2_rut * log(par_rut) ^ f_k3_rut’
This equation is identical to that for example 3 excapt that this case we apply a ‘log’ (log to the base 10) transform to the value held for key ‘par_rut’ from the value dictionary BEFORE we apply the power, multiplication and addition as shown before.
Example 5:
‘exp(f_k1_rut + f_k2_rut * log(par_rut) ^ f_k3_rut)’
This equation is identical to that for example 4 except that in this case we apply the exp() transform (raise to exponent) to the result.
Transforms
The table below shows the transforms that can be applied to individual terms or to your additive equation result as a whole:
| Transform | Meaning | Comment / Warnings |
|---|---|---|
| log() | Log to the base 10 | Negative/Zero values will throw an error |
| ln() | Natural log | Negative/Zero values will throw an error |
| invert() | Invert | Zero values will cause error |
| exp() | Exponent | Large numbers may cause numeric overflow |
| sqrt() | Square Root | Negative values will throw an error |
| logit() | Logistic Function | Large Numbers may cause overflow |
| percent() | Percent | Value is simply multiplied by 100 |
| 1min() | 1-minus-value | Value is subtracted from 1 |
| min1() | value-minus-1 | 1 is subtracted from Value |
| 1plus() | 1-plus-value | Value is added to 1 |
| floor() | Floor() function | Rounds down to nearest whole number |
| ceiling() | Ceiling() function | Rounds up to nearest whole number |
You will note that the combination of the term and the power (indicated by the’^’ symbol) can replicate some transforms. For example in JFunction syntax ‘k1 + k2 * sqrt(k3)’ is identical to ‘k1 + k2 * k3 ^ 0.5’. It is up to you to select the syntax and approach that will make your additive equations the easiest to understand. Remember the old programming mantra ‘you write it once but read it many times’!
Comments
The basic format for additive equations should be able to accommodate most of the equations you need to use. For more complex equations that you cannot express in the additive form illustrated above, you should pre-calculate the different terms of your complex equation to insert the result against other function keys. You can then use these pre-calculated results as building blocks in a more complex function.