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

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]

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]

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]

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.

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

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;
}
}
```
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 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.