Region basics¶

An object on which finite difference mesh, and accordingly, finite difference field are based is Region. In this tutorial, we show how to define a region as well as some basic operations.

Region is always cubic and it can be defined by any two diagonally opposite corner points. For instance, let us assume we have a region in Cartesian coordinates with edge lengths:

$$l_{x} = 100 \,\text{nm}$$$$l_{y} = 50 \,\text{nm}$$$$l_{z} = 20 \,\text{nm}$$

In order to define this region we need to choose two diagonally opposite corner points. There are many possibilities, but it is up to us which corner points we are going to choose as well as where we are going to position our region in Cartesian coordinate system. Most often, we choose either:

$$p_{1} = (0, 0, 0)$$$$p_{2} = (l_{x}, l_{y}, l_{z})$$

or

$$p_{1} = \left(-\frac{l_{x}}{2}, -\frac{l_{y}}{2}, -\frac{l_{z}}{2}\right)$$$$p_{2} = \left(\frac{l_{x}}{2}, \frac{l_{y}}{2}, \frac{l_{z}}{2}\right)$$

For simplicity, we are going to position $p_{1}$ at the origin of the coordinate system.

We define points as length-3 tuples and pass them to Region object via p1 and p2 arguments.

In [1]:

import discretisedfield as df  # df is here chosen to be an alias for discretisedfield

p1 = (0, 0, 0)
p2 = (100e-9, 50e-9, 20e-9)

region = df.Region(p1=p1, p2=p2)

(All units are SI and no prefixes are assumed. Therefore $1 \,\text{nm}$ is 1e-9.)

The region is now defined. Now, we are going to have a look at some basic methods (functions) which are part of the Region object.

We can ask the region to give us the minimum and maximum points in the region.

In [2]:

region.pmin

Out[2]:

(0.0, 0.0, 0.0)

In [3]:

region.pmax

Out[3]:

(1e-07, 5e-08, 2e-08)

In our case $p_\text{min} = p_{1}$ and $p_\text{max} = p_{2}$, only because of our choice of diagonally opposite points of the cubic region. In general, this is not the case, since we could have chosen any two points for $p_{1}$ and $p_{2}$.

Now we can ask the region to give us the edge lengths of the region (based on $p_{1}$ and $p_{2}$ we used at the definition).

In [4]:

region.edges

Out[4]:

(1e-07, 5e-08, 2e-08)

These lengths correspond to $l_{x}$, $l_{y}$, and $l_{z}$ we discussed earlier.

Similarly, we can ask for a centre point in the region (cross section point of all diagonals).

In [5]:

region.centre

Out[5]:

(5e-08, 2.5e-08, 1e-08)

Obviously, centre point we got is:

$$p_\text{c} = (\frac{l_{x}}{2}, \frac{l_{y}}{2}, \frac{l_{z}}{2})$$

The volume of the region is:

In [6]:

region.volume

Out[6]:

9.999999999999998e-23

This value is in $\text{m}^{3}$ and it is calculated as

$$V=l_{x}l_{y}l_{z}$$

Now, let us say we have a point $p$ and want to check if that point is in our region. We can do that using in. For instance, if our point is $p = (2\,\text{nm}, 4\,\text{nm}, 1\,\text{nm})$, we can ask the region if point $p$ is in it.

In [7]:

p = (2e-9, 4e-9, 1e-9)

p in region

Out[7]:

True

As a result, we get bool (either True or False). This can be useful, when we want to use these expressions as conditions for some more complex functions. For example:

In [8]:

if p in region:
    print("Point: I'm in! :)")
else:
    print("Point: I'm out! :(")

Point: I'm in! :)

On the other hand, we could have chosen a point which is outside of our region:

In [9]:

(1e-9, 200e-9, 0) in region

Out[9]:

False

Sometimes, we want any point which belongs to the region (usually for testing purposes) and we are too lazy to think. We can then ask the region to give us a random point.

In [10]:

# NBVAL_IGNORE_OUTPUT
region.random_point()

Out[10]:

(8.807246802450429e-08, 4.9394886042542286e-08, 8.683419701051645e-09)

Please note, that random_point is a function and not a property, unlike all the values we have looked at before. Therefore, we have to call it with parenthesis ().

Sometimes we want to check if two regions are the same. We can do that using relational == operator. Let us define two regions: one which is the same to the one we have and one different:

In [11]:

region_same = df.Region(p1=(0, 0, 0), p2=(100e-9, 50e-9, 20e-9))
region_different = df.Region(p1=(0, 0, 0), p2=(10e-9, 5e-9, 2e-9))

Now we can compare them:

In [12]:

region == region_same

Out[12]:

True

In [13]:

region == region_different

Out[13]:

False

Just like in operator, == returns bool. Similarly, we can ask if two regions are different:

In [14]:

region != region_same

Out[14]:

False

In [15]:

region != region_different

Out[15]:

True

Finally, we can ask the region object about its representation string:

In [16]:

repr(region)

Out[16]:

'Region(p1=(0, 0, 0), p2=(1e-07, 5e-08, 2e-08))'

In a jupyter notebook we can get a pretier version:

In [17]:

region

Out[17]:

Region

p1 = (0, 0, 0)
p2 = (1e-07, 5e-08, 2e-08)