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
andp2
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
, andz
. For more than three dimensions, it defaults tox1
,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 to1e-12
.
- Raises:
ValueError – If any of the region’s edge lengths is zero.
Examples
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(...)
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
Determine if a point or another region belong to the region.
__dir__
Default dir() implementation.
Relational operator
==
.Old implementation to find facing surfaces.
Representation string.
Check if two regions are close.
Facing surface.
Return a random point in the region.
Rotate region by 90 degrees.
Scale the region.
Convert region object to dict.
Translate the region.
Properties
Center point.
centre
Names of the region's dimensions.
Region's edge lengths.
k3d
plot.matplotlib
plot.Compute multiplier for the region.
Number of dimensions.
Point with maximum coordinates in the region.
Point with minimum coordinates in the region.
pyvista
plot.Tolerance factor for floating-point comparisons.
Units of the region's dimensions.
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 itspmin
andpmax
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
ifother
is inside the region andFalse
otherwise.- Return type:
bool
Example
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
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 andFalse
otherwise.- Return type:
bool
Examples
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
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) andFalse
otherwise.- Return type:
bool
Examples
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
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 byax1
andax2
. The rotation direction is fromax1
toax2
, 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 toFalse
.
- Returns:
The rotated region object. Either a new object or a reference to the existing region for
inplace=True
.- Return type:
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
- scale(factor, reference_point=None, inplace=False)#
Scale the region.
This method scales the region about its
center
point or areference_point
if provided. Iffactor
is a number the same scaling is applied along all dimensions. Iffactor
is array-like its length must matchregion.ndim
and different factors are applied along the different directions (based on their order). A new object is created unlessinplace=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:
- Raises:
ValueError, TypeError – If the operator cannot be applied.
Example
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.])
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.])
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
topmin
andpmax
. Thevector
must haveRegion.ndim
elements. A new object is created unlessinplace=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:
- Raises:
ValueError, TypeError – If the operator cannot be applied.
Examples
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])
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
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
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
- 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
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 usingcolor
argument.For details about
multiplier
, please refer todiscretisedfield.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
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 usingfigsize
. The colour of lines depicting the region can be specified usingcolor
argument, which must be a validmatplotlib
color. The plot is saved in PDF-format iffilename
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, ifmultiplier=1e-9
is passed, all axes will be divided by \(1\,\text{nm}\) and \(\text{nm}\) units will be used as axis labels. Ifmultiplier
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 toNone
.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
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
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
- 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
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
- 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
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
- property pyvista#
pyvista
plot.
- 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
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
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