biogeme.expressions.nary_expressions module

Arithmetic expressions accepted by Biogeme: nary operators

author:: Michel Bierlaire
date:: Sat Sep 9 15:29:36 2023

class biogeme.expressions.nary_expressions.ConditionalSum(list_of_terms)[source]

Bases: Expression

This expression returns the sum of a selected list of expressions. An expression is considered in the sum only if the corresponding key is True (that is, return a non-zero value).

Parameters:: list_of_terms (Iterable[ConditionalTermTuple])

getValue()[source]

Warning

This function is deprecated. Use get_value() instead.

Kept for backward compatibility

Return type:: float

get_signature()[source]

The signature of a string characterizing an expression.

This is designed to be communicated to C++, so that the expression can be reconstructed in this environment.

The list contains the following elements:

the signature of the expression defining the key

the signatures of all the children expressions,

the name of the expression between < >

the id of the expression between { }

the number of elements between ( )

the id of the expression defining the key

for each element: the value of the key and the id of the expression, separated by commas.

Consider the following expression:

\[2 \beta_1 V_1 - \frac{\exp(-\beta_2 V_2) }{ \beta_3 (\beta_2 \geq \beta_1)}.\]

It is defined as:

2 * beta1 * Variable1 - expressions.exp(-beta2*Variable2) /
    (beta3 * (beta2 >= beta1))

And its signature is:

[b'<Numeric>{4780527008},2',
 b'<Beta>{4780277152}"beta1"[0],0,0',
 b'<Times>{4780526952}(2),4780527008,4780277152',
 b'<Variable>{4511837152}"Variable1",5,2',
 b'<Times>{4780527064}(2),4780526952,4511837152',
 b'<Beta>{4780277656}"beta2"[0],1,1',
 b'<UnaryMinus>{4780527120}(1),4780277656',
 b'<Variable>{4511837712}"Variable2",6,3',
 b'<Times>{4780527176}(2),4780527120,4511837712',
 b'<exp>{4780527232}(1),4780527176',
 b'<Beta>{4780277264}"beta3"[1],2,0',
 b'<Beta>{4780277656}"beta2"[0],1,1',
 b'<Beta>{4780277152}"beta1"[0],0,0',
 b'<GreaterOrEqual>{4780527288}(2),4780277656,4780277152',
 b'<Times>{4780527344}(2),4780277264,4780527288',
 b'<Divide>{4780527400}(2),4780527232,4780527344',
 b'<Minus>{4780527456}(2),4780527064,4780527400']

Returns:: list of the signatures of an expression and its children.
Return type:: list(string)

get_value()[source]

Evaluates the value of the expression

Returns:: value of the expression
Return type:: float

class biogeme.expressions.nary_expressions.ConditionalTermTuple(condition, term)[source]

Bases: NamedTuple

Parameters:

condition (Expression | float | int | bool)
term (Expression | float | int | bool)

condition: Expression | float | int | bool: Alias for field number 0

term: Expression | float | int | bool: Alias for field number 1

class biogeme.expressions.nary_expressions.Elem(dict_of_expressions, key_expression)[source]

Bases: Expression

This returns the element of a dictionary. The key is evaluated from an expression and must return an integer, possibly negative.

Parameters:

dict_of_expressions (dict[int, ExpressionOrNumeric])
key_expression (ExpressionOrNumeric)

dict_of_expressions: dict of expressions

getValue()[source]

Warning

This function is deprecated. Use get_value() instead.

Kept for backward compatibility

Return type:: float

get_signature()[source]

The signature of a string characterizing an expression.

This is designed to be communicated to C++, so that the expression can be reconstructed in this environment.

The list contains the following elements:

the signature of the expression defining the key

the signatures of all the children expressions,

the name of the expression between < >

the id of the expression between { }

the number of elements between ( )

the id of the expression defining the key

for each element: the value of the key and the id of the expression, separated by commas.

Consider the following expression:

\[2 \beta_1 V_1 - \frac{\exp(-\beta_2 V_2) }{ \beta_3 (\beta_2 \geq \beta_1)}.\]

It is defined as:

2 * beta1 * Variable1 - expressions.exp(-beta2*Variable2) /
    (beta3 * (beta2 >= beta1))

And its signature is:

[b'<Numeric>{4780527008},2',
 b'<Beta>{4780277152}"beta1"[0],0,0',
 b'<Times>{4780526952}(2),4780527008,4780277152',
 b'<Variable>{4511837152}"Variable1",5,2',
 b'<Times>{4780527064}(2),4780526952,4511837152',
 b'<Beta>{4780277656}"beta2"[0],1,1',
 b'<UnaryMinus>{4780527120}(1),4780277656',
 b'<Variable>{4511837712}"Variable2",6,3',
 b'<Times>{4780527176}(2),4780527120,4511837712',
 b'<exp>{4780527232}(1),4780527176',
 b'<Beta>{4780277264}"beta3"[1],2,0',
 b'<Beta>{4780277656}"beta2"[0],1,1',
 b'<Beta>{4780277152}"beta1"[0],0,0',
 b'<GreaterOrEqual>{4780527288}(2),4780277656,4780277152',
 b'<Times>{4780527344}(2),4780277264,4780527288',
 b'<Divide>{4780527400}(2),4780527232,4780527344',
 b'<Minus>{4780527456}(2),4780527064,4780527400']

Returns:: list of the signatures of an expression and its children.
Return type:: list(string)

get_value()[source]

Evaluates the value of the expression

Returns:: value of the expression
Return type:: float
Raises:: BiogemeError – if the calcuated key is not present in the dictionary.

class biogeme.expressions.nary_expressions.LinearTermTuple(beta, x)[source]

Bases: NamedTuple

Parameters:

beta (Beta)
x (Variable)

beta: Beta: Alias for field number 0

x: Variable: Alias for field number 1

class biogeme.expressions.nary_expressions.bioLinearUtility(list_of_terms)[source]

Bases: Expression

When the utility function is linear, it is expressed as a list of terms, where a parameter multiplies a variable.

Parameters:: list_of_terms (list[LinearTermTuple])

betas: list of parameters

dict_of_elementary_expression(the_type)[source]

Extract a dict with all elementary expressions of a specific type

Parameters:: the_type (TypeOfElementaryExpression) – the type of expression
Returns:: returns a dict with the variables appearing in the expression the keys being their names.
Return type:: dict(string:biogeme.expressions.Expression)

get_signature()[source]

The signature of a string characterizing an expression.

This is designed to be communicated to C++, so that the expression can be reconstructed in this environment.

The list contains the following elements:

the signatures of all the children expressions,

the name of the expression between < >

the id of the expression between { }

the number of terms in the utility ( )

for each term:

the id of the Beta parameter

the unique id of the Beta parameter

the name of the parameter

the id of the variable

the unique id of the variable

the name of the variable

Consider the following expression:

\[2 \beta_1 V_1 - \frac{\exp(-\beta_2 V_2) }{ \beta_3 (\beta_2 \geq \beta_1)}.\]

It is defined as:

2 * beta1 * Variable1 - expressions.exp(-beta2*Variable2) /
    (beta3 * (beta2 >= beta1))

And its signature is:

[b'<Numeric>{4780527008},2',
 b'<Beta>{4780277152}"beta1"[0],0,0',
 b'<Times>{4780526952}(2),4780527008,4780277152',
 b'<Variable>{4511837152}"Variable1",5,2',
 b'<Times>{4780527064}(2),4780526952,4511837152',
 b'<Beta>{4780277656}"beta2"[0],1,1',
 b'<UnaryMinus>{4780527120}(1),4780277656',
 b'<Variable>{4511837712}"Variable2",6,3',
 b'<Times>{4780527176}(2),4780527120,4511837712',
 b'<exp>{4780527232}(1),4780527176',
 b'<Beta>{4780277264}"beta3"[1],2,0',
 b'<Beta>{4780277656}"beta2"[0],1,1',
 b'<Beta>{4780277152}"beta1"[0],0,0',
 b'<GreaterOrEqual>{4780527288}(2),4780277656,4780277152',
 b'<Times>{4780527344}(2),4780277264,4780527288',
 b'<Divide>{4780527400}(2),4780527232,4780527344',
 b'<Minus>{4780527456}(2),4780527064,4780527400']

Returns:: list of the signatures of an expression and its children.
Return type:: list(string)

listOfTerms: List of terms

variables: list of variables

class biogeme.expressions.nary_expressions.bioMultSum(list_of_expressions)[source]

Bases: Expression

This expression returns the sum of several other expressions.

It is a generalization of ‘Plus’ for more than two terms

Parameters:: list_of_expressions (list[ExpressionOrNumeric] | dict[Any:ExpressionOrNumeric])

getValue()[source]

Warning

This function is deprecated. Use get_value() instead.

Kept for backward compatibility

Return type:: float

get_value()[source]

Evaluates the value of the expression

Returns:: value of the expression
Return type:: float