# TimeFunction

`TimeFunction(self, *args, **kwargs)`

Tensor symbol representing a discrete function in symbolic equations.

A TimeFunction carries multi-dimensional data and provides operations to create finite-differences approximations, in both space and time.

A TimeFunction encapsulates space- and time-varying data.

## Parameters

Name | Type | Description | Default |
---|---|---|---|

`name` |
str | Name of the symbol. | required |

`grid` |
Grid | 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. | required |

`space_order` |
int or 3-tuple of ints | Discretisation order for space derivatives. `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 3-tuple `(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; * a 2-tuple `(o, ((lp0, rp0), (lp1, rp1), ...))` indicating the discretization order (`o` ) as well as the number of points on the left/right sides of a generic point of interest for each SpaceDimension. |
`1` |

`time_order` |
int | Discretization order for time derivatives. Defaults to 1. | required |

`shape` |
tuple of ints | Shape of the domain region in grid points. Only necessary if `grid` isn’t given. |
required |

`dimensions` |
tuple of Dimension | Dimensions associated with the object. Only necessary if `grid` isn’t given. |
required |

`dtype` |
devito.data - type | Any object that can be interpreted as a numpy data type. | `np.float32` |

`save` |
int or devito.types.utils.Buffer | By default, `save=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 avoid using an alternating buffer), an explicit value for `save` ( an integer) must be provided. |
`None` |

`time_dim` |
devito.types.dimension.Dimension | TimeDimension to be used in the TimeFunction. | `grid.time_dim` |

`staggered` |
Dimension or tuple of Dimension or Stagger | Define how the Function is staggered. | `None` |

`initializer` |
callable or any object exposing the buffer interface | Data initializer. If a callable is provided, data is allocated lazily. | `None` |

`allocator` |
MemoryAllocator | 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. |
required |

`padding` |
int or tuple of ints | Allocate extra grid points to maximize data access alignment. When a tuple of ints, one int per Dimension should be provided. | required |

## 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)
```

First-order derivatives through centered finite-difference approximations

```
>>> f.dx
Derivative(f(t, x, y), x)>>> f.dt
Derivative(f(t, x, y), t)>>> g.dt
Derivative(g(t, x, y), t)
```

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 parameter `grid`

is provided, the values for `shape`

, `dimensions`

and `dtype`

will be derived from it. When present, the parameter `shape`

should only define the spatial shape of the grid. The temporal dimension will be inserted automatically as the leading dimension.

## Attributes

Name | Description |
---|---|

backward | Symbol for the time-backward state of the TimeFunction. |

forward | Symbol for the time-forward state of the TimeFunction. |

is_TimeDependent | bool(x) -> bool |

is_TimeFunction | bool(x) -> bool |

time_order | The time order. |