Dimension¶

class
devito.types.dimension.
Dimension
[source]¶ Bases:
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.
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
 BasicDimension DefaultDimension
 DerivedDimension
 SteppingDimension 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)

property
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.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.
TimeDimension
(*args, **kwargs)[source]¶ Bases:
devito.types.dimension.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.

class
devito.types.dimension.
DefaultDimension
(*args, **kwargs)[source]¶ Bases:
devito.types.dimension.Dimension
,devito.types.basic.DataSymbol
Symbol defining an iteration space with staticallyknown 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 subspace derived from a
parent
Dimension, which cyclically produces a finite range of values, such as0, 1, 2, 0, 1, 2, 0, ...
(also referred to as “modulo buffered iteration”).SteppingDimension is most commonly used to represent a timestepping 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:
devito.types.dimension.DerivedDimension
Symbol defining a convex iteration subspace derived from a
parent
Dimension. Parameters
name (str) – Name of the dimension.
parent (Dimension) – The parent Dimension.
left (exprlike) – Symbolic expression providing the left (lower) bound of the SubDimension.
right (exprlike) – Symbolic expression providing the right (upper) bound of the SubDimension.
thickness (2tuple of 2tuples) – 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
andright
shortcuts are, by default, local (i.e., nondistributed) 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, passlocal=False
.

class
devito.types.dimension.
ConditionalDimension
(*args, **kwargs)[source]¶ Bases:
devito.types.dimension.DerivedDimension
Symbol defining a nonconvex iteration subspace derived from a
parent
Dimension, implemented by the compiler generating conditional “ifthen” 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 ifbranch. If None (default),
condition
must be provided.condition (exprlike, optional) – An arbitrary SymPy expression, typically involving the
parent
Dimension. When it evaluates to True, the ifbranch 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 thecondition
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 intof
everyfactor=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 forloop (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 outofbounds 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 forloop (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

property
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 noncontiguous subregion of a given
parent
Dimension, which cyclically produces a finite range of values, such as0, 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 noncontiguous subregion of a given
parent
Dimension, with one point everystep
points. Thus, ifstep == k
, the dimension represents the sequencemin, 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.