# 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 as ok


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

ok.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 = ok.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 ok.init() between the calculations, e.g.:

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

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


## Input/Output¶

The input filename can be specified by:

ok.options.filename = 'h2o.molden'


The file type has to be specified via:

ok.options.itype = 'molden'


The available file types are ‘molden’ (default), ‘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 several 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)

Several output types can be considered at once:

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


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

ok.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 ok.options.otype = [] or by setting ok.options.no_output = True. Furthermore, you can disable the creation of .oklog file can with ok.options.no_log = True, and the terminal output can be disabled with ok.options.quiet = True.

## Molecular Orbital Selection¶

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

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


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

ok.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:

ok.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:

ok.options.spin = 'alpha'


or:

ok.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 = ok.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 density numpy.ndarray with shape=(N) derivative of density numpy.ndarray with shape=(NDRV,N) molecular orbitals numpy.ndarray with shape=((NMO,) + N) dict with information on selected molecular orbitals derivative of molecular orbitals numpy.ndarray with shape=((NDRV,NMO,) + N) dict with information on selected molecular orbitals density from a set of molecular orbitals numpy.ndarray with shape=((NSET,) + N) dict with information on selected molecular orbitals derivative of density from a set of molecular orbitals numpy.ndarray with shape=((NSET,NDRV,) + N) 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.