Equation

User API to specify equations.

class devito.equation.Eq[source]

Bases: sympy.core.relational.Equality, devito.tools.abc.Evaluable

An equal relation between two objects, the left-hand side and the right-hand side.

The left-hand side may be a Function or a SparseFunction. The right-hand side may be any arbitrary expressions with numbers, Dimensions, Constants, Functions and SparseFunctions as operands.

Parameters
  • lhs (Function or SparseFunction) – The left-hand side.

  • rhs (expr-like, optional) – The right-hand side. Defaults to 0.

  • subdomain (SubDomain, optional) – To restrict the computation of the Eq to a particular sub-region in the computational domain.

  • coefficients (Substitutions, optional) – Can be used to replace symbolic finite difference weights with user defined weights.

  • implicit_dims (Dimension or list of Dimension, optional) – An ordered list of Dimensions that do not explicitly appear in either the left-hand side or in the right-hand side, but that should be honored when constructing an Operator.

Examples

>>> from devito import Grid, Function, Eq
>>> grid = Grid(shape=(4, 4))
>>> f = Function(name='f', grid=grid)
>>> Eq(f, f + 1)
Eq(f(x, y), f(x, y) + 1)

Any SymPy expressions may be used in the right-hand side.

>>> from sympy import sin
>>> Eq(f, sin(f.dx)**2)
Eq(f(x, y), sin(Derivative(f(x, y), x))**2)

Notes

An Eq can be thought of as an assignment in an imperative programming language (e.g., a[i] = b[i]*c).

evaluate

Evaluate the Equation or system of Equations. The rhs of the Equation is evaluated at the indices of the lhs if required.

property subdomain

The SubDomain in which the Eq is defined.

xreplace(rules)[source]

Replace occurrences of objects within the expression.

Parameters

rule (dict-like) – Expresses a replacement rule

Returns

xreplace

Return type

the result of the replacement

Examples

>>> from sympy import symbols, pi, exp
>>> x, y, z = symbols('x y z')
>>> (1 + x*y).xreplace({x: pi})
pi*y + 1
>>> (1 + x*y).xreplace({x: pi, y: 2})
1 + 2*pi

Replacements occur only if an entire node in the expression tree is matched:

>>> (x*y + z).xreplace({x*y: pi})
z + pi
>>> (x*y*z).xreplace({x*y: pi})
x*y*z
>>> (2*x).xreplace({2*x: y, x: z})
y
>>> (2*2*x).xreplace({2*x: y, x: z})
4*z
>>> (x + y + 2).xreplace({x + y: 2})
x + y + 2
>>> (x + 2 + exp(x + 2)).xreplace({x + 2: y})
x + exp(y) + 2

xreplace doesn’t differentiate between free and bound symbols. In the following, subs(x, y) would not change x since it is a bound symbol, but xreplace does:

>>> from sympy import Integral
>>> Integral(x, (x, 1, 2*x)).xreplace({x: y})
Integral(y, (y, 1, 2*y))

Trying to replace x with an expression raises an error:

>>> Integral(x, (x, 1, 2*x)).xreplace({x: 2*y}) 
ValueError: Invalid limits given: ((2*y, 1, 4*y),)

See also

replace()

replacement capable of doing wildcard-like matching, parsing of match, and conditional replacements

subs()

substitution of subexpressions as defined by the objects themselves.

class devito.equation.Inc[source]

Bases: devito.equation.Eq

An increment relation between two objects, the left-hand side and the right-hand side.

Parameters
  • lhs (Function or SparseFunction) – The left-hand side.

  • rhs (expr-like) – The right-hand side.

  • subdomain (SubDomain, optional) – To restrict the computation of the Eq to a particular sub-region in the computational domain.

  • coefficients (Substitutions, optional) – Can be used to replace symbolic finite difference weights with user defined weights.

  • implicit_dims (Dimension or list of Dimension, optional) – An ordered list of Dimensions that do not explicitly appear in either the left-hand side or in the right-hand side, but that should be honored when constructing an Operator.

Examples

Inc may be used to express tensor contractions. Below, a summation along the user-defined Dimension i.

>>> from devito import Grid, Dimension, Function, Inc
>>> grid = Grid(shape=(4, 4))
>>> x, y = grid.dimensions
>>> i = Dimension(name='i')
>>> f = Function(name='f', grid=grid)
>>> g = Function(name='g', shape=(10, 4, 4), dimensions=(i, x, y))
>>> Inc(f, g)
Inc(f(x, y), g(i, x, y))

Notes

An Inc can be thought of as the augmented assignment ‘+=’ in an imperative programming language (e.g., a[i] += c).

devito.equation.solve(eq, target, **kwargs)[source]

Algebraically rearrange an Eq w.r.t. a given symbol.

This is a wrapper around sympy.solve.

Parameters
  • eq (expr-like) – The equation to be rearranged.

  • target (symbol) – The symbol w.r.t. which the equation is rearranged. May be a Function or any other symbolic object.

  • **kwargs – Symbolic optimizations applied while rearranging the equation. For more information. refer to sympy.solve.__doc__.