utilities.symbolic.lambdify_expression#

utilities.symbolic.lambdify_expression(expression: str | Basic, axes: List[Symbol], parameters: Dict[str, Any] | None = None) → Callable[source]#

Convert a Sympy expression (scalar, Matrix, or N-dimensional Array) or a string into a callable function. The returned function depends on the given axes and optional parameters, and returns either:

  • A scalar or array of shape matching the input arguments (if the expression is scalar).

  • A 2D or higher-dimensional NumPy array (if the expression is a sympy.matrices.Matrix or N-dim Array).

The returned function utilizes numpy functions to ensure that it is relatively optimized for use on array valued arguments.

Note

While lambdify_expression() is designed to perform relatively well on array inputs, it should not be called in large loops as the call overhead can be quite large.

Parameters:

  • expression (str or sympy.Basic) – The expression to be converted into a callable function. This may be any valid sympy expression or a string which can be parsed directly to a valid sympy expression using sympy.sympify(). In expression is a sympy matrix or other non-scalar object, each element is lambdified independently and then combined again in the callable that is returned.

  • axes (list of Symbol) – The list of coordinate symbols which will become the arguments of the resulting function. This should be a list of valid Symbol objects, each corresponding to an independent variable in the expression. The order of the axes will determine the expected order of inputs when using the resulting callable function.

  • parameters (dict, optional) – A mapping from symbol name to numerical value (or another valid Sympy expression) which will be substituted into the final expression. Defaults to None.

Returns:

A function f(*axes) that evaluates the expression numerically:

  • If the expression is scalar: returns float or NumPy array.

  • If the expression is Matrix/Array: returns a NumPy array of shape (rows, cols) or the corresponding multi-dimensional shape. If the first argument is an array of length N, then the result generally has shape (N, rows, cols, ...) etc.

Return type:

Callable

Raises:

ValueError –

  • If sympifying the expression fails. - If there are unrecognized symbols that do not match any of the axes or parameters. - If a constant expression cannot be converted to float.

Examples

>>> import sympy as sp
>>> x = sp.Symbol('x')
>>> expr = sp.Matrix([[1, 0], [x, 1]])
>>> f = lambdify_expression(expr, axes=[x])
>>> import numpy as np
>>> print(f(2.0))
[[1. 0.]
 [2. 1.]]
>>> # For an array of x-values, you'll get shape (N, 2, 2).
>>> xs = np.linspace(0, 1, 3)
>>> print(f(xs).shape)
(3, 2, 2)

Notes

This operation proceeds in the following basic steps:

  1. Parse and sympify string expressions.

  2. Substitute known parameters.

  3. Validate that any remaining free symbols are among the provided axes.

  4. Identify whether the expression is a scalar, Matrix, or Array.

  5. Recursively lambdify each entry (for Matrix/Array), or do a scalar lambdify.

  6. Return a function that evaluates those sub-lambdas and aggregates them into a NumPy array of the correct shape (for Matrix/Array) or a scalar/array (for scalar expressions).

On this page

This Page