Basis Set Superposition Corrections¶
Code author: Daniel G. A. Smith
- psi4.driver.driver_nbody.nbody(func, method_string[, molecule, bsse_type, max_nbody, ptype, return_total_data])[source]¶
Computes the nbody interaction energy, gradient, or Hessian depending on input. This is a generalized universal function for computing interaction and total quantities.
- Returns
return type of func – The data.
- Returns
(float,
Wavefunction
) – data and wavefunction with energy/gradient/hessian set appropriately when return_wfn specified.- Parameters
molecule (molecule) –
h2o
|| etc.The target molecule, if not the last molecule defined.
return_wfn (boolean) –
'on'
|| \(\Rightarrow\)'off'
\(\Leftarrow\)Indicate to additionally return the
Wavefunction
calculation result as the second element of a tuple.'cp'
||['nocp', 'vmfc']
|| \(\Rightarrow\)None
\(\Leftarrow\) || etc.Type of BSSE correction to compute: CP for counterpoise correction, NoCP for plain supramolecular interaction energy, or VMFC for Valiron-Mayer Function Counterpoise correction. If a list is provided, the first string in the list determines which interaction or total energies/gradients/Hessians are returned by this function. By default, many-body treatments are inactive.
max_nbody (int) –
3
|| etc.Maximum n-body to compute, cannot exceed the number of fragments in the molecule.
return_total_data (boolean) –
'on'
|| \(\Rightarrow\)'off'
\(\Leftarrow\)If True returns the total data (energy/gradient/Hessian) of the system, otherwise returns interaction data. Default is
'off'
for energies,'on'
for gradients and Hessians. Note that the calculation of total counterpoise corrected energies implies the calculation of the energies of monomers in the monomer basis, hence specifyingreturn_total_data = True
may carry out more computations thanreturn_total_data = False
. For gradients and Hessians,return_total_data = False
is rarely useful.levels (dict) –
{1: 'ccsd(t)', 2: 'mp2', 'supersystem': 'scf'}
||{1: 2, 2: 'ccsd(t)', 3: 'mp2'}
|| etcDictionary of different levels of theory for different levels of expansion Note that method_string is not used in this case.
supersystem
computes all higher order n-body effects up to the number of fragments.embedding_charges (dict) –
{1: [-0.834, 0.417, 0.417], ..}
Dictionary of atom-centered point charges. keys: 1-based index of fragment, values: list of charges for each fragment. Add atom-centered point charges for fragments whose basis sets are not included in the computation.
The nbody function computes counterpoise-corrected (CP), non-CP (noCP), and Valiron-Mayer Function Counterpoise (VMFC) interaction energies for complexes composed of arbitrary numbers of monomers.
Examples :
# Counterpoise corrected CCSD(T) energies for the Helium dimer
molecule mol {
He
--
He 1 3
}
# Calculate interaction energies only (skips monomers in monomer basis):
energy('CCSD(T)', bsse_type='cp')
# Calculate interaction and total energies, return interaction energies:
energy('CCSD(T)', bsse_type=['cp','nocp'])
# Calculate and return counterpoise-corrected gradient
# Useful for e.g. CP-corrected geometry optimization
gradient('CCSD(T)', bsse_type='cp', return_total_data=True)
# noCP, VMFC, and CP energy for a helium cluster, limited at 3 bodies
molecule mol {
He 0 0 0
--
He 0 0 4
--
He 0 4 0
--
He 4 0 0
}
# Returns the nocp energy as its first in the list
energy('CCSD(T)', bsse_type=['nocp', 'cp', 'vmfc'], max_nbody=3)
- class psi4.driver.driver_nbody.ManyBodyComputer(**data)[source]¶
- Parameters
molecule (Any) – The target molecule, if not the last molecule defined.
basis (str, Default: (auto)) –
method (str, Default: (auto)) –
driver ({energy,gradient,hessian,properties}) – The computation driver; i.e., energy, gradient, hessian.
keywords (Dict[Any], Default: {}) – The computation keywords/options.
bsse_type ({nocp,cp,vmfc}, Default: [<BsseEnum.cp: 'cp'>]) – Requested BSSE treatments. First in list determines which interaction or total energy/gradient/Hessian returned.
nfragments (int, Default: -1) – Number of distinct fragments comprising full molecular supersystem.
max_nbody (int, Default: -1) – Maximum number of bodies to include in the many-body treatment. Possible: max_nbody <= nfragments. Default: max_nbody = nfragments.
nbodies_per_mc_level (List[List[Union[int, ]]], Default: []) – Distribution of active n-body levels among model chemistry levels. All bodies in range [1, self.max_nbody] must be present exactly once. Number of items in outer list is how many different modelchems. Each inner list specifies what n-bodies to be run at the corresponding modelchem (e.g., [[1, 2]] has max_nbody=2 and 1-body and 2-body contributions computed at the same level of theory; [[1], [2]] has max_nbody=2 and 1-body and 2-body contributions computed at different levels of theory. An entry ‘supersystem’ means all higher order n-body effects up to the number of fragments. The n-body levels are effectively sorted in the outer list, and any ‘supersystem’ element is at the end.
embedding_charges (Dict[List[float]], Default: {}) – Atom-centered point charges to be used on molecule fragments whose basis sets are not included in the computation. Keys: 1-based index of fragment. Values: list of atom charges for that fragment.
return_total_data (bool, Optional) – When True, returns the total data (energy/gradient/Hessian) of the system, otherwise returns interaction data. Default is False for energies, True for gradients and Hessians. Note that the calculation of total counterpoise corrected energies implies the calculation of the energies of monomers in the monomer basis, hence specifying
return_total_data = True
may carry out more computations thanreturn_total_data = False
.quiet (bool, Default: False) – Whether to print/log formatted n-body energy analysis. Presently used by multi to suppress output. Candidate for removal from class once in-class/out-of-class functions sorted.
task_list (Dict[Union[, , ]], Default: {}) –
extra_data (Any) –
- Return type
None
- build_tasks(mb_computer, mc_level_idx, **kwargs)[source]¶
Adds to the task_list as many new unique tasks as necessary to treat a single model chemistry level at one or several n-body levels. New tasks are of type mb_computer with model chemistry level specified in kwargs and n-body levels accessed through mc_level_idx.
- Parameters
mb_computer (
Union
[AtomicComputer, CompositeComputer, FiniteDifferenceComputer]) – Class of TaskComputers to instantiate and add to self.task_list. Usually AtomicComputer but may be other when wrappers are layered.mc_level_idx (
int
) – Position in field self.nbodies_per_mc_level used to obtainnbodies
, the list of n-body levels (e.g., [1] or [1, 2] or [“supersystem”]) to which the modelchem specified in kwargs applies. That is, nbodies = self.nbodies_per_mc_level[mc_level_idx]. Note the natural 1-indexing ofnbodies
_contents_, so [1] covers one-body contributions. The corresponding user label is the 1-indexed counterpart, mc_level_lbl = mc_level_idx + 1 Formerly nlevel as in nbody = self.nbody_list[nbody_level=nlevel].kwargs (
Dict
[str
,Any
]) – Other arguments for initializing mb_computer. In particular, specifies model chemistry.
- Returns
Number of new tasks planned by this call. Formerly, didn’t include supersystem in count.
- Return type
count
- get_psi_results(return_wfn=False)[source]¶
Called by driver to assemble results into ManyBody-flavored QCSchema, then reshape and return them in the customary Psi4 driver interface:
(e/g/h, wfn)
.- Parameters
return_wfn (
bool
) –Whether to additionally return the dummy
Wavefunction
calculation result as the second element of a tuple. Contents are:supersystem molecule
dummy basis, def2-svp
e/g/h member data
QCVariables
- Return type
Union
[float
,Matrix
,Tuple
[Union
[float
,Matrix
],Wavefunction
]]- Returns
ret – Energy, gradient, or Hessian according to self.driver.
wfn – Wavefunction described above when return_wfn specified.
- get_results(client=None)[source]¶
Return results as ManyBody-flavored QCSchema.
- Return type
AtomicResult
- Parameters
client (Optional[FractalClient]) –
- prepare_results(results=None, client=None)[source]¶
Process the results from all n-body component molecular systems and model chemistry levels into final quantities.
- Parameters
results (
Optional
[Dict
[str
,Union
[AtomicComputer, CompositeComputer, FiniteDifferenceComputer]]]) – A set of tasks to process instead of self.task_list. Used in multilevel processing to pass a subset of self.task_list filtered to only one modelchem level.client (
Optional
[FractalClient]) – QCFractal client if using QCArchive for distributed compute.
- Returns
When the ManyBodyComputer specifies a single model chemistry level (see self.nbodies_per_mc_level), the return is a dictionary, nbody_results, described in the table below. Many of the items are actually filled by successive calls to assemble_nbody_components(). When multiple model chemistry levels are specified, this function diverts its return to driver_nbody_multilevel.prepare_results() wherein each mc level calls this function again and collects separate nbody_results dictionaries and processes them into a final return that is a small subset of the table below.
- Return type
nbody_results
- ptype_size = (1,)/(nat, 3)/(3 * nat, 3 * nat)
e/g/h := energy or gradient or Hessian rtd := return_total_data
item
size
present / zeroed
contents / interpretation
ret_ptype
ptype_size
always
- interaction data requested: IE or total (depending on return_total_data) e/g/h (depending on driver)
with cp/nocp/vmfc treatment (depending on 1st of bsse_type)
ret_energy
1
always
interaction energy: IE or total (depending on return_total_data) w/ cp/nocp/vmfc treat. (dep. on 1st of bsse_type)
ret_gradient
(nat, 3)
when driver is g/h
interaction gradient: IE or total (depending on return_total_data) w/ cp/nocp/vmfc treat. (dep. on 1st of bsse_type
ret_hessian
(nat * 3, nat * 3)
when driver is h
interaction Hessian: IE or total (depending on return_total_data) w/ cp/nocp/vmfc treat. (dep. on 1st of bsse_type)
nbody
>=1
always
energy n-body QCVariables to be set
CP-CORRECTED TOTAL ENERGY THROUGH 1-BODY
1
when cp in bsse_type
MBE sum of subsystems of 1-body. summed are total energies with cp treatment
CP-CORRECTED TOTAL ENERGY THROUGH 2-BODY
1
when cp in bsse_type & max_nbody>=2
MBE sum of subsystems of 2-body or fewer (cumulative); summed are total energies with cp treatment
CP-CORRECTED TOTAL ENERGY THROUGH {nb}-BODY
1
when cp in bsse_type
MBE sum of subsystems of {max_nbody}-body or fewer (cumulative); summed are total energies w/ cp treatment
CP-CORRECTED TOTAL ENERGY
1
when cp in bsse_type & rtd=T
best available total energy with cp treatment: CP-CORRECTED TOTAL ENERGY THROUGH {max_nbody}-BODY
CP-CORRECTED INTERACTION ENERGY THROUGH 2-BODY
1
when cp in bsse_type & max_nbody>=2
2-body total data less 1-body total data for cumulative IE; inputs are total energies with cp treatment
CP-CORRECTED INTERACTION ENERGY THROUGH {nb}-BODY
1
when cp in bsse_type
{max_nbody}-body total data less 1-body total data for cumulative IE; inputs are total energies with cp treatment
CP-CORRECTED INTERACTION ENERGY
1
when cp in bsse_type
best available interaction energy with cp treatment: CP-CORRECTED INTERACTION ENERGY THROUGH {max_nbody}-BODY
CP-CORRECTED 2-BODY CONTRIBUTION TO ENERGY
1
when cp in bsse_type & max_nbody>=2
2-body total data less (2-1)-body total data for partial IE; inputs are total energies w/ cp treatment
CP-CORRECTED {nb}-BODY CONTRIBUTION TO ENERGY
1
when cp in bsse_type
{max_nbody}-body total data less ({max_nbody}-1)-body data for partial IE; inputs are total energies w/ cp treat.
NOCP-CORRECTED TOTAL ENERGY THROUGH 1-BODY
1
when nocp in bsse_type
MBE sum of subsystems of 1-body. summed are total energies without cp treatment
NOCP-CORRECTED TOTAL ENERGY THROUGH 2-BODY
1
when nocp in bsse_type & max_nbody>=2
MBE sum of subsystems of 2-body or fewer (cumulative); summed are total energies without cp treatment
NOCP-CORRECTED TOTAL ENERGY THROUGH {nb}-BODY
1
when nocp in bsse_type
MBE sum of subsystems of {max_nbody}-body or fewer (cumulative); summed are total energies w/o cp treatment
NOCP-CORRECTED TOTAL ENERGY
1
when nocp in bsse_type
best available total energy without cp treatment: NOCP-CORRECTED TOTAL ENERGY THROUGH {max_nbody}-BODY
NOCP-CORRECTED INTERACTION ENERGY THROUGH 2-BODY
1
when nocp in bsse_type & max_nbody>=2
2-body total data less 1-body total data for cumulative IE; inputs are total energies w/o cp treatment
NOCP-CORRECTED INTERACTION ENERGY THROUGH {nb}-BODY
1
when nocp in bsse_type
{max_nbody}-body total data less 1-body total data for cumulative IE; inputs are total energies w/o cp treatment
NOCP-CORRECTED INTERACTION ENERGY
1
when nocp in bsse_type
best available interaction energy without cp treatment: NOCP-CORRECTED INTERACTION ENERGY THROUGH {max_nbody}-BODY
NOCP-CORRECTED 2-BODY CONTRIBUTION TO ENERGY
1
when nocp in bsse_type & max_nbody>=2
2-body total data less (2-1)-body total data for partial IE; inputs are total energies w/o cp treatment
NOCP-CORRECTED {nb}-BODY CONTRIBUTION TO ENERGY
1
when nocp in bsse_type
{max_nbody}-body total data less ({max_nbody}-1)-body data for partial IE; inputs are total energies w/o cp treat.
VMFC-CORRECTED TOTAL ENERGY THROUGH 1-BODY
1
when vmfc in bsse_type
MBE sum of subsystems of 1-body. summed are total energies with vmfc treatment
VMFC-CORRECTED TOTAL ENERGY THROUGH 2-BODY
1
when vmfc in bsse_type & max_nbody>=2
MBE sum of subsystems of 2-body or fewer (cumulative); summed are total energies with vmfc treatment
VMFC-CORRECTED TOTAL ENERGY THROUGH {nb}-BODY
1
when vmfc in bsse_type
MBE sum of subsystems of {max_nbody}-body or fewer (cumulative); summed are total energies w/ vmfc treatment
VMFC-CORRECTED TOTAL ENERGY
1
when vmfc in bsse_type
best available total energy with vmfc treatment: VMFC-CORRECTED TOTAL ENERGY THROUGH {max_nbody}-BODY
VMFC-CORRECTED INTERACTION ENERGY THROUGH 2-BODY
1
when vmfc in bsse_type & max_nbody>=2
2-body total data less 1-body total data for cumulative IE; inputs are total energies w/ vmfc treatment
VMFC-CORRECTED INTERACTION ENERGY THROUGH {nb}-BODY
1
when vmfc in bsse_type
{max_nbody}-body total data less 1-body total data for cumulative IE; inputs are total energies w/ vmfc treatment
VMFC-CORRECTED INTERACTION ENERGY
1
when vmfc in bsse_type
best available interaction energy with vmfc treatment: VMFC-CORRECTED INTERACTION ENERGY THROUGH {max_nbody}-BODY
VMFC-CORRECTED 2-BODY CONTRIBUTION TO ENERGY
1
when vmfc in bsse_type & max_nbody>=2
2-body total data less (2-1)-body total data for partial IE; inputs are total energies w/ vmfc treatment
VMFC-CORRECTED {nb}-BODY CONTRIBUTION TO ENERGY
1
when vmfc in bsse_type
{max_nbody}-body total data less ({max_nbody}-1)-body data for partial IE; inputs are total energies w/ vmfc treat.
energy_body_dict
max_nbody
always
total energies at each n-body level
1
1
always; zeroed if cp & rtd=F
cumulative through 1-body total energies w/ cp/nocp/vmfc treatment (dep. on 1st of bsse_type)
2
1
max_nbody>=2
cumulative through 2-body total energies w/ cp/nocp/vmfc treatment (dep. on 1st of bsse_type)
{max_nbody}
1
always
cumulative through {max_nbody}-body total energies w/ cp/nocp/vmfc treatment (dep. on 1st of bsse_type)
gradient_body_dict
max_nbody
when driver is g/h
1
(nat, 3)
when driver is g/h
cumulative through 1-body total gradients with cp/nocp/vmfc treatment (dep. on 1st of bsse_type)
2
(nat, 3)
when driver is g/h & max_nbody>=2
cumulative through 2-body total gradients with cp/nocp/vmfc treatment (dep. on 1st of bsse_type)
{max_nbody}
(nat, 3)
when driver is g/h
cumulative through {max_nbody}-body total gradients w/ cp/nocp/vmfc treatment (dep. on 1st of bsse_type)
hessian_body_dict
max_nbody
when driver is h
1
(nat*3, nat*3)
when driver is h
cumulative through 1-body total Hessians w/ cp/nocp/vmfc treatment (dep. on 1st of bsse_type)
2
(nat*3, nat*3)
when driver is h & max_nbody>=2
cumulative through 2-body total Hessians w/ cp/nocp/vmfc treatment (dep. on 1st of bsse_type)
{max_nbody}
(nat*3, nat*3)
when driver is h
cumulative through {max_nbody}-body total Hessians w/ cp/nocp/vmfc treatment (dep. on 1st of bsse_type)
cp_energy_body_dict
max_nbody
always; zeroed if cp not in bsse_type
total energies at each n-body level with cp treatment
1cp
1
always; zeroed if cp not in bsse_type or rtd=F
cumulative through 1-body total energies with cp treatment
2cp
1
when max_nbody>=2; zeroed if cp not in bsse_type
cumulative through 2-body total energies with cp treatment
{max_nbody}cp
1
always; zeroed if cp not in bsse_type
cumulative through {max_nbody}-body total energies with cp treatment
cp_gradient_body_dict
max_nbody
when driver is g/h; zeroed if cp not in bsse_type
total gradients at each n-body level with cp treatment
1cp
(nat, 3)
when driver is g/h; zeroed if cp not in bsse_type or rtd=F
cumulative through 1-body total gradients with cp treatment
2cp
(nat, 3)
when driver is g/h & max_nbody>=2; zeroed if cp not in bsse_type
cumulative through 2-body total gradients with cp treatment
{max_nbody}cp
(nat, 3)
when driver is g/h; zeroed if cp not in bsse_type
cumulative through {max_nbody}-body total gradients with cp treatment
cp_hessian_body_dict
max_nbody
when driver is h; zeroed if cp not in bsse_type
total Hessians at each n-body level with cp treatment
1cp
(nat*3, nat*3)
when driver is h; zeroed if cp not in bsse_type or rtd=F
cumulative through 1-body total Hessians with cp treatment
2cp
(nat*3, nat*3)
when driver is h & max_nbody>=2; zeroed if cp not in bsse_type
cumulative through 2-body total Hessians with cp treatment
{max_nbody}cp
(nat*3, nat*3)
when driver is h; zeroed if cp not in bsse_type
cumulative through {max_nbody}-body total Hessians with cp treatment
nocp_energy_body_dict
max_nbody
always; zeroed if nocp not in bsse_type
total energies at each n-body level with nocp treatment
1nocp
1
always; zeroed if nocp not in bsse_type
cumulative through 1-body total energies with nocp treatment
2nocp
1
when max_nbody>=2; zeroed if nocp not in bsse_type
cumulative through 2-body total energies with nocp treatment
{max_nbody}nocp
1
always; zeroed if nocp not in bsse_type
cumulative through {max_nbody}-body total energies with nocp treatment
nocp_gradient_body_dict
max_nbody
when driver is g/h; zeroed if nocp not in bsse_type
total gradients at each n-body level with nocp treatment
1nocp
(nat, 3)
when driver is g/h; zeroed if nocp not in bsse_type
cumulative through 1-body total gradients with nocp treatment
2nocp
(nat, 3)
when driver is g/h & max_nbody>=2; zeroed if nocp not in bsse_type
cumulative through 2-body total gradients with nocp treatment
{max_nbody}nocp
(nat, 3)
when driver is g/h; zeroed if nocp not in bsse_type
cumulative through {max_nbody}-body total gradients with nocp treatment
nocp_hessian_body_dict
max_nbody
when driver is h; zeroed if nocp not in bsse_type
total Hessians at each n-body level with nocp treatment
1nocp
(nat*3, nat*3)
when driver is h; zeroed if nocp not in bsse_type
cumulative through 1-body total Hessians with nocp treatment
2nocp
(nat*3, nat*3)
when driver is h & max_nbody>=2; zeroed if nocp not in bsse_type
cumulative through 2-body total Hessians with nocp treatment
{max_nbody}nocp
(nat*3, nat*3)
when driver is h; zeroed if nocp not in bsse_type
cumulative through {max_nbody}-body total Hessians with nocp treatment
vmfc_energy_body_dict
max_nbody
always; zeroed if vmfc not in bsse_type
total energies at each n-body level with vmfc treatment
1vmfc
1
always; zeroed if vmfc not in bsse_type
cumulative through 1-body total energies with vmfc treatment
2vmfc
1
when max_nbody>=2; zeroed if vmfc not in bsse_type
cumulative through 2-body total energies with vmfc treatment
{max_nbody}vmfc
1
always; zeroed if vmfc not in bsse_type
cumulative through {max_nbody}-body total energies with vmfc treatment
vmfc_gradient_body_dict
max_nbody
when driver is g/h; zeroed if vmfc not in bsse_type
total gradients at each n-body level with vmfc treatment
1vmfc
(nat, 3)
when driver is g/h; zeroed if vmfc not in bsse_type
cumulative through 1-body total gradients with vmfc treatment
2vmfc
(nat, 3)
when driver is g/h & max_nbody>=2; zeroed if vmfc not in bsse_type
cumulative through 2-body total gradients with vmfc treatment
{max_nbody}vmfc
(nat, 3)
when driver is g/h; zeroed if vmfc not in bsse_type
cumulative through {max_nbody}-body total gradients with vmfc treatment
vmfc_hessian_body_dict
max_nbody
when driver is h; zeroed if vmfc not in bsse_type
total Hessians at each n-body level with vmfc treatment
1vmfc
(nat*3, nat*3)
when driver is h; zeroed if vmfc not in bsse_type
cumulative through 1-body total Hessians with vmfc treatment
2vmfc
(nat*3, nat*3)
when driver is h & max_nbody>=2; zeroed if vmfc not in bsse_type
cumulative through 2-body total Hessians with vmfc treatment
{max_nbody}vmfc
(nat*3, nat*3)
when driver is h; zeroed if vmfc not in bsse_type
cumulative through {max_nbody}-body total Hessians with vmfc treatment
intermediates
ntasks
always
all individual energies with nice labels
N-BODY (1, 2)@(1, 2) TOTAL ENERGY
1
always
total energy for 1st modelchem, 1st & 2nd fragments in basis of 1st & 2nd fragments
N-BODY (3)@(2, 3) TOTAL ENERGY
1
always
total energy for 2nd modelchem, 3rd fragment in basis of 2nd and 3rd fragments
…
intermediates_energy
ntasks
always
all individual energies
1_((1, 2), (1, 2))
1
always
total energy for 1st modelchem, 1st & 2nd fragments in basis of 1st & 2nd fragments
2_((3,), (2, 3))
1
always
total energy for 2nd modelchem, 3rd fragment in basis of 2nd and 3rd fragments
…
intermediates_gradient
ntasks
when driver is g/h
all individual gradients
1_((1, 2), (1, 2))
(nat, 3)
when driver is g/h
total gradient for 1st modelchem, 1st & 2nd fragments in basis of 1st & 2nd fragments
2_((3,), (2, 3))
(nat, 3)
when driver is g/h
total gradient for 2nd modelchem, 3rd fragment in basis of 2nd and 3rd fragments
…
intermediates_hessian
ntasks
when driver is h
all individual Hessians
1_((1, 2), (1, 2))
(nat*3, nat*3)
when driver is h
total Hessian for 1st modelchem, 1st & 2nd fragments in basis of 1st & 2nd fragments
2_((3,), (2, 3))
(nat*3, nat*3)
when driver is h
total Hessian for 2nd modelchem, 3rd fragment in basis of 2nd and 3rd fragments
…