Evaluation of One-Electron Properties — oeprop()

Code author: Robert M. Parrish and Andrew C. Simmonett

Section author: Andrew C. Simmonett

psi4.oeprop(wfn, *args, **kwargs)

Evaluate one-electron properties.

Returns:

None

Parameters:

• wfn (Wavefunction) – set of molecule, basis, orbitals from which to compute properties

• args (List[str]) – Arbitrary-number of properties to be computed from wfn. See Available One-Electron Properties.

• title (str) – label prepended to all psivars computed

Examples:

>>> # [1] Moments with specific label
>>> E, wfn = energy('hf', return_wfn=True)
>>> oeprop(wfn, 'DIPOLE', 'QUADRUPOLE', title='H3O+ SCF')

PSI4 is capable of computing a number of one-electron properties summarized in the table below.

Current one-electron property capabilities of PSI4

Feature	Keyword	Notes
Electric dipole moment	DIPOLE
Electric quadrupole moment	QUADRUPOLE	Raw (traced) moments and traceless multipoles
All moments up order N	MULTIPOLE(N)	Only raw (traced) moments. Sets global variables e.g. “DIPOLE”, “32-POLE”
Electrostatic potential, at nuclei	ESP_AT_NUCLEI	Sets global variables “ESP AT CENTER n”, n = 1 to natoms
Electrostatic potential, on grid	GRID_ESP	Generates V at each point in grid_esp.dat. See Properties evaluated on a grid
Electric field, on grid	GRID_FIELD	Generates {Ex,Ey,Ez} at each point grid_field.dat. See Properties evaluated on a grid
Molecular orbital extents	MO_EXTENTS
Mulliken atomic charges	MULLIKEN_CHARGES
Löwdin atomic charges	LOWDIN_CHARGES
Wiberg bond indices	WIBERG_LOWDIN_INDICES	Uses (Löwdin) symmetrically orthogonalized orbitals
Mayer bond indices	MAYER_INDICES
Natural orbital occupations	NO_OCCUPATIONS
Stockholder Atomic Multipoles	MBIS_CHARGES	Generates atomic charges, dipoles, etc. See Minimal Basis Iterative Stockholder
Free-atom volumes	MBIS_VOLUME_RATIOS

There are two ways the computation of one-electron properties can be requested. Firstly, the properties can be evaluated from the last computed one-particle density, using the following syntax:

oeprop("MO_EXTENTS", "MULTIPOLE(4)", title = "hello!")

Note that it is the user’s responsibility to ensure that the relaxed density matrix is computed using the method of interest, which may require setting additional keywords (see the method’s manual section for details). The named argument, title, is completely optional and is prepended to any globals variables set during the computation. The unnamed arguments are the properties to be computed. These can appear in any order, and multiple properties may be requested, as in the example above. Note that, due to Python syntax restrictions, the title argument must appear after the list of properties to compute. The available properties are shown in the table above.

The syntax above works well for computing properties using the SCF wavefunction, however, may be difficult (or impossible) to use for some of the correlated levels of theory. Alternatively, one-electron properties can be computed using the built-in properties() function, e.g.:

properties('ccsd', properties=['dipole'])

The properties() function provides limited functionality, but is a lot easier to use for correlated methods. For capabilities of properties() see the corresponding section of the manual.

Basic Keywords

Multipole moments may be computed at any origin, which is controlled by the global PROPERTIES_ORIGIN keyword. The keyword takes an array with the following possible values:

Allowed origin specifications

Keyword	Interpretation
[x, y, z]	Origin is at the coordinates, in the same units as the geometry specification
[“COM”]	Origin is at the center of mass
[“NUCLEAR_CHARGE”]	Origin is at the center of nuclear charge

Properties evaluated on a grid

Certain properties may be evaluated a user-specified grid points. The grid points are completely arbitrary and are specified by providing a file called grid.dat containing the x,y,z values separated with spaces for each point in order:

x1 y1 z1
x2 y2 z2
..........
xn yn zn

The grid.dat file is completely free form; any number of spaces and/or newlines between entries is permitted. The units of the coordinates in grid.dat are the same as those used to specify the molecule’s geometry, and the output quantities are always in atomic units. The requested properties will be written out in the same order as the grid point specification in grid.dat; see the above table for the format and file name of the output.

The grid may be generated in the input file using standard Python loops. By capturing the wavefunction used to evaluate the one-electron properties, the values at each grid point may be captured as Python arrays in the input file:

E, wfn = prop('scf', properties=["GRID_ESP", "GRID_FIELD"], return_wfn=True)
Vvals = wfn.oeprop.Vvals()
Exvals = wfn.oeprop.Exvals()
Eyvals = wfn.oeprop.Eyvals()
Ezvals = wfn.oeprop.Ezvals()

In this example, the Vvals array contains the electrostatic potential at each grid point, in the order that the grid was specified, while the Exvals, Eyvals and Ezvals arrays contain the x, y and z components of the electric field, respectively; all of these arrays can be iterated and manipulated using standard Python syntax. For a complete demonstration of this utility, see the props4 test case.

Minimal Basis Iterative Stockholder

The Minimal Basis Iterative Stockholder (MBIS) method is one of many procedures that partitions a molecular one-particle density matrix into atomic electron densities. Running MBIS in PSI4 will calculate atomic valence charge widths, volume ratios, atomic charges, as well as dipoles, quadrupoles, and octupoles. Additionally, all expectation values of radial moments of n-th order (\(<r^n>\)) are computed up to fourth order. Higher moments can be computed by specifying MAX_RADIAL_MOMENT. The volume ratios are computed as the ratio between the volume of the atomic density (\(<r^3>\)) and the volume of the free atom computed using the same level of theory, but with a potentially unrestricted reference.

The allowed number of iterations and convergence criteria for the stockholder algorithm is controlled by MBIS_MAXITER and MBIS_D_CONVERGENCE. Note that the density is partitioned on a molecular quadrature grid, the details of which can be controlled with the keywords MBIS_RADIAL_POINTS, MBIS_SPHERICAL_POINTS, and MBIS_PRUNING_SCHEME. (Associated Paper: [Verstraelen:2016])