Complete Basis Set¶

Code author: Lori A. Burns, Daniel G. A. Smith and Peter Kraus

Section author: Lori A. Burns and Peter Kraus

The psi4.driver.cbs() function described below is powerful but complicated, requiring many options. For most common calculations, a shorthand can be accessed directly though psi4.driver.energy(), psi4.driver.gradient(), etc. For example, a MP2 single-point DT extrapolation can be accessed through the first item below more conveniently than the equivalent second or third items.

energy('mp2/cc-pv[dt]z')
energy("cbs", corl_wfn='mp2', corl_basis='cc-pv[dt]z')
energy("cbs", cbs_metadata=[{"wfn": "hf", "basis": "cc-pvtz"}, {"wfn": "mp2", "basis": "cc-pv[dt]z", "scheme": "corl_xtpl_helgaker_2"}])

Caution

In PSI4 previous to Spring 2022 and v1.6, calling certain cbs-related functions like the above looked like

energy(cbs, corl_wfn='mp2', corl_basis='cc-pv[dt]z')

energy(cbs, cbs_metadata=[{"wfn": "hf", "basis": "cc-pvtz"}, {"wfn": "mp2", "basis": "cc-pv[dt]z", "scheme": corl_xtpl_helgaker_2}])

The difference is that the main function psi4.driver.cbs() and extrapolation schemes like psi4.driver.driver_cbs_helper.xtpl_highest_1() and psi4.driver.driver_cbs_helper.scf_xtpl_helgaker_2() and composite aliases like psi4.driver.aliases.sherrill_gold_standard() and psi4.driver.aliases.allen_focal_point() in the old way passed the Python function directly, whereas the new way uses the string of the function name.

A CCSD(T) DT coupled-cluster correction atop a TQ MP2 extrapolation geometry optimization can also be accessed through the first item below more conveniently than the equivalent second and third items.

optimize('mp2/cc-pv[tq]z + D:ccsd(t)/cc-pvdz')
optimize("cbs", corl_wfn='mp2', corl_basis='cc-pv[tq]z', delta_wfn='ccsd(t)', delta_basis='cc-pvdz')
optimize("cbs", cbs_metadata=[{"wfn": "hf", "basis": "cc-pvqz"}, {"wfn": "mp2", "basis": "cc-pv[tq]z"}, {"wfn": "ccsd(t)", "basis": "cc-pvdz"}])

Many examples can be found at cbs-xtpl-energy, cbs-xtpl-gradient, cbs-xtpl-opt, cbs-xtpl-freq, cbs-xtpl-func, cbs-xtpl-wrapper, cbs-xtpl-dict.

psi4.cbs(name[, scf_basis, scf_scheme, corl_wfn, corl_basis, corl_scheme, delta_wfn, delta_wfn_lesser, delta_basis, delta_scheme, delta2_wfn, delta2_wfn_lesser, delta2_basis, delta2_scheme, cbs_metadata])[source]

Function to define a multistage energy method from combinations of basis set extrapolations and delta corrections and condense the components into a minimum number of calculations.

Aliases:: complete_basis_set()
Returns:: (float) – Total electronic energy in Hartrees
PSI variables:

Caution

Some features are not yet implemented. Buy a developer a coffee.

No way to tell function to boost fitting basis size for all calculations.
Need to add more extrapolation schemes

As represented in the equation below, a CBS energy method is defined in several sequential stages (scf, corl, delta1, delta2, … ) covering treatment of the reference total energy, the correlation energy, a delta correction to the correlation energy, and a second delta correction, etc.. Each is activated by its stage_wfn keyword, or as a field in the `cbs_metadata` list, and is only allowed if all preceding stages are active.

\[E_{\text{total}}^{\text{CBS}} = \mathcal{F}_{\textbf{scf_scheme}} \left(E_{\text{total},\; \text{SCF}}^{\textbf{scf_basis}}\right) \; + \mathcal{F}_{\textbf{corl_scheme}} \left(E_{\text{corl},\; \textbf{corl_wfn}}^{\textbf{corl_basis}}\right) \; + \delta_{\textbf{delta_wfn_lesser}}^{\textbf{delta_wfn}} \; + \delta_{\textbf{delta2_wfn_lesser}}^{\textbf{delta2_wfn}} \; + \delta_{\textbf{delta3_wfn_lesser}}^{\textbf{delta3_wfn}} \; + \delta_{\textbf{delta4_wfn_lesser}}^{\textbf{delta4_wfn}} \; + \delta_{\textbf{delta5_wfn_lesser}}^{\textbf{delta5_wfn}}\]

Here, \(\mathcal{F}\) is an energy or energy extrapolation scheme, and the following also hold.

\[\delta_{\textbf{delta_wfn_lesser}}^{\textbf{delta_wfn}} \; = \mathcal{F}_{\textbf{delta_scheme}} \left(E_{\text{corl},\; \textbf{delta_wfn}}^{\textbf{delta_basis}}\right) - \mathcal{F}_{\textbf{delta_scheme}} \left(E_{\text{corl},\; \textbf{delta_wfn_lesser}}^{\textbf{delta_basis}}\right)\]

\[\delta_{\textbf{delta2_wfn_lesser}}^{\textbf{delta2_wfn}} \; = \mathcal{F}_{\textbf{delta2_scheme}} \left(E_{\text{corl},\; \textbf{delta2_wfn}}^{\textbf{delta2_basis}}\right) - \mathcal{F}_{\textbf{delta2_scheme}} \left(E_{\text{corl},\; \textbf{delta2_wfn_lesser}}^{\textbf{delta2_basis}}\right)\]

\[\delta_{\textbf{delta3_wfn_lesser}}^{\textbf{delta3_wfn}} \; = \mathcal{F}_{\textbf{delta3_scheme}} \left(E_{\text{corl},\; \textbf{delta3_wfn}}^{\textbf{delta3_basis}}\right) - \mathcal{F}_{\textbf{delta3_scheme}} \left(E_{\text{corl},\; \textbf{delta3_wfn_lesser}}^{\textbf{delta3_basis}}\right)\]

\[\delta_{\textbf{delta4_wfn_lesser}}^{\textbf{delta4_wfn}} \; = \mathcal{F}_{\textbf{delta4_scheme}} \left(E_{\text{corl},\; \textbf{delta4_wfn}}^{\textbf{delta4_basis}}\right) - \mathcal{F}_{\textbf{delta4_scheme}} \left(E_{\text{corl},\; \textbf{delta4_wfn_lesser}}^{\textbf{delta4_basis}}\right)\]

\[\delta_{\textbf{delta5_wfn_lesser}}^{\textbf{delta5_wfn}} \; = \mathcal{F}_{\textbf{delta5_scheme}} \left(E_{\text{corl},\; \textbf{delta5_wfn}}^{\textbf{delta5_basis}}\right) - \mathcal{F}_{\textbf{delta5_scheme}} \left(E_{\text{corl},\; \textbf{delta5_wfn_lesser}}^{\textbf{delta5_basis}}\right)\]

A translation of this ungainly equation to example [5] below is as follows. In words, this is a double- and triple-zeta 2-point Helgaker-extrapolated CCSD(T) coupled-cluster correlation correction appended to a triple- and quadruple-zeta 2-point Helgaker-extrapolated MP2 correlation energy appended to a SCF/aug-cc-pVQZ reference energy.

\[E_{\text{total}}^{\text{CBS}} = \mathcal{F}_{\text{highest_1}} \left(E_{\text{total},\; \text{SCF}}^{\text{aug-cc-pVQZ}}\right) \; + \mathcal{F}_{\text{corl_xtpl_helgaker_2}} \left(E_{\text{corl},\; \text{MP2}}^{\text{aug-cc-pV[TQ]Z}}\right) \; + \delta_{\text{MP2}}^{\text{CCSD(T)}}\]

\[\delta_{\text{MP2}}^{\text{CCSD(T)}} \; = \mathcal{F}_{\text{corl_xtpl_helgaker_2}} \left(E_{\text{corl},\; \text{CCSD(T)}}^{\text{aug-cc-pV[DT]Z}}\right) - \mathcal{F}_{\text{corl_xtpl_helgaker_2}} \left(E_{\text{corl},\; \text{MP2}}^{\text{aug-cc-pV[DT]Z}}\right)\]

Energy Methods

The presence of a stage_wfn keyword is the indicator to incorporate (and check for stage_basis and stage_scheme keywords) and compute that stage in defining the CBS energy.

The cbs() function requires, at a minimum, name='scf' and scf_basis keywords to be specified for reference-step only jobs and name and corl_basis keywords for correlated jobs.

The following energy methods have been set up for cbs().

scf
hf
mp2
mp2.5
mp3
mp4(sdq)
mp4
mpn

omp2
omp2.5
omp3
olccd
lccd
lccsd
cepa(0)
cepa(1)

cepa(3)
acpf
aqcc
qcisd
cc2
ccsd
fno-ccsd
bccd

cc3
qcisd(t)
ccsd(t)
fno-ccsd(t)
bccd(t)
cisd
cisdt

cisdtq
cin
fci
mrccsd
mrccsd(t)
mrccsdt
mrccsdt(q)

Parameters:

name (str) –
'scf' || 'ccsd' || etc.

First argument, usually unlabeled. Indicates the computational method for the correlation energy, unless only reference step to be performed, in which case should be 'scf'. Overruled if stage_wfn keywords supplied.
scf_wfn (str) –
\(\Rightarrow\) 'scf' \(\Leftarrow\) || 'c4-scf' || etc.

Indicates the energy method for which the reference energy is to be obtained. Generally unnecessary, as ‘scf’ is the scf in PSI4 but can be used to direct lone scf components to run in PSI4 or Cfour in a mixed-program composite method.
corl_wfn (str) –
'mp2' || 'ccsd(t)' || etc.

Indicates the energy method for which the correlation energy is to be obtained. Can also be specified with name or as the unlabeled first argument to the function.
delta_wfn (str) –
'ccsd' || 'ccsd(t)' || etc.

Indicates the (superior) energy method for which a delta correction to the correlation energy is to be obtained.
delta_wfn_lesser (str) –
\(\Rightarrow\) corl_wfn \(\Leftarrow\) || 'mp2' || etc.

Indicates the inferior energy method for which a delta correction to the correlation energy is to be obtained.
delta2_wfn (str) –
'ccsd' || 'ccsd(t)' || etc.

Indicates the (superior) energy method for which a second delta correction to the correlation energy is to be obtained.
delta2_wfn_lesser (str) –
\(\Rightarrow\) delta_wfn \(\Leftarrow\) || 'ccsd(t)' || etc.

Indicates the inferior energy method for which a second delta correction to the correlation energy is to be obtained.

Basis Sets
Currently, the basis set set through set commands have no influence on a cbs calculation.

Parameters:

scf_basis (basis string) –
\(\Rightarrow\) corl_basis \(\Leftarrow\) || 'cc-pV[TQ]Z' || 'jun-cc-pv[tq5]z' || '6-31G*' || etc.

Indicates the sequence of basis sets employed for the reference energy. If any correlation method is specified, scf_basis can default to corl_basis.
corl_basis (basis string) –
'cc-pV[TQ]Z' || 'jun-cc-pv[tq5]z' || '6-31G*' || etc.

Indicates the sequence of basis sets employed for the correlation energy.
delta_basis (basis string) –
'cc-pV[TQ]Z' || 'jun-cc-pv[tq5]z' || '6-31G*' || etc.

Indicates the sequence of basis sets employed for the delta correction to the correlation energy.
delta2_basis (basis string) –
'cc-pV[TQ]Z' || 'jun-cc-pv[tq5]z' || '6-31G*' || etc.

Indicates the sequence of basis sets employed for the second delta correction to the correlation energy.

Schemes
Transformations of the energy through basis set extrapolation for each stage of the CBS definition. A complaint is generated if number of basis sets in stage_basis does not exactly satisfy requirements of stage_scheme. An exception is the default, 'xtpl_highest_1', which uses the best basis set available. See Extrapolation Schemes for all available schemes.

Parameters:

scf_scheme (str) –
\(\Rightarrow\) 'xtpl_highest_1' \(\Leftarrow\) || 'scf_xtpl_helgaker_3' || etc.

Indicates the basis set extrapolation scheme to be applied to the reference energy. Defaults to scf_xtpl_helgaker_3() if three valid basis sets present in psi4.driver.driver_cbs.scf_basis, scf_xtpl_helgaker_2() if two valid basis sets present in scf_basis, and xtpl_highest_1() otherwise.
xtpl_highest_1()

scf_xtpl_helgaker_3()

scf_xtpl_helgaker_2()

scf_xtpl_truhlar_2()

scf_xtpl_karton_2()
corl_scheme (str) –
\(\Rightarrow\) 'xtpl_highest_1' \(\Leftarrow\) || 'corl_xtpl_helgaker_2' || etc.

Indicates the basis set extrapolation scheme to be applied to the correlation energy. Defaults to corl_xtpl_helgaker_2() if two valid basis sets present in corl_basis and xtpl_highest_1() otherwise.
xtpl_highest_1()

corl_xtpl_helgaker_2()
delta_scheme (str) –
\(\Rightarrow\) 'xtpl_highest_1' \(\Leftarrow\) || 'corl_xtpl_helgaker_2' || etc.

Indicates the basis set extrapolation scheme to be applied to the delta correction to the correlation energy. Defaults to corl_xtpl_helgaker_2() if two valid basis sets present in delta_basis and xtpl_highest_1() otherwise.
xtpl_highest_1()

corl_xtpl_helgaker_2()
delta2_scheme (str) –
\(\Rightarrow\) 'xtpl_highest_1' \(\Leftarrow\) || 'corl_xtpl_helgaker_2' || etc.

Indicates the basis set extrapolation scheme to be applied to the second delta correction to the correlation energy. Defaults to corl_xtpl_helgaker_2() if two valid basis sets present in delta2_basis and xtpl_highest_1() otherwise.
xtpl_highest_1()

corl_xtpl_helgaker_2()
scf_alpha (float) –
\(\Rightarrow\) 1.63 \(\Leftarrow\)

Overrides the default alpha parameter used in the listed SCF extrapolation procedures. Has no effect on others, including xtpl_highest_1() and scf_xtpl_helgaker_3().
scf_xtpl_helgaker_2()

scf_xtpl_truhlar_2()

scf_xtpl_karton_2()
corl_alpha (float) –
\(\Rightarrow\) 3.00 \(\Leftarrow\)

Overrides the default alpha parameter used in the listed corl_xtpl_helgaker_2() correlation extrapolation to the corl stage. The supplied alpha does not impact delta or any further stages.
corl_xtpl_helgaker_2()
delta_alpha (float) –
\(\Rightarrow\) 3.00 \(\Leftarrow\)

Overrides the default alpha parameter used in the listed corl_xtpl_helgaker_2() correlation extrapolation for the delta correction. Useful when delta correction is performed using smaller basis sets for which a different alpha might be more appropriate.
corl_xtpl_helgaker_2()

Combined interface

Parameters:

cbs_metadata (List[Dict]) –

\(\Rightarrow\) autogenerated from above keywords \(\Leftarrow\) || [{"wfn": "hf", "basis": "cc-pv[TQ5]z"}] || etc.

This is the interface to which all of the above calls are internally translated. The first item in the array is always defining the SCF contribution to the total energy. The required items in the dictionary are:

`wfn`: typically `HF`, which is subsumed in correlated methods anyway.
`basis`: basis set, can be in a bracketed form (eg. `cc-pv[tq]z`)

Other supported arguments for the first dictionary are:

`scheme`: scf extrapolation scheme function, by default it is worked out from the number of basis sets (1 - 3) supplied as `basis`.
`alpha`: alpha for the above scheme, if the default is to be overriden
`options`: if special options are required for a step, they should be entered as a dict here. If some options should be used for both parts of the stage, they should be entered in both `options` and `options_lo`. This is helpful for calculating all electron corrections in otherwise frozen core calculations, or relativistic (DKH) Hamiltionian corrections for otherwise nonrelativistic.
`options_lo`: special options for lower method in a given stage. This is useful to calculate a direct stage in an otherwise density-fitted calculation, or similar.
`treatment`: treat extrapolation stage as `scf` or `corl`, by default only the first stage is `scf` and every later one is `corl`.
`stage`: tag for the stage used in tables.

The next items in the `cbs_metadata` array extrapolate correlation. All of the above parameters are available, with only the `wfn` and `basis` keywords required. Other supported parameters are:

`wfn_lo`: the lower method from which the delta correction is to be calculated. By default, it is set to `wfn` from the previous field in the `cbs_metadata` array.
`basis_lo`: basis set to be used for the delta correction. By default, it is the same as the `basis` specified above.

Others

Parameters:

molecule (molecule) –

h2o || etc.

The target molecule, if not the last molecule defined.

Examples:

>>> # [1] replicates with cbs() the simple model chemistry scf/cc-pVDZ: set basis cc-pVDZ energy('scf')
>>> energy(cbs, scf_wfn='scf', scf_basis='cc-pVDZ')

>>> # [2] replicates with cbs() the simple model chemistry mp2/jun-cc-pVDZ: set basis jun-cc-pVDZ energy('mp2')
>>> energy(cbs, corl_wfn='mp2', corl_basis='jun-cc-pVDZ')

>>> # [3] DTQ-zeta extrapolated scf reference energy
>>> energy('cbs', scf_wfn='scf', scf_basis='cc-pV[DTQ]Z', scf_scheme='scf_xtpl_helgaker_3')

>>> # [4] DT-zeta extrapolated mp2 correlation energy atop a T-zeta reference
>>> energy('cbs', corl_wfn='mp2', corl_basis='cc-pv[dt]z', corl_scheme='corl_xtpl_helgaker_2')

>>> # [5] a DT-zeta extrapolated coupled-cluster correction atop a TQ-zeta extrapolated mp2 correlation energy atop a Q-zeta reference (both equivalent)
>>> energy('cbs', corl_wfn='mp2', corl_basis='aug-cc-pv[tq]z', delta_wfn='ccsd(t)', delta_basis='aug-cc-pv[dt]z')
>>> energy('cbs', corl_wfn='mp2', corl_basis='aug-cc-pv[tq]z', corl_scheme='corl_xtpl_helgaker_2', delta_wfn='ccsd(t)', delta_basis='aug-cc-pv[dt]z', delta_scheme='corl_xtpl_helgaker_2')

>>> # [6] a D-zeta ccsd(t) correction atop a DT-zeta extrapolated ccsd cluster correction atop a TQ-zeta extrapolated mp2 correlation energy atop a Q-zeta reference
>>> energy('cbs', corl_wfn='mp2', corl_basis='aug-cc-pv[tq]z', corl_scheme=corl_xtpl_helgaker_2, delta_wfn='ccsd', delta_basis='aug-cc-pv[dt]z', delta_scheme='corl_xtpl_helgaker_2', delta2_wfn='ccsd(t)', delta2_wfn_lesser='ccsd', delta2_basis='aug-cc-pvdz')

>>> # [7] a Q5-zeta MP2 calculation, corrected by CCSD(T) at the TQ-zeta extrapolated level, and all-electron CCSD(T) correlation at T-zeta level
>>> energy(cbs, cbs_metadata=[{"wfn": "hf", "basis": "cc-pv5z"}, {"wfn": "mp2", "basis": "cc-pv[q5]z"}, {"wfn": "ccsd(t)", "basis": "cc-pv[tq]z"}, {"wfn": "ccsd(t)", "basis": "cc-pvtz", "options": {"freeze_core": "False"}}])

>>> # [8] cbs() coupled with database()
>>> TODO database('mp2', 'BASIC', subset=['h2o','nh3'], symm='on', func=cbs, corl_basis='cc-pV[tq]z', corl_scheme='corl_xtpl_helgaker_2', delta_wfn='ccsd(t)', delta_basis='sto-3g')

>>> # [9] cbs() coupled with optimize()
>>> TODO optimize('mp2', corl_basis='cc-pV[DT]Z', corl_scheme='corl_xtpl_helgaker_2', func=cbs)

Note

As of October 2018, only two explicit `deltaN_[wfn,basis,scheme]` sets of options are active; if more delta functions are required, use the `cbs_metadata` interface. Also, temporarily extrapolations are performed on differences of target and scf total energies, rather than on correlation energies directly. This doesn’t affect the extrapolated values of the particular formulas defined here (though it does affect the betas, which are commented out), but it is sloppy and temporary and could affect any user-defined corl extrapolations.

Output¶

At the beginning of a cbs() job is printed a listing of the individual energy calculations which will be performed. The output snippet below is from the example job [2] above. It shows first each model chemistry needed to compute the aggregate model chemistry requested through cbs(). Then, since, for example, an energy('ccsd(t)') yields CCSD(T), CCSD, MP2, and SCF energy values, the wrapper condenses this task list into the second list of minimum number of calculations which will actually be run.

Naive listing of computations required.
        scf / aug-cc-pvqz              for  SCF TOTAL ENERGY
        mp2 / aug-cc-pvtz              for  MP2 CORRELATION ENERGY
        mp2 / aug-cc-pvqz              for  MP2 CORRELATION ENERGY
    ccsd(t) / aug-cc-pvdz              for  CCSD(T) CORRELATION ENERGY
    ccsd(t) / aug-cc-pvtz              for  CCSD(T) CORRELATION ENERGY
        mp2 / aug-cc-pvdz              for  MP2 CORRELATION ENERGY
        mp2 / aug-cc-pvtz              for  MP2 CORRELATION ENERGY

Enlightened listing of computations required.
        mp2 / aug-cc-pvqz              for  MP2 CORRELATION ENERGY
    ccsd(t) / aug-cc-pvdz              for  CCSD(T) CORRELATION ENERGY
    ccsd(t) / aug-cc-pvtz              for  CCSD(T) CORRELATION ENERGY

At the end of a cbs() job is printed a summary section like the one below. First, in the components section, are listed the results for each model chemistry available, whether required for the cbs job (*) or not. Next, in the stages section, are listed the results for each extrapolation. The energies of this section must be dotted with the weightings in column Wt to get the total cbs energy. Finally, in the CBS section, are listed the results for each stage of the cbs procedure. The stage energies of this section sum outright to the total cbs energy.

==> Components <==

----------------------------------------------------------------------------------
               Method / Basis            Rqd   Energy [H]   Variable
----------------------------------------------------------------------------------
                  scf / aug-cc-pvqz        *  -1.11916375   SCF TOTAL ENERGY
                  mp2 / aug-cc-pvqz        *  -0.03407997   MP2 CORRELATION ENERGY
                  scf / aug-cc-pvdz           -1.11662884   SCF TOTAL ENERGY
                  mp2 / aug-cc-pvdz        *  -0.02881480   MP2 CORRELATION ENERGY
              ccsd(t) / aug-cc-pvdz        *  -0.03893812   CCSD(T) CORRELATION ENERGY
                 ccsd / aug-cc-pvdz           -0.03893812   CCSD CORRELATION ENERGY
                  scf / aug-cc-pvtz           -1.11881134   SCF TOTAL ENERGY
                  mp2 / aug-cc-pvtz        *  -0.03288936   MP2 CORRELATION ENERGY
              ccsd(t) / aug-cc-pvtz        *  -0.04201004   CCSD(T) CORRELATION ENERGY
                 ccsd / aug-cc-pvtz           -0.04201004   CCSD CORRELATION ENERGY
----------------------------------------------------------------------------------

==> Stages <==

----------------------------------------------------------------------------------
 Stage         Method / Basis             Wt   Energy [H]   Scheme
----------------------------------------------------------------------------------
   scf            scf / aug-cc-pvqz        1  -1.11916375   highest_1
  corl            mp2 / aug-cc-pv[tq]z     1  -0.03494879   corl_xtpl_helgaker_2
 delta        ccsd(t) / aug-cc-pv[dt]z     1  -0.04330347   corl_xtpl_helgaker_2
 delta            mp2 / aug-cc-pv[dt]z    -1  -0.03460497   corl_xtpl_helgaker_2
----------------------------------------------------------------------------------

==> CBS <==

----------------------------------------------------------------------------------
 Stage         Method / Basis                  Energy [H]   Scheme
----------------------------------------------------------------------------------
   scf            scf / aug-cc-pvqz           -1.11916375   highest_1
  corl            mp2 / aug-cc-pv[tq]z        -0.03494879   corl_xtpl_helgaker_2
 delta  ccsd(t) - mp2 / aug-cc-pv[dt]z        -0.00869851   corl_xtpl_helgaker_2
 total            CBS                         -1.16281105
----------------------------------------------------------------------------------

Extrapolation Schemes¶

Basis set extrapolations are encoded into individual functions like the built-in ones below:

psi4.driver.driver_cbs_helper.xtpl_highest_1(functionname, zHI, valueHI, verbose=1, **kwargs)[source]¶

Scheme for total or correlation energies with a single basis or the highest zeta-level among an array of bases. Used by cbs().

Parameters:

functionname (str) – Name of the CBS component (e.g., ‘mp2’) used in summary printing.
zHI (int) – Zeta-level, only used for printing.
valueHI (Union[float, Matrix, Vector]) – Energy, gradient, or Hessian value at the basis set.
verbose (int) – Controls volume of printing.

Returns:

Returns \(E_{total}^{\infty}\) which is equal to valueHI. Eponymous function applied to input zetas and values; type from valueHI.

Return type:

float or ndarray

Notes

\[E_{total}^X = E_{total}^{\infty}\]

Examples

>>> # [1] Fancy way to get HF/cc-pCVQZ
>>> psi4.energy('cbs', scf_wfn='hf', scf_basis='cc-pcvqz', scf_scheme='xtpl_highest_1')

psi4.driver.driver_cbs_helper.scf_xtpl_helgaker_2(functionname, zLO, valueLO, zHI, valueHI, verbose=1, alpha=None)[source]¶

Extrapolation scheme using exponential form for reference energies with two adjacent zeta-level bases. Used by cbs().

Parameters:

functionname (str) – Name of the CBS component (e.g., ‘HF’) used in summary printing.
zLO (int) – Zeta number of the smaller basis set in 2-point extrapolation.
valueLO (Union[float, Matrix, Vector]) – Energy, gradient, or Hessian value at the smaller basis set in 2-point extrapolation.
zHI (int) – Zeta number of the larger basis set in 2-point extrapolation. Must be zLO + 1.
valueHI (Union[float, Matrix, Vector]) – Energy, gradient, or Hessian value at the larger basis set in 2-point extrapolation.
verbose (int) – Controls volume of printing.
alpha (Optional[float]) – Fitted 2-point parameter. Overrides the default \(\alpha = 1.63\)

Returns:

Eponymous function applied to input zetas and values; type from valueLO.

Return type:

float or ndarray

Notes

The extrapolation is calculated according to [1]: \(E_{total}^X = E_{total}^{\infty} + \beta e^{-\alpha X}, \alpha = 1.63\)

References

Examples

>>> # [1] Hartree-Fock extrapolation
>>> psi4.energy('cbs', scf_wfn='hf', scf_basis='cc-pV[DT]Z', scf_scheme='scf_xtpl_helgaker_2')

psi4.driver.driver_cbs_helper.scf_xtpl_truhlar_2(functionname, zLO, valueLO, zHI, valueHI, verbose=1, alpha=None)[source]¶

Extrapolation scheme using power form for reference energies with two adjacent zeta-level bases. Used by cbs().

Parameters:

functionname (str) – Name of the CBS component (e.g., ‘HF’) used in summary printing.
zLO (int) – Zeta number of the smaller basis set in 2-point extrapolation.
valueLO (Union[float, Matrix, Vector]) – Energy, gradient, or Hessian value at the smaller basis set in 2-point extrapolation.
zHI (int) – Zeta number of the larger basis set in 2-point extrapolation Must be zLO + 1.
valueHI (Union[float, Matrix, Vector]) – Energy, gradient, or Hessian value at the larger basis set in 2-point extrapolation.
verbose (int) – Controls volume of printing.
alpha (Optional[float]) – Overrides the default \(\alpha = 3.4\)

Returns:

Eponymous function applied to input zetas and values; type from valueLO.

Return type:

float or ndarray

Notes

The extrapolation is calculated according to [2]: \(E_{total}^X = E_{total}^{\infty} + \beta X^{-\alpha}, \alpha = 3.4\)

References

psi4.driver.driver_cbs_helper.scf_xtpl_karton_2(functionname, zLO, valueLO, zHI, valueHI, verbose=1, alpha=None)[source]¶

Extrapolation scheme using root-power form for reference energies with two adjacent zeta-level bases. Used by cbs().

Parameters:

functionname (str) – Name of the CBS component (e.g., ‘HF’) used in summary printing.
zLO (int) – Zeta number of the smaller basis set in 2-point extrapolation.
valueLO (Union[float, Matrix, Vector]) – Energy, gradient, or Hessian value at the smaller basis set in 2-point extrapolation.
zHI (int) – Zeta number of the larger basis set in 2-point extrapolation Must be zLO + 1.
valueHI (Union[float, Matrix, Vector]) – Energy, gradient, or Hessian value at the larger basis set in 2-point extrapolation.
verbose (int) – Controls volume of printing.
alpha (Optional[float]) – Overrides the default \(\alpha = 6.3\)

Returns:

Eponymous function applied to input zetas and values; type from valueLO.

Return type:

float or ndarray

Notes

The extrapolation is calculated according to [3]: \(E_{total}^X = E_{total}^{\infty} + \beta e^{-\alpha\sqrt{X}}, \alpha = 6.3\)

References

psi4.driver.driver_cbs_helper.scf_xtpl_helgaker_3(functionname, zLO, valueLO, zMD, valueMD, zHI, valueHI, verbose=1, alpha=None)[source]¶

Extrapolation scheme for reference energies with three adjacent zeta-level bases. Used by cbs().

Parameters:

functionname (str) – Name of the CBS component (e.g., ‘HF’) used in summary printing.
zLO (int) – Zeta number of the smaller basis set in 3-point extrapolation.
valueLO (Union[float, Matrix, Vector]) – Energy, gradient, or Hessian value at the smaller basis set in 3-point extrapolation.
zMD (int) – Zeta number of the medium basis set in 3-point extrapolation. Must be zLO + 1.
valueMD (Union[float, Matrix, Vector]) – Energy, gradient, or Hessian value at the medium basis set in 3-point extrapolation.
zHI (int) – Zeta number of the larger basis set in 3-point extrapolation. Must be zLO + 2.
valueHI (Union[float, Matrix, Vector]) – Energy, gradient, or Hessian value at the larger basis set in 3-point extrapolation.
verbose (int) – Controls volume of printing.
alpha (Optional[float]) – Not used.

Returns:

Eponymous function applied to input zetas and values; type from valueLO.

Return type:

float or ndarray

Notes

The extrapolation is calculated according to [4]: \(E_{total}^X = E_{total}^{\infty} + \beta e^{-\alpha X}, \alpha = 3.0\)

References

Examples

>>> # [1] Hartree-Fock extrapolation
>>> psi4.energy('cbs', scf_wfn='hf', scf_basis='cc-pV[DTQ]Z', scf_scheme='scf_xtpl_helgaker_3')

psi4.driver.driver_cbs_helper.corl_xtpl_helgaker_2(functionname, zLO, valueLO, zHI, valueHI, verbose=1, alpha=None)[source]¶

Extrapolation scheme for correlation energies with two adjacent zeta-level bases. Used by cbs().

Parameters:

functionname (str) – Name of the CBS component (e.g., ‘MP2’) used in summary printing.
zLO (int) – Zeta number of the smaller basis set in 2-point extrapolation.
valueLO (Union[float, Matrix, Vector]) – Energy, gradient, or Hessian value at the smaller basis set in 2-point extrapolation.
zHI (int) – Zeta number of the larger basis set in 2-point extrapolation. Must be zLO + 1.
valueHI (Union[float, Matrix, Vector]) – Energy, gradient, or Hessian value at the larger basis set in 2-point extrapolation.
verbose (int) – Controls volume of printing.
alpha (Optional[float]) – Overrides the default \(\alpha = 3.0\)

Returns:

Eponymous function applied to input zetas and values; type from valueLO.

Return type:

float or ndarray

Notes

The extrapolation is calculated according to [5]: \(E_{corl}^X = E_{corl}^{\infty} + \beta X^{-alpha}\)

References

Examples

>>> # [1] CISD extrapolation
>>> energy('cbs', corl_wfn='cisd', corl_basis='cc-pV[DT]Z', corl_scheme='corl_xtpl_helgaker_2')

psi4.driver.driver_cbs._get_default_xtpl(nbasis, xtpl_type)[source]¶

A helper function to determine default extrapolation type.

Parameters:

nbasis (int) – Number of basis sets
xtpl_type (str) – {‘scf’, ‘corl’} Extrapolation type: ‘scf’ for the total energy, ‘corl’ for just the correlation component.

Returns:

Extrapolation function to be used.

Return type:

Callable

Additional extrapolation schemes are easy to define by the user. Follow models in psi4/psi4/driver/driver_cbs_helper.py and pywrap-cbs1 and use the psi4.driver.driver_cbs_helper.register_xtpl_function() to make user-defined functions known to PSI4.

psi4.driver.driver_cbs_helper.register_xtpl_function(func)[source]¶

Register a user-defined extrapolation function to use like an built-in one.

Parameters:: func (Callable) – A Python function that applies a basis set extrapolation formula to scalars and optionally to NumPy arrays. See psi4/psi4/driver/driver_cbs_helper.py and pywrap-cbs1 for examples. The name of the function should follow the pattern <scf|corl>_xtpl_<scientist>_<#basis>.

Aliases¶

When a particular composite method or its functional form is going to be reused often, it is convenient to define an alias to it. A convenient place for such Python code to reside is in psi4/psi4/driver/aliases.py Some existing examples are below.

psi4.driver.aliases.sherrill_gold_standard(**kwargs)[source]¶

Function to call the quantum chemical method known as ‘Gold Standard’ in the Sherrill group. Uses the composite wrapper to evaluate the following expression. Two-point extrapolation of the correlation energy performed according to corl_xtpl_helgaker_2(). :rtype: List[Dict[str, Any]]

\[E_{total}^{\text{Au\_std}} = E_{total,\; \text{SCF}}^{\text{aug-cc-pVQZ}} \; + E_{corl,\; \text{MP2}}^{\text{aug-cc-pV[TQ]Z}} \; + \delta_{\text{MP2}}^{\text{CCSD(T)}}\big\vert_{\text{aug-cc-pVTZ}}\]

>>> # [1] single-point energy by this composite method
>>> energy('sherrill_gold_standard')

>>> # [2] finite-difference geometry optimization
>>> optimize('sherrill_gold_standard')

>>> # [3] finite-difference geometry optimization, overwriting some pre-defined sherrill_gold_standard options
>>> optimize('sherrill_gold_standard', corl_basis='cc-pV[DT]Z', delta_basis='3-21g')

Return type:: List[Dict[str, Any]]

psi4.driver.aliases.allen_focal_point(**kwargs)[source]¶

Function to call Wes Allen-style Focal Point Analysis. JCP 127 014306, https://doi.org/10.1063/1.2747241 . Uses the composite wrapper to evaluate the following expression. SCF employs a three-point extrapolation according to scf_xtpl_helgaker_3(). MP2, CCSD, and CCSD(T) employ two-point extrapolation performed according to corl_xtpl_helgaker_2(). CCSDT and CCSDT(Q) are plain deltas. This wrapper requires Kallay’s MRCC code. :rtype: List[Dict[str, Any]]

\[E_{total}^{\text{FPA}} = E_{total,\; \text{SCF}}^{\text{cc-pV[Q56]Z}} \; + E_{corl,\; \text{MP2}}^{\text{cc-pV[56]Z}} \; + \delta_{\text{MP2}}^{\text{CCSD}}\big\vert_{\text{cc-pV[56]Z}} \; + \delta_{\text{CCSD}}^{\text{CCSD(T)}}\big\vert_{\text{cc-pV[56]Z}} \; + \delta_{\text{CCSD(T)}}^{\text{CCSDT}}\big\vert_{\text{cc-pVTZ}} \; + \delta_{\text{CCSDT}}^{\text{CCSDT(Q)}}\big\vert_{\text{cc-pVDZ}}\]

>>> # [1] single-point energy by this composite method
>>> energy('allen_focal_point')

>>> # [2] single-point energy reducing the Hartree-Fock basis sets size
>>> energy('allen_focal_point', scf_basis='cc-pV[TQ5]Z')

Return type:: List[Dict[str, Any]]

Additional composite aliases are easy to define by the user. Follow models in psi4/psi4/driver/aliases.py and cbs-xtpl-nbody and use the psi4.driver.driver_cbs_helper.register_composite_function() to make user-defined functions known to PSI4.

psi4.driver.driver_cbs_helper.register_composite_function(func)[source]¶

Register a user-defined composite method function to use like a built-in one.

Parameters:: func (Callable) – A Python function that defines a configuration of the psi4.driver.cbs() wrapper. See psi4/psi4/driver/aliases.py and cbs-xtpl-nbody for examples.

API¶

pydantic model psi4.driver.driver_cbs.CompositeComputer[source]¶

Show JSON schema

{
   "title": "CompositeComputer",
   "description": "Base class for \"computers\" that plan, run, and process QC tasks.",
   "type": "object",
   "properties": {
      "molecule": {
         "title": "Molecule"
      },
      "basis": {
         "title": "Basis",
         "default": "(auto)",
         "type": "string"
      },
      "method": {
         "title": "Method",
         "default": "(auto)",
         "type": "string"
      },
      "driver": {
         "$ref": "#/definitions/DriverEnum"
      },
      "keywords": {
         "title": "Keywords",
         "default": {},
         "type": "object"
      },
      "metadata": {
         "title": "Metadata"
      },
      "metameta": {
         "title": "Metameta",
         "default": {},
         "type": "object"
      },
      "verbose": {
         "title": "Verbose",
         "default": 1,
         "type": "integer"
      },
      "cbsrec": {
         "title": "Cbsrec",
         "default": [],
         "type": "array",
         "items": {
            "type": "object"
         }
      },
      "trove": {
         "title": "Trove",
         "default": [],
         "type": "array",
         "items": {
            "type": "object"
         }
      },
      "compute_list": {
         "title": "Compute List",
         "default": [],
         "type": "array",
         "items": {
            "type": "object"
         }
      },
      "task_list": {
         "title": "Task List",
         "default": [],
         "type": "array",
         "items": {
            "$ref": "#/definitions/AtomicComputer"
         }
      },
      "results_list": {
         "title": "Results List",
         "default": [],
         "type": "array",
         "items": {}
      }
   },
   "required": [
      "driver"
   ],
   "definitions": {
      "DriverEnum": {
         "title": "DriverEnum",
         "description": "Allowed computation driver values.",
         "enum": [
            "energy",
            "gradient",
            "hessian",
            "properties"
         ],
         "type": "string"
      },
      "WavefunctionProtocolEnum": {
         "title": "WavefunctionProtocolEnum",
         "description": "Wavefunction to keep from a computation.",
         "enum": [
            "all",
            "orbitals_and_eigenvalues",
            "occupations_and_eigenvalues",
            "return_results",
            "none"
         ],
         "type": "string"
      },
      "ErrorCorrectionProtocol": {
         "title": "ErrorCorrectionProtocol",
         "description": "Configuration for how QCEngine handles error correction\n\nWARNING: These protocols are currently experimental and only supported by NWChem tasks",
         "type": "object",
         "properties": {
            "default_policy": {
               "title": "Default Policy",
               "description": "Whether to allow error corrections to be used if not directly specified in `policies`",
               "default": true,
               "type": "boolean"
            },
            "policies": {
               "title": "Policies",
               "description": "Settings that define whether specific error corrections are allowed. Keys are the name of a known error and values are whether it is allowed to be used.",
               "type": "object",
               "additionalProperties": {
                  "type": "boolean"
               }
            }
         },
         "additionalProperties": false
      },
      "NativeFilesProtocolEnum": {
         "title": "NativeFilesProtocolEnum",
         "description": "CMS program files to keep from a computation.",
         "enum": [
            "all",
            "input",
            "none"
         ],
         "type": "string"
      },
      "AtomicResultProtocols": {
         "title": "AtomicResultProtocols",
         "description": "Protocols regarding the manipulation of computational result data.",
         "type": "object",
         "properties": {
            "wavefunction": {
               "description": "Wavefunction to keep from a computation.",
               "default": "none",
               "allOf": [
                  {
                     "$ref": "#/definitions/WavefunctionProtocolEnum"
                  }
               ]
            },
            "stdout": {
               "title": "Stdout",
               "description": "Primary output file to keep from the computation",
               "default": true,
               "type": "boolean"
            },
            "error_correction": {
               "title": "Error Correction",
               "description": "Policies for error correction",
               "allOf": [
                  {
                     "$ref": "#/definitions/ErrorCorrectionProtocol"
                  }
               ]
            },
            "native_files": {
               "description": "Policies for keeping processed files from the computation",
               "default": "none",
               "allOf": [
                  {
                     "$ref": "#/definitions/NativeFilesProtocolEnum"
                  }
               ]
            }
         },
         "additionalProperties": false
      },
      "AtomicComputer": {
         "title": "AtomicComputer",
         "description": "Computer for analytic single-geometry computations.",
         "type": "object",
         "properties": {
            "molecule": {
               "title": "Molecule",
               "description": "The molecule to use in the computation."
            },
            "basis": {
               "title": "Basis",
               "description": "The quantum chemistry basis set to evaluate (e.g., 6-31g, cc-pVDZ, ...).",
               "type": "string"
            },
            "method": {
               "title": "Method",
               "description": "The quantum chemistry method to evaluate (e.g., B3LYP, MP2, ...).",
               "type": "string"
            },
            "driver": {
               "description": "The resulting type of computation: energy, gradient, hessian, properties.Note for finite difference that this should be the target driver, not the means driver.",
               "allOf": [
                  {
                     "$ref": "#/definitions/DriverEnum"
                  }
               ]
            },
            "keywords": {
               "title": "Keywords",
               "description": "The keywords to use in the computation.",
               "type": "object"
            },
            "protocols": {
               "title": "Protocols",
               "description": "Output modifications.",
               "default": {
                  "stdout": true
               },
               "anyOf": [
                  {
                     "$ref": "#/definitions/AtomicResultProtocols"
                  },
                  {
                     "type": "object"
                  }
               ]
            },
            "tag": {
               "title": "Tag",
               "description": "The tags to pass along to compute managers.",
               "default": "*",
               "type": "string"
            },
            "priority": {
               "title": "Priority",
               "description": "The priority of a Task; higher priority will be pulled first. {high:2, normal:1, low:0}",
               "default": 1,
               "type": "string"
            },
            "owner_group": {
               "title": "Owner Group",
               "description": "group in the chown sense.",
               "type": "string"
            },
            "computed": {
               "title": "Computed",
               "description": "Whether quantum chemistry has been run on this task.",
               "default": false,
               "type": "boolean"
            },
            "result": {
               "title": "Result",
               "description": ":py:class:`~qcelemental.models.AtomicResult` return."
            },
            "result_id": {
               "title": "Result Id",
               "description": "The optional ID for the computation.",
               "type": "string"
            }
         },
         "required": [
            "molecule",
            "basis",
            "method",
            "driver"
         ]
      }
   }
}

Fields:

basis (str)
cbsrec (List[Dict[str, Any]])
compute_list (List[Dict[str, Any]])
driver (qcelemental.models.common_models.DriverEnum)
keywords (Dict[str, Any])
metadata (Any)
metameta (Dict[str, Any])
method (str)
molecule (Any)
results_list (List[Any])
task_list (List[psi4.driver.task_base.AtomicComputer])
trove (List[Dict[str, Any]])
verbose (int)

Validators:

set_molecule » molecule

field basis: str = '(auto)'¶

field cbsrec: List[Dict[str, Any]] = []¶

field compute_list: List[Dict[str, Any]] = []¶

field driver: DriverEnum [Required]¶

field keywords: Dict[str, Any] = {}¶

field metadata: Any = None¶

field metameta: Dict[str, Any] = {}¶

field method: str = '(auto)'¶

field molecule: Any = None¶

Validated by:

set_molecule

field results_list: List[Any] = []¶

field task_list: List[AtomicComputer] = []¶

field trove: List[Dict[str, Any]] = []¶

field verbose: int = 1¶

build_tasks(obj, **kwargs)[source]¶

compute(client=None)[source]¶

Parameters:: client (qcportal.FractalClient | None) –

get_psi_results(client=None, *, return_wfn=False)[source]¶

Called by driver to assemble results into Composite-flavored QCSchema, then reshape and return them in the customary Psi4 driver interface: (e/g/h, wfn).

Parameters:

return_wfn –
Whether to additionally return the dummy Wavefunction calculation result as the second element of a tuple. Contents are:
- molecule
- dummy basis, def2-svp
- e/g/h member data
- QCVariables
- module if simple
client (qcportal.FractalClient | None) –

Returns:

ret – Energy, gradient, or Hessian according to self.driver.
wfn – Wavefunction described above when return_wfn specified.

Return type:

float | Matrix | Tuple[float | Matrix, Wavefunction]

get_results(client=None)[source]¶

Return results as Composite-flavored QCSchema.

Parameters:: client (qcportal.FractalClient | None) –
Return type:: AtomicResult

plan()[source]¶

validator set_molecule » molecule[source]¶