Formula Definition Files (*.qlf)

Previous  Top  Next

Formula Files allow you to define Expressions and Conversion Functions.

Expressions
Expressions are mathematical expressions that can take any number of parameters and you can select Expressions as display objects on the screen. Expressions can be used to perform a mathematical operation on a data item before displaying it. Expressions can also be accessed from Python script as explained later in this chapter.
A simple example of an expression definition would be:

Linear(m, x, t) := m*x+t

Conversion Functions
Conversion functions are similar to Expressions in that they allow you to use a define a mathematical function. However, they are closely related to a specific data item in that they represent a conversion for this particular item. The following example shows the engineering unit conversion for the data item HK.HTR_5V

EU(Raw="HK.HTR_5V") := (Raw*5.0)/256

A Conversion function can have only one parameter and it needs to define a default value which is the name of a data item (Note that you have to specify the name of the item as opposed to the value). You can then use the formal argument name in the function definition to refer to the data item. As opposed to expressions you can define multiple conversion functions with the same name (the data items these functions are tied to should be different though). Usually this is exactly what you want to do. This way you can define for example a EU engineering unit conversion and can call this function on various data items. In this case the appropriate conversion function (which may differ from data item to data item) will be invoked. This feature is used for the STOL emulator to map to the correct conversion function depending on telemetry point.

Both Conversion functions and Expressions are defined in a .qlf formula file. The formulas need to be loaded either at runtime or from the gseos.ini file. Once the formula is loaded it can be accessed from GSEOS when displaying an Expression or in the item select dialog when selecting a data item.
The loaded formulas are also displayed in the GSEOS Explorer underneath the nodes Conversions and Expressions.

If you change the formula file and load it into GSEOS the formula definitions will be updated accordingly and reflected in the display.

Expressions and Conversion functions are mapped into the Conversion module. The two examples defined above can be accessed from Python in the following way:

Conversion.Linear(2.3, PHA.TOF1, 20)
Conversion.EU("HK.HTR_5V")
This feature now allows you to use the same Expressions that you have used in the past for display purposes only from Python script. It effectively can be used instead of going through the effort and writing a separate decoder. Since Expressions and Conversions functions are limited to one line statements and can not contain flow control directives any complex decoding tasks are still better managed in a separate decoder generating a new output block that then in turn can get displayed.

On the other hand, if the expression needed is very simple instead of writing Decoders to convert data items you can use Expressions to display items modified by a simple function. The latter approach allows you to quickly assemble display screens without going through the overhead of defining a separate block and writing a Decoder.

Formula files must have the extension .qlf and contain one function per line. The syntax of a Conversion Function definition is:

FunctionName(Parameter1, Parameter2, ... ParameterN) := Expression

or
ExpressionName(Param1="Block.ItemName") := Expression

The formal parameter names can be used in the expression. These parameters will be replaced with GSEOS data items when an Expression is displayed on a screen. For Conversion functions you have to provide exactly one parameter that has a default value which is the name of a data item.

The body of the Expression/Conversion function can be any valid Python expression. The expression must not span multiple lines and it can not contain flow control statements. For backward compatibility the old Qlook Formula File format is still supported. However, it is strongly recommended to only use valid Python constructs, i.e. use 0xE43F instead of 0E43Fh for hexadecimal numbers.

In order to use Expressions/Conversion Functions you have to load them. This can either be done with the user interface File/Open function or at startup time in the gseos.ini Config/Load section. Once the functions are loaded they are available to be placed on display screens as Expressions or Conversion Function items. They can also be accessed from Python via the Conversion module. The module Conversion is automatically imported and is updated when new Formula files are loaded. You can load any number of Formula files, the Expressions and Conversion Functions contained in these files will be added to the pool of available Conversion Functions.
You should avoid using the same name for different Expressions since they will overwrite each other. As explained above for Conversion functions you might want to do exactly that and choose the same name for multiple functions (using different data items).
Comments can be inserted anywhere in a Formula file and are started with the '#' character.

If a formula raises an exception during runtime the result of the conversion will be set to 0.0. and the exception will be displayed in the status line when moving the cursor onto the data item.

The following functions are available for use in a formula file:

sin	Sine
cos	Cosine
tan	Tangent
max	The maximum of the two values
min	The minimum of the two values
ftol	Float interpreted as signed long
ltof	Signed long interpreted as float
swap16	Swap bytes in a 16-bit item
swap32	Swap bytes in a 32-bit item
signed8	Interpret 8-bit value as signed
signed16	Interpret 16-bit value as signed
signed32	Interpret 32-bit value as signed
log	Log
exp	Exponent
year	Get the year (the full 4-digit year) from the number of seconds as of Jan-01-1958 00:00:00
month	Get the month (Jan=1, Feb=2, ...)from the number of seconds as of Jan-01-1958 00:00:00
day	Get the day from the number of seconds as of Jan-01-1958 00:00:00
hour	Get the hour from the number of seconds as of Jan-01-1958 00:00:00
minute	Get the minute from the number of seconds as of Jan-01-1958 00:00:00
sec	Get the second from the number of seconds as of Jan-01-1958 00:00:00
pow	Power

Besides the functions mentioned above all the functions from the standard Python math module are available.

The sample file below shows a simple formula file:


#
#  Sample Expressions.
#
Analog       (a,b)                  := ltof(a)*b
Div          (a,b)                  := a/b
Equal        (a, b)                 := a == b
Ever         (a)                    := 1
Lin          (m,x,t)                := m*x+t
Percent      (Total, Used)          := Used / Total * 100

Year         (Time)                 := year(Time+378691200)
Month        (Time)                 := month(Time+378691200)
Day          (Time)                 := day(Time+378691200)
Hour         (Time)                 := hour(Time+378691200)
Minute       (Time)                 := minute(Time+378691200)
Second       (Time)                 := sec(Time+378691200)
Mod          (a,b)                  := a % b
f            (x,y)                  := 2*sin(x) - 2* cos(y)
NadirCycle   (flNadirCycle)         := ltof(flNadirCycle)
CheckInstNPacket(byInstIs, byInstWant, byPacketIs, byPacketWant) := (byInstIs == byInstWant) && (byPacketIs == byPacketWant)
LongToFloat  (l)  := ltof(l)
FloatToLong  (f)  := ftol(f)
TicksToMs    (Ticks) := (Ticks*1000)/515625
Signed8      (s) := signed8(s)
Signed16     (s) := signed16(s)
Signed32     (s) := signed32(s)

#
#  Sample Conversion Functions.
#
EU(Raw='MDS_Status.MIRROR_SETPOINT_TEMP') := -31.98687876 + 1.23958063*Raw + (-.01357386)*pow(Raw, 2) + 8.788e-005*pow(Raw, 3) + (-2e-007)*pow(Raw, 4)

EU(Raw='MDS_Status.GRATING_SETPOINT_TEMP') := -31.98687876 + (-1.7654)*Raw + 0.0065*pow(Raw, 2) + 8.788e-005*pow(Raw, 3) + (-2e-007)*pow(Raw, 4) + 0.0*pow(Raw, 7)

EU(Raw='MDS_Status.MIRROR_A_TEMP') := -31.98687876 + 2.9833*Raw + (-0.00333)*pow(Raw, 2) + 8.788e-005*pow(Raw, 3) + (-2e-007)*pow(Raw, 4)