\(\newcommand{\AA}{\text{Å}}\)

CRYSTALpytools.topond module

The module for TOPOND topological analysis of electron density

class ScalarField

Bases: object

Basic TOPOND scalar field class, containing a nY*nX (nZ*nY*nX) data array for 2D (3D) fields. Call the property-specific child classes below to use. 3D methods under development.

plot_2D(levels=100, lineplot=False, contourline=None, isovalues='%.2f', colorplot=False, colormap='jet', cbar_label=None, a_range=[0.0, 1.0], b_range=[0.0, 1.0], edgeplot=False, x_ticks=5, y_ticks=5, figsize=[6.4, 4.8], overlay=None, fig=None, ax_index=None, **kwargs)

Plot 2D contour lines, color maps or both for the 2D data set. The user can also get the overlapped plot of ScalarField and Trajectory classes.

Note

2D periodicity (a_range and b_range), though available for the ScalarField class, is not suggested as TOPOND plotting window does not always commensurate with periodic boundary. The Trajectory class has no 2D periodicity so if overlay is not None, a_range, b_range and edgeplot will be disabled.

3 styles are available:

  1. lineplot=True and colorplot=True: The color-filled contour

    map with black contour lines. Dotted lines for negative values and solid lines for positive values. The solid line twice in width for 0.

  2. lineplot=False and colorplot=True: The color-filled contour

    map.

  3. lineplot=True and colorplot=False: The color coded contour

    line map. Blue dotted line for negative values and red solid lines for positive values. The balck solid line twice in width for 0.

Parameters:

  • levels (array|int) – Set levels of colored / line contour plot. A number for linear scaled plot colors or an array for user-defined levels. 1D.

  • lineplot (bool) – Plot contour lines.

  • contourline (list) – nLevel*3 contour line styles. Useful only if lineplot=True. For every line, color, line style and line width are defined in sequence.

  • isovalues (str|None) – Add isovalues to contour lines and set their formats. Useful only if lineplot=True. None for not adding isovalues.

  • colorplot (bool) – Plot color-filled contour plots.

  • colormap (str) – Matplotlib colormap option. Useful only if colorplot=True.

  • cbar_label (str) – Label of colorbar. Useful only if colorplot=True. ‘None’ for no labels.

  • a_range (list) – 1*2 range of \(a\) axis (x, or BC) in fractional coordinate.

  • b_range (list) – 1*2 range of \(b\) axis (y, or BA) in fractional coordinate.

  • edgeplot (bool) – Whether to add cell boundaries represented by the original base vectors (not inflenced by a/b range).

  • x_ticks (int) – Number of ticks on x axis.

  • y_ticks (int) – Number of ticks on y axis.

  • figsize (list) – Matplotlib figure size. Note that axes aspects are fixed to be equal.

  • overlay (None|Trajectory) – Overlapping a 2D plot from the topond.Trajectory object if not None.

  • fig (Figure) – Developer Only, matplotlib Figure class.

  • ax_index (int) – Developer Only, index of the axis in fig.axes.

  • **kwargs – Other arguments passed to topond.Trajectory.

Returns:

fig (Figure) – Matplotlib Figure object

subtract(*args)

Subtracting data of the same type from the object.

Parameters:

*args (str|ScalarField) – File names or ScalarField objects. Must be of the same type (check the attribute type).

Returns:

self (ScalarField) – Data difference

substract(*args)

An old typo

class Trajectory

Bases: object

Basic TOPOND trajectory plot class. Call the property-specific child classes below to use.

plot_2D(cpt_marker='o', cpt_color='k', cpt_size=10, traj_color='r', traj_linestyle=':', traj_linewidth=0.5, x_ticks=5, y_ticks=5, figsize=[6.4, 4.8], overlay=None, fig=None, ax_index=None, **kwargs)

Get TOPOND trajectory in a 2D plot.

Note

2D periodicity (a_range and b_range) is not available for the Trajectory class. If overlay is not None, a_range and b_range and edgeplot will be disabled for the ScalarField object.

Parameters:

  • cpt_marker (str) – Marker of critical point scatter.

  • cpt_color (str) – Marker color of critical point scatter.

  • cpt_size (float|int) – Marker size of critical point scatter.

  • traj_color (str) – Line color of 2D trajectory plot.

  • traj_linestyl (str) – Line style of 2D trajectory plot.

  • traj_linewidth (str) – Line width of 2D trajectory plot.

  • x_ticks (int) – Number of ticks on x axis.

  • y_ticks (int) – Number of ticks on y axis.

  • figsize (list) – Matplotlib figure size. Note that axes aspects are fixed to be equal.

  • overlay (None|ScalarField) – Overlapping a 2D plot from the topond.ScalarField object if not None.

  • fig (Figure|None) – Developers only, matplotlib Figure class..

  • ax_index (list[int]) – Developer Only, indices of axes in fig.axes.

  • **kwargs – Other arguments passed to ScalarField.plot_2D().

Returns:

fig (Figure) – Matplotlib Figure object

class ChargeDensity(data, base, dimen, struc=None, unit='Angstrom')

Bases: ScalarField

The charge density object from TOPOND. Unit: ‘Angstrom’ for \(\AA^{-3}\) and ‘a.u.’ for Bohr \(^{-3}\).

Parameters:

  • data (array) – 2D (3D) Plot data. (nZ*)nY*nX. 3D methods under developing.

  • base (array) – 3*3 Cartesian coordinates of the 3 points defining vectors BA and BC.

  • struc (CStructure) – Extended Pymatgen Structure object.

  • unit (str) – In principle, should always be ‘Angstrom’ (case insensitive).

classmethod from_file(file, output=None)

Generate a ChargeDensity object from a single file. Can be used for multiple dimensions (2D only now. 3D under development).

Note

Though output is not mandatory for plotting proposes, it is highly recommended to be added for geometry information and other methods.

Parameters:

  • file (str) – File name of the ‘SURFRHOO.DAT’ file

  • output (str) – Screen output of ‘properties’ calculation.

Returns:

cls (ChargeDensity)

plot_2D(unit='Angstrom', levels='default', lineplot=True, linewidth=1.0, isovalues='%.2f', colorplot=False, colormap='jet', cbar_label='default', a_range=[0.0, 1.0], b_range=[0.0, 1.0], edgeplot=False, x_ticks=5, y_ticks=5, title='default', figsize=[6.4, 4.8], overlay=None, fig=None, ax_index=None, **kwargs)

Plot 2D contour lines, color maps or both for the 2D data set. The user can also get the overlapped plot of ScalarField and Trajectory classes.

Note

For more information of plot setups, please refer its parent class, topond.ScalarField.

Parameters:

  • unit (str) – Plot unit. ‘Angstrom’ for \(\AA^{-3}\), ‘a.u.’ for Bohr \(^{-3}\).

  • levels (array|int) – Set levels of colored / line contour plot. A number for linear scaled plot colors or an array for user-defined levels. 1D. ‘default’ for default levels.

  • lineplot (bool) – Plot contour lines.

  • contourline (list) – Width of contour lines. Other styles are pre- set and cannot be changed.

  • isovalues (str|None) – Add isovalues to contour lines and set their formats. Useful only if lineplot=True. None for not adding isovalues.

  • colorplot (bool) – Plot color-filled contour plots.

  • colormap (str) – Matplotlib colormap option. Useful only if colorplot=True.

  • cbar_label (str) – Label of colorbar. Useful only if colorplot=True. ‘None’ for no labels.

  • a_range (list) – 1*2 range of \(a\) axis (x, or BC) in fractional coordinate.

  • b_range (list) – 1*2 range of \(b\) axis (y, or BA) in fractional coordinate.

  • edgeplot (bool) – Whether to add cell boundaries represented by the original base vectors (not inflenced by a/b range).

  • x_ticks (int) – Number of ticks on x axis.

  • y_ticks (int) – Number of ticks on y axis.

  • title (str|None) – Plot title. ‘default’ for default values and ‘None’ for no title.

  • figsize (list) – Matplotlib figure size. Note that axes aspects are fixed to be equal.

  • overlay (None|Trajectory) – Overlapping a 2D plot from the topond.Trajectory object if not None.

  • fig (Figure) – Developer Only, matplotlib Figure class.

  • ax_index (int) – Developer Only, index of the axis in fig.axes.

  • **kwargs – Other arguments passed to topond.Trajectory.

Returns:

fig (Figure) – Matplotlib Figure object

_set_unit(unit)

Set units of data of ChargeDensity object.

Parameters:

unit (str) – ‘’Angstrom’, \(\AA^{-3}\); ‘a.u.’, Bohr \(^{-3}\).

class SpinDensity(data, base, dimen, struc=None, unit='Angstrom')

Bases: ScalarField

The spin density object from TOPOND. Unit: ‘Angstrom’ for \(\AA^{-3}\) and ‘a.u.’ for Bohr \(^{-3}\).

Parameters:

  • data (array) – 2D (3D) Plot data. (nZ*)nY*nX. 3D methods under developing.

  • base (array) – 3*3 Cartesian coordinates of the 3 points defining vectors BA and BC.

  • struc (CStructure) – Extended Pymatgen Structure object.

  • unit (str) – In principle, should always be ‘Angstrom’ (case insensitive).

classmethod from_file(file, output=None)

Generate a SpinDensity object from a single file. Can be used for multiple dimensions (2D only now. 3D under development).

Note

Though output is not mandatory for plotting proposes, it is highly recommended to be added for geometry information and other methods.

Parameters:

  • file (str) – File name of the ‘SURFSPDE.DAT’ file

  • output (str) – Screen output of ‘properties’ calculation.

Returns:

cls (SpinDensity)

plot_2D(unit='Angstrom', levels='default', lineplot=True, linewidth=1.0, isovalues='%.4f', colorplot=False, colormap='jet', cbar_label='default', a_range=[0.0, 1.0], b_range=[0.0, 1.0], edgeplot=False, x_ticks=5, y_ticks=5, title='default', figsize=[6.4, 4.8], overlay=None, fig=None, ax_index=None, **kwargs)

Plot 2D contour lines, color maps or both for the 2D data set. The user can also get the overlapped plot of ScalarField and Trajectory classes.

Note

For more information of plot setups, please refer its parent class, topond.ScalarField.

Parameters:

  • unit (str) – Plot unit. ‘Angstrom’ for \(\AA^{-3}\), ‘a.u.’ for Bohr \(^{-3}\).

  • levels (array|int) – Set levels of colored / line contour plot. A number for linear scaled plot colors or an array for user-defined levels. 1D. ‘default’ for default levels.

  • lineplot (bool) – Plot contour lines.

  • contourline (list) – Width of contour lines. Other styles are pre- set and cannot be changed.

  • isovalues (str|None) – Add isovalues to contour lines and set their formats. Useful only if lineplot=True. None for not adding isovalues.

  • colorplot (bool) – Plot color-filled contour plots.

  • colormap (str) – Matplotlib colormap option. Useful only if colorplot=True.

  • cbar_label (str) – Label of colorbar. Useful only if colorplot=True. ‘None’ for no labels.

  • a_range (list) – 1*2 range of \(a\) axis (x, or BC) in fractional coordinate.

  • b_range (list) – 1*2 range of \(b\) axis (y, or BA) in fractional coordinate.

  • edgeplot (bool) – Whether to add cell boundaries represented by the original base vectors (not inflenced by a/b range).

  • x_ticks (int) – Number of ticks on x axis.

  • y_ticks (int) – Number of ticks on y axis.

  • title (str|None) – Plot title. ‘default’ for default values and ‘None’ for no title.

  • figsize (list) – Matplotlib figure size. Note that axes aspects are fixed to be equal.

  • overlay (None|Trajectory) – Overlapping a 2D plot from the topond.Trajectory object if not None.

  • fig (Figure) – Developer Only, matplotlib Figure class.

  • ax_index (int) – Developer Only, index of the axis in fig.axes.

  • **kwargs – Other arguments passed to topond.Trajectory.

Returns:

fig (Figure) – Matplotlib Figure object

_set_unit(unit)

Set units of data of SpinDensity object.

Parameters:

unit (str) – ‘’Angstrom’, \(\AA^{-3}\); ‘a.u.’, Bohr \(^{-3}\).

class Gradient(data, base, dimen, struc=None, unit='Angstrom')

Bases: ScalarField

The charge density gradient object from TOPOND. Unit: ‘Angstrom’ for \(\AA^{-4}\) and ‘a.u.’ for Bohr \(^{-4}\).

Parameters:

  • data (array) – 2D (3D) Plot data. (nZ*)nY*nX. 3D methods under developing.

  • base (array) – 3*3 Cartesian coordinates of the 3 points defining vectors BA and BC.

  • struc (CStructure) – Extended Pymatgen Structure object.

  • unit (str) – In principle, should always be ‘Angstrom’ (case insensitive).

classmethod from_file(file, output=None)

Generate a Gradient object from a single file. Can be used for multiple dimensions (2D only now. 3D under development).

Note

Though output is not mandatory for plotting proposes, it is highly recommended to be added for geometry information and other methods.

Parameters:

  • file (str) – File name of the ‘SURFGRHO.DAT’ file

  • output (str) – Screen output of ‘properties’ calculation.

Returns:

cls (Gradient)

plot_2D(unit='Angstrom', levels='default', lineplot=True, linewidth=1.0, isovalues='%.2f', colorplot=False, colormap='jet', cbar_label='default', a_range=[0.0, 1.0], b_range=[0.0, 1.0], edgeplot=False, x_ticks=5, y_ticks=5, title='default', figsize=[6.4, 4.8], overlay=None, fig=None, ax_index=None, **kwargs)

Plot 2D contour lines, color maps or both for the 2D data set. The user can also get the overlapped plot of ScalarField and Trajectory classes.

Note

For more information of plot setups, please refer its parent class, topond.ScalarField.

Parameters:

  • unit (str) – Plot unit. ‘Angstrom’ for \(\AA^{-3}\), ‘a.u.’ for Bohr \(^{-3}\).

  • levels (array|int) – Set levels of colored / line contour plot. A number for linear scaled plot colors or an array for user-defined levels. 1D. ‘default’ for default levels.

  • lineplot (bool) – Plot contour lines.

  • contourline (list) – Width of contour lines. Other styles are pre- set and cannot be changed.

  • isovalues (str|None) – Add isovalues to contour lines and set their formats. Useful only if lineplot=True. None for not adding isovalues.

  • colorplot (bool) – Plot color-filled contour plots.

  • colormap (str) – Matplotlib colormap option. Useful only if colorplot=True.

  • cbar_label (str) – Label of colorbar. Useful only if colorplot=True. ‘None’ for no labels.

  • a_range (list) – 1*2 range of \(a\) axis (x, or BC) in fractional coordinate.

  • b_range (list) – 1*2 range of \(b\) axis (y, or BA) in fractional coordinate.

  • edgeplot (bool) – Whether to add cell boundaries represented by the original base vectors (not inflenced by a/b range).

  • x_ticks (int) – Number of ticks on x axis.

  • y_ticks (int) – Number of ticks on y axis.

  • title (str|None) – Plot title. ‘default’ for default values and ‘None’ for no title.

  • figsize (list) – Matplotlib figure size. Note that axes aspects are fixed to be equal.

  • overlay (None|Trajectory) – Overlapping a 2D plot from the topond.Trajectory object if not None.

  • fig (Figure) – Developer Only, matplotlib Figure class.

  • ax_index (int) – Developer Only, index of the axis in fig.axes.

  • **kwargs – Other arguments passed to topond.Trajectory.

Returns:

fig (Figure) – Matplotlib Figure object

_set_unit(unit)

Set units of data of Gradient object.

Parameters:

unit (str) – ‘’Angstrom’, \(\AA^{-4}\); ‘a.u.’, Bohr \(^{-4}\).

class Laplacian(data, base, dimen, struc=None, unit='Angstrom')

Bases: ScalarField

The Laplacian object from TOPOND. Unit: ‘Angstrom’ for \(\AA^{-5}\) and ‘a.u.’ for Bohr \(^{-5}\).

Parameters:

  • data (array) – 2D (3D) Plot data. (nZ*)nY*nX. 3D methods under developing.

  • base (array) – 3*3 Cartesian coordinates of the 3 points defining vectors BA and BC.

  • struc (CStructure) – Extended Pymatgen Structure object.

  • unit (str) – In principle, should always be ‘Angstrom’ (case insensitive).

classmethod from_file(file, output=None)

Generate a Laplacian object from a single file. Can be used for multiple dimensions (2D only now. 3D under development).

Note

Though output is not mandatory for plotting proposes, it is highly recommended to be added for geometry information and other methods.

It is suggested to name the file with ‘LAPP’ or ‘LAPM’. Otherwise it will be read as ‘LAPP’. Data is always saved as \(\nabla^{2}\rho\).

Parameters:

  • file (str) – File name of the ‘SURFLAPP.DAT’ or ‘SURFLAPM.DAT’ file

  • output (str) – Screen output of ‘properties’ calculation.

Returns:

cls (Laplacian)

plot_2D(unit='Angstrom', plot_lapm=False, levels='default', lineplot=True, linewidth=1.0, isovalues='%.2f', colorplot=False, colormap='jet', cbar_label='default', a_range=[0.0, 1.0], b_range=[0.0, 1.0], edgeplot=False, x_ticks=5, y_ticks=5, title='default', figsize=[6.4, 4.8], overlay=None, fig=None, ax_index=None, **kwargs)

Plot 2D contour lines, color maps or both for the 2D data set. The user can also get the overlapped plot of ScalarField and Trajectory classes.

Note

For more information of plot setups, please refer its parent class, topond.ScalarField.

Parameters:

  • unit (str) – Plot unit. ‘Angstrom’ for \(\AA^{-3}\), ‘a.u.’ for Bohr \(^{-3}\).

  • plot_lapm (bool) – Whether to plot \(-\nabla^{2}\rho\).

  • levels (array|int) – Set levels of colored / line contour plot. A number for linear scaled plot colors or an array for user-defined levels. 1D. ‘default’ for default levels.

  • lineplot (bool) – Plot contour lines.

  • contourline (list) – Width of contour lines. Other styles are pre- set and cannot be changed.

  • isovalues (str|None) – Add isovalues to contour lines and set their formats. Useful only if lineplot=True. None for not adding isovalues.

  • colorplot (bool) – Plot color-filled contour plots.

  • colormap (str) – Matplotlib colormap option. Useful only if colorplot=True.

  • cbar_label (str) – Label of colorbar. Useful only if colorplot=True. ‘None’ for no labels.

  • a_range (list) – 1*2 range of \(a\) axis (x, or BC) in fractional coordinate.

  • b_range (list) – 1*2 range of \(b\) axis (y, or BA) in fractional coordinate.

  • edgeplot (bool) – Whether to add cell boundaries represented by the original base vectors (not inflenced by a/b range).

  • x_ticks (int) – Number of ticks on x axis.

  • y_ticks (int) – Number of ticks on y axis.

  • title (str|None) – Plot title. ‘default’ for default values and ‘None’ for no title.

  • figsize (list) – Matplotlib figure size. Note that axes aspects are fixed to be equal.

  • overlay (None|Trajectory) – Overlapping a 2D plot from the topond.Trajectory object if not None.

  • fig (Figure) – Developer Only, matplotlib Figure class.

  • ax_index (int) – Developer Only, index of the axis in fig.axes.

  • **kwargs – Other arguments passed to topond.Trajectory.

Returns:

fig (Figure) – Matplotlib Figure object

_set_unit(unit)

Set units of data of Laplacian object.

Parameters:

unit (str) – ‘’Angstrom’, \(\AA^{-5}\); ‘a.u.’, Bohr \(^{-5}\).

class HamiltonianKE(data, base, dimen, struc=None, unit='Angstrom')

Bases: ScalarField

The Hamiltonian kinetic energy density object from TOPOND. Unit: ‘Angstrom’ for eV.:math:AA^{-3} and ‘a.u.’ for Hartree.Bohr \(^{-3}\).

Parameters:

  • data (array) – 2D (3D) Plot data. (nZ*)nY*nX. 3D methods under developing.

  • base (array) – 3*3 Cartesian coordinates of the 3 points defining vectors BA and BC.

  • struc (CStructure) – Extended Pymatgen Structure object.

  • unit (str) – In principle, should always be ‘Angstrom’ (case insensitive).

classmethod from_file(file, output=None)

Generate a HamiltonianKE object from a single file. Can be used for multiple dimensions (2D only now. 3D under development).

Note

Though output is not mandatory for plotting proposes, it is highly recommended to be added for geometry information and other methods.

Parameters:

  • file (str) – File name of the ‘SURFKKIN.DAT’ file

  • output (str) – Screen output of ‘properties’ calculation.

Returns:

cls (HamiltonianKE)

plot_2D(unit='Angstrom', levels='default', lineplot=True, linewidth=1.0, isovalues='%.2f', colorplot=False, colormap='jet', cbar_label='default', a_range=[0.0, 1.0], b_range=[0.0, 1.0], edgeplot=False, x_ticks=5, y_ticks=5, title='default', figsize=[6.4, 4.8], overlay=None, fig=None, ax_index=None, **kwargs)

Plot 2D contour lines, color maps or both for the 2D data set. The user can also get the overlapped plot of ScalarField and Trajectory classes.

Note

For more information of plot setups, please refer its parent class, topond.ScalarField.

Parameters:

  • unit (str) – Plot unit. ‘Angstrom’ for \(\AA^{-3}\), ‘a.u.’ for Bohr \(^{-3}\).

  • levels (array|int) – Set levels of colored / line contour plot. A number for linear scaled plot colors or an array for user-defined levels. 1D. ‘default’ for default levels.

  • lineplot (bool) – Plot contour lines.

  • contourline (list) – Width of contour lines. Other styles are pre- set and cannot be changed.

  • isovalues (str|None) – Add isovalues to contour lines and set their formats. Useful only if lineplot=True. None for not adding isovalues.

  • colorplot (bool) – Plot color-filled contour plots.

  • colormap (str) – Matplotlib colormap option. Useful only if colorplot=True.

  • cbar_label (str) – Label of colorbar. Useful only if colorplot=True. ‘None’ for no labels.

  • a_range (list) – 1*2 range of \(a\) axis (x, or BC) in fractional coordinate.

  • b_range (list) – 1*2 range of \(b\) axis (y, or BA) in fractional coordinate.

  • edgeplot (bool) – Whether to add cell boundaries represented by the original base vectors (not inflenced by a/b range).

  • x_ticks (int) – Number of ticks on x axis.

  • y_ticks (int) – Number of ticks on y axis.

  • title (str|None) – Plot title. ‘default’ for default values and ‘None’ for no title.

  • figsize (list) – Matplotlib figure size. Note that axes aspects are fixed to be equal.

  • overlay (None|Trajectory) – Overlapping a 2D plot from the topond.Trajectory object if not None.

  • fig (Figure) – Developer Only, matplotlib Figure class.

  • ax_index (int) – Developer Only, index of the axis in fig.axes.

  • **kwargs – Other arguments passed to topond.Trajectory.

Returns:

fig (Figure) – Matplotlib Figure object

_set_unit(unit)

Set units of data of HamiltonianKE object.

Parameters:

unit (str) – ‘’Angstrom’, eV.:math:AA^{-3}; ‘a.u.’, Hartree.Bohr \(^{-3}\).

class LagrangianKE(data, base, dimen, struc=None, unit='Angstrom')

Bases: ScalarField

The Lagrangian kinetic energy density object from TOPOND. Unit: ‘Angstrom’ for eV.:math:AA^{-3} and ‘a.u.’ for Hartree.Bohr \(^{-3}\).

Parameters:

  • data (array) – 2D (3D) Plot data. (nZ*)nY*nX. 3D methods under developing.

  • base (array) – 3*3 Cartesian coordinates of the 3 points defining vectors BA and BC.

  • struc (CStructure) – Extended Pymatgen Structure object.

  • unit (str) – In principle, should always be ‘Angstrom’ (case insensitive).

classmethod from_file(file, output=None)

Generate a LagrangianKE object from a single file. Can be used for multiple dimensions (2D only now. 3D under development).

Note

Though output is not mandatory for plotting proposes, it is highly recommended to be added for geometry information and other methods.

Parameters:

  • file (str) – File name of the ‘SURFGKIN.DAT’ file

  • output (str) – Screen output of ‘properties’ calculation.

Returns:

cls (LagrangianKE)

plot_2D(unit='Angstrom', levels='default', lineplot=True, linewidth=1.0, isovalues='%.2f', colorplot=False, colormap='jet', cbar_label='default', a_range=[0.0, 1.0], b_range=[0.0, 1.0], edgeplot=False, x_ticks=5, y_ticks=5, title='default', figsize=[6.4, 4.8], overlay=None, fig=None, ax_index=None, **kwargs)

Plot 2D contour lines, color maps or both for the 2D data set. The user can also get the overlapped plot of ScalarField and Trajectory classes.

Note

For more information of plot setups, please refer its parent class, topond.ScalarField.

Parameters:

  • unit (str) – Plot unit. ‘Angstrom’ for \(\AA^{-3}\), ‘a.u.’ for Bohr \(^{-3}\).

  • levels (array|int) – Set levels of colored / line contour plot. A number for linear scaled plot colors or an array for user-defined levels. 1D. ‘default’ for default levels.

  • lineplot (bool) – Plot contour lines.

  • contourline (list) – Width of contour lines. Other styles are pre- set and cannot be changed.

  • isovalues (str|None) – Add isovalues to contour lines and set their formats. Useful only if lineplot=True. None for not adding isovalues.

  • colorplot (bool) – Plot color-filled contour plots.

  • colormap (str) – Matplotlib colormap option. Useful only if colorplot=True.

  • cbar_label (str) – Label of colorbar. Useful only if colorplot=True. ‘None’ for no labels.

  • a_range (list) – 1*2 range of \(a\) axis (x, or BC) in fractional coordinate.

  • b_range (list) – 1*2 range of \(b\) axis (y, or BA) in fractional coordinate.

  • edgeplot (bool) – Whether to add cell boundaries represented by the original base vectors (not inflenced by a/b range).

  • x_ticks (int) – Number of ticks on x axis.

  • y_ticks (int) – Number of ticks on y axis.

  • title (str|None) – Plot title. ‘default’ for default values and ‘None’ for no title.

  • figsize (list) – Matplotlib figure size. Note that axes aspects are fixed to be equal.

  • overlay (None|Trajectory) – Overlapping a 2D plot from the topond.Trajectory object if not None.

  • fig (Figure) – Developer Only, matplotlib Figure class.

  • ax_index (int) – Developer Only, index of the axis in fig.axes.

  • **kwargs – Other arguments passed to topond.Trajectory.

Returns:

fig (Figure) – Matplotlib Figure object

_set_unit(unit)

Set units of data of LagrangianKE object.

Parameters:

unit (str) – ‘’Angstrom’, eV.:math:AA^{-3}; ‘a.u.’, Hartree.Bohr \(^{-3}\).

class VirialField(data, base, dimen, struc=None, unit='Angstrom')

Bases: ScalarField

The Virial field density object from TOPOND. Unit: ‘Angstrom’ for eV.:math:AA^{-3} and ‘a.u.’ for Hartree.Bohr \(^{-3}\).

Parameters:

  • data (array) – 2D (3D) Plot data. (nZ*)nY*nX. 3D methods under developing.

  • base (array) – 3*3 Cartesian coordinates of the 3 points defining vectors BA and BC.

  • struc (CStructure) – Extended Pymatgen Structure object.

  • unit (str) – In principle, should always be ‘Angstrom’ (case insensitive).

classmethod from_file(file, output=None)

Generate a VirialField object from a single file. Can be used for multiple dimensions (2D only now. 3D under development).

Note

Though output is not mandatory for plotting proposes, it is highly recommended to be added for geometry information and other methods.

Parameters:

  • file (str) – File name of the ‘SURFVIRI.DAT’ file

  • output (str) – Screen output of ‘properties’ calculation.

Returns:

cls (VirialField)

plot_2D(unit='Angstrom', levels='default', lineplot=True, linewidth=1.0, isovalues='%.2f', colorplot=False, colormap='jet', cbar_label='default', a_range=[0.0, 1.0], b_range=[0.0, 1.0], edgeplot=False, x_ticks=5, y_ticks=5, title='default', figsize=[6.4, 4.8], overlay=None, fig=None, ax_index=None, **kwargs)

Plot 2D contour lines, color maps or both for the 2D data set. The user can also get the overlapped plot of ScalarField and Trajectory classes.

Note

For more information of plot setups, please refer its parent class, topond.ScalarField.

Parameters:

  • unit (str) – Plot unit. ‘Angstrom’ for \(\AA^{-3}\), ‘a.u.’ for Bohr \(^{-3}\).

  • levels (array|int) – Set levels of colored / line contour plot. A number for linear scaled plot colors or an array for user-defined levels. 1D. ‘default’ for default levels.

  • lineplot (bool) – Plot contour lines.

  • contourline (list) – Width of contour lines. Other styles are pre- set and cannot be changed.

  • isovalues (str|None) – Add isovalues to contour lines and set their formats. Useful only if lineplot=True. None for not adding isovalues.

  • colorplot (bool) – Plot color-filled contour plots.

  • colormap (str) – Matplotlib colormap option. Useful only if colorplot=True.

  • cbar_label (str) – Label of colorbar. Useful only if colorplot=True. ‘None’ for no labels.

  • a_range (list) – 1*2 range of \(a\) axis (x, or BC) in fractional coordinate.

  • b_range (list) – 1*2 range of \(b\) axis (y, or BA) in fractional coordinate.

  • edgeplot (bool) – Whether to add cell boundaries represented by the original base vectors (not inflenced by a/b range).

  • x_ticks (int) – Number of ticks on x axis.

  • y_ticks (int) – Number of ticks on y axis.

  • title (str|None) – Plot title. ‘default’ for default values and ‘None’ for no title.

  • figsize (list) – Matplotlib figure size. Note that axes aspects are fixed to be equal.

  • overlay (None|Trajectory) – Overlapping a 2D plot from the topond.Trajectory object if not None.

  • fig (Figure) – Developer Only, matplotlib Figure class.

  • ax_index (int) – Developer Only, index of the axis in fig.axes.

  • **kwargs – Other arguments passed to topond.Trajectory.

Returns:

fig (Figure) – Matplotlib Figure object

_set_unit(unit)

Set units of data of VirialField object.

Parameters:

unit (str) – ‘’Angstrom’, eV.:math:AA^{-3}; ‘a.u.’, Hartree.Bohr \(^{-3}\).

class ELF(data, base, dimen, struc=None, unit='Angstrom')

Bases: ScalarField

The electron localization object from TOPOND. Dimensionless. Unit: ‘Angstrom’ for \(\AA\) and ‘a.u.’ for Bohr (only for plot base vectors).

Parameters:

  • data (array) – 2D (3D) Plot data. (nZ*)nY*nX. 3D methods under developing.

  • base (array) – 3*3 Cartesian coordinates of the 3 points defining vectors BA and BC.

  • struc (CStructure) – Extended Pymatgen Structure object.

classmethod from_file(file, output=None)

Generate a ELF object from a single file. Can be used for multiple dimensions (2D only now. 3D under development).

Note

Though output is not mandatory for plotting proposes, it is highly recommended to be added for geometry information and other methods.

Parameters:

  • file (str) – File name of the ‘SURFELFBDAT’ file

  • output (str) – Screen output of ‘properties’ calculation.

Returns:

cls (ELF)

plot_2D(unit='Angstrom', levels='default', lineplot=True, linewidth=1.0, isovalues='%.2f', colorplot=False, colormap='jet', cbar_label='default', a_range=[0.0, 1.0], b_range=[0.0, 1.0], edgeplot=False, x_ticks=5, y_ticks=5, title='default', figsize=[6.4, 4.8], overlay=None, fig=None, ax_index=None, **kwargs)

Plot 2D contour lines, color maps or both for the 2D data set. The user can also get the overlapped plot of ScalarField and Trajectory classes.

Note

For more information of plot setups, please refer its parent class, topond.ScalarField.

Parameters:

  • unit (str) – Plot unit. ‘Angstrom’ for \(\AA^{-3}\), ‘a.u.’ for Bohr \(^{-3}\).

  • levels (array|int) – Set levels of colored / line contour plot. A number for linear scaled plot colors or an array for user-defined levels. 1D. ‘default’ for default levels.

  • lineplot (bool) – Plot contour lines.

  • contourline (list) – Width of contour lines. Other styles are pre- set and cannot be changed.

  • isovalues (str|None) – Add isovalues to contour lines and set their formats. Useful only if lineplot=True. None for not adding isovalues.

  • colorplot (bool) – Plot color-filled contour plots.

  • colormap (str) – Matplotlib colormap option. Useful only if colorplot=True.

  • cbar_label (str) – Label of colorbar. Useful only if colorplot=True. ‘None’ for no labels.

  • a_range (list) – 1*2 range of \(a\) axis (x, or BC) in fractional coordinate.

  • b_range (list) – 1*2 range of \(b\) axis (y, or BA) in fractional coordinate.

  • edgeplot (bool) – Whether to add cell boundaries represented by the original base vectors (not inflenced by a/b range).

  • x_ticks (int) – Number of ticks on x axis.

  • y_ticks (int) – Number of ticks on y axis.

  • title (str|None) – Plot title. ‘default’ for default values and ‘None’ for no title.

  • figsize (list) – Matplotlib figure size. Note that axes aspects are fixed to be equal.

  • overlay (None|Trajectory) – Overlapping a 2D plot from the topond.Trajectory object if not None.

  • fig (Figure) – Developer Only, matplotlib Figure class.

  • ax_index (int) – Developer Only, index of the axis in fig.axes.

  • **kwargs – Other arguments passed to topond.Trajectory.

Returns:

fig (Figure) – Matplotlib Figure object

_set_unit(unit)

Set units of data of ELF object.

Parameters:

unit (str) – ‘’Angstrom’, \(\AA\); ‘a.u.’, Bohr. Only for plot base vectors

class GradientTraj(wtraj, traj, base, struc, unit='Angstrom')

Bases: Trajectory

The charge density gradient trajectory object from TOPOND. Unit: ‘Angstrom’ for \(\AA\) and ‘a.u.’ for Bohr.

Parameters:

  • wtraj (list[int]) – 1*nPath, weight of the path, int 0 to 3.

  • traj (list[array]) – 1*nPath, list of paths. Every array is a nPoint*3 3D ref framework coordinates of points on the path.

  • base (array) – 3*3 Cartesian coordinates of the 3 points defining vectors BA and BC.

  • struc (CStructure) – Extended Pymatgen Structure object.

  • unit (str) – In principle, should always be ‘Angstrom’ (case insensitive).

Returns:

self (GradientTraj) – Import attributes: trajectory, nPath*2 list of trajectory and its weight; cpoint, nCpoint*3 array of critical point coordinates in 3D ref framework.

classmethod from_file(file, output)

Generate a GradientTraj object from ‘TRAJGRAD.DAT’ file and the standard screen output of CRYSTAL ‘properties’ calculation.

Note

Output file is mandatory.

Parameters:

  • file (str) – ‘TRAJGRAD.DAT’ file by TOPOND.

  • output (str) – Standard output of Properties calculation, used to get geometry and orientation of the plane.

Returns:

cls (ChargeDensity)

plot_2D(unit='Angstrom', cpt_marker='o', cpt_color='k', cpt_size=10, traj_color='r', traj_linestyle=':', traj_linewidth=0.5, x_ticks=5, y_ticks=5, title='default', figsize=[6.4, 4.8], overlay=None, fig=None, ax_index=None, **kwargs)

Plot charge density gradient trajectory in a 2D plot.

Note

For more information of plot setups, please refer its parent class, topond.Trajectory.

Parameters:

  • unit (str) – Plot unit. ‘Angstrom’ for \(\AA^{-3}\), ‘a.u.’ for Bohr \(^{-3}\).

  • cpt_marker (str) – Marker of critical point scatter.

  • cpt_color (str) – Marker color of critical point scatter.

  • cpt_size (float|int) – Marker size of critical point scatter.

  • traj_color (str) – Line color of 2D trajectory plot.

  • traj_linestyl (str) – Line style of 2D trajectory plot.

  • traj_linewidth (str) – Line width of 2D trajectory plot.

  • x_ticks (int) – Number of ticks on x axis.

  • y_ticks (int) – Number of ticks on y axis.

  • title (str|None) – Plot title. ‘default’ for proeprty plotted. ‘None’ for no title.

  • figsize (list) – Matplotlib figure size. Note that axes aspects are fixed to be equal.

  • overlay (None|ScalarField) – Overlapping a 2D plot from the topond.ScalarField object if not None.

  • fig (Figure|None) – Developers only, matplotlib Figure class..

  • ax_index (list[int]) – Developer Only, indices of axes in fig.axes.

  • **kwargs – Other arguments passed to ScalarField.plot_2D().

Returns:

fig (Figure) – Matplotlib Figure object

_set_unit(unit)

Set units of data of GradientTraj object.

Parameters:

unit (str) – ‘Angstrom’ or ‘a.u.’

class ChemicalGraph(wtraj, traj, base, struc, unit='Angstrom')

Bases: Trajectory

The molecular / crystal graph object from TOPOND. Unit: ‘Angstrom’ for \(\AA\) and ‘a.u.’ for Bohr.

Parameters:

  • wtraj (list[int]) – 1*nPath, weight of the path, int 0 to 3.

  • traj (list[array]) – 1*nPath, list of paths. Every array is a nPoint*3 3D ref framework coordinates of points on the path.

  • base (array) – 3*3 Cartesian coordinates of the 3 points defining vectors BA and BC.

  • struc (CStructure) – Extended Pymatgen Structure object.

  • unit (str) – In principle, should always be ‘Angstrom’ (case insensitive).

Returns:

self (ChemicalGraph) – Import attributes: trajectory, nPath*2 list of trajectory and its weight; cpoint, nCpoint*3 array of critical point coordinates in 3D ref framework.

classmethod from_file(file, output)

Generate a ChemicalGraph object from ‘TRAJMOLG.DAT’ file and the standard screen output of CRYSTAL ‘properties’ calculation.

Note

Output file is mandatory.

Parameters:

  • file (str) – ‘TRAJMOLG.DAT’ file by TOPOND.

  • output (str) – Standard output of Properties calculation, used to get geometry and orientation of the plane.

Returns:

cls (ChargeDensity)

plot_2D(unit='Angstrom', cpt_marker='o', cpt_color='k', cpt_size=10, traj_color='r', traj_linestyle=':', traj_linewidth=0.5, x_ticks=5, y_ticks=5, title='default', figsize=[6.4, 4.8], overlay=None, fig=None, ax_index=None, **kwargs)

Plot crystal / molecular graph in a 2D plot.

Note

For more information of plot setups, please refer its parent class, topond.Trajectory.

Parameters:

  • unit (str) – Plot unit. ‘Angstrom’ for \(\AA^{-3}\), ‘a.u.’ for Bohr \(^{-3}\).

  • cpt_marker (str) – Marker of critical point scatter.

  • cpt_color (str) – Marker color of critical point scatter.

  • cpt_size (float|int) – Marker size of critical point scatter.

  • traj_color (str) – Line color of 2D trajectory plot.

  • traj_linestyl (str) – Line style of 2D trajectory plot.

  • traj_linewidth (str) – Line width of 2D trajectory plot.

  • x_ticks (int) – Number of ticks on x axis.

  • y_ticks (int) – Number of ticks on y axis.

  • title (str|None) – Plot title. ‘default’ for proeprty plotted. ‘None’ for no title.

  • figsize (list) – Matplotlib figure size. Note that axes aspects are fixed to be equal.

  • overlay (None|ScalarField) – Overlapping a 2D plot from the topond.ScalarField object if not None.

  • fig (Figure|None) – Developers only, matplotlib Figure class..

  • ax_index (list[int]) – Developer Only, indices of axes in fig.axes.

  • **kwargs – Other arguments passed to ScalarField.plot_2D().

Returns:

fig (Figure) – Matplotlib Figure object

_set_unit(unit)

Set units of data of ChemicalGraph object.

Parameters:

unit (str) – ‘Angstrom’ or ‘a.u.’