Update psivardefs.py

psi4/driver/qcdb/psivardefs.py

@@ -31,7 +31,28 @@
 
 def sapt_psivars():
     """Returns dictionary of PsiVariable definitions.
+    This function assembles SAPT subtotals and total energies from the fundamental SAPT variables like SAPT EXCH-DISP20 ENERGY.
+    This function pertains to wavefunction-based SAPT (not FISAPT or SAPT(DFT))
+
+    Those fundamental SAPT varliables are never scaled by any exchange scaling.  
+
+    Optionally, we can modify SAPT subtotal or total interation energies by scaling the terms that 
+    depend on the S^2 approximation.  These terms can be scaled by the ratio 
+    [(SAPT EXCH10 ENERGY) / (SAPT EXCH10(S^2) ENERGY)]^(SAPT ALPHA), where SAPT ALPHA would normally be 1.0.
+    (if SAPT EXCH10 ENERGY is < 1E-5 we set the ratio to 1).
+    In older copies of Psi4, we did this scaling (with SAPT ALPHA = 1) by default, but then we changed the default
+    to not do this scaling (this is controlled by user option EXCH_SCALE_ALPHA which is False by default, or 
+    it can be set to True to set SAPT ALPHA = 1, or it can be set to some other value to set SAPT ALPHA to that value)
 
+    SAPT EXCHSCAL1 is the above scaling ratio with SAPT ALPHA = 1
+    SAPT EXCHSCAL3 is the above scaling ratio with SAPT ALPHA = 3 (used in the so-called scaled SAPT0, or sSAPT0, which
+    we found to work better for many short-range contacts, e.g., 10.1039/c8cp02029a).  (On the other hand, we found
+    that some *very* close contacts get over-corrected by sSAPT0, e.g., the Sherrill group Splinter dataset paper 2023).
+
+    The final scale factor for S^2 dependent terms (for methods other than sSAPT0, which uses fixed SAPT EXCHSCAL3) is
+    SAPT EXCHSCAL, which is by default 1.0 (i.e., no scaling, or SAPT ALPHA = 0).
+
+    Note: SAPT HF TOTAL ENERGY is the HF *interaction* energy (like all SAPT energies)
     """
     pv1 = collections.OrderedDict()
     pv1['SAPT EXCHSCAL1'] = {'func': lambda x: 1.0 if x[0] < 1.0e-5 else x[0] / x[1], 'args': ['SAPT EXCH10 ENERGY', 'SAPT EXCH10(S^2) ENERGY']}  # special treatment in pandas