FlxFunction

FlxFunction#

Theoretically, a FlxFunction is simply a data type. However, it can be considered the most important (and most complex) data type in Fesslix. A FlxFunction defines a mathematical function that can be stored as a function and evaluated multiple times. The result of an evaluation of a FlxFunction is a scalar value.

The syntax of expressions of type FlxFunction is outlined in this section.

TODO get rid?#

class FlxFunction#

Theoretically, a FlxFunction is simply a data type. However, it can be considered the most important (and most complex) data type in Fesslix. A FlxFunction defines a mathematical function that can be stored as a function and evaluated multiple times. The result of an evaluation of a FlxFunction is a scalar value.

The syntax of expressions of type FlxFunction is outlined in this section.

flxPara: type = str | float | "FlxFunction"

---------------------------------------------------------------------------
TypeError                                 Traceback (most recent call last)
Cell In[1], line 1
----> 1 flxPara: type = str | float | "FlxFunction"

TypeError: unsupported operand type(s) for |: 'typing.Union' and 'str'

import fesslix as flx
flx.load_engine()

Random Number Generator: MT19937 - initialized with rand()=199349714;
Random Number Generator: MT19937 - initialized with 1000 initial calls.

Working with a FlxFunction in Python#

Functions that do not expect parameters#

In Python, you can specify a FlxFunction when the type flxPara is required:

class flxPara#

A parameter that can pass a callable expression (that returns a floating-point number; i.e., scalar value).

The following types are accepted:

str: The content of the string is parsed as a callable expression of type FlxFunction.
callable: A Python-callable that does not require any parameters is expected and returns a float.
float: A simple float value is assigned as value for the parameter.

Example:

## ==============================================
## use <float> as type for FlxPara
## ==============================================
print( flx.eval_fun( 42. ) )

## ==============================================
## use <callable> as type for FlxPara
## ==============================================

## -----------------------------------------
## Function without arguments
## -----------------------------------------
def help_fun():
    return 42.
print( flx.eval_fun( help_fun ) )

## -----------------------------------------
## lambda function without arguments
## -----------------------------------------
print( flx.eval_fun( lambda: 42. ) )

## ==============================================
## use <FlxFunction> as type for FlxPara
## ==============================================
print( flx.eval_fun("sqrt(pi+e/gamma)") )

0
0
0
801944471776144

To simply check/evaluate a FlxFunction, you can use the Python function flx.eval_fun().

flx.eval_fun()#

Syntax:: flx.eval_fun(expr)
Description:: Evaluates the expression expr and returns the result.

Parameters:: expr (flxPara) – The expression to evaluate.
Return type:: float

Example:

print( flx.eval_fun( "cos(pi)" ) )

## -----------------------------------------
## Handling errors
## -----------------------------------------
## in case of errors, 'nan' is returned.
def help_fun_raise():
    raise NameError(f'ERROR 202504041234')
    return 42.
print( flx.eval_fun( help_fun_raise ) )

Functions that accept an array as input parameter#

If the type flxParaFun is required, a FlxFunction can be specified as well:

class flxParaFun#

A parameter that can pass a callable expression that accepts an array (of pre-specified size N) as input (and that returns a floating-point number; i.e., scalar value).

The value of N that is expected for a specific instance of flxParaFun is mentioned in the documentation of the associated object/parameter.

The following types are accepted:

str: The content of the string is parsed as a callable expression of type FlxFunction.

A total number of N parameters is passed and can be used in the FlxFunction. To retrieve the value of a passed parameter inside the expression of FlxFunction, you can use the syntax $PARA_NUMB, where PARA_NUMB is a positive integer that denotes the number of the parameter to retrieve (counting of parameters starts with one).
callable: A Python-callable that accepts a single parameter (a numpy-array of pre-specified size).
float: A simple float value is assigned as value for the parameter.

For a demonstrating example, please see filter.

Syntax of a FlxFunction#

Numbers#

The most primitive element of a FlxFunction is a Number.

type Number#

Syntax:

VALUE

Description:

The type Number can be used exactly like the type Double, with the following two additions:

Angles can be specified. The default unit of an angle in Fesslix is radian. If you want to specify an angle in degrees, you have to put a ’°’ behind the value (the angle is internally transformed to radian).
Values can be specified in percent.

Examples:

180°: evaluates to 3.14159…
100%: evaluates to 1.0

type Double#

Syntax:

VALUE

Description:

Represents a floating point value. The decimal separator for floating-point numbers in Fesslix is the dot (.).

Examples:

In the following, a few examples of admissible floating-point numbers are given:

1 5.1 -7.2 4.124e-8

Operators#

The available operators in Fesslix are listed in the following table. The operators are ordered according to their precedence (in decreasing order): For example, 1 + 32 · 2 is equal to 1 + ((32) · 2).

Name of operator	Symbol	Example
logical NOT	`!`	!1 (= 0); !0 (= 1)
exponentiation	`^`	2^4 (= 16); 16^0.5 (= 4)
multiplication; division	`*` `/`	2*4 (= 8); 16/0.5 (= 32)
addition; substraction	`+` `-`	2+4 (= 6); 16-5 (= 11)
less than; greater than;	`<` `>` `<=` `>=`	2<2 (= 0); 4<=2 (= 0);
less than or equal to;		2<=4 (= 1); 2<=2 (= 1)
greater than or equal to
equal to; not equal to	`==` `!=`	2==4 (= 0); 2==2 (= 1);
		2!=2 (= 0); 2!=4 (= 1)
logical AND	`&&`	1&&1 (= 1); 1&&0 (= 0);
logical OR	`\|\|`	1\|\|0 (= 1)
ternary operator	`condt?true:false`	1?2:3 (= 2); 0?2:3 (= 3)

Note

The logical AND and OR operators evaluate the term on the right-hand-side only if the result is not already determined by the term on the left-hand-side.

Variables#

Fesslix has two types of variables: const-variables and var-variables. A const-variable stores a scalar value, whereas a var-variable stores a FlxFunction. Calculations with const-variables are faster than calculations with var-variables, because each time a var-variable is used, a FlxFunction has to be evaluated.

A variable has to be defined (using either the method flx.set_const() or the method flx.set_var()) before it can be used. In the variable name, lowercase and uppercase letters are not distinguished. Variable names are unique: a name that was used to declare a const-variable cannot be used to declare a var-variable, and vice versa. Moreover, names of functions in a FlxFunction are not allowed as names of variables.

const-variables#

A const-variable stores a scalar value. It is defined through the method flx.set_const() and can be used within a FlxFunction by its name.

Note

The value of a const-variable can change during the execution of Fesslix. Therefore, it is not constant. The const-keyword refers to the fact that the variable stores a scalar value and not a function.

flx.set_const()#

Syntax:: flx.set_const( const_name, value )
Description:: Assigns number value to a const-variable with name const_name.

Parameters:

const_name (Word) – The name of the const-variable.
value (float) – The value to assign.

Return type:

None

Example:

flx.set_const( 'my_const', 7.57 )
print( flx.eval_fun( "my_const*2" ) )

15.14

type Word#

The first character of a Word has to be one of the characters listed below:

A - Z

a - z

-

For all other characters, additionally, the following characters are permitted, too:

0 - 9

No spaces are allowed.

var-variables#

A var-variable stores an arithmetic expression. It is defined by means of the object flx.set_const() and can be used within a FlxFunction by its name.

Note

Every time a var-variable is used, the FlxFunction that is stored in the variable is evaluated. Therefore, a var-variable should be regarded as a function, despite the name “variable”.

flx.set_var()#

Syntax:: flx.set_var( var_name, FUN )
Description:: Assigns expression FUN to a var-variable with name var_name.

Parameters:

var_name (Word) – The name of the var-variable.
value (flxPara) – The expression to assign.

Return type:

None

Example:

my_py_var = 7.57
def my_py_fun():
    return 2*my_py_var
flx.set_var( 'my_var', my_py_fun )
my_py_var = 3.33
print( flx.eval_fun( "my_var" ) )

6.66

special variables#

A special variable is a const-variable that is used as an internal variable in some methods of Fesslix. Some special variables used in Fesslix are:

gx: used by sets of random variables defined with flx.rv_set_proc()
gx2: used by sets of random variables defined with flx.rv_set_proc()
deltax: used by sets of random variables defined with flx.rv_set_proc()

Predefined constants#

A predefined constant is a const-variable that is defined at the startup of Fesslix. In spite of the name predefined constants, a predefined constant is technically nothing else than a const-variable. Therefore, the value of a predefined constant can be changed (by the user) during execution. However, it is strongly recommended not to change the value of a predefined constant.

Predefined constants in Fesslix are:

Name of constant	Value
`pi`	3.14159…
`e`	2.71828…
`gamma`	0.5772…
`true`	1.0
`false`	0.0

Functions#

Todo

Write this section.

Data-types based on flxPara#

type flxParaPr#

Syntax:: flxPara
Description:: Expects a value of type flxPara that evaluates to a floating-point number on the interval [0.0, 1.0]; i.e., the evaluated expression is interpreted as a probability.

type flxParaPos0#

Syntax:: flxPara
Description:: Expects a value of type flxPara that evaluates to a positive floating-point number or zero.

type flxParaPosNo0#

Syntax:: flxPara
Description:: Expects a value of type flxPara that evaluates to a positive floating-point number (zero is not allowed).

FlxFunction

Contents

FlxFunction#

TODO get rid?#

Working with a FlxFunction in Python#

Functions that do not expect parameters#

Functions that accept an array as input parameter#

Syntax of a FlxFunction#

Numbers#

Operators#

Variables#

const-variables#

var-variables#

special variables#

Predefined constants#

Functions#

Data-types based on flxPara#