API Reference

Basic usage:

xmolecule provides a API to call and control xmolecule from python. API reference.

Load the interface using

from pyxmol import xmol

and then initialize an xmol object using

xm = xmol("input.in")

where "input.in" is a path to an input file specifiying a molecular geometry and basic calculation parameters (such as basis set). An example input file is the following:

 O      0.00000    0.00000      0.00000  
 H     -0.00000    0.78516      0.53415  
 H      0.00000   -0.78516      0.53415  
unit=angstrom
gto=6-31G
HF=yes

Next, you have to initialize the calculations using

xm.init()

You may retriece the current energy via

energy = xm.energy

obtain the current geometry using

geom = xm.get_geom()

and update the geometry to new coordinates via

xm.set_geom(new_geom)

Members:

xmol.energy

The current energy of the molecule

Methods:

xmol.init()

Initializes the xmolecule calculation. This has to be done before any other computation

xmol.mass()

returns the atomic masses as list of floats (len= 3 * number of atoms)

xmol.atom_labels()

returns the atom labels as list of strings (len= 3 * number of atoms)

xmol.ao_labels()

returns the atomic orbital labels as list of strings (len=number of basis functions)

xmol.ao_overlap()

returns basis function overlap matrix of shape (number of basis functions, number of basis functions)

xmol.get_geom()

returns the molecular geometry as list of floats len=3 * number of atoms

xmol.set_geom(new_geom)

sets the molecular geometry to new_geom, where geom is a list of floats, length 3 * number of atoms OR an array of shape (3 * number of atoms)

xmol.get_occ()

returns the occupation number as list of integers 0, 1, or 2

xmol.set_occ(new_occ)

sets the occupation number to new_occ. new_occ is a list of integers of values 0,1, or 2

xmol.mo_coef()

returns a 2-dimensional numpy array of shape (number of basis functions, number of molecular orbitals) with molecular orbital coefficients

xmol.set_mo_coef(coef)

sets the molecular orbital coefficients to the values provided by the 2-dimensional numpy array coef with shape (number of basis functions, number of molecular orbitals)

xmol.nao_conf()

returns a string describing the nao basis configuration when using numerical atomic orbitals

xmol.orbital_energies()

returns a list of orbital energies

xmol.mullikencharge()

returns the a list of floats (len=number of atoms) containing the Mulliken charge of each atom

xmol.loewdincharge()

returns the a list of floats (len=number of atoms) containing the Loewdin charge of each atom

xmol.bondorder()

returns 2-dimensional numpy array of shape (number of atoms, number of atoms) containing bondorder values.

xmol.population()

returns 2-dimensional numpy array of shape (number of orbitals, number of atoms) containing populations of each molecular orbital on respective atoms.

xmol.os()

returns oscillator strengths. Returns (osc, tdip).

• osc is a 2-dimensional numpy array of shape (number of orbitals, number of orbitals) with oscillator strengths for transitions between orbital pairs (assuming independent electrons).
• tdip is a 3-dimensional numpy array of shape (number of orbitals, number of orbitals, 3) containing the respective transition dipole matrix elements.

xmol.fluorescencerates()

returns fluorescence rates. Returns a 2-dimensional numpy array with calculated fluorescence rates for the fluorescence transitions between orbital pairs (assuming independent electrons).

xmol.process()

returns a list or process data. Each member of the list is a tuple (process_label, final_occ, value, energy_eV),

• process_label is byte-string of value b'P', b'A', or b'F', for photoionization, Auger-Meitner decay, or fluorescence, respectively,
• final_occ specifies the target electronic occupation,
• value specifcies cross section (P) or decay rate (P,A),
• energy_eV is an integer value containing the involved electronic energy difference.

xmol.gradient()

returns the gradient as array of shape (3 * number of atoms)

xmol.write_molden()

writes a molden file "xmolecule.molden"

xmol.write_density_cube()

writes a cube file "xmolecule.molden" with the electronic density

xmol.write_mo_cube(norb)

writes a cube file "mo.cube" showing the molecule orbital with integer index norb.

xmol.hole_properties()

This method returns properties assuming a vacancy otherwise closed shell configuration in a valence orbital assuming Koopmann's theorem. The method returns a tuple (occ, energy, gradient, nacs).

• occ is a numpy array of shape (number of states, len of occ) describing occupation configurations of the respective hole configuration
• energy is a numpy array of shape (number of states) with the respective Koopmann's theorem energy (E_RHF - E_orbital)
• gradient is a 2-dimensional numpy array of shape (number of states, 3 * number of atoms) containing the respective gradients
• nacs is a 3-dimensional numpy array of shape (number of states, number of states, 3 * number of atoms) containing respective non-adiabatic coupling vectors

xmol.part_properties()

This method returns properties assuming an additional electron in a virtual orbital assuming Koopmann's theorem. Returns the same as xmol.hole_properties()

xmol.CIS_energies()

returns list of CIS excited state energies

xmol.CIS_mullikenpop(state, type)

returns mulliken charge analysis for cis. state is an integer specifying the state index type is either "F", "H", "P", for full, hole, and particle analysis

xmol.CIS_loewdinpop(state, type)

returns Loewdin charge analysis for CIS. Works the same way as xmol.cis_mullikenpop(state, type)

xmol.CIS_os(state)

returns CIS oscillator strength for a given state. state specifies the state index. Returns (osc, tdip), where osc is a numpy array with oscillator strength and tdip is an array with transition dipole matrix elements shape=(number of states, 3)

xmol.CIS_energy_gradient(state)

returns gradients as numpy array of shape (3 * number of atoms) for a specific CIS state with state index state.

xmol.CIS_energy_gradient_nacs(state)

returns gradients & nacs for a specific CIS state with state index state as (energy, gradient, nacs):

• energy: numpy array of CIS excited state energies
• gradient: numpy array of shape (number of excited states, 3 * number of atoms) containing the gradients. Note that only the gradient for the desired state index is computed. All other values are zero.
• nacs: numpy array of shape (number of excited states, number of excited states, 3 * number of atoms) containing the non-adiabatic couplings. Note that only the couplings for the desired state index to other states is computed. All other values are zero.

xmol.CIS_transdens(state)

returns transition density for CIS state with state index state as numpy arrau of shape (number of basis functions, number of basis functions).

Obsolete and/or experimental methods

xmol.hole_efields()

returns hole state efields

xmol.CI_energies()

returns list of CI energies

xmol.CI_olap()

returns matrix of CI state overlaps to previous geometry

xmol.CI_Auger()

returns Auger decay rates of CI state

xmol.occ2CIstate()

returns a random state index based on probabilities from the weight on occupation number

xmol.CIstate2occ()

returns the occupation number of the dominant csf

xmol.set_multp(multp):

sets the spin multiplicity to integer value multp

xmol.set_irrep(irrep)

sets the index of the irreducible representation to integer value irrep