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

CRYSTALpytools.relativistics module

The module for ‘2c-SCF’, i.e., 2-component SCF, and relativistics.

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

Bases: ChargeDensity

Same as electronics.ChargeDensity, the spin density. But its dimension is kept to be commensurate with other keywords of the ‘PROPS2COMP’ block.

Note

Its type attribute is ‘ECHG’ rather than ‘DENSITY’

classmethod from_file(file, output)

Generate a ChargeDensity object from CRYSTAL formatted output unit and standard screen output (mandatory).

Parameters:

file (str) – File name of fort.25 or CUBE (in development) files.
output (str) – Screen output of ‘properties’ calculation.

Returns:

cls (ChargeDensity)

class VectorField

Bases: object

The basic vector field object, containing a nY*nX*3 (nZ*nY*nX*3) data array for 2D (3D) fields. Call the property-specific child classes below in use. 3D methods under development.

plot_2D(levels=100, quiverplot=True, quiverscale=1.0, colorplot=True, colormap='jet', cbar_label=None, a_range=[], b_range=[], rectangle=False, edgeplot=False, x_ticks=5, y_ticks=5, figsize=[6.4, 4.8], fig=None, ax_index=None, **kwargs)

Plot 2D vector field.

3 styles are available:

quiverplot=True and colorplot=True: The color-filled contour
illustrates the norm of vectors. The black arrows indicates both the directions and norms of in-plane prjections.
quiverplot=True and colorplot=False: The arrows are colored
to indicate the directions and norms of in-plane prjections.
quiverplot=False and colorplot=True: The color-filled contour
illustrates the norm of vectors, similar to the 2D scalar map.

Parameters:

levels (int|array) – Set levels of colored contour/quiver plot. A number for linear scaled plot colors or an array for user-defined levels. 1D.
quiverplot (bool) – Plot 2D field of arrows.
quiverscale (float) – Tune the length of arrows. Useful only if quiverplot=True.
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.
a_range (list) – 1*2 range of \(a\) axis (x, or BC) in fractional coordinate.
b_range (list) – 1*2 range of \(b\) axis (x, or AB) in fractional coordinate.
rectangle (bool) – If \(a, b\) are non-orthogonal, plot a rectangle region and reset \(b\). If used together with b_range, that refers to the old \(b\) (i.e., expansion first).
edgeplot (bool) – Whether to add cell edges represented by the original base vectors (not inflenced by a/b range or rectangle options).
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.
fig (Figure) – Developer Only, matplotlib Figure class.
ax_index (list[int]) – Developer Only, indices of axes in fig.axes.
**kwargs – Other arguments passed to axes.quiver() function to set arrow styles.

Returns:

fig (Figure) – Matplotlib Figure class.

class Magnetization(data, base, dimen, struc, unit='SI')

Bases: VectorField

The class for magnetization. Unit: ‘SI’ (length: \(\AA\), magnetization: A/m).

Parameters:

data (array) – nY*nX*3 (nZ*nY*nX*3) array of magnetization vectors in 2D (3D) plane.
base (array) – 3*3 Cartesian coordinates of the 3 points defining vectors BA and BC (2D) or 3 base vectors (3D)
dimen (int) – Dimensionality of the plot.
struc (CStructure) – Extended Pymatgen Structure object.
unit (str) – In principle, should always be ‘SI’ (case insensitive).

classmethod from_file(file, output)

Generate a Magentization object from CRYSTAL formatted output unit and standard screen output (mandatory).

Parameters:

file (str) – File name of fort.25 or CUBE (in development) files.
output (str) – Screen output of ‘properties’ calculation.

Returns:

cls (Magnetization)

plot_2D(unit='SI', levels=100, quiverplot=True, quiverscale=1.0, colorplot=True, colormap='jet', cbar_label='default', a_range=[], b_range=[], rectangle=False, edgeplot=False, x_ticks=5, y_ticks=5, title='default', figsize=[6.4, 4.8], fig=None, ax_index=None, **kwargs)

Plot 2D magnetization field.

3 styles are available:

quiverplot=True and colorplot=True: The color-filled contour
illustrates the norm of vectors. The black arrows indicates both the directions and norms of in-plane prjections.
quiverplot=True and colorplot=False: The arrows are colored
to indicate the directions and norms of in-plane prjections.
quiverplot=False and colorplot=True: The color-filled contour
illustrates the norm of vectors, similar to the 2D scalar map.

Parameters:

unit (str) – Plot unit. ‘SI’ for \(\AA\) and A/m. ‘a.u.’ for Bohr and a.u. magnetization.
levels (int|array) – Set levels of colored contour/quiver plot. A number for linear scaled plot colors or an array for user-defined levels. 1D.
quiverplot (bool) – Plot 2D field of arrows.
quiverscale (float) – Tune the length of arrows. Useful only if quiverplot=True.
colorplot (bool) – Plot color-filled contour plots.
colormap (str) – Matplotlib colormap option. Useful only if colorplot=True.
cbar_label (str|None) – Label of colorbar. ‘default’ for unit. ‘None’ for no label. Useful only if colorplot=True.
a_range (list) – 1*2 range of \(a\) axis (x, or BC) in fractional coordinate.
b_range (list) – 1*2 range of \(b\) axis (x, or AB) in fractional coordinate.
rectangle (bool) – If \(a, b\) are non-orthogonal, plot a rectangle region and reset \(b\). If used together with b_range, that refers to the old \(b\) (i.e., expansion first).
edgeplot (bool) – Whether to add cell edges represented by the original base vectors (not inflenced by a/b range or rectangle options).
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.
fig (Figure) – Developer Only, matplotlib Figure class.
ax_index (list[int]) – Developer Only, indices of axes in fig.axes.
**kwargs – Other arguments passed to axes.quiver() function to set arrow styles.

Returns:

fig (Figure) – Matplotlib Figure class.

_set_unit(unit)

Set units of data of Magnetization object.

Parameters:: unit (str) – ‘SI’, length: \(\AA\), magnetization: A/m. ‘a.u.’, all in a.u..

class OrbitalCurrentDensity(data, base, dimen, struc, unit='SI')

Bases: VectorField

The class for orbital current density. Unit: ‘SI’ (length: \(\AA\), orbital current density: A/m \(^{2}\)).

Parameters:

data (array) – nY*nX*3 (nZ*nY*nX*3) array of orbnital current vectors in 2D (3D) plane.
base (array) – 3*3 Cartesian coordinates of the 3 points defining vectors BA and BC (2D) or 3 base vectors (3D)
dimen (int) – Dimensionality of the plot.
struc (CStructure) – Extended Pymatgen Structure object.
unit (str) – In principle, should always be ‘SI’ (case insensitive).

classmethod from_file(file, output)

Generate a OrbitalCurrentDensity object from CRYSTAL formatted output unit and standard screen output (mandatory).

Parameters:

file (str) – File name of fort.25 or CUBE (in development) files.
output (str) – Screen output of ‘properties’ calculation.

Returns:

cls (OrbitalCurrentDensity)

plot_2D(unit='SI', levels=100, quiverplot=True, quiverscale=1.0, colorplot=True, colormap='jet', cbar_label='default', a_range=[], b_range=[], rectangle=False, edgeplot=False, x_ticks=5, y_ticks=5, title='default', figsize=[6.4, 4.8], fig=None, ax_index=None, **kwargs)

Plot 2D orbital current density field.

3 styles are available:

quiverplot=True and colorplot=True: The color-filled contour
illustrates the norm of vectors. The black arrows indicates both the directions and norms of in-plane prjections.
quiverplot=True and colorplot=False: The arrows are colored
to indicate the directions and norms of in-plane prjections.
quiverplot=False and colorplot=True: The color-filled contour
illustrates the norm of vectors, similar to the 2D scalar map.

Parameters:

unit (str) – Plot unit. ‘SI’ for \(\AA\) and A/m \(^{2}\). ‘a.u.’ for Bohr and a.u. current density.
levels (int|array) – Set levels of colored contour/quiver plot. A number for linear scaled plot colors or an array for user-defined levels. 1D.
quiverplot (bool) – Plot 2D field of arrows.
quiverscale (float) – Tune the length of arrows. Useful only if quiverplot=True.
colorplot (bool) – Plot color-filled contour plots.
colormap (str) – Matplotlib colormap option. Useful only if colorplot=True.
cbar_label (str|None) – Label of colorbar. ‘default’ for unit. ‘None’ for no label. Useful only if colorplot=True.
a_range (list) – 1*2 range of \(a\) axis (x, or BC) in fractional coordinate.
b_range (list) – 1*2 range of \(b\) axis (x, or AB) in fractional coordinate.
rectangle (bool) – If \(a, b\) are non-orthogonal, plot a rectangle region and reset \(b\). If used together with b_range, that refers to the old \(b\) (i.e., expansion first).
edgeplot (bool) – Whether to add cell edges represented by the original base vectors (not inflenced by a/b range or rectangle options).
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.
fig (Figure) – Developer Only, matplotlib Figure class.
ax_index (list[int]) – Developer Only, indices of axes in fig.axes.
**kwargs – Other arguments passed to axes.quiver() function to set arrow styles.

Returns:

fig (Figure) – Matplotlib Figure class.

_set_unit(unit)

Set units of data of OrbitalCurrentDensity object.

Parameters:: unit (str) – ‘SI’, length: \(\AA\), orbital current density: A/m \(^{2}\). ‘a.u.’, all in a.u..

class SpinCurrentDensity(data_x, data_y, data_z, base, dimen, struc, unit='SI')

Bases: VectorField

The class for spin current density. Unit: ‘SI’ (length: \(\AA\), spin current density: A/m \(^{2}\)).

Parameters:

data_x (array) – nY*nX*3 (nZ*nY*nX*3) array of spin current vectors \(J^{x}\) in 2D (3D) plane.
data_y (array) – nY*nX*3 (nZ*nY*nX*3) array of spin current vectors \(J^{y}\) in 2D (3D) plane.
data_z (array) – nY*nX*3 (nZ*nY*nX*3) array of spin current vectors \(J^{z}\) in 2D (3D) plane.
base (array) – 3*3 Cartesian coordinates of the 3 points defining vectors BA and BC (2D) or 3 base vectors (3D)
dimen (int) – Dimensionality of the plot.
struc (CStructure) – Extended Pymatgen Structure object.
unit (str) – In principle, should always be ‘SI’ (case insensitive).

classmethod from_file(file, output)

Generate a SpinCurrentDensity object from CRYSTAL formatted output unit and standard screen output (mandatory).

Parameters:

file (str) – File name of fort.25 or CUBE (in development) files.
output (str) – Screen output of ‘properties’ calculation.

Returns:

cls (SpinCurrentDensity)

plot_2D(unit='SI', direction=['x', 'y', 'z'], levels=100, quiverplot=True, quiverscale=1.0, colorplot=True, colormap='jet', cbar_label='default', a_range=[], b_range=[], rectangle=False, edgeplot=False, x_ticks=5, y_ticks=5, title='default', figsize=[6.4, 4.8], fig=None, ax_index=None, **kwargs)

Plot 2D orbital current density field.

3 styles are available:

quiverplot=True and colorplot=True: The color-filled contour
illustrates the norm of vectors. The black arrows indicates both the directions and norms of in-plane prjections.
quiverplot=True and colorplot=False: The arrows are colored
to indicate the directions and norms of in-plane prjections.
quiverplot=False and colorplot=True: The color-filled contour
illustrates the norm of vectors, similar to the 2D scalar map.

Parameters:

unit (str) – Plot unit. ‘SI’ for \(\AA\) and A/m \(^{2}\). ‘a.u.’ for Bohr and a.u. current density.
direction (str|list) – Direction of spin-current to plot, in ‘x’, ‘y’ or ‘z’.
levels (int|array) – Set levels of colored contour/quiver plot. A number for linear scaled plot colors or an array for user-defined levels. 1D.
quiverplot (bool) – Plot 2D field of arrows.
quiverscale (float) – Tune the length of arrows. Useful only if quiverplot=True.
colorplot (bool) – Plot color-filled contour plots.
colormap (str) – Matplotlib colormap option. Useful only if colorplot=True.
cbar_label (str|None) – Label of colorbar. ‘default’ for unit. ‘None’ for no label. Useful only if colorplot=True.
a_range (list) – 1*2 range of \(a\) axis (x, or BC) in fractional coordinate.
b_range (list) – 1*2 range of \(b\) axis (x, or AB) in fractional coordinate.
rectangle (bool) – If \(a, b\) are non-orthogonal, plot a rectangle region and reset \(b\). If used together with b_range, that refers to the old \(b\) (i.e., expansion first).
edgeplot (bool) – Whether to add cell edges represented by the original base vectors (not inflenced by a/b range or rectangle options).
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.
fig (Figure) – Developer Only, matplotlib Figure class.
ax_index (list[int]) – Developer Only, indices of axes in fig.axes. Must be consistent with length of direction.
**kwargs – Other arguments passed to axes.quiver() function to set arrow styles.

Returns:

fig (Figure) – Matplotlib Figure class.

_set_unit(unit)

Set units of data of SpinCurrentDensity object.

Parameters:: unit (str) – ‘SI’, length: \(\AA\), spin current density: A/m \(^{2}\). ‘a.u.’, all in a.u..