API Reference

This page contains the full API documentation for complex-expr-parser.

Module Functions

complex_expr_parser.parse_complex_function(expr_str)[source]

Parse a complex function string into a sympy expression.

This is a convenience function that creates a parser and parses the given expression in one call.

Parameters:

expr_str (str) – Human-friendly function string.

Returns:

A sympy expression with z as the variable.

Raises:

ValueError – If the expression cannot be parsed.

Return type:

Expr

Example

>>> parse_complex_function("z^2 + 1")
z**2 + 1
>>> parse_complex_function("sin(z)/z")
sin(z)/z
>>> parse_complex_function("e^z")
exp(z)
complex_expr_parser.get_callable(expr_str, use_numpy=True)[source]

Parse and return a callable function for the given expression.

This is a convenience function that parses an expression and converts it to a callable in one step.

Parameters:

  • expr_str (str) – Human-friendly function string.

  • use_numpy (bool) – Use numpy for vectorized evaluation (faster for plotting).

Returns:

A callable function f(z) -> complex that evaluates the expression.

Return type:

Callable[[complex | Any], complex | Any]

Example

>>> f = get_callable("z^2 + 1")
>>> f(1+1j)
(1+2j)
>>> import numpy as np
>>> f(np.array([1, 1j, -1]))
array([2.+0.j, 0.+0.j, 2.+0.j])
complex_expr_parser.validate_expression(expr_str)[source]

Validate a complex function expression without fully evaluating it.

This function checks if an expression can be parsed and converted to a callable function. Useful for input validation in user interfaces.

Parameters:

expr_str (str) – Human-friendly function string.

Returns:

A tuple of (is_valid, error_message). If valid, error_message is None.

Return type:

tuple[bool, str | None]

Example

>>> validate_expression("z^2 + 1")
(True, None)
>>> validate_expression("z +* 1")
(False, "Could not parse expression: 'z +* 1'...")
>>> validate_expression("")
(False, "Expression cannot be empty")

ComplexFunctionParser Class

class complex_expr_parser.ComplexFunctionParser[source]

Bases: object

Fault-tolerant parser for complex functions.

Accepts various human-friendly notations and converts to sympy expressions.

Supported notations:

  • Power notation: z^2 or z**2

  • Implicit multiplication: 2z, z(z+1), (z+1)(z-1)

  • Absolute value: |z| -> Abs(z)

  • Conjugate: z* -> conjugate(z) (note: z** is power)

  • Unicode: pi -> pi, sqrt -> sqrt, oo -> infinity

  • Function aliases:

    • ln -> log

    • arcsin/arccos/arctan -> asin/acos/atan

    • Re/real -> re, Im/imag -> im

    • phase/angle -> arg

    • conj -> conjugate

  • Imaginary unit: i or j -> I

  • Euler’s number: standalone e -> E

Example

>>> parser = ComplexFunctionParser()
>>> expr = parser.parse("2z^2 + 3z + 1")
>>> print(expr)
2*z**2 + 3*z + 1
>>> f = parser.to_callable(expr)
>>> f(1+1j)
(5+8j)
__init__()[source]

Initialize the parser with sympy transformations and namespace.

Return type:

None

preprocess(expr_str)[source]

Apply substitutions and normalizations to input string.

Parameters:

expr_str (str) – The raw expression string.

Returns:

Preprocessed expression string ready for sympy parsing.

Return type:

str

parse(expr_str)[source]

Parse a human-friendly complex function string into a sympy expression.

This method attempts multiple parsing strategies to handle various input formats gracefully.

Parameters:

expr_str (str) – String representation of the function.

Returns:

A sympy expression with z as the variable.

Raises:

ValueError – If parsing fails with all strategies.

Return type:

Expr

Example

>>> parser = ComplexFunctionParser()
>>> parser.parse("z^2 + 1")
z**2 + 1
>>> parser.parse("sin(z)/z")
sin(z)/z
>>> parser.parse("|z|")
Abs(z)
to_callable(expr, use_numpy=True)[source]

Convert sympy expression to a callable function.

Parameters:

  • expr (Expr) – A sympy expression.

  • use_numpy (bool) – If True, use numpy for vectorized evaluation (faster). If False or if special functions are needed, use mpmath.

Returns:

A callable that takes complex numbers (or numpy arrays) and returns complex numbers.

Return type:

Callable[[complex | Any], complex | Any]

Note

Special functions like gamma and zeta automatically use mpmath for evaluation regardless of the use_numpy setting.

Example

>>> parser = ComplexFunctionParser()
>>> expr = parser.parse("z^2")
>>> f = parser.to_callable(expr)
>>> f(1+1j)
2j
>>> import numpy as np
>>> f(np.array([1, 1j, -1]))
array([ 1.+0.j, -1.+0.j,  1.+0.j])

Module Constants

z

complex_expr_parser.z: sympy.Symbol

The complex variable symbol used in parsed expressions.

Example:

from complex_expr_parser import z, parse_complex_function

expr = parse_complex_function("z^2")
# expr is equivalent to z**2

KNOWN_FUNCTIONS

complex_expr_parser.KNOWN_FUNCTIONS: list[str]

List of recognized function names that the parser handles specially. These function names are protected from implicit multiplication (e.g., sin(z) won’t become s*i*n*(z)).

Includes:

  • Trigonometric: sin, cos, tan, asin, acos, atan

  • Hyperbolic: sinh, cosh, tanh, asinh, acosh, atanh

  • Exponential/Log: exp, log, ln, sqrt

  • Complex: Abs, abs, conjugate, conj, re, im, arg

  • Special: gamma, zeta, factorial, binomial

  • Aliases: arcsin, arccos, arctan, Re, Im, real, imag, phase, angle