# cbs

`psi4.driver.``cbs`(func, label, **kwargs)

  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: |

  - `CBS TOTAL ENERGY`
  - `CBS REFERENCE ENERGY`
  - `CBS CORRELATION ENERGY`
  - `CURRENT ENERGY`
  - `CURRENT REFERENCE ENERGY`
  - `CURRENT CORRELATION ENERGY`

  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 sec:cbs_xtpl for all available schemes.

  Parameters:

  - scf_scheme (function) –

    \(\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 `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 (function) –

    \(\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 (function) –

    \(\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 (function) –

    \(\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

  - Combined interface

  - 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)