Tutorial for Processing Multiple Input Files

We assume that you have followed the Installation Instructions and that you have navigated to the folder $ORBKITPATH/examples/basic_examples. Please note that the input files are compressed in .tar.gz file in the examples folder ($ORBKITPATH/examples/basic_examples/NaCl_molden_files.tar.gz) and need to be decompressed before performing this tutorial.

Hint

This tutorial explains parts of the example file $ORBKITPATH/examples/basic_examples/use_for_ordering.py.

How to Read a List of Files

As a starting point, you have to import the ORBKIT module for processing multiple files:

from orbkit import multiple_files

Now, we have to create a list of input file names:

import os
path = 'NaCl_molden_files'
# How are input files formatted?
fid = 'nacl.%03d.molden'
fid_list = []
for i in range(0,16,1):
  f = os.path.join(path,fid % i)
  if not os.path.exists(f):
    raise IOError('%s does not exist!' % f)
  fid_list.append(f)

Here, we have used the os module to get sure that all input files exist.

The input files can be read with:

multiple_files.read(fid_list,itype='molden',all_mo=True,nosym=False)

Now, all input variables are global values in the module multiple_files. These variables are named according to their analogue in the QCinfo class (cf. Central Variables):

Variable	Contents
geo_spec_all	Contains all molecular geometries, see geo_spec in Central Variables.
geo_info	See geo_info in Central Variables.
ao_spec	See ao_spec in Central Variables.
ao_spherical	See ao_spherical in Central Variables.
mo_coeff_all	Contains all molecular orbital coefficients. List of numpy.ndarray.
mo_energy_all	Contains all molecular orbital energies. List of numpy.ndarray.
mo_occ_all	Contains all molecular orbital occupations. List of numpy.ndarray.
sym	Python dictionary containing the molecular orbital symmetries and the corresponding position in mo_coeff_all, mo_energy_all, and mo_occ_all, respectively.
index_list	After the execution of the ordering routine, it contains the new indices of the molecular orbitals. If index < 0, the molecular orbital changes its sign. shape=(Nfiles,NMO).

How to Order the Molecular Orbital Coefficients

ORBKIT provides different schemes to order molecular orbitals, of which the best shall be presented here: the ordering using analytical integrals between neighboring molecular orbitals.

This procedure is a black box procedure and can be called with:

index_list, mo_overlap = multiple_files.order_using_analytical_overlap(None)

The input argument None has been used since we have read already the input files.

This function changes all global variables and returns an index list containing the new indices of the molecular orbitals.

Note

If the index is negative, the molecular orbital changes its sign.

Moreover, it returns the molecular orbital overlap matrix between the molecular orbitals of two neighboring geometries, i.e., mo_overlap[i,j,k] corresponds to overlap between the \(j\) th molecular orbital at geometry \(i\) to the \(k\) th molecular orbital at geometry \((i+1)\).

How to Save and Read the Information Obtained to and from an HDF5-File

All global variables of the module multiple_files can be stored to an HDF5-file by:

multiple_files.save_hdf5('nacl.h5')

To read this file and recover the global variables, simply call:

multiple_files.read_hdf5('nacl.h5')

How to Depict Several Molecular Orbitals

You can use this module to depict snapshots of selected molecular orbitals with simple contour plots:

selected_mos = ['24.1','23.2'] # Specifies, which MOs to be plotted
r0 = 1                         # Specifies the starting structure geo_spec_all[r0]
steps = 5                      # Specifies, how many steps to printed in one graph

select_slice = 'xz'            # Selects which plane to be plotted
where = 0.0                    # Selects where to place the plane (Here, y=0)

multiple_files.show_selected_mos(selected_mos,r0=r0,steps=steps,
                                 select_slice=select_slice,where=where)

How to Perform a Standard ORBKIT Computation for One Molecular Structures

You can cast the global variables of multiple_files automatically to a list of QCinfo classes (cf. Central Variables) by:

QC = multiple_files.construct_qc()

Now, you can access every data point separately and perform ORBKIT calculations, e.g.:

import orbkit as ok

r = 0                    # Index to be calculated
out_fid = 'nacl_r%d' % r # Specifies the name of the output file

# Initialize orbkit with default parameters and options
ok.init()

# Set some options
ok.options.adjust_grid= [5, 0.5]                # adjust the grid to the geometry
ok.options.otype      = 'mayavi'                  # output file (base) name

# Run orbkit with one instance of qc as input
ok.run_orbkit(QC[10])

How to Process Data of Two or More dimensions

Since the ordering routine is only suitable for one dimensional data, the input data has to be rearranged if you want to treat problems of higher dimensionality.

We suggest two different approaches, which may be applied to an arbitrary number of dimensions:

Attention

Please make always sure that the ordering procedure was successful by plotting and checking the final molecular orbital overlaps and molecular orbital coefficients!