devito.ir.support package¶
Submodules¶
devito.ir.support.basic module¶

class
devito.ir.support.basic.
Vector
[source]¶ Bases:
tuple
A representation of a vector in Z^n.
The elements of a Vector can be integers or any SymPy expression.
If a comparison between a vector and a nonvector is attempted, then the nonvector is promoted to a vector; if this is not possible, an exception is raised. This is handy because it turns a vectorscalar comparison into a vectorvector comparison with the scalar broadcasted to all vector entries. For example:
(3, 4, 5) > 4 => (3, 4, 5) > (4, 4, 4) => False
When we compare two entries that are both generic SymPy expressions, it is generally not possible to determine the truth value of the relation. For example, the truth value of 3*i < 4*j cannot be determined. In some cases, however, the comparison is feasible; for example, i + 4 < i should always return false. A sufficient condition for two Vectors to be comparable is that their pairwise indices are affine functions of the same variables, with coefficient 1.

distance
(other)[source]¶ Compute the distance from
self
toother
.The distance is a reflexive, transitive, and antisymmetric relation, which establishes a total ordering amongst Vectors.
The distance is a function [Vector x Vector –> D]. D is a tuple of length equal to the Vector
rank
. The ith entry of D, D_i, indicates whether the ith component ofself
, self_i, precedes (< 0), equals (== 0), or succeeds (> 0) the ith component ofother
, other_i.In particular, the absolute value of D_i represents the number of integer points that exist between self_i and sink_i.
3   1   2  source =  2  , sink =  4  , distance =>  2 
 1   5   4 
There are 2, 2, and 4 points between [32], [24], and [15], respectively.

rank
¶

sum
¶


class
devito.ir.support.basic.
IterationInstance
[source]¶ Bases:
devito.ir.support.basic.Vector
A representation of the iteration and data points accessed by an
Indexed
object. Three different concepts are distinguished: Index functions: the expressions telling what iteration space point is accessed.
aindices
: the :class:`Dimension`s acting as iteration variables. There is one aindex for each index function. If the index function is nonaffine, then it may not be possible to detect its aindex; in such a case, None is used as placeholder.findices
: the :class:`Dimension`s telling what data space point is accessed.

affine
(findices)[source]¶ Return True if all of the provided findices appear in self and are affine, False otherwise.

affine_if_present
(findices)[source]¶ Return False if any of the provided findices appears in self and is not affine, True otherwise.

aindices
¶

distance
(other, findex=None, view=None)[source]¶ Compute the distance from
self
toother
.Parameters:  other – The
IterationInstance
from which the distance is computed.  findex – (Optional) if supplied, compute the distance only up to
and including
findex
(defaults to None).  view – (Optional) an iterable of
findices
(defaults to None); if supplied, project the distance along these dimensions.
 other – The

findices_affine
¶

findices_irregular
¶

index_mode
¶

irregular
(findices)[source]¶ Return True if all of the provided findices appear in self and are irregular, False otherwise.

is_irregular
¶

is_regular
¶

is_scalar
¶

class
devito.ir.support.basic.
Access
[source]¶ Bases:
devito.ir.support.basic.IterationInstance
A representation of the access performed by a
Indexed
object (a scalar in the degenerate case).The comparison operators
==, !=, <, <=, >, >=
should be regarded as operators for lexicographic ordering ofAccess
objects, based on the values of the index functions (and the index functions only).For example, if two Access objects A and B employ the same index functions, the operation A == B will return True regardless of whether A and B are reads or writes or mixed.

is_increment
¶

is_local
¶

is_read
¶

is_read_increment
¶

is_write
¶

is_write_increment
¶

name
¶


class
devito.ir.support.basic.
TimedAccess
[source]¶ Bases:
devito.ir.support.basic.Access
A special
Access
object enriched with:* a "timestamp"; that is, an integer indicating the access location within the execution flow; * an array of directions; there is one direction for each index, indicating whether the index function is monotonically increasing or decreasing.
Further, a TimedAccess may be regular or irregular. A TimedAccess is regular if and only if all index functions are affine in their respective findex. The downside of irregular TimedAccess objects is that dependence testing is harder, which in turn may force the data dependence analyzer to make stronger assumptions to be conservative.
Given: findices = [x, y, z] w = an object of type Dimension
x+1   x   x   w   x+y  obj1 =  y+2  , obj2 =  4  , obj3 =>  x  , obj4 =  y  , obj5 =  y 
 z3   z+1   y   z   z 
We have that:
* obj1 and obj2 are regular; * obj3 is irregular because an findex, ``x``, appears outside of its index function (i.e., in the second slot, whew ``y`` is expected); * obj4 is irregular, because a different dimension, ``w``, is used in place of ``x`` within the first index function, where ``x`` is expected; * obj5 is irregular, as two findices appear in the same index function  the one in the first slot, where only ``x`` is expected.

distance
(other, findex=None)[source]¶ Compute the distance from
self
toother
.Parameters:  other – The
IterationInstance
from which the distance is computed.  findex – (Optional) if supplied, compute the distance only up to
and including
findex
(defaults to None).  view – (Optional) an iterable of
findices
(defaults to None); if supplied, project the distance along these dimensions.
 other – The

class
devito.ir.support.basic.
Scope
(exprs)[source]¶ Bases:
object

accesses
¶

d_all
¶ Retrieve all flow, anti, and output dependences.

d_anti
¶ Retrieve the anti dependencies, or writeafterread.

d_flow
¶ Retrieve the flow dependencies, or true dependencies, or readafterwrite.

d_output
¶ Retrieve the output dependencies, or writeafterwrite.

has_dep
¶ Return True if at least a dependency is detected, False otherwise.

devito.ir.support.space module¶

class
devito.ir.support.space.
NullInterval
(dim)[source]¶ Bases:
devito.ir.support.space.AbstractInterval

is_Null
= True¶

merge
(o)¶


class
devito.ir.support.space.
Interval
(dim, lower, upper)[source]¶ Bases:
devito.ir.support.space.AbstractInterval
Create an
Interval
of extent:dim.extent + abs(upper  lower)

is_Defined
= True¶

limits
¶


class
devito.ir.support.space.
IntervalGroup
[source]¶ Bases:
devito.tools.data_structures.PartialOrderTuple
A partiallyordered sequence of :class:`Interval`s with setlike operations exposed.

dimensions
¶

extent
¶

classmethod
generate
(op, *interval_groups)[source]¶ Create a new
IntervalGroup
from the iterative application of the operationop
to theIntervalGroup`s in ``interval_groups`
.Parameters: ig0 = IntervalGroup([Interval(x, 1, 1)]) ig1 = IntervalGroup([Interval(x, 2, 2), Interval(y, 3, 3)]) ig2 = IntervalGroup([Interval(y, 2, 2), Interval(z, 1, 1)])
ret = IntervalGroup.generate(‘intersection’, ig0, ig1, ig2) ret > IntervalGroup([Interval(x, 2, 2), Interval(y, 3, 3), Interval(z, 1, 1)])

is_well_defined
¶ Return True if all :class:`Interval`s are over different :class:`Dimension`s, False otherwise.

shape
¶


class
devito.ir.support.space.
IterationSpace
(intervals, sub_iterators=None, directions=None)[source]¶ Bases:
devito.ir.support.space.Space
A representation of an iteration space and its traversal through :class:`Interval`s and :class:`IterationDirection`s. For each interval, an arbitrary number of (sub)iterators may be specified (see below).
Parameters:  intervals – An ordered sequence of :class:`Interval`s defining the iteration space.
 sub_iterators – (Optional) a mapper from
Dimension`s in ``intervals`
to iterables ofDerivedDimension
, which represent subdimensions along which the iteration space is traversed.  directions – (Optional) a mapper from
Dimension`s in ``intervals`
to :class:`IterationDirection`s.

args
¶

dimensions
¶

directions
¶

is_compatible
(other)[source]¶ A relaxed version of
__eq__
, in which only nonderived dimensions are compared for equality.

itintervals
¶

nonderived_directions
¶

project
(cond)[source]¶ Return a new
IterationSpace
in which only someDimension`s in ``self`
are retained. In particular, a dimensiond
inself
is retained if:* either ``cond(d)`` is true (``cond`` is a callable), * or ``d in cond`` is true (``cond`` is an iterable)

sub_iterators
¶

class
devito.ir.support.space.
DataSpace
(intervals, parts)[source]¶ Bases:
devito.ir.support.space.Space
A representation of a data space.
Parameters:  intervals – A sequence of :class:`Interval`s describing the data space.
 parts – A mapper from
Function`s to iterables of :class:`Interval
describing the individual components of the data space.

parts
¶

devito.ir.support.space.
Forward
= ++¶ Forward iteration direction (‘++’).

devito.ir.support.space.
Backward
= ¶ Backward iteration direction (‘–’).

devito.ir.support.space.
Any
= *¶ Wildcard direction (both ‘++’ and ‘–’ would be OK).
devito.ir.support.stencil module¶

class
devito.ir.support.stencil.
Stencil
(entries=None)[source]¶ Bases:
devito.tools.data_structures.DefaultOrderedDict
A Stencil is a mapping from
Dimension
symbols to the set of integer offsets used with it in expressions (the “neighboring points accessed”).This also include zero offsets.
The mapping is ordered based on the order in which dimensions are encountered (if extracted from expressions) or inserted.
Note: Expressions must have been indexified for a Stencil to be computed.

add
(o)[source]¶ Compute the set union of each Dimension in self with the corresponding Dimension in
o
.

diameter
¶

dimensions
¶

empty
¶

entries
¶

devito.ir.support.utils module¶

devito.ir.support.utils.
detect_accesses
(expr)[source]¶ Return a mapper
M : F > S
, where F areFunction`s appearing in ``expr`
and S areStencil`s. ``M[f]`
represents all data accesses tof
withinexpr
. Also mapM[None]
to all Dimensions used inexpr
as plain symbols, rather than as array indices.

devito.ir.support.utils.
detect_oobs
(mapper)[source]¶ Given M as produced by
detect_accesses()
, return the set of :class:`Dimension`s that cannot be iterated over for the entire computational domain, to avoid outofbounds (OOB) accesses.

devito.ir.support.utils.
build_iterators
(mapper)[source]¶ Given M as produced by
detect_accesses()
, return a mapperM' : D > V
, where D is the set ofDimension`s in M, and V is a set of :class:`DerivedDimension`s. M'[d] provides the subiterators along the Dimension `d
.

devito.ir.support.utils.
build_intervals
(stencil)[source]¶ Given a
Stencil
, return an iterable ofInterval`s, one for each :class:`Dimension
in the stencil.

devito.ir.support.utils.
detect_flow_directions
(exprs)[source]¶ Return a mapper from
Dimension`s to iterables of :class:`IterationDirection`s representing the theoretically necessary directions to evaluate ``exprs`
so that the information “naturally flows” from an iteration to another.

devito.ir.support.utils.
force_directions
(mapper, key)[source]¶ Return a mapper
M : D > I
where D is the set ofDimension`s found in the input mapper ``M' : D > {I}`
, while I = {Any, Backward, Forward} (i.e., the set of possible :class:`IterationDirection`s).The iteration direction is chosen so that the information “naturally flows” from an iteration to another (i.e., to generate “flow” or “readafterwrite” dependencies).
In the case of a clash (e.g., both Forward and Backward should be used for a given dimension in order to have a flow dependence), the function
key : D > I
is used to pick one value.

devito.ir.support.utils.
group_expressions
(exprs)[source]¶ {exprs} > ({exprs'}, {exprs''}, ...)
where:* There are data dependences within exprs' and within exprs''; * There are *no* data dependencies across exprs' and exprs''.