devito package

Subpackages

Submodules

devito.arguments module

class devito.arguments.Argument(name, provider, default_value=None)[source]

Bases: object

Abstract base class for any object that represents a run time argument for generated kernels.

dtype
is_PtrArgument = False
is_ScalarArgument = False
is_TensorArgument = False
reset()[source]
value
verify
class devito.arguments.ArgumentProvider(*args, **kwargs)[source]

Bases: object

Abstract base class for any object that, post code-generation, might resolve resolve to runtime arguments. We assume that one source object (e.g. Dimension, SymbolicData) might provide multiple runtime arguments.

rtargs

Return a list of RuntimeArgument objects that this object needs.

class devito.arguments.ArrayArgProvider(*args, **kwargs)[source]

Bases: devito.arguments.ArgumentProvider

Class used to decorate Tensor Function objects with behaviour required for runtime arguments.

rtargs
class devito.arguments.ConstantArgProvider(*args, **kwargs)[source]

Bases: devito.arguments.ArgumentProvider

Class used to decorate Constant Data objects with behaviour required for runtime arguments.

rtargs
class devito.arguments.DimensionArgProvider(*args, **kwargs)[source]

Bases: devito.arguments.ArgumentProvider

This class is used to decorate the Dimension class with behaviour required to handle runtime arguments. All properties/methods defined here are available in any Dimension object.

dtype

The data type of the iteration variable

reducer()

max(iterable, *[, default=obj, key=func]) -> value max(arg1, arg2, *args, *[, key=func]) -> value

With a single iterable argument, return its biggest item. The default keyword-only argument specifies an object to return if the provided iterable is empty. With two or more arguments, return the largest argument.

reset()[source]
rtargs
value

Returns a tuple (same order as rtargs) with the current value of each rtarg If any of the rtargs has value None, the return value here is None.

verify(value, enforce=False)[source]
class devito.arguments.ObjectArgProvider(*args, **kwargs)[source]

Bases: devito.arguments.ArgumentProvider

Class used to decorate Objects with behaviour required for runtime arguments.

rtargs
class devito.arguments.PtrArgument(name, provider)[source]

Bases: devito.arguments.Argument

Class representing arbitrary arguments that a kernel might expect. These are passed as void pointers and then promptly casted to their actual type.

is_PtrArgument = True
verify(value)[source]
class devito.arguments.ScalarArgProvider(*args, **kwargs)[source]

Bases: devito.arguments.ArgumentProvider

Class used to decorate Scalar Function objects with behaviour required for runtime arguments.

rtargs
class devito.arguments.ScalarArgument(name, provider, reducer=<function ScalarArgument.<lambda>>, default_value=None)[source]

Bases: devito.arguments.Argument

Class representing scalar arguments that a kernel might expect. Most commonly used to pass dimension sizes enforce determines whether any reduction will be performed or not. i.e. if it is a user-provided value, use it directly.

is_ScalarArgument = True
reset()[source]
verify(value, enforce=False)[source]

ScalarArgument.verify is called from many different places, with different values. e.g. 1. From inside Operator.arguments(), with an accompanying user-provided value from kwargs 2. From the verify of a Dimension object, with an accompanying “derived” value, which is the best-guess for this ScalarArgument’s value that the Dimension can come up with. In the above two cases, the value passed in case 2 is “optional”, since a dimension “belongs” to multiple Function objects and each object might lead to a different best-guess. During normal behaviour, verify is expected to be called multiple times with different values and this method will combine all the values received in the different invocations in a configurable (self.reducer) way. However, if the user has explicitly passed in a value (case 1 above), that value has to be respected and this best-guess behaviour described above needs to be switched off. Another thing to note is that, once a ScalarArgument has been passed a value with enforce=True, any further calls to verify should not change the stored value. The self._frozen flag is used to ensure that. :param enforce: Turn off the best-guess behaviour and just use the value

passed, ignoring any previously stored values.
class devito.arguments.TensorArgument(name, provider)[source]

Bases: devito.arguments.Argument

Class representing tensor arguments that a kernel might expect. Most commonly used to pass numpy-like multi-dimensional arrays.

is_TensorArgument = True
verify(value)[source]
class devito.arguments.TensorFunctionArgProvider(*args, **kwargs)[source]

Bases: devito.arguments.ArgumentProvider

Class used to decorate Symbolic Data objects with behaviour required for runtime arguments.

rtargs
devito.arguments.infer_dimension_values_tuple(value, rtargs, offsets=None)[source]

Strictly, a dimension’s value is a 3-tuple consisting of the values of each of its rtargs - currently size, start and end. However, for convenience, we may accept partial representations of the value, e.g. scalars and 2-tuples and interpret them in a certain way while assuming defaults for missing information. If value is: 3-tuple: it contains explicit values for all 3 rtargs and hence will be used directly 2-tuple: We assume we are being provided the (start, end) values. This will be promoted to a 3-tuple assuming size to be the same as end. scalar: We assume we are being provided the value of size. Promote to 3-tuple by assuming this scalar is the size and the end of the dimension. start will default to 0.

devito.arguments.log_args(arguments)[source]

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

Symbolic object representing a tensor.

Parameters:
  • name – Name of the symbol
  • dtype – Data type of the scalar
  • shape – The shape of the tensor
  • dimensions – The symbolic dimensions of the tensor.
  • external – Pass True if there is no need to allocate storage
  • onstack – Pass True to enforce allocation on the stack
  • onheap – Pass True to enforce allocation on the heap
default_assumptions = {}
class devito.base.Constant(*args, **kwargs)[source]

Bases: devito.function.Constant

Symbol representing constant values in symbolic equations.

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

Bases: devito.function.Function

Data object for spatially varying data acting as a SymbolicFunction.

Parameters:
  • name – Name of the symbol
  • gridGrid object from which to infer the data shape and Dimension indices.
  • shape – (Optional) shape of the associated data for this symbol.
  • dimensions – (Optional) symbolic dimensions that define the data layout and function indices of this symbol.
  • staggered – (Optional) tuple containing staggering offsets.
  • dtype – (Optional) data type of the buffered data.
  • space_order – Discretisation order for space derivatives
  • initializer – Function to initialize the data, optional

Note

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

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

Note

The tuple :param staggered: contains a 1 in each dimension entry that should be staggered, and 0 otherwise. For example, staggered=(1, 0, 0) entails discretization on horizontal edges, staggered=(0, 0, 1) entails discretization on vertical edges, staggered=(0, 1, 1) entails discretization side facets and staggered=(1, 1, 1) entails discretization on cells.

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

Bases: devito.operator.Operator

A node representing a function.

Parameters:
  • name – The name of the function.
  • body – A Node or an iterable of Node objects representing the body of the function.
  • retval – The type of the value returned by the function.
  • parameters – An iterable of SymbolicData objects in input to the function, or None if the function takes no parameter.
  • prefix – An iterable of qualifiers to prepend to the function 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.Scalar(*args, **kwargs)[source]

Bases: devito.types.Scalar

Symbolic object representing a scalar.

Parameters:
  • name – Name of the symbol
  • dtype – Data type of the scalar
default_assumptions = {}
class devito.base.SparseFunction(*args, **kwargs)[source]

Bases: devito.function.SparseFunction

Function representing a set of sparse point objects that are not aligned with the computational grid. SparseFunction objects provide symbolic interpolation routines to convert between grid-aligned Function objects and sparse data points.

Parameters:
  • name – Name of the resulting sympy.Function symbol
  • gridGrid object defining the computational domain.
  • npoint – Number of points to sample
  • nt – Size of the time dimension for point data
  • coordinates – Optional coordinate data for the sparse points
  • dtype – Data type of the buffered data
default_assumptions = {}
class devito.base.TimeFunction(*args, **kwargs)[source]

Bases: devito.function.TimeFunction

Data object for time-varying data that acts as a Function symbol

Parameters:
  • name – Name of the resulting sympy.Function symbol
  • gridGrid object from which to infer the data shape and Dimension indices.
  • staggered – (Optional) tuple containing staggering offsets.
  • dtype – (Optional) data type of the buffered data
  • save – Save the intermediate results to the data buffer. Defaults to False, indicating the use of alternating buffers.
  • time_dim – Size of the time dimension that dictates the leading dimension of the data buffer if :param save: is True.
  • time_order – Order of the time discretization which affects the final size of the leading time dimension of the data buffer.

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

push_stack(scope, obj)[source]

Generate a cgen statement that allocates obj on the stack.

class devito.cgen_utils.CodePrinter(settings={})[source]

Bases: sympy.printing.ccode.C99CodePrinter

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

Decorator for sympy.printing.ccode.CCodePrinter.

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

Bases: sympy.core.function.AppliedUndef

default_assumptions = {}
class devito.cgen_utils.INT

Bases: sympy.core.function.AppliedUndef

default_assumptions = {}
devito.cgen_utils.ccode(expr, **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.ccode_eq(eq, **settings)[source]

Generate C++ assignment from an equation assigning RHS to LHS

Parameters:
  • eq – The equation
  • settings – A dictionary of settings for code printing
Returns:

The resulting code as a string

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

devito.compiler module

devito.compiler.jit_compile(ccode, compiler)[source]

JIT compile the given ccode.

Parameters:
  • ccode – String of C source code.
  • compiler – The toolchain used for compilation.
Returns:

The name of the compilation unit.

devito.compiler.load(basename, compiler)[source]

Load a compiled library

Parameters:
  • basename – Name of the .so file.
  • compiler – The toolchain used for compilation.
Returns:

The loaded library.

Note: If the provided compiler is of type IntelMICCompiler we utilise the pymic package to manage device streams.

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.

devito.dimension module

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

Bases: sympy.core.symbol.Symbol, devito.arguments.DimensionArgProvider

default_assumptions = {}
end_name
is_Lowered = False

Index object that represents a problem dimension and thus defines a potential iteration space.

Parameters:
  • name – Name of the dimension symbol.
  • reverse – Traverse dimension in reverse order (default False)
  • spacing – Optional, symbol for the spacing along this dimension.
is_Space = False
is_Stepping = False
is_Time = False
limits
size_name
start_name
symbolic_end
symbolic_extent

Return the extent of the loop over this dimension. Would be the same as size if using default values

symbolic_size

The symbolic size of this dimension.

symbolic_start
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.
  • reverse – Traverse dimension in reverse order (default False)
  • 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.
  • reverse – Traverse dimension in reverse order (default False)
  • spacing – Optional, symbol for the spacing along this dimension.
class devito.dimension.SteppingDimension(*args, **kwargs)[source]

Bases: devito.dimension.Dimension

default_assumptions = {}
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:parent – Parent dimension over which to loop in modulo fashion.
reverse
spacing

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.StencilOperationError[source]

Bases: devito.exceptions.DevitoError

exception devito.exceptions.VisitorException[source]

Bases: devito.exceptions.DevitoError

devito.finite_difference module

devito.finite_difference.first_derivative(*args, **kwargs)[source]

Derives first derivative for a product of given functions.

Parameters:
  • *args – All positional arguments must be fully qualified function objects, eg. f(x, y) or g(t, x, y, z).
  • dims – symbol defining the dimension wrt. which to differentiate, eg. x, y, z or t.
  • diff – Finite Difference symbol to insert, default h.
  • side – Side of the shift for the first derivatives.
Returns:

The first derivative

Example: Deriving the first-derivative of f(x)*g(x) wrt. x via:
cross_derivative(f(x), g(x), dim=x, side=1, order=1) results in: *(-f(x)*g(x) + f(x + h)*g(x + h) ) / h
devito.finite_difference.second_derivative(*args, **kwargs)[source]

Derives second derivative for a product of given functions.

Parameters:
  • *args – All positional arguments must be fully qualified function objects, eg. f(x, y) or g(t, x, y, z).
  • dim – Symbol defininf the dimension wrt. which to differentiate, eg. x, y, z or t.
  • diff – Finite Difference symbol to insert, default h.
  • order – Discretisation order of the stencil to create.
Returns:

The second derivative

Example: Deriving the second derivative of f(x, y)*g(x, y) wrt. x via
second_derivative(f(x, y), g(x, y), order=2, dim=x) results in (-2.0*f(x, y)*g(x, y) + 1.0*f(-h + x, y)*g(-h + x, y) + 1.0*f(h + x, y)*g(h + x, y)) / h**2.
devito.finite_difference.cross_derivative(*args, **kwargs)[source]

Derives cross derivative for a product of given functions.

Parameters:
  • *args – All positional arguments must be fully qualified function objects, eg. f(x, y) or g(t, x, y, z).
  • dims – 2-tuple of symbols defining the dimension wrt. which to differentiate, eg. x, y, z or t.
  • diff – Finite Difference symbol to insert, default h.
Returns:

The cross derivative

Example: Deriving the cross-derivative of f(x, y)*g(x, y) wrt. x and y via:
cross_derivative(f(x, y), g(x, y), dims=(x, y)) results in: 0.5*(-2.0*f(x, y)*g(x, y) + f(x, -h + y)*g(x, -h + y) + f(x, h + y)*g(x, h + y) + f(-h + x, y)*g(-h + x, y) - f(-h + x, h + y)*g(-h + x, h + y) + f(h + x, y)*g(h + x, y) - f(h + x, -h + y)*g(h + x, -h + y)) / h**2
devito.finite_difference.generic_derivative(function, deriv_order, dim, fd_order)[source]

Create generic arbitrary order derivative expression from a single Function object. This methods is essentially a dedicated wrapper around SymPy’s as_finite_diff utility for devito.Function objects.

Parameters:
  • function – The symbol representing a function.
  • deriv_order – Derivative order, eg. 2 for a second derivative.
  • dim – The dimension for which to take the derivative.
  • fd_order – Order of the coefficient discretization and thus the width of the resulting stencil expression.
devito.finite_difference.second_cross_derivative(function, dims, order)[source]

Create a second order order cross derivative for a given function.

Parameters:
  • function – The symbol representing a function.
  • dims – Dimensions for which to take the derivative.
  • order – Discretisation order of the stencil to create.

devito.function module

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

Bases: devito.types.AbstractSymbol, devito.arguments.ConstantArgProvider

Symbol representing constant values in symbolic equations.

base
data

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

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

Bases: devito.function.TensorFunction

Data object for spatially varying data acting as a SymbolicFunction.

Parameters:
  • name – Name of the symbol
  • gridGrid object from which to infer the data shape and Dimension indices.
  • shape – (Optional) shape of the associated data for this symbol.
  • dimensions – (Optional) symbolic dimensions that define the data layout and function indices of this symbol.
  • staggered – (Optional) tuple containing staggering offsets.
  • dtype – (Optional) data type of the buffered data.
  • space_order – Discretisation order for space derivatives
  • initializer – Function to initialize the data, optional

Note

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

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

Note

The tuple :param staggered: contains a 1 in each dimension entry that should be staggered, and 0 otherwise. For example, staggered=(1, 0, 0) entails discretization on horizontal edges, staggered=(0, 0, 1) entails discretization on vertical edges, staggered=(0, 1, 1) entails discretization side facets and staggered=(1, 1, 1) entails discretization on cells.

data

The value of the data object, as a numpy.ndarray storing elements in the classical row-major storage layout.

default_assumptions = {}
initialize()[source]

Apply the data initilisation function, if it is not None.

is_Function = True
laplace

Generates a symbolic expression for the Laplacian, the second derivative wrt. all spatial dimensions.

laplace2(weight=1)[source]

Generates a symbolic expression for the double Laplacian wrt. all spatial dimensions.

shape
shape_data

Full allocated shape of the data associated with this Function.

space_dimensions

Tuple of index dimensions that define physical space.

symbolic_shape

Return the symbolic shape of the object. This is simply the appropriate combination of symbolic dimension sizes shifted according to the staggered mask.

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

Bases: devito.function.Function

Data object for time-varying data that acts as a Function symbol

Parameters:
  • name – Name of the resulting sympy.Function symbol
  • gridGrid object from which to infer the data shape and Dimension indices.
  • staggered – (Optional) tuple containing staggering offsets.
  • dtype – (Optional) data type of the buffered data
  • save – Save the intermediate results to the data buffer. Defaults to False, indicating the use of alternating buffers.
  • time_dim – Size of the time dimension that dictates the leading dimension of the data buffer if :param save: is True.
  • time_order – Order of the time discretization which affects the final size of the leading time dimension of the data buffer.

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 = {}
dim

Returns the spatial dimension of the data object

dt

Symbol for the first derivative wrt the time dimension

dt2

Symbol for the second derivative wrt the t dimension

forward

Symbol for the time-forward state of the function

initialize()[source]
is_TimeFunction = True
shape_data

Full allocated shape of the data associated with this TimeFunction.

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

Bases: devito.function.CompositeFunction

Function representing a set of sparse point objects that are not aligned with the computational grid. SparseFunction objects provide symbolic interpolation routines to convert between grid-aligned Function objects and sparse data points.

Parameters:
  • name – Name of the resulting sympy.Function symbol
  • gridGrid object defining the computational domain.
  • npoint – Number of points to sample
  • nt – Size of the time dimension for point data
  • coordinates – Optional coordinate data for the sparse points
  • dtype – Data type of the buffered data
coefficients

Symbolic expression for the coefficients for sparse point interpolation according to: https://en.wikipedia.org/wiki/Bilinear_interpolation.

Returns:List of coefficients, eg. [b_11, b_12, b_21, b_22]
coordinate_bases

Symbol for the base coordinates of the reference grid point

coordinate_indices

Symbol for each grid index according to the coordinates

coordinate_symbols

Symbol representing the coordinate values in each dimension

default_assumptions = {}
inject(field, expr, offset=0, **kwargs)[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, **kwargs)[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.
is_SparseFunction = True
point_increments

Index increments in each dimension for each point symbol

point_symbols

Symbol for coordinate value in each dimension of the point

shape_data

Full allocated shape of the data associated with this SparseFunction.

devito.grid module

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

Bases: object

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 – Physical extent of the domain in m; defaults to a unit box of extent 1m in all dimensions.
  • origin – Physical coordinate of the origin of the domain; defaults to 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 – Default data type to be inherited by all Functions created from this Grid.

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 + extent
  |     x------------x
  |     |            |
  |     |            |
  |     |   DOMAIN   | extent[1]
  |     |            |
  |     |            |
  |     |  extent[0] |
  |     x------------x
  |  origin
  |
  |----------------------->
             y
dim

Problem dimension, or number of spatial dimensions.

shape_domain

Shape of the physical domain (without external boundary layer)

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

devito.logger module

The Devito logger.

devito.logger.set_log_level(level)[source]

Set the log level of the Devito logger.

Parameters:level – accepted values are: DEBUG, INFO, AUTOTUNER, DSE, DSE_WARN, DLE, DLE_WARN, WARNING, ERROR, CRITICAL
devito.logger.set_log_noperf()[source]

Do not print performance-related messages.

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, INFO, AUTOTUNER, DSE, DSE_WARN, DLE, DLE_WARN, WARNING, ERROR, CRITICAL
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, INFO, AUTOTUNER, 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.info_at(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.memory module

class devito.memory.CMemory(shape, dtype=<class 'numpy.float32'>, alignment=None)[source]

Bases: object

fill(val)[source]
devito.memory.first_touch(array)[source]

Uses the Propagator low-level API to initialize the given array(in Devito types) in the same pattern that would later be used to access it.

devito.memory.free(internal_pointer)[source]

Use the C function free to free the memory allocated for the given pointer.

devito.memory.malloc_aligned(shape, alignment=None, dtype=<class 'numpy.float32'>)[source]

Allocate memory using the C function malloc_aligned :param shape: Shape of the array to allocate :param alignment: number of bytes to align to. Defaults to page size if not set. :param dtype: Numpy datatype to allocate. Default to np.float32

:returns (pointer, data_pointer) the first element of the tuple is the reference that can be used to access the data as a ctypes object. The second element is the low-level reference that is needed only for the call to free.

devito.operator module

class devito.operator.FunMeta(root, local)

Bases: tuple

Metadata for functions called by an Operator. local = True means that the function was generated by Devito itself.

local

Alias for field number 1

root

Alias for field number 0

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

Bases: devito.ir.iet.nodes.Callable

arguments(**kwargs)[source]

Process any apply-time arguments passed to apply and derive values for any remaining arguments

cfunction

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

compile

JIT-compile the C code generated by the Operator.

It is ensured that JIT compilation will only be performed once per Operator, reagardless of how many times this method is invoked.

Returns:The file name of the JIT-compiled function.
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]

Apply the stencil kernel to a set of data objects

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 = Parameters([('log_level', 'DEBUG'), ('first_touch', False), ('dse', 'advanced'), ('dle', 'advanced'), ('dle_options', {'blockinner': False, 'blockshape': None, 'blockalways': False}), ('compiler', DevitoJITCompiler[GNUCompiler]), ('openmp', False), ('debug_compiler', False), ('backend', 'core'), ('isa', None), ('platform', None)])

The Devito configuration parameters.

devito.parameters.init_configuration(configuration=Parameters([('log_level', 'DEBUG'), ('first_touch', False), ('dse', 'advanced'), ('dle', 'advanced'), ('dle_options', {'blockinner': False, 'blockshape': None, 'blockalways': False}), ('compiler', DevitoJITCompiler[GNUCompiler]), ('openmp', False), ('debug_compiler', False), ('backend', 'core'), ('isa', None), ('platform', None)]), env_vars_mapper={'DEVITO_ARCH': 'compiler', 'DEVITO_ISA': 'isa', 'DEVITO_PLATFORM': 'platform', 'DEVITO_BACKEND': 'backend', 'DEVITO_DSE': 'dse', 'DEVITO_DLE': 'dle', 'DEVITO_DLE_OPTIONS': 'dle_options', 'DEVITO_OPENMP': 'openmp', 'DEVITO_LOGGING': 'log_level', 'DEVITO_FIRST_TOUCH': 'first_touch', 'DEVITO_DEBUG_COMPILER': 'debug_compiler'})[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.Profile(name, ops, memory)

Bases: tuple

Metadata for a profiled code section.

memory

Alias for field number 2

name

Alias for field number 0

ops

Alias for field number 1

devito.profiling.create_profile(node)[source]

Create a Profiler for the Iteration/Expression tree node. The following code sections are profiled:

* The whole ``node``;
* A sequence of perfectly nested loops that have common :class:`Iteration`
  dimensions, but possibly different extent. For example: ::

    for x = 0 to N
      ..
    for x = 1 to N-1
      ..

  Both Iterations have dimension ``x``, and will be profiled as a single
  section, though their extent is different.
* Any perfectly nested loops.

devito.tools module

class devito.tools.memoized(func)[source]

Bases: object

Decorator. Caches a function’s return value each time it is called. If called later with the same arguments, the cached value is returned (not reevaluated).

Adapted from:

https://wiki.python.org/moin/PythonDecoratorLibrary#Memoize
devito.tools.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.types module

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

Bases: devito.types.AbstractSymbol

A sympy.Symbol capable of mimicking an sympy.Indexed

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

Bases: sympy.tensor.indexed.Indexed

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

Module contents

devito.clear_cache()[source]