exatomic.core.orbital module

Orbital DataFrame

Orbital information. All of the dataframe structures and functions associated with the results of a quantum chemical calculation. The Orbital table itself summarizes information such as centers and energies. The Excitation table collects information about orbital excitations from time-dependent calculations. The convolve() bound method can be used to generate photoelectron spectroscopy and absorbance spectra.

The MOMatrix table contains a C matrix as it is presented in quantum textbooks, stored in a columnar format. The bound method square() returns the matrix as one would write it out. This table should have dimensions N_basis_functions * N_basis_functions. The DensityMatrix table stores a triangular matrix in columnar format and contains a similar square() method to return the matrix as we see it on a piece of paper.

class exatomic.core.orbital.Orbital(*args, **kwargs)

Bases: _Convolve

Column	Type	Description
frame	category	non-unique integer (req.)
group	category	like frame but for same geometry
orbital	int	vector of MO coefficient matrix
label	int	label of orbital
occupation	float	population of orbital
energy	float	eigenvalue of orbital eigenvector
symmetry	str	symmetry designation (if applicable)
x	float	orbital center in x
y	float	orbital center in y
z	float	orbital center in z

Note

Spin zero means alpha spin or unknown and spin one means beta spin.

get_orbital(orb=-1, spin=0, orbocc='occupation', index=None, group=None, frame=None)

Returns a specific orbital.

Parameters:

• orb (int) – See note below (default HOMO)

• spin (int) – 0, no spin or alpha (default); 1, beta

• index (int) – Orbital dataframe index (default None)

• frame (int) – The frame of the universe (default max(frame))

• group (int) – The group of orbitals within a given frame

• orbocc (str) – column of occupations (default ‘occupation’)

Returns:

slc (pd.Series) – row of the Orbital table

Note

If the index is not known (usually), but a criterion such as (HOMO or LUMO) is desired, use the orb and spin criteria. Negative orb values are occupied, positive are unoccupied. So -1 returns the HOMO, -2 returns the HOMO-1; 0 returns the LUMO, 1 returns the LUMO+1, etc.

active_orbitals(orbocc='occupation', maxocc=1.985, minocc=0.015, irrep=None)

Returns a slice of the orbital table containing so-called active orbitals (defined here as orbitals with occupations between minocc and maxocc).

Parameters:

• orbocc (str) – column name of occupation numbers in uni.orbital

• maxocc (float) – maximum occupation to be considered active

• minocc (float) – minimum occupation to be considered active

• irrep (int) – irreducible representation

Returns:

slc (pd.DataFrame) – active orbitals in the Orbital table

classmethod from_energies(energies, alphae, betae, os=False)

Convenience method to generate the Orbital table from an array of orbital energies and the number of alpha and beta electrons.

Parameters:

• energies (np.ndarray) – orbital energies

• alphae (int) – number of alpha electrons

• betae (int) – number of beta electrons

• os (bool) – open shell

Returns:

orb (~:class:exatomic.core.orbital.Orbital) – the Orbital table

classmethod from_occupation_vector(occvec, os=False)

Convenience method to generate the Orbital table from an array of occupation numbers.

Parameters:

• energies (np.ndarray) – orbital energies

• os (bool) – open shell

Returns:

orb (~:class:exatomic.core.orbital.Orbital) – the Orbital table

class exatomic.core.orbital.Excitation(*args, **kwargs)

Bases: _Convolve

Column	Type	Description
energy	float	excitation energy in Ha
irrep	str	irreducible representation of excitation
osc	float	oscillator strength (length repr.)
occ	int	occupied orbital of excitation
virt	int	virtual orbital of excitation
occsym	str	occupied orbital symmetry
virtsym	str	virtual orbital symmetry
frame	int	non-unique integer (req.)
group	int	like frame but for same geometry

classmethod from_universe(uni, initial=None, final=None, spin=0)

Generate the zeroth order approximation to excitation energies via the transition dipole method (provided a universe contains an MOMatrix and dipole moment integrals already).

class exatomic.core.orbital.MOMatrix(*args, **kwargs)

Bases: DataFrame

The MOMatrix is the result of solving a quantum mechanical eigenvalue problem in a finite basis set. Individual columns are eigenfunctions of the Fock matrix with eigenvalues corresponding to orbital energies.

\[C^{*}SC = 1\]

Column	Type	Description
chi	int	row of MO coefficient matrix
orbital	int	vector of MO coefficient matrix
coef	float	weight of basis_function in MO
frame	category	non-unique integer (req.)

contributions(orbital, mocoefs='coef', tol=0.01, frame=0)

Returns a slice containing all non-negligible basis function contributions to a specific orbital.

Args

orbital (int): orbital index

square(frame=0, column='coef', mocoefs=None, irrep=None)

Returns a square dataframe corresponding to the canonical C matrix representation.

class exatomic.core.orbital.DensityMatrix(*args, **kwargs)

Bases: DataFrame

The density matrix in a contracted basis set. As it is square symmetric, only n_basis_functions * (n_basis_functions + 1) / 2 rows are stored.

Column	Type	Description
chi0	int	first index in matrix
chi1	int	second index in matrix
coef	float	overlap matrix element
frame	category	non-unique integer (req.)

square(frame=0)

Returns a square dataframe of the density matrix.

classmethod from_momatrix(momatrix, occvec, mocoefs='coef')

A density matrix can be constructed from an MOMatrix by: .. math:

D_{uv} = \sum_{i}^{N} C_{ui} C_{vi} n_{i}

Parameters:

• momatrix (MOMatrix) – a C matrix

• occvec (array or similar) – vector of len(C.shape[0]) containing the occupations of each molecular orbital.

Returns:

ret (DensityMatrix) – The density matrix

classmethod from_universe(uni, mocoefs, orbocc)

The density matrix is defined as: .. math:

D_{uv} = \sum_{i}^{N} C_{ui} C_{vi} n_{i}

Parameters:

• uni (Universe) – a universe containing momatrix and orbital

• mocoefs (str) – column name of C matrix in uni.momatrix

• orbocc (str) – column name of occupation vector in uni.orbital

Returns:

ret (DensityMatrix) – The density matrix