4.6.5. pde.tools.expressions module¶

Handling mathematical expressions with sympy

This module provides classes representing expressions that can be provided as human-readable strings and are converted to numpy and numba representations using sympy.

`parse_number`	return a number compiled from an expression
`ScalarExpression`	describes a mathematical expression of a scalar quantity
`TensorExpression`	describes a mathematical expression of a tensorial quantity

class ExpressionBase(expression: basic.Basic, signature: Optional[Sequence[Union[str, List[str]]]] = None, *, user_funcs: Optional[Dict[str, Any]] = None, consts: Optional[Dict[str, Any]] = None)[source]¶

Bases: object

abstract base class for handling expressions

Warning

This implementation uses exec() and should therefore not be used in a context where malicious input could occur.

Parameters

expression (sympy.core.basic.Basic) – A sympy expression or array. This could for instance be an instance of Expr or NDimArray.
signature (list of str, optional) – The signature defines which variables are expected in the expression. This is typically a list of strings identifying the variable names. Individual names can be specified as list, in which case any of these names can be used. The first item in such a list is the definite name and if another name of the list is used, the associated variable is renamed to the definite name. If signature is None, all variables in expressions are allowed.
user_funcs (dict, optional) – A dictionary with user defined functions that can be used in the expression.
consts (dict, optional) – A dictionary with user defined constants that can be used in the expression. The values of these constants should either be numbers or ndarray.

classmethod check_reserved_symbols(symbols: Iterable[str], strict: bool = True) → None[source]¶

throws an error if reserved symbols are found

Parameters

symbols (iterable) – A sequence or set of strings with symbols to check.
strict (bool) – Flag determining whether an exception is raised

property complex: bool¶

whether the expression contains the imaginary unit I

Type: bool

property constant: bool¶

whether the expression is a constant

Type: bool

depends_on(variable: str) → bool[source]¶

determine whether the expression depends on variable

Parameters: variable (str) – the name of the variable to check for
Returns: whether the variable appears in the expression
Return type: bool

property expression: str¶

the expression in string form

Type: str

get_compiled(single_arg: bool = False) → Callable[[...], NumberOrArray][source]¶

return numba function evaluating expression

Parameters: single_arg (bool) – Determines whether the returned function accepts all variables in a single argument as an array or whether all variables need to be supplied separately
Returns: the compiled function
Return type: function

property rank: int¶

the rank of the expression

Type: int

abstract property shape: Tuple[int, ...]¶

class ScalarExpression(expression: Union[float, str, numpy.ndarray, ExpressionBase] = 0, signature: Optional[Sequence[Union[str, List[str]]]] = None, *, user_funcs: Optional[Dict[str, Any]] = None, consts: Optional[Dict[str, Any]] = None, allow_indexed: bool = False)[source]¶

Bases: pde.tools.expressions.ExpressionBase

describes a mathematical expression of a scalar quantity

Warning

This implementation uses exec() and should therefore not be used in a context where malicious input could occur.

Parameters

expression (str or float) – The expression, which is either a number or a string that sympy can parse
signature (list of str) – The signature defines which variables are expected in the expression. This is typically a list of strings identifying the variable names. Individual names can be specified as lists, in which case any of these names can be used. The first item in such a list is the definite name and if another name of the list is used, the associated variable is renamed to the definite name. If signature is None, all variables in expressions are allowed.
user_funcs (dict, optional) – A dictionary with user defined functions that can be used in the expression
consts (dict, optional) – A dictionary with user defined constants that can be used in the expression. The values of these constants should either be numbers or ndarray.
allow_indexed (bool) – Whether to allow indexing of variables. If enabled, array variables are allowed to be indexed using square bracket notation.

copy() → ScalarExpression[source]¶: return a copy of the current expression

derivatives¶: differentiate the expression with respect to all variables

differentiate(var: str) → ScalarExpression[source]¶: return the expression differentiated with respect to var

property is_zero: bool¶

returns whether the expression is zero

Type: bool

shape: Tuple[int, ...] = ()¶

property value: Union[int, float, complex]¶

the value for a constant expression

Type: float

class TensorExpression(expression: Union[float, str, numpy.ndarray, ExpressionBase], signature: Optional[Sequence[Union[str, List[str]]]] = None, *, user_funcs: Optional[Dict[str, Any]] = None)[source]¶

Bases: pde.tools.expressions.ExpressionBase

describes a mathematical expression of a tensorial quantity

Warning

This implementation uses exec() and should therefore not be used in a context where malicious input could occur.

Parameters

expression (str or float) – The expression, which is either a number or a string that sympy can parse
signature (list of str) – The signature defines which variables are expected in the expression. This is typically a list of strings identifying the variable names. Individual names can be specified as list, in which case any of these names can be used. The first item in such a list is the definite name and if another name of the list is used, the associated variable is renamed to the definite name. If signature is None, all variables in expressions are allowed.
user_funcs (dict, optional) – A dictionary with user defined functions that can be used in the expression.

derivatives¶: differentiate the expression with respect to all variables

differentiate(var: str) → TensorExpression[source]¶: return the expression differentiated with respect to var

get_compiled_array(single_arg: bool = True) → Callable[[numpy.ndarray, numpy.ndarray], numpy.ndarray][source]¶

compile the tensor expression such that a numpy array is returned

Parameters: single_arg (bool) – Whether the compiled function expects all arguments as a single array or whether they are supplied individually.

property shape: Tuple[int, ...]¶

the shape of the tensor

Type: tuple

property value¶: the value for a constant expression

parse_number(expression: Union[str, int, float, complex], variables: Optional[Mapping[str, Number]] = None) → Number[source]¶

return a number compiled from an expression

Warning

This implementation uses exec() and should therefore not be used in a context where malicious input could occur.

Parameters

expression (str or Number) – An expression that can be interpreted as a number
variables (dict) – A dictionary of values that replace variables in the expression

Returns

the calculated value

Return type

Number