Utilities

Basic Object

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

• 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_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.

Logging

Logging utility.

This module provides utilities for logging.

class LogHandler(level=10, stream=None, text_widget=None)

Bases: Handler

Log handler.

Parameters:

• level (Level, optional) -- log level.

• stream (TextIO, optional) -- stream.

• text_widget (LogWidget, optional) -- text widget.

Note

• if stream/text_widget is None, it is not used.

emit(record)

Emit message.

Parameters:

record (LogRecord) -- log record.

class LogWidget(title='log message', level=10, stream=None, hook=True, parent=None)

Bases: QWidget

Log widget.

Parameters:

• title (str, optional) -- window title.

• level (Level, optional) -- log level.

• stream (TextIO, optional) -- stream for logging.

• hook (bool, optional) -- exception hook ?

• parent (QObject, optional) -- parent.

Note

• if stream is True, sys.stderr is used.

• if level is None, no logging.

append_text(text)

Append text.

Parameters:

text (str) -- text.

clear()

Clear log message.

save()

Save log message.

set_text(text)

Set text.

Parameters:

text (str) -- text.

start_logging(level=10, stream=None, text_widget=None, hook=True)

Start logging.

Parameters:

• level (Level, optional) -- logging level.

• stream (TextIO, optional) -- stream for logging.

• text_widget (LogWidget, optional) -- text widget.

• hook (bool, optional) -- exception hook ?

Note

• stream is True, sys.stderr is used.

timer(func)

Timer decorater.

Parameters:

func (Function) -- function to decorate.

Event Loop

Control Qt event loop.

This module provides functions to control Qt event loop.

See also,

• [use Qt from Jupyter NB](https://qiita.com/Hanjin_Liu/items/9df684920727f8a784c4)

• [exception hook](https://timlehr.com/python-exception-hooks-with-qt-message-box/)

class ExceptionHook(parent=None)

Bases: QObject

Exception hook.

Parameters:

parent (QObject, optional) -- parent.

Note

• call this before super().__init__() in __init__() of QMainWindow class as follows.

  • self.app = get_qt_application()

  • ExceptionHook()

hook(type, value, traceback)

Callback for uncaught exceptions.

Parameters:

• type (Any) -- type of exception.

• value (Any) -- arguments.

• traceback (TraceBack) -- traceback.

reset()

Reset exception hook.

get_qt_application(latex=True)

Get Qt application.

Parameters:

latex (bool, optional) -- use latex setting ?

Returns:

• (QApplication) -- Qt application.

Note

• call this before super().__init__() in __init__() of QMainWindow class as follows.

  • self.app = get_qt_application()

  • ExceptionHook()

gui_qt()

Execute gui magic command for qtconsole.

PDF Viewer

Simple PDF viewer.

This module contains a class for simple PDF viewer. It can load PDF file, and save the same file to different directory (just by copying it).

class PDFViewer(filename=None)

Bases: QWidget

Simple PDF viewer.

Parameters:

filename (str, optional) -- file name to load.

load()

Load PDF file.

save()

Save PDF file (default = current directory).

set_title(filename=None)

Set window title.

Parameters:

filename (str, optional) -- file name.

LaTeX

Render LaTeX to backend.

This module provides LaTeX converter to backend.

See for example, ipython/IPython.

latex_to_png(text, wrap=True, color='black', size=12, dpi=120)

Render a LaTeX string to png via matplotlib.

Parameters:

• text (str) -- raw string containing valid inline LaTeX.

• backend (str, optional) -- backend for producing png or svg.

• wrap (bool, optional) -- if true, automatically wrap s as a LaTeX equation.

• color (str, optional) -- color name.

• size (int, optional) -- fontsize.

• dpi (int, optional) -- DPI.

Returns:

• (pixmap) -- pixmap image.

Note

• None is returned when the backend cannot be used.

Render LaTeX to SVG.

This module provides LaTeX converter to SVG.

See for example, ipython/IPython.

class MathText(parent, text, size, color)

Bases: QWidget

Math Text via SVG.

Parameters:

• parent (QWidget) -- parent.

• text (str) -- LaTeX stirng without "$".

• size (int) -- font size.

• color (str) -- color.

class SVGWidget

Bases: QSvgWidget

get_svg_size(svg)

Get SVG size.

Parameters:

svg (str) -- bin code of svg.

Returns:

• (int) -- width.

• (int) -- hight.

latex_to_svg(text, wrap=True, color='black', size=12)

Render a LaTeX string to svg via matplotlib.

Parameters:

• text (str) -- raw string containing valid inline LaTeX.

• wrap (bool, optional) -- if true, automatically wrap s as a LaTeX equation.

• color (str, optional) -- color name.

• size (int, optional) -- fontsize.

Returns:

• (str) -- SVG code (byte string).

• (int) -- width.

• (int) -- height.

Note

• None is returned when the backend cannot be used.

Utility

Utility.

This module contains the versatile utilities.

cat_filename(base, ext=None)

Cat filename.

Parameters:

• base (str) -- (base) filename.

• ext (str, optional) -- extension.

Returns:

• (str) -- full file name.

check_multipie()

Check if multipie is installed or not.

Returns:

• (bool) -- installed ?

convert_str_vector(vector, cell='[0,0,0]', transform=True, A=None)

Convert 3-component vector(s) to A.(position+cell).

Parameters:

• vector (str) -- vector, str([float]) or str([[float]]).

• cell (str, optional) -- cell, str([int]).

• transform (bool, optional) -- transform by using A ?

• A (numpy.ndarray, optional)

Returns:

• (numpy.ndarray) -- transformed position.

convert_to_str(v)

Convert from object to str, and remove spaces.

Parameters:

v (Any) -- object.

Returns:

• (str) -- converted str.

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.

create_style_sheet(size)

Create style sheet.

Parameters:

size (int) -- font size (point).

Returns:

• (str) -- style sheet string.

read_dict(filename)

Read dict text file.

Parameters:

filename (str) -- file name.

Returns:

• (dict) -- dictionary from dict text.

set_latex_setting()

Set LaTeX setting.

split_filename(filename)

Split file name.

Parameters:

filename (str) -- filename.

Returns:

• (str) -- filename with absolute path.

• (str) -- filename with relative path.

• (str) -- base filename.

• (str) -- extension.

• (str) -- directory.

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.

Versatile utility.

This module contains the utilities mainly for string and list.

affine_trans(v, s=None, A=None, digit=None, check_var=None)

Affine transformation, A.v + s.

Parameters:

• v (str) -- site/vector or a list of site/vector.

• s (str, optional) -- shift vector or a list of shift vector.

• A (str, optional) -- rotaional matrix (3x3), [a1, a2, a3].

• digit (int, optional) -- accuracy digit (only for numerical vector).

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

Returns:

• (ndarray) -- transformed vector.

apply_to_list(func, lst)

Apply a function to each element of a list.

Parameters:

• func (function) -- a function.

• lst (list) -- a list.

Returns:

• (list) -- an applied list.

Note

• applicable to an irregular-shaped list.

apply_to_numpy(func, lst)

Apply a function to each element of ndarray.

Parameters:

• func (function) -- a function.

• lst (ndarray) -- a numpy array.

Returns:

• (ndarray) -- an applied array.

Note

• applicable only to a regular-shaped ndarray.

get_variable(sp_ex)

Get variables used in a sympy expression.

Parameters:

sp_ex (sympy) -- a sympy expression (except for Matrix).

Returns:

• (list) -- variable strings (sorted).

is_regular_list(lst)

Is regular-shaped list ?

Parameters:

lst (list) -- a list.

Returns:

• (bool) -- is regular-shaped list ?

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_numpy(s, digit=None, check_var=None, check_shape=None)

Convert a string (list) to a numpy array.

Parameters:

• s (str) -- a string (list).

• digit (int, optional) -- accuracy digit (only for numerical vector).

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

• check_shape (tuple, optional) -- shape to check.

Returns:

a numpy array.

Return type:

• (ndarray)

Note

• when parse error occurrs, return None.

• in check_shape, '0' means no check.

str_to_sympy(s, check_var=None, rational=True, subs=None)

Convert a string to a sympy.

Parameters:

• s (str) -- a string.

• local (dict, optional) -- variables to replace.

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

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

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

Returns:

• (sympy) -- a sympy.

Notes

• if format error occurs, return None.

• if s cannot be converted to a sympy, return None.

str_to_sympy1(s, check_var=None, rational=True, subs=None)

Convert a string to a sympy (new version).

Parameters:

• s (str) -- a string.

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

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

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

Returns:

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

Notes

• if format error occurs, raise ValueError.

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

to_fraction(x, max_denominator=1000000)

Convert a float number to a fractional one.

Parameters:

• x (float) -- a float number.

• max_denominator (int, optional) -- max. of denominator.

Returns:

• (str) -- a fractional string.

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_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.

Color selector widget.

This module provides color selector widget.

color2pixmap(color_type, size, aspect_ratio=4, step=50)

Convert color/colormap to QPixmap.

Parameters:

• color_type (str) -- color type, "color/colormap/color_both".

• size (int) -- size of pixmap.

• aspect_ratio (int, optional) -- aspect ratio of pximap (width/height).

• steps (int, optional) -- division of colorbar gradation.

Retruns:

• (dict) -- pixmap dict {name: pixmap}.

• (list) -- separator position.