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 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=(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} of the # Dimension can be set at will.
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 as0, 1, 2, 0, 1, 2, 0, ...
.When
modulo=None
, the ModuloDimension degenerates and keeps generating the same number such as2, 2, 2, 2, 2, ...
(the actual value depends onincr
).- 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.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 as0, 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
andright
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, passlocal=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.