Sum-Product
Overview
This is a powerful function that can simplify long equations into a tabular form that is easier to view and edit. This is best explained by an example. Let’s assume you have an equation that you want to use in your domain model, that gives a value ‘f_increment’ using the following equation:
f_increment = (k1.par_rut) + (k2.par_roughness)
where k1 and k2 are constants and ‘par_rut’ and ‘par_roughness’ are keys that map to parameter values or pre-calculated JFunction values in the value dictionary.
You can obviously use an additive equation to express this function, and for a simple equation like the one shown above, that is a viable option. However, when you have a long equation with say 10 coefficients (k1, k2, k3…, k10), and especially when these coefficients each have several decimal places, it will become difficult to view and edit the JFunction if it is defined as an additive equation.
For such cases, the Sum-Product is a good alternative. What the Sum-Product does in principle is to convert your equation to a tabular format, like this:
| Coefficient | Variable |
|---|---|
| k1 | par_rut |
| k2 | par_roughness |
Now, let us presume that the values for k1 and k2 are 0.134 and 2.347, respectively. And let us assume that at run time for a particular element, the values mapping to ‘par_rut’ and ‘par_roughness’ in the value dictionary are 6.7 and 3.4, respectively (assuming roughness is in IRI units, e.g. mm/m). Then, our tabular representation of the equation will look as follows:
| Coefficient | Variable | Product |
|---|---|---|
| 0.134 | 6.7 | 0.898 |
| 2.347 | 3.4 | 7.980 |
Here we added a ‘Product’ column to represent the product (i.e. multiplication of) the values in the Coefficient and Variable columns. If we now sum the values in the product column, we get the answer of our equation, which is 8.878.
So you should see from this example how the Sum-Product JFunction works. You define a Sum-Product JFunction in your lookups definitions, and then supply the name of the defined lookup set in your JFunction Definition.
The figure below shows a simplified example of a lookup table definition, and the lookup set that pertains to the example calculation is highlighted in yellow.
With the equation terms now defined in a lookup set named ‘equation_1’, we can define our equation as a Sum-Product by simply specifying the name of the lookup set.
In the above example, we are multiplying constant coefficient values with the values mapping to the parameter keys ‘par_rut’ and ‘par_roughness’. It is also possible to mimic Dummy Variables, also known as One-Hot encoding, of categorical variables by replacing a code such as ‘par_rut’ with a Basic Equality JFunction that evaluates to zero or 1.
For example, let’s say we want to expand the above equation to take into account whether the element is in a Rural (code ‘R’) or Urban (code ‘U’) environment. If the element is in a Rural environment, we want to add 0.22 to the result, and if the element is in an Urban environment, we want to add -0.33 to the result. We will now expand our lookup set as follows, assuming the rural or urban code is held in a field named ‘urban_rural’:
With the above addition of two equalities to determine whether the element is in a Rural or Urban situation, our Sum-Product will evaluate as follows when the element is in an Urban (‘U’) situation:
| Coefficient | Variable | Product |
|---|---|---|
| 0.134 | 6.7 | 0.8978 |
| 2.347 | 3.4 | 7.9798 |
| 0.22 | 0 | 0.0000 |
| -0.33 | 1 | -0.3300 |
If we now sum all the values in the product column, we get a final result for the Sum-Product function of 8.5476.
The combination of using value names such as ‘par_rut’ or JFunction equalities such as ‘t : urban_rural = U’ makes the Sum-Product function one of the most powerful tools in your model building arsenal.
Provided your function can be expressed in the above manner, you can easily code equations with 10 or 20 variables with the code being held in a table that is easy to view and edit.
This example should give you a good idea of how you can use this powerful JFunction. Details of how you define a Sum-Product are provided below.
Type Name
‘sum_product’
Definition Syntax
‘lookup_set_name’
where:
- ‘lookup_set_name’ denotes the name of a lookup set in your domain model lookups.
An error will be thrown at run time if the lookup set name you provide to define the Sum-Product is not found in your defined lookup sets. You should also carefully check your lookup set that defines the Sum-Product to make sure that all of the values provided under the ‘setting_key’ column map to items in your value dictionary - that is, either raw input column names or JFunction keys or model parameter codes.
Example
See example provided in the discussion above.