# esys.escript.symbolic Package

## Classes

- `Evaluator`

- `Symbol`

class esys.escript.symbolic.Evaluator(*expressions)
  __init__(*expressions)

    Returns a symbolic evaluator.

    Parameters

      expressions – optional expressions to initialise with

  addExpression(expression)

    Adds an expression to this evaluator.

    Returns

      the modified Evaluator object

  evaluate(evalf=False, **args)

    Evaluates all expressions in this evaluator and returns the result as a tuple.

    Returns

      the evaluated expressions in the order they were added to this Evaluator.

  subs(**args)

    Symbol substitution.

    Returns

      the modified Evaluator object

class esys.escript.symbolic.Symbol(*args, **kwargs)

  `Symbol` objects are placeholders for a single mathematical symbol, such as ‘x’, or for arbitrarily complex mathematical expressions such as ‘c*x**4+alpha*exp(x)-2*sin(beta*x)’, where ‘alpha’, ‘beta’, ‘c’, and ‘x’ are also Symbols (the symbolic ‘atoms’ of the expression).

  With the help of the ‘Evaluator’ class these symbols and expressions can be resolved by substituting numeric values and/or escript `Data` objects for the atoms. To facilitate the use of `Data` objects a `Symbol` has a shape (and thus a rank) as well as a dimension (see constructor). Symbols are useful to perform mathematical simplifications, compute derivatives and as coefficients for nonlinear PDEs which can be solved by the `NonlinearPDE` class.

  __init__(*args, **kwargs)

    Initialises a new `Symbol` object in one of three ways:

        u=Symbol('u')

    returns a scalar symbol by the name ‘u’.

    > alpha=Symbol(‘alpha’, (4,3))

    returns a rank 2 symbol with the shape (4,3), whose elements are named ‘[alpha]_i_j’ (with i=0..3, j=0..2).

    > a,b,c=symbols(‘a,b,c’) x=Symbol([[a+b,0,0],[0,b-c,0],[0,0,c-a]])

    returns a rank 2 symbol with the shape (3,3) whose elements are explicitly specified by numeric values and other symbols/expressions within a list or numpy array.

    The dimensionality of the symbol can be specified through the `dim` keyword. All other keywords are passed to the underlying symbolic library (currently sympy).

    Parameters

      - args – initialisation arguments as described above

      - dim (`int`) – dimensionality of the new Symbol (default: 2)

  applyfunc(f, on_type=None)

    Applies the function `f` to all elements (if on_type is None) or to all elements of type `on_type`.

  atoms(*types)

    Returns the atoms that form the current Symbol.

    By default, only objects that are truly atomic and cannot be divided into smaller pieces are returned: symbols, numbers, and number symbols like I and pi. It is possible to request atoms of any type, however.

    Note that if this symbol contains components such as [x]_i_j then only their main symbol ‘x’ is returned.

    Parameters

      types – types to restrict result to

    Returns

      list of atoms of specified type

    Return type

      `set`

  coeff(x, expand=True)

    Returns the coefficient of the term “x” or 0 if there is no “x”.

    If “x” is a scalar symbol then “x” is searched in all components of this symbol. Otherwise the shapes must match and the coefficients are checked component by component.

    Example:

        x=Symbol('x', (2,2))
        y=3*x
        print y.coeff(x)
        print y.coeff(x[1,1])

    will print:

        [[3 3]
         [3 3]]

        [[0 0]
         [0 3]]

    Parameters

      x (`Symbol`, `numpy.ndarray`, `list`) – the term whose coefficients are to be found

    Returns

      the coefficient(s) of the term

    Return type

      `Symbol`

  diff(*symbols, **assumptions)
  evalf()

    Applies the sympy.evalf operation on all elements in this symbol

  expand()

    Applies the sympy.expand operation on all elements in this symbol

  getDataSubstitutions()

    Returns a dictionary of symbol names and the escript `Data` objects they represent within this Symbol.

    Returns

      the dictionary of substituted `Data` objects

    Return type

      `dict`

  getDim()

    Returns the spatial dimensionality of this symbol.

    Returns

      the symbol’s spatial dimensionality, or -1 if undefined

    Return type

      `int`

  getRank()

    Returns the rank of this symbol.

    Returns

      the symbol’s rank which is equal to the length of the shape.

    Return type

      `int`

  getShape()

    Returns the shape of this symbol.

    Returns

      the symbol’s shape

    Return type

      `tuple` of `int`

  grad(where=None)

    Returns a symbol which represents the gradient of this symbol. :type where: `Symbol`, `FunctionSpace`

  inverse()
  is_Add = False
  is_Float = False
  item(*args)

    Returns an element of this symbol. This method behaves like the item() method of numpy.ndarray. If this is a scalar Symbol, no arguments are allowed and the only element in this Symbol is returned. Otherwise, ‘args’ specifies a flat or nd-index and the element at that index is returned.

    Parameters

      args – index of item to be returned

    Returns

      the requested element

    Return type

      `sympy.Symbol`, `int`, or `float`

  lambdarepr()
  simplify()

    Applies the sympy.simplify operation on all elements in this symbol

  subs(old, new)

    Substitutes an expression.

  swap_axes(axis0, axis1)
  tensorProduct(other, axis_offset)
  tensorTransposedProduct(other, axis_offset)
  trace(axis_offset)

    Returns the trace of this Symbol.

  transpose(axis_offset)

    Returns the transpose of this Symbol.

  transposedTensorProduct(other, axis_offset)

## Functions

esys.escript.symbolic.combineData(array, shape)

esys.escript.symbolic.getTotalDifferential(f, x, order=0)

  This function computes:

      | Df/Dx = del_f/del_x + del_f/del_grad(x)*del_grad(x)/del_x + ...
      |            \   /         \   /
      |              a             b

esys.escript.symbolic.isSymbol(arg)

  Returns True if the argument `arg` is an escript `Symbol` or `sympy.Basic` object, False otherwise.

esys.escript.symbolic.pprint(expr, use_unicode=None)

  Prints expr in pretty form.

  pprint is just a shortcut for this function

esys.escript.symbolic.pretty_print(expr, use_unicode=None)

  Prints expr in pretty form.

  pprint is just a shortcut for this function

esys.escript.symbolic.removeFsFromGrad(sym)

  Returns `sym` with all occurrences grad_n(a,b,c) replaced by grad_n(a,b). That is, all functionspace parameters are removed.

esys.escript.symbolic.symbols(*names, **kwargs)

  Emulates the behaviour of sympy.symbols.

## Others

- HAVE_SYMBOLS

## Packages