Dimension

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

Bases: devito.types.basic.AbstractSymbol, devito.types.args.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.

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)
dtype

alias of numpy.int32

spacing

Symbol representing the physical spacing along 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.SpaceDimension(*args, **kwargs)[source]

Bases: devito.types.dimension.Dimension

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.TimeDimension(*args, **kwargs)[source]

Bases: devito.types.dimension.Dimension

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.

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

Bases: devito.types.dimension.Dimension

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.

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

Bases: devito.types.dimension.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.

symbolic_max

Symbol defining the maximum point of the Dimension.

symbolic_min

Symbol defining the minimum point of the Dimension.

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

Bases: devito.types.dimension.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.

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.ConditionalDimension(*args, **kwargs)[source]

Bases: devito.types.dimension.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) – 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 condition, 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=(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 to make sure certain conditions are honoured. The following artificial example employs indirect array accesses and uses ConditionalDimension to guard against out-of-bounds accesses.

>>> 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=(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;
  }
}
spacing

Symbol representing the physical spacing along the Dimension.

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

Bases: devito.types.dimension.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, ....

Parameters
  • parent (Dimension) – The Dimension from which the ModuloDimension is derived.

  • offset (int) – The offset from the parent dimension

  • modulo (int) – The divisor value.

  • name (str, optional) – To force a different Dimension name.

Notes

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

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

Bases: devito.types.dimension.DerivedDimension

Dimension symbol representing a non-contiguous sub-region of a given parent Dimension, with one point every step points. Thus, if step == k, the dimension represents the sequence min, min + k, min + 2*k, ....

Parameters
  • parent (Dimension) – The Dimension from which the IncrDimension is derived.

  • _min (int, optional) – The minimum point of the sequence. Defaults to the parent’s symbolic minimum.

  • step (int, optional) – The distance between two consecutive points. Defaults to the symbolic size.

  • name (str, optional) – To force a different Dimension name.

Notes

This type should not be instantiated directly in user code.