devito package

Subpackages

Submodules

devito.backends module

The Devito backend configuration engine.

Warning

The backend should always be set via devito.init()

devito.backends.get_backend()[source]

Get the Devito backend.

devito.backends.init_backend(backend)[source]

Initialise Devito: select the backend and other configuration options.

devito.backends.initialised_backend()[source]

Check whether Devito has been yet initialised.

devito.backends.set_backend(backend)[source]

Set the Devito backend.

class devito.backends.void[source]

Bases: object

Dummy backend.

devito.base module

Metaclasses used to construct classes of proper backend type at runtime.

class devito.base.Array(*args, **kwargs)[source]

Bases: devito.types.Array

A symbolic function object, created and managed directly by Devito..

Parameters:
  • name – Name of the object.
  • dtype – Data type of the object.
  • dimensions – The symbolic dimensions of the object.
  • halo – The halo region of the object, expressed as an iterable [(dim1_left_halo, dim1_right_halo), (dim2_left_halo, ...)]
  • padding – The padding region of the object, expressed as an iterable [(dim1_left_pad, dim1_right_pad), (dim2_left_pad, ...)]
  • scope – (Optional) Control memory allocation. Allowed values are [‘heap’, ‘stack’, ‘external’]. Defaults to ‘heap’. ‘external’ implies that no storage needs to be allocated for the Array.
default_assumptions = {}
class devito.base.CacheManager[source]

Bases: devito.types.CacheManager

Drop unreferenced objects from the SymPy and Devito caches. The associated data is lost (and thus memory is freed).

default_assumptions = {}
is_algebraic
is_antihermitian
is_commutative
is_complex
is_composite
is_even
is_finite
is_hermitian
is_imaginary
is_infinite
is_integer
is_irrational
is_negative
is_noninteger
is_nonnegative
is_nonpositive
is_nonzero
is_odd
is_polar
is_positive
is_prime
is_rational
is_real
is_transcendental
is_zero
class devito.base.Constant(*args, **kwargs)[source]

Bases: devito.function.Constant

Symbol representing constant values in symbolic equations.

Note

The parameters must always be given as keyword arguments, since SymPy uses *args to (re-)create the dimension arguments of the symbolic function.

default_assumptions = {}
class devito.base.Function(*args, **kwargs)[source]

Bases: devito.function.Function

A TensorFunction providing operations to express finite-difference approximation. A Function encapsulates space-varying data; for time-varying data, use TimeFunction.

Parameters:
  • name – Name of the symbol
  • gridGrid object from which to infer the data shape and Dimension indices.
  • space_order – Discretisation order for space derivatives. By default, space_order points are available on both sides of a generic point of interest, including those on the grid border. Sometimes, fewer points may be necessary; in other cases, depending on the PDE being approximated, more points may be necessary. In such cases, one can pass a 3-tuple (o, lp, rp) instead of a single integer representing the discretization order. Here, o is the discretization order, while lp and rp indicate how many points are expected on left (lp) and right (rp) of a point of interest.
  • shape – (Optional) shape of the domain region in grid points.
  • dimensions – (Optional) symbolic dimensions that define the data layout and function indices of this symbol.
  • dtype – (Optional) data type of the buffered data.
  • staggered – (Optional) a Dimension, or a tuple of Dimension`s, or a :class:`Stagger, defining how the function is staggered. For example: * staggered=x entails discretization on x edges, * staggered=y entails discretization on y edges, * staggered=(x, y) entails discretization on xy facets, * staggered=NODE entails discretization on node, * staggerd=CELL entails discretization on cell.
  • padding – (Optional) allocate extra grid points at a space dimension boundary. These may be used for data alignment. Defaults to 0. In alternative to an integer, a tuple, indicating the padding in each dimension, may be passed; in this case, an error is raised if such tuple has fewer entries then the number of space dimensions.
  • initializer – (Optional) a callable or an object exposing buffer interface used to initialize the data. If a callable is provided, initialization is deferred until the first access to data.
  • allocator – (Optional) an object of type MemoryAllocator to specify where to allocate the function data when running on a NUMA architecture. Refer to default_allocator()’s __doc__ for more information about possible allocators.

Note

The parameters must always be given as keyword arguments, since SymPy uses *args to (re-)create the dimension arguments of the symbolic function.

Note

If the parameter grid is provided, the values for shape, dimensions and dtype will be derived from it.

Note

Function objects are assumed to be constant in time and therefore do not support time derivatives. Use TimeFunction for time-varying grid data.

default_assumptions = {}
class devito.base.Grid(shape, extent=None, origin=None, dimensions=None, time_dimension=None, dtype=<class 'numpy.float32'>, comm=None)[source]

Bases: devito.grid.Grid

A cartesian grid that encapsulates a physical domain over which to discretize :class:`Function`s.

Parameters:
  • shape – Shape of the domain region in grid points.
  • extent – (Optional) physical extent of the domain in m; defaults to a unit box of extent 1m in all dimensions.
  • origin – (Optional) physical coordinate of the origin of the domain; defaults to 0.0 in all dimensions.
  • dimensions – (Optional) list of SpaceDimension symbols that defines the spatial directions of the physical domain encapsulated by this Grid.
  • time_dimension – (Optional) TimeDimension symbols to to define the time dimension for all TimeFunction symbols created from this Grid.
  • dtype – (Optional) default data type to be inherited by all Function`s created from this :class:`Grid. Defaults to numpy.float32.
  • comm – (Optional) an MPI communicator defining the set of processes among which the grid is distributed.

The Grid encapsulates the topology and geometry information of the computational domain that Function objects can be discretized on. As such it defines and provides the physical coordinate information of the logically cartesian grid underlying the discretized Function objects. For example, the conventions for defining the coordinate space in 2D are:

Note

              x
    |----------------------->
    |  origin
    |     o------------o
    |     |            |
    |     |            |
    |     |   DOMAIN   | extent[1]
y   |     |            |
    |     |            |
    |     |  extent[0] |
    |     o------------o
    |             origin + extent
    |
    v
default_assumptions = {}
is_algebraic
is_antihermitian
is_commutative
is_complex
is_composite
is_even
is_finite
is_hermitian
is_imaginary
is_infinite
is_integer
is_irrational
is_negative
is_noninteger
is_nonnegative
is_nonpositive
is_nonzero
is_odd
is_polar
is_positive
is_prime
is_rational
is_real
is_transcendental
is_zero
class devito.base.Operator(expressions, **kwargs)[source]

Bases: devito.operator.Operator

A node representing a callable function.

Parameters:
  • name – The name of the callable.
  • body – A Node or an iterable of Node objects representing the body of the callable.
  • retval – The type of the value returned by the callable.
  • parameters – An iterable of AbstractFunction`s in input to the callable, or ``None` if the callable takes no parameter.
  • prefix – An iterable of qualifiers to prepend to the callable declaration. The default value is (‘static’, ‘inline’).
default_assumptions = {}
is_algebraic
is_antihermitian
is_commutative
is_complex
is_composite
is_even
is_finite
is_hermitian
is_imaginary
is_infinite
is_integer
is_irrational
is_negative
is_noninteger
is_nonnegative
is_nonpositive
is_nonzero
is_odd
is_polar
is_positive
is_prime
is_rational
is_real
is_transcendental
is_zero
class devito.base.PrecomputedSparseFunction(*args, **kwargs)[source]

Bases: devito.function.PrecomputedSparseFunction

A specialised type of SparseFunction where the interpolation is externally defined. Currently, this means that the grid points and associated coefficients for each sparse point is precomputed at the time this object is being created.

Parameters:
  • name – Name of the function.
  • npoint – Number of points to sample.
  • gridGrid object defining the computational domain.
  • r – The number of gridpoints in each dimension to interpolate a single sparse point to. e.g. 2 for linear interpolation.
  • gridpoints – The reference grid point corresponding to each sparse point. Of all the gridpoints that one sparse point would be interpolated to, this is the grid point closest to the origin, i.e. the one with the lowest value of each coordinate dimension. Must be a two-dimensional array of shape [npoint][grid.ndim].
  • coefficients – An array containing the coefficient for each of the r^2 (2D) or r^3 (3D) gridpoints that each sparsefunction will be interpolated to. The coefficient is split across the n dimensions such that the contribution of the point (i, j, k) will be multiplied by coefficients[…, i]*coefficients[…, j]*coefficients[…,k]. So for r=6, we will store 18 coefficients per sparse point (instead of potentially 216). Shape must be [npoint][grid.ndim][r].
  • space_order – (Optional) discretisation order for space derivatives. Default to 0.
  • time_order – (Optional) discretisation order for time derivatives. Default to 1.
  • shape – (Optional) shape of the function. Defaults to (nt, npoint,).
  • dimensions – (Optional) symbolic dimensions that define the data layout and function indices of this symbol.
  • dtype – (Optional) data type of the buffered data.
  • initializer – (Optional) a callable or an object exposing buffer interface used to initialize the data. If a callable is provided, initialization is deferred until the first access to data.

Note

The parameters must always be given as keyword arguments, since SymPy uses *args to (re-)create the dimension arguments of the symbolic function.

default_assumptions = {}
class devito.base.PrecomputedSparseTimeFunction(*args, **kwargs)[source]

Bases: devito.function.PrecomputedSparseTimeFunction

A specialised type of SparseFunction where the interpolation is externally defined. Currently, this means that the grid points and associated coefficients for each sparse point is precomputed at the time this object is being created.

Parameters:
  • name – Name of the function.
  • npoint – Number of points to sample.
  • gridGrid object defining the computational domain.
  • r – The number of gridpoints in each dimension to interpolate a single sparse point to. e.g. 2 for linear interpolation.
  • gridpoints – The reference grid point corresponding to each sparse point. Of all the gridpoints that one sparse point would be interpolated to, this is the grid point closest to the origin, i.e. the one with the lowest value of each coordinate dimension. Must be a two-dimensional array of shape [npoint][grid.ndim].
  • coefficients – An array containing the coefficient for each of the r^2 (2D) or r^3 (3D) gridpoints that each sparsefunction will be interpolated to. The coefficient is split across the n dimensions such that the contribution of the point (i, j, k) will be multiplied by coefficients[…, i]*coefficients[…, j]*coefficients[…,k]. So for r=6, we will store 18 coefficients per sparse point (instead of potentially 216). Shape must be [npoint][grid.ndim][r].
  • space_order – (Optional) discretisation order for space derivatives. Default to 0.
  • time_order – (Optional) discretisation order for time derivatives. Default to 1.
  • shape – (Optional) shape of the function. Defaults to (nt, npoint,).
  • dimensions – (Optional) symbolic dimensions that define the data layout and function indices of this symbol.
  • dtype – (Optional) data type of the buffered data.
  • initializer – (Optional) a callable or an object exposing buffer interface used to initialize the data. If a callable is provided, initialization is deferred until the first access to data.

Note

The parameters must always be given as keyword arguments, since SymPy uses *args to (re-)create the dimension arguments of the symbolic function.

default_assumptions = {}
class devito.base.Scalar(*args, **kwargs)[source]

Bases: devito.types.Scalar

Symbolic object representing a scalar.

Parameters:
  • name – Name of the symbol.
  • dtype – (Optional) data type of the object. Defaults to float32.
default_assumptions = {}
class devito.base.SparseFunction(*args, **kwargs)[source]

Bases: devito.function.SparseFunction

A special TensorFunction representing a set of sparse point objects that are not aligned with the computational grid.

A SparseFunction provides symbolic interpolation routines to convert between grid-aligned Function objects and sparse data points. These are based upon standard [bi,tri]linear interpolation.

Parameters:
  • name – Name of the function.
  • npoint – Number of points to sample.
  • gridGrid object defining the computational domain.
  • coordinates – (Optional) coordinate data for the sparse points.
  • space_order – (Optional) discretisation order for space derivatives.
  • shape – (Optional) shape of the function. Defaults to (npoint,).
  • dimensions – (Optional) symbolic dimensions that define the data layout and function indices of this symbol.
  • dtype – (Optional) data type of the buffered data.
  • initializer – (Optional) a callable or an object exposing buffer interface used to initialize the data. If a callable is provided, initialization is deferred until the first access to data.
  • allocator – (Optional) an object of type MemoryAllocator to specify where to allocate the function data when running on a NUMA architecture. Refer to default_allocator()’s __doc__ for more information about possible allocators.

Note

The parameters must always be given as keyword arguments, since SymPy uses *args to (re-)create the dimension arguments of the symbolic function.

default_assumptions = {}
class devito.base.SparseTimeFunction(*args, **kwargs)[source]

Bases: devito.function.SparseTimeFunction

A time-dependent SparseFunction.

Parameters:
  • name – Name of the function.
  • nt – Size of the time dimension for point data.
  • npoint – Number of points to sample.
  • gridGrid object defining the computational domain.
  • coordinates – (Optional) coordinate data for the sparse points.
  • space_order – (Optional) discretisation order for space derivatives. Default to 0.
  • time_order – (Optional) discretisation order for time derivatives. Default to 1.
  • shape – (Optional) shape of the function. Defaults to (nt, npoint,).
  • dimensions – (Optional) symbolic dimensions that define the data layout and function indices of this symbol.
  • dtype – (Optional) Data type of the buffered data.
  • initializer – (Optional) a callable or an object exposing buffer interface used to initialize the data. If a callable is provided, initialization is deferred until the first access to data.
  • allocator – (Optional) an object of type MemoryAllocator to specify where to allocate the function data when running on a NUMA architecture. Refer to default_allocator()’s __doc__ for more information about possible allocators.

Note

The parameters must always be given as keyword arguments, since SymPy uses *args to (re-)create the dimension arguments of the symbolic function.

default_assumptions = {}
class devito.base.TimeFunction(*args, **kwargs)[source]

Bases: devito.function.TimeFunction

A special Function encapsulating time-varying data.

Parameters:
  • name – Name of the resulting sympy.Function symbol
  • gridGrid object from which to infer the data shape and Dimension indices.
  • space_order – Discretisation order for space derivatives. By default, space_order points are available on both sides of a generic point of interest, including those on the grid border. Sometimes, fewer points may be necessary; in other cases, depending on the PDE being approximated, more points may be necessary. In such cases, one can pass a 3-tuple (o, lp, rp) instead of a single integer representing the discretization order. Here, o is the discretization order, while lp and rp indicate how many points are expected on left (lp) and right (rp) of a point of interest.
  • time_order – Discretization order for time derivatives.
  • shape – (Optional) shape of the domain region in grid points.
  • dimensions – (Optional) symbolic dimensions that define the data layout and function indices of this symbol.
  • dtype – (Optional) data type of the buffered data.
  • save – (Optional) defaults to None, which indicates the use of alternating buffers. This enables cyclic writes to the TimeFunction. For example, if the TimeFunction u(t, x) has shape (3, 100), then, in an Operator, t will assume the values 1, 2, 0, 1, 2, 0, 1, ... (note that the very first value depends on the stencil equation in which u is written.). The default size of the time buffer when save=None is time_order + 1. To specify a different size for the time buffer, one should use the syntax save=Buffer(mysize). Alternatively, if all of the intermediate results are required (or, simply, to forbid the usage of an alternating buffer), an explicit value for save (i.e., an integer) must be provided.
  • time_dim – (Optional) the Dimension object to use to represent time in this symbol. Defaults to the time dimension provided by the Grid.
  • staggered – (Optional) a Dimension, or a tuple of Dimension`s, or a :class:`Stagger, defining how the function is staggered. For example: * staggered=x entails discretization on x edges, * staggered=y entails discretization on y edges, * staggered=(x, y) entails discretization on xy facets, * staggered=NODE entails discretization on node, * staggerd=CELL entails discretization on cell.
  • padding – (Optional) allocate extra grid points at a space dimension boundary. These may be used for data alignment. Defaults to 0. In alternative to an integer, a tuple, indicating the padding in each dimension, may be passed; in this case, an error is raised if such tuple has fewer entries then the number of space dimensions.
  • initializer – (Optional) a callable or an object exposing buffer interface used to initialize the data. If a callable is provided, initialization is deferred until the first access to data.
  • allocator – (Optional) an object of type MemoryAllocator to specify where to allocate the function data when running on a NUMA architecture. Refer to default_allocator()’s __doc__ for more information about possible allocators.

Note

The parameters must always be given as keyword arguments, since SymPy uses *args to (re-)create the dimension arguments of the symbolic function.

Note

If the parameter grid is provided, the values for shape, dimensions and dtype will be derived from it.

The parameter shape should only define the spatial shape of the grid. The temporal dimension will be inserted automatically as the leading dimension, according to the time_dim, time_order and whether we want to write intermediate timesteps in the buffer. The same is true for explicitly provided dimensions, which will be added to the automatically derived time dimensions symbol. For example:

In []: TimeFunction(name="a", dimensions=(x, y, z))
Out[]: a(t, x, y, z)

In []: TimeFunction(name="a", shape=(20, 30))
Out[]: a(t, x, y)
default_assumptions = {}

devito.cgen_utils module

class devito.cgen_utils.Allocator[source]

Bases: object

Generate C strings to declare pointers, allocate and free memory.

onheap
onstack
push_heap(obj)[source]

Generate cgen objects to declare, allocate memory, and free memory for obj, of type Array.

push_stack(scope, obj)[source]

Generate a cgen statement that allocates obj on the stack.

class devito.cgen_utils.CodePrinter(dtype=<class 'numpy.float32'>, settings={})[source]

Bases: sympy.printing.ccode.C99CodePrinter

custom_functions = {'DOUBLE': '(double)', 'FLOAT': '(float)', 'INT': '(int)'}

Decorator for sympy.printing.ccode.CCodePrinter.

Parameters:settings – A dictionary containing relevant settings
class devito.cgen_utils.DOUBLE

Bases: sympy.core.function.AppliedUndef

default_assumptions = {}
class devito.cgen_utils.FLOAT

Bases: sympy.core.function.AppliedUndef

default_assumptions = {}
devito.cgen_utils.FLOOR

alias of floor

class devito.cgen_utils.INT

Bases: sympy.core.function.AppliedUndef

default_assumptions = {}
devito.cgen_utils.ccode(expr, dtype=<class 'numpy.float32'>, **settings)[source]

Generate C++ code from an expression calling CodePrinter class

Parameters:
  • expr – The expression
  • settings – A dictionary of settings for code printing
Returns:

The resulting code as a string. If it fails, then it returns the expr

devito.cgen_utils.printmark(i)
devito.cgen_utils.printvar(i)

devito.compiler module

devito.compiler.jit_compile(soname, code, compiler)[source]

JIT compile the given C/C++ code.

This function relies upon codepy’s compile_from_string, which performs caching of compilation units and avoids potential race conditions due to multiple processing trying to compile the same object.

Parameters:
  • soname – A unique name for the jit-compiled shared object.
  • code – String of C source code.
  • compiler – The toolchain used for compilation.
devito.compiler.load(soname)[source]

Load a compiled shared object.

Parameters:soname – Name of the .so file (w/o the suffix).
Returns:The loaded shared object.
devito.compiler.make(loc, args)[source]

Invoke make command from within loc with arguments args.

class devito.compiler.GNUCompiler(*args, **kwargs)[source]

Bases: devito.compiler.Compiler

Set of standard compiler flags for the GCC toolchain.

CC = 'gcc'
CPP = 'g++'
MPICC = 'mpicc'
MPICXX = 'mpicxx'

devito.data module

devito.dimension module

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

Bases: devito.types.AbstractSymbol, devito.tools.abc.ArgProvider

base
default_assumptions = {}
dtype
is_Conditional = False
is_Default = False
is_Derived = False
is_Dimension = True
is_NonlinearDerived = False
is_Space = False
is_Stepping = False

A Dimension is a symbol representing a problem dimension and thus defining a potential iteration space.

Parameters:
  • name – Name of the dimension symbol.
  • spacing – Optional, symbol for the spacing along this dimension.
is_Sub = False
is_Time = False
limits
max_name
min_name
root
size_name
spacing
symbolic_end

The symbol defining the iteration end for this dimension.

symbolic_size

The symbolic size of this dimension.

symbolic_start

The symbol defining the iteration start for this dimension.

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

Bases: devito.dimension.Dimension

default_assumptions = {}
is_Space = True

Dimension symbol to represent a space dimension that defines the extent of physical grid. SpaceDimensions create dedicated shortcut notations for spatial derivatives on Function symbols.

Parameters:
  • name – Name of the dimension symbol.
  • spacing – Optional, symbol for the spacing along this dimension.
class devito.dimension.TimeDimension(*args, **kwargs)[source]

Bases: devito.dimension.Dimension

default_assumptions = {}
is_Time = True

Dimension symbol to represent a dimension that defines the extent of time. As time might be used in different contexts, all derived time dimensions should inherit from TimeDimension.

Parameters:
  • name – Name of the dimension symbol.
  • spacing – Optional, symbol for the spacing along this dimension.
class devito.dimension.DefaultDimension(*args, **kwargs)[source]

Bases: devito.dimension.Dimension

default_assumptions = {}
is_Default = True

Dimension symbol to represent a dimension that has a statically-known size.

Note

A DefaultDimension carries a value, so it has a mutable state. Hence, it is not cached.

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

Bases: devito.dimension.DerivedDimension

default_assumptions = {}
is_NonlinearDerived = True
is_Stepping = True

Dimension symbol that defines the stepping direction of an Operator and implies modulo buffered iteration. This is most commonly use to represent a timestepping dimension.

Parameters:
  • name – Name of the dimension symbol.
  • parent – Parent dimension over which to loop in modulo fashion.
symbolic_end

The symbol defining the iteration end for this dimension.

symbolic_start

The symbol defining the iteration start for this dimension.

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

Bases: devito.dimension.DerivedDimension

class Thickness(left, right)

Bases: tuple

left

Alias for field number 0

right

Alias for field number 1

default_assumptions = {}
is_Sub = True

Dimension symbol representing a contiguous sub-region of a given parent Dimension.

Parameters:
  • name – Name of the dimension symbol.
  • parent – Parent dimension from which the SubDimension is created.
  • left – Symbolic expression to provide the left bound.
  • right – Symbolic expression to provide the right bound.
  • thickness – A 2-tuple of 2-tuples, ((symbol, int), (symbol, int)), representing the thickness of the left and right regions, respectively.
classmethod left(name, parent, thickness)[source]
classmethod middle(name, parent, thickness_left, thickness_right)[source]
offset_left()[source]
offset_right()[source]
classmethod right(name, parent, thickness)[source]
symbolic_end

The symbol defining the iteration end for this dimension.

symbolic_start

The symbol defining the iteration start for this dimension.

classmethod symbolic_thickness(name)[source]
thickness
thickness_map
class devito.dimension.ConditionalDimension(*args, **kwargs)[source]

Bases: devito.dimension.DerivedDimension

condition
default_assumptions = {}
factor

See the factor() function in sympy.polys.polytools

index
indirect
is_Conditional = True

Dimension symbol representing a sub-region of a given parent Dimension. Unlike a SubDimension, a ConditionalDimension does not represent a contiguous region. The iterations touched by a ConditionalDimension are expressible in two different ways:

* ``factor``: an integer indicating the size of the increment.
* ``condition``: an arbitrary SymPy expression depending on ``parent``.
                 All iterations for which the expression evaluates to
                 True are part of the ``ConditionalDimension`` region.

ConditionalDimension needs runtime arguments. The generated C code will require the size of the dimension to initialize the arrays as e.g:

Note

Sometimes the ConditionalDimension itself, rather than its parent, needs to be used to index into an array. For example, this may happen when an array is indirectly addressed and the ConditionalDimension’s parent doesn’t define an affine iteration space. In such a case, one should create the ConditionalDimension with the flag indirect=True.

is_NonlinearDerived = True
spacing
devito.dimension.dimensions(names)[source]

Shortcut for:

dimensions('i j k') -> [Dimension('i'), Dimension('j'), Dimension('k')]

devito.equation module

User API to specify equations.

class devito.equation.Eq[source]

Bases: sympy.core.relational.Equality

A sympy.Eq that accepts the additional keyword parameter region.

The region, an object of type Region, may be used to restrict the execution of the equation to a sub-domain.

default_assumptions = {}
is_Increment = False
xreplace(rules)[source]

Replace occurrences of objects within the expression.

rule : dict-like
Expresses a replacement rule

xreplace : the result of the replacement

>>> from sympy import symbols, pi, exp
>>> x, y, z = symbols('x y z')
>>> (1 + x*y).xreplace({x: pi})
pi*y + 1
>>> (1 + x*y).xreplace({x: pi, y: 2})
1 + 2*pi

Replacements occur only if an entire node in the expression tree is matched:

>>> (x*y + z).xreplace({x*y: pi})
z + pi
>>> (x*y*z).xreplace({x*y: pi})
x*y*z
>>> (2*x).xreplace({2*x: y, x: z})
y
>>> (2*2*x).xreplace({2*x: y, x: z})
4*z
>>> (x + y + 2).xreplace({x + y: 2})
x + y + 2
>>> (x + 2 + exp(x + 2)).xreplace({x + 2: y})
x + exp(y) + 2

xreplace doesn’t differentiate between free and bound symbols. In the following, subs(x, y) would not change x since it is a bound symbol, but xreplace does:

>>> from sympy import Integral
>>> Integral(x, (x, 1, 2*x)).xreplace({x: y})
Integral(y, (y, 1, 2*y))

Trying to replace x with an expression raises an error:

>>> Integral(x, (x, 1, 2*x)).xreplace({x: 2*y}) 
ValueError: Invalid limits given: ((2*y, 1, 4*y),)
replace: replacement capable of doing wildcard-like matching,
parsing of match, and conditional replacements
subs: substitution of subexpressions as defined by the objects
themselves.
class devito.equation.Inc[source]

Bases: devito.equation.Eq

A Eq performing a linear increment.

default_assumptions = {}
is_Increment = True
devito.equation.DOMAIN = DOMAIN

Represent the physical domain of the PDE; that is, domain = boundary + interior

devito.equation.INTERIOR = INTERIOR

Represent the physical interior domain of the PDE; that is, PDE boundaries are not included.

devito.equation.solve(expr, target, **kwargs)[source]

Algebraically rearrange an equation w.r.t. a given symbol.

This is a wrapper around sympy.solve.

Parameters:
  • eq – The sympy.Eq to be rearranged.
  • target – The symbol w.r.t. which the equation is rearranged.
  • kwargs – (Optional) Symbolic optimizations applied while rearranging the equation. For more information. refer to sympy.solve.__doc__.

devito.exceptions module

exception devito.exceptions.CompilationError[source]

Bases: devito.exceptions.DevitoError

exception devito.exceptions.DLEException[source]

Bases: devito.exceptions.DevitoError

exception devito.exceptions.DSEException[source]

Bases: devito.exceptions.DevitoError

exception devito.exceptions.DevitoError[source]

Bases: Exception

exception devito.exceptions.InvalidArgument[source]

Bases: devito.exceptions.DevitoError

exception devito.exceptions.InvalidOperator[source]

Bases: devito.exceptions.DevitoError

exception devito.exceptions.VisitorException[source]

Bases: devito.exceptions.DevitoError

devito.function module

class devito.function.Constant(*args, **kwargs)[source]

Bases: devito.types.AbstractCachedSymbol, devito.tools.abc.ArgProvider

Symbol representing constant values in symbolic equations.

Note

The parameters must always be given as keyword arguments, since SymPy uses *args to (re-)create the dimension arguments of the symbolic function.

data

The value of the data object, as a scalar (int, float, …).

default_assumptions = {}
is_Constant = True
is_Input = True
is_Scalar = True
class devito.function.Function(*args, **kwargs)[source]

Bases: devito.function.TensorFunction, devito.finite_differences.differentiable.Differentiable

A TensorFunction providing operations to express finite-difference approximation. A Function encapsulates space-varying data; for time-varying data, use TimeFunction.

Parameters:
  • name – Name of the symbol
  • gridGrid object from which to infer the data shape and Dimension indices.
  • space_order – Discretisation order for space derivatives. By default, space_order points are available on both sides of a generic point of interest, including those on the grid border. Sometimes, fewer points may be necessary; in other cases, depending on the PDE being approximated, more points may be necessary. In such cases, one can pass a 3-tuple (o, lp, rp) instead of a single integer representing the discretization order. Here, o is the discretization order, while lp and rp indicate how many points are expected on left (lp) and right (rp) of a point of interest.
  • shape – (Optional) shape of the domain region in grid points.
  • dimensions – (Optional) symbolic dimensions that define the data layout and function indices of this symbol.
  • dtype – (Optional) data type of the buffered data.
  • staggered – (Optional) a Dimension, or a tuple of Dimension`s, or a :class:`Stagger, defining how the function is staggered. For example: * staggered=x entails discretization on x edges, * staggered=y entails discretization on y edges, * staggered=(x, y) entails discretization on xy facets, * staggered=NODE entails discretization on node, * staggerd=CELL entails discretization on cell.
  • padding – (Optional) allocate extra grid points at a space dimension boundary. These may be used for data alignment. Defaults to 0. In alternative to an integer, a tuple, indicating the padding in each dimension, may be passed; in this case, an error is raised if such tuple has fewer entries then the number of space dimensions.
  • initializer – (Optional) a callable or an object exposing buffer interface used to initialize the data. If a callable is provided, initialization is deferred until the first access to data.
  • allocator – (Optional) an object of type MemoryAllocator to specify where to allocate the function data when running on a NUMA architecture. Refer to default_allocator()’s __doc__ for more information about possible allocators.

Note

The parameters must always be given as keyword arguments, since SymPy uses *args to (re-)create the dimension arguments of the symbolic function.

Note

If the parameter grid is provided, the values for shape, dimensions and dtype will be derived from it.

Note

Function objects are assumed to be constant in time and therefore do not support time derivatives. Use TimeFunction for time-varying grid data.

avg(p=None, dims=None)[source]

Generate a symbolic expression computing the average of p points along the spatial dimensions dims.

Parameters:
  • p – (Optional) the number of summands. Defaults to the halo extent.
  • dims – (Optional) the Dimension`s along which the sum is computed. Defaults to ``self`’s spatial dimensions.
default_assumptions = {}
is_Function = True
space_order
sum(p=None, dims=None)[source]

Generate a symbolic expression computing the sum of p points along the spatial dimensions dims.

Parameters:
  • p – (Optional) the number of summands. Defaults to the halo extent.
  • dims – (Optional) the Dimension`s along which the sum is computed. Defaults to ``self`’s spatial dimensions.
class devito.function.TimeFunction(*args, **kwargs)[source]

Bases: devito.function.Function

A special Function encapsulating time-varying data.

Parameters:
  • name – Name of the resulting sympy.Function symbol
  • gridGrid object from which to infer the data shape and Dimension indices.
  • space_order – Discretisation order for space derivatives. By default, space_order points are available on both sides of a generic point of interest, including those on the grid border. Sometimes, fewer points may be necessary; in other cases, depending on the PDE being approximated, more points may be necessary. In such cases, one can pass a 3-tuple (o, lp, rp) instead of a single integer representing the discretization order. Here, o is the discretization order, while lp and rp indicate how many points are expected on left (lp) and right (rp) of a point of interest.
  • time_order – Discretization order for time derivatives.
  • shape – (Optional) shape of the domain region in grid points.
  • dimensions – (Optional) symbolic dimensions that define the data layout and function indices of this symbol.
  • dtype – (Optional) data type of the buffered data.
  • save – (Optional) defaults to None, which indicates the use of alternating buffers. This enables cyclic writes to the TimeFunction. For example, if the TimeFunction u(t, x) has shape (3, 100), then, in an Operator, t will assume the values 1, 2, 0, 1, 2, 0, 1, ... (note that the very first value depends on the stencil equation in which u is written.). The default size of the time buffer when save=None is time_order + 1. To specify a different size for the time buffer, one should use the syntax save=Buffer(mysize). Alternatively, if all of the intermediate results are required (or, simply, to forbid the usage of an alternating buffer), an explicit value for save (i.e., an integer) must be provided.
  • time_dim – (Optional) the Dimension object to use to represent time in this symbol. Defaults to the time dimension provided by the Grid.
  • staggered – (Optional) a Dimension, or a tuple of Dimension`s, or a :class:`Stagger, defining how the function is staggered. For example: * staggered=x entails discretization on x edges, * staggered=y entails discretization on y edges, * staggered=(x, y) entails discretization on xy facets, * staggered=NODE entails discretization on node, * staggerd=CELL entails discretization on cell.
  • padding – (Optional) allocate extra grid points at a space dimension boundary. These may be used for data alignment. Defaults to 0. In alternative to an integer, a tuple, indicating the padding in each dimension, may be passed; in this case, an error is raised if such tuple has fewer entries then the number of space dimensions.
  • initializer – (Optional) a callable or an object exposing buffer interface used to initialize the data. If a callable is provided, initialization is deferred until the first access to data.
  • allocator – (Optional) an object of type MemoryAllocator to specify where to allocate the function data when running on a NUMA architecture. Refer to default_allocator()’s __doc__ for more information about possible allocators.

Note

The parameters must always be given as keyword arguments, since SymPy uses *args to (re-)create the dimension arguments of the symbolic function.

Note

If the parameter grid is provided, the values for shape, dimensions and dtype will be derived from it.

The parameter shape should only define the spatial shape of the grid. The temporal dimension will be inserted automatically as the leading dimension, according to the time_dim, time_order and whether we want to write intermediate timesteps in the buffer. The same is true for explicitly provided dimensions, which will be added to the automatically derived time dimensions symbol. For example:

In []: TimeFunction(name="a", dimensions=(x, y, z))
Out[]: a(t, x, y, z)

In []: TimeFunction(name="a", shape=(20, 30))
Out[]: a(t, x, y)
backward

Symbol for the time-backward state of the function

default_assumptions = {}
forward

Symbol for the time-forward state of the function

is_TimeFunction = True
time_order
class devito.function.SparseFunction(*args, **kwargs)[source]

Bases: devito.function.AbstractSparseFunction, devito.finite_differences.differentiable.Differentiable

A special TensorFunction representing a set of sparse point objects that are not aligned with the computational grid.

A SparseFunction provides symbolic interpolation routines to convert between grid-aligned Function objects and sparse data points. These are based upon standard [bi,tri]linear interpolation.

Parameters:
  • name – Name of the function.
  • npoint – Number of points to sample.
  • gridGrid object defining the computational domain.
  • coordinates – (Optional) coordinate data for the sparse points.
  • space_order – (Optional) discretisation order for space derivatives.
  • shape – (Optional) shape of the function. Defaults to (npoint,).
  • dimensions – (Optional) symbolic dimensions that define the data layout and function indices of this symbol.
  • dtype – (Optional) data type of the buffered data.
  • initializer – (Optional) a callable or an object exposing buffer interface used to initialize the data. If a callable is provided, initialization is deferred until the first access to data.
  • allocator – (Optional) an object of type MemoryAllocator to specify where to allocate the function data when running on a NUMA architecture. Refer to default_allocator()’s __doc__ for more information about possible allocators.

Note

The parameters must always be given as keyword arguments, since SymPy uses *args to (re-)create the dimension arguments of the symbolic function.

coordinates
coordinates_data
default_assumptions = {}
gridpoints

The reference grid point corresponding to each sparse point.

inject(field, expr, offset=0)[source]

Symbol for injection of an expression onto a grid

Parameters:
  • field – The grid field into which we inject.
  • expr – The expression to inject.
  • offset – Additional offset from the boundary for absorbing boundary conditions.
interpolate(expr, offset=0, increment=False, self_subs={})[source]

Creates a sympy.Eq equation for the interpolation of an expression onto this sparse point collection.

Parameters:
  • expr – The expression to interpolate.
  • offset – Additional offset from the boundary for absorbing boundary conditions.
  • increment – (Optional) if True, perform an increment rather than an assignment. Defaults to False.
is_SparseFunction = True
class devito.function.SparseTimeFunction(*args, **kwargs)[source]

Bases: devito.function.AbstractSparseTimeFunction, devito.function.SparseFunction

A time-dependent SparseFunction.

Parameters:
  • name – Name of the function.
  • nt – Size of the time dimension for point data.
  • npoint – Number of points to sample.
  • gridGrid object defining the computational domain.
  • coordinates – (Optional) coordinate data for the sparse points.
  • space_order – (Optional) discretisation order for space derivatives. Default to 0.
  • time_order – (Optional) discretisation order for time derivatives. Default to 1.
  • shape – (Optional) shape of the function. Defaults to (nt, npoint,).
  • dimensions – (Optional) symbolic dimensions that define the data layout and function indices of this symbol.
  • dtype – (Optional) Data type of the buffered data.
  • initializer – (Optional) a callable or an object exposing buffer interface used to initialize the data. If a callable is provided, initialization is deferred until the first access to data.
  • allocator – (Optional) an object of type MemoryAllocator to specify where to allocate the function data when running on a NUMA architecture. Refer to default_allocator()’s __doc__ for more information about possible allocators.

Note

The parameters must always be given as keyword arguments, since SymPy uses *args to (re-)create the dimension arguments of the symbolic function.

default_assumptions = {}
inject(field, expr, offset=0, u_t=None, p_t=None)[source]

Symbol for injection of an expression onto a grid

Parameters:
  • field – The grid field into which we inject.
  • expr – The expression to inject.
  • offset – Additional offset from the boundary for absorbing boundary conditions.
  • u_t – (Optional) time index to use for indexing into field.
  • p_t – (Optional) time index to use for indexing into expr.
interpolate(expr, offset=0, u_t=None, p_t=None, increment=False)[source]

Creates a sympy.Eq equation for the interpolation of an expression onto this sparse point collection.

Parameters:
  • expr – The expression to interpolate.
  • offset – Additional offset from the boundary for absorbing boundary conditions.
  • u_t – (Optional) time index to use for indexing into field data in expr.
  • p_t – (Optional) time index to use for indexing into the sparse point data.
  • increment – (Optional) if True, perform an increment rather than an assignment. Defaults to False.
is_SparseTimeFunction = True
class devito.function.PrecomputedSparseFunction(*args, **kwargs)[source]

Bases: devito.function.AbstractSparseFunction

A specialised type of SparseFunction where the interpolation is externally defined. Currently, this means that the grid points and associated coefficients for each sparse point is precomputed at the time this object is being created.

Parameters:
  • name – Name of the function.
  • npoint – Number of points to sample.
  • gridGrid object defining the computational domain.
  • r – The number of gridpoints in each dimension to interpolate a single sparse point to. e.g. 2 for linear interpolation.
  • gridpoints – The reference grid point corresponding to each sparse point. Of all the gridpoints that one sparse point would be interpolated to, this is the grid point closest to the origin, i.e. the one with the lowest value of each coordinate dimension. Must be a two-dimensional array of shape [npoint][grid.ndim].
  • coefficients – An array containing the coefficient for each of the r^2 (2D) or r^3 (3D) gridpoints that each sparsefunction will be interpolated to. The coefficient is split across the n dimensions such that the contribution of the point (i, j, k) will be multiplied by coefficients[…, i]*coefficients[…, j]*coefficients[…,k]. So for r=6, we will store 18 coefficients per sparse point (instead of potentially 216). Shape must be [npoint][grid.ndim][r].
  • space_order – (Optional) discretisation order for space derivatives. Default to 0.
  • time_order – (Optional) discretisation order for time derivatives. Default to 1.
  • shape – (Optional) shape of the function. Defaults to (nt, npoint,).
  • dimensions – (Optional) symbolic dimensions that define the data layout and function indices of this symbol.
  • dtype – (Optional) data type of the buffered data.
  • initializer – (Optional) a callable or an object exposing buffer interface used to initialize the data. If a callable is provided, initialization is deferred until the first access to data.

Note

The parameters must always be given as keyword arguments, since SymPy uses *args to (re-)create the dimension arguments of the symbolic function.

coefficients
default_assumptions = {}
gridpoints

The reference grid point corresponding to each sparse point.

inject(field, expr, offset=0, u_t=None, p_t=None)[source]

Symbol for injection of an expression onto a grid

Parameters:
  • field – The grid field into which we inject.
  • expr – The expression to inject.
  • offset – Additional offset from the boundary for absorbing boundary conditions.
  • u_t – (Optional) time index to use for indexing into field.
  • p_t – (Optional) time index to use for indexing into expr.
interpolate(expr, offset=0, u_t=None, p_t=None, increment=False)[source]

Creates a sympy.Eq equation for the interpolation of an expression onto this sparse point collection.

Parameters:
  • expr – The expression to interpolate.
  • offset – Additional offset from the boundary for absorbing boundary conditions.
  • u_t – (Optional) time index to use for indexing into field data in expr.
  • p_t – (Optional) time index to use for indexing into the sparse point data.
  • increment – (Optional) if True, perform an increment rather than an assignment. Defaults to False.
is_PrecomputedSparseFunction = True
class devito.function.PrecomputedSparseTimeFunction(*args, **kwargs)[source]

Bases: devito.function.AbstractSparseTimeFunction, devito.function.PrecomputedSparseFunction

A specialised type of SparseFunction where the interpolation is externally defined. Currently, this means that the grid points and associated coefficients for each sparse point is precomputed at the time this object is being created.

Parameters:
  • name – Name of the function.
  • npoint – Number of points to sample.
  • gridGrid object defining the computational domain.
  • r – The number of gridpoints in each dimension to interpolate a single sparse point to. e.g. 2 for linear interpolation.
  • gridpoints – The reference grid point corresponding to each sparse point. Of all the gridpoints that one sparse point would be interpolated to, this is the grid point closest to the origin, i.e. the one with the lowest value of each coordinate dimension. Must be a two-dimensional array of shape [npoint][grid.ndim].
  • coefficients – An array containing the coefficient for each of the r^2 (2D) or r^3 (3D) gridpoints that each sparsefunction will be interpolated to. The coefficient is split across the n dimensions such that the contribution of the point (i, j, k) will be multiplied by coefficients[…, i]*coefficients[…, j]*coefficients[…,k]. So for r=6, we will store 18 coefficients per sparse point (instead of potentially 216). Shape must be [npoint][grid.ndim][r].
  • space_order – (Optional) discretisation order for space derivatives. Default to 0.
  • time_order – (Optional) discretisation order for time derivatives. Default to 1.
  • shape – (Optional) shape of the function. Defaults to (nt, npoint,).
  • dimensions – (Optional) symbolic dimensions that define the data layout and function indices of this symbol.
  • dtype – (Optional) data type of the buffered data.
  • initializer – (Optional) a callable or an object exposing buffer interface used to initialize the data. If a callable is provided, initialization is deferred until the first access to data.

Note

The parameters must always be given as keyword arguments, since SymPy uses *args to (re-)create the dimension arguments of the symbolic function.

default_assumptions = {}
is_PrecomputedSparseTimeFunction = True
class devito.function.Buffer(value)[source]

Bases: devito.tools.abc.Tag

devito.grid module

class devito.grid.Grid(shape, extent=None, origin=None, dimensions=None, time_dimension=None, dtype=<class 'numpy.float32'>, comm=None)[source]

Bases: devito.tools.abc.ArgProvider

A cartesian grid that encapsulates a physical domain over which to discretize :class:`Function`s.

Parameters:
  • shape – Shape of the domain region in grid points.
  • extent – (Optional) physical extent of the domain in m; defaults to a unit box of extent 1m in all dimensions.
  • origin – (Optional) physical coordinate of the origin of the domain; defaults to 0.0 in all dimensions.
  • dimensions – (Optional) list of SpaceDimension symbols that defines the spatial directions of the physical domain encapsulated by this Grid.
  • time_dimension – (Optional) TimeDimension symbols to to define the time dimension for all TimeFunction symbols created from this Grid.
  • dtype – (Optional) default data type to be inherited by all Function`s created from this :class:`Grid. Defaults to numpy.float32.
  • comm – (Optional) an MPI communicator defining the set of processes among which the grid is distributed.

The Grid encapsulates the topology and geometry information of the computational domain that Function objects can be discretized on. As such it defines and provides the physical coordinate information of the logically cartesian grid underlying the discretized Function objects. For example, the conventions for defining the coordinate space in 2D are:

Note

              x
    |----------------------->
    |  origin
    |     o------------o
    |     |            |
    |     |            |
    |     |   DOMAIN   | extent[1]
y   |     |            |
    |     |            |
    |     |  extent[0] |
    |     o------------o
    |             origin + extent
    |
    v
dim

Problem dimension, or number of spatial dimensions.

dimension_map

Map between self’s SpaceDimension and their global and local size.

distributor

The Distributor used for domain decomposition.

is_distributed(dim)[source]

Return True if dim is a distributed Dimension, False otherwise.

origin_domain

Origin of the local (per-process) physical domain.

shape

Shape of the physical domain.

shape_domain

Shape of the local (per-process) physical domain.

spacing

Spacing between grid points in m.

spacing_map

Map between spacing symbols and their values for each SpaceDimension

spacing_symbols

Symbols representing the grid spacing in each SpaceDimension

volume_cell

Volume of a single cell e.g h_x*h_y*h_z in 3D

devito.logger module

The Devito logger.

devito.logger.set_log_level(level, comm=None)[source]

Set the log level of the Devito logger.

Parameters:
  • level – Accepted values are: DEBUG, PERF, INFO, DSE, DSE_WARN, DLE, DLE_WARN, WARNING, ERROR, CRITICAL.
  • comm – An MPI communicator the logger should be collective over. If provided, only rank-0 on that communicator will write to the registered handlers, other ranks will use a logging.NullHandler. By default, comm is set to None, so all ranks will use the default handlers. This could be used, for example, if one wants to log to one file per rank.
devito.logger.set_log_noperf()[source]

Do not print performance-related messages.

class devito.logger.silencio(log_level='WARNING')[source]

Bases: object

Decorator to temporarily change log levels.

devito.logger.log(msg, level=20, *args, **kwargs)[source]

Wrapper of the main Python’s logging function. Print ‘msg % args’ with the severity ‘level’.

Parameters:
  • msg – the message to be printed.
  • level – accepted values are: DEBUG, YASK, YASK_WARN, PERF, INFO, DSE, DSE_WARN, DLE, DLE_WARN, WARNING, ERROR, CRITICAL.
devito.logger.warning(msg, *args, **kwargs)[source]
devito.logger.error(msg, *args, **kwargs)[source]
devito.logger.perf(msg, *args, **kwargs)[source]
devito.logger.perf_adv(msg, *args, **kwargs)[source]
devito.logger.dse(msg, *args, **kwargs)[source]
devito.logger.dse_warning(msg, *args, **kwargs)[source]
devito.logger.dle(msg, *args, **kwargs)[source]
devito.logger.dle_warning(msg, *args, **kwargs)[source]

devito.operator module

class devito.operator.Operator(expressions, **kwargs)[source]

Bases: devito.ir.iet.nodes.Callable

arguments(**kwargs)[source]
cfunction

Returns the JIT-compiled C function as a ctypes.FuncPtr object.

elemental_functions
class devito.operator.OperatorRunnable(expressions, **kwargs)[source]

Bases: devito.operator.Operator

A special Operator that, besides generation and compilation of C code evaluating stencil expressions, can also execute the computation.

apply(**kwargs)[source]

Run the operator.

Without additional parameters specified, the operator runs on the same data objects used to build it – the so called default arguments.

Optionally, any of the operator default arguments may be replaced by passing suitable key-value parameters. Given apply(k=v, ...), (k, v) may be used to:

* replace a constant (scalar) used by the operator. In this case,
    ``k`` is the name of the constant; ``v`` is either an object
    of type :class:`Constant` or an actual scalar value.
* replace a function (tensor) used by the operator. In this case,
    ``k`` is the name of the function; ``v`` is either an object
    of type :class:`TensorFunction` or a :class:`numpy.ndarray`.
* alter the iteration interval along a given :class:`Dimension`
    ``d``, which represents a subset of the operator iteration space.
    By default, the operator runs over all iterations within the
    compact interval ``[d_m, d_M]``, in which ``d_m`` and ``d_M``
    are, respectively, the smallest and largest integers not causing
    out-of-bounds memory accesses. In this case, ``k`` can be any
    of ``(d_m, d_M, d_n)``; ``d_n`` can be used to indicate to run
    for exactly ``n`` iterations starting at ``d_m``. ``d_n`` is
    ignored (raising a warning) if ``d_M`` is also provided. ``v`` is
    an integer value.

The following operator implements a trivial time-marching method which adds 1 to every grid point at every time iteration.

>>> from devito import Eq, Grid, TimeFunction, Operator
>>> grid = Grid(shape=(3, 3))
>>> u = TimeFunction(name='u', grid=grid, save=3)
>>> op = Operator(Eq(u.forward, u + 1))

The operator is run by calling

>>> op.apply()

As no key-value parameters are specified, the operator runs with its default arguments, namely u=u, x_m=0, x_M=2, y_m=0, y_M=2, time_m=0, time_M=1. Note that one can access the operator dimensions via the grid object (e.g., grid.dimensions for the x and y space dimensions).

At this point, the same operator can be used for a completely different run, for example

>>> u2 = TimeFunction(name='u', grid=grid, save=5)
>>> op.apply(u=u2, x_m=1, y_M=1)

Now, the operator will run with a different set of arguments, namely u=u2, x_m=1, x_M=2, y_m=0, y_M=1, time_m=0, time_M=3.

Note

To run an operator that only uses buffered :class:`TimeFunction`s, the maximum iteration point along the time dimension must be explicitly specified (otherwise, the operator wouldn’t know how many iterations to run).

>>> u3 = TimeFunction(name='u', grid=grid)
>>> op = Operator(Eq(u3.forward, u3 + 1))
>>> op.apply(time_M=10)
devito.operator.set_dle_mode(mode)[source]

Transform Operator input in a format understandable by the DLE.

devito.operator.set_dse_mode(mode)[source]

Transform Operator input in a format understandable by the DLE.

devito.parameters module

The parameters dictionary contains global parameter settings.

devito.parameters.configuration = {'autotuning': at_setup(level=False, mode='preemptive'), 'backend': 'core', 'compiler': DevitoJITCompiler[CustomCompiler], 'debug_compiler': False, 'develop-mode': True, 'dle': 'advanced', 'dle_options': {'blockinner': False, 'blockshape': None, 'blockalways': False}, 'dse': 'advanced', 'first_touch': False, 'isa': 'cpp', 'log_level': 'INFO', 'mpi': False, 'openmp': False, 'platform': 'intel64', 'profiling': 'basic'}

The Devito configuration parameters.

devito.parameters.init_configuration(configuration={'autotuning': at_setup(level=False, mode='preemptive'), 'backend': 'core', 'compiler': DevitoJITCompiler[CustomCompiler], 'debug_compiler': False, 'develop-mode': True, 'dle': 'advanced', 'dle_options': {'blockinner': False, 'blockshape': None, 'blockalways': False}, 'dse': 'advanced', 'first_touch': False, 'isa': 'cpp', 'log_level': 'INFO', 'mpi': False, 'openmp': False, 'platform': 'intel64', 'profiling': 'basic'}, env_vars_mapper={'DEVITO_ARCH': 'compiler', 'DEVITO_AUTOTUNING': 'autotuning', 'DEVITO_BACKEND': 'backend', 'DEVITO_DEBUG_COMPILER': 'debug_compiler', 'DEVITO_DEVELOP': 'develop-mode', 'DEVITO_DLE': 'dle', 'DEVITO_DLE_OPTIONS': 'dle_options', 'DEVITO_DSE': 'dse', 'DEVITO_FIRST_TOUCH': 'first_touch', 'DEVITO_ISA': 'isa', 'DEVITO_LOGGING': 'log_level', 'DEVITO_MPI': 'mpi', 'DEVITO_OPENMP': 'openmp', 'DEVITO_PLATFORM': 'platform', 'DEVITO_PROFILING': 'profiling'})[source]
devito.parameters.print_defaults()[source]

Print the environment variables accepted by Devito, their default value, as well as all of the accepted values.

devito.parameters.print_state()[source]

Print the current configuration state.

devito.parameters.add_sub_configuration(sub_configuration, sub_env_vars_mapper=None)[source]

devito.profiling module

class devito.profiling.Timer(name, sections)[source]

Bases: devito.types.CompositeObject

default_assumptions = {}
reset()[source]
devito.profiling.create_profile(name)[source]

Create a new Profiler.

devito.types module

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

Bases: devito.types.AbstractCachedSymbol

A sympy.Symbol capable of mimicking an sympy.Indexed

default_assumptions = {}
is_Symbol = True
class devito.types.Indexed[source]

Bases: sympy.tensor.indexed.Indexed

default_assumptions = {'commutative': True}
dtype
function
is_Atom = False
is_Symbol = False
is_commutative = True
name

Module contents

class devito.at_setup(level, mode)

Bases: tuple

level

Alias for field number 0

mode

Alias for field number 1

devito.infer_cpu()[source]

Detect the highest Instruction Set Architecture and the platform codename using cpu flags and/or leveraging other tools. Return default values if the detection procedure was unsuccesful.

devito.mode_benchmark()[source]

Like mode_performance, but also switch YASK’s autotuner mode to preemptive.

devito.mode_develop()[source]

Run all future :class:`Operator`s in develop mode. This is the default configuration for Devito.

devito.mode_performance()[source]

Run all future Operator`s in performance mode. The performance mode will also try to allocate any future :class:`TensorFunction with a suitable NUMA strategy.