Electronic structure - VeloxChem Docs

Molecular orbitals¶

Visualization¶

The OrbitalViewer provides an interactive interface for visualizing molecular orbitals represented by a VeloxChem molecular orbital object.

Given a set of molecular orbitals, the viewer constructs three‑dimensional isodensity surfaces corresponding to selected orbitals and enables interactive inspection of their spatial characteristics. The OrbitalViewer operates directly on the orbital coefficients and basis information stored in the VeloxChem molecular orbital data structure, ensuring consistency with the underlying electronic‑structure calculation.

import veloxchem as vlx

molecule = vlx.Molecule.read_name("caffeine")
basis = vlx.MolecularBasis.read(molecule, "6-31g")

scf_drv = vlx.ScfRestrictedDriver()
scf_results = scf_drv.compute(molecule, basis)

orb_viewer = vlx.OrbitalViewer()
orb_viewer.visualize(molecule, basis, scf_drv.mol_orbs)

Figure: Interactive exploration of molecular orbitals is available through the OrbitalViewer. Here we show a representative isodensity surface generated with VeloxChem.

Localization¶

Orbital localization provides an alternative representation of the electronic structure in which molecular orbitals are transformed to maximize their spatial compactness or chemical interpretability, while preserving the span of the underlying orbital subspace. Localized orbitals are widely used for qualitative chemical analysis, construction of local correlation methods, and interpretation of bonding patterns in complex molecular systems.

In VeloxChem, localization is performed through unitary rotations of selected orbitals obtained from a prior electronic structure calculation. The default selection is the set of occupied orbitals, but it can alternatively be set with the keyword argument mo_range of the compute method.

The program implements the Boys and Pipek–Mezey localization schemes, which respectively optimize spatial localization and atomic charge separation criteria. Pipek–Mezey is the default choice but it can be changed to “boys” with the method attribute. For Pipek–Mezey in addition, a choice of projector can be made; the alternative to the default setting of “mulliken” is “lowdin”.

import veloxchem as vlx

molecule = vlx.Molecule.read_name("ethylene")
basis = vlx.MolecularBasis.read(molecule, "cc-pvdz")

scf_drv = vlx.ScfRestrictedDriver()
scf_results = scf_drv.compute(molecule, basis)

loc_drv = vlx.OrbitalLocalizationDriver()

loc_drv.method = "pm"  # this is default
loc_drv.pm_projector = "mulliken"  # this is default

loc_results = loc_drv.compute(molecule, basis, scf_results)

Reading ethylene from PubChem...

Reference: S. Kim, J. Chen, T. Cheng, A. Gindulyte, J. He, S. He, Q. Li, B. A. Shoemaker, P. A. Thiessen, B. Yu, L. Zaslavsky, J. Zhang, E. E. Bolton, Nucleic Acids Res., 2025, 53, D1516-D1525.

Please double-check the compound since names may refer to more than one record.

                                                                                                                          
                                            Self Consistent Field Driver Setup                                            
                                           ====================================                                           
                                                                                                                          
                   Wave Function Model             : Spin-Restricted Hartree-Fock                                         
                   Initial Guess Model             : Superposition of Atomic Densities                                    
                   Convergence Accelerator         : Two Level Direct Inversion of Iterative Subspace                     
                   Max. Number of Iterations       : 50                                                                   
                   Max. Number of Error Vectors    : 10                                                                   
                   Convergence Threshold           : 1.0e-06                                                              
                   ERI Screening Threshold         : 1.0e-12                                                              
                   Linear Dependence Threshold     : 1.0e-06                                                              
                                                                                                                          
* Info * Starting Reduced Basis SCF calculation...                                                                        
* Info * ...done. SCF energy in reduced basis set: -78.004791675958 a.u. Time: 0.26 sec.                                  
                                                                                                                          
                                                                                                                          
               Iter. | Hartree-Fock Energy | Energy Change | Gradient Norm | Max. Gradient | Density Change               
               --------------------------------------------------------------------------------------------               
                  1       -78.038624215446    0.0000000000      0.09007414      0.01191518      0.00000000                
                  2       -78.039593268576   -0.0009690531      0.01467490      0.00275829      0.03530952                
                  3       -78.039623063751   -0.0000297952      0.00331955      0.00065258      0.00399681                
                  4       -78.039625410293   -0.0000023465      0.00051324      0.00008713      0.00141058                
                  5       -78.039625489440   -0.0000000791      0.00009013      0.00001628      0.00029308                
                  6       -78.039625492061   -0.0000000026      0.00001191      0.00000264      0.00006840                
                  7       -78.039625492103   -0.0000000000      0.00000072      0.00000009      0.00000869                
                                                                                                                          
               *** SCF converged in 7 iterations. Time: 0.42 sec.                                                         
                                                                                                                          
               Spin-Restricted Hartree-Fock:                                                                              
               -----------------------------                                                                              
               Total Energy                       :      -78.0396254921 a.u.                                              
               Electronic Energy                  :     -111.4540390298 a.u.                                              
               Nuclear Repulsion Energy           :       33.4144135377 a.u.                                              
               ------------------------------------                                                                       
               Gradient Norm                      :        0.0000007154 a.u.                                              
                                                                                                                          
                                                                                                                          
               Ground State Information                                                                                   
               ------------------------                                                                                   
               Charge of Molecule            :  0.0                                                                       
               Multiplicity (2S+1)           :  1                                                                         
               Magnetic Quantum Number (M_S) :  0.0                                                                       
                                                                                                                          
* Info * PM converged after   5  iterations

The results dictionary of the orbital localization driver contains the localized orbitals in the form of a VeloxChem object that can be passed to the orbital viewer for visual inspection.

orb_viewer = vlx.OrbitalViewer()
orb_viewer.visualize(molecule, basis, loc_results["loc_orbs"])

Figure: One of the occupied localized sp2-hybridized orbitals resulting from a localization performed with the Pipek–Mezey scheme using the Mulliken projector.