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.

  • bsse_type (str or list) –

    '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 specifying return_total_data = True may carry out more computations than return_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'} || etc

    Dictionary 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 than return_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 obtain nbodies, 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 of nbodies _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

compute(client=None)[source]

Run quantum chemistry.

Parameters

client (Optional[FractalClient]) –

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

  …