Piecewise-Linear Function

Purpose

To represent a function of another variable. For example, if you want to calculate a variable y = f(x), then f() can be a Piecewise-Linear function.

The Piecewise-Linear JFunction is one of the most powerful tools in the JFunction arsenal. It allows you to quickly define a complex relationship between two variables simply by specifying several coordinate pairs that define the knot-points in the function. JCass will then do linear interpolation for X-values lying between any knot points, while for values coinciding with knot points, the corresponding Y-value is simply returned.

The figure below shows an example of a Piecewise-Linear function in which the variable ‘par_danger’ is a function of variable ‘par_x’. The table on the left of the figure shows the coordinate pairs used to define the function:

Type Name

‘piecewise_linear_function’

Definition Syntax

‘[param_code]: [x1,y1|x2,y2|x3,y3|etc] : [can_extrapolate] : [constants_only]’

where:

‘param_code’: denotes the key mapping to the value in the value dictionary that represents the independent variable. That is, the key pointing to the X-variable in your function.
‘x1,y1|x2,y2|x3,y3|etc’ : represent the (X,Y) pairs that define the knot-points in your function. Note that X and Y values in each pair are separated by a comma, while each (X,Y) pair is separated by a pipe symbol. You can leave spaces between the pairs and pipe symbols if you wish. JCass will trim any white space when parsing the data pair definitions.
‘can_extrapolate’: is a ‘true’ or ‘false’ value indicating whether the function should extrapolate if the X-values entered into the function are lower or higher than the minimum or maximum X-values in the definition pairs, respectively.
‘constants_only’: is an optional ‘true’ or ‘false’ value indicating whether the X-Y pairs have constant numeric values only (as opposed to keys mapping to values in the value dictionary). Default is ‘false’.

Extrapolation, if done, will use linear extrapolation using the slope between the nearest data pairs (that is, either the lowest or highest two data pairs).

Note

If you are only using literal constant numbers in your X-Y pair definition, it is recommended that you specify the value for the optional parameter ‘constants_only’ as ‘true’. This allows JCass to construct the Piecewise Linear Model only once instead of having to construct it at each evaluation call to the function, resulting in slightly better performance (it all adds up!).

Example 1

‘param_rut: 0,0|5,10|10,20|15,50|20,100 : false’

This example provides a normalisation function to normalise the parameter mapping to key ‘par_rut’ in the value dictionary to a scale of 0 to 100. For ‘par_rut’ values below 5, the normalisation score is very low, ranging from 0 to 10. As the values in ‘par_rut’ increase beyond 10, the normalised scale quickly increases from 20 to 50 before it finally increases from 50 to 100 for values in ‘par_rut’ ranging from 15 to 20. Since we have specified that ‘can_extrapolate’ is false, no extrapolation will be done, which means that values in ‘par_rut’ that are greater than 20 will all be assigned a value of 100.

In this example, we left out the optional parameter ‘constants_only’ which means JCass will assign the default value of ‘false’ to ‘constants_only’. Thus, JCass will assume the X-Y pairs can contain either numbers or the names of keys in the value dictionary which need to be extracted for each element at each evaluation call.

Example 2

‘param_rut: 0,0|5,10|10,20|15,50|f_kx5,f_ky5 : false: false’

This example is essentially the same as Example 1 above. However, here the values for the final X-Y pair are not constants but map to the values associated to keys ‘f_kx5’ and ‘f_ky5’ in the value dictionary. With this formulation, you can, for example, pre-set the values for keys ‘f_kx5’ and ‘f_ky5’ by using a Lookup JFunction which extracts the values from your model lookup set. In this way, users can modify features of your model without having to delve into the lower level coding of this JFunction.

In this example, we explicitly specified the optional parameter ‘constants_only’ as ‘false’ so that JCass knows it should rebuilt the X-Y pairs at each evaluation call using the names of keys in the value dictionary. Any values in the X-Y pair that are numeric will automatically be cast to a double precision number while any non-numeric values will be assumed to map to a key in the value dictionary.

Important

Be careful when you specify that extrapolation should be done (flag ‘can_extrapolate’ = true). Depending on how you define your function, you may end up with very large numbers when you extrapolate, and this may cause numeric-overflow errors when you in turn apply transforms such as exponents or powers to those values.