Pivotpy API Reference

Vasprun Parser

pivotpy.vr_parser.Dict2Data(d)[source]
  • Returns a Data object with dictionary keys as attributes of Data accessible by dot notation.

  • Parmeters
    • dict : Python dictionary (nested as well) containing any python data types.

  • Methods
    • to_dict() : Converts a Data object to dictionary if it could be made a dictionary, otherwise throws relevant error.

    • to_json() : Converts to json str or save to file if outfil given. Accepts indent as parameter.

    • to_pickle(): Converts to bytes str or save to file if outfile given.

  • Example

    > x = Dict2Data({‘A’:1,’B’:{‘C’:2}}) > x > Data( > A = 1 > B = Data( > C = 2 > ) > ) > x.B.to_dict() > {‘C’: 2}

pivotpy.vr_parser.read_asxml(path=None)[source]
  • Reads a big vasprun.xml file into memory once and then apply commands. If current folder contains vasprun.xml file, it automatically picks it.

  • Parameters
    • path : Path/To/vasprun.xml

  • Returns
    • xml_data : Xml object to use in other functions

pivotpy.vr_parser.get_summary(xml_data=None)[source]
  • Returns overview of system parameters.

  • Parameters
    • xml_data : From read_asxml function

  • Returns
    • Data : pivotpy.Dict2Data with attibutes accessible via dot notation.

pivotpy.vr_parser.get_kpts(xml_data=None, skipk=0, joinPathAt=[])[source]

Returns kpoints and calculated kpath.

Parameters:

xml_data

From read_asxml function.

skipkint

Number of initil kpoints to skip.

joinPathAtlist

List of indices of kpoints where path is broken.

Returns:

Datapivotpy.Dict2Data

with attibutes kpath and kpoints.

pivotpy.vr_parser.get_tdos(xml_data=None, spin_set=1, elim=[])[source]
  • Returns total dos for a spin_set (default 1) and energy limit. If spin-polarized calculations, gives SpinUp and SpinDown keys as well.

  • Parameters
    • xml_data : From read_asxml function

    • spin_set : int, default is 1.and

    • elim : List [min,max] of energy, default empty.

  • Returns
    • Data : pivotpy.Dict2Data with attibutes E_Fermi, ISPIN,tdos.

pivotpy.vr_parser.get_evals(xml_data=None, skipk=None, elim=[])[source]
  • Returns eigenvalues as numpy array. If spin-polarized calculations, gives SpinUp and SpinDown keys as well.

  • Parameters
    • xml_data : From read_asxml function

    • skipk : Number of initil kpoints to skip.

    • elim : List [min,max] of energy, default empty.

  • Returns
    • Data : pivotpy.Dict2Data with attibutes evals and related parameters.

pivotpy.vr_parser.get_bands_pro_set(xml_data=None, spin_set=1, skipk=0, bands_range=None, set_path=None)[source]
  • Returns bands projection of a spin_set(default 1). If spin-polarized calculations, gives SpinUp and SpinDown keys as well.

  • Parameters
    • xml_data : From read_asxml function

    • skipk : Number of initil kpoints to skip (Default 0).

    • spin_set : Spin set to get, default is 1.

    • bands_range : If elim used in get_evals,that will return bands_range to use here. Note that range(0,2) will give 2 bands 0,1 but tuple (0,2) will give 3 bands 0,1,2.

    • set_path : path/to/_set[1,2,3,4].txt, works if split_vasprun is used before.

  • Returns
    • Data : pivotpy.Dict2Data with attibutes of bands projections and related parameters.

pivotpy.vr_parser.get_dos_pro_set(xml_data=None, spin_set=1, dos_range=None)[source]
  • Returns dos projection of a spin_set(default 1) as numpy array. If spin-polarized calculations, gives SpinUp and SpinDown keys as well.

  • Parameters
    • xml_data : From read_asxml function

    • spin_set : Spin set to get, default 1.

    • dos_range : If elim used in get_tdos,that will return dos_range to use here..

  • Returns
    • Data : pivotpy.Dict2Data with attibutes of dos projections and related parameters.

pivotpy.vr_parser.get_structure(xml_data=None)[source]
  • Returns structure’s volume,basis,positions and rec-basis.

  • Parameters
    • xml_data : From read_asxml function.

  • Returns
    • Data : pivotpy.Dict2Data with attibutes volume,basis,positions and rec_basis.

pivotpy.vr_parser.export_vasprun(path=None, skipk=None, elim=[], joinPathAt=[], shift_kpath=0)[source]
  • Returns a full dictionary of all objects from vasprun.xml file. It first try to load the data exported by powershell’s Export-VR(Vasprun), which is very fast for large files. It is recommended to export large files in powershell first.

  • Parameters
    • path : Path to vasprun.xml file. Default is ‘./vasprun.xml’.

    • skipk : Default is None. Automatically detects kpoints to skip.

    • elim : List [min,max] of energy interval. Default is [], covers all bands.

    • joinPathAt : List of indices of kpoints where path is broken.

    • shift_kpath: Default 0. Can be used to merge multiple calculations on single axes side by side.

  • Returns
    • DataData accessible via dot notation containing nested Data objects:
      • sys_info : System Information

      • dim_info : Contains information about dimensions of returned objects.

      • kpoints : numpy array of kpoints with excluded IBZKPT points

      • kpath : 1D numpy array directly accessible for plot.

      • bands : Data containing bands.

      • tdos : Data containing total dos.

      • pro_bands : Data containing bands projections.

      • pro_dos : Data containing dos projections.

      • poscar : Data containing basis,positions, rec_basis and volume.

pivotpy.vr_parser.load_export(path='./vasprun.xml', joinPathAt=[], shift_kpath=0, path_to_ps='pwsh', skipk=None, max_filled=10, max_empty=10, keep_files=True)[source]
  • Returns a full dictionary of all objects from vasprun.xml file exported using powershell.

  • Parameters
    • path : Path to vasprun.xml file. Default is ‘./vasprun.xml’.

    • skipk : Default is None. Automatically detects kpoints to skip.

    • path_to_ps : Path to powershell.exe. Automatically picks on Windows and Linux if added to PATH.

    • joinPathAt : List of indices of kpoints where path is broken.

    • shift_kpath: Default 0. Can be used to merge multiple calculations side by side.

    • keep_files : Could be use to clean exported text files. Default is True.

    • max_filled : Number of filled bands below and including VBM. Default is 10.

    • max_empty : Number of empty bands above VBM. Default is 10.

  • Returns
    • DataData accessible via dot notation containing nested Data objects:
      • sys_info : System Information

      • dim_info : Contains information about dimensions of returned objects.

      • kpoints : numpy array of kpoints with excluded IBZKPT points

      • kpath : 1D numpy array directly accessible for plot.

      • bands : Data containing bands.

      • tdos : Data containing total dos.

      • pro_bands : Data containing bands projections.

      • pro_dos : Data containing dos projections.

      • poscar : Data containing basis,positions, rec_basis and volume.

pivotpy.vr_parser.dump_dict(dict_data=None, dump_to='pickle', outfile=None, indent=1)[source]
  • Dump an export_vasprun or load_export’s Data object or any dictionary to json or pickle string/file. It convert Dict2Data to dictionary before serializing to json/pickle, so json/pickle.loads() of converted Data would be a simple dictionary, pass that to Dict2Data to again make accessible via dot notation.

  • Parameters
    • dict_data : Any dictionary/Dict2Data object containg numpy arrays, including export_vasprun or load_export output.

    • dump_to : Defualt is pickle or json.

    • outfile : Defualt is None and return string. File name does not require extension.

    • indent : Defualt is 1. Only works for json.

pivotpy.vr_parser.load_from_dump(file_or_str, keep_as_dict=False)[source]
  • Loads a json/pickle dumped file or string by auto detecting it.

  • Parameters
    • file_or_str : Filename of pickl/json or their string.

    • keep_as_dict: Defualt is False and return Data object. If True, returns dictionary.

pivotpy.vr_parser.islice2array(path_or_islice, dtype=<class 'float'>, delimiter='\\s+', include=None, exclude='#', raw=False, fix_format=True, start=0, nlines=None, count=-1, cols=None, new_shape=None)[source]
  • Reads a sliced array from txt,csv type files and return to array. Also manages if columns lengths are not equal and return 1D array. It is faster than loading whole file into memory. This single function could be used to parse EIGENVAL, PROCAR, DOCAR and similar files with just a combination of exclude, include,start,stop,step arguments.

  • Parameters
    • path_or_islice: Path/to/file or itertools.islice(file_object). islice is interesting when you want to read different slices of an opened file and do not want to open it again and again. For reference on how to use it just execute pivotpy.export_potential?? in a notebook cell or ipython terminal to see how islice is used extensively.

    • dtype: float by default. Data type of output array, it is must have argument.

    • start,nlines: The indices of lines to start reading from and number of lines after start respectively. Only work if path_or_islice is a file path. both could be None or int, while start could be a list to read slices from file provided that nlines is int. The spacing between adjacent indices in start should be equal to or greater than nlines as pointer in file do not go back on its own. These parameters are in output of slice_data

    > Note: start should count comments if exclude is None. You can use slice_data function to get a dictionary of start,nlines, count, cols, new_shape and unpack in argument instead of thinking too much. - count: np.size(output_array) = nrows x ncols, if it is known before execution, performance is increased. This parameter is in output of slice_data. - delimiter: Default is s+. Could be any kind of delimiter valid in numpy and in the file. - cols: List of indices of columns to pick. Useful when reading a file like PROCAR which e.g. has text and numbers inline. This parameter is in output of slice_data. - include: Default is None and includes everything. String of patterns separated by | to keep, could be a regular expression. - exclude: Default is ‘#’ to remove comments. String of patterns separated by | to drop,could be a regular expression. - raw : Default is False, if True, returns list of raw strings. Useful to select cols. - fix_format: Default is True, it sepearates numbers with poor formatting like 1.000-2.000 to 1.000 2.000 which is useful in PROCAR. Keep it False if want to read string literally. - new_shape : Tuple of shape Default is None. Will try to reshape in this shape, if fails fallbacks to 2D or 1D. This parameter is in output of slice_data.

  • Examples

    > islice2array(‘path/to/PROCAR’,start=3,include=’k-point’,cols=[3,4,5])[:2] > array([[ 0.125, 0.125, 0.125], > [ 0.375, 0.125, 0.125]]) > islice2array(‘path/to/EIGENVAL’,start=7,exclude=’E’,cols=[1,2])[:2] > array([[-11.476913, 1. ], > [ 0.283532, 1. ]])

> Note: Slicing a dimension to 100% of its data is faster than let say 80% for inner dimensions, so if you have to slice more than 50% of an inner dimension, then just load full data and slice after it.

pivotpy.vr_parser.slice_data(dim_inds, old_shape)[source]
  • Returns a dictionary that can be unpacked in arguments of isclice2array function. This function works only for regular txt/csv/tsv data files which have rectangular data written.

  • Parameters
    • dim_inds : List of indices array or range to pick from each dimension. Inner dimensions are more towards right. Last itmes in dim_inds is considered to be columns. If you want to include all values in a dimension, you can put -1 in that dimension. Note that negative indexing does not work in file readig, -1 is s special case to fetch all items.

    • old_shape: Shape of data set including the columns length in right most place.

  • Example
    • You have data as 3D arry where third dimension is along column.

    > 0 0 > 0 2 > 1 0 > 1 2 - To pick [[0,2], [1,2]], you need to give > slice_data(dim_inds = [[0,1],[1],-1], old_shape=(2,2,2)) > {‘start’: array([1, 3]), ‘nlines’: 1, ‘count’: 2} - Unpack above dictionary in islice2array and you will get output array.

  • Note that dimensions are packed from right to left, like 0,2 is repeating in 2nd column.

pivotpy.vr_parser.split_vasprun(path=None)[source]
  • Splits a given vasprun.xml file into a smaller _vasprun.xml file plus _set[1,2,3,4].txt files which contain projected data for each spin set.

  • Parameters
    • path: path/to/vasprun.xml file.

  • Output
    • _vasprun.xml file with projected data.

    • _set1.txt for projected data of colinear calculation.

    • _set1.txt for spin up data and _set2.txt for spin-polarized case.

    • _set[1,2,3,4].txt for each spin set of non-colinear calculations.

Static Plots

pivotpy.s_plots.init_figure(figsize=3.4, 2.6, nrows=1, ncols=1, widths=[], heights=[], axes_off=[], sharex=False, sharey=False, **subplots_adjust_kwargs)[source]
  • Returns flatten axes of initialized figure, based on plt.subplots(). If you want to access parent figure, use ax.get_figure() or current figure as plt.gcf().

  • Parameters
    • figsize : Tuple (width, height). Default is (3.4,2.6).

    • nrows : Default 1.

    • ncols : Default 1.

    • widths : List with len(widths)==nrows, to set width ratios of subplots.

    • heights : List with len(heights)==ncols, to set height ratios of subplots.

    • share(x,y): Share axes between plots, this removes shared ticks automatically.

    • axes_off : Turn off axes visibility, If nrows = ncols = 1, set True/False, If anyone of nrows or ncols > 1, provide list of axes indices to turn off. If both nrows and ncols > 1, provide list of tuples (x_index,y_index) of axes.

    • **subplots_adjust_kwargs : These are same as plt.subplots_adjust()’s arguements.

pivotpy.s_plots.plot_potential(basis=None, e_or_m=None, operation='mean_z', ax=None, period=None, lr_pos=0.25, 0.75, lr_widths=[0.5, 0.5], labels='$V(z)$', '$\\langle V \\rangle _{roll}(z)$', '$\\langle V \\rangle $', colors=0, 0.2, 0.7, 'b', 'r', annotate=True)[source]
  • Returns tuple(ax,Data) where Data contains resultatnt parameters of averaged potential of LOCPOT.

  • Parameters
    • basis : export_potential().basis.

    • e_or_m : epxort_potential().[e,m,m_x,m_y,m_z] is 3D grid data. As epxort_potential is slow, so compute it once and then plot the output data.

    • operation: Default is ‘mean_z’. What to do with provided volumetric potential data. Anyone of these ‘mean_x’,’min_x’,’max_x’,’mean_y’,’min_y’,’max_y’,’mean_z’,’min_z’,’max_z’.

    • ax: Matplotlib axes, if not given auto picks.

    • period: Periodicity of potential in fraction between 0 and 1. For example if a slab is made of 4 super cells in z-direction, period=0.25.

    • lr_pos: Locations around which averages are taken.Default (0.25,0.75). Provide in fraction between 0 and 1. Center of period is located at these given fractions. Work only if period is given.

    • lr_widths: Default is [0.5,0.5], you may have slabs which have different lengths on left and right side. Provide a pair proportional to widths e.g (1,1), (1,1.1) etc. and it is auto normalized to 1. Works only if period is given.

    • labels: List of three labels for legend. Use plt.legend() or pp.add_legend() for labels to appear. First entry is data plot, second is its convolution and third is complete average.

    • colors: List of three colors for lines.

    • annotate: True by default, writes difference of right and left averages on plot.

pivotpy.s_plots.plt_to_html(plt_fig=None, transparent=True, dash_html=None)[source]
  • Returns base64 encoded Image to display in notebook or HTML <svg> or plotly’s dash_html_components.Img object.

  • Parameters
    • plt_fig : Matplotlib’s figure instance, auto picks as well.

    • transparent: True of False for fig background.

    • dash_htmlDefault is None which results in an image display in jupyter notebook.
      • If True, returns html.Img object for plotly’s dash.

      • If False, returns <svg> object to embed in HTML DOM.

pivotpy.s_plots.quick_bplot(path_evr=None, ax=None, skipk=None, joinPathAt=[], elim=[], xt_indices=[], xt_labels=[], E_Fermi=None, figsize=3.4, 2.6, txt=None, xytxt=[0.05, 0.9], ctxt='black')[source]
  • Returns axes object and plot on which all matplotlib allowed actions could be performed.

  • Parameters
    • path_evr : path/to/vasprun.xml or output of export_vasprun. Auto picks in CWD.

    • ax : Matplotlib axes object, if not given, one is created.

    • skipk : Number of kpoints to skip, default will be from IBZKPT.

    • joinPathAt : Points where kpath is broken.

    • elim : [min,max] of energy range.

    • E_Fermi : If not given, automatically picked from export_vasprun.

    • xt_indices : High symmetry kpoints indices.abs

    • xt_labels : High Symmetry kpoints labels.

    • **kwargs : figsize=(3.4,2.6). Text,its position and color.

  • Returns
    • ax : matplotlib axes object with plotted bands.

pivotpy.s_plots.quick_color_lines(path_evr=None, axes=None, skipk=None, joinPathAt=[], elim=[], elements=[[0]], orbs=[[0]], labels=['s'], color_map='gist_rainbow', scale_data=False, max_width=None, spin='both', xt_indices=[0, - 1], xt_labels=['$\\Gamma$', 'M'], E_Fermi=None, showlegend=True, figsize=3.4, 2.6, txt=None, xytxt=[0.05, 0.85], ctxt='black', interpolate=False, n=5, k=3, legend_kwargs={'anchor': 0, 1.05, 'fontsize': 'small', 'frameon': False, 'handlelength': 1, 'handletextpad': 0.5, 'ncol': 4}, **subplots_adjust_kwargs)[source]
  • Returns axes object and plot on which all matplotlib allowed actions could be performed. If given, elements, orbs, and labels must have same length. If not given, zeroth ion is plotted with s-orbital.

  • Parameters
    • path_evr : Path/to/vasprun.xml or output of export_vasprun. Auto picks in CWD.

    • axes : Matplotlib axes object with one or many axes, if not given, auto created.

    • skipk : Number of kpoints to skip, default will be from IBZKPT.

    • joinPathAt : Points where kpath is broken.

    • elim : [min,max] of energy range.

    • E_Fermi : If not given, automatically picked from export_vasprun.

    • xt_indices : High symmetry kpoints indices.abs

    • xt_labels : High Symmetry kpoints labels.

    • elements : List [[0],], by defualt and plot first ion’s projections.

    • orbs : List [[0],] lists of indices of orbitals, could be empty.

    • labels : List [str,] of orbitals labels. len(labels)==len(orbs) must hold. Auto adds ,`↓` for ISPIN=2. If a label is empty i.e. ‘’, it will not show up in legend.

    • color_map : Matplotlib’s standard color maps. Default is ‘gist_ranibow’.

    • showlegend : True by defualt and displays legend relative to axes[0]. If False, it writes text on individual ax.

    • scale_data : Default is False, If True, normalize projection data to 1.

    • max_width : Width to scale whole projections. Default is None and linewidth at any point on a line = 2.5*sum(ions+orbitals projection of the input for that line at that point). Linewidth is scaled to max_width if an int or float is given.

    • figsize : Tuple (width,height) in inches. Default (3.4.2.6) is article column’s width.

    • txt : Text on figure, if None, SYSTEM’s name is printed.

    • xytxt : [x_coord,y_coord] of text relative to axes.

    • ctxt : color of text.

    • spin : Plot spin-polarized for spin {‘up’,’down’,’both’}. Default is both.

    • interpolate: Default is False, if True, bands are interpolated.

    • n : int, number of points, default is 5.

    • k : int, order of interpolation 0,1,2,3. Defualt 3. n > k should be hold.

    • legend_kwargs: Dictionary containing legend arguments.

    • **subplots_adjust_kwargs : plt.subplots_adjust parameters.

  • Returns
    • ax : matplotlib axes object with plotted projected bands.

> Note: Two figures made by this function could be comapred quantitatively only if scale_data=False, max_width=None as these parameters act internally on data.

pivotpy.s_plots.quick_dos_lines(path_evr=None, ax=None, elim=[], include_dos='both', elements=[[0]], orbs=[[0]], labels=['s'], color_map='gist_rainbow', tdos_color=0.8, 0.95, 0.8, linewidth=0.5, fill_area=True, vertical=False, E_Fermi=None, figsize=3.4, 2.6, txt=None, xytxt=[0.05, 0.85], ctxt='black', spin='both', interpolate=False, n=5, k=3, showlegend=True, legend_kwargs={'anchor': 0, 1, 'fontsize': 'small', 'frameon': False, 'handlelength': 1, 'handletextpad': 0.5, 'ncol': 4})[source]
  • Returns ax object (if ax!=False) and plot on which all matplotlib allowed actions could be performed, returns lists of energy,tdos and pdos and labels. If given,elements,orbs colors, and labels must have same length. If not given, zeroth ions is plotted with s-orbital.

  • Parameters)
    • path_evr : Path/to/vasprun.xml or output of export_vasprun. Auto picks in CWD.

    • ax : Matplotlib axes object, if None, one is created. If False, data lists are returned.

    • include_dos: One of {‘both’,’tdos’,’pdos’}.

    • elim : [min,max] of energy range.

    • E_Fermi : If not given, automatically picked from export_vasprun.

    • elements : List [[0],], by defualt and plot first ion’s projections.

    • orbs : List [[0],] lists of indices of orbitals, could be empty.

    • labels : List [str,] of orbitals labels. len(labels)==len(orbs) must hold. Auto adds ,`↓` for ISPIN=2.

    • color_map : Matplotlib’s standard color maps. Default is ‘gist_ranibow’. Use ‘RGB’ if want to compare with quick_rgb_lines with 3 projection inputs (len(orbs)==3).

    • fill_area : Default is True and plots filled area for dos. If False, plots lines only.

    • vertical : False, If True, plots along y-axis.

    • showlegend : True by defualt.

    • figsize : Tuple (width,height) in inches. Default (3.4.2.6) is article column’s width.

    • txt : Text on figure, if None, SYSTEM’s name is printed.

    • xytxt : [x_coord,y_coord] of text relative to axes.

    • ctxt : color of text.

    • spin : Plot spin-polarized for spin {‘up’,’down’,’both’}. Default is both.

    • interpolate: Default is False, if True, bands are interpolated.

    • n : int, number of points, default is 5.

    • k : int, order of interpolation 0,1,2,3. Defualt 3. n > k should be hold.

    • legend_kwargs: Dictionary to contain legend arguments to fix.

  • Returns
    • ax : Matplotlib axes.

pivotpy.s_plots.quick_rgb_lines(path_evr=None, ax=None, skipk=None, joinPathAt=[], elim=[], elements=[[0], [], []], orbs=[[0], [], []], labels=['Elem0-s', '', ''], max_width=None, xt_indices=[0, - 1], xt_labels=['$\\Gamma$', 'M'], E_Fermi=None, figsize=3.4, 2.6, txt=None, xytxt=[0.05, 0.9], ctxt='black', uni_width=False, interpolate=False, spin='both', n=5, k=3, scale_color=True, scale_data=True, colorbar=True, color_matrix=None)[source]
  • Returns axes object and plot on which all matplotlib allowed actions could be performed. In this function,orbs,labels,elements all have list of length 3. Inside list, sublists or strings could be any length but should be there even if empty.

  • Parameters
    • path_evr : path/to/vasprun.xml or output of export_vasprun. Auto picks in CWD.

    • ax : Matplotlib axes object, if not given, one is created.

    • skipk : Number of kpoints to skip, default will be from IBZKPT.

    • joinPathAt : Points where kpath is broken.

    • elim : [min,max] of energy range.

    • E_Fermi : If not given, automatically picked from export_vasprun.

    • xt_indices : High symmetry kpoints indices.abs

    • xt_labels : High Symmetry kpoints labels.

    • elements : List [[0],[],[]] by default and plots s orbital of first ion..

    • orbs : List [[r],[g],[b]] of indices of orbitals, could be empty, but shape should be same.

    • labels : List [str,str,str] of projection labels. empty string should exist to maintain shape. Auto adds ,`↓` for ISPIN=2. If a label is empty i.e. ‘’, it will not show up in colorbar ticks or legend.

    • max_width : Width to scale whole projections. if uni_width=True, width=max_width/2. Default is None and linewidth at any point = 2.5*sum(ions+orbitals projection of all three input at that point). Linewidth is scaled to max_width if an int or float is given.

    • figsize : Tuple (width,height) in inches. Default (3.4.2.6) is article column’s width.

    • txt : Text on figure, if None, SYSTEM’s name is printed.

    • xytxt : [x_coord,y_coord] of text relative to axes.

    • ctxt : color of text.

    • uni_width : If True, width of bands kept uniform.

    • spin : Plot spin-polarized for spin {‘up’,’down’,’both’}. Default is both.

    • interpolate: Default is False, if True, bands are interpolated.

    • n : int, number of points, default is 5.

    • k : int, order of interpolation 0,1,2,3. Defualt 3. n > k should be hold.

    • scale_color: Boolean. Default True, colors are scaled to 1 at each point. If False, clips colors in range [0,1] but does not effect linewidth.

    • scale_data : Default is True and normalizes projection data to 1. Has no visual effect if scale_color = True too.

    • colorbar : Default is True. Displays a vertical RGB colorbar.

    • color_matrix: Only works if scale_color==True. 3x3 or 3x4 numpy array or list to transform from RGB to another space,provided that sum(color_matrix[i,:3]) <= 1. 4th column, if given can be used to control the saturation,contrast and brightness as s,c,b = color_matrix[:,3] For simply changing the color intensity use np.diag([r,g,b]) with r,g,b interval in [0,1]. Try pivotpy.color_matrix as suggested color matrix and modify, which at s=0 returns gray scale.!

  • Returns
    • ax : matplotlib axes object with plotted projected bands.

    • Registers as colormap RGB_m to use in DOS to plot in same colors and RGB_f to display bands colorbar on another axes.

> Note: Two figures made by this function could be comapred quantitatively only if scale_data=False, max_width=None, scale_color=False as these parameters act internally on data.

Interactive Plots

pivotpy.i_plots.plotly_dos_lines(path_evr=None, elim=[], elements=[[0]], orbs=[[0]], labels=['s'], color_map='gist_rainbow', tdos_color=0.5, 0.95, 0, linewidth=2, fill_area=True, vertical=False, E_Fermi=None, figsize=None, spin='both', interpolate=False, n=5, k=3, title=None)[source]
  • Returns ax object (if ax!=False) and plot on which all matplotlib allowed actions could be performed, returns lists of energy,tdos and pdos and labels. If given,elements,orbs colors, and labels must have same length. If not given, zeroth ions is plotted with s-orbital.

  • Parameters)
    • path_evr : Path/to/vasprun.xml or output of export_vasprun. Auto picks in CWD.

    • elim : [min,max] of energy range.

    • E_Fermi : If not given, automatically picked from export_vasprun.

    • elements : List [[0,],] of ions indices, by defualt plot first ion’s projections.

    • orbs : List [[0,],] lists of indices of orbitals, could be empty.

    • labels : List [str,] of orbitals labels. len(labels)==len(orbs) must hold.

    • color_map : Matplotlib’s standard color maps. Default is ‘gist_ranibow’. Use ‘RGB’ if want to compare with plotly_rgb_lines with 3 projection inputs (len(orbs)==3).

    • fill_area : Default is True and plots filled area for dos. If False, plots lines only.

    • vertical : False, If True, plots along y-axis.

    • figsize : Tuple in pixels (width,height).

    • interpolate: Default is False, if True, bands are interpolated.

    • n : int, number of points, default is 5.

    • k : int, order of interpolation 0,1,2,3. Defualt 3. n > k should be hold.

    • legend_kwargs: Dictionary to contain legend arguments to fix.

  • Returns
    • fig : Plotly’s figure object.

pivotpy.i_plots.plotly_rgb_lines(path_evr=None, elements=[[], [], []], orbs=[[], [], []], labels=['', '', ''], mode='markers', elim=[], E_Fermi=None, skipk=None, joinPathAt=[], max_width=6, title=None, xt_indices=[0, - 1], xt_labels=['Γ', 'M'], figsize=None, interpolate=False, n=5, k=3)[source]
  • Returns plotly’s figure object, takes care of spin-polarized calculations automatically. elements,`orbs` and labels are required to be one-to-one lists of size 3 where each item in list could be another list or integer.

  • Parameters
    • path_evr : Path/to/vasprun.xml or xml output of read_asxml.

    • elements : List of size 3 of list of indices of ions. If not given, picks all ions for each orbital.

    • orbs : List of size 3 of list of orbital indices, if not gievn, s,p,d plotted.

    • labels : List of labels for projection.

    • modeThree plotting modes are available:
      • ‘markers’ : Plot whole data as a single scatter object. Its too fast.

      • ‘bands’ : Plot data such that each band is accessible via legend.

      • ‘lines’ : A replica of matplotlib LineCollection object. It plots at each point separately, slower than other two modes.

    • **kwargs : interpolate, ticks, figsize,elim,joinPathAt,max_width,title etc.

pivotpy.i_plots.plotly_to_html(fig, filename=None, out_string=False, modebar=True)[source]
  • Writes plotly’s figure as HTML file or display in IPython which is accessible when online. It is different than plotly’s fig.to_html as it is minimal in memory. If you need to have offline working file, just use fig.write_html(‘file.html’) which will be larger in size.

  • Parameters
    • fig : A plotly’s figure object.

    • filename : Name of file to save fig. Defualt is None and show plot in Colab/Online or return hrml string.

    • out_string: If True, returns HTML string, if False displays graph if possible.

Utilities

class pivotpy.g_utils.DecodeToNumpy(*args, **kwargs)[source]
  • Deserilizes JSON object to Python/Numpy’s objects.

  • Usage
    • json.loads(json_string,cls=DecodeToNumpy) from string, use json.load() for file.

class pivotpy.g_utils.EncodeFromNumpy(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)[source]
  • Serializes python/Numpy objects via customizing json encoder.

  • Usage
    • json.dumps(python_dict, cls=EncodeFromNumpy) to get json string.

    • json.dump(*args, cls=EncodeFromNumpy) to create a file.json.

default(obj)[source]

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return JSONEncoder.default(self, o)
class pivotpy.g_utils.LOCPOT_CHG(path=None, e=True, m=False)[source]
  • Returns Data from LOCPOT and similar structure files like CHG. Loads only single set out of 2/4 magnetization data to avoid performance/memory cost while can load electrostatic and one set of magnetization together.

  • Parameters
    • path: path/to/LOCPOT or similar stuructured file like CHG. LOCPOT is auto picked in CWD.

    • e : Electric potential/charge density. Default is True.

    • m : Magnetization density m. Default is False. If True, picks m for spin polarized case, and m_x for non-colinear case. Additionally it can take ‘x’,’y’ and ‘z’ in case of non-colinear calculations.

  • Exceptions
    • Would raise index error if magnetization density set is not present in LOCPOT/CHG in case m is not False.

view_period(period_guess=0.25, operation='mean_z', nslice=10, e_or_m=None)[source]
  • Periodicity check by plotly’s interactive plot.

  • Parameters
    • period_guess: Initial guess of period. Default is 0.25. Should be in [0,1].

    • operation : Any of [‘mean_x’,’min_x’,’max_x’,’mean_y’,’min_y’,’max_y’,’mean_z’,’min_z’,’max_z’].

    • nslice : Default is 10. Number of periods around and including period_guess. e.g. If you give 0.25 as period_guess and nslice is 10, you will get 10 lines of rolling average over given data from where you can choose best fit or try another guess and so on.

    • e_or_m : None by default. Not required in most cases as view_period() will try to get data itself from top class in order of self.data.[e,m,m_x,m_y,m_z] and if self.data.e exists it never goes to others, so you can overwrite this by setting e_or_m = self.data.[your choice].

class pivotpy.g_utils.Vasprun(path=None, skipk=None, elim=[], joinPathAt=[], shift_kpath=0)[source]
  • All plotting functions that depend on export_vasprun are joined under this class and renamed.

  • Parameters
    • path : str: path/to/vasprun.xml. Auto picks in CWD.

    • skipk : int: Skip initial kpoints

    • elim : list: Energy range e.g. [-5,5]

    • joinPathAt : list: Join broken path at given indices. Could be obtained from SEG-INDS if used trace_kpath.

    • shift_kpath: float: Shift in kpath values for side by side plotting.

  • Attributes
    • data : Return of export_vasprun which is auto-picked in plotting methods under this class.

  • Methods
    • sbands : Shortcut for quick_bplot.

    • sdos : Shortcut for quick_dos_lines.

    • srgb : Shortcut for quick_rgb_lines.

    • scolor : Shortcut for quick_color_lines.

    • idos : Shortcut for plotly_dos_lines.

    • irgb : Shortcut for plotly_rgb_lines.

    • Each of above mathods have an attribute kwargs which can be accessed, modified and put back as argumnets.

  • Example

    > vasp = Vasprun(path=’./vasprun.xml’) > kwargs = vasp.sbands.kwargs > Modify kwargs dictionary as you want for input parameters and unpack back in function. > vasp.sbands(**kwargs)

idos(**kwargs)[source]
  • Returns ax object (if ax!=False) and plot on which all matplotlib allowed actions could be performed, returns lists of energy,tdos and pdos and labels. If given,elements,orbs colors, and labels must have same length. If not given, zeroth ions is plotted with s-orbital.

  • Parameters)
    • elim : [min,max] of energy range.

    • E_Fermi : If not given, automatically picked from export_vasprun.

    • elements : List [[0,],] of ions indices, by defualt plot first ion’s projections.

    • orbs : List [[0,],] lists of indices of orbitals, could be empty.

    • labels : List [str,] of orbitals labels. len(labels)==len(orbs) must hold.

    • color_map : Matplotlib’s standard color maps. Default is ‘gist_ranibow’. Use ‘RGB’ if want to compare with plotly_rgb_lines with 3 projection inputs (len(orbs)==3).

    • fill_area : Default is True and plots filled area for dos. If False, plots lines only.

    • vertical : False, If True, plots along y-axis.

    • figsize : Tuple in pixels (width,height).

    • interpolate: Default is False, if True, bands are interpolated.

    • n : int, number of points, default is 5.

    • k : int, order of interpolation 0,1,2,3. Defualt 3. n > k should be hold.

    • legend_kwargs: Dictionary to contain legend arguments to fix.

  • Returns
    • fig : Plotly’s figure object.

irgb(**kwargs)[source]
  • Returns plotly’s figure object, takes care of spin-polarized calculations automatically. elements,`orbs` and labels are required to be one-to-one lists of size 3 where each item in list could be another list or integer.

  • Parameters
    • elements : List of size 3 of list of indices of ions. If not given, picks all ions for each orbital.

    • orbs : List of size 3 of list of orbital indices, if not gievn, s,p,d plotted.

    • labels : List of labels for projection.

    • modeThree plotting modes are available:
      • ‘markers’ : Plot whole data as a single scatter object. Its too fast.

      • ‘bands’ : Plot data such that each band is accessible via legend.

      • ‘lines’ : A replica of matplotlib LineCollection object. It plots at each point separately, slower than other two modes.

    • **kwargs : interpolate, ticks, figsize,elim,joinPathAt,max_width,title etc.

sbands(**kwargs)[source]
  • Returns axes object and plot on which all matplotlib allowed actions could be performed.

  • Parameters
    • ax : Matplotlib axes object, if not given, one is created.

    • skipk : Number of kpoints to skip, default will be from IBZKPT.

    • joinPathAt : Points where kpath is broken.

    • elim : [min,max] of energy range.

    • E_Fermi : If not given, automatically picked from export_vasprun.

    • xt_indices : High symmetry kpoints indices.abs

    • xt_labels : High Symmetry kpoints labels.

    • **kwargs : figsize=(3.4,2.6). Text,its position and color.

  • Returns
    • ax : matplotlib axes object with plotted bands.

scolor(**kwargs)[source]
  • Returns axes object and plot on which all matplotlib allowed actions could be performed. If given, elements, orbs, and labels must have same length. If not given, zeroth ion is plotted with s-orbital.

  • Parameters
    • axes : Matplotlib axes object with one or many axes, if not given, auto created.

    • skipk : Number of kpoints to skip, default will be from IBZKPT.

    • joinPathAt : Points where kpath is broken.

    • elim : [min,max] of energy range.

    • E_Fermi : If not given, automatically picked from export_vasprun.

    • xt_indices : High symmetry kpoints indices.abs

    • xt_labels : High Symmetry kpoints labels.

    • elements : List [[0],], by defualt and plot first ion’s projections.

    • orbs : List [[0],] lists of indices of orbitals, could be empty.

    • labels : List [str,] of orbitals labels. len(labels)==len(orbs) must hold. Auto adds ,`↓` for ISPIN=2. If a label is empty i.e. ‘’, it will not show up in legend.

    • color_map : Matplotlib’s standard color maps. Default is ‘gist_ranibow’.

    • showlegend : True by defualt and displays legend relative to axes[0]. If False, it writes text on individual ax.

    • scale_data : Default is False, If True, normalize projection data to 1.

    • max_width : Width to scale whole projections. Default is None and linewidth at any point on a line = 2.5*sum(ions+orbitals projection of the input for that line at that point). Linewidth is scaled to max_width if an int or float is given.

    • figsize : Tuple (width,height) in inches. Default (3.4.2.6) is article column’s width.

    • txt : Text on figure, if None, SYSTEM’s name is printed.

    • xytxt : [x_coord,y_coord] of text relative to axes.

    • ctxt : color of text.

    • spin : Plot spin-polarized for spin {‘up’,’down’,’both’}. Default is both.

    • interpolate: Default is False, if True, bands are interpolated.

    • n : int, number of points, default is 5.

    • k : int, order of interpolation 0,1,2,3. Defualt 3. n > k should be hold.

    • legend_kwargs: Dictionary containing legend arguments.

    • **subplots_adjust_kwargs : plt.subplots_adjust parameters.

  • Returns
    • ax : matplotlib axes object with plotted projected bands.

> Note: Two figures made by this function could be comapred quantitatively only if scale_data=False, max_width=None as these parameters act internally on data.

sdos(**kwargs)[source]
  • Returns ax object (if ax!=False) and plot on which all matplotlib allowed actions could be performed, returns lists of energy,tdos and pdos and labels. If given,elements,orbs colors, and labels must have same length. If not given, zeroth ions is plotted with s-orbital.

  • Parameters)
    • ax : Matplotlib axes object, if None, one is created. If False, data lists are returned.

    • include_dos: One of {‘both’,’tdos’,’pdos’}.

    • elim : [min,max] of energy range.

    • E_Fermi : If not given, automatically picked from export_vasprun.

    • elements : List [[0],], by defualt and plot first ion’s projections.

    • orbs : List [[0],] lists of indices of orbitals, could be empty.

    • labels : List [str,] of orbitals labels. len(labels)==len(orbs) must hold. Auto adds ,`↓` for ISPIN=2.

    • color_map : Matplotlib’s standard color maps. Default is ‘gist_ranibow’. Use ‘RGB’ if want to compare with quick_rgb_lines with 3 projection inputs (len(orbs)==3).

    • fill_area : Default is True and plots filled area for dos. If False, plots lines only.

    • vertical : False, If True, plots along y-axis.

    • showlegend : True by defualt.

    • figsize : Tuple (width,height) in inches. Default (3.4.2.6) is article column’s width.

    • txt : Text on figure, if None, SYSTEM’s name is printed.

    • xytxt : [x_coord,y_coord] of text relative to axes.

    • ctxt : color of text.

    • spin : Plot spin-polarized for spin {‘up’,’down’,’both’}. Default is both.

    • interpolate: Default is False, if True, bands are interpolated.

    • n : int, number of points, default is 5.

    • k : int, order of interpolation 0,1,2,3. Defualt 3. n > k should be hold.

    • legend_kwargs: Dictionary to contain legend arguments to fix.

  • Returns
    • ax : Matplotlib axes.

srgb(**kwargs)[source]
  • Returns axes object and plot on which all matplotlib allowed actions could be performed. In this function,orbs,labels,elements all have list of length 3. Inside list, sublists or strings could be any length but should be there even if empty.

  • Parameters
    • ax : Matplotlib axes object, if not given, one is created.

    • skipk : Number of kpoints to skip, default will be from IBZKPT.

    • joinPathAt : Points where kpath is broken.

    • elim : [min,max] of energy range.

    • E_Fermi : If not given, automatically picked from export_vasprun.

    • xt_indices : High symmetry kpoints indices.abs

    • xt_labels : High Symmetry kpoints labels.

    • elements : List [[0],[],[]] by default and plots s orbital of first ion..

    • orbs : List [[r],[g],[b]] of indices of orbitals, could be empty, but shape should be same.

    • labels : List [str,str,str] of projection labels. empty string should exist to maintain shape. Auto adds ,`↓` for ISPIN=2. If a label is empty i.e. ‘’, it will not show up in colorbar ticks or legend.

    • max_width : Width to scale whole projections. if uni_width=True, width=max_width/2. Default is None and linewidth at any point = 2.5*sum(ions+orbitals projection of all three input at that point). Linewidth is scaled to max_width if an int or float is given.

    • figsize : Tuple (width,height) in inches. Default (3.4.2.6) is article column’s width.

    • txt : Text on figure, if None, SYSTEM’s name is printed.

    • xytxt : [x_coord,y_coord] of text relative to axes.

    • ctxt : color of text.

    • uni_width : If True, width of bands kept uniform.

    • spin : Plot spin-polarized for spin {‘up’,’down’,’both’}. Default is both.

    • interpolate: Default is False, if True, bands are interpolated.

    • n : int, number of points, default is 5.

    • k : int, order of interpolation 0,1,2,3. Defualt 3. n > k should be hold.

    • scale_color: Boolean. Default True, colors are scaled to 1 at each point. If False, clips colors in range [0,1] but does not effect linewidth.

    • scale_data : Default is True and normalizes projection data to 1. Has no visual effect if scale_color = True too.

    • colorbar : Default is True. Displays a vertical RGB colorbar.

    • color_matrix: Only works if scale_color==True. 3x3 or 3x4 numpy array or list to transform from RGB to another space,provided that sum(color_matrix[i,:3]) <= 1. 4th column, if given can be used to control the saturation,contrast and brightness as s,c,b = color_matrix[:,3] For simply changing the color intensity use np.diag([r,g,b]) with r,g,b interval in [0,1]. Try pivotpy.color_matrix as suggested color matrix and modify, which at s=0 returns gray scale.!

  • Returns
    • ax : matplotlib axes object with plotted projected bands.

    • Registers as colormap RGB_m to use in DOS to plot in same colors and RGB_f to display bands colorbar on another axes.

> Note: Two figures made by this function could be comapred quantitatively only if scale_data=False, max_width=None, scale_color=False as these parameters act internally on data.

pivotpy.g_utils.export_outcar(path=None)[source]
  • Read potential at ionic sites from OUTCAR.

pivotpy.g_utils.export_potential(locpot=None, e=True, m=False)[source]
  • Returns Data from LOCPOT and similar structure files like CHG. Loads only single set out of 2/4 magnetization data to avoid performance/memory cost while can load electrostatic and one set of magnetization together.

  • Parameters
    • locpot: path/to/LOCPOT or similar stuructured file like CHG. LOCPOT is auto picked in CWD.

    • e : Electric potential/charge density. Default is True.

    • m : Magnetization density m. Default is False. If True, picks m for spin polarized case, and m_x for non-colinear case. Additionally it can take ‘x’,’y’ and ‘z’ in case of non-colinear calculations.

  • Exceptions
    • Would raise index error if magnetization density set is not present in LOCPOT/CHG in case m is not False.

pivotpy.g_utils.get_child_items(path='E:\\Research\\pivotpy\\docs_rst', depth=None, recursive=True, include=None, exclude=None, filesOnly=False, dirsOnly=False)[source]
  • Returns selected directories/files recursively from a parent directory.

  • Parameters
    • path : path to a parent directory, default is “.”

    • depth : int, subdirectories depth to get recursively, default is None to list all down.

    • recursive : If False, only list current directory items, if True,list all items recursively down the file system.

    • include: Default is None and includes everything. String of patterns separated by | to keep, could be a regular expression.

    • exclude: Default is None and removes nothing. String of patterns separated by | to drop,could be a regular expression.

    • filesOnly : Boolean, if True, returns only files.

    • dirsOnly : Boolean, if True, returns only directories.

  • Returns
    • GLOB : Tuple (children,parent), children is list of selected directories/files and parent is given path. Access by index of by get_child_items().{children,path}.

pivotpy.g_utils.interpolate_data(x, y, n=10, k=3)[source]
  • Returns interpolated xnew,ynew. If two points are same, it will add 0.1*min(dx>0) to compensate it.

  • Parameters
    • x: 1D array of size p,

    • y: ndarray of size p*q*r,….

    • n: Number of points to add between two given points.

    • k: Polynomial order to interpolate.

  • Only axis 0 will be interpolated. If you want general interploation, use from scipy.interpolate import make_interp_spline, BSpline

  • General Usage: K(p),E(p,q) input from bandstructure.
    • Knew,Enew= interpolate_data(K,E,n=10,k=3). cubic interploation

pivotpy.g_utils.ps_to_py(ps_command='Get-ChildItem', exec_type='-Command', path_to_ps='powershell.exe')[source]
  • Captures powershell output in python.

  • Parameters
    • ps_command: enclose ps_command in ‘ ‘ or ” “.

    • exec_type : type of execution, default ‘-Command’, could be ‘-File’.

    • path_to_ps: path to powerhell.exe if not added to PATH variables.

pivotpy.g_utils.ps_to_std(ps_command='Get-ChildItem', exec_type='-Command', path_to_ps='powershell.exe')[source]
  • Prints powershell output in python std.

  • Parameters
    • ps_command: enclose ps_command in ‘ ‘ or ” “.

    • exec_type: type of execution, default ‘-Command’, could be ‘-File’.

    • path_to_ps: path to powerhell.exe if not added to PATH variables.

pivotpy.g_utils.transform_color(arr, s=1, c=1, b=0, mixing_matrix=None)[source]
  • Color transformation such as brightness, contrast, saturation and mixing of an input color array. c = -1 would invert color,keeping everything else same.

  • Parameters
    • arr: input array, a single RGB/RGBA color or an array with inner most dimension equal to 3 or 4. e.g. [[[0,1,0,1],[0,0,1,1]]].

    • c : contrast, default is 1. Can be a float in [-1,1].

    • s : saturation, default is 1. Can be a float in [-1,1]. If s = 0, you get a gray scale image.

    • b : brightness, default is 0. Can be a float in [-1,1] or list of three brightnesses for RGB components.

    • mixing_matrix: A 3x3 matrix to mix RGB values, such as pp.color_matrix.

[Recoloring](https://docs.microsoft.com/en-us/windows/win32/gdiplus/-gdiplus-recoloring-use?redirectedfrom=MSDN) [Rainmeter](https://docs.rainmeter.net/tips/colormatrix-guide/)

Interactive Widgets

pivotpy.widgets.get_files_gui(auto_fill='vasprun.xml', html_style=None, height=320)[source]
  • Creates a GUI interface for files/folders filtering.

  • Parmeters
    • auto_fill : Default is vasprun.xml, any file/folder.

    • html_style : None,`dark_style` or light_style.

    • height : Height of Grid box.

  • Returns
    • Tuple(GUI_gridbox,Files_Dropdown). Access second one by item itself.

pivotpy.widgets.get_input_gui(rgb=True, sys_info=None, html_style=None, height=400)[source]
  • Creates a GUI interface for input/selection of orbitals/ions projection.

  • Parmeters
    • rgb : Default is True and generates input for plotly(quick)_rgb_lines, if False creates input for quick(plotly)_dos(color)_lines

    • html_style : None,`dark_style` or light_style.

    • height : Height of Grid box.

  • Returns
    • Tuple(GUI_gridbox,json_in_HTML). Access second one by item.value.

pivotpy.widgets.show_app(height=600)[source]

Displays a GUI for visulaizing and manipulating output of vasp calculations. It only has one argument height which sets min-height of the app.

Structue

pivotpy.sio.get_bz(poscar=None, loop=True, digits=8)[source]
  • Return required information to construct first Brillouin zone in form of tuple (basis, normals, vertices, faces).

  • Parameters
    • poscar : POSCAR file or list of 3 vectors in 3D aslist[list,list,list].

    • loop : If True, joins the last vertex of a BZ plane to starting vertex in order to complete loop.

    • digits : int, rounding off decimal places, no effect on intermediate calculations, just for pretty final results

  • Attributes
    • basis : get_bz().basis, recprocal lattice basis.

    • normals : get_bz().normals, all vertors that are perpendicular BZ faces/planes.

    • vertices: get_bz().vertices, all vertices of BZ, could be input into ConvexHull for constructing 3D BZ.

    • faces : get_bz().faces, vertices arranged into faces, could be input to Poly3DCollection of matplotlib for creating BZ from faces’ patches.

    • specials : get_bz().specials, Dictionary of high symmetry KPOINTS with keys as points relative to basis and values are corresponding positions in recirprocal coordinates space.

pivotpy.sio.get_kmesh(n_xyz=[5, 5, 5], weight=None, gamma=True, ibzkpt=None, poscar=None, outfile=None, plot=False)[source]
  • Generate uniform mesh of kpoints. Options are write to file, plot or return KPOINTS list.

  • Parameters
    • n_xyz : List of [nx ny nz] or integer. If integere given, kmesh is autoscaled.

    • weight : Float, if None, auto generates weights.

    • gamma : Default True, shifts mesh at gamma point.

    • ibzkpt : Path to ibzkpt file, required for HSE calculations.

    • poscar : POSCAR file or real space lattice vectors, if None, cubic symmetry is used and it is fast.

    • outfile: Path/to/file to write kpoints.

    • plot : If True, returns interactive plot. You can look at mesh before you start calculation.

  • Attributes
    • If plot = False, a tuple is returned which consists of:
      • nkpts : get_kmesh().nkpts.

      • kpoints : get_kmesh().kpoints.

      • weight : get_kmesh().weight, its one float number, provided or calculated.

pivotpy.sio.get_kpath(hsk_list=[], labels=[], n=5, weight=None, ibzkpt=None, outfile=None)[source]
  • Generate list of kpoints along high symmetry path. Options are write to file or return KPOINTS list. It generates uniformly spaced point with input n as just a scale factor of number of points per unit length. You can also specify custom number of kpoints in an interval by putting number of kpoints as 4th entry in left kpoint.

  • Parameters
    • hsk_list : N x 3 list of N high symmetry points, if broken path then [[N x 3],[M x 3],…]. Optionally you can put a 4 values point where 4th entry will decide number of kpoints in current interval. Make sure that points in a connected path patch are at least two i.e. [[x1,y1,z1],[x2,y2,z2]] or [[x1,y1,z1,N],[x2,y2,z2]].

    • n ; int, number per unit length, this makes uniform steps based on distance between points.

    • weight : Float, if None, auto generates weights.

    • gamma : If True, shifts mesh at gamma point.

    • ibzkpt : Path to ibzkpt file, required for HSE calculations.

    • labels : Hight symmetry points labels. Good for keeping record of lables and points indices for later use. - Note: If you do not want to label a point, label it as ‘skip’ at its index and it will be removed.

    • outfile: Path/to/file to write kpoints.

  • Attributes
    • If outfile = None, a tuple is returned which consists of:
      • nkpts : get_kmesh().nkpts.

      • kpoints : get_kmesh().kpoints.

      • weights : get_kmesh().weights.

pivotpy.sio.get_poscar(formula, api_key=None, mp_id=None, max_sites=None)[source]
  • Returns poscar information dictionary including cif data format.

  • Parameters
    • formula : Material formula such as ‘NaCl’.

    • api_key : API key for your account from material project site. Auto picks if you already used save_mp_API function.

    • mp_id : Optional, you can specify material ID to filter results.

    -max_sites : Option, you can set maximum number of sites to load fastly as it will not fetch all large data sets.

  • Usage
    • get_poscar(‘GaAs’,api_key,**kwargs). Same result is returned from Get-POSCAR command in PowerShell terminal if Vasp2Visual module is installed.

pivotpy.sio.plot_bz(poscar_or_bz=None, fill=True, color='rgba(168,204,216,0.4)', background='rgb(255,255,255)')[source]
  • Plots interactive figure showing axes,BZ surface, special points and basis, each of which could be hidden or shown.

  • Parameters
    • pocar_or_bz: POSCAR or 3 basis vectors’ list forming POSCAR. Auto picks in working directory. Output of get_bz() also works.

    • fill : True by defult, determines whether to fill surface of BZ or not.

    • color : color to fill surface ‘rgba((168,204,216,0.4)` by default.

    • background : Plot background color, default is ‘rgb(255,255,255)’.

  • Returns
    • fig : plotly.graph_object’s Figure instance.

pivotpy.sio.save_mp_API(api_key)[source]
  • Save materials project api key for autoload in functions.