Reference

Get symbolic representation for function index object

isconst(x::Constant)

True if the symbol value cannot be modified within an Operator (and thus its value is provided by the user directly from Python-land), False otherwise.

ndims(x::DiscreteFunction)

Return the number of dimensions corresponding to the discrete function x.

parent(x::AbstractSubDimension)

Returns the parent dimension of a subdimension.

Example

julia x = SpaceDimension(name="x") xr = SubDimensionRight(name="xr", parent=x, thickness=2) parent(xr)`

size(x::DiscreteFunction)

Return the shape of the grid for the discrete function x.

Derivative(x::Union{Constant, Number}, args...; kwargs...)

Returns the derivative of a constant or number, which is zero.

Derivative(x::Union{DiscreteFunction,Py}, args...; kwargs...)


An unevaluated Derivative, which carries metadata (Dimensions,
derivative order, etc) describing how the derivative will be expanded
upon evaluation.

Parameters
----------
expr : expr-like
    Expression for which the Derivative is produced.
dims : Dimension or tuple of Dimension
    Dimenions w.r.t. which to differentiate.
fd_order : int or tuple of int, optional
    Coefficient discretization order. Note: this impacts the width of
    the resulting stencil. Defaults to 1.
deriv_order: int or tuple of int, optional
    Derivative order. Defaults to 1.
side : Side or tuple of Side, optional
    Side of the finite difference location, centered (at x), left (at x - 1)
    or right (at x +1). Defaults to ``centered``.
transpose : Transpose, optional
    Forward (matvec=direct) or transpose (matvec=transpose) mode of the
    finite difference. Defaults to ``direct``.
subs : dict, optional
    Substitutions to apply to the finite-difference expression after evaluation.
x0 : dict, optional
    Origin (where the finite-difference is evaluated at) for the finite-difference
    scheme, e.g. Dict(x=> x, y => y + spacing(y)/2).

Examples
--------
Creation

```julia
using Devito
grid = Grid((10, 10))
y, x = dimensions(grid)
u = Devito.Function(name="u", grid=grid, space_order=2)
Derivative(u, x)

# You can also specify the order as a keyword argument

Derivative(u, x, deriv_order=2)

# Or as a tuple

Derivative(u, (x, 2))
```

DevReal(x)
DevImag(x)
DevConj(x)

Symbolic real part, imaginary part, and conjugate of a complex-typed Devito expression x, returned as devito symbolic nodes from devito.finite_differences.differentiable (not Julia numbers). Use them inside Devito equations on complex-typed Functions: they emit correct C code, whereas sympy.re/im/conjugate hit a devito assumption bug (AbstractSymbol._eval_is_imaginary is True for complex dtypes, so sympy treats the Function as purely imaginary).

Max(args...)

Can be used in a Devito.Eq to return the minimum of a collection of arguments Example:

    eqmax = Eq(f,Max(g,1))

Is equivalent to f = Max(g,1) for Devito functions f,g

Min(args...)

Can be used in a Devito.Eq to return the minimum of a collection of arguments Example:

    eqmin = Eq(f,Min(g,1))

Is equivalent to f = Min(g,1) for Devito functions f,g

Mod(x::AbstractDimension,y::Int)

Perform Modular division on a dimension

apply( operator::Operator; kwargs...)

Execute the Devito operator, Operator.

See: https://www.devitoproject.org/devito/operator.html?highlight=apply#devito.operator.operator.Operator.apply

Note that this returns a summary::Dict of the action of applying the operator. This contains information such as the number of floating point operations executed per second.

backward(x::TimeFunction)

Returns the symbol for the time-backward state of the TimeFunction.

See: https://www.devitoproject.org/devito/timefunction.html?highlight=forward#devito.types.TimeFunction.backward

ccode(x::Operator; filename="")

Print the ccode associated with a devito operator. If filename is provided, writes ccode to disk using that filename

configuration!(key, value)

Configure Devito. Examples include

configuration!("log-level", "DEBUG")
configuration!("language", "openmp")
configuration!("mpi", false)

coordinates(x::SparseDiscreteFunction)

Returns a Devito function associated with the coordinates of a sparse time function. Note 1: contrary to typical Julia convention, coordinate order is from slow-to-fast (Python ordering). Thus, for a 3D grid, the sparse time function coordinates would be ordered x,y,z. Note 2: we need to handle complex data types, because coordinats are purely real

coordinates_data(x::SparseDiscreteFunction)

Returns a Devito array associated with the coordinates of a sparse time function. Note that contrary to typical Julia convention, coordinate order is from slow-to-fast (Python ordering). Thus, for a 3D grid, the sparse time function coordinates would be ordered x,y,z.

csize_allocated(x::DiscreteFunction, dim::AbstractDimension)

Symbolic extent of x's allocated data field along dimension dim — Devito's FULL data region (domain + halo + padding). Returns the devito C-code expression (e.g. b_vec->size[1], an IndexedPointer), not a Julia integer; use it where devito expects such an expression (e.g. as a CCall argument).

data(x::Constant{T})

Returns value(x::Constant{T}). See value documentation for more information.

data(x::DiscreteFunction)

Return the data associated with the grid that corresponds to the discrete function x. This is the portion of the grid that excludes the halo. In the case of non-MPI Devito, this returns an array of type DevitoArray. In the case of the MPI Devito, this returns an array of type DevitoMPIArray.

The data can be converted to an Array via convert(Array, data(x)). In the case where data(x)::DevitoMPIArray, this also collects the data onto MPI rank 0.

data_allocated(x::DiscreteFunction)

Return the data associated with the grid that corresponds to the discrete function x. This is the portion of the grid that includes the inner halo and includes the outer halo. We expect this to be equivalent to data_with_inhalo.

The data can be converted to an Array via convert(Array, data(x)). In the case where data(x)::DevitoMPIArray, this also collects the data onto MPI rank 0.

data_with_halo(x::DiscreteFunction)

Return the data associated with the grid that corresponds to the discrete function x. This is the portion of the grid that excludes the inner halo and includes the outer halo. In the case of non-MPI Devito, this returns an array of type DevitoArray. In the case of the MPI Devito, this returns an array of type DevitoMPIArray.

The data can be converted to an Array via convert(Array, data(x)). In the case where data(x)::DevitoMPIArray, this also collects the data onto MPI rank 0.

data_with_inhalo(x::DiscreteFunction)

Return the data associated with the grid that corresponds to the discrete function x. This is the portion of the grid that includes the inner halo and includes the outer halo. In the case of non-MPI Devito, this returns an array of type DevitoArray. In the case of the MPI Devito, this returns an array of type DevitoMPIArray.

The data can be converted to an Array via convert(Array, data(x)). In the case where data(x)::DevitoMPIArray, this also collects the data onto MPI rank 0.

dimensions(x::Union{Grid,DiscreteFunction})

Returns a tuple with the dimensions associated with the Devito grid.

dt(f::TimeFunction, args...; kwargs...)

Returns the symbol for the first time derivative of a time function

dt2(f::TimeFunction, args...; kwargs...)

Returns the symbol for the second time derivative of a time function

dx(f::Union{DiscreteFunction,Py,Constant,Number}, args...; kwargs...)

Returns the symbol for the first derivative with respect to x if f is a Function with dimension x. Otherwise returns 0. Thus, the derivative of a function with respect to a dimension it doesn't have is zero, as is the derivative of a constant.

dx2(f::Union{DiscreteFunction,Py,Constant,Number}, args...; kwargs...)

Returns the symbol for the second derivative with respect to x if f is a Function with dimension x. Otherwise returns 0. Thus, the derivative of a function with respect to a dimension it doesn't have is zero, as is the derivative of a constant.

dxl(f::DiscreteFunction, args...; kwargs...)

Returns the symbol for the first backward one-sided derivative with respect to x if f is a Function with dimension x. Otherwise returns 0. Thus, the derivative of a function with respect to a dimension it doesn't have is zero, as is the derivative of a constant.

dxr(f::DiscreteFunction, args...; kwargs...)

Returns the symbol for the first forward one-sided derivative with respect to x if f is a Function with dimension x. Otherwise returns 0. Thus, the derivative of a function with respect to a dimension it doesn't have is zero, as is the derivative of a constant.

dy(f::DiscreteFunction, args...; kwargs...)

Returns the symbol for the first derivative with respect to y if f is a Function with dimension y. Otherwise returns 0. Thus, the derivative of a function with respect to a dimension it doesn't have is zero, as is the derivative of a constant.

dy2(f::DiscreteFunction, args...; kwargs...)

Returns the symbol for the second derivative with respect to y if f is a Function with dimension y. Otherwise returns 0. Thus, the derivative of a function with respect to a dimension it doesn't have is zero, as is the derivative of a constant.

dyl(f::DiscreteFunction, args...; kwargs...)

Returns the symbol for the first backward one-sided derivative with respect to y if f is a Function with dimension y. Otherwise returns 0. Thus, the derivative of a function with respect to a dimension it doesn't have is zero, as is the derivative of a constant.

dyr(f::DiscreteFunction, args...; kwargs...)

Returns the symbol for the first forward one-sided derivative with respect to y if f is a Function with dimension y. Otherwise returns 0. Thus, the derivative of a function with respect to a dimension it doesn't have is zero, as is the derivative of a constant.

dzr(f::DiscreteFunction, args...; kwargs...)

Returns the symbol for the first forward one-sided derivative with respect to z if f is a Function with dimension z. Otherwise returns 0. Thus, the derivative of a function with respect to a dimension it doesn't have is zero, as is the derivative of a constant.

dzl(f::DiscreteFunction, args...; kwargs...)

Returns the symbol for the first backward one-sided derivative with respect to z if f is a Function with dimension y. Otherwise returns 0. Thus, the derivative of a function with respect to a dimension it doesn't have is zero, as is the derivative of a constant.

evaluate(x::Py)

Evaluate a PythonCall expression

forward(x::TimeFunction)

Returns the symbol for the time-forward state of the TimeFunction.

See: https://www.devitoproject.org/devito/timefunction.html?highlight=forward#devito.types.TimeFunction.forward

grid(f::DiscreteFunction)

Return the grid corresponding to the discrete function f.

halo(x::DiscreteFunction)

Return the Devito "outer" halo size corresponding to the discrete function f.

The wrapped IndexedData object.

inhalo(x::DiscreteFunction)

Return the Devito "inner" halo size used for domain decomposition, and corresponding to the discrete function f.

inject(x::SparseDiscreteFunction; kwargs...)

Generate equations injecting an arbitrary expression into a field.

See: Generate equations injecting an arbitrary expression into a field.

Example

x = SpaceDimension(name="x", spacing=Constant(name="h_x", value=5.0))
z = SpaceDimension(name="z", spacing=Constant(name="h_z", value=5.0))
grid = Grid(
    dimensions = (x,z),
    shape = (251,501), # assume x is first, z is second (i.e. z is fast in python)
    origin = (0.0,0.0),
    extent = (1250.0,2500.0),
    dtype = Float32)

time_range = 0.0f0:0.5f0:1000.0f0
src = SparseTimeFunction(name="src", grid=grid, npoint=1, nt=length(time_range))
src_term = inject(src; field=forward(p), expr=2*src)

interior(x::grid)

returns the interior subdomain of a Devito grid

interpolate(x::SparseDiscreteFunction; kwargs...)

Generate equations interpolating an arbitrary expression into self.

See: https://www.devitoproject.org/devito/sparsetimefunction.html#devito.types.SparseTimeFunction.interpolate

Example

x = SpaceDimension(name="x", spacing=Constant(name="h_x", value=5.0))
z = SpaceDimension(name="z", spacing=Constant(name="h_z", value=5.0))
grid = Grid(
    dimensions = (z,x),
    shape = (501,251), # assume z is first, x is second
    origin = (0.0,0.0),
    extent = (2500.0,1250.0),
    dtype = Float32)

p = TimeFunction(name="p", grid=grid, time_order=2, space_order=8)

time_range = 0.0f0:0.5f0:1000.0f0
nz,nx,δz,δx = size(grid)...,spacing(grid)...
rec = SparseTimeFunction(name="rec", grid=grid, npoint=nx, nt=length(time_range))
rec_coords = coordinates_data(rec)
rec_coords[1,:] .= 10.0
rec_coords[2,:] .= δx*(0:nx-1)


rec_term = interpolate(rec, expr=p)

is_Derived(x::Dimension)

Returns true when dimension is derived, false when it is not

name(x::Union{SubDomain, DiscreteFunction, TimeFunction, Function, Constant, AbstractDimension, Operator})

returns the name of the Devito object

nsimplify(expr::Py; constants=(), tolerance=none, full=false, rational=none, rational_conversion="base10")

Wrapper around sympy.nsimplify. Find a simple representation for a number or, if there are free symbols or if $rational=True$, then replace Floats with their Rational equivalents. If no change is made and rational is not False then Floats will at least be converted to Rationals.

Explanation

For numerical expressions, a simple formula that numerically matches the given numerical expression is sought (and the input should be possible to evalf to a precision of at least 30 digits). Optionally, a list of (rationally independent) constants to include in the formula may be given. A lower tolerance may be set to find less exact matches. If no tolerance is given then the least precise value will set the tolerance (e.g. Floats default to 15 digits of precision, so would be tolerance=10**-15). With $full=True$, a more extensive search is performed (this is useful to find simpler numbers when the tolerance is set low). When converting to rational, if rationalconversion='base10' (the default), then convert floats to rationals using their base-10 (string) representation. When rationalconversion='exact' it uses the exact, base-2 representation.

See https://github.com/sympy/sympy/blob/52f606a503cea5e9588de14150ccb9f7f9ed4752/sympy/simplify/simplify.py .

Examples:

nsimplify(π) # PyObject 314159265358979/100000000000000

nsimplify(π; tolerance=0.1) # PyObject 22/7

operator_options(op::Operator)

Return an Operator's compilation options as a Dict{String,Any} (mirrors the Python operator's _options).

operator_timers(op::Operator)

Return an applied Operator's Python profiler timers as a Dict{String,Any}. Top-level values are elapsed seconds (Float64) — e.g. the devito-pro decoupler's "decoupler-prepare" and "decoupler-execute" entries — or nested per-section timer dicts.

origin(grid)

returns the tuple corresponding to the grid's origin

size_with_halo(x::DiscreteFunction)

Return the size of the grid associated with x, inclusive of the Devito "outer" halo.

size_with_inhalo(x::DiscreteFunction)

Return the size of the grid associated with z, inclusive the the Devito "inner" and "outer" halos.

solve(eq::Py, target::Py; kwargs...)

Algebraically rearrange an Eq w.r.t. a given symbol. This is a wrapper around $devito.solve$, which in turn is a wrapper around $sympy.solve$.

Parameters

• eq::Py expr-like. The equation to be rearranged.
• target::Py The symbol w.r.t. which the equation is rearranged. May be a Function or any other symbolic object.

kwargs

• Symbolic optimizations applied while rearranging the equation. For more information. refer to sympy.solve.__doc__.

space_order(x::Union{TimeFunction,Function})

Returns the space order for spatial derivatives defined on the associated TimeFunction or Function

spacing(x::Dimension)

Symbol representing the physical spacing along the Dimension.

stepping_dim(x::Grid)

Returns the stepping dimension for the associated grid.

subdomains(grid)

returns subdomains associated with a Devito grid

subs(f::DiscreteFunction{T,N,M},dict::Dict)

Perform substitution on the dimensions of Devito Discrete Function f based on a dictionary.

Example

    grid = Grid(shape=(10,10,10))
    z,y,x = dimensions(grid)
    f = Devito.Function(grid=grid, name="f", staggered=x)
    subsdict = Dict(x=>x-spacing(x)/2)
    g = subs(f,subsdict)

symbolic_max(x::Dimension)

Symbol defining the maximum point of the Dimension

symbolic_min(x::Dimension)

Symbol defining the minimum point of the Dimension

symbolic_size(x::Dimension)

Symbol defining the size of the Dimension

function to return the sympy Or

thickness(x::AbstractSubDimension)

Returns a tuple of a tuple containing information about the left and right thickness of a SubDimension and a symbol corresponding to each side's thickness.

Example

x = SpaceDimension(name="x")
xr = SubDimensionRight(name="xr", parent=x, thickness=2)
thickness(xr)

time_dim(x::Union{Grid,TimeFunction})

Returns the time dimension for the associated object.

tuner_enabled(f, opname, outfile; opt, target, options, skip, fixed, errfile, mode)

Run f (a zero-arg function, typically a do block that builds and applys an Operator) inside devitotuner's tuner_enabled context manager, autotuning the operator named opname and writing results to outfile. DevitoPro only.

devitotuner raises DevitotunerAccomplished when a sweep completes, and devito raises CompilationError for a non-compilable variant; both are caught here (the run is treated as finished/skipped) so callers need no Python-level exception handling. Returns f()'s value on a normal run, or nothing when such a signal was caught.

options, skip and fixed accept a Julia Dict; the remaining keywords mirror devitotuner.tuner_enabled.

Example

summary = tuner_enabled("MyOperator_nlfwd", "results.json"; fixed=Dict("cire-schedule" => 0)) do
    op = Operator(eqns, subs=smap, name="MyOperator_nlfwd")
    apply(op)
end

value!(x::Constant{T},y::T)

Change the numerical value of a constant, x, after creation to y, after converting y to datatype T of constant x.

value(x::Constant)

Returns the value of a devito constant. Can not be used to change constant value, for that use value!(x,y)

Buffer(value::Int)

Construct a devito buffer. This may be used as a save= keyword argument in the construction of TimeFunctions.

Symbolic representation of the C notation &expr.

Symbolic representation of the C notation (type)expr.

ConditionalDimension(;kwargs)

Symbol defining a non-convex iteration sub-space derived from a parent Dimension, implemented by the compiler generating conditional "if-then" code within the parent Dimension's iteration space.

See: https://www.devitoproject.org/devito/dimension.html?highlight=conditional#devito.types.dimension.ConditionalDimension

Example

size, factor = 16, 4
i  = SpaceDimension(name="i")
grid = Grid(shape=(size,),dimensions=(i,))
ci = ConditionalDimension(name="ci", parent=i, factor=factor)
g  = Devito.Function(name="g", grid=grid, shape=(size,), dimensions=(i,))
f  = Devito.Function(name="f", grid=grid, shape=(div(size,factor),), dimensions=(ci,))
op = Operator([Eq(g, 1), Eq(f, g)],name="Cond")

Constant(args...; kwargs...)

Symbol representing a constant, scalar value in symbolic equations. A Constant carries a scalar value.

kwargs

• name::String Name of the symbol.
• value::Real Value associated with the symbol. Defaults to 0.
• dtype::Type{AbstractFloat} choose from Float32 or Float64. Default is Float32

Symbolic representation of the C notation *expr.

Devito.Function(; kwargs...)

Tensor symbol representing a discrete function in symbolic equations.

See: https://www.devitoproject.org/devito/function.html?highlight=function#devito.types.Function

Example

x = SpaceDimension(name="x", spacing=Constant(name="h_x", value=5.0))
z = SpaceDimension(name="z", spacing=Constant(name="h_z", value=5.0))
grid = Grid(
    dimensions = (x,z),
    shape = (251,501), # assume x is first, z is second (i.e. z is fast in python)
    origin = (0.0,0.0),
    extent = (1250.0,2500.0),
    dtype = Float32)

b = Devito.Function(name="b", grid=grid, space_order=8)

Grid(; shape[, optional key-word arguments...])

Construct a grid that can be used in the construction of a Devito Functions.

See: https://www.devitoproject.org/devito/grid.html?highlight=grid#devito.types.Grid

Example

x = SpaceDimension(name="x", spacing=Constant(name="h_x", value=5.0))
z = SpaceDimension(name="z", spacing=Constant(name="h_z", value=5.0))
grid = Grid(
    dimensions = (x,z), # z is fast (row-major)
    shape = (251,501),
    origin = (0.0,0.0),
    extent = (1250.0,2500.0),
    dtype = Float32)

Operator(expressions...[; optional named arguments])

Generate, JIT-compile and run C code starting from an ordered sequence of symbolic expressions, and where you provide a list of expressions defining the computation.

See: https://www.devitoproject.org/devito/operator.html?highlight=operator#devito.operator.operator.Operator""

Optional named arguments

• name::String Name of the Operator, defaults to "Kernel".
• subs::Dict Symbolic substitutions to be applied to expressions.
• opt::String The performance optimization level. Defaults to configuration["opt"].
• language::String The target language for shared-memory parallelism. Defaults to configuration["language"].
• platform::String The architecture the code is generated for. Defaults to configuration["platform"].
• compiler::String The backend compiler used to jit-compile the generated code. Defaults to configuration["compiler"].

Example

Assuming that one has constructed the following Devito expressions: stencil_p, src_term and rec_term,

op = Operator([stencil_p, src_term, rec_term]; name="opIso")

Symbolic representation of a pointer in C

SpaceDimension(;kwargs...)

Construct a space dimension that defines the extend of a physical grid.

See https://www.devitoproject.org/devito/dimension.html?highlight=spacedimension#devito.types.dimension.SpaceDimension.

Example

julia x = SpaceDimension(name="x", spacing=Constant(name="h_x", value=5.0))`

SparseFunction(; kwargs...)

Tensor symbol representing a sparse array in symbolic equations.

See: https://www.devitoproject.org/devito/sparsefunction.html

Example

x = SpaceDimension(name="x", spacing=Constant(name="h_x", value=5.0))
z = SpaceDimension(name="z", spacing=Constant(name="h_z", value=5.0))
grid = Grid(
    dimensions = (x,z),
    shape = (251,501), # assume x is first, z is second (i.e. z is fast in python)
    origin = (0.0,0.0),
    extent = (1250.0,2500.0),
    dtype = Float32)

src = SparseFunction(name="src", grid=grid, npoint=1)

SparseTimeFunction(; kwargs...)

Tensor symbol representing a space- and time-varying sparse array in symbolic equations.

See: https://www.devitoproject.org/devito/sparsetimefunction.html?highlight=sparsetimefunction

Example

x = SpaceDimension(name="x", spacing=Constant(name="h_x", value=5.0))
z = SpaceDimension(name="z", spacing=Constant(name="h_z", value=5.0))
grid = Grid(
    dimensions = (x,z),
    shape = (251,501), # assume x is first, z is second (i.e. z is fast in python)
    origin = (0.0,0.0),
    extent = (1250.0,2500.0),
    dtype = Float32)

time_range = 0.0f0:0.5f0:1000.0f0
src = SparseTimeFunction(name="src", grid=grid, npoint=1, nt=length(time_range))

SubDimensionLeft(args...; kwargs...)

Creates middle a SubDimension. Equivalent to devito.SubDimension.left helper function.

Example

x = SpaceDimension(name="x")
xm = SubDimensionLeft(name="xl", parent=x, thickness=2)

SubDimensionMiddle(args...; kwargs...)

Creates middle a SubDimension. Equivalent to devito.SubDimension.middle helper function.

Example

x = SpaceDimension(name="x")
xm = SubDimensionMiddle(name="xm", parent=x, thickness_left=2, thickness_right=3)

SubDimensionRight(args...; kwargs...)

Creates right a SubDimension. Equivalent to devito.SubDimension.right helper function.

Example

x = SpaceDimension(name="x")
xr = SubDimensionRight(name="xr", parent=x, thickness=3)

SubDomain(name, instructions)

Create a subdomain by passing a list of instructions for each dimension. Using an instruction with (nothing,) implies that the whole dimension should be used for that subdomain, as will ("middle",0,0)

Examples:

instructions = ("left",2),("middle",3,3)
SubDomain("subdomain_name",instructions)

or

instructions = [("right",4),("middle",1,2)]
SubDomain("subdomain_name",instructions)

or

SubDomain("subdomain_name",("right",2),("left",1))

TimeFunction(; kwargs...)

Tensor symbol representing a discrete function in symbolic equations.

See https://www.devitoproject.org/devito/timefunction.html?highlight=timefunction#devito.types.TimeFunction.

Example

x = SpaceDimension(name="x", spacing=Constant(name="h_x", value=5.0))
z = SpaceDimension(name="z", spacing=Constant(name="h_z", value=5.0))
grid = Grid(
    dimensions = (x,z),
    shape = (251,501), # assume x is first, z is second (i.e. z is fast in python)
    origin = (0.0,0.0),
    extent = (1250.0,2500.0),
    dtype = Float32)

p = TimeFunction(name="p", grid=grid, time_order=2, space_order=8)