Equation
User API to specify equations.
- class devito.types.equation.Eq(lhs, rhs=0, subdomain=None, coefficients=None, implicit_dims=None, **kwargs)[source]
Bases:
Equality
,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 devito 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
).- func(*args, **kwargs)
Reconstruct self via self.__class__(*args, **kwargs) using self’s __rargs__ and __rkwargs__ if and where *args and **kwargs lack entries.
Examples
Given
- class Foo(object):
__rargs__ = (‘a’, ‘b’) __rkwargs__ = (‘c’,) def __init__(self, a, b, c=4):
self.a = a self.b = b self.c = c
a = foo(3, 5)`
Then:
a._rebuild() -> x(3, 5, 4) (i.e., copy of a).
a._rebuild(4) -> x(4, 5, 4)
a._rebuild(4, 7) -> x(4, 7, 4)
a._rebuild(c=5) -> x(3, 5, 5)
a._rebuild(1, c=7) -> x(1, 5, 7)
- 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 does not 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.types.equation.Inc(lhs, rhs=0, subdomain=None, coefficients=None, implicit_dims=None, **kwargs)[source]
Bases:
Reduction
An increment Reduction.
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
).