Line#

class discretisedfield.Line(points, values, point_columns, value_columns)#

Line class.

This class represents field sampled on the line. It is based on pandas.DataFrame, which is generated from two lists: points and values of the same length. points is a list of array_like objects representing the points on the line on which the field was sampled. On the other hand, values is a list of field values, which are numbers.Real for scalar fields or array_like for vector fields. During the initialisation of the object, r column is added to pandas.DataFrame and it represents the distance of the point from the first point in points.

The names of the columns are set by passing point_columns and value_columns lists. Both lists are composed of strings and must have appropriate lengths.

The number of points can be retrieved as discretisedfield.Line.n and the dimension of the value can be retrieved using discretisedfield.Line.dim.

Data in the form of pandas.DataFrame can be exposed as line.data.

Parameters:

points (list) – Points at which the field was sampled. It is a list of array_like.
values (list) – Values sampled at points.
point_columns (list) – Point column names.
value_columns (list) – Value column names.

Raises:

ValueError – If the numbers of points is not the same as the number of values.

Example

Defining Line object, which contains scalar values.

>>> import discretisedfield as df
...
>>> points = [(0, 0, 0), (1, 0, 0), (2, 0, 0)]
>>> values = [1, 2, 3]  # scalar values
>>> line = df.Line(points=points,
...                values=values,
...                point_columns=["x", "y", "z"],
...                value_columns=["vx"])
>>> line.n  # the number of points
3
>>> line.dim
1

Defining Line for vector values.

>>> points = [(0, 0, 0), (1, 1, 1), (2, 2, 2), (3, 3, 3)]
>>> values = [(0, 0, 1), (0, 0, 2), (0, 0, 3), (0, 0, 4)]  # vector values
>>> line = df.Line(points=points,
...                values=values,
...                point_columns=["x", "y", "z"],
...                value_columns=["vx", "vy", "vz"])
>>> line.n  # the number of points
4
>>> line.dim
3

Methods

`__dir__`	Default dir() implementation.
`__eq__`	Return self==value.
`__repr__`	Representation string.
`mpl`	Line values plot.
`selector`	Selection list for interactive plotting.
`slider`	Slider for interactive plotting.

Properties

`dim`	Descriptor allowing setting attributes only with scalars (`numbers.Real`).
`length`	Line length.
`n`	Descriptor allowing setting attributes only with scalars (`numbers.Real`).
`point_columns`	The names of point columns.
`value_columns`	The names of value columns.

__repr__()#

Representation string.

Returns:: Representation string.
Return type:: str

Example

Getting representation string.

>>> import discretisedfield as df
...
>>> points = [(0, 0, 0), (2, 0, 0), (4, 0, 0)]
>>> values = [(1, 0, 0), (0, 1, 0), (0, 0, 1)]  # vector values
>>> line = df.Line(points=points,
...                values=values,
...                point_columns=["x1", "x2", "x3"],
...                value_columns=["v1", "v2", "v3"])
>>> repr(line)
'...

mpl(ax=None, figsize=None, yaxis=None, xlim=None, multiplier=None, filename=None, **kwargs)#

Line values plot.

This method plots the values (scalar or individual components) as a function of the distance r. mpl adds the plot to matplotlib.axes.Axes passed via ax argument. If ax is not passed, matplotlib.axes.Axes object is created automatically and the size of a figure can be specified using figsize. To choose particular value columns to be plotted yaxis can be passed as a list of column names. The range of r values on the horizontal axis can be defined by passing a lenth-2 tuple to xlim. It is often the case that the line length is 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 horizontal axis will be scaled and appropriate units shown. For instance, if multiplier=1e-9 is passed, all mesh points 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. The plot can be saved as a PDF when filename is passed.

This method plots the mesh using matplotlib.pyplot.plot() function, so any keyword arguments accepted by it can be passed.

Parameters:

ax (matplotlib.axes.Axes, optional) – Axes to which the field plot is added. Defaults to None - axes are created internally.
figsize (tuple, optional) – The size of a created figure if ax is not passed. Defaults to None.
yaxis (list, optional) – A list of value columns to be plotted.
xlim (tuple) – A length-2 tuple setting the limits of the horizontal axis.
multiplier (numbers.Real, optional) – 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, the mesh points will be divided by \(1\,\text{nm}\) and \(\text{nm}\) units will be used as axis labels. Defaults to None.
filename (str, optional) – If filename is passed, the plot is saved. Defaults to None.

Examples

Visualising the values on the line using matplotlib.

>>> import discretisedfield as df
...
>>> points = [(0, 0, 0), (2, 0, 0), (4, 0, 0)]
>>> values = [(1, 0, 0), (0, 1, 0), (0, 0, 1)]  # vector values
>>> line = df.Line(points=points,
...                values=values,
...                point_columns=["x", "y", "z"],
...                value_columns=["v1", "v2", "v3"])
>>> line.mpl()

selector(**kwargs)#

Selection list for interactive plotting.

Based on the value columns, ipywidgets.SelectMultiple widget is returned for selecting the value columns to be plotted.

This method is based on ipywidgets.SelectMultiple, so any keyword argument accepted by it can be passed.

Returns:: Selection list.
Return type:: ipywidgets.SelectMultiple

Example

Get the widget for selecting value columns.

>>> import discretisedfield as df
...
>>> points = [(0, 0, 0), (2, 0, 0), (4, 0, 0)]
>>> values = [(1, 0, 0), (0, 1, 0), (0, 0, 1)]  # vector values
>>> line = df.Line(points=points,
...                values=values,
...                point_columns=["px", "py", "pz"],
...                value_columns=["vx", "vy", "vz"])
>>> line.selector()
SelectMultiple(...)

slider(multiplier=None, **kwargs)#

Slider for interactive plotting.

Based on the values in the r column, ipywidgets.SelectionRangeSlider is returned for navigating interactive plots.

This method is based on ipywidgets.SelectionRangeSlider, so any keyword argument accepted by it can be passed.

Parameters:: multiplier (numbers.Real, optional) – multiplier can be passed as \(10^{n}\), where \(n\) is a multiple of 3 (…, -6, -3, 0, 3, 6,…). According to that value, the values will be scaled and appropriate units shown. For instance, if multiplier=1e-9 is passed, the slider points will be divided by \(1\,\text{nm}\) and \(\text{nm}\) units will be used in the description. If multiplier is not passed, the optimum one is computed internally. Defaults to None.
Returns:: r range slider.
Return type:: ipywidgets.SelectionRangeSlider

Example

Get the slider for the horizontal axis.

>>> import discretisedfield as df
...
>>> points = [(0, 0, 0), (2, 0, 0), (4, 0, 0)]
>>> values = [(1, 0, 0), (0, 1, 0), (0, 0, 1)]  # vector values
>>> line = df.Line(points=points,
...                values=values,
...                point_columns=["x", "y", "z"],
...                value_columns=["x", "y", "z"])
>>> line.slider()
SelectionRangeSlider(...)

property length#

Line length.

Length of the line is defined as the distance between the first and the last point in points.

Returns:: Line length.
Return type:: float

Example

Getting the length of the line.

>>> import discretisedfield as df
...
>>> points = [(0, 0, 0), (2, 0, 0), (4, 0, 0)]
>>> values = [(1, 0, 0), (0, 1, 0), (0, 0, 1)]  # vector values
>>> line = df.Line(points=points,
...                values=values,
...                point_columns=["x", "y", "z"],
...                value_columns=["vx", "vy", "vz"])
>>> line.length
4.0

property point_columns#

The names of point columns.

This method returns a list of strings denoting the names of columns storing three coordinates of points. Similarly, by assigning a list of strings to this property, the columns can be renamed.

Parameters:: val (list) – Point column names used to rename them.
Returns:: List of point column names.
Return type:: list
Raises:: ValueError – If a list of inappropriate length is passed.

Examples

Getting and setting the column names.

>>> import discretisedfield as df
...
>>> points = [(0, 0, 0), (1, 0, 0), (2, 0, 0)]
>>> values = [1, 2, 3]  # scalar values
>>> line = df.Line(points=points,
...                values=values,
...                point_columns=["px", "py", "pz"],
...                value_columns=["v"])
>>> line.point_columns
['px', 'py', 'pz']
>>> line.point_columns = ['p0', 'p1', 'p2']
>>> line.data.columns
Index(['r', 'p0', 'p1', 'p2', 'v'], dtype='object')

property value_columns#

The names of value columns.

This method returns a list of strings denoting the names of columns storing values. The length of the list is the same as the dimension of the value. Similarly, by assigning a list of strings to this property, the columns can be renamed.

Parameters:: val (list) – Value column names used to rename them.
Returns:: List of value column names.
Return type:: list
Raises:: ValueError – If a list of inappropriate length is passed.

Examples

Getting and setting the column names.

>>> import discretisedfield as df
...
>>> points = [(0, 0, 0), (1, 0, 0), (2, 0, 0)]
>>> values = [1, 2, 3]  # scalar values
>>> line = df.Line(points=points,
...                values=values,
...                point_columns=["px", "py", "pz"],
...                value_columns=["v"])
>>> line.value_columns
['v']
>>> line.value_columns = ['my_interesting_value']
>>> line.data.columns
Index(['r', 'px', 'py', 'pz', 'my_interesting_value'], dtype='object')