Utilities

Utility

Basic PolyData objects.

This module provides PolyData objects as fundamental elements to draw. The following objects are available.

• sphere

• bond

• vector

• orbital

• vector stream

• line

• plane

• circle

• torus

• ellipsoid

• toroid

• box

• polygon

• text3d

• text2d (math)

• spline

• spline (parametric)

• isosurface

create_bond(direction, width=1.0, twotone=True)

Create bond object.

Parameters:

• direction (list or numpy.ndarray) -- bond direction (cartesian), [float].

• width (float, optional) -- width.

• twotone (bool, optional) -- twotone color ?

Returns:

• (vtk.PolyData) -- cylinder object

Note

• bond position is at center.

create_box(a1=None, a2=None, a3=None)

Create box object.

Parameters:

• a1 (numpy.ndarray, optional) -- a1 vector (cartesian).

• a2 (numpy.ndarray, optional) -- a2 vector (cartesian).

• a3 (numpy.ndarray, optional) -- a3 vector (cartesian).

Returns:

• (vtk.PolyData) -- cube object.

Note

• if a1/a2/a3 is None, unit vector is used.

create_circle(normal, size=0.5)

Create circle object.

Parameters:

• normal (list or numpy.ndarray) -- normal vector (cartesian), [float].

• size (float, optional) -- size.

Returns:

• (vtk.PolyData) -- circle object.

create_ellipsoid(normal, x_size=0.5, y_size=0.4, z_size=0.3)

Create ellipsoid object.

Parameters:

• normal (list or numpy.ndarray) -- normal vector (cartesian), [float].

• x_size (float, optional) -- x_size.

• y_size (float, optional) -- y_size.

• z_size (float, optional) -- z_size.

Returns:

• (vtk.PolyData) -- ellipsoid object.

create_isosurface(grid_data, value, surface_name)

Create isosurface.

Parameters:

• grid_data (dict) -- grid data.

• value (list or numpy.ndarray) -- value of isosurface.

• surface_name (str) -- surface data.

Returns:

• (vtk.DataSet) -- isosurface object.

Note

• n : [nx,ny,nz] division of grid.

• origin : [rx,ry,rz] origin in fractional coordinate.

• Ag : [g1,g2,g3] grid vectors in 4x4 matrix.

• data : data at each grid point.

• surface : surface data at each grid point.

• endpoint : include endpoint ?

• row_major : row-major grid ?

create_line(direction, width=1.0, arrow1=False, arrow2=False, tip_radius=2.0, tip_length=0.1)

Create line object.

Parameters:

• direction (list or numpy.ndarray) -- bond direction (cartesian), [float].

• width (float, optional) -- width.

• arrow1 (bool, optional) -- arrow at start point ?

• arrow2 (bool, optional) -- arrow at end point ?

• tip_radius (float, optional) -- tip radius.

• tip_length (float, optional) -- tip length.

Returns:

• (vtk.PolyData) -- cylinder object

create_orbital(shape, surface='', size=1.0, theta_phi_range=None, theta_phi_resolution=None)

Create orbital object.

Parameters:

• shape (str) -- (x,y,z) shape (cartesian).

• surface (str, optional) -- (x,y,z) surface color (cartesian).

• size (float, optional) -- size.

• theta_phi_range (list or numpy.ndarray, optional) -- theta and phi range, [[float]].

• theta_phi_resolution (list) -- theta and phi resolution, [int].

Returns:

• (vtk.PolyData) -- orbital object with "surface".

Note

• if surface is "", the same one of shape is used.

• if size is positive, max. value is equivalent to size.

• if size is negative, abs. value is scaled by size.

• if theta_phi_range is None, default is used.

• if theta_phi_resolution is None, default is used.

create_orbital_data(shape, surface=None, size=1.0, spherical_plot=False, point_size=0.03)

Create orbital object from data.

Parameters:

• shape (ndarray) -- (x,y,z) shape (cartesian).

• surface (ndarray, optional) -- (x,y,z) surface color (cartesian).

• size (float, optional) -- size.

• spherical_plot (bool, optional) -- spherical-like plot ?

• point_size (float, optional) -- point size.

Returns:

• (vtk.PolyData) -- orbital object with "surface".

Note

• if surface is None, the same one of shape is used.

• if size is positive, max. value is equivalent to size.

• if size is negative, abs. value is scaled by size.

• if point_size is None, no point is shown.

create_plane(normal, x_size=1.0, y_size=1.0)

Create plane object.

Parameters:

• normal (list or numpy.ndarray) -- normal vector (cartesian), [float].

• x_size (float, optional) -- x size.

• y_size (float, optional) -- y size.

Returns:

• (vtk.PolyData) -- plane object.

create_polygon(point, connectivity)

Create polygon object.

Parameters:

• point (list or numpy.ndarray) -- vertices (cartesian), [float].

• conectivity (list) -- list connectivities of #point for each plane, [[int]].

Returns:

• (vtk.PolyData) -- polygon object.

create_sphere(radius, theta_phi_range=None, theta_phi_resolution=None)

Create sphere object.

Parameters:

• radius (float) -- radius.

• theta_phi_range (list or numpy.ndarray, optional) -- theta and phi range, [[float]].

• theta_phi_resolution (list) -- theta and phi resolution, [int].

Returns:

• (vtk.PolyData) -- sphere object.

Note

• if theta_phi_range/theta_phi_resolution is None, default is used.

create_spline(point, width=1.0, n_interp=500, closed=False, natural=True, arrow1=False, arrow2=False, tip_radius=2.0, tip_length=0.1)

Create spline object.

Parameters:

• point (list or numpy.ndarray) -- points to be connected, [[float]].

• width (float, optional)

• n_interp (int, optional) -- number of interpolation points.

• closed (bool, optional) -- closed spline ?

• natural (bool, optional) -- natural boundary ?

• arrow1 (bool, optional) -- arrow at start point ?

• arrow2 (bool, optional) -- arrow at end point ?

• tip_radius (float, optional) -- tip radius.

• tip_length (float, optional) -- tip length.

Returns:

• (vtk.PolyData) -- spline object.

create_spline_t(point, t_range=None, width=1.0, n_interp=300, closed=False, natural=True, arrow1=False, arrow2=False, tip_radius=2.0, tip_length=0.1, A=None)

Create parametric spline object.

Parameters:

• point (str) -- sympy expression for point in terms of "t".

• t_range (list or numpy.ndarray, optional) -- t range, [start, stop, step], [float].

• width (float, optional) -- width.

• n_interp (int, optional) -- interpolation points.

• closed (bool, optional) -- closed spline ?

• natural (bool, optional) -- natural boundary ?

• arrow1 (bool, optional) -- arrow at start point ?

• arrow2 (bool, optional) -- arrow at end point ?

• tip_radius (float, optional) -- tip radius.

• tip_length (float, optional) -- tip length.

• A (numpy.ndarray, optional) -- (a1, a2, a3) in each column, 4x4 (cartesian).

Returns:

• (vtk.PolyData) -- parameteric spline object.

Note

• if t_range is None, default is used.

• if A is None, unit vector is used.

create_stream(shape='1', vector='[x,y,z]', size=1.0, theta_phi_range=None, division=None, length=0.1, width=0.1, offset=-0.43, abs_scale=False, shaft_radius=1.0, tip_radius=2.0, tip_length=0.25)

Create steam vector object.

Parameters:

• shape (str, optional) -- f(x,y,z) shape (cartesian).

• vector (str, optional) -- stream vector [vx(x,y,z),vy(x,y,z),vz(x,y,z)] (cartesina).

• size (float, optional) -- shape size.

• theta_phi_range (list or numpy.ndarray, optional) -- theta and phi range, [[float]].

• division (list, optional) -- division for theta and phi, [int].

• length (float, optional) -- length.

• width (float, optional) -- width.

• offset (float, optional) -- offest ratio.

• abs_scale (bool, optional) -- use |v(x,y,z)| * length ?

• shaft_radius (float, optional) -- shaft radius.

• tip_radius (float, optional) -- tip radius.

• tip_length (float, optional) -- tip length.

Returns:

• (vtk.PolyData) -- orbital object with "vector" and "vector_abs".

Note

• if theta_phi_range/division is None, default is used.

• if size is negative, shape is normalized.

create_stream_data(shape, surface, vector, size=1.0, length=0.1, width=0.1, offset=-0.43, abs_scale=False, shaft_radius=1.0, tip_radius=2.0, tip_length=0.25, spherical_plot=False)

Create steam vector object.

Parameters:

• shape (ndarray) -- f(x,y,z) shape (cartesian).

• surface (ndarray, optional) -- (x,y,z) surface color (cartesian).

• vector (ndarray) -- stream vector [vx(x,y,z),vy(x,y,z),vz(x,y,z)] (cartesina).

• size (float, optional) -- shape size.

• length (float, optional) -- length.

• width (float, optional) -- width.

• offset (float, optional) -- offest ratio.

• abs_scale (bool, optional) -- use |v(x,y,z)| * length ?

• shaft_radius (float, optional) -- shaft radius.

• tip_radius (float, optional) -- tip radius.

• tip_length (float, optional) -- tip length.

• spherical_plot (bool, optional) -- spherical-like plot ?

Returns:

• (vtk.PolyData) -- orbital object with "vector" and "vector_abs".

Note

• if size is negative, shape is normalized.

create_text2d(latex, mathjax, x, y, size, color)

Create text 2d (math).

Parameters:

• latex (str) -- LaTeX with $.

• mathjax (MathJaxSVG) -- mathjax converter.

• x (int) -- x position from left.

• y (int) -- y position from bottom.

• size (int) -- size (height).

• color (str) -- color.

Returns:

• (vtkActor2D) -- actor.

create_text3d(text, size=1.0, view=None, depth=1.0, offset=[0, 0, 0], A=None)

Create text3d object.

Parameters:

• text (str) -- text.

• size (float, optional) -- size.

• view (list, optional) -- normal indices, [int].

• depth (float, optional) -- depth.

• offset (list or numpy.ndarray, optional) -- offset, [float].

• A (numpy.ndarray, optional) -- (a1, a2, a3) in each column, 4x4 (cartesian).

Returns:

• (vtk.PolyData) -- text3d object.

Note

• if normal is None, default is used.

• if A is None, unit vector is used.

create_toroid(normal, size=0.5, width=0.15, x_scale=1.0, y_scale=1.0, z_scale=1.0, ring_shape=0.3, tube_shape=0.3)

Create ellipsoid object.

Parameters:

• normal (list or numpy.ndarray) -- normal vector (cartesian), [float].

• size (float, optional) -- ring size.

• width (float, optional) -- tube width.

• x_scale (float, optional) -- scale factor for x axis.

• y_scale (float, optional) -- scale factor for y axis.

• z_scale (float, optional) -- scale factor for z axis.

• ring_shape (float, optional) -- ring shape.

• tube_shape (float, optional) -- tube shape.

Returns:

• (vtk.PolyData) -- toroid object.

create_torus(normal, size=0.5, width=0.15)

Create torus object.

Parameters:

• normal (list or numpy.ndarray) -- normal vector (cartesian), [float].

• size (float, optional) -- size.

• width (float, optioanl) -- torus width.

Returns:

• (vtk.PolyData) -- torus object.

create_vector(direction, length=1.0, width=1.0, offset=-0.43, shaft_radius=1.0, tip_radius=2.0, tip_length=0.25)

Create vector object.

Parameters:

• direction (list or numpy.ndarray) -- direction (cartesian), [float].

• length (float, optional) -- length.

• width (float, optional) -- width.

• offset (float, optional) -- offest ratio.

• shaft_radius (float, optional) -- shaft radius.

• tip_radius (float, optional) -- tip radius.

• tip_length (float, optional) -- tip length.

Returns:

• (vtk.PolyData) -- arrow object.

Note

• if length is negative, norm of direction multiplied by |length| is used.

For versatile utility.

apply(f, lst)

Apply function to (nested) list.

Parameters:

• f (function) -- function to apply to each element of list.

• lst (list or value) -- (nested) list to apply.

Returns:

• (list or value) -- applied list.

check_multipie()

Check if multipie is installed or not.

Returns:

• (bool) -- installed ?

create_grid(grid_n, grid_min, grid_max, A=None, endpoint=False)

Create grid.

Parameters:

• grid_n (list) -- grid size.

• grid_min (list) -- grid minimum.

• grid_max (list) -- grid maximum.

• A (list) -- [a1,a2,a3].

• endpoint (bool, optional) -- include end points ?

Returns:

uniform grid.

Return type:

UniformGrid

Note

• grid in column-major order.

distance(s1, s2, G=None, accuracy=4)

group of sites with the same distance (in increasing order).

Parameters:

• s1 (ndarray) -- vector array.

• s2 (ndarray) -- vector array.

• G (ndarray, optional) -- metric matrix (None = unit matrix).

• accuracy (int, optional) -- accuracy of digit.

Returns:

i, j are indices of positions (i<=j only for s1=s2), { distance(float): [(i(int),j(int))] }.

Return type:

dict

igrid(N, offset=None)

create integer grid points.

Parameters:

• N (list) -- number of points in each direction.

• offset (tuple, optional) -- offset in each direction. 0 is used for None.

Returns:

grid points.

Return type:

ndarray

Notes

• grid point: increase of indices from left to right.

• x[i] = offset + i.

list_to_table(lst1d, col, p=None)

Convert from list to table

Parameters:

• lst1d (list) -- 1d list

• col (int) -- number of columns

• p (any, optional) -- padding value (no padding for None)

Returns:

• (list) -- 2d list.

read_dict(filename)

Read dict text file.

Parameters:

filename (str) -- file name.

Returns:

• (dict) -- dictionary from dict text.

remove_space(s)

Remove space, tab, and newline.

Parameters:

s (str) -- string

Returns:

• (str) -- removed string.

str_to_list(s)

Convert a string to a list of strings.

Parameters:

s (str) -- a string with irregular-shaped list format.

Returns:

• (list) -- a list of strings.

Note

• in case of no bracket, return as it is.

• raise ValueError for invalid brackets.

str_to_sympy(s, check_var=None, check_shape=None, rational=True, subs=None, **assumptions)

Convert a string to a sympy.

Parameters:

• s (str) -- a string.

• check_var (list, optional) -- variables to accept, None (all).

• check_shape (tuple, optional) -- shape, (), (n,), (n,m), ...

• rational (bool, optional) -- use rational number ?

• subs (dict, optional) -- replace dict for local variables.

• **assumptions (dict, optional) -- common assumptions for all variables.

Returns:

• (ndarray) -- (list of) sympy.

Notes

• if format error occurs, raise ValueError.

• if s cannot be converted to a sympy, raise ValueError.

text_to_list(text)

Convert single text to list.

Parameters:

text (str) -- text to convert.

Returns:

• (list or str) -- converted list.

Notes

• if format error occurs, return None.

to_latex(a, style='scalar')

convert list to latex list.

Parameters:

• a (array-like) -- list of sympy.

• style (str, optional) -- style, "scalar/vector/matrix".

Returns:

• (ndarray or str) -- (list of) LaTeX string without "$".

vector3d(head='Q', pre=None)

3d vector.

Parameters:

• head (str, optional) -- type of vector, Q/G/T/M.

• pre (str, optional) -- head of symbol.

Returns:

• (ndarray) -- 3d vector.

write_dict(filename, dic, header=None, var=None)

write dict text file.

Parameters:

• filename (str) -- filename.

• dic (dict) -- dictionary to write.

• header (str, optional) -- header comment at the top of file.

• var (str, optional) -- varialbe of dict.

Utility for axis actor and label, unit cell, and view vector.

This module contains utility for axis, etc.

create_axes_widget(pv_widget, A, label='[x,y,z]', label_size=28, label_bold=True, label_italic=False, label_color=['black', 'black', 'black'], viewport=True)

Create axes widget.

Parameters:

• pv_widget (PyVistaWidget) -- pyvista widget.

• A (numpy.ndarray) -- (a1, a2, a3) unit vectors, 4x4 [float].

• label (str, optional) -- axes labels.

• label_size (int, optional) -- font size.

• label_bold (bool, optional) -- bold face ?

• label_italic (bool, optional) -- italic ?

• label_color (list, optional) -- axes label color names, [str].

• viewport (bool, optional) -- set viewport ?

Note

• if label is None, no label is used.

create_cell_grid(ilower, dims)

Create grid point.

Parameters: :param ilower: start cell. :type ilower: list :param dims: range in each dim. :type dims: list

Returns:

• (list) -- grid point, [str].

create_unit_cell(A, origin, lower=None, dimensions=None)

Create unit cell mesh.

Parameters:

• A (numpy.ndarray) -- (a1, a2, a3) unit vectors, 4x4 [float].

• origin (list or numpy.ndarray) -- origin, [float].

• lower (list, optional) -- lower bound indices, [int].

• dimensions (list, optional) -- repeat times, [int].

Returns:

• (pyvista.PolyData) -- unit cel mesh.

get_lattice_vector(crystal, cell)

Get lattice vector.

Parameters:

• crystal (str) -- crystal.

• cell (dict) -- cell.

Returns:

cell. - list: A.

Return type:

• dict

get_outside_box(point, lower, upper)

Get indices outside range.

Parameters:

• point (numpy.ndarray) -- a set of points.

• lower (list) -- lower bound.

• upper (list) -- upper bound.

Returns:

• (numpy.ndarray) -- list of indices.

get_repeat_range(lower, upper)

Get repeart range.

Parameters:

• lower (list) -- upper.

• upper (list) -- lower.

Returns:

lower cell. - list: size of repeat.

Return type:

• list

get_view_vector(n, A)

Get view and viewup.

Parameters:

• n (list) -- view indices of [a1,a2,a3], [int].

• A (numpy.ndarray) -- (a1, a2, a3) unit vectors, 4x4 [float].

Returns:

• (numpy.ndarray) -- view.

• (numpy.ndarray) -- viewup.