TimeFunction¶

class
devito.types.
TimeFunction
(*args, **kwargs)[source]¶ Bases:
devito.types.dense.Function
Tensor symbol representing a space and timevarying array in symbolic equations.
A TimeFunction carries multidimensional data and provides operations to create finitedifferences approximations, in both space and time.
 Parameters
name (str) – Name of the symbol.
grid (Grid, optional) – Carries shape, dimensions, and dtype of the Function. When grid is not provided, shape and dimensions must be given. For MPI execution, a Grid is compulsory.
space_order (int or 3tuple of ints, optional) – Discretisation order for space derivatives. Defaults to 1.
space_order
also impacts the number of points available around a generic point of interest. By default,space_order
points are available on both sides of a generic point of interest, including those nearby the grid boundary. Sometimes, fewer points suffice; in other scenarios, more points are necessary. In such cases, instead of an integer, one can pass a 3tuple(o, lp, rp)
indicating the discretization order (o
) as well as the number of points on the left (lp
) and right (rp
) sides of a generic point of interest.time_order (int, optional) – Discretization order for time derivatives. Defaults to 1.
shape (tuple of ints, optional) – Shape of the domain region in grid points. Only necessary if grid isn’t given.
dimensions (tuple of Dimension, optional) – Dimensions associated with the object. Only necessary if grid isn’t given.
dtype (datatype, optional) – Any object that can be interpreted as a numpy data type. Defaults to np.float32.
save (int or Buffer, optional) – By default,
save=None
, which indicates the use of alternating buffers. This enables cyclic writes to the TimeFunction. For example, if the TimeFunctionu(t, x)
has shape (3, 100), then, in an Operator,t
will assume the values1, 2, 0, 1, 2, 0, 1, ...
(note that the very first value depends on the stencil equation in whichu
is written.). The default size of the time buffer whensave=None
istime_order + 1
. To specify a different size for the time buffer, one should use the syntaxsave=Buffer(mysize)
. Alternatively, if all of the intermediate results are required (or, simply, to avoid using an alternating buffer), an explicit value forsave
( an integer) must be provided.time_dim (Dimension, optional) – TimeDimension to be used in the TimeFunction. Defaults to
grid.time_dim
.staggered (Dimension or tuple of Dimension or Stagger, optional) – Define how the Function is staggered.
padding (int or tuple of ints, optional) – Allocate extra grid points to maximize data access alignment. When a tuple of ints, one int per Dimension should be provided.
initializer (callable or any object exposing the buffer interface, optional) – Data initializer. If a callable is provided, data is allocated lazily.
allocator (MemoryAllocator, optional) – Controller for memory allocation. To be used, for example, when one wants to take advantage of the memory hierarchy in a NUMA architecture. Refer to default_allocator.__doc__ for more information.
Examples
Creation
>>> from devito import Grid, TimeFunction >>> grid = Grid(shape=(4, 4)) >>> f = TimeFunction(name='f', grid=grid) >>> f f(t, x, y) >>> g = TimeFunction(name='g', grid=grid, time_order=2) >>> g g(t, x, y)
Firstorder derivatives through centered finitedifference approximations
>>> f.dx f(t, x, y)/h_x + f(t, x + h_x, y)/h_x >>> f.dt f(t, x, y)/dt + f(t + dt, x, y)/dt >>> g.dt 0.5*g(t  dt, x, y)/dt + 0.5*g(t + dt, x, y)/dt
When using the alternating buffer protocol, the size of the time dimension is given by
time_order + 1
>>> f.shape (2, 4, 4) >>> g.shape (3, 4, 4)
One can drop the alternating buffer protocol specifying a value for
save
>>> h = TimeFunction(name='h', grid=grid, save=20) >>> h h(time, x, y) >>> h.shape (20, 4, 4)
Notes
The parameters must always be given as keyword arguments, since SymPy uses
*args
to (re)create the dimension arguments of the symbolic object. If the parametergrid
is provided, the values forshape
,dimensions
anddtype
will be derived from it. When present, the parametershape
should only define the spatial shape of the grid. The temporal dimension will be inserted automatically as the leading dimension.
avg
(p=None, dims=None)¶ Generate a symbolic expression computing the average of
p
points along the spatial dimensionsdims
. Parameters
p (int, optional) – The number of summands. Defaults to the halo size.
dims (tuple of Dimension, optional) – The Dimensions along which the average is computed. Defaults to
self
’s spatial dimensions.

backward
¶ Symbol for the timebackward state of the TimeFunction.

data
¶ The domain data values, as a numpy.ndarray.
Elements are stored in rowmajor format.
Notes
With this accessor you are claiming that you will modify the values you get back. If you only need to look at the values, use
data_ro()
instead.

data_domain
¶ The domain data values.
Elements are stored in rowmajor format.
Notes
Alias to
self.data
.With this accessor you are claiming that you will modify the values you get back. If you only need to look at the values, use
data_ro_domain()
instead.

data_ro_domain
¶ Readonly view of the domain data values.

data_ro_with_halo
¶ Readonly view of the domain+outhalo data values.

data_with_halo
¶ The domain+outhalo data values.
Elements are stored in rowmajor format.
Notes
With this accessor you are claiming that you will modify the values you get back. If you only need to look at the values, use
data_ro_with_halo()
instead.

dimensions
¶ Tuple of Dimensions representing the object indices.

dtype
¶ The data type of the object.

forward
¶ Symbol for the timeforward state of the TimeFunction.

grid
¶ The Grid on which the discretization occurred.

name
¶ The name of the object.

shape
¶ Shape of the domain region. The domain constitutes the area of the data written to by an Operator.
Notes
In an MPI context, this is the local domain region shape.

shape_allocated
¶ Shape of the allocated data. It includes the domain and inhalo regions, as well as any additional padding surrounding the halo.
Notes
In an MPI context, this is the local with_halo region shape.

shape_global
¶ Global shape of the domain region. The domain constitutes the area of the data written to by an Operator.
Notes
In an MPI context, this is the global domain region shape, which is therefore identical on all MPI ranks.

shape_with_halo
¶ Shape of the domain+outhalo region. The outhalo is the region surrounding the domain that may be read by an Operator.
Notes
In an MPI context, this is the local with_halo region shape. Further, note that the outhalo of inner ranks is typically empty, while the outhalo of boundary ranks contains a number of elements depending on the rank position in the decomposed grid (corner, side, …).

space_dimensions
¶ Tuple of Dimensions defining the physical space.

space_order
¶ The space order.

sum
(p=None, dims=None)¶ Generate a symbolic expression computing the sum of
p
points along the spatial dimensionsdims
. Parameters
p (int, optional) – The number of summands. Defaults to the halo size.
dims (tuple of Dimension, optional) – The Dimensions along which the sum is computed. Defaults to
self
’s spatial dimensions.

time_order
¶ The time order.