The first compilation pass is named lowering, and three main tasks are carried out: indexification, substitution, and domain-alignment. In this notebook, we will explore the Indexification step.

Indexification

The indexification consists of converting Functions into Indexeds, that is actual array accesses. An Indexed always keeps a reference to its originating Function. For instance, all accesses to u such as u[t, x + 1] and u[t + 1, x − 2] would store a pointer to the same, user-defined Function u(t, x). This metadata is exploited throughout the various compilation passes.

To see this, let's create a TimeFunction named u.



In [1]:

    
from devito import Grid, TimeFunction
u = TimeFunction(name='u', grid=Grid((3,)), save=1)
print(u)









    



u(time, x)

Note that u has one temporal dimension and one spatial dimension, that we will call time and x here, respectively.



In [2]:

    
time, x = u.dimensions
time, x









    Out[2]:





(time, x)

Functions (of type Function, TimeFunction and SparseFunction) can be indexified in two equivalent ways, either via the .indexify() method, as illustrated below, or via explicit indexing, as typically done in user code.



In [3]:

    
u_i = u.indexify() # For more details about the method `indexify`, see `devito/symbolics/manipulation.py`
print(u_i)









    



u[time, x]

Now, dimensions are interpreted as indices.



In [4]:

    
u_i.indices == u.dimensions









    Out[4]:





True

The explicit indexing mode is when you write



In [5]:

    
a = u[time,x+1]

and you get exactly (representation shown below)



In [6]:

    
print(a)









    



u[time, x + 1]

ie, this is totally equivalent to indexify. Another example, you can write



In [7]:

    
b = u[time+1,x-2]

and you get



In [8]:

    
print(b)









    



u[time + 1, x - 2]

Clearly, we now have that



In [9]:

    
a.indices == b.indices









    Out[9]:





False

Thus



In [10]:

    
a == b









    Out[10]:





False

However, we can verify that these accesses still point to the very same TimeFunction object.



In [11]:

    
a.function is b.function









    Out[11]:





True

Note also that there is no data associated with Indexed objects.



In [12]:

    
type(u_i)
# u_i.data   # This should return an error!









    Out[12]:





devito.types.basic.Indexed

The data representing the grid is accessed through the Function that the indices point to.



In [13]:

    
u_i.function.data









    Out[13]:





Data([[0., 0., 0.]], dtype=float32)