4. Electronic wavefunction API

4.1. Electronic Wavefunctions

class moldesign.orbitals.wfn.ElectronicWfn(mol, num_electrons, model=None, aobasis=None, fock_ao=None, positions=None, civectors=None, description=None, density_matrix_ao=None)[source]

Stores the results of a quantum chemistry calculation.

This is necessarily pretty flexible, but generally stores an LCAO wfn and one or more sets of orbitals. Can also store CI vectors, etc.

These objects will usually be created by quantum chemical energy models.

  • mol (moldesign.Molecule) – Molecule this wavefunction belongs to
  • num_electrons (int) – number of electrons in this wavefunction
  • model (moldesign.models.base.EnergyModelBase) – The model this wavefunction was created with
  • aobasis (moldesign.orbitals.BasisSet) – The basis functions for the enclosed orbitals
  • nbasis (int) – number of AO basis functions
  • fock_ao (moldesign.units.Array[energy]) – fock matrix in the AO basis
  • positions (moldesign.units.Array[length]) – positions of the nuclei for this wfn
  • civectors (np.ndarray) – CI vectors (if applicable)
  • description (str) – text describing the wfn (e.g. ‘RHF/STO-3G’, ‘CAS(2,2)/SA3/6-31G**’)
  • density_matrix_ao (np.ndarray) – density matrix in the ao basis
align_orbital_phases(other, assert_same=True)[source]

Align this wavefunction’s orbitals to have the same phase as those in other. :type other: ElectronicWfn :param assert_same: raise an exception if the two wavefunctions do not have the same kinds of orbitals


A synonym for self.orbitals[‘canonical’], since this is usually what’s wanted

4.2. Molecular Orbital Sets

class moldesign.orbitals.orbitals.MolecularOrbitals(orbitals, wfn=None, basis=None, canonical=False, orbtype=None)[source]

Stores a wfn of molecular orbitals in an AO wfn Orbitals are accessed as orbs[orbital index, ao index]

align_phases(other, threshold=0.5, assert_same_type=True)[source]

Flip the signs of these orbitals to bring them into maximum coincidence with another set of orbitals

  • other (MolecularOrbitals) – the “reference” set of orbitals to match phases with
  • threshold (float) – only flip orbital if the overlap is less than -1*threshold
  • assert_same_type (bool) – require that self.orbtype == other.orbtype


This function assumes that the overlap matrix is the same for both sets of orbitals - this is a reasonable assumption if the two sets of orbitals were calculated at very similar molecular geometries.


u.Vector[energy] – energies of the molecular orbitals

This is just the diagonal of the fock matrix


u.Array[energy] – Fock matrix for these orbitals


Transform an operator into this orbital basis from the ao basis

Given the matrix elements :math:`hat O_{mu
u}` of an operator over AO basis indices
u`, returns the operator’s matrix elements \(\hat O_{ij}\) over

orbital indices \(i,j\):

hat O_{ij} =
left langle i

ight| hat O left| j ight angle =


u}C_{i mu} O_{mu u} C_{j u}

where \(C_{i \mu}\) is the expansion coefficient for AO basis function \(\mu\) in molecular orbital _i_.

ao_operator (u.Array): matrix elements of the operator in the ao basis
u.Array: matrix elements of the operator in this orbital basis
Assumes that this set of orbitals is orthogonal

u.Array[energy] – 1-electron matrix elements for these orbitals


u.Array[energy] – 2-electron matrix elements for these orbitals


np.ndarray – orbital occupation numbers


Calculate overlaps between this and another set of orbitals

Parameters:other (MolecularOrbitals) –
Returns:overlaps between the two sets of orbitals
Return type:numpy.ndarray


>>> canonical = mol.wfn.canonical
>>> atomic = mol.wfn.basis
>>> overlaps = canonical.overlap(atomic)
>>> overlaps[i, j] == canonical.orbitals[i].overlap(atomic.orbitals[j])

np.array – overlap matrix for these orbitals


Transform an operator from this orbital basis into the AO basis

Given the matrix elements \(\hat O_{ij}\) of an operator over orbital basis indices \(i,j\), returns the operator’s matrix elements :math:`hat O_{mu
u}` over
orbital indices :math:`mu,


hat O_{mu
u} =
left langle mu

ight| hat O left| u ight angle =

sum_{i,j,lambda,kappa}S_{mu lambda} C_{i lambda} O_{ij} C_{j kappa} S_{kappa


where :math:`S_{mu

u} = left langle mu | u ight angle` is the AO overlap matrix

and \(C_{i \mu}\) is the expansion coefficient for AO basis function \(\mu\) in molecular orbital _i_.

mo_operator (u.Array): matrix elements of the operator in this orbital basis
u.Array: matrix elements of the operator in the AO basis

4.3. Electronic Orbitals

class moldesign.orbitals.orbitals.Orbital(coeffs, basis=None, wfn=None, occupation=None, name='unnamed')[source]

Stores a single orbital and its meta-data Generally wants to be part of a set of MolecularOrbitals

The orbital is defined as .. math:

\left| i \right \rangle = \sum_\mu c_{i \mu} \left| \mu \right \rangle

where the coefficients \(c_{i \mu}\) are stored in self.coeffs and the basis orbitals \(\left| \mu \right \rangle\) are stored at self.basis


u.Scalar[energy] – This orbital’s energy


This is equivalent to self.fock(self)


Calculate fock matrix element with another orbital

Parameters:other (Orbital) – calculate the fock element with this orbital
Returns:fock matrix element
Return type:u.Scalar[energy]

Calculate overlap with another orbital

Parameters:other (Orbital) – calculate the overlap with this orbital
Returns:orbital overlap
Return type:float