Overview

Allows composition and evaluations of tokenized expressions.

With this module you can compose an expression and do repeated evaluations with the same expression.

How the ucalc Module Works

As a simple example, consider the following expression,

expression = "$(eq)=$(CU)*.12"

In this expression we are setting two tokens, $(EQ) and $(CU). The $(xx) represents a token variable that will be substituted with values. Lets continue with our example and substitute a value for CU,

values = {"cu":10}
variable, value = ucalc.calculate(expression, **values)

At this point variable will be equal to EQ, and value will be equal to 1.2. Notice that token substitution is case insensitive. In fact all calculations will be done in lower-case.

The calculate function is a convenience function for manipulating the StringExpr class. The above example could have been re-written as,

expression = "$(eq)=$(cu)*.12"
values = {"cu":10}
eqn = ucalc.StringExpr(expression)
for item, num in values.items():
   eqn.setvalue(item, num)
variable = eqn.variable()
value = eqn.evaluate()

In this case there is more typing, but it is a bit more efficient when you have the same expression but varying values. For example consider,

expression = "$(eq)=(cu)*.12"
values = [1.2, 31.,2.3, 5.6]
eqn = ucalc.StringExpr(expression)
for value in values:
   eqn.setvalue("cu", value)
   value = eqn.evaluate()

In the above example we can evaluate the number 1.2, 31.0, 2.3, and 5.6 on the same StringExpr object. This is slightly faster than using the convenience calculate() function, which would have to needless reconstruct the expression for each value that is being evaluated.

Default function list

The StringExpr comes with a the following set of default functions and constants,

• acos
• asin
• atan
• atan2
• ceil
• cos
• cosh
• e
• exp
• fabs
• floor
• fmod
• frexp
• hypot
• int
• ldexp
• log
• log10
• max
• min
• modf
• pi
• pow
• sin
• sinh
• sqrt
• tan
• tanhi

Most of the above functions and constants come from the python math library [2]. The remaining functions come from Python's built-in library [1].

Creating Custom Functions

If you wish to add your own custom function to the above list, or override an existing function you can do it via the StringExpr.setfunction() method. For example, say you have derived a much better tan() function that you would like to use instead. Then you can do the following,

def mytan(x):
    return # ... my much better tangent calculation!

eqn = ucalc.StringExpr("$(eq)=tan($(a))")
eqn.setvalue("a", .2)
eqn.setfunction("tan", mytan)
value = eqn.evaluate()

In this way you have complete flexibility when using the StringExpr.

The calculate Function

calculate(expression[,values])

Simplified expression calculation routine.

You can use the dictionary like behavior of values to set your expression values. This can be done in two ways,

values = {"cu":12., "moly":.2}
eqn = ucalc.calculate("$(eq)=.2*$(cu)+12.3*$(moly)", **values)

or,

eqn = ucalc.calculate("$(eq)=.2*$(cu)+12.3*$(moly)",
                      cu=12., moly=.2)

In reality you would utilize the first example most often.

Arguments:

expression : string

Expression you wish to evaluate.

values : variable dictionary

Dictionary keywords for the values you wish to evaluate.

The StringExpr Class

class StringExpr(expression [, funcmap])

Simple string expression and evaluation class.

See How the ucalc Module Works for examples of using this class.

Arguments:

expression : string

Expression you wish to evaluate (must have a left-hand side).

funcmap : dictionary

Name-function pairs that are used during evaluation. This defaults to the DEFAULT_FUNCTION_MAP.

values : variable dictionary

Optionally specify the values to calculate (see ucalc.calculate() for an example).

evaluate()

Substitutes and evaluates the expression.

Returns:

The result of calling eval() [1] with the function map and the name-value pairs substituted.

setfunction(name, function)

Allows extension or overriding of a function.

Argument:

name : string

Name of the function (as it should appear in the expression).

function : function

Python function that is used when the name is encountered in the expression.

setvalue(name, value)

Set the name-value pair for evaluation.

Overrides previous name-value pair (see How the ucalc Module Works for some examples)

Arguments:

name : string

Name of the variable (for example, "CU" for replacing $(cu) in an expression).

value :

The value you want to replace during evaluation.

strrhs()

Returns the right-hand side after variable substitutions.

For example, if your expression is,

"$(EQ)=$(A)*$(B)"

And you substituted A with 5 and B with 10, then this function would return,

"5*10".

variable()

Returns the value of the left-hand side of the expression.

For example, if the expression was,

"$(a) = $(b)**2 + $(c)**2"

This method would return the string: "a".

Returns:

The value on the left-hand side of the expression.

Data

DEFAULT_FUNCTION_MAP

Dictionary of name-function pairs that will be used during expression evaluation.

Exception

exception UcalcError

Error for this module.

References