**VISUAL

This section describes the functionalities of the VISUAL module, which calculates various molecular densities from the 1-electron density matrices and atomic orbitals. These densities (here called grid functions) are calculated on numerical grids and can be integrated or exported as scalar, vector, or tensor fields (e.g., for visualization or further processing). The VISUAL module is not activated by default.

The main setup for these calculations should be provided by the .GRIDS and .GRIDFUNCTIONS blocks, as described below.

GRIDS

.GRIDS

Grid(s) specification block. Next line should contain the number of grids to be used. Then, the following lines should provide information about each grid (as a key=value list).

For example, to import the grid from the grid.h5 file, use:

.GRIDS
1
id=1 input=import file_inp=grid.h5

Available key=value options

• id=int

  The ID of a grid. Required, used as a reference for .GRIDFUNCTIONS specification.

• npoints=[Nx,Ny,nz]

  Specify the number of grid points in x, y, and z directions. Either npoints or spacing is required for grid generation.

• spacing=[Sx,Sy,Sz] or spacing=S

  Specify the grid resolution, i.e., the distance between two consecutive grid points. Use spacing=[Sx,Sy,Sz] to specify the distance between grid points in x, y, and z directions, or spacing=S to specify the same distance between grid points for all directions. Either npoints or spacing is required for grid generation.

• input=option

  Specify grid input. Available options:

  • input=create : create grid; the default is a 3D rectilinear grid; requires the specification of npoints or spacing

  • input=import : import grid from an external file

  • input=dft : use the DFT numerical grid; requires numerical_grid file

  • input=list : use the list of grid points; should be provided in the input (see .LIST)

  • input=line : create grid points on line; should be provided in the input (see .LINE keyword)

  • input=2d : create grid points on a 2D plane; should be provided in the input (see .2D keyword)

  • input=2d_int : create grid points on a 2D plane for integration; should be provided in the input (see .2D_INT keyword)

  • input=3d : create grid points on a 3D surface; should be provided in the input (see .3D keyword)

  • input=3d_int : create grid points on a 3D surface for integration; should be provided in the input (see .3D_INT keyword)

  • input=radial : create radial grid; should be provided in the input (see .RADIAL keyword)

• margin=f

  Add space around the 3D rectilinear grid. Applies only to generated 3D rectilinear grids. Default is f=0.0 (value in a.u.), which creates grid point spanning the space between the minimum and maximum coordinates of all atoms, i.e., \(x_{grid}=[min(x_{a}),max(x_{a})]_{a\in atoms}\), \(y_{grid}=[min(y_{a}),max(y_{a})]_{a\in atoms}\), \(z_{grid}=[min(z_{a}),max(z_{a})]_{a\in atoms}\). Therefore, for typical applications, choose some \(f>0\) (e.g., margin=4.0 is typically OK for the electron density visualization).

• export=option

  If the grid should be exported to a file, this allows to define the file format for export. Supported formats:

  • export=hdf5 : export to hdf5 file

  • export=txt : export to text file, no header, space as a separator (for backward compatibility with old VISUAL code)

  • export=csv : export to text file (csv): header line, coma as a separator

• file_inp=string

  The name of a file, from which the grid should be read.

• file_out=string

  The name of a file, to which the grid should be exported

Notes:

• current limitations:

  • make sure there is one space between each key=value entry in the grid specification line.

  • the maximum line length in the input file is 200 characters

• for the specific examples, see the corresponding test in DIRAC test suite: test/visual_grid_options

Additional keywords

The selected grid inputs (see input=option) require additional specification. This should be provided as a separate keyword block following the .GRID keyword. Most of these keywords are the same as used in the old VISUAL code.

.LIST

Calculate various densities in few points. Scalar and vector densities are written to the standard output file. Example (3 points; coordinates in bohr):

.LIST
 3
 1.0 0.0 0.0
 0.0 1.0 0.0
 0.0 0.0 1.0

In the DIRAC input file, this should be provided as:

.GRIDS
id=1 input=list
.LIST
 3
 1.0 0.0 0.0
 0.0 1.0 0.0
 0.0 0.0 1.0

.LINE

Calculate various densities along a line. Example (line connecting two points; 200 steps; coordinates in bohr):

.LINE
 0.0 0.0 0.0
 0.0 0.0 5.0
 200

.RADIAL

Compute radial distributions

\[f(r) = \int_{0}^{2\pi}\int_{0}^{\pi}f(\mathbf{r})r^2\sin\theta d\theta d\phi\]

by performing Lebedev angular integration over a specified number of even-spaced radial shells out to some specified distance from a specified initial point. Example (coordinates and distance in bohr):

.RADIAL
0.0 0.0 0.0
10.0
200

The first line after the keyword specifies the initial point, here chosen to be the origin. The second and third line is the distance and step size, respectively.

.2D

Calculate various densities in a plane. The plane is specified using 3 points that have to form a right angle. Example (coordinates in bohr):

.2D
 0.0  0.0  0.0     !origin
 0.0  0.0 10.0     !"right"
 200               !nr of points origin-"right"
 0.0 10.0  0.0     !"top"
 200               !nr of points origin-"top"

.2D_INT

Integrate various densities in a plane using Gauss-Lobatto quadrature. The plane is specified using 3 points that have to form a right angle. Example (coordinates in bohr):

.2D_INT
 0.0  0.0  0.0     !origin
 0.0  0.0 10.0     !"right"
 10                !nr of tiles to the "right"
 0.0 10.0  0.0     !"top"
 10                !nr of tiles to the "right"
 5                 !order of the Legendre polynomial for each tile

.3D

Calculate various densities in 3D and write to cube file format. Example (coordinates in bohr):

.3D
 40 40 40          ! 40 x 40 x 40 points

Note: this is the same as using npoints=[40,40,40] in the grid specification line.

.3D_INT

Integrate various densities in a volume.

Grid functions

.GRIDFUNCTIONS

Grid function(s) specification block. Next line should contain the number of grid functions to be calculated. Then, the following lines should provide information about each grid function (as a key=value list).

For example, to calculate the values of the electron density (ed), its laplacian (ed_laplacian), and the reduced density gradient (rdg) in the grid points of the grid supplied with the index \(id=1\) (specified in the .GRIDS section of the input) and exporting them to the respective files, use:

.GRIDFUNCTIONS
3
name=ed id_grid=1 purpose=visualization export=cube file_out=ed.cube
name=ed_laplacian id_grid=1 purpose=visualization export=hdf5 file_out=ed_laplacian.h5
name=rdg id_grid=1 purpose=visualization export=csv file_out=rdg.csv

Available grid functions

The table below summarizes the grid functions currently implemented in DIRAC with their respective test directories in DIRAC test suite.

DIRAC properties

name	property	DIRAC tests directories
ed	electron density, $rho(vec{r})$	visual_3d_electronden*
ed_gradient	electron density gradient, $nablarho(vec{r})$	visual_3d_electronden*
ed_hessian	electron density Hessian, $Hrho(vec{r})$	visual_3d_electronden*
ed_laplacian	electron density Laplacian, $nabla^2rho(vec{r})$	visual_3d_electronden*
ed_sign_lambda2	$sign(lambda_2)rho(vec{r})$	visual_3d_electronden*
rdg	reduced density gradient	visual_3d_electronden*
elf	electron localization function	visual_3d_elf*
kin	kinetic energy density (1)	visual_3d_kinden*
kinls	kinetic energy density (2)	visual_3d_kinden*
kinsl	kinetic energy density (2)	visual_3d_kinden*
kinlap	the Laplacian of the kinetic energy density	visual_3d_kinden*
kintau	kinetic energy density (3)	visual_3d_kinden*
kinnr	the non-relativistic kinetic energy density	visual_3d_kinden*
s	spin density, $rho_s(vec{r})$	visual_3d_spinden*
divs	$Delta cdotrho_s(vec{r})$	visual_3d_spinden*
rots	$Delta times rho_s(vec{r})$	visual_3d_spinden*
gamma5	$gamma^5$ density	visual_3d_gamma5*
edip	the electric dipole density	visual_3d_rspE*
bdip	the magnetic dipole density	visual_3d_rspB*
ndip	the nuclear magnetic dipole density	visual_3d_rspB*
j	the probability current density, $vec{j}(vec{r})$	visual_3d_rspB*
rotj	$nabla times vec{j}(vec{r})$	visual_3d_rspB*
divj	$nabla cdot vec{j}(vec{r})$	visual_3d_rspB*
gradj	$Delta vec{j}(vec{r})$	visual_3d_rspB*

Comments:

• the kinetic energy density (1) and its LS- and SL-components (2) are calculated as $c psi^dagger(r) (alpha cdot p) psi(r)$

• the kinetic energy density (3) calculated as $tau = nabla_i phi_k nabla_i phi_k$

Available key=value options

Notes:

• current limitations:

  • make sure there is one space between each key=value entry in the grid function specification line.

  • the maximum line length in the input file is 200 characters

General key=value options

• name=string

  The name of the grid function to calculate; see the available options in the table above.

• id_grid=int

  The ID of a grid on which the grid function should be calculated (see the grid ID specification in .GRIDS.

• input=option

  Specify grid function input. Available options:

  • input=calculate : calculate grid function; the default option

  • input=import : import grid function from file

• purpose=option

  Specify the type of calculations. Available options:

  • purpose=visualization : calculate grid function in grid points; possible export as scalar/vector/tensor field for a subsequent visualization; the default option

  • purpose=integration : integrate grid function; for the specific examples, see the corresponding test in DIRAC test suite: test/visual_integration.

• outpri=option

  Specify whether the grid function values should also be printed out to DIRAC output. Available options: outpri=no (default if purpose=visualization), outpri=yes (default if purpose=integration).

• export=option

  If the grid function should be exported to a file, this allows to define the file format for export. Supported formats:

  • export=hdf5 : export to hdf5 file

  • export=txt : export to text file, no header, space as a separator (for backward compatibility with old VISUAL code)

  • export=cube : export to gaussian cube file; available only for 3D rectilinear grids and scalar fields (for backward compatibility with old VISUAL code)

  • export=csv : export to text file (csv): header line, coma as a separator

• file_inp=string

  The name of a file, from which the grid should be read.

• file_out=string

  The name of a file, to which the grid should be exported

key=value options allowing for pointwise modification of grid functions

• dscale=f

  Scale densities down by a factor f. Default: dscale=1.0

• uscale=f

  Scale densities up by a factor f. Default: uscale=1.0

• carpow=[x,y,z]

  Scale densities by Cartesian product \(x^iy^jz^k\). The x,y,z values are three integers specifying the exponents \((i,j,k)\). For example, carpow=[1,0,0] is equivalent to calculating the x-component of the electric dipole moment density (specification name=edip).

• radpow=f

  Scale densities by a radial power \(r^{n}\). The keyword is followed by three integers specifying the exponent \(n\). Example: radpow=1 allows to the calculation of radial expectation values \(<r>\) with respect to the origin.

Notes:

• for the specific examples, see the corresponding test in DIRAC test suite: test/visual_grid_function_modifications

Additional keywords affecting grid functions

.OCCUPATION

Specify occupation of orbitals. Example (neon atom):

.OCCUPATION
 2
 1 1-2 1.0
 2 1-3 1.0

The first line after the keyword gives the number of subsequent lines to read. In each line, the first number is the fermion ircop. In molecules with inversion symmetry there are two fermion ircops: gerade (1) and ungerade (2). Otherwise there is a single fermion ircop (1). The specification of the fermion ircop is followed by the range of selected orbitals and their occupation. If a single orbital is specified a single number is given instead of the range.

Another example (water):

.OCCUPATION
 1
 1 1-5 1.0

Another example (nitrogen atom):

.OCCUPATION
 2
 1 1-2 1.0
 2 1-3 0.5

Warning: this keyword affects all grid functions specified in the input.

.CVALUE

Set the speed of light to be used in the VISUAL module.

Warning: this keyword affects all grid functions specified in the input.

General setup

.PRINTL

Control the print level:

.PRINTL
print_level

Predefined print_level values:

• print_level = 0: ony the basic information from the VISUAL calculations is printed out; the default option

• print_level = 1 : more details on the methods used are printed out

• print_level = 2 : additional print of matrices (warning: large output!)

• print_level > 2 : the development prints (warning: large output!)

All information is printed out to DIRAC output.

Additional notes (untested functionalities; notes from the old VISUAL code)

Warning

Only the calculation of the density is tested for open shell configurations (and relies on a correct .OCCUPATION). All other properties are only tested for closed shell systems and should not be trusted for open shell systems without a thorough testing.