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.
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.
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.
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.
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.
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().
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.
\(\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.
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.
'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.
\(\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.
\(\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.
\(\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.
\(\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.
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().
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.
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.
\(\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.
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')
>>> # [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()>>> TODOdatabase('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()>>> TODOoptimize('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.
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.
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.
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>.
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.
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().
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.
{"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"},"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"},"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"]}}}
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).