{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# \n",
"\n",
"# Operator\n",
"\n",
"`Operator(self, *args, **kwargs)`\n",
"\n",
"Generate, JIT-compile and run C code starting from an ordered sequence\n",
"of symbolic expressions.\n",
"\n",
"## Parameters\n",
"\n",
"| Name | Type | Description | Default |\n",
"|---|-----|--------------------------------------------------------------|---|\n",
"| `expressions` | expr - like or list or expr - like | The (list of) expression(s) defining the Operator computation. | *required* |\n",
"| `**kwargs` | | \\* name : str Name of the Operator, defaults to “Kernel”. \\* subs : dict Symbolic substitutions to be applied to `expressions`. \\* opt : str The performance optimization level. Defaults to `configuration['opt']`. \\* language : str The target language for shared-memory parallelism. Defaults to `configuration['language']`. \\* platform : str The architecture the code is generated for. Defaults to `configuration['platform']`. \\* compiler : str The backend compiler used to jit-compile the generated code. Defaults to `configuration['compiler']`. | `{}` |\n",
"\n",
"## Examples\n",
"\n",
"The following Operator implements a trivial time-marching method that\n",
"adds 1 to every grid point in `u` at every timestep.\n",
"\n",
"``` python\n",
">>> from devito import Eq, Grid, TimeFunction, Operator\n",
">>> grid = Grid(shape=(4, 4))\n",
">>> u = TimeFunction(name='u', grid=grid)\n",
">>> op = Operator(Eq(u.forward, u + 1))\n",
"```\n",
"\n",
"Multiple expressions can be supplied, and there is no limit to the\n",
"number of expressions in an Operator.\n",
"\n",
"``` python\n",
">>> v = TimeFunction(name='v', grid=grid)\n",
">>> op = Operator([Eq(u.forward, u + 1),\n",
"... Eq(v.forward, v + 1)])\n",
"```\n",
"\n",
"Simple boundary conditions can be imposed easily exploiting the “indexed\n",
"notation” for Functions/TimeFunctions.\n",
"\n",
"``` python\n",
">>> t = grid.stepping_dim\n",
">>> x, y = grid.dimensions\n",
">>> op = Operator([Eq(u.forward, u + 1),\n",
"... Eq(u[t+1, x, 0], 0),\n",
"... Eq(u[t+1, x, 2], 0),\n",
"... Eq(u[t+1, 0, y], 0),\n",
"... Eq(u[t+1, 2, y], 0)])\n",
"```\n",
"\n",
"A semantically equivalent computation can be expressed exploiting\n",
"SubDomains.\n",
"\n",
"``` python\n",
">>> u.data[:] = 0\n",
">>> op = Operator(Eq(u.forward, u + 1, subdomain=grid.interior))\n",
"```\n",
"\n",
"By specifying a SubDomain, the Operator constrains the execution of an\n",
"expression to a certain sub-region within the computational domain.\n",
"Ad-hoc SubDomains can also be created in application code – refer to the\n",
"SubDomain documentation for more info.\n",
"\n",
"Advanced boundary conditions can be expressed leveraging `SubDomain` and\n",
"`SubDimension`.\n",
"\n",
"Tensor contractions are supported, but with one caveat: in case of MPI\n",
"execution, any global reductions along an MPI-distributed Dimension\n",
"should be handled explicitly in user code. The following example shows\n",
"how to implement the matrix-vector multiplication `Av = b` (inducing a\n",
"reduction along `y`).\n",
"\n",
"``` python\n",
">>> from devito import Inc, Function\n",
">>> A = Function(name='A', grid=grid)\n",
">>> v = Function(name='v', shape=(3,), dimensions=(y,))\n",
">>> b = Function(name='b', shape=(3,), dimensions=(x,))\n",
">>> op = Operator(Inc(b, A*v))\n",
"```\n",
"\n",
"Dense and sparse computation may be present within the same Operator. In\n",
"the following example, interpolation is used to approximate the value of\n",
"four sparse points placed at the center of the four quadrants at the\n",
"grid corners.\n",
"\n",
"``` python\n",
">>> import numpy as np\n",
">>> from devito import SparseFunction\n",
">>> grid = Grid(shape=(4, 4), extent=(3.0, 3.0))\n",
">>> f = Function(name='f', grid=grid)\n",
">>> coordinates = np.array([(0.5, 0.5), (0.5, 2.5), (2.5, 0.5), (2.5, 2.5)])\n",
">>> sf = SparseFunction(name='sf', grid=grid, npoint=4, coordinates=coordinates)\n",
">>> op = Operator([Eq(f, f + 1)] + sf.interpolate(f))\n",
"```\n",
"\n",
"The iteration direction is automatically detected by the Devito\n",
"compiler. Below, the Operator runs from `time_M` (maximum point in the\n",
"time dimension) down to `time_m` (minimum point in the time dimension),\n",
"as opposed to all of the examples seen so far, in which the execution\n",
"along time proceeds from `time_m` to `time_M` through unit-step\n",
"increments.\n",
"\n",
"``` python\n",
">>> op = Operator(Eq(u.backward, u + 1))\n",
"```\n",
"\n",
"Loop-level optimisations, including SIMD vectorisation and OpenMP\n",
"parallelism, are automatically discovered and handled by the Devito\n",
"compiler. For more information, refer to the relevant documentation.\n",
"\n",
"## Attributes\n",
"\n",
"| Name | Description |\n",
"|------------------------------------|------------------------------------|\n",
"| [cfunction](#devito.Operator.cfunction) | The JIT-compiled C function as a ctypes.FuncPtr object. |\n",
"\n",
"## Methods\n",
"\n",
"| Name | Description |\n",
"|------------------------------------|------------------------------------|\n",
"| [apply](#devito.Operator.apply) | Execute the Operator. |\n",
"| [arguments](#devito.Operator.arguments) | Arguments to run the Operator. |\n",
"| [cinterface](#devito.Operator.cinterface) | Generate two files under the prescribed temporary directory: |\n",
"\n",
"### apply\n",
"\n",
"`apply(**kwargs)`\n",
"\n",
"Execute the Operator.\n",
"\n",
"With no arguments provided, the Operator runs using the data carried by\n",
"the objects appearing in the input expressions – these are referred to\n",
"as the “default arguments”.\n",
"\n",
"Optionally, any of the Operator default arguments may be replaced by\n",
"passing suitable key-value arguments. Given `apply(k=v, ...)`, `(k, v)`\n",
"may be used to:\n",
"\n",
"- replace a Constant. In this case, `k` is the name of the Constant,\n",
" `v` is either a Constant or a scalar value.\n",
"\n",
"- replace a Function (SparseFunction). Here, `k` is the name of the\n",
" Function, `v` is either a Function or a numpy.ndarray.\n",
"\n",
"- alter the iteration interval along a Dimension. Consider a generic\n",
" Dimension `d` iterated over by the Operator. By default, the\n",
" Operator runs over all iterations within the compact interval\n",
" `[d_m, d_M]`, where `d_m` and `d_M` are, respectively, the smallest\n",
" and largest integers not causing out-of-bounds memory accesses (for\n",
" the Grid Dimensions, this typically implies iterating over the\n",
" entire physical domain). So now `k` can be either `d_m` or `d_M`,\n",
" while `v` is an integer value.\n",
"\n",
"#### Examples\n",
"\n",
"Consider the following Operator\n",
"\n",
"``` python\n",
">>> from devito import Eq, Grid, TimeFunction, Operator\n",
">>> grid = Grid(shape=(3, 3))\n",
">>> u = TimeFunction(name='u', grid=grid, save=3)\n",
">>> op = Operator(Eq(u.forward, u + 1))\n",
"```\n",
"\n",
"The Operator is run by calling `apply`\n",
"\n",
"``` python\n",
">>> summary = op.apply()\n",
"```\n",
"\n",
"The variable `summary` contains information about runtime performance.\n",
"As no key-value parameters are specified, the Operator runs with its\n",
"default arguments, namely\n",
"`u=u, x_m=0, x_M=2, y_m=0, y_M=2, time_m=0, time_M=1`.\n",
"\n",
"At this point, the same Operator can be used for a completely different\n",
"run, for example\n",
"\n",
"``` python\n",
">>> u2 = TimeFunction(name='u', grid=grid, save=5)\n",
">>> summary = op.apply(u=u2, x_m=1, y_M=1)\n",
"```\n",
"\n",
"Now, the Operator will run with a different set of arguments, namely\n",
"`u=u2, x_m=1, x_M=2, y_m=0, y_M=1, time_m=0, time_M=3`.\n",
"\n",
"To run an Operator that only uses buffered TimeFunctions, the maximum\n",
"iteration point along the time dimension must be explicitly specified\n",
"(otherwise, the Operator wouldn’t know how many iterations to run).\n",
"\n",
"``` python\n",
">>> u3 = TimeFunction(name='u', grid=grid)\n",
">>> op = Operator(Eq(u3.forward, u3 + 1))\n",
">>> summary = op.apply(time_M=10)\n",
"```\n",
"\n",
"### arguments\n",
"\n",
"`arguments(**kwargs)`\n",
"\n",
"Arguments to run the Operator.\n",
"\n",
"### cinterface\n",
"\n",
"`cinterface(force=False)`\n",
"\n",
"Generate two files under the prescribed temporary directory:\n",
"\n",
" * `X.c` (or `X.cpp`): the code generated for this Operator;\n",
" * `X.h`: an header file representing the interface of `X.c`.\n",
"\n",
"Where `X=self.name`.\n",
"\n",
"#### Parameters\n",
"\n",
"| Name | Type | Description | Default |\n",
"|---------|------|--------------------------------------------------|---------|\n",
"| `force` | bool | Overwrite any existing files. Defaults to False. | `False` |"
],
"id": "d2ffb18b-dcca-459a-bc2a-70d3cec67fd2"
}
],
"nbformat": 4,
"nbformat_minor": 5,
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
}
}
}