LogixNG Reference - Chapter 9

Formula

LogixNG has native support for complex calculations with the tool "Formula". Formula supports almost all the Java operators and you can use local variables and functions with formula. In many cases, like the action Turnout, you can choose to use formula to get the turnout you want to act on, or to get the new state you want to set.

Local variables, which are explained in chapter 8, can be used directly in formula. So if you have a local variable index, you can for example have the formula "IT" + str(index), which adds the string "IT" and the value of index. This can be useful if you for example want to set all the turnouts IT1, IT2, IT3, ..., IT10 to thrown. You can then use the For action to iterate from 1 to 10 and to set each of these turnouts to thrown.

The Formula expressions

There are three expressions for formula: Analog Formula, Digital Formula and String Formula. They all work the same way, except that Analog Formula returns a floating point number, Digital Formula returns a boolean value (true or false), and String Formula returns a string. The expression Formula can have child expressions, for example reading an analog value or reading the state of a sensor. You use the result of the child expressions by using the name of the female socket in the formula. So if you have an expression Formula which has a child E1 to which an expression Sensor is connected, you can use the result of the expression Sensor in the formula by the identifier E1 which points to the female socket and its connected expression.

Operators

Formula supports most of the Java operators. A list of the Java operators, together with the priority of them, is on this page.

Currently supported operators are:

Operator Description Associativity
v++
v--
post-increment
post-decrement
not associative
++v
--v
pre-increment
pre-decrement
right to left
- unary minus right to left
! unary logical NOT right to left
~ unary bitwise NOT right to left
* / % multiply, divide, modulo left to right
+ -
+
additive
string concatenation
left to right
<<
>>
>>>
shift left
shift right
unsigned shift right
left to right
< <=
> >=
relational not associative
==
!=
equality left to right
&& logical AND left to right
|| logical OR left to right
?: ternary right to left
= += -=
*= /= %=
&= |= ^=
<<= >>= >>>=
assignment right to left

Note that for the calculations to work, each operand must have the correct type. For example, if you have a memory IM1 that has a number as a string and you want to subtrack from it, like IM1 - 1, you need to convert the string in IM1 to an integer or a float. Example: int(IM1) - 1 or float(IM1) - 1. The same rules apply to concatenating a string and an integer. The integer has to be converted to a string. "IT" + str(index)

In this example, the A1 section uses the For action to toggle 5 turnouts. The turnout user names are T1 thru T5. The index local variable is used to supply the number. The index value has to converted to a string before concatenating with the "T"

The A2 section is an example of a digital expression. This a simple one with just the "and" operator.

Chapter 9 formula_example

Functions

Formula supports functions, like sin(x) and random(). Some functions takes one or several parameters. A function has an identifier, for example "sin", followed by a left parantheses, optional one or several parameters separated by comma, and then closed by a right parantheses.

The dialog boxes for editing an action or expression, and the dialog box for editing variables, has a button "Formula functions". If you click on that button, you get a new dialog box that shows the functions that are available and the documentation on each of them.

One may notice that there is several modules with one or two functions in each module. For example, the module Math has the functions random() and sin(). The reason for so many modules for so few functions is that the number of functions is expected to grow. For example, the Math module should have cos(), tan(), atan() and sqrt(), but these are not implemented yet.

For JMRI developers: The functions are defined in the package jmri.jmrit.logixng.util.parser.functions and each module has its own Java class. Each function is its own class that implements the Function interface.

Function Lists

Documentation of the functions

To make it easier to use the functions, each function has some documentation.

Each action/expression has a Formula functions button that opens a dialog box with documentation of the functions.

Chapter 9 function button

The functions are grouped in modules to make it easier to find the functions. Select the module you are interested in.

Chapter 9 select module

Then select the function you are interested in.

Chapter 9 select function

In this case, the function fastClock() take a string parameter which can have any of the values hour, min or minOfDay.

Some functions, for example the function random(), can take different numbers of parameters. The default is 0.0 <= x < 1.0. Supplying max or min and max values can change the range.

Chapter 9 random functions

Advanced: Add new function with Jython

It's possible to create a new function using Jython to be used by formula. The code below gives an example that you can use as a template. A new function is added by creating a new class that extends the class Function and implements these methods:

Method Description
getModule The name of the module that the function belongs to
getName The name of the function
calculate Calculate the function
getDescription Description of the function for the user

Example Jython script that defines the function jythonTest that takes one floating point parameter:

import jmri

class MyFunction(jmri.jmrit.logixng.util.parser.Function):
  def getModule(self):
    return "Jython example"

  def getName(self):
    return "jythonTest"

  def calculate(self, parameterList):
    if (parameterList.size() != 1):
      raise jmri.jmrit.logixng.util.parser.WrongNumberOfParametersException("Function requires one parameter")
    return parameterList.get(0).calculate() * 3.4

  def getDescription(self):
    return "Example of function defined in Jython"


jmri.InstanceManager.getDefault(jmri.jmrit.logixng.util.parser.FunctionManager).put("jythonTest", MyFunction())
        

Calculate the function

The function calculate takes a number of arguments as a List<ExpressionNode>. We first check the number of arguments by calling the method size() and if that's correct, we get the arguments by calling the method get(index) where "index" is the index of the argument.

But to do something useful with the arguments, we need to calculate each argument we want to use. We do that by calling the method calculate on each argument we want to use.

We then do the calculation, which in this case multiplies the first argument with 3.4 and then returns the value.

Important!

A function may set turnouts, sensors, and other things on the layout. You may for example create the function setTurnout(turnout, newState). But it's important to remember that a ConditionalNG runs on a separate thread so if you set a turnout or a sensor, you must do that on the layout thread. Formula is always run on the thread that the ConditionalNG is run on, so if a function updates the layout or the GUI, it needs to do it on the layout thread or the GUI thread.

See the later chapter on threads (may not exist yet) for more information of LogixNG threads.


Chapter 10 - Modules

Return to the Reference TOC