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
evaluate	evaluate an expression involving fields

class ExpressionBase(expression, signature=None, *, user_funcs=None, consts=None, repl=None)

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 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.

• repl (dict, optional) – Replacements that are applied to symbols before turning the expression into a python equivalent.

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)

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=False)

return numba function evaluating expression

Parameters:

single_arg (bool) – Determines whether the function takes 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, ...]

the shape of the tensor

Type:

tuple

class ScalarExpression(expression=0, signature=None, *, user_funcs=None, consts=None, repl=None, explicit_symbols=None, allow_indexed=False)

Bases: 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, 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 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.

• repl (dict, optional) – Replacements that are applied to symbols before turning the expression into a python equivalent.

• explicit_symbols (list of str) – List of symbols that need to be interpreted as general sympy symbols

• allow_indexed (bool) – Whether to allow indexing of variables. If enabled, array variables are allowed to be indexed using square bracket notation.

copy()

return a copy of the current expression

Return type:

ScalarExpression

derivatives

differentiate the expression with respect to all variables

differentiate(var)

return the expression differentiated with respect to var

Parameters:

var (str) –

Return type:

ScalarExpression

property is_zero: bool

returns whether the expression is zero

Type:

bool

shape: tuple[int, ...] = ()

property value: int | float | complex

the value for a constant expression

Type:

float

class TensorExpression(expression, signature=None, *, user_funcs=None, consts=None, repl=None, explicit_symbols=None)

Bases: 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, 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 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.

• repl (dict, optional) – Replacements that are applied to symbols before turning the expression into a python equivalent.

• explicit_symbols (list of str) – List of symbols that need to be interpreted as general sympy symbols

derivatives

differentiate the expression with respect to all variables

differentiate(var)

return the expression differentiated with respect to var

Parameters:

var (str) –

Return type:

TensorExpression

get_compiled_array(single_arg=True)

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.

Return type:

Callable[[ndarray, ndarray | None], ndarray]

property rank: int

rank of the tensor expression

Type:

int

property shape: tuple[int, ...]

the shape of the tensor

Type:

tuple

property value

the value for a constant expression

evaluate(expression, fields, *, bc='auto_periodic_neumann', bc_ops=None, user_funcs=None, consts=None, label=None)

evaluate an expression involving fields

Warning

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

Parameters:

• expression (str) – The expression, which is parsed by sympy. The expression may contain variables (i.e., fields and spatial coordinates of the grid), standard local mathematical operators defined by sympy, and the operators defined in the pde package. Note that operators need to be specified with their full name, i.e., laplace for a scalar Laplacian and vector_laplace for a Laplacian operating on a vector field. Moreover, the dot product between two vector fields can be denoted by using dot(field1, field2) in the expression, and outer(field1, field2) calculates an outer product. More information can be found in the expression documentation.

• fields (dict or FieldCollection) – Dictionary of the fields involved in the expression. The dictionary keys specify the field names allowed in expression. Alternatively, fields can be a FieldCollection with unique labels.

• bc (BoundariesData) – Boundary conditions for the operators used in the expression. The conditions here are applied to all operators that do not have a specialized condition given in bc_ops. Boundary conditions are generally given as a list with one condition for each axis. For periodic axes, only periodic boundary conditions are allowed (indicated by ‘periodic’ and ‘anti-periodic’). For non- periodic axes, different boundary conditions can be specified for the lower and upper end (using a tuple of two conditions). For instance, Dirichlet conditions enforcing a value NUM (specified by {‘value’: NUM}) and Neumann conditions enforcing the value DERIV for the derivative in the normal direction (specified by {‘derivative’: DERIV}) are supported. Note that the special value ‘natural’ imposes periodic boundary conditions for periodic axis and a vanishing derivative otherwise. More information can be found in the boundaries documentation.

• bc_ops (dict) – Special boundary conditions for some operators. The keys in this dictionary specify the operator to which the boundary condition will be applied.

• user_funcs (dict, optional) – A dictionary with user defined functions that can be used in the expressions in rhs.

• consts (dict, optional) – A dictionary with user defined constants that can be used in the expression. These can be either scalar numbers or fields defined on the same grid as the actual simulation.

• label (str) – Name of the field that is returned.

Returns:

The resulting field. The rank of the returned field (and thus the precise class) is determined automatically.

Return type:

pde.fields.base.DataFieldBase

parse_number(expression, variables=None)

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