Region#

class discretisedfield.Region(p1=None, p2=None, dims=None, units=None, tolerance_factor=1e-12, **kwargs)#

Region.

A cuboid region spans between two corner points \(\mathbf{p}_1\) and \(\mathbf{p}_2\). Points p1 and p2 can be any two diagonally-opposite points. If any of the edge lengths of the cuboid region is zero, ValueError is raised.

Parameters:

  • p2 (p1 /) – Diagonally-opposite corner points of the region, for example in three dimensions \(\mathbf{p}_i = (p_x, p_y, p_z)\).

  • dims (array_like of str, optional) –

    Name of the respective geometrical dimensions of the region.

    Up to three dimensions, this defaults to x, y, and z. For more than three dimensions, it defaults to x1, x2, x3, x4, etc.

  • units (array_like of str, optional) – Physical units of the region. This is mainly used for labelling plots. Defaults to m for all the dimensions.

  • tolerance_factor (float, optional) – This factor is used to obtain a tolerance for comparison operations, e.g. region1 in region2. It is internally multiplied with the minimum of the edge lengths to adjust the tolerance to the region size and have more accurate floating-point comparisons. Defaults to 1e-12.

Raises:

ValueError – If any of the region’s edge lengths is zero.

Examples

  1. Defining a nano-sized region.

>>> import discretisedfield as df
...
>>> p1 = (-50e-9, -25e-9, 0)
>>> p2 = (50e-9, 25e-9, 5e-9)
>>> region = df.Region(p1=p1, p2=p2)
...
>>> region
Region(...)

  1. An attempt to define a region whose one of the edge lengths is zero.

>>> # The edge length in the z-direction is zero.
>>> p1 = (-25, 3, 1)
>>> p2 = (25, 6, 1)
>>> region = df.Region(p1=p1, p2=p2)
Traceback (most recent call last):
    ...
ValueError: ...

Methods

__contains__

Determine if a point or another region belong to the region.

__dir__

Default dir() implementation.

__eq__

Relational operator ==.

__or__

Old implementation to find facing surfaces.

__repr__

Representation string.

allclose

Check if two regions are close.

facing_surface

Facing surface.

random_point

Return a random point in the region.

rotate90

Rotate region by 90 degrees.

scale

Scale the region.

to_dict

Convert region object to dict.

translate

Translate the region.

Properties

center

Center point.

centre

dims

Names of the region's dimensions.

edges

Region's edge lengths.

k3d

k3d plot.

mpl

matplotlib plot.

multiplier

Compute multiplier for the region.

ndim

Number of dimensions.

pmax

Point with maximum coordinates in the region.

pmin

Point with minimum coordinates in the region.

tolerance_factor

Tolerance factor for floating-point comparisons.

units

Units of the region's dimensions.

volume

Region's volume.
__contains__(other)#

Determine if a point or another region belong to the region.

Point is considered to be in the region if

\[p^\text{min}_{i} \le p_{i} \le p^\text{max}_{i}, \text{for}\, i in dims.\]

Similarly, if the second operand is discretisedfield.Region object, it is considered to be in the region if both its pmin and pmax belong to the region.

Parameters:

other (array_like or discretisedfield.Region) – The point coordinate (E.g. in three dimensions \((p_{x}, p_{y}, p_{z})\)) or a region object.

Returns:

True if other is inside the region and False otherwise.

Return type:

bool

Example

  1. Check if point is inside the region.

>>> import discretisedfield as df
...
>>> p1 = (0, 0, 0)
>>> p2 = (2, 2, 1)
>>> region = df.Region(p1=p1, p2=p2)
>>> (1, 1, 1) in region
True
>>> (1, 3, 1) in region
False
>>> # corner points are considered to be in the region
>>> p1 in region
True
>>> p2 in region
True

  1. Check if another region belongs to the region.

>>> df.Region(p1=(0, 0, 0), p2=(1, 1, 1)) in region
True
>>> df.Region(p1=(0, 0, 0), p2=(2, 2, 2)) in region
False
>>> # Region is considered to be in itself
>>> region in region
True
__eq__(other)#

Relational operator ==.

Two regions are considered to be equal if they have the same minimum and maximum coordinate points, the same units, and the same dimension names.

Parameters:

other (discretisedfield.Region) – Second operand.

Returns:

True if two regions are equal and False otherwise.

Return type:

bool

Examples

  1. Usage of relational operator ==.

>>> import discretisedfield as df
...
>>> region1 = df.Region(p1=(0, 0, 0), p2=(5, 5, 5))
>>> region2 = df.Region(p1=(0.0, 0, 0), p2=(5.0, 5, 5))
>>> region3 = df.Region(p1=(1, 1, 1), p2=(5, 5, 5))
...
>>> region1 == region2
True
>>> region1 != region2
False
>>> region1 == region3
False
>>> region1 != region3
True
__or__(other)#

Old implementation to find facing surfaces.

__repr__()#

Representation string.

Internally self._repr_html_() is called and all html tags are removed from this string.

Returns:

Representation string.

Return type:

str

Example

  1. Getting representation string.

>>> import discretisedfield as df
...
>>> p1 = (0, 0, 0)
>>> p2 = (2, 2, 1)
>>> region = df.Region(p1=p1, p2=p2)
...
>>> region
Region(pmin=[0, 0, 0], pmax=[2, 2, 1], ...)
allclose(other, rtol=None, atol=None)#

Check if two regions are close.

Two regions are considered to be equal if they have the same minimum and maximum coordinate points: \(\mathbf{p}^\text{max}_1 = \mathbf{p}^\text{max}_2\) and \(\mathbf{p}^\text{min}_1 = \mathbf{p}^\text{min}_2\) within a tolerance.

Parameters:

  • other (discretisedfield.Region) – Second operand.

  • atol (numbers.Number, optional) – Absolute tolerance. If None, the default value is the smallest edge length of the region multiplied by the tolerance factor.

  • rtol (numbers.Number, optional) – Relative tolerance. If None, region.tolerance_factor is used.

Returns:

True if two regions are equal (within floating-point accuracy) and False otherwise.

Return type:

bool

Examples

  1. Usage of allclose method.

>>> import discretisedfield as df
...
>>> region1 = df.Region(p1=(0, 0, 0), p2=(5, 5, 5))
>>> region2 = df.Region(p1=(0.0, 0, 0), p2=(5.0, 5, 5))
>>> region3 = df.Region(p1=(1, 1, 1), p2=(5, 5, 5))
...
>>> region1.allclose(region2)
True
>>> region1.allclose(region3)
False
>>> region2.allclose(region3)
False
facing_surface(other)#

Facing surface.

Parameters:

other (discretisedfield.Region) – Second operand.

Returns:

tuple – The first element is the axis facing surfaces are perpendicular to. If we start moving along that axis (e.g. from minus infinity) the first region we are going to enter is the region which is the second element of the tuple. When we leave that region, we enter the second region, which is the third element of the tuple.

Return type:

(ndims,)

Examples

  1. Find facing surfaces.

>>> import discretisedfield as df
...
>>> p11 = (0, 0, 0)
>>> p12 = (100e-9, 50e-9, 20e-9)
>>> region1 = df.Region(p1=p11, p2=p12)
...
>>> p21 = (0, 0, 20e-9)
>>> p22 = (100e-9, 50e-9, 30e-9)
>>> region2 = df.Region(p1=p21, p2=p22)
...
>>> res = region1.facing_surface(region2)
>>> res[0]
'z'
>>> res[1] == region1
True
>>> res[2] == region2
True
random_point()#

Return a random point in the region.

rotate90(ax1, ax2, k=1, reference_point=None, inplace=False)#

Rotate region by 90 degrees.

Rotate the region k times by 90 degrees in the plane defined by ax1 and ax2. The rotation direction is from ax1 to ax2, the two must be different.

Parameters:

  • ax1 (str) – Name of the first dimension.

  • ax2 (str) – Name of the second dimension.

  • k (int, optional) – Number of 90° rotations, defaults to 1.

  • reference_point (array_like, optional) – Point around which the region is rotated. If not provided the region’s centre point is used.

  • inplace (bool, optional) – If True, the rotation is applied in-place. Defaults to False.

Returns:

The rotated region object. Either a new object or a reference to the existing region for inplace=True.

Return type:

discretisedfield.Region

Examples

>>> import discretisedfield as df
>>> import numpy as np
>>> p1 = (0, 0, 0)
>>> p2 = (10, 8, 6)
>>> region = df.Region(p1=p1, p2=p2)
>>> rotated = region.rotate90('x', 'y')
>>> rotated.pmin
array([ 1., -1.,  0.])
>>> rotated.pmax
array([9., 9., 6.])

See also

rotate90(), rotate90()

scale(factor, reference_point=None, inplace=False)#

Scale the region.

This method scales the region about its center point or a reference_point if provided. If factor is a number the same scaling is applied along all dimensions. If factor is array-like its length must match region.ndim and different factors are applied along the different directions (based on their order). A new object is created unless inplace=True is specified.

Parameters:

  • factor (numbers.Real or array-like of numbers.Real) – Factor to scale the region.

  • reference_point (array_like, optional) – The position of the reference point is fixed when scaling the region. If not specified the region is scaled about its center.

  • inplace (bool, optional) – If True, the Region object is modified in-place. Defaults to False.

Returns:

Resulting region.

Return type:

discretisedfield.Region

Raises:

ValueError, TypeError – If the operator cannot be applied.

Example

  1. Scale region uniformly.

>>> import discretisedfield as df
>>> p1 = (0, 0, 0)
>>> p2 = (10, 10, 10)
>>> region = df.Region(p1=p1, p2=p2)
>>> res = region.scale(5)
>>> res.pmin
array([-20., -20., -20.])
>>> res.pmax
array([30., 30., 30.])

  1. Scale the region inplace.

>>> import discretisedfield as df
>>> p1 = (-10, -10, -10)
>>> p2 = (10, 10, 10)
>>> region = df.Region(p1=p1, p2=p2)
>>> region.scale(5, inplace=True)
Region(...)
>>> region.pmin
array([-50., -50., -50.])
>>> region.pmax
array([50., 50., 50.])

  1. Scale region with different factors along different directions.

>>> import discretisedfield as df
>>> p1 = (0, 0, 0)
>>> p2 = (10, 10, 10)
>>> region = df.Region(p1=p1, p2=p2)
>>> res = region.scale((2, 3, 4))
>>> res.pmin
array([ -5., -10., -15.])
>>> res.pmax
array([15., 20., 25.])
to_dict()#

Convert region object to dict.

Convert region object to dict with items pmin, pmax, dims, units, and tolerance_factor.

translate(vector, inplace=False)#

Translate the region.

This method translates the region by adding vector to pmin and pmax. The vector must have Region.ndim elements. A new object is created unless inplace=True is specified.

Parameters:

  • vector (array-like of numbers.Number) – Vector to translate the region.

  • inplace (bool, optional) – If True, the Region object is modified in-place. Defaults to False.

Returns:

Resulting region.

Return type:

discretisedfield.Region

Raises:

ValueError, TypeError – If the operator cannot be applied.

Examples

  1. Translate the region.

>>> import discretisedfield as df
>>> p1 = (0, 0, 0)
>>> p2 = (10, 10, 10)
>>> region = df.Region(p1=p1, p2=p2)
>>> res = region.translate((2, -2, 5))
>>> res.pmin
array([ 2, -2,  5])
>>> res.pmax
array([12,  8, 15])

  1. Translate the region inplace.

>>> import discretisedfield as df
>>> p1 = (0, 0, 0)
>>> p2 = (10, 10, 10)
>>> region = df.Region(p1=p1, p2=p2)
>>> region.translate((2, -2, 5), inplace=True)
Region(...)
>>> region.pmin
array([ 2, -2,  5])
>>> region.pmax
array([12,  8, 15])
__hash__ = None#
property center#

Center point.

Center point is computed as the middle point between region’s points with minimum and maximum coordinates:

\[\mathbf{p}_\text{center} = \frac{1}{2} (\mathbf{p}_\text{min} + \mathbf{p}_\text{max}).\]
Returns:

Center point. E.g. in three dimensions \((p_c^x, p_c^y, p_c^z)\).

Return type:

numpy.ndarray

Examples

  1. Getting the center point.

>>> import discretisedfield as df
...
>>> p1 = (0, 0, 0)
>>> p2 = (5, 15, 20)
>>> region = df.Region(p1=p1, p2=p2)
...
>>> region.center
array([ 2.5,  7.5, 10. ])
property dims#

Names of the region’s dimensions.

Returns:

Names of the region’s dimensions.

Return type:

tuple of str

Examples

  1. Getting region’s dimension names.

>>> import discretisedfield as df
...
>>> p1 = (-1.1, 2.9, 0)
>>> p2 = (5, 0, -0.1)
>>> region = df.Region(p1=p1, p2=p2)
...
>>> region.dims
('x', 'y', 'z')

See also

ndim()

property edges#

Region’s edge lengths.

Edge length is computed from the points between which the region spans \(\mathbf{p}_1\) and \(\mathbf{p}_2\):

\[\mathbf{l} = (|p_2^x - p_1^x|, |p_2^y - p_1^y|, |p_2^z - p_1^z|).\]
Returns:

Edge lengths. E.g. in three dimensions \((l_{x}, l_{y}, l_{z})\).

Return type:

numpy.ndarray

Examples

  1. Getting edge lengths of the region.

>>> import discretisedfield as df
...
>>> p1 = (0, 0, -5)
>>> p2 = (5, 15, 15)
>>> region = df.Region(p1=p1, p2=p2)
...
>>> region.edges
array([ 5, 15, 20])
property k3d#

k3d plot.

If plot is not passed, k3d.Plot object is created automatically. The colour of the region can be specified using color argument.

For details about multiplier, please refer to discretisedfield.Region.mpl.

This method is based on k3d.voxels, so any keyword arguments accepted by it can be passed (e.g. wireframe).

Parameters:

  • plot (k3d.Plot, optional) – Plot to which the plot is added. Defaults to None - plot is created internally.

  • color (int, optional) – Colour of the region. Defaults to the default color palette.

  • multiplier (numbers.Real, optional) – Axes multiplier. Defaults to None.

Examples

  1. Visualising the region using k3d.

>>> import discretisedfield as df
...
>>> p1 = (-50e-9, -50e-9, 0)
>>> p2 = (50e-9, 50e-9, 10e-9)
>>> region = df.Region(p1=p1, p2=p2)
>>> region.k3d()
Plot(...)
property mpl#

matplotlib plot.

If ax is not passed, matplotlib.axes.Axes object is created automatically and the size of a figure can be specified using figsize. The colour of lines depicting the region can be specified using color argument, which must be a valid matplotlib color. The plot is saved in PDF-format if filename is passed.

It is often the case that the object size is either small (e.g. on a nanoscale) or very large (e.g. in units of kilometers). Accordingly, multiplier can be passed as \(10^{n}\), where \(n\) is a multiple of 3 (…, -6, -3, 0, 3, 6,…). According to that value, the axes will be scaled and appropriate units shown. For instance, if multiplier=1e-9 is passed, all axes will be divided by \(1\,\text{nm}\) and \(\text{nm}\) units will be used as axis labels. If multiplier is not passed, the best one is calculated internally.

This method is based on matplotlib.pyplot.plot, so any keyword arguments accepted by it can be passed (for instance, linewidth, linestyle, etc.).

Parameters:

  • ax (matplotlib.axes.Axes, optional) – Axes to which the plot is added. Defaults to None - axes are created internally.

  • figsize ((2,) tuple, optional) – The size of a created figure if ax is not passed. Defaults to None.

  • color (int, str, tuple, optional) – A valid matplotlib color for lines depicting the region. Defaults to the default color palette.

  • multiplier (numbers.Real, optional) – Axes multiplier. Defaults to None.

  • box_aspect (str, array_like (3), optional) – Set the aspect-ratio of the plot. If set to ‘auto’ the aspect ratio is determined from the edge lengths of the region. To set different aspect ratios a tuple can be passed. Defaults to 'auto'.

  • filename (str, optional) – If filename is passed, the plot is saved. Defaults to None.

Examples

  1. Visualising the region using matplotlib.

>>> import discretisedfield as df
...
>>> p1 = (-50e-9, -50e-9, 0)
>>> p2 = (50e-9, 50e-9, 10e-9)
>>> region = df.Region(p1=p1, p2=p2)
>>> region.mpl()
property multiplier#

Compute multiplier for the region.

property ndim#

Number of dimensions.

Calculates the number of dimensions of the region.

Returns:

Number of dimensions of the region.

Return type:

int

Examples

  1. Getting number of dimensions of the region.

>>> import discretisedfield as df
...
>>> p1 = (-1.1, 2.9, 0)
>>> p2 = (5, 0, -0.1)
>>> region = df.Region(p1=p1, p2=p2)
...
>>> region.ndim
3

See also

dims()

property pmax#

Point with maximum coordinates in the region.

The \(i\)-th component of \(\mathbf{p}_\text{max}\) is computed from points \(p_1\) and \(p_2\), between which the region spans: \(p_\text{max}^i = \text{max}(p_1^i, p_2^i)\).

Returns:

Point with maximum coordinates. E.g. for three dimensions \((p_x^\text{max}, p_y^\text{max}, p_z^\text{max})\).

Return type:

numpy.ndarray

Examples

  1. Getting region’s point with maximum coordinates.

>>> import discretisedfield as df
...
>>> p1 = (-1.1, 2.9, 0)
>>> p2 = (5, 0, -0.1)
>>> region = df.Region(p1=p1, p2=p2)
...
>>> region.pmax
array([5. , 2.9, 0. ])

See also

pmin()

property pmin#

Point with minimum coordinates in the region.

The \(i\)-th component of \(\mathbf{p}_\text{min}\) is computed from points \(p_1\) and \(p_2\), between which the region spans: \(p_\text{min}^i = \text{min}(p_1^i, p_2^i)\).

Returns:

Point with minimum coordinates. E.g. for three dimensions \((p_x^\text{min}, p_y^\text{min}, p_z^\text{min})\).

Return type:

numpy.ndarray

Examples

  1. Getting region’s point with minimum coordinates.

>>> import discretisedfield as df
...
>>> p1 = (-1.1, 2.9, 0)
>>> p2 = (5, 0, -0.1)
>>> region = df.Region(p1=p1, p2=p2)
...
>>> region.pmin
array([-1.1,  0. , -0.1])

See also

pmax()

property tolerance_factor#

Tolerance factor for floating-point comparisons.

The tolerance factor is used for allclose and in if no other tolerance is provided. It is multiplied with the minimum edge length of the region to obtain reasonable relative and absolute tolerance.

property units#

Units of the region’s dimensions.

Returns:

Units of the region’s dimensions.

Return type:

tuple of str

Examples

  1. Getting region’s dimension units.

>>> import discretisedfield as df
...
>>> p1 = (-1.1, 2.9, 0)
>>> p2 = (5, 0, -0.1)
>>> region = df.Region(p1=p1, p2=p2)
...
>>> region.units
('m', 'm', 'm')
property volume#

Region’s volume.

It is computed by multiplying edge lengths of the region. E.g. in three dimensions

\[V = l_x l_y l_z.\]
Returns:

Volume of the region.

Return type:

numbers.Real

Examples

  1. Computing the volume of the region.

>>> import discretisedfield as df
...
>>> p1 = (0, 0, 0)
>>> p2 = (5, 10, 2)
>>> region = df.Region(p1=p1, p2=p2)
...
>>> region.volume
100