oeprop(1)

📦 version 3.4.0, in debian bookworm, ubuntu jammy, ubuntu noble

oeprop(1) 💖 — the One-Electron Property Program

okay bestie, sit down, hydrate, because oeprop is the One-Electron Property Program and she is booked and busy. ✨

✨ NAME ✨

oeprop — One-Electron Property Program 🎀

🦋 DESCRIPTION 🦋

so here's the vibe: oeprop computes expectation values of one-electron property operators, using a one-particle density matrix that's either computed from an eigenvector hanging out in PSIF_CHKPT, or read in from an external file. either way, she ate. 💅

Right now she is currently capable of:

  • Mulliken population analysis 👑
  • computing electric multipole moments through octopole
  • electrostatic properties at atomic centers — that's electrostatic potential, electric field, electric field gradient, electron and spin density, and the dipolar anisotropic contribution to the hyperfine coupling constants 🌸
  • electron and spin density
  • electron and spin density gradient
  • Laplacian of electron and spin densities
  • electrostatic potential over an arbitrary two-dimensional (planar) rectangular grid
  • molecular orbitals values over an arbitrary three-dimensional rectangular grid

and then the miscellaneous corner of the group chat, which is also iconic:

  • computation of the relativistic first-order one-electron corrections to the energy (that's the mass-velocity and Darwin terms, no cap) 🔥
  • construction of natural molecular orbitals from one-particle density read from an external file (and yes, the NOs can be written to PSIF_CHKPT)
  • computation of spatial extents — expectation values of X^2, Y^2, Z^2, and R^2 operators — of total electron density and of individual MOs (if READ_OPDM = false) or natural (if READ_OPDM = true) orbitals.
⚠️ okay so for those spatial extents: MPMAX must be set to a value greater than 1 for computing these entities. and fr fr, use spatial extents cautiously, because they depend on the reference point. it's giving "results may shift depending on where you're standing." 🫶

📚 REFERENCES 📚

Mulliken population analysis

  1. Electronic Population Analysis on LCAO-MO Molecular Wave Functions. R. S. Mulliken, J. Chem. Phys. 23, 1833 (1955), ibid. 23, 1841 (1955), ibid. 36, 3428 (1962).

Recurrence relations for one-electron integrals over Cartesian Gaussian functions.

  1. Efficient recursive computation of molecular integrals over Cartesian Gaussian functions. S. Obara and A. Saika, J. Phys. Chem. 84, 3963 (1986).

Fundamental physical constants and conversion factors.

  1. CRC Handbook of chemistry and physics. Edited by D. R. Lide. 73rd edition (1992-1993).

🎀 FILES REQUIRED 🎀

like, she needs these to even function, bestie:

input.dat        - Input file
PSIF_CHKPT       - Checkpoint file

💖 FILES UPDATED 💖

the receipts she leaves behind. obsessed:

output.dat
dipmom.dat       -   Dipole moments
esp.dat          -   Electrostatic potential on a 2D grid
edens.dat        -   Electron density on a 2D grid
edgrad.dat       -   Electron density gradient on a 2D grid
edlapl.dat       -   Laplacian of the electron density on a 2D grid
sdens.dat        -   Spin density on a 2D grid
sdgrad.dat       -   Spin density gradient on a 2D grid
sdlapl.dat       -   Laplacian of the spin density on a 2D grid
mo.dat           -   Molecular orbital/Density values on a 3D grid
mo.pov           -   MegaPov input file for rendering an image of mo.dat
mo.cube          -   Molecular orbital(s) on a 3D grid in Gaussian94 Cube format
dens.cube        -   Electron/spin density(s) on a 3D grid in Gaussian94 Cube format

🌺 that's the setup, and there is so much more coming — don't go anywhere, part 2 is right there 👑

✨ INPUT FORMAT ✨

okay so real talk bestie: most of these keywords? you will literally never need them for your everyday lil routine tasks 💅. but here's the full list anyway because we don't gatekeep. the following keywords are valid:

  • WFN = boolean — the type of the wavefunction. this one is a total "macro" vibe — it lets the user set most of the necessary keywords in one go 🫶. here are the values that get recognized:
    • WFN = SCF — equivalent to READ_OPDM = false;
    • WFN = DETCI — equivalent to READ_OPDM = true, OPDM_FILE = 40, OPDM_BASIS = AO, OPDM_FORMAT = TRIANG;
    • WFN = CCSD — equivalent to EAD_OPDM = true, OPDM_FILE = 79, OPDM_BASIS = AO, OPDM_FORMAT = TRIANG;
    • WFN = QVCCD — equivalent to READ_OPDM = true, OPDM_FILE = 76, OPDM_BASIS = SO, OPDM_FORMAT = TRIANG;
  • READ_OPDM = boolean — this flag says whether the one-particle density matrix is gonna be read from disk. default is false. no cap ✨
  • OPDM_FILE = integer — specifies the one-particle density matrix file number. default is 40 (the master file). for backward compatibility with the earlier PSI property packages (proper, ciprop, ccprop) a special format of the density file is assumed when OPDM_FILE = 40 (computing properties from CI density — ciprop compatibility mode) and OPDM_FILE = 79 (computing properties from CC density — ccprop compatibility mode). as of now, in the generic case onepdm must be written at the very beginning of the file. in the future PSI will have a standard onepdm file 💖
  • OPDM_BASIS = string — this option may not exist in the future 👀. as of February 1st, 1998, a standard for the onepdm file format has not been set. this keyword should be set to either "SO" (read in onepdm matrix in SO basis) or "AO" (in AO basis). default is "SO".
  • OPDM_FORMAT = string — this option may not exist in the future either 🙈. this keyword should be set to either "TRIANG" (read in onepdm matrix in lower triangular form) or "SQUARE" (in square form). default is "TRIANG"
  • ASYMM_OPDM = boolean — this flag specifies whether the one-particle density matrix has to be symmetrized. must be set to true if a generic non-symmetric onepdm is to be read (for example, from a coupled-cluster program). this keyword is for code development only 🧑‍💻. existing PSI CC codes now in use produce symmetric onepdm, therefore there is no need to use this keyword. default is false.
  • ROOT = integer — this specifies which root to do the excited state analysis for. the appropriate one particle density matrix will be read from disk. currently implemented for DETCI and DETCAS wavefunctions.
  • MPMAX = integer — this integer, somewhere between 1 and 3, specifies the highest electric multipole moment to be computed.
    • MPMAX = 1 — only the electric dipole moment will be computed (default);
    • MPMAX = 2 — electric dipole and quadrupole moments will be computed;
    • MPMAX = 3 — electric dipole, quadrupole, and octopole moments will be computed.
  • MP_REF integer — this parameter specifies the reference point for the electric multipole moments calculation.
    • MP_REF = 0 (default) or 1 — the center of mass;
    • MP_REF = 2 — the origin of the space coordinate system;
    • MP_REF = 3 — the center of electronic charge;
    • MP_REF = 4 — the center of nuclear charge;
    • MP_REF = 5 — the center of net charge.
CAUTION ⚠️ : according to classical electrodynamics, the electric 2^(n+1)-pole moment is independent of the reference point only if the electric 2^(n)-pole moment is vanishing. it means that the dipole moment will depend on the reference point if the total charge of the system is non-zero. by analogy, the electric quadrupole moment will depend on the reference point if the system possesses a non-zero electric dipole moment, etc. so yeah. read that twice bestie 😭
  • MP_REF_XYZ = real_vector — this vector specifies the coordinates of the reference point. if this keyword is present in the input, the MP_REF keyword will be disregarded. sorry MP_REF, you're cancelled 💀
  • NUC_ESP = boolean — this flag specifies if electrostatic properties will be computed at the nuclei. the current list includes electrostatic potential, electric field, electric field gradient, electron and spin density, and the anisotropic contribution to the hyperfine coupling constants (the latter two require setting SPIN_PROP to true). default is true 🌸
  • GRID = integer — specifies the type of property to be evaluated over a grid.
    • GRID = 0 (default) — compute nothing;
    • GRID = 1 — electrostatic potential on a two-dimensional grid;
    • GRID = 2 — electron density (spin density if SPIN_PROP is set to true) on a two-dimensional grid;
    • GRID = 3 — electron density gradient (spin density gradient if SPIN_PROP is set to true) on a two-dimensional grid;
    • GRID = 4 — Laplacian of the electron density (Laplacian of the spin density if SPIN_PROP is set to true) on a two-dimensional grid. according to the convention used in the field, what actually gets plotted are the Laplacians taken with negative sign;
    • GRID = 5 — values of molecular orbitals on a three-dimensional grid;
    • GRID = 6 — values of the electron density (spin density gradient if SPIN_PROP is set to true) on a three-dimensional grid.
  • GRID_FORMAT = string — specifies in which format the grid output will be produced. currently, PLOTMTV (default for 2-d grids), MEGAPOVPLUS (available for 3-d grids), and GAUSSCUBE (default for 3-d grids) are supported. pick your fighter 🎀
  • MO_TO_PLOT = vector — specifies indices of the molecular orbitals to be computed on the 3-d grid. indices can be specified as:
    • unsigned integer — index in Pitzer ordering (ordered according to irreps, not eigenvalues). ranges from 1 to the number of MOs;
    • signed integer — index with respect to the Fermi level. +1 means LUMO, +2 means second lowest virtual orbital, -1 means HOMO, etc.
all indices have to be either unsigned or signed, you can't mix and match, or you will get unpredictable results 😭. default is to compute HOMO and LUMO.
  • GRID_ORIGIN = real_vector — specifies the origin of the grid. a rectangular grid box which envelops the entire molecule will be computed automatically if GRID_ORIGIN is missing, however, there is no default for 2-d grids.
  • GRID_UNIT_X = real_vector — this vector specifies the direction of the first (x) side of the grid. it doesn't have to be of unit length. there is no default for 2-d grids.
  • GRID_UNIT_Y = real_vector — the same for the second (y) side. it doesn't have to be of unit length or even orthogonal to GRID_UNIT_X. there is no default for 2-d grids.
  • GRID_XY0 = real_2d_vector — specifies the coordinates of the lower left corner of the grid rectangle in the 2D coordinate system defined by GRID_ORIGIN, GRID_UNIT_X, and GRID_UNIT_Y. there is no default.
  • GRID_XY1 = real_2d_vector — specifies the coordinates of the upper right corner of the grid rectangle in the 2D coordinate system defined by GRID_ORIGIN, GRID_UNIT_X, and GRID_UNIT_Y. there is no default.
  • GRID_XYZ0 = real_3d_vector — specifies the coordinates of the far lower left corner of the grid box in the 3D coordinate system defined by GRID_ORIGIN, GRID_UNIT_X, GRID_UNIT_Y, and the cross-product of the latter two. there is no default.
  • GRID_XYZ1 = real_3d_vector — specifies the coordinates of the near upper right corner of the grid box in the 3D coordinate system defined by GRID_ORIGIN, GRID_UNIT_X, GRID_UNIT_Y, and the cross-product of the latter two. there is no default.
  • NIX = integer — the number of grid points along the x direction. this parameter has to be greater than 1. default is 20.
  • NIY = integer — the same as NIX for the y direction. default is 20.
  • NIZ = integer — the same as NIX for the z direction. default is 20.
  • GRID_ZMIN = double — lower limit on displayed z-values for contour plots of electron density and its Laplacian. default is 0.0
  • GRID_ZMAX = double — upper limit on displayed z-values for contour plots of electron density and its Laplacian. default is 3.0
  • EDGRAD_LOGSCALE = integer — controls logarithmic scaling of the produced electron density gradient plot. turns the scaling off if set to zero, otherwise the higher the value, the stronger the gradient field will be scaled. recommended value (default) is 5 ⭐
  • SPIN_PROP = boolean — flag for computing spin properties (Mulliken population analysis of alpha and beta densities, spin densities and anisotropic contributions to the hyperfine coupling constants at atomic centers). default is false.
  • PRINT = integer — this is the most important keyword 👑 — it determines the amount of information printed. the following values are currently used:
    • PRINT = 0 — quiet mode — print out essential results only — "compact" results of Mulliken population analysis, electric multipole moments, and electrostatic properties;
    • PRINT = 1 (default) — all of the above plus the list of tasks to be performed and the list of calculation parameters;
    • PRINT = 2 — all of the above plus the Mulliken AO population matrix and electronic and nuclear components of the electric dipole moment;
    • PRINT = 3 — all of the above plus the density matrix in AO basis and dipole moment integrals in AO (and SO) basis;
    • PRINT = 4 — all of the above plus basis set information, natural orbitals in terms of symmetry orbitals, overlap matrix;
    • PRINT >= 5 — all of the above plus coupling coefficient vectors, an occupation vector, and a modified Z-vector in MO basis.
  • PRINT_NOS = boolean — if WRTNOS = TRUE and this option is also TRUE, the natural orbitals will be printed to output before they are written to the checkpoint file.
  • WRTNOS = boolean — if TRUE, the natural orbitals will be written to the checkpoint file 💾

✨ GRID OUTPUT AND PLOTTING ✨

okay bestie this is the part where your numbers stop being numbers and become pictures 💖 plotting time, let's go

🌸 2D grids, aka the PLOTMTV situation

Currently, oeprop produces output of two-dimensional grids ready for plotting with a program called PLOTMTV version 1.3.2. no cap, that's the whole point of this format 🎀

The program is written by Kenny Toh (ktoh@td2cad.intel.com), software developer for the Technology CAD Department, Intel Corp, Santa Clara. It is a freeware package, and can be downloaded off the Internet. iconic of him honestly 👑

🦋 3D grids, aka the MegaPov era

Three-dimensional grids are output in a format suitable for plotting with a program called MegaPov version 0.5. It's a freeware program — a patched version of POV-Ray, if you can believe 💀 — and it is developed by a number of people, and can be downloaded off the Internet (go to http://nathan.kopp.com/patched.htm to find out more info).

So to render an MO or density image, here's the ritual bestie:

  1. edit (if necessary) the command file mo.pov that was created by oeprop
  2. execute this:
megapovplus +Imo.pov

and for more options, just run:

megapovplus -h
fr fr, if mo.pov needs tweaking, tweak it — that's literally why you're allowed to edit it 🍓

and that's the whole grid-output arc, bestie 🌈 go render something gorgeous, you've got this 💜

this page is from oeprop(1), dated March 30, 2001 — yeah it's an elder but it still ate ✨ mwah, take care of her 🫶

📦 where this page comes from