Dimension

class devito.types.dimension.BlockDimension(*args, **kwargs)[source]

Bases: AbstractIncrDimension

Dimension symbol for lowering TILABLE Dimensions.

class devito.types.dimension.ConditionalDimension(*args, **kwargs)[source]

Bases: DerivedDimension

Symbol defining a non-convex iteration sub-space derived from a parent Dimension, implemented by the compiler generating conditional “if-then” code within the parent Dimension’s iteration space.

Parameters:

name (str) – Name of the dimension.
parent (Dimension, optional) – The parent Dimension.
factor (int, optional) – The number of iterations between two executions of the if-branch. If None (default), condition must be provided.
condition (expr-like, optional) – An arbitrary SymPy expression, typically involving the parent Dimension. When it evaluates to True, the if-branch is executed. If None (default), factor must be provided.
indirect (bool, optional) – If True, use self, rather than the parent Dimension, to index into arrays. A typical use case is when arrays are accessed indirectly via the condition expression. Defaults to False.

Examples

Among the other things, ConditionalDimensions are indicated to implement Function subsampling. In the following example, an Operator evaluates the Function g and saves its content into f every factor=4 iterations.

>>> from devito import Dimension, ConditionalDimension, Function, Eq, Operator
>>> size, factor = 16, 4
>>> i = Dimension(name='i')
>>> ci = ConditionalDimension(name='ci', parent=i, factor=factor)
>>> g = Function(name='g', shape=(size,), dimensions=(i,))
>>> f = Function(name='f', shape=(int(size/factor),), dimensions=(ci,))
>>> op = Operator([Eq(g, 1), Eq(f, g)])

The Operator generates the following for-loop (pseudocode)

for (int i = i_m; i <= i_M; i += 1) {
  g[i] = 1;
  if (i%4 == 0) {
    f[i / 4] = g[i];
  }
}

Another typical use case is when one needs to constrain the execution of loop iterations so that certain conditions are honoured. The following artificial example uses ConditionalDimension to guard against out-of-bounds accesses in indirectly accessed arrays.

>>> from sympy import And
>>> ci = ConditionalDimension(name='ci', parent=i,
...                           condition=And(g[i] > 0, g[i] < 4, evaluate=False))
>>> f = Function(name='f', shape=(int(size/factor),), dimensions=(ci,))
>>> op = Operator(Eq(f[g[i]], f[g[i]] + 1))

The Operator generates the following for-loop (pseudocode)

for (int i = i_m; i <= i_M; i += 1) {
  if (g[i] > 0 && g[i] < 4) {
    f[g[i]] = f[g[i]] + 1;
  }
}

property factor: See the factor() function in sympy.polys.polytools

free_symbols

property spacing: Symbol representing the physical spacing along the Dimension.

class devito.types.dimension.CustomDimension(*args, **kwargs)[source]

Bases: BasicDimension

Dimension defining an iteration space with known size. Unlike a DefaultDimension, a CustomDimension:

Provides more freedom – the symbolic_{min,max,size} can be set at will;

It provides no runtime argument values.

Notes

This type should not be instantiated directly in user code.

property bound_symbols: Unlike SymPy, we systematically define bound_symbols on all of the API and internal objects that may be used to construct an Operator.

property is_Derived

bool(x) -> bool

Returns True when the argument x is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

property spacing: Symbol representing the physical spacing along the Dimension.

property symbolic_max: Symbol defining the maximum point of the Dimension.

property symbolic_min: Symbol defining the minimum point of the Dimension.

property symbolic_size: Symbolic size of the Dimension.

class devito.types.dimension.DefaultDimension(*args, **kwargs)[source]

Bases: Dimension, DataSymbol

Symbol defining an iteration space with statically-known size.

Parameters:

name (str) – Name of the dimension.
spacing (Symbol, optional) – A symbol to represent the physical spacing along this Dimension.
default_value (float, optional) – Default value associated with the Dimension.

Notes

A DefaultDimension carries a value, so it has a mutable state. Hence, it is not cached.

symbolic_size

class devito.types.dimension.Dimension(*args, **kwargs)[source]

Bases: ArgProvider

Symbol defining an iteration space.

A Dimension represents a problem dimension. It is typically used to index into Functions, but it can also appear in the middle of a symbolic expression just like any other symbol.

Dimension is the root of a hierarchy of classes, which looks as follows (only the classes exposed to the level of the user API are shown):

                         Dimension
                             |
                ---------------------------
                |                         |
         DerivedDimension            DefaultDimension
                |
     ---------------------
     |                   |
SubDimension   ConditionalDimension

Parameters:

name (str) – Name of the dimension.
spacing (symbol, optional) – A symbol to represent the physical spacing along this Dimension.

Examples

Dimensions are automatically created when a Grid is instantiated.

>>> from devito import Grid
>>> grid = Grid(shape=(4, 4))
>>> x, y = grid.dimensions
>>> type(x)
<class 'devito.types.dimension.SpaceDimension'>
>>> time = grid.time_dim
>>> type(time)
<class 'devito.types.dimension.TimeDimension'>
>>> t = grid.stepping_dim
>>> type(t)
<class 'devito.types.dimension.SteppingDimension'>

Alternatively, one can create Dimensions explicitly

>>> from devito import Dimension
>>> i = Dimension(name='i')

Or, when many “free” Dimensions are needed, with the shortcut

>>> from devito import dimensions
>>> i, j, k = dimensions('i j k')

A Dimension can be used to build a Function as well as within symbolic expressions, as both array index (“indexed notation”) and free symbol.

>>> from devito import Function
>>> f = Function(name='f', shape=(4, 4), dimensions=(i, j))
>>> f + f
2*f(i, j)
>>> f[i + 1, j] + f[i, j + 1]
f[i, j + 1] + f[i + 1, j]
>>> f*i
i*f(i, j)

classmethod class_key()[source]: Overrides sympy.Symbol.class_key such that Dimensions always preceed other symbols when printed (e.g. x + h_x, not h_x + x).

property spacing: Symbol representing the physical spacing along the Dimension.

property symbolic_incr: The increment value while iterating over the Dimension.

symbolic_max: Symbol defining the maximum point of the Dimension.

symbolic_min: Symbol defining the minimum point of the Dimension.

symbolic_size: Symbolic size of the Dimension.

class devito.types.dimension.IncrDimension(*args, **kwargs)[source]

Bases: AbstractIncrDimension

A concrete implementation of an AbstractIncrDimension.

Notes

This type should not be instantiated directly in user code.

class devito.types.dimension.ModuloDimension(*args, **kwargs)[source]

Bases: DerivedDimension

Dimension symbol representing a non-contiguous sub-region of a given parent Dimension, which cyclically produces a finite range of values, such as 0, 1, 2, 0, 1, 2, 0, ....

When modulo=None, the ModuloDimension degenerates and keeps generating the same number such as 2, 2, 2, 2, 2, ... (the actual value depends on incr).

Parameters:

name (str) – Name of the dimension.
parent (Dimension) – The Dimension from which the ModuloDimension is derived.
offset (expr-like, optional) – Min value offset. Defaults to 0.
modulo (int, optional) – The divisor value.
incr (expr-like, optional) – The iterator increment value. Defaults to offset % modulo.
origin (expr-like, optional) – The expression – typically a function of the parent Dimension – the ModuloDimension represents.

Notes

This type should not be instantiated directly in user code; if in need for modulo buffered iteration, use SteppingDimension instead.

About origin – the ModuloDimensions t0, t1, t2, … are generated by the compiler to implement modulo iteration along a TimeDimension. For example, t0’s origin may be t + 0 (where t is a SteppingDimension), t1’s origin will then be t + 1 and so on.

bound_symbols

symbolic_incr

symbolic_min

symbolic_size

class devito.types.dimension.SpaceDimension(*args, **kwargs)[source]

Bases: BasicDimension

Symbol defining an iteration space.

This symbol represents a space dimension that defines the extent of a physical grid.

A SpaceDimension creates dedicated shortcut notations for spatial derivatives on Functions.

Parameters:

name (str) – Name of the dimension.
spacing (symbol, optional) – A symbol to represent the physical spacing along this Dimension.

class devito.types.dimension.Spacing(*args, **kwargs)[source]: Bases: Scalar

class devito.types.dimension.StencilDimension(*args, **kwargs)[source]

Bases: BasicDimension

Dimension symbol representing the points of a stencil.

Parameters:

name (str) – Name of the dimension.
_min (expr-like) – The minimum point of the stencil.
_max (expr-like) – The maximum point of the stencil.
spacing (expr-like, optional) – The space between two stencil points.

symbolic_max

symbolic_min

symbolic_size

class devito.types.dimension.SteppingDimension(*args, **kwargs)[source]

Bases: DerivedDimension

Symbol defining a convex iteration sub-space derived from a parent Dimension, which cyclically produces a finite range of values, such as 0, 1, 2, 0, 1, 2, 0, ... (also referred to as “modulo buffered iteration”).

SteppingDimension is most commonly used to represent a time-stepping Dimension.

Parameters:

name (str) – Name of the dimension.
parent (Dimension) – The parent Dimension.

property symbolic_max: Symbol defining the maximum point of the Dimension.

property symbolic_min: Symbol defining the minimum point of the Dimension.

class devito.types.dimension.SubDimension(*args, **kwargs)[source]

Bases: DerivedDimension

Symbol defining a convex iteration sub-space derived from a parent Dimension.

Parameters:

name (str) – Name of the dimension.
parent (Dimension) – The parent Dimension.
left (expr-like) – Symbolic expression providing the left (lower) bound of the SubDimension.
right (expr-like) – Symbolic expression providing the right (upper) bound of the SubDimension.
thickness (2-tuple of 2-tuples) – The thickness of the left and right regions, respectively.
local (bool) – True if, in case of domain decomposition, the SubDimension is guaranteed not to span more than one domains, False otherwise.

Examples

SubDimensions should not be created directly in user code; SubDomains should be used instead. Exceptions are rare.

To create a SubDimension, one should use the shortcut methods left, right, middle. For example, to create a SubDimension that spans the entire space of the parent Dimension except for the two extremes:

>>> from devito import Dimension, SubDimension
>>> x = Dimension('x')
>>> xi = SubDimension.middle('xi', x, 1, 1)

For a SubDimension that only spans the three leftmost points of its parent Dimension, instead:

>>> xl = SubDimension.left('xl', x, 3)

SubDimensions created via the left and right shortcuts are, by default, local (i.e., non-distributed) Dimensions, as they are assumed to fit entirely within a single domain. This is the most typical use case (e.g., to set up boundary conditions). To drop this assumption, pass local=False.

bound_symbols

symbolic_max

symbolic_min

symbolic_size

class devito.types.dimension.TimeDimension(*args, **kwargs)[source]

Bases: BasicDimension

Symbol defining an iteration space.

This symbol represents a time dimension that defines the extent of time.

A TimeDimension create dedicated shortcut notations for time derivatives on Functions.

Parameters:

name (str) – Name of the dimension.
spacing (symbol, optional) – A symbol to represent the physical spacing along this Dimension.