# 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`).

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}) # doctest: +SKIP
ValueError: Invalid limits given: ((2*y, 1, 4*y),)
```

`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]

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