ORBKIT’s High-Level Interface

This chapter should serve as an overview of how to use ORBKIT’s high-level interface within your Python programs. For clarity, it is structured equivalently to Usage via the Terminal.

General Aspects

To access the main features of ORBKIT, you have to import it using:

import orbkit

Now, you can specify all options for the computation analogously to Usage via the Terminal, e.g.:

orbkit.options.numproc = 4                       # number of processes

Within this chapter we will discuss the most important options. For an overview of all available options, please refer to the chapter Options.

Finally, you have to run ORBKIT with:

data = orbkit.run_orbkit()

This function will not only save the results to the requested output formats, it will also return the results for further post-processing.

Hint

If you want to run several calculations with different options, you have to reset all options. This can be accomplished by calling orbkit.init() between the calculations, e.g.:

import orbkit as ok
# Set some options ...
# run orbkit
data_1 = orbkit.run_orbkit()

# Reset all options
orbkit.init()
# Set some options ...
# run orbkit
data_2 = orbkit.run_orbkit()

Input/Output

The input filename can be specified by:

orbkit.options.filename = 'h2o.molden'

The available file types are ‘molden’, ‘aomix’ (AOMix file), ‘gamess’ (GAMESS-US output file), ‘gaussian.log’ (GAUSSIAN output file), ‘gaussian.fchk’ (GAUSSIAN formatted checkpoint file), ‘wfn’ and ‘wfx’ files.

Concerning ORBKIT’s output, you can choose between the following options:

  • ‘h5’ (HDF5 file)
  • ‘cb’ (Gaussian cube file)
  • ‘vmd’ (VMD network)
  • ‘am’ (ZIBAmiraMesh file)
  • ‘hx’ (ZIBAmira network)
  • ‘vmd’ (VMD network)
  • ‘mayavi’ (opens a simple interactive Mayavi interface)

You can also specify more than one output format at the same time:

orbkit.options.otype = ['h5','vmd']

ORBKIT assumes the input file, if not otherwise stated, e.g.:

orbkit.options.outputname = 'h2o' # output file (base) name

For more information on the different output types, refer to Input/Output (Usage via the Terminal).

Hint

You can omit the creation of an output file by either setting orbkit.options.otype = [] or by setting orbkit.options.no_output = True. Furthermore, you can disable the creation of .oklog file can with orbkit.options.no_log = True, and the terminal output can be disabled with orbkit.options.quiet = True.

Molecular Orbital Selection

ORBKIT is capable of calculating a selected set of molecular orbitals:

orbkit.options.calc_mo = ['3.1','1.1','2.3']

and of calculating the density with a selected set of molecular orbitals:

orbkit.options.mo_set = [[1,2,3],                   # first set
                     ['homo', 'lumo+2:lumo+4']] # second set

Note

While the first example uses the MOLPRO-like nomenclature, e.g., 3.1 for the third orbital in symmetry one, the second example uses the index within the input file (counting from one).

For unrestricted calculations, the symmetry labels are extended by _a for alpha and by _b for beta molecular orbitals, e.g., 3.A1_b.

For more information, refer to Molecular Orbital Selection (Usage via the Terminal).

Derivative Calculation

ORBKIT can compute analytical spatial derivatives with respect to \(x\), \(y\), and \(z\) for the atomic and molecular orbitals, as well as for the electron density:

orbkit.options.drv = ['x', 'z']

This invokes the computation of the derivatives with respect to \(x\) and the computation of the derivatives with respect to \(z\). For second derivatives, specify the respective combinations,e.g., ‘xx’ or ‘yz’.

Spin-Density

For unrestricted calculations, the spin density and related quantities (e.g. derivatives) may be calculated by:

orbkit.options.spin = 'alpha'

or:

orbkit.options.spin = 'beta'

The usage of this keyword omits the reading of the molecular orbitals of the other spin.

Return Values

Besides writing the requested output, the function run_orbkit(), returns all data computed:

data = orbkit.run_orbkit()

Depending on your options, this data set has a different structure.

Computed Quantity Returned Data
density numpy.ndarray with shape=(N)
derivative of density
  1. density numpy.ndarray with shape=(N)
  2. derivative of density numpy.ndarray with shape=(NDRV,N)
molecular orbitals
  1. numpy.ndarray with shape=((NMO,) + N)
  2. dict with information on selected molecular orbitals
derivative of molecular orbitals
  1. numpy.ndarray with shape=((NDRV,NMO,) + N)
  2. dict with information on selected molecular orbitals

density from a set of

molecular orbitals

  1. numpy.ndarray with shape=((NSET,) + N)
  2. dict with information on selected molecular orbitals

derivative of density from a

set of molecular orbitals

  1. numpy.ndarray with shape=((NSET,NDRV,) + N)
  2. dict with information on selected molecular orbitals
  • N is shape as the grid.
  • NDRV is the number derivatives requested.
  • NMO is the number of molecular orbitals requested.
  • NSET is the number of molecular orbital sets requested.