Psi4
Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
psi::JK Class Referenceabstract

#include <jk.h>

Inheritance diagram for psi::JK:
psi::DFJK psi::DirectJK psi::DiskJK psi::GTFockJK psi::PKJK psi::CDJK

Public Member Functions

 JK (std::shared_ptr< BasisSet > primary)
 
virtual ~JK ()
 Destructor. More...
 
virtual bool C1 () const =0
 Do we need to backtransform to C1 under the hood? More...
 
void set_cutoff (double cutoff)
 
void set_memory (size_t memory)
 
void set_omp_nthread (int omp_nthread)
 
void set_print (int print)
 Print flag (defaults to 1) More...
 
void set_debug (int debug)
 Debug flag (defaults to 0) More...
 
void set_bench (int bench)
 Bench flag (defaults to 0) More...
 
void set_do_J (bool do_J)
 
void set_do_K (bool do_K)
 
void set_do_wK (bool do_wK)
 
void set_omega (double omega)
 
void initialize ()
 
void compute ()
 
void finalize ()
 
virtual SharedVector iaia (SharedMatrix Ci, SharedMatrix Ca)
 
std::vector< SharedMatrix > & C_left ()
 
std::vector< SharedMatrix > & C_right ()
 
const std::vector< SharedMatrix > & J () const
 
const std::vector< SharedMatrix > & K () const
 
const std::vector< SharedMatrix > & wK () const
 
const std::vector< SharedMatrix > & D () const
 
virtual void print_header () const =0
 

Static Public Member Functions

static std::shared_ptr< JKbuild_JK (std::shared_ptr< BasisSet > primary, std::shared_ptr< BasisSet > auxiliary, Options &options)
 
static std::shared_ptr< JKbuild_JK (std::shared_ptr< BasisSet > primary, std::shared_ptr< BasisSet > auxiliary, Options &options, std::string jk_type)
 

Protected Member Functions

void compute_D ()
 Build the pseudo-density D_, before compute_JK() More...
 
void USO2AO ()
 Transform current C_left_/C_right_/D_ to C_left_ao_/C_right_ao_/D_ao_, before compute_JK() More...
 
void AO2USO ()
 Transform finished J_ao_/K_ao_ to J_/K_, after compute_JK() More...
 
void allocate_JK ()
 Allocate J_/K_ should we be using SOs. More...
 
void common_init ()
 
virtual void preiterations ()=0
 Setup integrals, files, etc. More...
 
virtual void compute_JK ()=0
 Compute J/K for current C/D. More...
 
virtual void postiterations ()=0
 Delete integrals, files, etc. More...
 
size_t memory_overhead () const
 Memory (doubles) used to hold J/K/wK/C/D and ao versions, at current moment. More...
 

Protected Attributes

int print_
 Print flag, defaults to 1. More...
 
int debug_
 Debug flag, defaults to 0. More...
 
int bench_
 Bench flag, defaults to 0. More...
 
size_t memory_
 Memory available, in doubles, defaults to 256 MB (32 M doubles) More...
 
int omp_nthread_
 Number of OpenMP threads (defaults to 1 in no OpenMP, Process::environment.get_n_threads() otherwise) More...
 
double cutoff_
 Integral cutoff (defaults to 0.0) More...
 
std::vector< bool > input_symmetry_cast_map_
 Whether to all desymmetrization, for cases when it's already been performed elsewhere. More...
 
bool do_J_
 Do J matrices? Defaults to true. More...
 
bool do_K_
 Do K matrices? Defaults to true. More...
 
bool do_wK_
 Do wK matrices? Defaults to false. More...
 
double omega_
 Omega, defaults to 0.0. More...
 
bool lr_symmetric_
 Left-right symmetric? Determined in each call of compute() More...
 
std::vector< SharedMatrixC_left_
 Pseudo-occupied C matrices, left side. More...
 
std::vector< SharedMatrixC_right_
 Pseudo-occupied C matrices, right side. More...
 
std::vector< SharedMatrixD_
 Pseudo-density matrices $D_{ls}=C_{li}^{left}C_{si}^{right}$. More...
 
std::vector< SharedMatrixJ_
 J matrices: $J_{mn}=(mn|ls)C_{li}^{left}C_{si}^{right}$. More...
 
std::vector< SharedMatrixK_
 K matrices: $K_{mn}=(ml|ns)C_{li}^{left}C_{si}^{right}$. More...
 
std::vector< SharedMatrixwK_
 wK matrices: $K_{mn}(\omega)=(ml|\omega|ns)C_{li}^{left}C_{si}^{right}$ More...
 
std::shared_ptr< BasisSetprimary_
 Primary basis set. More...
 
SharedMatrix AO2USO_
 AO2USO transformation matrix. More...
 
std::vector< SharedMatrixC_left_ao_
 Pseudo-occupied C matrices, left side. More...
 
std::vector< SharedMatrixC_right_ao_
 Pseudo-occupied C matrices, right side. More...
 
std::vector< SharedMatrixD_ao_
 Pseudo-density matrices. More...
 
std::vector< SharedMatrixJ_ao_
 J matrices: J_mn = (mn|ls) C_li^left C_si^right. More...
 
std::vector< SharedMatrixK_ao_
 K matrices: K_mn = (ml|ns) C_li^left C_si^right. More...
 
std::vector< SharedMatrixwK_ao_
 wK matrices: wK_mn = (ml|w|ns) C_li^left C_si^right More...
 

Detailed Description

Class JK

Class to compute Generalized Fock-Matrix Contributions of the form:

J_mn = (mn|ls) C_li^left C_si^right K_mn = (ml|ns) C_li^left C_si^right wK_mn = (ml|w|ns) C_li^left C_si^right

These matrices appear prominently in Hartree-Fock, CIS, and CPHF theory. This class (and associated subclasses) attempt to provide a uniform framework for quickly obtaining these matrices using a variety of techniques.

This class is abstract, specific instances must be obtained by constructing an object corresponding to the desired algorithm's subclass of JK, e.g., DFJK or DirectJK.

This class is available for symmetric or nonsymmetric C (this refers to C^left = C^right or not). Symmetric or nonsymmetric behavior is obtained by using the JKAlgorithm(C,basis) or JKAlgorithm(C,C,basis) constructors, respectively. Note that nonsymmetric can be up to 2x slower than symmetric for certain algorithms.

This class is designed to perform efficiently for any number of C^left/C^right combinations. The constructor takes a std::vector of C^left/C^right, which can be used to provide spin-specialization in SCF, arbitrary numbers of trial vectors in CIS, arbitrary numbers of perturbations in CPHF, etc. The number of C^left/C^right pairs may change from iteration to iteration, and the second dimension (typically noccpi) may change from pair to pair or iteration to iteration.

Tasking for J/K/wK is controlled by JK::set_do_J(), JK::set_do_K(), and JK::set_do_wK() knobs. By default, J and K matrices are built, wK matrices are not built. omega is set using the JK::set_omega() knob. set_omega() may be called between iterations, set_do_X() must be called before init().

Spatial symmetry is supported, though most of the algorithms backtransform to C1 for better sieving/scaling properties. The results are available after each call to JK::compute() in the methods JK::J(), JK::K(), JK::wK() and JK::D(), and will have the same size and symmetry structure as the forcing C^left/C^right vectors. J(), K(), wK(), and D() all return in the USO basis.

OpenMP and parallel BLAS/LAPACK threading are targeted where possible.

The typical calling convention for a JK instance is:

* // Constructor, Algorithm corresponds
* // to Type
* std::shared_ptr<JKType> jk(new JKType(
* basis, ...));
*
* // Set any desired knobs
*
* // 8 GB Memory, 1 G doubles
* jk->set_memory(1000000000L);
* // Cutoff of 1.0E-12
* jk->set_cutoff(1.0E-12);
* // Do J/K, Not wK (superfluous)
* jk->set_do_J(true);
* jk->set_do_K(true);
* jk->set_do_wK(false);
* ...
*
* // Initialize calls your derived class's preiterations member
* jk->initialize();
*
* // Enter iterations or whatever
* // In each iteration:
*
* // Clear and pack the C_left/C_right arrays
* // If C_left == C_right, only pack C_left
* // Make sure to declare your handles as references (&)
* std::vector<SharedMatrix>& C_left = jk->C_left();
* C_left.clear()
* C_left.push_back(Cocc)
* ...
*
* // Let jk compute for the given C_left/C_right
* jk->compute();
*
* // In return for the flexibility I give you with
* // C_left/C_right, I ask that you renew your reference
* // to the results J/K/D here. I only malloc where needed,
* // but if anything at all happens to C_left/C_right, last
* // iteration's SharedMatrix values might not
* // be valid. The std::vector<boost::shard_ptr<Matrix> >
* // for J/K/D will still be valid, but the pointers in the
* // entries may change.
*
* SharedMatrix Jnew = jk->J()[0];
* SharedMatrix Knew = jk->K()[0];
*
* // After iterations:
*
* // Finalize (frees most memory, including C/D/J/K
* // pointers you are no longer holding)
* jk->finalize();
*

If you're like me and are trying to implement a new flavor of JK object, you probably want to know what sorts of things it needs to do and what hooks are At least within the confines of the HF code, the JK object works off of a modified visitor pattern. The derived wavefunction class, HF, contains a pointer to an instance of a JK object. At certain hooks (vide infra) throughout the SCF the boilerplate HF code calls the overloaded functions of the JK object. These are your chances to interact with the HF code.

1) During HF::integrals the JK instance is built by calling JK::build_JK, which is a static factory function. This is your chance to set up your derived JK as you want it, via its constructor.

2) Also within HF::integrals, JK::initialize is called, which is a wrapper to an abstract function preiterations(). Best I can tell this a second chance to setup your derived JK object.

3) The last thing HF::integrals does is call JK::print_header, which is an abstract function that your derived class is supposed to implement so that it, you guessed it, prints a header.

4) Now the SCF proceeds until HF::FormG() (an abstract function) is called. Because this function is implemented differently for each flavor of SCF, there is the possibility that different calls are made to your instance; however, all the calls seem to follow the same ordering:

4a) A call to JK::C_left, which allows the SCF code to set the MO coefficients

4b) A call to JK::compute() which: 4b1) Ensures you have both a C_left and C_right 4b2) Ensures you have a density 4b3) Allocates memory in J_ and K_ 4b4) Calls compute_JK(), which is the next hook and is where you build J and K. The resulting J and K are to be placed in the J_ and K_ members. 4c) The SCF routine then grabs the J and K via getters to the base JK 5) At this point the SCF decides if it's looping, which if it does return to point 4, otherwise...

6) You're off the hook! Do your cleanup in your destructor

General notes:

Your derived class is not responsible for memory associated with the density, MO coefficients, J, or K. These things are allocated by the base class into shared pointers and will be autodestroyed when the pointers go out of scope

Constructor & Destructor Documentation

psi::JK::JK ( std::shared_ptr< BasisSet primary)

Wrapper to common_init(), see that reference

Parameters
primaryprimary basis set for this system. AO2USO transforms will be built with the molecule contained in this basis object, so the incoming C matrices must have the same spatial symmetry structure as this molecule
psi::JK::~JK ( )
virtual

Destructor.

Member Function Documentation

void psi::JK::allocate_JK ( )
protected

Allocate J_/K_ should we be using SOs.

void psi::JK::AO2USO ( )
protected

Transform finished J_ao_/K_ao_ to J_/K_, after compute_JK()

std::shared_ptr< JK > psi::JK::build_JK ( std::shared_ptr< BasisSet primary,
std::shared_ptr< BasisSet auxiliary,
Options options 
)
static

Static instance constructor, used to get prebuilt DFJK/DirectJK objects using knobs in options. Nmat and sym are options for GTFock sym means that all density matrices will be symmetric

Returns
abstract JK object, tuned in with preset options
std::shared_ptr< JK > psi::JK::build_JK ( std::shared_ptr< BasisSet primary,
std::shared_ptr< BasisSet auxiliary,
Options options,
std::string  jk_type 
)
static
virtual bool psi::JK::C1 ( ) const
pure virtual

Do we need to backtransform to C1 under the hood?

Implemented in psi::DFJK, psi::GTFockJK, psi::DirectJK, psi::PKJK, and psi::DiskJK.

std::vector<SharedMatrix >& psi::JK::C_left ( )
inline

Reference to C_left queue. It is YOUR job to allocate and fill this object out

std::vector<SharedMatrix >& psi::JK::C_right ( )
inline

Reference to C_right queue. It is YOUR job to allocate and fill this object out. Only fill C_left if symmetric.

void psi::JK::common_init ( void  )
protected

Function that sets a number of flags and allocates memory and sets up AO2USO.

Important note: no other memory is allocated here. That needs to be done in your derived class' constructor!!!!

Warning: this function is currently shadowed in at least one derived class, use with care!!!!!

void psi::JK::compute ( )

Compute D/J/K for the current C Update values in your reference to C_left/C_right BEFORE calling this, renew your references to the matrices in D/J/K AFTER calling this.

void psi::JK::compute_D ( )
protected

Build the pseudo-density D_, before compute_JK()

Make sure the memory is there

virtual void psi::JK::compute_JK ( )
protectedpure virtual

Compute J/K for current C/D.

Implemented in psi::DFJK, psi::GTFockJK, psi::DirectJK, psi::PKJK, and psi::DiskJK.

const std::vector<SharedMatrix >& psi::JK::D ( ) const
inline

Reference to D results. The reference to the std::vector<SharedMatrix > is valid throughout the life of the object. However, the entries (actual SharedMatrix pointers) may be changed in each call of compute();

Returns
D vector of D matrices
void psi::JK::finalize ( )

Method to clear off memory without totally destroying the object. The object can be rebuilt later by calling initialize()

SharedVector psi::JK::iaia ( SharedMatrix  Ci,
SharedMatrix  Ca 
)
virtual

Virtual method to provide (ia|ia) integrals for SO-basis C_mi and C_na matrices in O(N^4) or less Only available in DF-type JK integrals Throws by default

Reimplemented in psi::DFJK.

void psi::JK::initialize ( )

Initialize the integral technology. MUST be called AFTER setting knobs but BEFORE first call of compute()

const std::vector<SharedMatrix >& psi::JK::J ( ) const
inline

Reference to J results. The reference to the std::vector<SharedMatrix > is valid throughout the life of the object. However, the entries (actual SharedMatrix pointers) may be changed in each call of compute();

Returns
J vector of J matrices
const std::vector<SharedMatrix >& psi::JK::K ( ) const
inline

Reference to K results. The reference to the std::vector<SharedMatrix > is valid throughout the life of the object. However, the entries (actual SharedMatrix pointers) may be changed in each call of compute();

Returns
K vector of K matrices
size_t psi::JK::memory_overhead ( ) const
protected

Memory (doubles) used to hold J/K/wK/C/D and ao versions, at current moment.

virtual void psi::JK::postiterations ( )
protectedpure virtual

Delete integrals, files, etc.

Implemented in psi::DFJK, psi::GTFockJK, psi::DirectJK, psi::PKJK, and psi::DiskJK.

virtual void psi::JK::preiterations ( )
protectedpure virtual

Setup integrals, files, etc.

Implemented in psi::DFJK, psi::GTFockJK, psi::DirectJK, psi::PKJK, and psi::DiskJK.

virtual void psi::JK::print_header ( ) const
pure virtual

Print header information regarding JK type on output file

Implemented in psi::CDJK, psi::DFJK, psi::GTFockJK, psi::DirectJK, psi::PKJK, and psi::DiskJK.

void psi::JK::set_bench ( int  bench)
inline

Bench flag (defaults to 0)

void psi::JK::set_cutoff ( double  cutoff)
inline

Cutoff for individual contributions to the J/K matrices Eventually we hope to use Schwarz/MBIE/Density cutoffs, for now just Schwarz

Parameters
cutoffceiling of magnitude of elements to be ignored if possible
void psi::JK::set_debug ( int  debug)
inline

Debug flag (defaults to 0)

void psi::JK::set_do_J ( bool  do_J)
inline

Set to do J tasks

Parameters
do_Jdo J matrices or not, defaults to true
void psi::JK::set_do_K ( bool  do_K)
inline

Set to do K tasks

Parameters
do_Kdo K matrices or not, defaults to true
void psi::JK::set_do_wK ( bool  do_wK)
inline

Set to do wK tasks

Parameters
do_wKdo wK matrices or not, defaults to false
void psi::JK::set_memory ( size_t  memory)
inline

Maximum memory to use, in doubles (for tensor-based methods, integral generation objects typically ignore this)

Parameters
memorymaximum number of doubles to allocate
void psi::JK::set_omega ( double  omega)
inline

Set the omega value for wK

Parameters
omegarange-separation parameter
void psi::JK::set_omp_nthread ( int  omp_nthread)
inline

Maximum number of OpenMP threads to use. It may be necessary to clamp this to some value smaller than the total number of cores for machines with a high core-to-memory ratio to avoid running out of memory due to integral generation objects

Parameters
omp_nthreadMaximum number of threads to use in integral generation objects (BLAS/LAPACK can still run with their original maximum number)
void psi::JK::set_print ( int  print)
inline

Print flag (defaults to 1)

void psi::JK::USO2AO ( )
protected

Transform current C_left_/C_right_/D_ to C_left_ao_/C_right_ao_/D_ao_, before compute_JK()

const std::vector<SharedMatrix >& psi::JK::wK ( ) const
inline

Reference to wK results. The reference to the std::vector<SharedMatrix > is valid throughout the life of the object. However, the entries (actual SharedMatrix pointers) may be changed in each call of compute();

Returns
wK vector of wK matrices

Member Data Documentation

SharedMatrix psi::JK::AO2USO_
protected

AO2USO transformation matrix.

int psi::JK::bench_
protected

Bench flag, defaults to 0.

std::vector<SharedMatrix> psi::JK::C_left_
protected

Pseudo-occupied C matrices, left side.

std::vector<SharedMatrix> psi::JK::C_left_ao_
protected

Pseudo-occupied C matrices, left side.

std::vector<SharedMatrix> psi::JK::C_right_
protected

Pseudo-occupied C matrices, right side.

std::vector<SharedMatrix> psi::JK::C_right_ao_
protected

Pseudo-occupied C matrices, right side.

double psi::JK::cutoff_
protected

Integral cutoff (defaults to 0.0)

std::vector<SharedMatrix> psi::JK::D_
protected

Pseudo-density matrices $D_{ls}=C_{li}^{left}C_{si}^{right}$.

std::vector<SharedMatrix> psi::JK::D_ao_
protected

Pseudo-density matrices.

int psi::JK::debug_
protected

Debug flag, defaults to 0.

bool psi::JK::do_J_
protected

Do J matrices? Defaults to true.

bool psi::JK::do_K_
protected

Do K matrices? Defaults to true.

bool psi::JK::do_wK_
protected

Do wK matrices? Defaults to false.

std::vector<bool> psi::JK::input_symmetry_cast_map_
protected

Whether to all desymmetrization, for cases when it's already been performed elsewhere.

std::vector<SharedMatrix> psi::JK::J_
protected

J matrices: $J_{mn}=(mn|ls)C_{li}^{left}C_{si}^{right}$.

std::vector<SharedMatrix> psi::JK::J_ao_
protected

J matrices: J_mn = (mn|ls) C_li^left C_si^right.

std::vector<SharedMatrix> psi::JK::K_
protected

K matrices: $K_{mn}=(ml|ns)C_{li}^{left}C_{si}^{right}$.

std::vector<SharedMatrix> psi::JK::K_ao_
protected

K matrices: K_mn = (ml|ns) C_li^left C_si^right.

bool psi::JK::lr_symmetric_
protected

Left-right symmetric? Determined in each call of compute()

size_t psi::JK::memory_
protected

Memory available, in doubles, defaults to 256 MB (32 M doubles)

double psi::JK::omega_
protected

Omega, defaults to 0.0.

int psi::JK::omp_nthread_
protected

Number of OpenMP threads (defaults to 1 in no OpenMP, Process::environment.get_n_threads() otherwise)

std::shared_ptr<BasisSet> psi::JK::primary_
protected

Primary basis set.

int psi::JK::print_
protected

Print flag, defaults to 1.

std::vector<SharedMatrix> psi::JK::wK_
protected

wK matrices: $K_{mn}(\omega)=(ml|\omega|ns)C_{li}^{left}C_{si}^{right}$

std::vector<SharedMatrix> psi::JK::wK_ao_
protected

wK matrices: wK_mn = (ml|w|ns) C_li^left C_si^right


The documentation for this class was generated from the following files: